[gtk-doc] mkhtml, mkman, mkpdf: improved usage output, add --verbose switch

[Stefan Kost <stefkost src gnome org>]

commit 8a7db93c69a913395c2102528226b121186f2f45
Author: Stefan Kost <ensonic users sf net>
Date:   Wed Apr 13 15:09:15 2011 +0300

    mkhtml,mkman,mkpdf: improved usage output, add --verbose switch

 gtkdoc-mkhtml.in |   84 ++++++++++++++++++++++++++++++++---------------------
 gtkdoc-mkman.in  |   70 ++++++++++++++++++++++++++++----------------
 gtkdoc-mkpdf.in  |   80 ++++++++++++++++++++++++++++++++------------------
 3 files changed, 146 insertions(+), 88 deletions(-)
---
diff --git a/gtkdoc-mkhtml.in b/gtkdoc-mkhtml.in
index 1abdf4f..c2fc588 100644
--- a/gtkdoc-mkhtml.in
+++ b/gtkdoc-mkhtml.in
@@ -1,29 +1,41 @@
 #!/bin/sh
 #
 
-usage="\
-Usage: gtkdoc-mkhtml [--path=SEARCH_PATH] MODULE DRIVER_FILE [BACKEND_OPTIONS...]"
+usage() {
+cat <<EOF
+gtkdoc-mkhtml version @VERSION@ - generate documentation in html format
 
-#echo "args $0\n";
+--verbose               Print extra output while processing
+--path=SEARCH_PATH      Extra source directories
+MODULE                  Name of the doc module being parsed
+DRIVER_FILE             File containing the toplevel DocBook file.
+--version               Print the version of this program
+--help                  Print this help
+EOF
+}
+
+# echo "args $*\n";
 
 # parse options, ignore unknown options for future extensions
 
+verbose="0"
 searchpath=
 uninstalled=no
 while true; do
     case "X$1" in
         X--version) echo "@VERSION@"; exit 0;;
-        X--help) echo "$usage"; exit 0;;
+        X--help) usage; exit 0;;
         X--uninstalled) uninstalled=yes; shift;;
+        X--verbose) verbose="1"; shift;;
         X--path=*) searchpath=`echo $1 | sed s/.*=//`; shift;;
         X--*) shift;;
         X*) break;;
     esac
 done
- 
+
 if test $# -lt 2; then
-      echo "${usage}" 1>&2
-      exit 1
+    usage 1>&2
+    exit 1
 fi
 
 module=$1
@@ -31,29 +43,34 @@ shift
 document=$1
 shift
 
+quiet="1"
+if test $verbose = "1"; then
+    quiet="0"
+fi
+
 if test $uninstalled = yes; then
-      # this does not work from buiddir!=srcdir
-      gtkdocdir=`dirname $0`
-      if test ! -e $gtkdocdir/gtk-doc.xsl; then
+    # this does not work from buiddir!=srcdir
+    gtkdocdir=`dirname $0`
+    if test ! -e $gtkdocdir/gtk-doc.xsl; then
         # try to src dir (set from makefiles) too
         if test -e $ABS_TOP_SRCDIR/gtk-doc.xsl; then
-          gtkdocdir=$ABS_TOP_SRCDIR
+            gtkdocdir=$ABS_TOP_SRCDIR
         fi
-      fi
-      #echo "uninstalled, gtkdocdir=$gtkdocdir, cwd=$PWD"
+    fi
+    #echo "uninstalled, gtkdocdir=$gtkdocdir, cwd=$PWD"
 else
-      # the first two are needed to resolve datadir
-      prefix= prefix@
-      datarootdir= datarootdir@
-      gtkdocdir= datadir@/gtk-doc/data
+    # the first two are needed to resolve datadir
+    prefix= prefix@
+    datarootdir= datarootdir@
+    gtkdocdir= datadir@/gtk-doc/data
 fi
 
 if head -n 1 $document | grep "<?xml" > /dev/null; then
