From 72183df4da75116a496099c856097f7f049b2d8a 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/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. --- ChangeLog | 15 ++++++++++++++ build-aux/cross-options.pl | 41 ++++++++++++++++++++++++++++---------- doc/Makefile.am | 3 ++- doc/bison.texinfo | 9 ++++----- src/getargs.c | 5 +++++ src/scan-gram.l | 11 ++++++++-- 6 files changed, 66 insertions(+), 18 deletions(-) diff --git a/ChangeLog b/ChangeLog index 50e8fba9..37dd3a6e 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/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 Copyright years. diff --git a/build-aux/cross-options.pl b/build-aux/cross-options.pl index 58772775..8d507254 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,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"; } diff --git a/doc/Makefile.am b/doc/Makefile.am index 36370fca..f5ff34b2 100644 --- 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 diff --git a/doc/bison.texinfo b/doc/bison.texinfo index 9d9fa3dc..110f580e 100644 --- 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 diff --git a/src/getargs.c b/src/getargs.c index 5601e981..9ffa4cf5 100644 --- 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\ diff --git a/src/scan-gram.l b/src/scan-gram.l index 697f52f0..292960cb 100644 --- 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. */ + { "%binary" return PERCENT_NONASSOC; -- 2.45.2