vte r2280 - in trunk: . doc/reference src

[behdad svn gnome org]

Author: behdad
Date: Tue Dec  2 00:11:48 2008
New Revision: 2280
URL: http://svn.gnome.org/viewvc/vte?rev=2280&view=rev

Log:
2008-12-01  Behdad Esfahbod  <behdad gnome org>

        * doc/reference/Makefile.am:
        * doc/reference/check-doc-syntax.sh:
        * src/Makefile.am:
        * src/check-doc-syntax.sh:
        * src/vte.c (vte_terminal_catch_child_exited),
        (vte_terminal_class_init):
        * src/vte.h:
        * src/vtepangocairo.c:
        Copy check-doc-syntax.sh tests from cairo and fix doc bugs.



Added:
   trunk/doc/reference/check-doc-syntax.sh   (contents, props changed)
   trunk/src/check-doc-syntax.sh   (contents, props changed)
Modified:
   trunk/ChangeLog
   trunk/doc/reference/Makefile.am
   trunk/src/Makefile.am
   trunk/src/vte.c
   trunk/src/vte.h
   trunk/src/vtepangocairo.c

Modified: trunk/doc/reference/Makefile.am
==============================================================================
--- trunk/doc/reference/Makefile.am	(original)
+++ trunk/doc/reference/Makefile.am	Tue Dec  2 00:11:48 2008
@@ -68,8 +68,13 @@
 # This line really belongs in gtk-doc.mk
 $(REPORT_FILES): sgml-build.stamp
 
+TESTS =
+
 if ENABLE_GTK_DOC
-TESTS = check-doc-coverage.sh
+TESTS += check-doc-coverage.sh
 endif
 
-EXTRA_DIST += check-doc-coverage.sh
+TESTS += check-doc-syntax.sh
+EXTRA_DIST += check-doc-coverage.sh check-doc-syntax.sh
+
+TESTS_ENVIRONMENT = srcdir="$(srcdir)" top_srcdir="$(top_srcdir)" MAKE="$(MAKE) $(AM_MAKEFLAGS)" DOC_MODULE="$(DOC_MODULE)" REPORT_FILES="$(REPORT_FILES)"

Added: trunk/doc/reference/check-doc-syntax.sh
==============================================================================
--- (empty file)
+++ trunk/doc/reference/check-doc-syntax.sh	Tue Dec  2 00:11:48 2008
@@ -0,0 +1,11 @@
+#!/bin/sh
+
+LANG=C
+
+test -z "$srcdir" && srcdir=.
+test -z "$top_srcdir" && top_srcdir=$srcdir/../..
+
+SGML_DOCS=true
+FILES=`echo $srcdir/tmpl/*.sgml`
+
+. "$top_srcdir/src/check-doc-syntax.sh"

Modified: trunk/src/Makefile.am
==============================================================================
--- trunk/src/Makefile.am	(original)
+++ trunk/src/Makefile.am	Tue Dec  2 00:11:48 2008
@@ -155,8 +155,11 @@
 pkglib_SCRIPTS = decset osc window
 EXTRA_DIST += $(pkglib_SCRIPTS)
 
+TEST_SH = check-doc-syntax.sh
+EXTRA_DIST += $(TEST_SH)
+
 check_PROGRAMS = buffer dumpkeys iso2022 pty reaper reflect-text-view reflect-vte ring mev ssfe table trie xticker vteconv vtetc
-TESTS = buffer ring table trie
+TESTS = buffer ring table trie $(TEST_SH)
 
 AM_CFLAGS = $(GLIB_CFLAGS) $(GOBJECT_CFLAGS)
 LDADD = $(GLIB_LIBS) $(GOBJECT_LIBS)

Added: trunk/src/check-doc-syntax.sh
==============================================================================
--- (empty file)
+++ trunk/src/check-doc-syntax.sh	Tue Dec  2 00:11:48 2008
@@ -0,0 +1,77 @@
+#!/bin/sh
+
+LANG=C
+
+prefix=vte
+PREFIX=VTE
+
+if grep --version 2>/dev/null | grep GNU >/dev/null; then
+	:
+else
+	echo "GNU grep not found; skipping test"
+	exit 0
+fi
+
+test -z "$srcdir" && srcdir=.
+stat=0
+
+echo Checking documentation for incorrect syntax
+
+cd "$srcdir"
+
+# Note: this test is also run from doc/public/ to check the SGML files
+
+if test "x$SGML_DOCS" = x; then
+    FILES=$all_source_files
+    if test "x$FILES" = x; then
+        FILES=`find . -name "$prefix*.h" -or -name "$prefix*.c"`
+    fi
+fi
+
+enum_regexp="\([^%@']\|^\)\<\(FALSE\|TRUE\|NULL\|${PREFIX}_[0-9A-Z_]*\)\($\|[^(A-Za-z0-9_]\)"
+if test "x$SGML_DOCS" = x; then
+	enum_regexp='^[^:]*:[/ ][*]\(\|[ \t].*\)'$enum_regexp
+fi
+if echo $FILES | xargs grep . /dev/null | sed -e '/<programlisting>/,/<\/programlisting>/d' | grep "$enum_regexp" | grep -v '#####'; then
+	stat=1
+	echo Error: some macros in the docs are not prefixed by percent sign.
+	echo Fix this by searching for the following regexp in the above files:
+	echo "	'$enum_regexp'"
+fi >&2
+
+type_regexp="\( .*[^#']\| \|^\)\<$prefix[0-9a-z_]*_t\>\($\|[^:]$\|[^:].\)"
+if test "x$SGML_DOCS" = x; then
+	type_regexp='^[^:]*:[/ ][*]'$type_regexp
+else
+	type_regexp='\(.'$type_regexp'\)\|\('$type_regexp'.\)'
+fi
+
+if echo $FILES | xargs grep . /dev/null | sed -e '/<programlisting>/,/<\/programlisting>/d' | grep "$type_regexp" | grep -v '#####'; then
+	stat=1
+	echo Error: some type names in the docs are not prefixed by hash sign,
+	echo neither are the only token in the doc line followed by colon.
+	echo Fix this by searching for the following regexp in the above files:
+	echo "	'$type_regexp'"
+fi >&2
+
+func_regexp="\([^#']\|^\)\<\(${prefix}_[][<>/0-9a-z_]*\>[^][<>(]\)"
+if test "x$SGML_DOCS" = x; then
+	func_regexp='^[^:]*:[/ ][*]\(\|[ \t].*\)'$func_regexp
+fi
+
+# We need to filter out gtk-doc markup errors for program listings.
+if echo $FILES | xargs grep . /dev/null | sed -e '/<programlisting>/,/<\/programlisting>/d' | grep "$func_regexp" | grep -v '^[^:]*: [*] [a-z_0-9]*:$' | grep -v '#####'; then
+	stat=1
+	echo Error: some function names in the docs are not followed by parentheses.
+	echo Fix this by searching for the following regexp in the above files:
+	echo "	'$func_regexp'"
+fi >&2
+
+note_regexp='\<NOTE\>'
+if echo $FILES | xargs grep "$note_regexp" /dev/null; then
+	stat=1
+	echo Error: some source files contain the string 'NOTE'.
+	echo Be civil and replace it by 'Note' please.
+fi >&2
+
+exit $stat

