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.
2026-03-09 04:13:03 +00:00 · 2008-11-20 12:36:30 -08:00
parent 6c88b51e83
commit a7c09cba09
6 changed files with 64 additions and 16 deletions
--- a/15
+++ b/15
@@ -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.
--- 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";
 }
--- 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

--- 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)

--- 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\
--- 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;