2002-09-05 nalin first pass at writing documentation fix
authorNalin Dahyabhai <nalin@src.gnome.org>
Thu, 5 Sep 2002 05:42:13 +0000 (05:42 +0000)
committerNalin Dahyabhai <nalin@src.gnome.org>
Thu, 5 Sep 2002 05:42:13 +0000 (05:42 +0000)
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.

36 files changed:
ChangeLog
Makefile.am
configure.in
doc/Makefile.am [new file with mode: 0644]
doc/reference/Makefile.am [new file with mode: 0644]
doc/reference/tmpl/caps.sgml [new file with mode: 0644]
doc/reference/tmpl/debug.sgml [new file with mode: 0644]
doc/reference/tmpl/iso2022.sgml [new file with mode: 0644]
doc/reference/tmpl/marshal.sgml [new file with mode: 0644]
doc/reference/tmpl/pty.sgml [new file with mode: 0644]
doc/reference/tmpl/reaper.sgml [new file with mode: 0644]
doc/reference/tmpl/ring.sgml [new file with mode: 0644]
doc/reference/tmpl/table.sgml [new file with mode: 0644]
doc/reference/tmpl/termcap.sgml [new file with mode: 0644]
doc/reference/tmpl/trie.sgml [new file with mode: 0644]
doc/reference/tmpl/vte-unused.sgml [new file with mode: 0644]
doc/reference/tmpl/vte.sgml [new file with mode: 0644]
doc/reference/tmpl/vteaccess.sgml [new file with mode: 0644]
doc/reference/vte-docs.sgml [new file with mode: 0644]
doc/reference/vte-sections.txt [new file with mode: 0644]
doc/reference/vte.types [new file with mode: 0644]
src/caps.c
src/caps.h
src/debug.h
src/iso2022.h
src/pty.c
src/reaper.c
src/ring.c
src/ring.h
src/table.c
src/termcap.c
src/trie.c
src/vte.c
src/vte.h
src/vteaccess.c
src/vteaccess.h

index 4b41341..567380c 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+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
index 4026235..d1e4de2 100644 (file)
@@ -1,4 +1,4 @@
-SUBDIRS = src python termcaps po
+SUBDIRS = src python termcaps po doc
 EXTRA_DIST = HACKING vte.spec vte.pc.in
 
 pkgconfigdir = $(libdir)/pkgconfig
