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/Makefile.am (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 20:33:03 +00:00 · 2008-11-20 12:36:30 -08:00
parent e80b068ce1
commit 72183df4da
6 changed files with 66 additions and 18 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/Makefile.am (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.
+
 2009-02-25  Akim Demaille  <demaille@gostai.com>

 	Copyright years.
--- 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,6 +30,7 @@ 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]}].
@@ -33,19 +40,33 @@ while (<>)
 	      $long_arg = "[$long_arg]";
 	      $arg = "[$arg]";
 	    }
-	    $option{"$long$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$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/Makefile.am
+++ b/doc/Makefile.am
@@ -28,7 +28,8 @@ CROSS_OPTIONS_PL = $(top_srcdir)/build-aux/cross-options.pl
 $(srcdir)/cross-options.texi: $(top_srcdir)/src/getargs.c $(CROSS_OPTIONS_PL)
 	-rm -f $@ $@.tmp
 	cd $(top_builddir)/src && $(MAKE) $(AM_MAKEFLAGS) bison
-	$(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 = $(srcdir)/cross-options.texi

--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -7941,7 +7941,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}
@@ -7950,7 +7950,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.
@@ -7963,12 +7963,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/src/getargs.c
+++ b/src/getargs.c
@@ -246,6 +246,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
@@ -1,7 +1,7 @@
 /* Bison Grammar Scanner                             -*- C -*-

-   Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation,
-   Inc.
+   Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software
+   Foundation, Inc.

   This file is part of Bison, the GNU Compiler Compiler.

@@ -152,6 +152,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;