2002-09-05 nalin first pass at writing documentation fix

2002-09-05 nalin
	* docs/reference: first pass at writing documentation
	* src/termcap.c: fix how'd-that-ever-work in vte_termcap_strip(), patch
	from Brian Cameron.  Take \\e as an alias for \\E, which is already
	an alias for Escape.
	* src/vte.c(vte_terminal_get_cursor): Return an absolute cursor position
	instead of a relative position.

ChangeLog

+2002-09-05 nalin
+	* docs/reference: first pass at writing documentation
+	* src/termcap.c: fix how'd-that-ever-work in vte_termcap_strip(), patch
+	from Brian Cameron.  Take \\e as an alias for \\E, which is already
+	an alias for Escape.
+	* src/vte.c(vte_terminal_get_cursor): Return an absolute cursor position
+	instead of a relative position.
+
 2002-09-04  jacob berkman  <jacob@ximian.com>
 
 	* src/vte.c (vte_default_substitute): only compile the FC_HINT_STYLE

Makefile.am

-SUBDIRS = src python termcaps po
+SUBDIRS = src python termcaps po doc
 EXTRA_DIST = HACKING vte.spec vte.pc.in
 
 pkgconfigdir = $(libdir)/pkgconfig

configure.in

@@ -112,6 +112,57 @@ AC_DEFINE_UNQUOTED(LOCALEDIR,"$mydatadir/locale",
 GETTEXT_PACKAGE=vte
 AC_SUBST(GETTEXT_PACKAGE)
 
+################################################################################
+
+# This is a check for gtk-doc which you can insert into your configure.in.
+# You shouldn't need to change it at all.
+
+##################################################
+# Check for gtk-doc.
+##################################################
+
+AC_ARG_WITH(html-dir, [  --with-html-dir=PATH path to installed docs ])
+
+if test "x$with_html_dir" = "x" ; then
+  HTML_DIR='${datadir}/gtk-doc/html'
+else
+  HTML_DIR=$with_html_dir
+fi
+
+AC_SUBST(HTML_DIR)
+
+AC_CHECK_PROG(GTKDOC, gtkdoc-mkdb, true, false)
+
+gtk_doc_min_version=0.6
+if $GTKDOC ; then 
+    gtk_doc_version=`gtkdoc-mkdb --version`
+    AC_MSG_CHECKING([gtk-doc version ($gtk_doc_version) >= $gtk_doc_min_version])
+    if perl <<EOF ; then
+      exit (("$gtk_doc_version" =~ /^[[0-9]]+\.[[0-9]]+$/) &&
+            ("$gtk_doc_version" >= "$gtk_doc_min_version") ? 0 : 1);
+EOF
+      AC_MSG_RESULT(yes)
+   else
+      AC_MSG_RESULT(no)
+      GTKDOC=false
+   fi
+fi
+
+dnl Let people disable the gtk-doc stuff.
+AC_ARG_ENABLE(gtk-doc, [  --enable-gtk-doc  Use gtk-doc to build documentation [default=auto]], enable_gtk_doc="$enableval", enable_gtk_doc=auto)
+
+if test x$enable_gtk_doc = xauto ; then
+  if test x$GTKDOC = xtrue ; then
+    enable_gtk_doc=yes
+  else
+    enable_gtk_doc=no 
+  fi
+fi
+
+AM_CONDITIONAL(ENABLE_GTK_DOC, test x$enable_gtk_doc = xyes)
+
+################################################################################
+
 AM_CONFIG_HEADER(config.h)
 AC_OUTPUT([
 Makefile
@@ -119,5 +170,7 @@ src/Makefile
 termcaps/Makefile
 python/Makefile
 po/Makefile.in
+doc/Makefile
+doc/reference/Makefile
 vte.pc
 ])

doc/Makefile.am

+SUBDIRS = reference

doc/reference/Makefile.am

+## Process this file with automake to produce Makefile.in
+
+# This is a blank Makefile.am for using gtk-doc.
+# Copy this to your project's API docs directory and modify the variables to
+# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples
+# of using the various options.
+
+# The name of the module, e.g. 'glib'.
+DOC_MODULE=vte
+
+# The top-level SGML file. Change it if you want.
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
+
+# The directory containing the source code. Relative to $(srcdir).
+# gtk-doc will search all .c & .h files beneath here for inline comments
+# documenting functions and macros.
+DOC_SOURCE_DIR=../../src
+
+# Extra options to pass to gtkdoc-scanobj or gtkdoc-scangobj.
+SCANOBJ_OPTIONS=
+
+# Extra options to supply to gtkdoc-scan.
+SCAN_OPTIONS=
+
+# Extra options to supply to gtkdoc-mkdb.
+MKDB_OPTIONS=
+
+# Extra options to supply to gtkdoc-fixref.
+FIXXREF_OPTIONS=
+
+# Used for dependencies.
+HFILE_GLOB=
+CFILE_GLOB=
+
+# Header files to ignore when scanning.
+IGNORE_HFILES=
+
+# Images to copy into HTML directory.
+HTML_IMAGES =
+
+# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
+content_files =
+
+# Other files to distribute.
+extra_files =
+
+# CFLAGS and LDFLAGS for compiling scan program. Only needed if your app/lib
+# contains GtkObjects/GObjects and you want to document signals and properties.
+GTKDOC_CFLAGS = @GTK_CFLAGS@
+GTKDOC_LIBS = @GTK_LIBS@ ../../src/libvte.la
+
+GTKDOC_CC=$(LIBTOOL) --mode=compile $(CC)
+GTKDOC_LD=$(LIBTOOL) --mode=link $(CC)
+
+# If you need to override some of the declarations, place them in the
+# $(DOC_MODULE)-overrides.txt file and uncomment the second line here.
+DOC_OVERRIDES =
+#DOC_OVERRIDES = $(DOC_MODULE)-overrides.txt
+
+
+
+###########################################################################
+# Everything below here is generic and you shouldn't need to change it.
+###########################################################################
+
+TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE)
+
+EXTRA_DIST = 				\
+	$(content_files)		\
+	$(extra_files)			\
+	$(HTML_IMAGES)			\
+	$(DOC_MAIN_SGML_FILE)		\
+	$(DOC_MODULE).types		\
+	$(DOC_MODULE)-sections.txt	\
+	$(DOC_OVERRIDES)
+
+DOC_STAMPS=scan-build.stamp tmpl-build.stamp sgml-build.stamp html-build.stamp \
+	   $(srcdir)/tmpl.stamp $(srcdir)/sgml.stamp $(srcdir)/html.stamp
+
+SCANOBJ_FILES = 		\
+	$(DOC_MODULE).args 	\
+	$(DOC_MODULE).hierarchy \
+	$(DOC_MODULE).signals
+
+if ENABLE_GTK_DOC
+all-local: html-build.stamp
+
+#### scan ####
+
+scan-build.stamp: $(HFILE_GLOB)
+	@echo '*** Scanning header files ***'
+	if grep -l '^..*$$' $(srcdir)/$(DOC_MODULE).types > /dev/null ; then \
+	    CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" CFLAGS="$(GTKDOC_CFLAGS)" LDFLAGS="$(GTKDOC_LIBS)" gtkdoc-scangobj $(SCANOBJ_OPTIONS) --module=$(DOC_MODULE) --output-dir=$(srcdir) ; \
+	else \
+	    cd $(srcdir) ; \
+	    for i in $(SCANOBJ_FILES) ; do \
+               test -f $$i || touch $$i ; \
+	    done \
+	fi
+	cd $(srcdir) && \
+	  gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --ignore-headers="$(IGNORE_HFILES)" $(SCAN_OPTIONS) $(EXTRA_HFILES)
+	touch scan-build.stamp
+
+$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES): scan-build.stamp
+	@true
+
+#### templates ####
+
+tmpl-build.stamp: $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_OVERRIDES)
+	@echo '*** Rebuilding template files ***'
+	cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE)
+	touch tmpl-build.stamp
+
+tmpl.stamp: tmpl-build.stamp
+	@true
+
+#### sgml ####
+
+sgml-build.stamp: tmpl.stamp $(CFILE_GLOB) $(srcdir)/tmpl/*.sgml
+	@echo '*** Building SGML ***'
+	cd $(srcdir) && \
+	gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --main-sgml-file=$(DOC_MAIN_SGML_FILE) $(MKDB_OPTIONS)
+	touch sgml-build.stamp
+
+sgml.stamp: sgml-build.stamp
+	@true
+
+#### html ####
+
+html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files)
+	@echo '*** Building HTML ***'
+	test -d $(srcdir)/html || mkdir $(srcdir)/html
+	cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
+	test "x$(HTML_IMAGES)" = "x" || ( cd $(srcdir) && cp $(HTML_IMAGES) html )
+	@echo '-- Fixing Crossreferences' 
+	cd $(srcdir) && gtkdoc-fixxref --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)
+	touch html-build.stamp
+endif
+
+##############
+
+clean-local:
+	rm -f *~ *.bak $(SCANOBJ_FILES) *-unused.txt $(DOC_STAMPS)
+
+maintainer-clean-local: clean
+	cd $(srcdir) && rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt
+
+install-data-local:
+	$(mkinstalldirs) $(DESTDIR)$(TARGET_DIR)
+	(installfiles=`echo $(srcdir)/html/*.html`; \
+	if test "$$installfiles" = '$(srcdir)/html/*.html'; \
+	then echo '-- Nothing to install' ; \
+	else \
+	  for i in $$installfiles; do \
+	    echo '-- Installing '$$i ; \
+	    $(INSTALL_DATA) $$i $(DESTDIR)$(TARGET_DIR); \
+	  done; \
+	  echo '-- Installing $(srcdir)/html/index.sgml' ; \
+	  $(INSTALL_DATA) $(srcdir)/html/index.sgml $(DESTDIR)$(TARGET_DIR); \
+	fi)
+
+#
+# Require gtk-doc when making dist
+#
+if ENABLE_GTK_DOC
+dist-check-gtkdoc:
+else
+dist-check-gtkdoc:
+	@echo "*** gtk-doc must be installed and enabled in order to make dist"
+	@false
+endif
+
+dist-hook: dist-check-gtkdoc dist-hook-local
+	mkdir $(distdir)/tmpl
+	mkdir $(distdir)/sgml
+	mkdir $(distdir)/html
+	-cp $(srcdir)/tmpl/*.sgml $(distdir)/tmpl
+	-cp $(srcdir)/sgml/*.sgml $(distdir)/sgml
+	-cp $(srcdir)/html/index.sgml $(distdir)/html
+	-cp $(srcdir)/html/*.html $(srcdir)/html/*.css $(distdir)/html
+
+	images=$(HTML_IMAGES) ;    	      \
+	for i in $$images ; do		      \
+	  cp $(srcdir)/$$i $(distdir)/html ;  \
+	done
+
+.PHONY : dist-hook-local

doc/reference/tmpl/caps.sgml

+<!-- ##### SECTION Title ##### -->
+caps
+
+<!-- ##### SECTION Short_Description ##### -->
+Global structures which contain terminal capability names and Xterm control
+sequence definitions.
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### MACRO VTE_CAP_ESC ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### MACRO VTE_CAP_CSI ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### MACRO VTE_CAP_ST ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### MACRO VTE_CAP_OSC ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### MACRO VTE_CAP_PM ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### MACRO VTE_CAP_APC ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### FUNCTION vte_capability_init ##### -->
+<para>
+
+</para>
+
+
+

doc/reference/tmpl/debug.sgml

+<!-- ##### SECTION Title ##### -->
+debug
+
+<!-- ##### SECTION Short_Description ##### -->
+Facilities for enabling debugging message output from libvte.
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+Functions in libvte will only output debugging information if the library was
+configured with --enable-maintainer-mode.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### ENUM VteDebugFlags ##### -->
+<para>
+
+</para>
+
+@VTE_DEBUG_MISC: 
+@VTE_DEBUG_PARSE: 
+@VTE_DEBUG_IO: 
+@VTE_DEBUG_UPDATES: 
+@VTE_DEBUG_EVENTS: 
+@VTE_DEBUG_SIGNALS: 
+@VTE_DEBUG_SELECTION: 
+@VTE_DEBUG_SUBSTITUTION: 
+@VTE_DEBUG_RING: 
+@VTE_DEBUG_PTY: 
+
+<!-- ##### FUNCTION vte_debug_parse_string ##### -->
+<para>
+
+</para>
+
+@string: 
+
+
+<!-- ##### FUNCTION vte_debug_on ##### -->
+<para>
+
+</para>
+
+@flags: 
+@Returns: 
+
+

doc/reference/tmpl/iso2022.sgml

+<!-- ##### SECTION Title ##### -->
+iso2022
+
+<!-- ##### SECTION Short_Description ##### -->
+A state machine for converting #gunichar strings with embedded ISO-2022 control
+sequences into plain #gunichar strings.
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### FUNCTION vte_iso2022_free ##### -->
+<para>
+
+</para>
+
+@p: 
+
+
+<!-- ##### FUNCTION vte_iso2022_substitute ##### -->
+<para>
+
+</para>
+
+@state: 
+@instring: 
+@length: 
+@outstring: 
+@specials: 
+@Returns: 
+
+

doc/reference/tmpl/marshal.sgml

+<!-- ##### SECTION Title ##### -->
+marshal
+
+<!-- ##### SECTION Short_Description ##### -->
+Signal marshalers.
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+

doc/reference/tmpl/pty.sgml

+<!-- ##### SECTION Title ##### -->
+pty
+
+<!-- ##### SECTION Short_Description ##### -->
+Functions for starting a new process on a new pseudo-terminal and for
+manipulating psuedo-terminals.
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+The terminal widget uses these functions to start commands with new controlling
+pseudo-terminals and to resize psuedo-terminals.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### FUNCTION vte_pty_open ##### -->
+<para>
+
+</para>
+
+@child: 
+@env_add: 
+@command: 
+@argv: 
+@columns: 
+@rows: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_pty_get_size ##### -->
+<para>
+
+</para>
+
+@master: 
+@columns: 
+@rows: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_pty_set_size ##### -->
+<para>
+
+</para>
+
+@master: 
+@columns: 
+@rows: 
+@Returns: 
+
+

doc/reference/tmpl/reaper.sgml

+<!-- ##### SECTION Title ##### -->
+VteReaper
+
+<!-- ##### SECTION Short_Description ##### -->
+A singleton object which catches %SIGCHLD signals and converts them into
+GObject-style &quot;child-exited&quot; signals.
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+Because an application may need to be notified when child processes
+exit, and because there is only one %SIGCHLD handler, the #VteTerminal
+widget relies on a #VteReaper to watch for %SIGCHLD notifications and
+retrieve the exit status of child processes which have exited.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### STRUCT VteReaper ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION vte_reaper_get ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### SIGNAL VteReaper::child-exited ##### -->
+<para>
+
+</para>
+
+@vtereaper: the object which received the signal.
+@arg1: the process ID of the exited child.
+@arg2: the status of the exited child, as returned by #waitpid.
+

doc/reference/tmpl/ring.sgml

+<!-- ##### SECTION Title ##### -->
+ring
+
+<!-- ##### SECTION Short_Description ##### -->
+
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### STRUCT VteRing ##### -->
+<para>
+
+</para>
+
+@free: 
+@user_data: 
+@array: 
+@delta: 
+@length: 
+@max: 
+
+<!-- ##### USER_FUNCTION VteRingFreeFunc ##### -->
+<para>
+
+</para>
+
+@freeing: 
+@data: 
+
+
+<!-- ##### MACRO vte_ring_index ##### -->
+<para>
+
+</para>
+
+@__ring: 
+@__cast: 
+@__position: 
+
+
+<!-- ##### FUNCTION vte_ring_new ##### -->
+<para>
+
+</para>
+
+@max_elements: 
+@free: 
+@data: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_ring_insert ##### -->
+<para>
+
+</para>
+
+@ring: 
+@position: 
+@data: 
+
+
+<!-- ##### FUNCTION vte_ring_remove ##### -->
+<para>
+
+</para>
+
+@ring: 
+@position: 
+@free_element: 
+
+
+<!-- ##### FUNCTION vte_ring_at ##### -->
+<para>
+
+</para>
+
+@ring: 
+@Param2: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_ring_append ##### -->
+<para>
+
+</para>