-  is_xml=true
-  path_option='--path'
+    is_xml=true
+    path_option='--path'
 else
-  is_xml=false
-  path_option='--directory'
+    is_xml=false
+    path_option='--directory'
 fi
 
 # we could do "$path_option $PWD "
@@ -67,22 +84,23 @@ fi
 
 # Delete the old index.sgml file, if it exists.
 if test -f index.sgml; then
-      rm -f index.sgml
+  rm -f index.sgml
 fi
 
 if $is_xml; then
-  #echo @XSLTPROC@ $path_arg --nonet --xinclude \
-  #    --stringparam gtkdoc.bookname $module \
-  #    --stringparam gtkdoc.version "@VERSION@" \
-  #    "$@" $gtkdocdir/gtk-doc.xsl $document
-  @XSLTPROC@ $path_arg --nonet --xinclude \
-      --stringparam gtkdoc.bookname $module \
-      --stringparam gtkdoc.version "@VERSION@" \
-      "$@" $gtkdocdir/gtk-doc.xsl $document || exit $?
+    #echo @XSLTPROC@ $path_arg --nonet --xinclude \
+    #    --stringparam gtkdoc.bookname $module \
+    #    --stringparam gtkdoc.version "@VERSION@" \
+    #    "$@" $gtkdocdir/gtk-doc.xsl $document
+    @XSLTPROC@ $path_arg --nonet --xinclude \
+        --stringparam gtkdoc.bookname $module \
+        --stringparam gtkdoc.version "@VERSION@" \
+        --stringparam chunk.quietly $quiet \
+        "$@" $gtkdocdir/gtk-doc.xsl $document || exit $?
 else
-  @JADE@ $path_arg -t @SGML_FORMAT_TYPE@ -w no-idref -d $gtkdocdir/gtk-doc.dsl \
-      -V "gtkdoc-bookname=$module" -V "gtkdoc-version= VERSION@" \
-      "$@" $gtkdocdir/gtk-doc.dcl $document || exit $?
+    @JADE@ $path_arg -t @SGML_FORMAT_TYPE@ -w no-idref -d $gtkdocdir/gtk-doc.dsl \
+        -V "gtkdoc-bookname=$module" -V "gtkdoc-version= VERSION@" \
+        "$@" $gtkdocdir/gtk-doc.dcl $document || exit $?
 fi
 
 # copy navigation images and stylesheets to html directory ...
diff --git a/gtkdoc-mkman.in b/gtkdoc-mkman.in
index c5f5857..bf50380 100644
--- a/gtkdoc-mkman.in
+++ b/gtkdoc-mkman.in
@@ -1,18 +1,30 @@
 #!/bin/sh
 #
 
-usage="\
-Usage: gtkdoc-mkman [--path=SEARCH_PATH] MODULE DRIVER_FILE"
+usage() {
+cat <<EOF
+gtkdoc-mkman version @VERSION@ - generate documentation in man format
+
+--verbose               Print extra output while processing
+--path=SEARCH_PATH      Extra source directories
+MODULE                  Name of the doc module being parsed
+DRIVER_FILE             File containing the toplevel DocBook file.
+--version               Print the version of this program
+--help                  Print this help
+EOF
+}
 
 # parse options, ignore unknown options for future extensions
 
+verbose=0
 searchpath=
 uninstalled=no
 while true; do
     case "X$1" in
         X--version) echo "@VERSION@"; exit 0;;
-        X--help) echo "$usage"; exit 0;;
+        X--help) usage; exit 0;;
         X--uninstalled) uninstalled=yes; shift;;
+        X--verbose) verbose="1"; shift;;
         X--path=*) searchpath=`echo $1 | sed s/.*=//`; shift;;
         X--*) shift;;
         X*) break;;
@@ -20,8 +32,8 @@ while true; do
 done
 
 if test $# -ne 2; then
-      echo "${usage}" 1>&2
-      exit 1
+    usage 1>&2
+    exit 1
 fi
 
 module=$1
