[SCM] GNU shishi branch, master, updated. shishi-1-0-2-26-gcad1c16

[Mats Erik Andersson]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU shishi".

http://git.savannah.gnu.org/cgit/shishi.git/commit/?id=cad1c16b23b8532e58213f1de60f3174653fdfa1

The branch, master has been updated
       via  cad1c16b23b8532e58213f1de60f3174653fdfa1 (commit)
       via  97e00e3fab60fa855a4e8714df7e1a96307c56a8 (commit)
       via  39ea98c9e0f99cd8a6b1eb6edda7f36423549446 (commit)
      from  6e9c754d175e4a99c07e826d134bd7428cad0013 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit cad1c16b23b8532e58213f1de60f3174653fdfa1
Author: Mats Erik Andersson <address@hidden>
Date:   Tue Jun 17 23:00:31 2014 +0200

    gdoc: Document this tool using POD.

commit 97e00e3fab60fa855a4e8714df7e1a96307c56a8
Author: Mats Erik Andersson <address@hidden>
Date:   Mon Jun 16 23:12:46 2014 +0200

    gdoc: Common corner cases with HTML and SGML.
    
    Insertion of XML marks introduces recurring problems
    during HTML and DOCBOOK production. In addition,
    ampersands must be escaped.

commit 39ea98c9e0f99cd8a6b1eb6edda7f36423549446
Author: Mats Erik Andersson <address@hidden>
Date:   Mon Jun 16 22:40:12 2014 +0200

    gdoc: Handle options with Getopt::Long.

-----------------------------------------------------------------------

Summary of changes:
 doc/gdoc |  404 +++++++++++++++++++++++++++++++++++++++++++++++++++----------
 1 files changed, 337 insertions(+), 67 deletions(-)

diff --git a/doc/gdoc b/doc/gdoc
index 4307013..e764c5c 100755
--- a/doc/gdoc
+++ b/doc/gdoc
@@ -133,7 +133,9 @@ eval '(exit $?0)' && eval 'exec perl -S "$0" ${1+"$@"}'
 # 3. xxx\: with xxx:
 
 # XXX: Migrate to strict code with warnings.
-#      Possibly rewrite with Getopt::Long.
+
+use Getopt::Long;
+use Pod::Usage;
 
 use POSIX qw(strftime);
 
@@ -148,6 +150,8 @@ $type_env =  '(\$\w+)';
 # Output conversion substitutions.
 #  One for each output format
 