Modified: trunk/src/vte.c
==============================================================================
--- trunk/src/vte.c	(original)
+++ trunk/src/vte.c	Tue Dec  2 00:11:48 2008
@@ -280,7 +280,7 @@
 
 
 /* Indexes in the "palette" color array for the dim colors.
- * Only the first VTE_LEGACY_COLOR_SET_SIZE colors have dim versions.  */
+ * Only the first %VTE_LEGACY_COLOR_SET_SIZE colors have dim versions.  */
 static const guchar corresponding_dim_index[] = {16,88,28,100,18,90,30,102};
 
 /* Free a no-longer-used row data array. */
@@ -2941,7 +2941,7 @@
 }
 
 
-/* Cleanup smart-tabs.  See vte_sequence_handler_ta */
+/* Cleanup smart-tabs.  See vte_sequence_handler_ta() */
 inline void
 _vte_terminal_cleanup_tab_fragments_at_cursor (VteTerminal *terminal)
 {
@@ -3304,7 +3304,7 @@
                 g_object_thaw_notify(object);
                 g_object_unref(object);
 
-                /* NOTE! terminal may be destroyed at this point */
+                /* Note: terminal may be destroyed at this point */
 	}
 }
 
@@ -6027,7 +6027,7 @@
  * passed the column and row, respectively.  A #VteCharAttributes structure
  * is added to @attributes for each byte added to the returned string detailing
  * the character's position, colors, and other characteristics. This function
- * differs from vte_terminal_get_text in that trailing spaces at the end of
+ * differs from vte_terminal_get_text() in that trailing spaces at the end of
  * lines are included.
  *
  * Returns: a text string which must be freed by the caller, or %NULL.
@@ -11738,7 +11738,7 @@
          * window as the background, adjusted so that if there are no windows
          * below your application, the widget will appear to be transparent.
          *
-         * NOTE: When using a compositing window manager, you should instead
+         * Note: When using a compositing window manager, you should instead
          * set a RGBA colourmap on the toplevel window, so you get real transparency.
          *
          * Since: 0.17.5
@@ -11769,7 +11769,7 @@
         /**
          * VteTerminal:cursor-blink-mode:
          *
-         * Sets whether or not the cursor will blink. Using VTE_CURSOR_BLINK_SYSTEM
+         * Sets whether or not the cursor will blink. Using %VTE_CURSOR_BLINK_SYSTEM
          * will use the #GtkSettings::gtk-cursor-blink setting.
          * 
          * Since: 0.17.5
@@ -12762,7 +12762,7 @@
  * @terminal: a #VteTerminal
  * @mode: the #VteTerminalCursorBlinkMode to use
  *
- * Sets whether or not the cursor will blink. Using VTE_CURSOR_BLINK_SYSTEM
+ * Sets whether or not the cursor will blink. Using %VTE_CURSOR_BLINK_SYSTEM
  * will use the #GtkSettings::gtk-cursor-blink setting.
  *
  * Since: 0.16.15

Modified: trunk/src/vte.h
==============================================================================
--- trunk/src/vte.h	(original)
+++ trunk/src/vte.h	Tue Dec  2 00:11:48 2008
@@ -336,7 +336,7 @@
 /* Read the contents of the terminal, using a callback function to determine
  * if a particular location on the screen (0-based) is interesting enough to
  * include.  Each byte in the returned string will have a corresponding
- * VteCharAttributes structure in the passed GArray, if the array was not NULL.
+ * VteCharAttributes structure in the passed GArray, if the array was not %NULL.
  * 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,

Modified: trunk/src/vtepangocairo.c
==============================================================================
--- trunk/src/vtepangocairo.c	(original)
+++ trunk/src/vtepangocairo.c	Tue Dec  2 00:11:48 2008
@@ -133,7 +133,7 @@
  * Setting this to a large value can cause dramatic slow-downs for some
  * xservers (notably fglrx), see bug #410534.
  *
- * Moreover, setting it larger than VTE_DRAW_MAX_LENGTH is nonsensical,
+ * Moreover, setting it larger than %VTE_DRAW_MAX_LENGTH is nonsensical,
  * as the higher layers will not submit runs longer than that value.
  */
 #define MAX_RUN_LENGTH 100