@@ -29,23 +41,28 @@ shift
 document=$1
 shift
 
+quiet="1"
+if test $verbose = "1"; then
+    quiet="0"
+fi
+
 if test $uninstalled = yes; then
-      # this does not work from buiddir!=srcdir
-      gtkdocdir=`dirname $0`
-      #echo "uninstalled, gtkdocdir=$gtkdocdir"
+    # this does not work from buiddir!=srcdir
+    gtkdocdir=`dirname $0`
+    #echo "uninstalled, gtkdocdir=$gtkdocdir"
 else
-      # the first two are needed to resolve datadir
-      prefix= prefix@
-      datarootdir= datarootdir@
-      gtkdocdir= datadir@/gtk-doc/data
+    # the first two are needed to resolve datadir
+    prefix= prefix@
+    datarootdir= datarootdir@
+    gtkdocdir= datadir@/gtk-doc/data
 fi
 
 if head -n 1 $document | grep "<?xml" > /dev/null; then
-  is_xml=true
-  path_option='--path'
+   is_xml=true
+    path_option='--path'
 else
-  is_xml=false
-  path_option='--directory'
+    is_xml=false
+    path_option='--directory'
 fi
 
 # we could do "$path_option $PWD "
@@ -60,16 +77,17 @@ fi
 # would it make sens to create man pages only for certain refentries
 # e.g. for tools
 if $is_xml; then
-  # see http://bugzilla.gnome.org/show_bug.cgi?id=467488
-  @XSLTPROC@ $path_arg --nonet --xinclude \
-      --stringparam gtkdoc.bookname $module \
-      --stringparam gtkdoc.version "@VERSION@" \
-      manpages/docbook.xsl $document || exit $?
+    # see http://bugzilla.gnome.org/show_bug.cgi?id=467488
+    @XSLTPROC@ $path_arg --nonet --xinclude \
+        --stringparam gtkdoc.bookname $module \
+        --stringparam gtkdoc.version "@VERSION@" \
+        --stringparam chunk.quietly $quiet \
+        manpages/docbook.xsl $document || exit $?
 else
-  for i in `cd sgml;ls *.sgml`; do
-    j=`echo $i | sed 's/.sgml/.man/'`
-    echo ": converting " $i $j
-    docbook-to-man sgml/$i > man/$j 2> man/$j.log
-  done
+    for i in `cd sgml;ls *.sgml`; do
+        j=`echo $i | sed 's/.sgml/.man/'`
+        echo ": converting " $i $j
+        docbook-to-man sgml/$i > man/$j 2> man/$j.log
+    done
 fi
 
diff --git a/gtkdoc-mkpdf.in b/gtkdoc-mkpdf.in
index eaf53fc..9c0a31f 100644
--- a/gtkdoc-mkpdf.in
+++ b/gtkdoc-mkpdf.in
@@ -1,8 +1,19 @@
 #!/bin/sh
 #
 
-usage="\
-Usage: gtkdoc-mkpdf [--path=SEARCH_PATH] [--imgdir=DIR] MODULE DRIVER_FILE [BACKEND_OPTIONS...]"
+usage() {
+cat <<EOF
+gtkdoc-mkpdf version @VERSION@ - generate documentation in pdf format
+
+--verbose               Print extra output while processing
+--path=SEARCH_PATH      Extra source directories
+--imgdir=DIR            Extra image directories
+MODULE                  Name of the doc module being parsed
+DRIVER_FILE             File containing the toplevel DocBook file.
+--version               Print the version of this program
+--help                  Print this help
+EOF
+}
 
 #echo "args $0\n";
 
@@ -13,24 +24,26 @@ cleanexit() {
 
 # parse options, ignore unknown options for future extensions
 
+verbose="0"
 searchpath=
 uninstalled=no
 imgdirs=
 while true; do
     case "X$1" in
         X--version) echo "@VERSION@"; exit 0;;
