From a7c09cba098dd0140b0ba0336cd05ece2c8dfcf0 Mon Sep 17 00:00:00 2001 From: Di-an Jan Date: Thu, 20 Nov 2008 12:36:30 -0800 Subject: [PATCH] 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 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. --- ChangeLog | 15 ++++++++++++++ build-aux/cross-options.pl | 41 ++++++++++++++++++++++++++++---------- doc/bison.texinfo | 9 ++++----- doc/local.mk | 3 ++- src/getargs.c | 5 +++++ src/scan-gram.l | 7 +++++++ 6 files changed, 64 insertions(+), 16 deletions(-) diff --git a/ChangeLog b/ChangeLog index 93561b02..3b3ac267 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,18 @@ +2008-11-20 Di-an Jan + + 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 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 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 () { 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. */ + { "%binary" return PERCENT_NONASSOC; -- 2.45.2