index 538a99a..7473dbe 100644 (file)
@@ -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
 ])
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644 (file)
index 0000000..f3ddc22
--- /dev/null
@@ -0,0 +1 @@
+SUBDIRS = reference
diff --git a/doc/reference/Makefile.am b/doc/reference/Makefile.am
new file mode 100644 (file)
index 0000000..5106729
--- /dev/null
@@ -0,0 +1,187 @@
+## 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
diff --git a/doc/reference/tmpl/caps.sgml b/doc/reference/tmpl/caps.sgml
new file mode 100644 (file)
index 0000000..7afcd94
--- /dev/null
@@ -0,0 +1,66 @@
+<!-- ##### 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>
+
+
+
diff --git a/doc/reference/tmpl/debug.sgml b/doc/reference/tmpl/debug.sgml
new file mode 100644 (file)
index 0000000..ff48404
--- /dev/null
@@ -0,0 +1,50 @@
+<!-- ##### 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: 
+
+
diff --git a/doc/reference/tmpl/iso2022.sgml b/doc/reference/tmpl/iso2022.sgml
new file mode 100644 (file)
index 0000000..2717a8c
--- /dev/null
@@ -0,0 +1,38 @@
+<!-- ##### 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: 
+
+
diff --git a/doc/reference/tmpl/marshal.sgml b/doc/reference/tmpl/marshal.sgml
new file mode 100644 (file)
index 0000000..e2ce994
--- /dev/null
@@ -0,0 +1,16 @@
+<!-- ##### SECTION Title ##### -->
+marshal
+
+<!-- ##### SECTION Short_Description ##### -->
+Signal marshalers.
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
diff --git a/doc/reference/tmpl/pty.sgml b/doc/reference/tmpl/pty.sgml
new file mode 100644 (file)
index 0000000..554308a
--- /dev/null
@@ -0,0 +1,54 @@
+<!-- ##### 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: 
+
+
diff --git a/doc/reference/tmpl/reaper.sgml b/doc/reference/tmpl/reaper.sgml
new file mode 100644 (file)
index 0000000..d950326
--- /dev/null
@@ -0,0 +1,43 @@
+<!-- ##### 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.
+
diff --git a/doc/reference/tmpl/ring.sgml b/doc/reference/tmpl/ring.sgml
new file mode 100644 (file)
index 0000000..bdd1399
--- /dev/null
@@ -0,0 +1,143 @@
+<!-- ##### 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>
+
+@ring: 
+@data: 
+
+
+<!-- ##### FUNCTION vte_ring_delta ##### -->
+<para>
+
+</para>
+
+@ring: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_ring_length ##### -->
+<para>
+
+</para>
+
+@ring: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_ring_next ##### -->
+<para>
+
+</para>
+
+@ring: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_ring_contains ##### -->
+<para>
+
+</para>
+
+@ring: 
+@Param2: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_ring_free ##### -->
+<para>
+
+</para>
+
+@ring: 
+@free_elements: 
+
+
diff --git a/doc/reference/tmpl/table.sgml b/doc/reference/tmpl/table.sgml
new file mode 100644 (file)
index 0000000..bd337b6
--- /dev/null
@@ -0,0 +1,77 @@
+<!-- ##### SECTION Title ##### -->
+table
+
+<!-- ##### SECTION Short_Description ##### -->
+The tree-of-tables sequence parser.
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+This control sequence parser uses a tree of tables, similar in design to that
+used by Xterm, but generated dynamically at run-time using data from the system
+termcap database.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### FUNCTION vte_table_free ##### -->
+<para>
+
+</para>
+
+@table: 
+
+
+<!-- ##### FUNCTION vte_table_add ##### -->
+<para>
+
+</para>
+
+@table: 
+@pattern: 
+@length: 
+@result: 
+@quark: 
+
+
+<!-- ##### FUNCTION vte_table_match ##### -->
+<para>
+
+</para>
+
+@table: 
+@pattern: 
+@length: 
+@res: 
+@consumed: 
+@quark: 
+@array: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_table_print ##### -->
+<para>
+
+</para>
+
+@table: 
+
+
+<!-- ##### FUNCTION vte_table_wide_encoding ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_table_narrow_encoding ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
diff --git a/doc/reference/tmpl/termcap.sgml b/doc/reference/tmpl/termcap.sgml
new file mode 100644 (file)
index 0000000..5f67d0f
--- /dev/null
@@ -0,0 +1,79 @@
+<!-- ##### SECTION Title ##### -->
+termcap
+
+<!-- ##### SECTION Short_Description ##### -->
+A set of functions for parsing the system termcap database.
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### FUNCTION vte_termcap_free ##### -->
+<para>
+
+</para>
+
+@termcap: 
+
+
+<!-- ##### FUNCTION vte_termcap_find_boolean ##### -->
+<para>
+
+</para>
+
+@termcap: 
+@tname: 
+@cap: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_termcap_find_numeric ##### -->
+<para>
+
+</para>
+
+@termcap: 
+@tname: 
+@cap: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_termcap_find_string ##### -->
+<para>
+
+</para>
+
+@termcap: 
+@tname: 
+@cap: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_termcap_find_string_length ##### -->
+<para>
+
+</para>
+
+@termcap: 
+@tname: 
+@cap: 
+@length: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_termcap_strip ##### -->
+<para>
+
+</para>
+
+@termcap: 
+@stripped: 
+@len: 
+
+
diff --git a/doc/reference/tmpl/trie.sgml b/doc/reference/tmpl/trie.sgml
new file mode 100644 (file)
index 0000000..0b81d3b
--- /dev/null
@@ -0,0 +1,76 @@
+<!-- ##### SECTION Title ##### -->
+trie
+
+<!-- ##### SECTION Short_Description ##### -->
+The trie sequence parser.
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+This control sequence parser uses a tree of nodes and attempts to find the
+control sequence which best matches a given chunk of data.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### FUNCTION vte_trie_free ##### -->
+<para>
+
+</para>
+
+@trie: 
+
+
+<!-- ##### FUNCTION vte_trie_add ##### -->
+<para>
+
+</para>
+
+@trie: 
+@pattern: 
+@length: 
+@result: 
+@quark: 
+
+
+<!-- ##### FUNCTION vte_trie_match ##### -->
+<para>
+
+</para>
+
+@trie: 
+@pattern: 
+@length: 
+@res: 
+@consumed: 
+@quark: 
+@array: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_trie_print ##### -->
+<para>
+
+</para>
+
+@trie: 
+
+
+<!-- ##### FUNCTION vte_trie_wide_encoding ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_trie_narrow_encoding ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
diff --git a/doc/reference/tmpl/vte-unused.sgml b/doc/reference/tmpl/vte-unused.sgml
new file mode 100644 (file)
index 0000000..c50cf24
--- /dev/null
@@ -0,0 +1,236 @@
+<!-- ##### SECTION ./tmpl/iso2022.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/iso2022.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/iso2022.sgml:Short_Description ##### -->
+A state machine for converting #gunichar strings with embedded ISO-2022 control
+sequences into plain #gunichar strings.
+
+
+<!-- ##### SECTION ./tmpl/iso2022.sgml:Title ##### -->
+iso2022
+
+
+<!-- ##### SECTION ./tmpl/marshal.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/marshal.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/marshal.sgml:Short_Description ##### -->
+Signal marshalers.
+
+
+<!-- ##### SECTION ./tmpl/marshal.sgml:Title ##### -->
+marshal
+
+
+<!-- ##### SECTION ./tmpl/table.sgml:Long_Description ##### -->
+<para>
+This control sequence parser uses a tree of tables, similar in design to that
+used by Xterm, but generated dynamically at run-time using data from the system
+termcap database.
+</para>
+
+
+<!-- ##### SECTION ./tmpl/table.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/table.sgml:Short_Description ##### -->
+The tree-of-tables sequence parser.
+
+
+<!-- ##### SECTION ./tmpl/table.sgml:Title ##### -->
+table
+
+
+<!-- ##### SECTION ./tmpl/trie.sgml:Long_Description ##### -->
+<para>
+This control sequence parser uses a tree of nodes and attempts to find the
+control sequence which best matches a given chunk of data.
+</para>
+
+
+<!-- ##### SECTION ./tmpl/trie.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/trie.sgml:Short_Description ##### -->
+The trie sequence parser.
+
+
+<!-- ##### SECTION ./tmpl/trie.sgml:Title ##### -->
+trie
+
+
+<!-- ##### MACRO VTE_IS_TERMINAL_ERASE_BINDING ##### -->
+<para>
+
+</para>
+
+@obj: 
+
+<!-- ##### MACRO VTE_TYPE_TERMINAL_ERASE_BINDING ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION vte_iso2022_free ##### -->
+<para>
+
+</para>
+
+@p: 
+
+<!-- ##### FUNCTION vte_iso2022_substitute ##### -->
+<para>
+
+</para>
+
+@state: 
+@instring: 
+@length: 
+@outstring: 
+@specials: 
+@Returns: 
+
+<!-- ##### FUNCTION vte_table_add ##### -->
+<para>
+
+</para>
+
+@table: 
+@pattern: 
+@length: 
+@result: 
+@quark: 
+
+<!-- ##### FUNCTION vte_table_free ##### -->
+<para>
+
+</para>
+
+@table: 
+
+<!-- ##### FUNCTION vte_table_match ##### -->
+<para>
+
+</para>
+
+@table: 
+@pattern: 
+@length: 
+@res: 
+@consumed: 
+@quark: 
+@array: 
+@Returns: 
+
+<!-- ##### FUNCTION vte_table_narrow_encoding ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+<!-- ##### FUNCTION vte_table_print ##### -->
+<para>
+
+</para>
+
+@table: 
+
+<!-- ##### FUNCTION vte_table_wide_encoding ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+<!-- ##### FUNCTION vte_termcap_new ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+<!-- ##### FUNCTION vte_terminal_erase_binding_get_type ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+<!-- ##### FUNCTION vte_trie_add ##### -->
+<para>
+
+</para>
+
+@trie: 
+@pattern: 
+@length: 
+@result: 
+@quark: 
+
+<!-- ##### FUNCTION vte_trie_free ##### -->
+<para>
+
+</para>
+
+@trie: 
+
+<!-- ##### FUNCTION vte_trie_match ##### -->
+<para>
+
+</para>
+
+@trie: 
+@pattern: 
+@length: 
+@res: 
+@consumed: 
+@quark: 
+@array: 
+@Returns: 
+
+<!-- ##### FUNCTION vte_trie_narrow_encoding ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+<!-- ##### FUNCTION vte_trie_print ##### -->
+<para>
+
+</para>
+
+@trie: 
+
+<!-- ##### FUNCTION vte_trie_wide_encoding ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
diff --git a/doc/reference/tmpl/vte.sgml b/doc/reference/tmpl/vte.sgml
new file mode 100644 (file)
index 0000000..b2e51e1
--- /dev/null
@@ -0,0 +1,683 @@
+<!-- ##### SECTION Title ##### -->
+VteTerminal
+
+<!-- ##### SECTION Short_Description ##### -->
+A terminal widget implementation.
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+A VteTerminal is a terminal emulator implemented as a GTK2 widget.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### STRUCT VteTerminalPrivate ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ENUM VteTerminalEraseBinding ##### -->
+<para>
+
+</para>
+
+@VTE_ERASE_AUTO: For backspace, attempt to determine the right value from the terminal's IO settings.  For delete, use the control sequence.
+@VTE_ERASE_ASCII_BACKSPACE: Send an ASCII backspace character (0x08).
+@VTE_ERASE_ASCII_DELETE: Send an ASCII delete character (0x7F).
+@VTE_ERASE_DELETE_SEQUENCE: Send the "@7" control sequence.
+
+<!-- ##### STRUCT VteTerminal ##### -->
+<para>
+
+</para>
+
+@widget: 
+@adjustment: Scroll bar adjustments.
+@char_width: Width of a narrow character cell.
+@char_height: Height of a character cell.
+@char_ascent: 
+@char_descent: 
+@row_count: Number of visible rows.
+@column_count: Number of visible columns.
+@window_title: The terminal's idea of what the window's title should be.
+@icon_title: The terminal's idea of what the window's title should be when iconified.
+
+<!-- ##### FUNCTION vte_terminal_new ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_terminal_im_append_menuitems ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@menushell: 
+
+
+<!-- ##### FUNCTION vte_terminal_fork_command ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@command: 
+@argv: 
+@envv: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_terminal_feed ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@data: 
+@length: 
+
+
+<!-- ##### FUNCTION vte_terminal_feed_child ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@data: 
+@length: 
+
+
+<!-- ##### FUNCTION vte_terminal_copy_clipboard ##### -->
+<para>
+
+</para>
+
+@terminal: 
+
+
+<!-- ##### FUNCTION vte_terminal_paste_clipboard ##### -->
+<para>
+
+</para>
+
+@terminal: 
+
+
+<!-- ##### FUNCTION vte_terminal_copy_primary ##### -->
+<para>
+
+</para>
+
+@terminal: 
+
+
+<!-- ##### FUNCTION vte_terminal_paste_primary ##### -->
+<para>
+
+</para>
+
+@terminal: 
+
+
+<!-- ##### FUNCTION vte_terminal_set_size ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@columns: 
+@rows: 
+<!-- # Unused Parameters # -->
+@Param2: 
+@Param3: 
+
+
+<!-- ##### FUNCTION vte_terminal_set_audible_bell ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@is_audible: 
+
+
+<!-- ##### FUNCTION vte_terminal_get_audible_bell ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_terminal_set_visible_bell ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@is_visible: 
+
+
+<!-- ##### FUNCTION vte_terminal_get_visible_bell ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_terminal_set_scroll_on_output ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@scroll: 
+
+
+<!-- ##### FUNCTION vte_terminal_set_scroll_on_keystroke ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@scroll: 
+
+
+<!-- ##### FUNCTION vte_terminal_set_color_bold ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@bold: 
+
+
+<!-- ##### FUNCTION vte_terminal_set_color_foreground ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@foreground: 
+
+
+<!-- ##### FUNCTION vte_terminal_set_color_background ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@background: 
+
+
+<!-- ##### FUNCTION vte_terminal_set_colors ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@foreground: 
+@background: 
+@palette: 
+@palette_size: 
+
+
+<!-- ##### FUNCTION vte_terminal_set_default_colors ##### -->
+<para>
+
+</para>
+
+@terminal: 
+
+
+<!-- ##### FUNCTION vte_terminal_set_background_image ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@image: 
+
+
+<!-- ##### FUNCTION vte_terminal_set_background_image_file ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@path: 
+
+
+<!-- ##### FUNCTION vte_terminal_set_background_saturation ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@saturation: 
+
+
+<!-- ##### FUNCTION vte_terminal_set_background_transparent ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@transparent: 
+
+
+<!-- ##### FUNCTION vte_terminal_set_cursor_blinks ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@blink: 
+
+
+<!-- ##### FUNCTION vte_terminal_set_scrollback_lines ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@lines: 
+<!-- # Unused Parameters # -->
+@Param2: 
+
+
+<!-- ##### FUNCTION vte_terminal_set_font ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@font_desc: 
+
+
+<!-- ##### FUNCTION vte_terminal_set_font_from_string ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@name: 
+
+
+<!-- ##### FUNCTION vte_terminal_get_font ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_terminal_get_using_xft ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_terminal_get_has_selection ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_terminal_set_word_chars ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@spec: 
+
+
+<!-- ##### FUNCTION vte_terminal_is_word_char ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@c: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_terminal_set_backspace_binding ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@binding: 
+
+
+<!-- ##### FUNCTION vte_terminal_set_delete_binding ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@binding: 
+
+
+<!-- ##### FUNCTION vte_terminal_set_mouse_autohide ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@setting: 
+
+
+<!-- ##### FUNCTION vte_terminal_get_mouse_autohide ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_terminal_reset ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@full: 
+@clear_history: 
+
+
+<!-- ##### FUNCTION vte_terminal_get_text ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@is_selected: 
+@attributes: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_terminal_get_text_range ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@start_row: 
+@start_col: 
+@end_row: 
+@end_col: 
+@is_selected: 
+@attributes: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_terminal_get_cursor_position ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@column: 
+@row: 
+
+
+<!-- ##### FUNCTION vte_terminal_match_clear_all ##### -->
+<para>
+
+</para>
+
+@terminal: 
+
+
+<!-- ##### FUNCTION vte_terminal_match_add ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@match: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_terminal_match_check ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@column: 
+@row: 
+@tag: 
+@Returns: 
+<!-- # Unused Parameters # -->
+@Param2: 
+@Param3: 
+
+
+<!-- ##### FUNCTION vte_terminal_set_emulation ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@emulation: 
+
+
+<!-- ##### FUNCTION vte_terminal_get_emulation ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_terminal_set_encoding ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@codeset: 
+
+
+<!-- ##### FUNCTION vte_terminal_get_encoding ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_terminal_get_status_line ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@Returns: 
+
+
+<!-- ##### FUNCTION vte_terminal_get_padding ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@xpad: 
+@ypad: 
+
+
+<!-- ##### SIGNAL VteTerminal::char-size-changed ##### -->
+<para>
+Emitted whenever selection of a new font causes the values of the
+@char_width or @char_height fields to change.
+</para>
+
+@vteterminal: the object which received the signal.
+@arg1: the new character cell width.
+@arg2: the new character cell height.
+
+<!-- ##### SIGNAL VteTerminal::child-exited ##### -->
+<para>
+This signal is emitted when the terminal detects that a child started using
+vte_terminal_fork_command() has exited.
+</para>
+
+@vteterminal: the object which received the signal.
+
+<!-- ##### SIGNAL VteTerminal::contents-changed ##### -->
+<para>
+Emitted whenever the visible appearance of the terminal has changed.  Used
+primarily by #VteTerminalAccessible.
+</para>
+
+@vteterminal: the object which received the signal.
+
+<!-- ##### SIGNAL VteTerminal::cursor-moved ##### -->
+<para>
+Emitted whenever the cursor moves to a new character cell.  Used primarily
+by #VteTerminalAccessible.
+</para>
+
+@vteterminal: the object which received the signal.
+
+<!-- ##### SIGNAL VteTerminal::deiconify-window ##### -->
+<para>
+Emitted at the child application's request.
+</para>
+
+@vteterminal: the object which received the signal.
+
+<!-- ##### SIGNAL VteTerminal::emulation-changed ##### -->
+<para>
+
+</para>
+
+@vteterminal: the object which received the signal.
+
+<!-- ##### SIGNAL VteTerminal::encoding-changed ##### -->
+<para>
+
+</para>
+
+@vteterminal: the object which received the signal.
+
+<!-- ##### SIGNAL VteTerminal::eof ##### -->
+<para>
+
+</para>
+
+@vteterminal: the object which received the signal.
+
+<!-- ##### SIGNAL VteTerminal::icon-title-changed ##### -->
+<para>
+Emitted when the terminal's @icon_title field is modified.
+</para>
+
+@vteterminal: the object which received the signal.
+
+<!-- ##### SIGNAL VteTerminal::iconify-window ##### -->
+<para>
+Emitted at the child application's request.
+</para>
+
+@vteterminal: the object which received the signal.
+
+<!-- ##### SIGNAL VteTerminal::lower-window ##### -->
+<para>
+Emitted at the child application's request.
+</para>
+
+@vteterminal: the object which received the signal.
+
+<!-- ##### SIGNAL VteTerminal::maximize-window ##### -->
+<para>
+Emitted at the child application's request.
+</para>
+
+@vteterminal: the object which received the signal.
+
+<!-- ##### SIGNAL VteTerminal::move-window ##### -->
+<para>
+Emitted at the child application's request.
+</para>
+
+@vteterminal: the object which received the signal.
+@arg1: the terminal's desired location, X coordinate.
+@arg2: the terminal's desired location, Y coordinate.
+
+<!-- ##### SIGNAL VteTerminal::raise-window ##### -->
+<para>
+Emitted at the child application's request.
+</para>
+
+@vteterminal: the object which received the signal.
+
+<!-- ##### SIGNAL VteTerminal::refresh-window ##### -->
+<para>
+Emitted at the child application's request.
+</para>
+
+@vteterminal: the object which received the signal.
+
+<!-- ##### SIGNAL VteTerminal::resize-window ##### -->
+<para>
+Emitted at the child application's request.
+</para>
+
+@vteterminal: the object which received the signal.
+@arg1: the desired width in pixels.
+@arg2: the desired height in pixels.
+
+<!-- ##### SIGNAL VteTerminal::restore-window ##### -->
+<para>
+Emitted at the child application's request.
+</para>
+
+@vteterminal: the object which received the signal.
+
+<!-- ##### SIGNAL VteTerminal::selection-changed ##### -->
+<para>
+Emitted whenever the contents of terminal's selection changes.
+</para>
+
+@vteterminal: the object which received the signal.
+
+<!-- ##### SIGNAL VteTerminal::status-line-changed ##### -->
+<para>
+Emitted whenever the contents of the status line are modified or cleared.
+</para>
+
+@vteterminal: the object which received the signal.
+
+<!-- ##### SIGNAL VteTerminal::window-title-changed ##### -->
+<para>
+Emitted when the terminal's @window_title field is modified.
+</para>
+
+@vteterminal: the object which received the signal.
+
diff --git a/doc/reference/tmpl/vteaccess.sgml b/doc/reference/tmpl/vteaccess.sgml
new file mode 100644 (file)
index 0000000..26d3f2d
--- /dev/null
@@ -0,0 +1,31 @@
+<!-- ##### SECTION Title ##### -->
+VteTerminalAccessible
+
+<!-- ##### SECTION Short_Description ##### -->
+Accessibility peer of #VteTerminal.
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### STRUCT VteTerminalAccessible ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION vte_terminal_accessible_new ##### -->
+<para>
+
+</para>
+
+@terminal: 
+@Returns: 
+
+
diff --git a/doc/reference/vte-docs.sgml b/doc/reference/vte-docs.sgml
new file mode 100644 (file)
index 0000000..04e01e4
--- /dev/null
@@ -0,0 +1,31 @@
+<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
+<!ENTITY vte-VteTerminal SYSTEM "sgml/vte.sgml">
+<!ENTITY vte-vteaccess SYSTEM "sgml/vteaccess.sgml">
+<!ENTITY vte-VteReaper SYSTEM "sgml/reaper.sgml">
+<!ENTITY vte-caps SYSTEM "sgml/caps.sgml">
+<!ENTITY vte-pty SYSTEM "sgml/pty.sgml">
+<!ENTITY vte-termcap SYSTEM "sgml/termcap.sgml">
+<!ENTITY vte-trie SYSTEM "sgml/trie.sgml">
+<!ENTITY vte-debug SYSTEM "sgml/debug.sgml">
+<!ENTITY vte-table SYSTEM "sgml/table.sgml">
+<!ENTITY vte-iso2022 SYSTEM "sgml/iso2022.sgml">
+<!ENTITY vte-ring SYSTEM "sgml/ring.sgml">
+]>
+<book id="index">
+  <bookinfo>
+    <title>VTE Reference Manual</title>
+  </bookinfo>
+
+  <chapter>
+    <title>VTE</title>
+    &vte-VteTerminal;
+    &vte-vteaccess;
+    &vte-VteReaper;
+    &vte-caps;
+    &vte-iso2022;
+    &vte-pty;
+    &vte-ring;
+    &vte-termcap;
+    &vte-trie;
+  </chapter>
+</book>
diff --git a/doc/reference/vte-sections.txt b/doc/reference/vte-sections.txt
new file mode 100644 (file)
index 0000000..75217d0
--- /dev/null
@@ -0,0 +1,153 @@
+<SECTION>
+<FILE>vte</FILE>
+VteTerminalPrivate
+<TITLE>VteTerminal</TITLE>
+VteTerminalEraseBinding
+VteTerminal
+vte_terminal_new
+vte_terminal_im_append_menuitems
+vte_terminal_fork_command
+vte_terminal_feed
+vte_terminal_feed_child
+vte_terminal_copy_clipboard
+vte_terminal_paste_clipboard
+vte_terminal_copy_primary
+vte_terminal_paste_primary
+vte_terminal_set_size
+vte_terminal_set_audible_bell
+vte_terminal_get_audible_bell
+vte_terminal_set_visible_bell
+vte_terminal_get_visible_bell
+vte_terminal_set_scroll_on_output
+vte_terminal_set_scroll_on_keystroke
+vte_terminal_set_color_bold
+vte_terminal_set_color_foreground
+vte_terminal_set_color_background
+vte_terminal_set_colors
+vte_terminal_set_default_colors
+vte_terminal_set_background_image
+vte_terminal_set_background_image_file
+vte_terminal_set_background_saturation
+vte_terminal_set_background_transparent
+vte_terminal_set_cursor_blinks
+vte_terminal_set_scrollback_lines
+vte_terminal_set_font
+vte_terminal_set_font_from_string
+vte_terminal_get_font
+vte_terminal_get_using_xft
+vte_terminal_get_has_selection
+vte_terminal_set_word_chars
+vte_terminal_is_word_char
+vte_terminal_set_backspace_binding
+vte_terminal_set_delete_binding
+vte_terminal_set_mouse_autohide
+vte_terminal_get_mouse_autohide
+vte_terminal_reset
+vte_terminal_get_text
+vte_terminal_get_text_range
+vte_terminal_get_cursor_position
+vte_terminal_match_clear_all
+vte_terminal_match_add
+vte_terminal_match_check
+vte_terminal_set_emulation
+vte_terminal_get_emulation
+vte_terminal_set_encoding
+vte_terminal_get_encoding
+vte_terminal_get_status_line
+vte_terminal_get_padding
+<SUBSECTION Standard>
+vte_terminal_erase_binding_get_type
+VTE_TYPE_TERMINAL_ERASE_BINDING
+VTE_IS_TERMINAL_ERASE_BINDING
+VTE_TERMINAL
+VTE_IS_TERMINAL
+VTE_TYPE_TERMINAL
+vte_terminal_get_type
+VTE_TERMINAL_CLASS
+VTE_IS_TERMINAL_CLASS
+VTE_TERMINAL_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>vteaccess</FILE>
+<TITLE>VteTerminalAccessible</TITLE>
+VteTerminalAccessible
+vte_terminal_accessible_new
+<SUBSECTION Standard>
+VTE_TERMINAL_ACCESSIBLE
+VTE_IS_TERMINAL_ACCESSIBLE
+VTE_TYPE_TERMINAL_ACCESSIBLE
+vte_terminal_accessible_get_type
+VTE_TERMINAL_ACCESSIBLE_CLASS
+VTE_IS_TERMINAL_ACCESSIBLE_CLASS
+VTE_TERMINAL_ACCESSIBLE_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>reaper</FILE>
+<TITLE>VteReaper</TITLE>
+VteReaper
+vte_reaper_get
+<SUBSECTION Standard>
+VTE_REAPER
+VTE_IS_REAPER
+VTE_TYPE_REAPER
+vte_reaper_get_type
+VTE_REAPER_CLASS
+VTE_IS_REAPER_CLASS
+VTE_REAPER_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>caps</FILE>
+VTE_CAP_ESC
+VTE_CAP_CSI
+VTE_CAP_ST
+VTE_CAP_OSC
+VTE_CAP_PM
+VTE_CAP_APC
+vte_capability_init
+</SECTION>
+
+<SECTION>
+<FILE>pty</FILE>
+vte_pty_open
+vte_pty_get_size
+vte_pty_set_size
+</SECTION>
+
+<SECTION>
+<FILE>termcap</FILE>
+vte_termcap_new
+vte_termcap_free
+vte_termcap_find_boolean
+vte_termcap_find_numeric
+vte_termcap_find_string
+vte_termcap_find_string_length
+vte_termcap_strip
+</SECTION>
+
+<SECTION>
+<FILE>debug</FILE>
+VteDebugFlags
+vte_debug_parse_string
+vte_debug_on
+</SECTION>
+
+<SECTION>
+<FILE>ring</FILE>
+VteRing
+VteRingFreeFunc
+vte_ring_index
+vte_ring_new
+vte_ring_insert
+vte_ring_remove
+vte_ring_at
+vte_ring_append
+vte_ring_delta
+vte_ring_length
+vte_ring_next
+vte_ring_contains
+vte_ring_free
+</SECTION>
+
diff --git a/doc/reference/vte.types b/doc/reference/vte.types
new file mode 100644 (file)
index 0000000..b39d448
--- /dev/null
@@ -0,0 +1,10 @@
+#include <glib.h>
+#include <glib-object.h>
+#include <gtk/gtk.h>
+#include "../../src/vte.h"
+#include "../../src/vteaccess.h"
+#include "../../src/reaper.h"
+
+vte_terminal_get_type
+vte_terminal_accessible_get_type
+vte_reaper_get_type
index d3632f1..a2d9de2 100644 (file)
@@ -527,6 +527,16 @@ struct vte_capability_string vte_xterm_capability_strings[] = {
        {NULL, NULL, 0},
 };
 