+my @known_modes = qw/ docbook html man sgml tex texinfo text /;
+
 # these work fairly well
 %highlights_html = ( $type_constant => "<i>\$1</i>",
                     $type_func =>      "<b>\$1</b>",
@@ -201,11 +205,6 @@ sub usage {
     exit 1;
 }
 
-# read arguments
-if ($#ARGV==-1) {
-    usage();
-}
-
 $verbose = 0;
 $output_mode = "man";
 %highlights = %highlights_man;
@@ -216,63 +215,56 @@ $function_only = 0;
 
 my $lineprefix = "";
 
-while ($ARGV[0] =~ m/^-(.*)/) {
-    $cmd = shift @ARGV;
-    if ($cmd eq "-html") {
-       $output_mode = "html";
-       %highlights = %highlights_html;
-       $blankline = $blankline_html;
-    } elsif ($cmd eq "-man") {
-       $output_mode = "man";
-       %highlights = %highlights_man;
-       $blankline = $blankline_man;
-    } elsif ($cmd eq "-tex") {
-       $output_mode = "tex";
-       %highlights = %highlights_tex;
-       $blankline = $blankline_tex;
-    } elsif ($cmd eq "-texinfo") {
-       $output_mode = "texinfo";
-       %highlights = %highlights_texinfo;
-       $blankline = $blankline_texinfo;
-    } elsif ($cmd eq "-text") {
-       $output_mode = "text";
-       %highlights = %highlights_text;
-       $blankline = $blankline_text;
-    } elsif ($cmd eq "-docbook") {
-       $output_mode = "sgml";
-       %highlights = %highlights_sgml;
-       $blankline = $blankline_sgml;
-    } elsif ($cmd eq "-listfunc") {
-       $output_mode = "listfunc";
-    } elsif ($cmd eq "-module") { # not needed for sgml, inherits from calling 
document
-       $modulename = shift @ARGV;
-    } elsif ($cmd eq "-sourceversion") {
-       $sourceversion = shift @ARGV;
-    } elsif ($cmd eq "-include") {
-       $include = shift @ARGV;
-    } elsif ($cmd eq "-includefuncprefix") {
-       $includefuncprefix = 1;
-    } elsif ($cmd eq "-bugsto") {
-       $bugsto = shift @ARGV;
-    } elsif ($cmd eq "-pkg-name") {
-       $pkgname = shift @ARGV;
-    } elsif ($cmd eq "-copyright") {
-       $copyright = shift @ARGV;
-    } elsif ($cmd eq "-verbatimcopying") {
-       $verbatimcopying = 1;
-    } elsif ($cmd eq "-seeinfo") {
-       $seeinfo = shift @ARGV;
-    } elsif ($cmd eq "-function") { # to only output specific functions
-       $function_only = 1;
-       $function = shift @ARGV;
-       $function_table{$function} = 1;
-    } elsif ($cmd eq "-v") {
-       $verbose++;
-    } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
-       usage();
-    }
+my $scanned_file;      # Presently active source file.
+
+##
+# Option handling and helpers.
+#
+sub set_output_mode {
+    my ($name, $mode) = @_;
+
+    $mode = $name      unless grep m/^$mode$/, @known_modes;
+
+    $mode = "sgml"     if $mode eq "docbook";
+
+    # Pass the selected mode to state parameters.
+    $output_mode = $mode;
+    eval "\%highlights = \%highlights_$mode";
+    eval "\$blankline = \$blankline_$mode";
 }
 
+my %opts = ( # Output modes
+       "docbook|sgml"  => \&set_output_mode,
+       "listfunc"      => sub { $output_mode = "listfunc" },
+       "html"          => \&set_output_mode,
+       "man"           => \&set_output_mode,
+       "mode=s"        => \&set_output_mode,
+       "tex"           => \&set_output_mode,
+       "texinfo"       => \&set_output_mode,
+       "text"          => \&set_output_mode,
+       # Parameter settings
+       "bugsto=s"      => \$bugsto,
+       "copyright=s"   => \$copyright,
+       "function=s"    => sub { $function = $_[1];
+                                $function_only = 1;
+                                $function_table{$function} = 1;
+                              },
+       "include=s"     => \$include,
+       "includefuncprefix+" => \$includefuncprefix,
+       "module=s"      => \$modulename, # No effect in SGML mode.
+       "pkg-name=s"    => \$pkgname,
+       "seeinfo=s"     => \$seeinfo,
+       "sourceversion=s" => \$sourceversion,
+       "verbatimcopying+" => \$verbatimcopying,
+       "verbose|v+"    => \$verbose,
+       # Help and usage.
+       # Legacy response to '-h' was like the present '-usage'.
+       "usage|h"       => sub { pod2usage( -exitval => 0,
+                                           -verbose => 0 ) },
+       "help|?"        => sub { pod2usage( -exitval => 0,
+                                           -verbose => 1 ) },
+    );
+
 ##
 # dumps section contents to arrays/hashes intended for that purpose.
 #
@@ -322,7 +314,13 @@ sub repstr {
 
     my $return;
 
-    eval "\$return = qq/$output/";
+    # Try two different quoting forms to circumvent collisions.
+    # The standard delimiter '/' corrupts end marks in HTML and XML.
+    if ($output =~ m/]/) {
+       eval "\$return = qq#$output#";          # Is '|' any safer?
+    } else {
+       eval "\$return = qq[$output]";
+    }
 
     if ($verbose > 1) {
        print STDERR "Pattern $pattern matched with \$1='$match1' \$2='$match2' 
\$3='$match3' \$4='$match4'\n",
@@ -411,7 +409,7 @@ sub output_html {
     my %args = %{$_[0]};
     my ($parameter, $section);
     my $count;
-    print "\n\n<a name=\"". $args{'function'} . 
"\">&nbsp</a><h2>Function</h2>\n";
+    print "\n\n<a name=\"". $args{'function'} . 
"\">&nbsp;</a><h2>Function</h2>\n";
 
     print "<i>".$args{'functiontype'}."</i>\n";
     print "<b>".$args{'function'}."</b>\n";
@@ -437,7 +435,11 @@ sub output_html {
     foreach $section (@{$args{'sectionlist'}}) {
        print "<h3>$section</h3>\n";
        print "<ul>\n";
-       output_highlight($args{'sections'}{$section});
+
+       # Escape all ampersands before displaying.
+       my $text = just_highlight($args{'sections'}{$section});
+       $text =~ s|&|\&amp;|g;
+       print "$text";
        print "</ul>\n";
     }
     print "<hr>\n";
@@ -540,6 +542,8 @@ sub output_sgml {
     $id = $args{'module'}."-".$args{'function'};
     $id =~ s/[^A-Za-z0-9]/-/g;
 
+    print "<!--\n\t Generated by gdoc from $scanned_file.\n-->\n";
+
     print "<refentry>\n";
     print "<refmeta>\n";
     print "<refentrytitle><phrase 
id=\"$id\">".$args{'function'}."</phrase></refentrytitle>\n";
@@ -604,7 +608,10 @@ sub output_sgml {
        if ($section =~ m/EXAMPLE/i) {
            print "<example><para>\n";
        }
-       output_highlight($args{'sections'}{$section});
+       # Escape all ampersands.
+       my $text = just_highlight($args{'sections'}{$section});
+       $text =~ s|&|\&amp;|g;
+       print "$text";
 #      print "</para>";
        if ($section =~ m/EXAMPLE/i) {
            print "</para></example>\n";
@@ -612,7 +619,7 @@ sub output_sgml {
        print " </para>\n</refsect1>\n";
     }
 
-    print "\n\n";
+    print "</refentry>\n\n";
 }
 
 ##
@@ -817,6 +824,15 @@ sub dump_function {
 # 1 - looking for function name
 # 2 - scanning field start.
 # 3 - scanning prototype.
+
+# read arguments
+if ($#ARGV==-1) {
+    pod2usage( -exitval => 1, -verbose => 0, -output => \*STDERR);
+}
+
+GetOptions(%opts)
+    or pod2usage( -exitval => 1, -verbose => 0, -output => \*STDERR);
+
 $state = 0;
 $section = "";
 
@@ -840,11 +856,14 @@ $section_default = "Description"; # default section
 $section = $section_default;
 
 $lineno = 0;
-foreach $file (@ARGV) {
+foreach my $file (@ARGV) {
     if (!open(IN,"<$file")) {
        print STDERR "Error: Cannot open file $file\n";
        next;
     }
+
+    $scanned_file = $file;
+
     while (<IN>) {
        $lineno++;
 
@@ -936,3 +955,254 @@ foreach $file (@ARGV) {
        }
     }
 }
+
+__END__
+
+=pod
+
+=head1 NAME
+
+gdoc - Generate documentation from source code.
+
+=head1 SYNOPSIS
+
+ gdoc [ -docbook | -html | -listfunc | -sgml | -tex |
+        -texinfo | -text | -mode=MODE ]
+      [ -v ] [ -function funcname [ -function funcname ...] ]
+      file ...  >  outputfile
+
+ gdoc [ -v ] [ -man ]
+      [ -include file | -includefuncprefix ]
+      [ -seeinfo infonode ] [ -sourceversion verno ]
+      [ -copyright notice ] [ -verbatimcopying ]
+      [ -bugsto address ] [ -pkg-name packagename ]
+      [ -function funcname [ -function funcname ...] ]
+      file ...  >  outputfile
+
+ gdoc [ -h | --usage ] [ -? | --help ]
+
+=head1 DESCRIPTION
+
+Read one or more C source code files and scan for embedded comments
+in the style of Gnome comments.
+The output format can be set to a handful modes, but the default
+is the standard Unix man page.
+
+Package specific information can be inserted, and output may be
+limited to a subset of the available function within a particular
+set of files.
+
+When multiple functions are being documented, the output text is a
+simple concatenation of the text for each individual function.
+This must be taken into account with the more complex output modes.
+
+All expected output goes to F<stdout>, while errors go
+to F<stderr>.
+
+=head1 OPTIONS
+
+=over 8
+
+=item B<-function> I<NAME>
+
+If set, then generate documentation only for the given function.
+Other functions are ignored.
+
+Multiple use is allowed, thus making extraction of function
+subsets feasible, at least by scripting.
+
+=item B<-v>, B<-verbose>
+
+Print some internal messages for tracking.
+
+=back
+
+The next few options are output mode selectors.
+
+=over 8
+
+=item B<-docbook>, B<-sgml>
+
+Two synonyms for Docbook formatted output, producing one
+I<refentry> block for each selected function.
+Some tweeking may be needed in corner cases.
+
+=item B<-html>
+
+A fragment containing the full function description.
+Editing is recommended for use with multiple functions.
+
+=item B<-listfunc>
+
+A pseudo format intended as a tool:
+On separate lines, the names of each function being documented
+in each source file, are listed.
+
+=item B<-man>
+
+Produce a man page.
+This is the default format when no selection is indicated at all.
+
+=item B<-mode> I<MODE>
+
+Select any mode among the explicit alternatives described here.
+
+=item B<-tex>
+
+Output is written in the typesetting language LaTeX.
+
+=item B<-texinfo>
+
+The Texinfo format of the GNU Project.
+
+=item B<-text>
+
+Plain text formatting.
+
+=back
+
+Finally, a set of options relevant in man page mode only.
+
+=over 8
+
+=item B<-bugsto> I<ADDRESS>
+
+Include a section about bug reporting and mention
+the given e-mail address as the desired recipient, e.g,
+'address@hidden'.
+
+=item B<-copyright> I<TEXT>
+
+Add a copyright section with the stated text inserted
+after a standard preamble.
+A typical notice could be '2003 Barac Uda'.
+
+=item B<-include> F<FILE>
+
+Mention C<#include E<lt>FILE.hE<gt>> within the synopsis.
+
+=item B<-includefuncprefix>
+
+Mention an include directive of F<FILE.h> in the synopsis.
+Now I<FILE> is derived from the function prefix.
+As an example, a function I<gss_init_sec_context> will generate
+an include statement C<#include E<lt>gss.hE<gt>>.
+
+=item B<-pkg-name> I<NAME>
+
+As a refinement when also B<-bugsto> is in use, include a URL
+to the the project's home page, and prepend I<NAME>.
+As an example, "GNU Shishi".
+
+=item B<-seeinfo> I<INFO-NODE>
+
+Include, in the man page, a section that points to
+a Tex info manual at I<INFO-NODE> for further information.
+
+=item B<-sourceversion> I<STRING>
+
+Version number of source code, e.g. '1.0.4'.
+This is put in the man page header, defaulting
+to the current date when not made explicit.
+
+=item B<-verbatimcopying>
+
+Used in addition to B<-copyright>, a licensing statement is added,
+stating that I<verbatim copying> is a permitted use of the
+formatted text.
+
+=back
+
+=head1 FORMATTING OF COMMENTS
+
+The comments in source code must obey a preset structure
+in order to be detected by B<gdoc>.
+Their elements are somewhat tersely conveyed here.
+
+A comment block commences with C</**> and ends with C<**/>,
+or with the normal C<*/> as is standard in B<C> source.
+The following template displays all elements, and will be
+complemented by examples in the next section.
+
+In the following template, the notation C<(...)?> denotes
+an optional construct (to be placed in the ellipse).
+In contrast, C<(...)*> denotes a construct present zero
+or more times.
+Both are standard notions in most kinds of regular expressions.
+
+   /**
+    * function_name(:)? (- short description)?
+   (* @parameterx: (description of parameter x)?)*
+   (* a blank line)?
+    * (Description:)? (Description of function)?
+    * (Section header: (section description)? )*
+    (*)?*/
+
+Descriptions are allowed to be multiline, the only exception
+being the I<short description>.
+
+In addition to separating the comment into functional parts,
+the descriptive text is processed further by a scanner,
+which is looking for the following special patterns.
+
+   funcname()    -- name of a function,
+   #struct_name  -- name of a structure,
+   @parameter    -- name of a parameter,
+   %CONST        -- name of a constant,
+   $ENVVAR       -- environmental variable (OBSOLETE!).
+
+The lexical tokens thus identified are then highlighted
+as is appropriate for the chosen output mode.
+
+=head1 EXAMPLE OF COMMENTS
+
+The minimal comment is obvious:
+
+   /**
+    * my_function
+    **/
+
+A more useful form names one argument and a description:
+
+   /**
+    * my_function - does my stuff
+    * @my_arg: it is mine for sure
+    * Description: My stuff explained.
+    */
+
+Should the header tag I<Description:> be omitted, then a blank
+line is mandatory after the last parameter specification:
+
+   /**
+    * my_function - does my stuff
+    * @my_arg: it is still mine
+    *
+    * My stuff explained.
+    */
+
+=head1 CAVEATS
+
+Most of the output modes produce a usable and conformant document
+for a single function only, since multiple functions lead to simple
+concatenation of the individual documents.
+
+=head1 AUTHORS
+
+Michael Zucchi wrote the first implementation.
+Nikos Mavrogiannopoulos added the LaTex mode.
+Simon Josefsson added Tex info mode, I<listfunc> mode,
+and improved the man page formatter.
+Mats Erik Andersson wrote POD and went bug hunting.
+
+=head1 COPYRIGHT
+
+Copyright (c) 1998 Michael Zucchi
+              2001, 2002 Nikos Mavrogiannopoulos
+              2002-2013 Simon Josefsson
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+=cut


hooks/post-receive
-- 
GNU shishi