-        X--help) echo "$usage"; exit 0;;
+        X--help) usage; exit 0;;
         X--uninstalled) uninstalled=yes; shift;;
+        X--verbose) verbose="1"; shift;;
         X--path=*) searchpath=`echo $1 | sed s/.*=//`; shift;;
         X--imgdir=*) imgdirs="$imgdirs -I `echo $1 | sed s/.*=//`"; shift;;
         X--*) shift;;
         X*) break;;
     esac
 done
- 
+
 if test $# -lt 2; then
-      echo "${usage}" 1>&2
-      exit 1
+    usage 1>&2
+    exit 1
 fi
 
 module=$1
@@ -38,6 +51,11 @@ shift
 document=$1
 shift
 
+quiet="1"
+if test $verbose = "1"; then
+    quiet="0"
+fi
+
 if test $uninstalled = yes; then
       # this does not work from buiddir!=srcdir
       # we could try this
@@ -52,11 +70,11 @@ else
 fi
 
 if head -n 1 $document | grep "<?xml" > /dev/null; then
-  is_xml=true
-  path_option='--path'
+    is_xml=true
+    path_option='--path'
 else
-  is_xml=false
-  path_option='--directory'
+    is_xml=false
+    path_option='--directory'
 fi
 
 # we could do "$path_option $PWD "
@@ -70,30 +88,34 @@ fi
 
 if $is_xml; then
   if test -n "@DBLATEX@"; then
-    # extra options to consider
-    # -I FIG_PATH
-    # -V is useful for debugging
-    # -T db2latex : different style
-    # -d : keep transient files (for debugging)
-    # xsltproc is already called with --xinclude
-    # does not work: --xslt-opts "$path_arg --nonet $@"
-    #echo "calling: @DBLATEX@ -o $module.pdf $imgdirs $document"
-    @DBLATEX@ 2>&1 -o $module.pdf $imgdirs $document | \
-      grep -v "not supported in programlisting or screen"
+      # extra options to consider
+      # -I FIG_PATH
+      # -V is useful for debugging
+      # -T db2latex : different style
+      # -d : keep transient files (for debugging)
+      # xsltproc is already called with --xinclude
+      # does not work: --xslt-opts "$path_arg --nonet $@"
+      #echo "calling: @DBLATEX@ -o $module.pdf $imgdirs $document"
+      if test $verbose = "0"; then
+        @DBLATEX@ 2>&1 >/dev/null -o $module.pdf $imgdirs $document | grep -v 'programlisting or screen'
+      else
+        { @DBLATEX@ 2>&1 >&3 -o $module.pdf $imgdirs $document | grep -v 'programlisting or screen' >&2; } 3>&1
+      fi
   else
     if test -n "@FOP@"; then
-      @XSLTPROC@ $path_arg --nonet --xinclude \
-          --stringparam gtkdoc.bookname $module \
-          --stringparam gtkdoc.version "@VERSION@" \
-          "$@" -o $module.fo $gtkdocdir/gtk-doc-fo.xsl $document || cleanexit $?
-      # fop dies too easily :(
-      # @FOP@ $module.fo $module.pdf
+        @XSLTPROC@ $path_arg --nonet --xinclude \
+            --stringparam gtkdoc.bookname $module \
+            --stringparam gtkdoc.version "@VERSION@" \
+            --stringparam chunk.quietly $quiet \
+            "$@" -o $module.fo $gtkdocdir/gtk-doc-fo.xsl $document || cleanexit $?
+        # fop dies too easily :(
+        # @FOP@ $module.fo $module.pdf
     fi
   fi
 else
-  # not very good output
-  # also for xxx-docs.sgml it will produce xxx-docs.pdf
-  docbook2pdf -e no-valid $document
+    # not very good output
+    # also for xxx-docs.sgml it will produce xxx-docs.pdf
+    docbook2pdf -e no-valid $document
 fi
 
 echo "timestamp" > pdf.stamp