Copy check-doc-syntax.sh tests from cairo and fix doc bugs.

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.


svn path=/trunk/; revision=2280

8 files changed, 120 insertions, 12 deletions

diff --git a/ChangeLog b/ChangeLog
index 4e0ffb17..c8b7ee90 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,17 @@
 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.
+
+2008-12-01  Behdad Esfahbod  <behdad@gnome.org>
+
 	* doc/reference/tmpl/vte-unused.sgml:
 	* doc/reference/vte-sections.txt:
 	Remove reaper docs.
diff --git a/doc/reference/Makefile.am b/doc/reference/Makefile.am
index b69c930a..385969c8 100644
--- a/doc/reference/Makefile.am
+++ b/doc/reference/Makefile.am
@@ -68,8 +68,13 @@ include $(top_srcdir)/gtk-doc.make
 # 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)"
diff --git a/doc/reference/check-doc-syntax.sh b/doc/reference/check-doc-syntax.sh
new file mode 100755
index 00000000..c446d26b
--- /dev/null
+++ b/doc/reference/check-doc-syntax.sh
@@ -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"
diff --git a/src/Makefile.am b/src/Makefile.am
index 458fec00..95417237 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -155,8 +155,11 @@ pkglib_PROGRAMS = interpret slowcat
 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)
diff --git a/src/check-doc-syntax.sh b/src/check-doc-syntax.sh
new file mode 100755
index 00000000..b530270e
--- /dev/null
+++ b/src/check-doc-syntax.sh
@@ -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
diff --git a/src/vte.c b/src/vte.c
index 12add584..a921cc01 100644
--- a/src/vte.c
+++ b/src/vte.c
@@ -280,7 +280,7 @@ G_DEFINE_TYPE(VteTerminal, vte_terminal, GTK_TYPE_WIDGET)
 
 
 /* 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 @@ vte_terminal_set_default_colors(VteTerminal *terminal)
 }
 
 
-/* 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 @@ vte_terminal_catch_child_exited(VteReaper *reaper, int pid, int status,
                 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 @@ vte_terminal_get_text(VteTerminal *terminal,
  * 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 @@ vte_terminal_class_init(VteTerminalClass *klass)
          * 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 @@ vte_terminal_class_init(VteTerminalClass *klass)
         /**
          * 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 @@ vte_terminal_set_cursor_blinks(VteTerminal *terminal, gboolean blink)
  * @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
diff --git a/src/vte.h b/src/vte.h
index 02195105..d49164e7 100644
--- a/src/vte.h
+++ b/src/vte.h
@@ -336,7 +336,7 @@ void vte_terminal_reset(VteTerminal *terminal, gboolean full,
 /* 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,
diff --git a/src/vtepangocairo.c b/src/vtepangocairo.c
index 5d213dde..1199db6b 100644
--- a/src/vtepangocairo.c
+++ b/src/vtepangocairo.c
@@ -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