From: Di-an Jan <dianj@freeshell.org>
Date: Thu, 20 Nov 2008 20:36:30 +0000 (-0800)
Subject: 	Improves options in the manual.
X-Git-Tag: v2.7.90~1005
X-Git-Url: https://git.saurik.com/bison.git/commitdiff_plain/a7c09cba098dd0140b0ba0336cd05ece2c8dfcf0?hp=6c88b51e8395fe490c15ede2f1b2562258a4260d

	Improves options in the manual.
	* doc/bison.texinfo (-g, -x): Add space before argument.
	(Option Cross Key): Implement FIXME: listing directives also.
	* build-aux/cross-options.pl:  Read from <STDIN> rather than <>.
	(Short Option): Special case -d.  Put arguments inside @option.
	(Bison Directive): Add column, automatically extracted from
	src/scan-gram.l (actual name passed as the first argument)
	with special case for %define.
	* doc/local.mk (doc/cross-options.texi): Pass src/scan-gram.l
	to build-aux/cross-options.pl.
	* src/getargs.c (usage): Document limitations of cross-options.pl.
	* src/scan-gram.l: Likewise.
---

diff --git a/ChangeLog b/ChangeLog
index 93561b02..3b3ac267 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,18 @@
+2008-11-20  Di-an Jan  <dianj@freeshell.org>
+
+	Improves options in the manual.
+	* doc/bison.texinfo (-g, -x): Add space before argument.
+	(Option Cross Key): Implement FIXME: listing directives also.
+	* build-aux/cross-options.pl:  Read from <STDIN> rather than <>.
+	(Short Option): Special case -d.  Put arguments inside @option.
+	(Bison Directive): Add column, automatically extracted from 
+	src/scan-gram.l (actual name passed as the first argument)
+	with special case for %define.
+	* doc/local.mk (doc/cross-options.texi): Pass src/scan-gram.l
+	to build-aux/cross-options.pl.
+	* src/getargs.c (usage): Document limitations of cross-options.pl.
+	* src/scan-gram.l: Likewise.
+
 2008-11-18  Joel E. Denny  <jdenny@ces.clemson.edu>
 
 	Fix unexpanded macros in GLR defines file.
diff --git a/build-aux/cross-options.pl b/build-aux/cross-options.pl
index 2cec3696..478303d5 100755
--- a/build-aux/cross-options.pl
+++ b/build-aux/cross-options.pl
@@ -5,7 +5,10 @@ use 5.005;
 use strict;
 
 my %option;
-while (<>)
+my %directive;
+my $scanner = `grep -i '"%[a-z]' $ARGV[0]`;
+$scanner =~ s/"\[-_\]"/-/g;
+while (<STDIN>)
 {
     if (/^\s*             # Initial spaces.
         (?:(-\w),\s+)?    # $1: $short: Possible short option.
@@ -16,7 +19,10 @@ while (<>)
         /x)
     {
 	my ($short, $long, $opt, $arg) = ($1, $2, $3, $4);
-	$short = defined $short ? '@option{' . $short . '}' : '';
+	$short = '' if ! defined $short;
+	$short = '-d' if $long eq '--defines' && ! $short;
+	my $dir = '%' . substr($long, 2);
+	$dir = '' if index ($scanner, "\"$dir\"") < 0;
 	if ($arg)
 	{
             # if $opt, $arg contains the closing ].
@@ -24,25 +30,40 @@ while (<>)
                 if $opt eq '[';
 	    $arg =~ s/^=//;
             $arg = lc ($arg);
+	    my $dir_arg = $arg;
             # If the argument is compite (e.g., for --define[=NAME[=VALUE]]),
             # put each word in @var, to build @var{name}[=@var{value}], not
             # @var{name[=value]}].
 	    $arg =~ s/(\w+)/\@var{$1}/g;
 	    $arg = '[' . $arg . ']'
 		if $opt eq '[';
-	    $option{"$long=$arg"} = $short ? "$short $arg" : '';
-	}
-	else
-	{
-	    $option{"$long"} = "$short";
+	    # For arguments of directives: this only works if all arguments
+	    # are strings and have the same syntax as on the command line.
+	    if ($dir_arg eq 'name[=value]')
+	    {
+		$dir_arg = '@var{name} ["@var{value}"]';
+	    }
+	    else
+	    {
+		$dir_arg =~ s/(\w+)/\@var{"$1"}/g;
+		$dir_arg = '[' . $dir_arg . ']'
+		    if $opt eq '[';
+	    }
+	    $long = "$long=$arg";
+	    $short = "$short $arg" if $short && $short ne '-d';
+	    $dir = "$dir $dir_arg" if $dir;
 	}
+	$option{$long} = $short;
+	$directive{$long} = $dir;
     }
 }
 
 foreach my $long (sort keys %option)
 {
     # Avoid trailing spaces.
-    printf ("\@item %-40s \@tab%s\n",
-            '@option{' . $long . '}',
-            $option{$long} ? " $option{$long}" : "");
+    print '@item @option{', $long, "}\n\@tab";
+    print ' @option{', $option{$long}, '}' if $option{$long};
+    print "\n\@tab";
+    print ' @code{', $directive{$long}, '}' if $directive{$long};
+    print "\n";
 }
diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index f760c292..74685493 100644
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -8001,7 +8001,7 @@ Specify the @var{file} for the parser file.
 The other output files' names are constructed from @var{file} as
 described under the @samp{-v} and @samp{-d} options.
 
-@item -g[@var{file}]
+@item -g [@var{file}]
 @itemx --graph[=@var{file}]
 Output a graphical representation of the @acronym{LALR}(1) grammar
 automaton computed by Bison, in @uref{http://www.graphviz.org/, Graphviz}
@@ -8010,7 +8010,7 @@ automaton computed by Bison, in @uref{http://www.graphviz.org/, Graphviz}
 If omitted and the grammar file is @file{foo.y}, the output file will be
 @file{foo.dot}.
 
-@item -x[@var{file}]
+@item -x [@var{file}]
 @itemx --xml[=@var{file}]
 Output an XML report of the @acronym{LALR}(1) automaton computed by Bison.
 @code{@var{file}} is optional.
@@ -8023,12 +8023,11 @@ More user feedback will help to stabilize it.)
 @node Option Cross Key
 @section Option Cross Key
 
-@c FIXME: How about putting the directives too?
 Here is a list of options, alphabetized by long option, to help you find
 the corresponding short option.
 
-@multitable {@option{--defines=@var{defines-file}}} {@option{-b @var{file-prefix}XXX}}
-@headitem Long Option @tab Short Option
+@multitable {@option{--defines=@var{defines-file}}} {@option{-D @var{name}[=@var{value}]}} {@code{%nondeterministic-parser}}
+@headitem Long Option @tab Short Option @tab Bison Directive
 @include cross-options.texi
 @end multitable
 
diff --git a/doc/local.mk b/doc/local.mk
index d54952f0..a352459d 100644
--- a/doc/local.mk
+++ b/doc/local.mk
@@ -31,7 +31,8 @@ CROSS_OPTIONS_TEXI = $(top_srcdir)/doc/cross-options.texi
 $(CROSS_OPTIONS_TEXI): $(top_srcdir)/src/getargs.c $(CROSS_OPTIONS_PL)
 	-rm -f $@ $@.tmp
 	$(MAKE) $(AM_MAKEFLAGS) src/bison$(EXEEXT)
-	$(top_builddir)/src/bison --help | perl $(CROSS_OPTIONS_PL) >$@.tmp
+	$(top_builddir)/src/bison --help |				\
+	perl $(CROSS_OPTIONS_PL) $(top_srcdir)/src/scan-gram.l >$@.tmp
 	mv $@.tmp $@
 MAINTAINERCLEANFILES = $(CROSS_OPTIONS_TEXI)
 
diff --git a/src/getargs.c b/src/getargs.c
index 2a0611bc..aebc2401 100644
--- a/src/getargs.c
+++ b/src/getargs.c
@@ -248,6 +248,11 @@ usage (int status)
 	     program_name);
   else
     {
+      /* For ../build-aux/cross-options.pl to work, use the format:
+		^  -S, --long[=ARGS] (whitespace)
+	 A --long option is required.
+	 Otherwise, add exceptions to ../build-aux/cross-options.pl.  */
+
       printf (_("Usage: %s [OPTION]... FILE\n"), program_name);
       fputs (_("\
 Generate LALR(1) and GLR parsers.\n\
diff --git a/src/scan-gram.l b/src/scan-gram.l
index 5ef8edba..9a733bc1 100644
--- a/src/scan-gram.l
+++ b/src/scan-gram.l
@@ -157,6 +157,13 @@ splice	 (\\[ \f\t\v]*\n)*
   /*----------------------------.
   | Scanning Bison directives.  |
   `----------------------------*/
+
+  /* For directives that are also command line options, the regex must be
+	"%..."
+     after "[-_]"s are removed, and the directive must match the --long
+     option name, with a single string argument.  Otherwise, add exceptions
+     to ../build-aux/cross-options.pl.  */
+
 <INITIAL>
 {
   "%binary"                         return PERCENT_NONASSOC;