+/**
+ * vte_capability_init:
+ *
+ * Initializes the vte_terminal_capability_strings and
+ * vte_xterm_capability_strings structures used by the terminal.  Can
+ * be called multiple times without ill effect.
+ *
+ * Returns: void
+ */
+
 void
 vte_capability_init(void)
 {
index 5bfe422..ac99693 100644 (file)
 
 G_BEGIN_DECLS
 
-#define VTE_CAP_ESC "\e"
-#define VTE_CAP_CSI VTE_CAP_ESC "["
-#define VTE_CAP_ST  VTE_CAP_ESC "\\"
-#define VTE_CAP_OSC VTE_CAP_ESC "]"
-#define VTE_CAP_PM  VTE_CAP_ESC "^"
-#define VTE_CAP_APC VTE_CAP_ESC "_"
+#define VTE_CAP_ESC "\033"             /* Escape */
+#define VTE_CAP_CSI VTE_CAP_ESC "["    /* Control Sequence Introducer */
+#define VTE_CAP_ST  VTE_CAP_ESC "\\"   /* String Terminator */
+#define VTE_CAP_OSC VTE_CAP_ESC "]"    /* Operating System Command */
+#define VTE_CAP_PM  VTE_CAP_ESC "^"    /* Privacy Message */
+#define VTE_CAP_APC VTE_CAP_ESC "_"    /* Application Program Command */
 
 /* A NULL-terminated list of capability strings which have string values,
  * which means they're either key sequences or commands. */
index b84844d..a748378 100644 (file)
@@ -33,7 +33,7 @@ typedef enum {
        VTE_DEBUG_SELECTION     = 1 << 6,
        VTE_DEBUG_SUBSTITUTION  = 1 << 7,
        VTE_DEBUG_RING          = 1 << 8,
-       VTE_DEBUG_PTY           = 1 << 9,
+       VTE_DEBUG_PTY           = 1 << 9
 } VteDebugFlags;
 
 void vte_debug_parse_string(const char *string);
index 18ab84c..10f4441 100644 (file)
@@ -27,7 +27,6 @@
 
 G_BEGIN_DECLS
 
-struct vte_iso2022;
 struct vte_iso2022 *vte_iso2022_new(void);
 struct vte_iso2022 *vte_iso2022_copy(struct vte_iso2022 *original);
 void vte_iso2022_free(struct vte_iso2022 *p);
index ecf8bb6..233b374 100644 (file)
--- a/src/pty.c
+++ b/src/pty.c
@@ -152,6 +152,17 @@ vte_pty_fork_on_pty(const char *path, char **env_add,
        _exit(0);
 }
 
+/**
+ * vte_pty_set_size:
+ * @master: the file descriptor of the pty master
+ * @columns: the desired number of columns
+ * @rows: the desired number of rows
+ *
+ * Attempts to resize the pseudo terminal's window size.  If successful, the
+ * OS kernel will send #SIGWINCH to the child process group.
+ *
+ * Returns: 0 on success, -1 on failure.
+ */
 int
 vte_pty_set_size(int master, int columns, int rows)
 {
@@ -178,6 +189,16 @@ vte_pty_set_size(int master, int columns, int rows)
        return ret;
 }
 
+/**
+ * vte_pty_get_size:
+ * @master: the file descriptor of the pty master
+ * @columns: a place to store the number of columns
+ * @rows: a place to store the number of rows
+ *
+ * Attempts to read the pseudo terminal's window size.
+ *
+ * Returns: 0 on success, -1 on failure.
+ */
 int
 vte_pty_get_size(int master, int *columns, int *rows)
 {
@@ -330,6 +351,21 @@ vte_pty_open_old_school(pid_t *child, char **env_add,
        return -1;
 }
 
+/**
+ * vte_pty_open:
+ * @child: location to store the new process's ID
+ * @env_add: a list of environment variables to add to the child's environment
+ * @command: name of the binary to run
+ * @argv: arguments to pass to @command
+ * @columns: desired window columns
+ * @rows: desired window rows
+ *
+ * Starts a new copy of @command running under a psuedo-terminal, with window
+ * size set to @rows x @columns and variables in @env_add added to its
+ * environment.
+ *
+ * Returns: an open file descriptor for the pty master, -1 on failure
+ */
 int
 vte_pty_open(pid_t *child, char **env_add,
             const char *command, char **argv,
index 46a1488..c440d66 100644 (file)
@@ -163,6 +163,11 @@ vte_reaper_get_type(void)
        return reaper_type;
 }
 
+/**
+ * vte_reaper_get:
+ *
+ * Returns: the global #VteReaper object
+ */
 VteReaper *
 vte_reaper_get(void)
 {
index 6a70635..d624e84 100644 (file)
@@ -37,8 +37,20 @@ vte_ring_validate(VteRing *ring)
 }
 #endif
 
+/**
+ * vte_ring_new:
+ * @max_elements: the maximum size the new ring will be allowed to reach
+ * @free: a #VteRingFreeFunc
+ * @data: user data for @free
+ *
+ * Allocates a new ring capable of holding up to @max_elements elements at a
+ * time, using @free to free them when they are removed from the ring.  The
+ * @data pointer is passed to the @free callback whenever it is called.
+ *
+ * Returns: a new ring
+ */
 VteRing *
-vte_ring_new(long max_elements, VteRingFreeFunc free, gpointer data)
+vte_ring_new(glong max_elements, VteRingFreeFunc free, gpointer data)
 {
        VteRing *ret = g_malloc0(sizeof(VteRing));
        ret->user_data = data;
@@ -50,7 +62,7 @@ vte_ring_new(long max_elements, VteRingFreeFunc free, gpointer data)
 }
 
 VteRing *
-vte_ring_new_with_delta(long max_elements, long delta,
+vte_ring_new_with_delta(glong max_elements, glong delta,
                        VteRingFreeFunc free, gpointer data)
 {
        VteRing *ret;
@@ -59,6 +71,17 @@ vte_ring_new_with_delta(long max_elements, long delta,
        return ret;
 }
 
+/**
+ * vte_ring_insert:
+ * @ring: a #VteRing
+ * @position: an index
+ * @data: the new item
+ *
+ * Inserts a new item (@data) into @ring at the @position'th offset.  If @ring
+ * already has an item stored at the desired location, it will be freed before
+ * being replaced by the new @data.
+ *
+ */
 void
 vte_ring_insert(VteRing *ring, long position, gpointer data)
 {
@@ -145,6 +168,16 @@ vte_ring_insert(VteRing *ring, long position, gpointer data)
 #endif
 }
 
+/**
+ * vte_ring_remove:
+ * @ring: a #VteRing
+ * @position: an index
+ * @free_element: TRUE if the item should be freed
+ *
+ * Removes the @position'th item from @ring, freeing it only if @free_element is
+ * TRUE.
+ *
+ */
 void
 vte_ring_remove(VteRing *ring, long position, gboolean free)
 {
@@ -186,17 +219,34 @@ vte_ring_remove(VteRing *ring, long position, gboolean free)
 #endif
 }
 
+/**
+ * vte_ring_append:
+ * @ring: a #VteRing
+ * @data: the new item
+ *
+ * Appends a new item to the ring.  If an item must be removed to make room for
+ * the new item, it is freed.
+ *
+ */
 void
 vte_ring_append(VteRing *ring, gpointer data)
 {
        vte_ring_insert(ring, ring->delta + ring->length, data);
 }
 
+/**
+ * vte_ring_free:
+ * @ring: a #VteRing
+ * @free_elements: TRUE if items in the ring should be freed
+ *
+ * Frees the ring and, optionally, each of the items it contains.
+ *
+ */
 void
-vte_ring_free(VteRing *ring, gboolean free)
+vte_ring_free(VteRing *ring, gboolean free_elements)
 {
        long i;
-       if (free) {
+       if (free_elements) {
                for (i = 0; i < ring->max; i++) {
                        /* Remove this item. */
                        if ((ring->free != NULL) && (ring->array[i] != NULL)) {
index 9a968a3..f992722 100644 (file)
@@ -32,7 +32,7 @@ struct _VteRing {
        VteRingFreeFunc free;
        gpointer user_data;
        gpointer *array;
-       long delta, length, max;
+       glong delta, length, max;
 };
 
 #define vte_ring_contains(__ring, __position) \
@@ -54,11 +54,13 @@ struct _VteRing {
 #define vte_ring_index(__ring, __cast, __position) \
        (__cast) vte_ring_at(__ring, __position)
 
-VteRing *vte_ring_new(long max_elements, VteRingFreeFunc free, gpointer data);
-VteRing *vte_ring_new_with_delta(long max_elements, long delta,
+VteRing *vte_ring_new(glong max_elements,
+                     VteRingFreeFunc free,
+                     gpointer data);
+VteRing *vte_ring_new_with_delta(glong max_elements, glong delta,
                                 VteRingFreeFunc free, gpointer data);
-void vte_ring_insert(VteRing *ring, long position, gpointer data);
-void vte_ring_remove(VteRing *ring, long position, gboolean free_element);
+void vte_ring_insert(VteRing *ring, glong position, gpointer data);
+void vte_ring_remove(VteRing *ring, glong position, gboolean free_element);
 void vte_ring_append(VteRing *ring, gpointer data);
 void vte_ring_free(VteRing *ring, gboolean free_elements);
 
index e08ac8b..1698dbe 100644 (file)
@@ -60,7 +60,7 @@ struct vte_table {
 enum vte_table_argtype {
        vte_table_arg_number,
        vte_table_arg_string,
-       vte_table_arg_char,
+       vte_table_arg_char
 };
 struct vte_table_arginfo {
        enum vte_table_argtype type;
index 5ae93d5..4f8e15a 100644 (file)
@@ -223,6 +223,7 @@ vte_termcap_strip_with_pad(const char *termcap, char **stripped, gssize *len)
                                        }
                                        continue;
                                case 'E':
+                               case 'e':
                                        i++;
                                        ret[o - 1] = 27;
                                        continue;
@@ -306,11 +307,22 @@ vte_termcap_strip_with_pad(const char *termcap, char **stripped, gssize *len)
        *len = o;
 }
 
+/**
+ * vte_termcap_strip:
+ * @termcap: a termcap structure
+ * @stripped: a location to store the new stripped version of the string
+ * @len: a location to store the length of the new string
+ *
+ * Converts various types of sequences used to represent non-printable data
+ * into the data they represent.  Specifically, this resolves ^{char} sequences,
+ * octal escapes. and the \r, \n, \E, \t, \b, and \f sequences.
+ *
+ */
 void
 vte_termcap_strip(const char *termcap, char **stripped, gssize *len)
 {
        vte_termcap_strip_with_pad(termcap, stripped, len);
-       while ((len > 0) && ((*stripped)[(*len) - 1] == ':')) {
+       while (((*len) > 0) && ((*stripped)[(*len) - 1] == ':')) {
                (*len)--;
                (*stripped)[*len] = '\0';
        }
@@ -380,6 +392,13 @@ vte_termcap_new(const char *filename)
        return ret;
 }
 
+/**
+ * vte_termcap_free:
+ * @termcap: the structure to be freed
+ *
+ * Frees the indicated structure.
+ *
+ */
 TERMCAP_MAYBE_STATIC void
 vte_termcap_free(struct vte_termcap *termcap)
 {
@@ -512,6 +531,17 @@ vte_termcap_find(struct vte_termcap *termcap,
        return vte_termcap_find_l(termcap, tname, strlen(tname), cap);
 }
 
+/**
+ * vte_termcap_find_boolean:
+ * @termcap: a termcap structure
+ * @tname: the name of the terminal type being queried
+ * @cap: the name of the capability being queried
+ *
+ * Checks if the given boolean capability is defined.
+ *
+ * Returns: TRUE if the terminal type is known and the capability is defined
+ * for it
+ */
 TERMCAP_MAYBE_STATIC gboolean
 vte_termcap_find_boolean(struct vte_termcap *termcap, const char *tname,
                         const char *cap)
@@ -525,6 +555,17 @@ vte_termcap_find_boolean(struct vte_termcap *termcap, const char *tname,
        return FALSE;
 }
 
+/**
+ * vte_termcap_find_numeric:
+ * @termcap: a termcap structure
+ * @tname: the name of the terminal type being queried
+ * @cap: the name of the capability being queried
+ *
+ * Checks if the given numeric capability is defined.
+ *
+ * Returns: non-zero if the terminal type is known and the capability is defined
+ * to a non-zero value for it
+ */
 TERMCAP_MAYBE_STATIC long
 vte_termcap_find_numeric(struct vte_termcap *termcap, const char *tname,
                         const char *cap)
@@ -545,6 +586,18 @@ vte_termcap_find_numeric(struct vte_termcap *termcap, const char *tname,
        return 0;
 }
 
+/**
+ * vte_termcap_find_string:
+ * @termcap: a termcap structure
+ * @tname: the name of the terminal type being queried
+ * @cap: the name of the capability being queried
+ *
+ * Checks if the given string capability is defined.
+ *
+ * Returns: the value of the capability if the terminal type is known and the
+ * capability is defined for it, else an empty string.  The return value must
+ * always be freed by the caller.
+ */
 TERMCAP_MAYBE_STATIC char *
 vte_termcap_find_string(struct vte_termcap *termcap, const char *tname,
                        const char *cap)
@@ -565,6 +618,20 @@ vte_termcap_find_string(struct vte_termcap *termcap, const char *tname,
        return g_strdup("");
 }
 
+/**
+ * vte_termcap_find_string_length:
+ * @termcap: a termcap structure
+ * @tname: the name of the terminal type being queried
+ * @cap: the name of the capability being queried
+ * @length: the location to store the length of the returned string
+ *
+ * Checks if the given string capability is defined.  This version of
+ * vte_termcap_find_string() properly handles zero bytes in the result.
+ *
+ * Returns: the value of the capability if the terminal type is known and the
+ * capability is defined for it, else an empty string.  The return value must
+ * always be freed by the caller.
+ */
 TERMCAP_MAYBE_STATIC char *
 vte_termcap_find_string_length(struct vte_termcap *termcap, const char *tname,
                               const char *cap, ssize_t *length)
@@ -578,7 +645,10 @@ vte_termcap_find_string_length(struct vte_termcap *termcap, const char *tname,
                val += (l + 1);
                p = val;
                while (*p != ':') p++;
-               *length = l = p - val;
+               l = p - val;
+               if (length) {
+                       *length = l;
+               }
                ret = g_malloc(l + 1);
                if (l > 0) {
                        memcpy(ret, val, l);
index 5bd41cd..4919867 100644 (file)
@@ -61,7 +61,7 @@ struct char_class {
                multi,                  /* Multiple-number special class. */
                any,                    /* Any single character. */
                string,                 /* Any string of characters. */
-               invalid,                /* A placeholder. */
+               invalid                 /* A placeholder. */
        } type;
        gboolean multiple;              /* Whether a sequence of multiple
                                           characters in this class should be
index 8431116..85bf465 100644 (file)
--- a/src/vte.c
+++ b/src/vte.c
@@ -147,13 +147,13 @@ struct vte_draw_item {
  * are really only defined for "application" mode. */
 typedef enum _VteKeypad {
        VTE_KEYPAD_NORMAL,
-       VTE_KEYPAD_APPLICATION,
+       VTE_KEYPAD_APPLICATION
 } VteKeypad;
 
 /* The terminal's function key setting. */
 typedef enum _VteFKey {
        VTE_FKEY_VT220,
-       VTE_FKEY_SUNPC,
+       VTE_FKEY_SUNPC
 } VteFKey;
 
 typedef struct _VteScreen VteScreen;
@@ -245,7 +245,7 @@ struct _VteTerminalPrivate {
        enum {
                selection_type_char,
                selection_type_word,
-               selection_type_line,
+               selection_type_line
        } selection_type;
        struct selection_event_coords {
                double x, y;
@@ -623,7 +623,7 @@ vte_invalidate_all(VteTerminal *terminal)
 /* Scroll a rectangular region up or down by a fixed number of lines. */
 static void
 vte_terminal_scroll_region(VteTerminal *terminal,
-                          long row, long count, long delta)
+                          long row, glong count, glong delta)
 {
        GtkWidget *widget;
        gboolean repaint = TRUE;
@@ -654,7 +654,7 @@ vte_terminal_scroll_region(VteTerminal *terminal,
 
 /* Find the character in the given "virtual" position. */
 static struct vte_charcell *
-vte_terminal_find_charcell(VteTerminal *terminal, long col, long row)
+vte_terminal_find_charcell(VteTerminal *terminal, glong col, glong row)
 {
        GArray *rowdata;
        struct vte_charcell *ret = NULL;
@@ -1101,7 +1101,7 @@ vte_terminal_match_contents_clear(VteTerminal *terminal)
 
 /* Refresh the cache of the screen contents we keep. */
 static gboolean
-always_selected(VteTerminal *terminal, long row, long column)
+always_selected(VteTerminal *terminal, glong row, glong column)
 {
        return TRUE;
 }
@@ -1118,7 +1118,14 @@ vte_terminal_match_contents_refresh(VteTerminal *terminal)
        terminal->pvt->match_attributes = array;
 }
 
-/* Display string matching:  clear all matching expressions. */
+/**
+ * vte_terminal_match_clear_all:
+ * @terminal: a #VteTerminal
+ *
+ * Clears the list of regular expressions the terminal uses to highlight text
+ * when the user moves the mouse cursor.
+ * 
+ */
 void
 vte_terminal_match_clear_all(VteTerminal *terminal)
 {
@@ -1137,8 +1144,17 @@ vte_terminal_match_clear_all(VteTerminal *terminal)
        vte_terminal_match_hilite_clear(terminal);
 }
 
-/* Add a matching expression, returning the tag the widget assigns to that
- * expression. */
+/**
+ * vte_terminal_match_add:
+ * @terminal: a #VteTerminal
+ * @match: a regular expression
+ *
+ * Adds a regular expression to the list of matching expressions.  When the
+ * user moves the mouse cursor over a section of displayed text which matches
+ * this expression, the text will be highlighted.
+ * 
+ * Returns: an integer associated with this expression
+ */
 int
 vte_terminal_match_add(VteTerminal *terminal, const char *match)
 {
@@ -1162,7 +1178,7 @@ vte_terminal_match_add(VteTerminal *terminal, const char *match)
  * argument. */
 static char *
 vte_terminal_match_check_internal(VteTerminal *terminal,
-                                 long column, long row,
+                                 long column, glong row,
                                  int *tag, int *start, int *end)
 {
        int i, j, ret, offset;
@@ -1301,8 +1317,28 @@ vte_terminal_match_check_internal(VteTerminal *terminal,
        return NULL;
 }
 
+/**
+ * vte_terminal_match_check:
+ * @terminal: a #VteTerminal
+ * @column: the text column
+ * @row: the text row
+ * @tag: pointer to an integer
+ *
+ * Checks if the text in and around the specified position matches any of the
+ * regular expressions previously set using vte_terminal_match_add().  If a
+ * match exists, the text string is returned and if @tag is not NULL, the number
+ * associated with the matched regular expression will be stored in @tag.
+ * 
+ * If more than one regular expression has been set with
+ * vte_terminal_match_add(), then expressions are checked in the order in
+ * which they were added.
+ * 
+ * Returns: a string which matches one of the previously set regular
+ * expressions, and which must be freed by the caller.
+ */
 char *
-vte_terminal_match_check(VteTerminal *terminal, long column, long row, int *tag)
+vte_terminal_match_check(VteTerminal *terminal, glong column, glong row,
+                        int *tag)
 {
        long delta;
        char *ret;
@@ -1542,7 +1578,7 @@ vte_sequence_handler_multiple(VteTerminal *terminal,
 
 /* Insert a blank line at an arbitrary position. */
 static void
-vte_insert_line_internal(VteTerminal *terminal, long position)
+vte_insert_line_internal(VteTerminal *terminal, glong position)
 {
        GArray *array;
        /* Pad out the line data to the insertion point. */
@@ -1562,7 +1598,7 @@ vte_insert_line_internal(VteTerminal *terminal, long position)
 
 /* Remove a line at an arbitrary position. */
 static void
-vte_remove_line_internal(VteTerminal *terminal, long position)
+vte_remove_line_internal(VteTerminal *terminal, glong position)
 {
        if (vte_ring_next(terminal->pvt->screen->row_data) > position) {
                vte_ring_remove(terminal->pvt->screen->row_data,
@@ -1570,8 +1606,17 @@ vte_remove_line_internal(VteTerminal *terminal, long position)
        }
 }
 
-/* Change the encoding used for the terminal to the given codeset, or the
- * locale default if NULL is passed in. */
+/**
+ * vte_terminal_set_encoding:
+ * @terminal: a #VteTerminal
+ * @codeset: a valid #gconv target
+ *
+ * Changes the encoding the terminal will expect data from the child to
+ * be encoded with.  For certain terminal types, applications executing in the
+ * terminal can change the encoding.  The default encoding is defined by the
+ * application's locale settings.
+ *
+ */
 void
 vte_terminal_set_encoding(VteTerminal *terminal, const char *codeset)
 {
@@ -1708,6 +1753,16 @@ vte_terminal_set_encoding(VteTerminal *terminal, const char *codeset)
 #endif
        vte_terminal_emit_encoding_changed(terminal);
 }
+
+/**
+ * vte_terminal_get_encoding:
+ * @terminal: a #VteTerminal
+ *
+ * Determines the name of the encoding in which the terminal expects data to be
+ * encoded.
+ *
+ * Returns: the current encoding for the terminal.
+ */
 const char *
 vte_terminal_get_encoding(VteTerminal *terminal)
 {
@@ -5245,9 +5300,13 @@ static struct {
        {"window-manipulation", vte_sequence_handler_window_manipulation},
 };
 
-/* Create the basic widget.  This more or less creates and initializes a
- * GtkWidget and clears out the rest of the data which is specific to our
- * widget class. */
+/**
+ * vte_terminal_new:
+ *
+ * Create a new terminal widget.
+ *
+ * Returns: a new #VteTerminal object
+ */
 GtkWidget *
 vte_terminal_new(void)
 {
@@ -5387,14 +5446,28 @@ vte_terminal_generate_bold(const struct vte_palette_entry *foreground,
 #endif
 }
 
-/* Set the bold foreground color. */
+/**
+ * vte_terminal_set_color_bold
+ * @terminal: a #VteTerminal
+ * @bold: the new bold color
+ *
+ * Sets the color used to draw bold text in the default foreground color.
+ *
+ */
 void
 vte_terminal_set_color_bold(VteTerminal *terminal, const GdkColor *bold)
 {
        vte_terminal_set_color_internal(terminal, VTE_BOLD_FG, bold);
 }
 
-/* Set the foreground color. */
+/**
+ * vte_terminal_set_color_foreground
+ * @terminal: a #VteTerminal
+ * @foreground: the new foreground color
+ *
+ * Sets the foreground color used to draw normal text
+ *
+ */
 void
 vte_terminal_set_color_foreground(VteTerminal *terminal,
                                  const GdkColor *foreground)
@@ -5402,7 +5475,16 @@ vte_terminal_set_color_foreground(VteTerminal *terminal,
        vte_terminal_set_color_internal(terminal, VTE_DEF_FG, foreground);
 }
 
-/* Set the background color. */
+/**
+ * vte_terminal_set_color_background
+ * @terminal: a #VteTerminal
+ * @background: the new background color
+ *
+ * Sets the background color for text which does not have a specific background
+ * color assigned.  Only has effect when no background image is set and when
+ * the terminal is not transparent.
+ *
+ */
 void
 vte_terminal_set_color_background(VteTerminal *terminal,
                                  const GdkColor *background)
@@ -5410,7 +5492,26 @@ vte_terminal_set_color_background(VteTerminal *terminal,
        vte_terminal_set_color_internal(terminal, VTE_DEF_BG, background);
 }
 
-/* Set a given set of colors as the palette. */
+/**
+ * vte_terminal_set_colors
+ * @terminal: a #VteTerminal
+ * @foreground: the new foreground color, or #NULL
+ * @background: the new background color, or #NULL
+ * @palette: the color palette
+ * @palette_size: the number of entries in @palette
+ *
+ * The terminal widget uses a 19-color model comprised of the default foreground
+ * and background colors, the bold foreground color, an eight color palette, and
+ * bold versions of the eight color palette.
+ *
+ * @palette_size must be either 0, 8, or 16.  If @foreground is NULL and
+ * @palette_size is greater than 0, the new foreground color is taken from
+ * @palette[7].  If @background is NULL and @palette_size is greater than 0,
+ * the new background color is taken from @palette[0].  If @palette_size is
+ * 8, the second 8-color palette is extrapolated from the new background
+ * color and the items in @palette.
+ *
+ */
 void
 vte_terminal_set_colors(VteTerminal *terminal,
                        const GdkColor *foreground,
@@ -5515,7 +5616,13 @@ vte_terminal_set_colors(VteTerminal *terminal,
        terminal->pvt->palette_initialized = TRUE;
 }
 
-/* Reset palette defaults for character colors. */
+/**
+ * vte_terminal_set_default_colors:
+ * @terminal: a #VteTerminal
+ *
+ * Reset the terminal palette to reasonable compiled-in defaults.
+ *
+ */
 void
 vte_terminal_set_default_colors(VteTerminal *terminal)
 {
@@ -5793,7 +5900,20 @@ vte_terminal_catch_child_exited(VteReaper *reaper, int pid, int status,
        }
 }
 
-/* Start up a command in a slave PTY. */
+/**
+ * vte_terminal_fork_command:
+ * @terminal: a #VteTerminal
+ * @command: the name of a binary to run
+ * @argv: the argument list to be passed to @command
+ * @envv: a list of environment variables to be added to the environment before
+ * starting @command
+ *
+ * Starts the specified command under a newly-alllocated control
+ * pseudo-terminal.  TERM is automatically set to reflect the terminal widget's
+ * emulation setting.
+ *
+ * Returns: the ID of the new process
+ */
 pid_t
 vte_terminal_fork_command(VteTerminal *terminal, const char *command,
                          char **argv, char **envv)
@@ -6365,13 +6485,28 @@ vte_terminal_io_read(GIOChannel *channel,
        return leave_open;
 }
 
-/* Render some UTF-8 text. */
+/**
+ * vte_terminal_feed:
+ * @terminal: a #VteTerminal
+ * @data: a string
+ * @length: the length of the string
+ *
+ * Interprets @data as if it were data received from a child process.  This
+ * can either be used to drive the terminal without a child process, or just
+ * to mess with your users.
+ *
+ */
 void
 vte_terminal_feed(VteTerminal *terminal, const char *data, glong length)
 {
        char *buf;
        gboolean empty;
 
+       /* If length == -1, use the length of the data string. */
+       if (length == ((gssize)-1)) {
+               length = strlen(data);
+       }
+
        /* Allocate space for old and new data. */
        buf = g_malloc(terminal->pvt->n_incoming + length + 1);
        empty = (terminal->pvt->n_incoming == 0);
@@ -6519,17 +6654,26 @@ vte_terminal_send(VteTerminal *terminal, const char *encoding,
        return;
 }
 
-/* Send a chunk of UTF-8 text to the child. */
+/**
+ * vte_terminal_feed_child:
+ * @terminal: a #VteTerminal
+ * @data: data to send to the child
+ * @length: length of @text
+ *
+ * Sends a block of UTF-8 text to the child as if it were entered by the user
+ * at the keyboard.
+ *
+ */
 void
-vte_terminal_feed_child(VteTerminal *terminal, const char *text, glong length)
+vte_terminal_feed_child(VteTerminal *terminal, const char *data, glong length)
 {
        g_return_if_fail(VTE_IS_TERMINAL(terminal));
        if (length == ((gssize)-1)) {
-               length = strlen(text);
+               length = strlen(data);
        }
        vte_terminal_im_reset(terminal);
        if (length > 0) {
-               vte_terminal_send(terminal, "UTF-8", text, length);
+               vte_terminal_send(terminal, "UTF-8", data, length);
        }
 }
 
@@ -7151,7 +7295,16 @@ vte_terminal_key_release(GtkWidget *widget, GdkEventKey *event)
        return gtk_im_context_filter_keypress(terminal->pvt->im_context, event);
 }
 
-/* Check if a particular character is part of a "word" or not. */
+/**
+ * vte_terminal_is_word_char:
+ * @terminal: a #VteTerminal
+ * @c: a candidate Unicode code point
+ *
+ * Checks if a particular character is considered to be part of a word or not,
+ * based on the values last passed to vte_terminal_set_word_chars().
+ * 
+ * Returns: TRUE if the character is considered to be part of a word
+ */
 gboolean
 vte_terminal_is_word_char(VteTerminal *terminal, gunichar c)
 {
@@ -7175,7 +7328,7 @@ vte_terminal_is_word_char(VteTerminal *terminal, gunichar c)
 /* Check if the characters in the given block are in the same class (word vs.
  * non-word characters). */
 static gboolean
-vte_uniform_class(VteTerminal *terminal, long row, long scol, long ecol)
+vte_uniform_class(VteTerminal *terminal, glong row, glong scol, glong ecol)
 {
        struct vte_charcell *pcell = NULL;
        long col;
@@ -7199,8 +7352,8 @@ vte_uniform_class(VteTerminal *terminal, long row, long scol, long ecol)
 }
 
 static gboolean
-vte_cell_is_between(long col, long row,
-                   long acol, long arow, long bcol, long brow,
+vte_cell_is_between(glong col, glong row,
+                   glong acol, glong arow, glong bcol, glong brow,
                    gboolean inclusive)
 {
        long t;
@@ -7262,7 +7415,7 @@ vte_cell_is_between(long col, long row,
 
 /* Check if a cell is selected or not. */
 static gboolean
-vte_cell_is_selected(VteTerminal *terminal, long col, long row)
+vte_cell_is_selected(VteTerminal *terminal, glong col, glong row)
 {
        long scol, ecol;
 
@@ -7959,12 +8112,31 @@ vte_terminal_copy_cb(GtkClipboard *clipboard, GtkSelectionData *data,
        }
 }
 
-/* Extract a view of the widget as if we were going to copy it. */
+/**
+ * vte_terminal_get_text_range:
+ * @terminal: a #VteTerminal
+ * @start_row: first row to search for data
+ * @start_col: first column to search for data
+ * @end_row: last row to search for data
+ * @end_col: last column to search for data
+ * @is_selected: a callback
+ * @attributes: location for storing text attributes
+ *
+ * Extracts a view of the visible part of the string.  If @is_selected is not
+ * NULL, characters will only be read if @is_selected returns TRUE after being
+ * passed the column and row, respectively.  A #vte_char_attributes structure
+ * is added to @attributes for each byte added to the returned string detailing
+ * the character&apos;s position, colors, and other characteristics.  The
+ * entire scrollback buffer is scanned, so it is possible to read the entire
+ * contents of the buffer using this function.
+ *
+ * Returns: a text string which must be freed by the caller.
+ */
 char *
 vte_terminal_get_text_range(VteTerminal *terminal,
                            glong start_row, glong start_col,
                            glong end_row, glong end_col,
-                           gboolean(*is_selected)(VteTerminal *, long, long),
+                           gboolean(*is_selected)(VteTerminal *, glong, glong),
                            GArray *attributes)
 {
        long col, row, spaces;
@@ -8063,10 +8235,23 @@ vte_terminal_get_text_range(VteTerminal *terminal,
        return g_string_free(string, FALSE);
 }
 
-/* Extract a view of the widget as if we were going to copy it. */
+/**
+ * vte_terminal_get_text:
+ * @terminal: a #VteTerminal
+ * @is_selected: a callback
+ * @attributes: location for storing text attributes
+ *
+ * Extracts a view of the visible part of the string.  If @is_selected is not
+ * NULL, characters will only be read if @is_selected returns TRUE after being
+ * passed the column and row, respectively.  A #vte_char_attributes structure
+ * is added to @attributes for each byte added to the returned string detailing
+ * the character&apos;s position, colors, and other characteristics.
+ *
+ * Returns: a text string which must be freed by the caller.
+ */
 char *
 vte_terminal_get_text(VteTerminal *terminal,
-                     gboolean(*is_selected)(VteTerminal *, long, long),
+                     gboolean(*is_selected)(VteTerminal *, glong, glong),
                      GArray *attributes)
 {
        long start_row, start_col, end_row, end_col;
@@ -8077,19 +8262,32 @@ vte_terminal_get_text(VteTerminal *terminal,
        return vte_terminal_get_text_range(terminal,
                                           start_row, start_col,
                                           end_row, end_col,
-                                          is_selected,
+                                          is_selected ?
+                                          is_selected : always_selected,
                                           attributes);
 }
 
-/* Tell the caller where the cursor is, in screen coordinates. */
+/**
+ * vte_terminal_get_cursor_position:
+ * @terminal: a #VteTerminal
+ * @column: long which will hold the column 
+ * @row : long which will hold the row
+ *
+ * Reads the location of the insertion cursor and returns it.  The row
+ * coordinate is absolute.
+ *
+ */
 void
 vte_terminal_get_cursor_position(VteTerminal *terminal,
-                                long *column, long *row)
+                                glong *column, glong *row)
 {
        g_return_if_fail(VTE_IS_TERMINAL(terminal));
-       *column = terminal->pvt->screen->cursor_current.col;
-       *row    = terminal->pvt->screen->cursor_current.row -
-                 terminal->pvt->screen->insert_delta;
+       if (column) {
+               *column = terminal->pvt->screen->cursor_current.col;
+       }
+       if (row) {
+               *row = terminal->pvt->screen->cursor_current.row;
+       }
 }
 
 /* Place the selected text onto the clipboard.  Do this asynchronously so that
@@ -8318,7 +8516,7 @@ vte_terminal_button_press(GtkWidget *widget, GdkEventButton *event)
                                fprintf(stderr, "Handling click ourselves.\n");
                        }
 #endif
-                       vte_terminal_paste(terminal, GDK_SELECTION_PRIMARY);
+                       vte_terminal_paste_primary(terminal);
                        ret = TRUE;
                }
        } else
@@ -9301,7 +9499,18 @@ vte_terminal_close_font(VteTerminal *terminal)
 #endif
 }
 
-/* Set the fontset used for rendering text into the widget. */
+/**
+ * vte_terminal_set_font:
+ * @terminal: a #VteTerminal
+ * @font_desc: The #PangoFontDescription of the desired font.
+ *
+ * Sets the font used for rendering all text displayed by the terminal,
+ * overriding any fonts set using gtk_widget_modify_font().  The terminal
+ * will immediately attempt to load the desired font, retrieve its
+ * metrics, and attempts to resize itself to keep the same number of rows
+ * and columns.
+ *
+ */
 void
 vte_terminal_set_font(VteTerminal *terminal,
                      const PangoFontDescription *font_desc)
@@ -9357,6 +9566,15 @@ vte_terminal_set_font(VteTerminal *terminal,
        vte_terminal_open_font(terminal);
 }
 
+/**
+ * vte_terminal_set_font_from_string:
+ * @terminal: a #VteTerminal
+ * @name: A string describing the font.
+ *
+ * A convenience function which converts @name into a #PangoFontDescription and
+ * passes it to vte_terminal_set_font().
+ *
+ */
 void
 vte_terminal_set_font_from_string(VteTerminal *terminal, const char *name)
 {
@@ -9370,6 +9588,13 @@ vte_terminal_set_font_from_string(VteTerminal *terminal, const char *name)
        pango_font_description_free(font_desc);
 }
 
+/**
+ * vte_terminal_get_font:
+ * @terminal: a #VteTerminal
+ *
+ * Returns: a #PangoFontDescription describing the font the terminal is
+ * currently using to render text.
+ */
 const PangoFontDescription *
 vte_terminal_get_font(VteTerminal *terminal)
 {
@@ -9395,9 +9620,18 @@ vte_terminal_refresh_size(VteTerminal *terminal)
        }
 }
 
-/* Set the size of the PTY. */
+/**
+ * vte_terminal_set_size:
+ * @terminal: a #VteTerminal
+ * @columns: the desired number of columns
+ * @rows: the desired number of rows
+ *
+ * Attempts to change the terminal's size in terms of rows and columns.  If
+ * the attempt succeeds, the widget will resize itself to the proper size.
+ *
+ */
 void
-vte_terminal_set_size(VteTerminal *terminal, long columns, long rows)
+vte_terminal_set_size(VteTerminal *terminal, glong columns, glong rows)
 {
        struct winsize size;
        g_return_if_fail(VTE_IS_TERMINAL(terminal));
@@ -9483,7 +9717,16 @@ vte_terminal_set_scroll_adjustment(VteTerminal *terminal,
        }
 }
 
-/* Set the type of terminal we're emulating. */
+/**
+ * vte_terminal_set_emulation:
+ * @terminal: a #VteTerminal
+ * @emulation: the name of a terminal description
+ *
+ * Sets what type of terminal the widget attempts to emulate by scanning for
+ * control sequences defined in the system's termcap file.  Unless you
+ * are interested in this feature, always use "xterm".
+ *
+ */
 void
 vte_terminal_set_emulation(VteTerminal *terminal, const char *emulation)
 {
@@ -9619,6 +9862,12 @@ vte_terminal_set_emulation(VteTerminal *terminal, const char *emulation)
        vte_terminal_emit_emulation_changed(terminal);
 }
 
+/**
+ * vte_terminal_get_emulation:
+ * @terminal: a #VteTerminal
+ *
+ * Returns: the name of the terminal type the widget is attempting to emulate
+ */
 const char *
 vte_terminal_get_emulation(VteTerminal *terminal)
 {
@@ -9667,7 +9916,7 @@ vte_terminal_set_termcap(VteTerminal *terminal, const char *path,
 }
 
 static void
-vte_terminal_reset_rowdata(VteRing **ring, long lines)
+vte_terminal_reset_rowdata(VteRing **ring, glong lines)
 {
        VteRing *new_ring;
        GArray *row;
@@ -12519,13 +12768,31 @@ vte_terminal_get_type(void)
        return terminal_type;
 }
 
-/* External access functions. */
+/**
+ * vte_terminal_set_audible_bell:
+ * @terminal: a #VteTerminal
+ * @is_audible: TRUE if the terminal should beep
+ *
+ * Controls whether or not the terminal will beep when the child outputs the
+ * "bl" sequence.
+ *
+ */
 void
-vte_terminal_set_audible_bell(VteTerminal *terminal, gboolean audible)
+vte_terminal_set_audible_bell(VteTerminal *terminal, gboolean is_audible)
 {
        g_return_if_fail(VTE_IS_TERMINAL(terminal));
-       terminal->pvt->audible_bell = audible;
+       terminal->pvt->audible_bell = is_audible;
 }
+
+/**
+ * vte_terminal_get_audible_bell:
+ * @terminal: a #VteTerminal
+ *
+ * Checks whether or not the terminal will beep when the child outputs the
+ * "bl" sequence.
+ *
+ * Returns: TRUE if audible bell is enabled, FALSE if not
+ */
 gboolean
 vte_terminal_get_audible_bell(VteTerminal *terminal)
 {
@@ -12533,12 +12800,33 @@ vte_terminal_get_audible_bell(VteTerminal *terminal)
        return terminal->pvt->audible_bell;
 }
 
+/**
+ * vte_terminal_set_visible_bell:
+ * @terminal: a #VteTerminal
+ * @is_visible: TRUE if the terminal should flash
+ *
+ * Controls whether or not the terminal will present a visible bell to the
+ * user when the child outputs the "bl" sequence.  The terminal
+ * will clear itself to the default foreground color and then repaint itself.
+ *
+ */
 void
-vte_terminal_set_visible_bell(VteTerminal *terminal, gboolean visible)
+vte_terminal_set_visible_bell(VteTerminal *terminal, gboolean is_visible)
 {
        g_return_if_fail(VTE_IS_TERMINAL(terminal));
-       terminal->pvt->visible_bell = visible;
+       terminal->pvt->visible_bell = is_visible;
 }
+
+/**
+ * vte_terminal_get_visible_bell:
+ * @terminal: a #VteTerminal
+ *
+ * Checks whether or not the terminal will present a visible bell to the
+ * user when the child outputs the "bl" sequence.  The terminal
+ * will clear itself to the default foreground color and then repaint itself.
+ *
+ * Returns: TRUE if visible bell is enabled, FALSE if not
+ */
 gboolean
 vte_terminal_get_visible_bell(VteTerminal *terminal)
 {
@@ -12546,6 +12834,15 @@ vte_terminal_get_visible_bell(VteTerminal *terminal)
        return terminal->pvt->visible_bell;
 }
 
+/**
+ * vte_terminal_set_scroll_on_output:
+ * @terminal: a #VteTerminal
+ * @scroll: TRUE if the terminal should scroll on output
+ *
+ * Controls whether or not the terminal will forcibly scroll to the bottom of
+ * the viewable history when the new data is received from the child.
+ *
+ */
 void
 vte_terminal_set_scroll_on_output(VteTerminal *terminal, gboolean scroll)
 {
@@ -12553,6 +12850,16 @@ vte_terminal_set_scroll_on_output(VteTerminal *terminal, gboolean scroll)
        terminal->pvt->scroll_on_output = scroll;
 }
 
+/**
+ * vte_terminal_set_scroll_on_keystroke:
+ * @terminal: a #VteTerminal
+ * @scroll: TRUE if the terminal should scroll on keystrokes
+ *
+ * Controls whether or not the terminal will forcibly scroll to the bottom of
+ * the viewable history when the user presses a key.  Modifier keys do not
+ * trigger this behavior.
+ *
+ */
 void
 vte_terminal_set_scroll_on_keystroke(VteTerminal *terminal, gboolean scroll)
 {
@@ -12560,6 +12867,14 @@ vte_terminal_set_scroll_on_keystroke(VteTerminal *terminal, gboolean scroll)
        terminal->pvt->scroll_on_keystroke = scroll;
 }
 
+/**
+ * vte_terminal_copy_clipboard:
+ * @terminal: a #VteTerminal
+ *
+ * Places the selected text in the terminal in the #GDK_SELECTION_CLIPBOARD
+ * selection.
+ *
+ */
 void
 vte_terminal_copy_clipboard(VteTerminal *terminal)
 {
@@ -12567,6 +12882,15 @@ vte_terminal_copy_clipboard(VteTerminal *terminal)
        vte_terminal_copy(terminal, GDK_SELECTION_CLIPBOARD);
 }
 
+/**
+ * vte_terminal_paste_clipboard:
+ * @terminal: a #VteTerminal
+ *
+ * Sends the contents of the #GDK_SELECTION_CLIPBOARD selection to the
+ * terminal's child.  If necessary, the data is converted from UTF-8 to the
+ * terminal's current encoding.
+ *
+ */
 void
 vte_terminal_paste_clipboard(VteTerminal *terminal)
 {
@@ -12574,6 +12898,14 @@ vte_terminal_paste_clipboard(VteTerminal *terminal)
        vte_terminal_paste(terminal, GDK_SELECTION_CLIPBOARD);
 }
 
+/**
+ * vte_terminal_copy_primary:
+ * @terminal: a #VteTerminal
+ *
+ * Places the selected text in the terminal in the #GDK_SELECTION_PRIMARY
+ * selection.
+ *
+ */
 void
 vte_terminal_copy_primary(VteTerminal *terminal)
 {
@@ -12581,6 +12913,17 @@ vte_terminal_copy_primary(VteTerminal *terminal)
        vte_terminal_copy(terminal, GDK_SELECTION_PRIMARY);
 }
 
+/**
+ * vte_terminal_paste_primary:
+ * @terminal: a #VteTerminal
+ *
+ * Sends the contents of the #GDK_SELECTION_PRIMARY selection to the terminal's
+ * child.  If necessary, the data is converted from UTF-8 to the terminal's
+ * current encoding.  The terminal will call also paste the
+ * #GDK_SELECTION_PRIMARY selection when the user clicks with the the second
+ * mouse button.
+ *
+ */
 void
 vte_terminal_paste_primary(VteTerminal *terminal)
 {
@@ -12588,7 +12931,16 @@ vte_terminal_paste_primary(VteTerminal *terminal)
        vte_terminal_paste(terminal, GDK_SELECTION_PRIMARY);
 }
 
-/* Append the menu items for our input method context to the given shell. */
+/**
+ * vte_terminal_im_append_menuitems:
+ * @terminal: a #VteTerminal
+ * @menushell: a GtkMenuShell
+ *
+ * Appends menu items for various input methods to the given menu.  The
+ * user can select one of these items to modify the input method used by
+ * the terminal.
+ *
+ */
 void
 vte_terminal_im_append_menuitems(VteTerminal *terminal, GtkMenuShell *menushell)
 {
@@ -12836,6 +13188,24 @@ vte_terminal_setup_background(VteTerminal *terminal,
        vte_invalidate_all(terminal);
 }
 
+/**
+ * vte_terminal_set_background_saturation:
+ * @terminal: a #VteTerminal
+ * @saturation: TRUE if the terminal should fake transparency
+ *
+ * If a background image has been set using
+ * vte_terminal_set_background_image(), 
+ * vte_terminal_set_background_image_file(), or
+ * vte_terminal_set_background_transparent(), the terminal will adjust the
+ * brightness of the image before drawing the image.  To do so, the terminal
+ * will create a copy of the background image (or snapshot of the root
+ * window) and modify its pixel values.
+ * 
+ * If your application intends to create multiple terminal widgets with the
+ * same settings, performing this step yourself and just using
+ * vte_terminal_set_background_image() will save memory.
+ * 
+ */
 void
 vte_terminal_set_background_saturation(VteTerminal *terminal, double saturation)
 {
@@ -12947,9 +13317,19 @@ vte_terminal_filter_property_changes(GdkXEvent *xevent, GdkEvent *event,
        return GDK_FILTER_CONTINUE;
 }
 
-/* Turn background "transparency" on or off. */
+/**
+ * vte_terminal_set_background_transparent:
+ * @terminal: a #VteTerminal
+ * @transparent: TRUE if the terminal should fake transparency
+ *
+ * Sets the terminal's background image to the pixmap stored in the root
+ * window, adjusted so that if there are no windows below your application,
+ * the widget will appear to be transparent.
+ * 
+ */
 void
-vte_terminal_set_background_transparent(VteTerminal *terminal, gboolean setting)
+vte_terminal_set_background_transparent(VteTerminal *terminal,
+                                       gboolean transparent)
 {
        GdkWindow *window;
        GdkAtom atom;
@@ -12958,17 +13338,17 @@ vte_terminal_set_background_transparent(VteTerminal *terminal, gboolean setting)
 #ifdef VTE_DEBUG
        if (vte_debug_on(VTE_DEBUG_MISC)) {
                fprintf(stderr, "Turning background transparency %s.\n",
-                       setting ? "on" : "off");
+                       transparent ? "on" : "off");
        }
 #endif
-       terminal->pvt->bg_transparent = setting;
+       terminal->pvt->bg_transparent = transparent;
 
        /* To be "transparent", we treat the _XROOTPMAP_ID attribute of the
         * root window as a picture of what's beneath us, and use that as
         * the background.  It's a little tricky because we need to "scroll"
         * the image to match our window position. */
        window = gdk_get_default_root_window();
-       if (setting) {
+       if (transparent) {
                /* Get the window and property name we'll be watching for
                 * changes in. */
                atom = gdk_atom_intern("_XROOTPMAP_ID", TRUE);
@@ -12996,6 +13376,17 @@ vte_terminal_set_background_transparent(VteTerminal *terminal, gboolean setting)
        vte_terminal_queue_background_update(terminal);
 }
 
+/**
+ * vte_terminal_set_background_image:
+ * @terminal: a #VteTerminal
+ * @image: a #GdkPixbuf to use, or #NULL to cancel
+ *
+ * Sets a background image for the widget.  Text which would otherwise be
+ * drawn using the default background color will instead be drawn over the
+ * specified image.  If necessary, the image will be tiled to cover the
+ * widget's entire visible area.
+ * 
+ */
 void
 vte_terminal_set_background_image(VteTerminal *terminal, GdkPixbuf *image)
 {
@@ -13029,9 +13420,21 @@ vte_terminal_set_background_image(VteTerminal *terminal, GdkPixbuf *image)
        vte_terminal_queue_background_update(terminal);
 }
 
-/* Set the background image using just a file.  It's more efficient for a
- * caller to pass us an already-desaturated pixbuf if we've got multiple
- * instances going, but this is handy for the single-widget case. */
+/**
+ * vte_terminal_set_background_image_file:
+ * @terminal: a #VteTerminal
+ * @path: path to an image file
+ *
+ * Sets a background image for the widget.  If specified by
+ * vte_terminal_set_background_saturation, the terminal will make its
+ * in-memory copy of the image darker for its own use.
+ * 
+ * This is a convenience function for vte_terminal_set_background_image().
+ * If your application intends to create multiple terminal widgets using the
+ * same background, performing this step yourself and just using
+ * vte_terminal_set_background_image() will reduce memory consumption.
+ *
+ */
 void
 vte_terminal_set_background_image_file(VteTerminal *terminal, const char *path)
 {
@@ -13057,7 +13460,12 @@ vte_terminal_set_background_image_file(VteTerminal *terminal, const char *path)
        }
 }
 
-/* Check if we're the current owner of the clipboard. */
+/**
+ * vte_terminal_get_has_selection:
+ * @terminal: a #VteTerminal
+ *
+ * Returns: TRUE if part of the text in the terminal is selected.
+ */
 gboolean
 vte_terminal_get_has_selection(VteTerminal *terminal)
 {
@@ -13065,7 +13473,18 @@ vte_terminal_get_has_selection(VteTerminal *terminal)
        return terminal->pvt->has_selection;
 }
 
-/* Tell the caller if we're [planning on] using Xft for rendering. */
+/**
+ * vte_terminal_get_using_xft:
+ * @terminal: a #VteTerminal
+ *
+ * A #VteTerminal can use Xft, Pango, or Xlib to draw text.  This function
+ * allows an application to determine which mode the widget is in.  This
+ * setting cannot be changed by the caller, but in practice usually matches
+ * the behavior of GTK+ itself.
+ *
+ * Returns: TRUE if the terminal is using Xft to render, FALSE if the terminal
+ * is using Pango or Xlib.
+ */
 gboolean
 vte_terminal_get_using_xft(VteTerminal *terminal)
 {
@@ -13074,7 +13493,15 @@ vte_terminal_get_using_xft(VteTerminal *terminal)
               (terminal->pvt->render_method == VteRenderXft1);
 }
 
-/* Toggle the cursor blink setting. */
+/**
+ * vte_terminal_set_cursor_blinks:
+ * @terminal: a #VteTerminal
+ * @blink: TRUE if the cursor should blink
+ *
+ * Sets whether or not the cursor will blink.  The length of the blinking cycle
+ * is controlled by the "gtk-cursor-blink-time" GTK+ setting.
+ *
+ */
 void
 vte_terminal_set_cursor_blinks(VteTerminal *terminal, gboolean blink)
 {
@@ -13082,9 +13509,21 @@ vte_terminal_set_cursor_blinks(VteTerminal *terminal, gboolean blink)
        terminal->pvt->cursor_blinks = blink;
 }
 
-/* Set the length of the scrollback buffers. */
+/**
+ * vte_terminal_set_scrollback_lines:
+ * @terminal: a #VteTerminal
+ * @lines: the length of the history buffer
+ *
+ * Sets the length of the scrollback buffer used by the terminal.  The size of
+ * the scrollback buffer will be set to the larger of this value and the number
+ * of visible rows the widget can display, so 0 can safely be used to disable
+ * scrollback.  Note that this setting only affects the normal screen buffer.
+ * For terminal types which have an alternate screen buffer, no scrollback is
+ * allowed.
+ *
+ */
 void
-vte_terminal_set_scrollback_lines(VteTerminal *terminal, long lines)
+vte_terminal_set_scrollback_lines(VteTerminal *terminal, glong lines)
 {
        long highd, high, low, delta, max, next;
        VteScreen *screens[2];
@@ -13134,9 +13573,17 @@ vte_terminal_set_scrollback_lines(VteTerminal *terminal, long lines)
        vte_invalidate_all(terminal);
 }
 
-/* Set the list of characters we consider to be parts of words.  Everything
- * else will be a non-word character, and we'll use transitions between the
- * two sets when doing selection-by-words. */
+/**
+ * vte_terminal_set_word_chars:
+ * @terminal: a #VteTerminal
+ * @spec: a specification
+ *
+ * When the user double-clicks to start selection, the terminal will extend
+ * the selection on word boundaries.  It will treat characters included in @spec
+ * as parts of words, and all other characters as word separators.  Ranges of
+ * characters can be specified by separating them with a hyphen.
+ *
+ */
 void
 vte_terminal_set_word_chars(VteTerminal *terminal, const char *spec)
 {
@@ -13218,6 +13665,16 @@ vte_terminal_set_word_chars(VteTerminal *terminal, const char *spec)
        g_free(obufptr);
 }
 
+/**
+ * vte_terminal_set_backspace_binding:
+ * @terminal: a #VteTerminal
+ * @binding: a #VteTerminalEraseBinding for the backspace key
+ *
+ * Modifies the terminal's backspace key binding, which controls what
+ * string or control sequence the terminal sends to its child when the user
+ * presses the backspace key.
+ *
+ */
 void
 vte_terminal_set_backspace_binding(VteTerminal *terminal,
                                   VteTerminalEraseBinding binding)
@@ -13227,6 +13684,16 @@ vte_terminal_set_backspace_binding(VteTerminal *terminal,
        terminal->pvt->backspace_binding = binding;
 }
 
+/**
+ * vte_terminal_set_delete_binding:
+ * @terminal: a #VteTerminal
+ * @binding: a #VteTerminalEraseBinding for the delete key
+ *
+ * Modifies the terminal's delete key binding, which controls what
+ * string or control sequence the terminal sends to its child when the user
+ * presses the delete key.
+ *
+ */
 void
 vte_terminal_set_delete_binding(VteTerminal *terminal,
                                VteTerminalEraseBinding binding)
@@ -13235,6 +13702,17 @@ vte_terminal_set_delete_binding(VteTerminal *terminal,
        terminal->pvt->delete_binding = binding;
 }
 
+/**
+ * vte_terminal_set_mouse_autohide:
+ * @terminal: a #VteTerminal
+ * @setting: TRUE if the autohide should be enabled
+ *
+ * Changes the value of the terminal's mouse autohide setting.  When autohiding
+ * is enabled, the mouse cursor will be hidden when the user presses a key and
+ * shown when the user moves the mouse.  This setting can be read using
+ * vte_terminal_get_mouse_autohide().
+ *
+ */
 void
 vte_terminal_set_mouse_autohide(VteTerminal *terminal, gboolean setting)
 {
@@ -13242,6 +13720,17 @@ vte_terminal_set_mouse_autohide(VteTerminal *terminal, gboolean setting)
        terminal->pvt->mouse_autohide = setting;
 }
 
+/**
+ * vte_terminal_get_mouse_autohide:
+ * @terminal: a #VteTerminal
+ *
+ * Determines the value of the terminal's mouse autohide setting.  When
+ * autohiding is enabled, the mouse cursor will be hidden when the user presses
+ * a key and shown when the user moves the mouse.  This setting can be changed
+ * using vte_terminal_set_mouse_autohide().
+ *
+ * Returns: TRUE if autohiding is enabled, FALSE if not.
+ */
 gboolean
 vte_terminal_get_mouse_autohide(VteTerminal *terminal)
 {
@@ -13249,6 +13738,18 @@ vte_terminal_get_mouse_autohide(VteTerminal *terminal)
        return terminal->pvt->mouse_autohide;
 }
 
+/**
+ * vte_terminal_reset:
+ * @terminal: a #VteTerminal
+ * @full: TRUE to reset tabstops
+ * @clear_history: TRUE to empty the terminal's scrollback buffer
+ *
+ * Resets as much of the terminal's internal state as possible, discarding any
+ * unprocessed input data, resetting character attributes, cursor state, 
+ * national character set state, status line, terminal modes (insert/delete),
+ * selection state, and encoding.
+ * 
+ */
 void
 vte_terminal_reset(VteTerminal *terminal, gboolean full, gboolean clear_history)
 {
@@ -13369,6 +13870,18 @@ vte_terminal_reset(VteTerminal *terminal, gboolean full, gboolean clear_history)
        vte_invalidate_all(terminal);
 }
 
+/**
+ * vte_terminal_get_status_line:
+ * @terminal: a #VteTerminal
+ *
+ * Some terminal emulations specify a status line which is separate from the
+ * main display area, and define a means for applications to move the cursor
+ * to the status line and back.
+ *
+ * Returns: the current contents of the terminal's status line.  For terminals
+ * like "xterm", this will usually be the empty string.  The string must not
+ * be modified or freed by the caller.
+ */
 const char *
 vte_terminal_get_status_line(VteTerminal *terminal)
 {
@@ -13376,6 +13889,23 @@ vte_terminal_get_status_line(VteTerminal *terminal)
        return terminal->pvt->screen->status_line_contents->str;
 }
 
+/**
+ * vte_terminal_get_padding:
+ * @terminal: a #VteTerminal
+ * @xpad: address in which to store left/right-edge padding
+ * @ypad: address in which to store top/bottom-edge ypadding
+ *
+ * Determines the amount of additional space the widget is using to pad the
+ * edges of its visible area.  This is necessary for cases where characters
+ * in the selected font don't themselves include a padding area and the
+ * text itself would be contiguous with the window border.  Applications
+ * which use the widget's #row_count, #column_count, #char_height, and
+ * #char_width fields to set geometry hints using
+ * gtk_window_set_geometry_hints() will need to add this value to the base
+ * size.  The values returned in @xpad and @ypad are the total padding used
+ * in each direction, and do not need to be doubled.
+ *
+ */
 void
 vte_terminal_get_padding(VteTerminal *terminal, int *xpad, int *ypad)
 {
index 2664915..25613d7 100644 (file)
--- a/src/vte.h
+++ b/src/vte.h
@@ -44,12 +44,13 @@ struct _VteTerminal {
        GtkAdjustment *adjustment;      /* Scrolling adjustment. */
 
        /* Metric and sizing data. */
-       long char_width, char_height;   /* dimensions of character cells */
-       long char_ascent, char_descent; /* important font metrics */
-       long row_count, column_count;   /* dimensions of the window */
+       glong char_width, char_height;  /* dimensions of character cells */
+       glong char_ascent, char_descent; /* important font metrics */
+       glong row_count, column_count;  /* dimensions of the window */
 
        /* Titles. */
-       char *window_title, *icon_title;
+       char *window_title;
+       char *icon_title;
 
        /*< private >*/
        VteTerminalPrivate *pvt;
@@ -98,7 +99,7 @@ typedef enum {
        VTE_ERASE_AUTO,
        VTE_ERASE_ASCII_BACKSPACE,
        VTE_ERASE_ASCII_DELETE,
-       VTE_ERASE_DELETE_SEQUENCE,
+       VTE_ERASE_DELETE_SEQUENCE
 } VteTerminalEraseBinding;
 
 /* The structure we return as the supplemental attributes for strings. */
@@ -148,7 +149,8 @@ void vte_terminal_copy_primary(VteTerminal *terminal);
 void vte_terminal_paste_primary(VteTerminal *terminal);
 
 /* Set the terminal's size. */
-void vte_terminal_set_size(VteTerminal *terminal, long columns, long rows);
+void vte_terminal_set_size(VteTerminal *terminal,
+                          glong columns, glong rows);
 
 /* Set various one-off settings. */
 void vte_terminal_set_audible_bell(VteTerminal *terminal, gboolean is_audible);
@@ -186,7 +188,7 @@ void vte_terminal_set_background_transparent(VteTerminal *terminal,
 void vte_terminal_set_cursor_blinks(VteTerminal *terminal, gboolean blink);
 
 /* Set the number of scrollback lines, above or at an internal minimum. */
-void vte_terminal_set_scrollback_lines(VteTerminal *terminal, long lines);
+void vte_terminal_set_scrollback_lines(VteTerminal *terminal, glong lines);
 
 /* Append the input method menu items to a given shell. */
 void vte_terminal_im_append_menuitems(VteTerminal *terminal,
@@ -229,18 +231,19 @@ void vte_terminal_reset(VteTerminal *terminal, gboolean full,
  * Note that it will have one entry per byte, not per character, so indexes
  * should match up exactly. */
 char *vte_terminal_get_text(VteTerminal *terminal,
-                           gboolean(*is_selected)(VteTerminal * terminal,
-                                                  long column, long row),
+                           gboolean(*is_selected)(VteTerminal *terminal,
+                                                  glong column,
+                                                  glong row),
                            GArray *attributes);
 char *vte_terminal_get_text_range(VteTerminal *terminal,
                                  glong start_row, glong start_col,
                                  glong end_row, glong end_col,
-                                 gboolean(*is_selected)(VteTerminal * terminal,
-                                                        long column,
-                                                        long row),
+                                 gboolean(*is_selected)(VteTerminal *terminal,
+                                                        glong column,
+                                                        glong row),
                                  GArray *attributes);
 void vte_terminal_get_cursor_position(VteTerminal *terminal,
-                                     long *column, long *row);
+                                     glong *column, glong *row);
 
 /* Display string matching:  clear all matching expressions. */
 void vte_terminal_match_clear_all(VteTerminal *terminal);
@@ -252,7 +255,8 @@ int vte_terminal_match_add(VteTerminal *terminal, const char *match);
 /* Check if a given cell on the screen contains part of a matched string.  If
  * it does, return the string, and store the match tag in the optional tag
  * argument. */
-char *vte_terminal_match_check(VteTerminal *terminal, long column, long row,
+char *vte_terminal_match_check(VteTerminal *terminal,
+                              glong column, glong row,
                               int *tag);
 
 /* Set the emulation type.  Most of the time you won't need this. */
@@ -260,7 +264,7 @@ void vte_terminal_set_emulation(VteTerminal *terminal, const char *emulation);
 const char *vte_terminal_get_emulation(VteTerminal *terminal);
 
 /* Set the character encoding.  Most of the time you won't need this. */
-void vte_terminal_set_encoding(VteTerminal *terminal, const char *encoding);
+void vte_terminal_set_encoding(VteTerminal *terminal, const char *codeset);
 const char *vte_terminal_get_encoding(VteTerminal *terminal);
 
 /* Get the contents of the status line. */
index 869b626..0679ba0 100644 (file)
@@ -52,7 +52,7 @@ typedef struct _VteTerminalAccessiblePrivate {
 enum direction {
        direction_previous = -1,
        direction_current = 0,
-       direction_next = 1,
+       direction_next = 1
 };
 
 static gunichar vte_terminal_accessible_get_character_at_offset(AtkText *text,
@@ -75,7 +75,7 @@ vte_terminal_accessible_new_private_data(void)
 
 /* "Oh yeah, that's selected.  Sure."  */
 static gboolean
-all_selected(VteTerminal *terminal, long column, long row)
+all_selected(VteTerminal *terminal, glong column, glong row)
 {
        return TRUE;
 }
@@ -308,6 +308,14 @@ vte_terminal_accessible_title_changed(VteTerminal *terminal, gpointer data)
        atk_object_set_description(ATK_OBJECT(data), terminal->window_title);
 }
 
+/**
+ * vte_terminal_accessible_new:
+ * @terminal: a #VteTerminal
+ *
+ * Creates a new accessibility peer for the terminal widget.
+ *
+ * Returns: the new #AtkObject
+ */
 AtkObject *
 vte_terminal_accessible_new(VteTerminal *terminal)
 {
index a209ac0..cd21e09 100644 (file)
 G_BEGIN_DECLS
 
 /* The terminal accessibility object itself. */
-typedef struct _VteTerminalAccessible {
+typedef struct _VteTerminalAccessible VteTerminalAccessible;
+struct _VteTerminalAccessible {
        GtkAccessible parent;
-} VteTerminalAccessible;
+};
 
 /* The object's class structure. */
-typedef struct _VteTerminalAccessibleClass {
+typedef struct _VteTerminalAccessibleClass VteTerminalAccessibleClass;
+struct _VteTerminalAccessibleClass {
        /*< public > */
        /* Inherited parent class. */
        GtkAccessibleClass parent_class;
-} VteTerminalAccessibleClass;
+};
 
 /* The object's type. */
 GtkType vte_terminal_accessible_get_type(void);