From 4e3c6f59cc0bd747d0b3b26707e45addf09c5a8a Mon Sep 17 00:00:00 2001 From: Akim Demaille Date: Fri, 5 Jul 2019 18:48:25 +0200 Subject: [PATCH] doc: move -y's documentation into "Tuning the Parser" Let's clarify --help: use clearer "section" names, as in the doc. Move --yacc to where it belongs. * src/getargs.c (usage): Rename "Parser" as "Tuning the Parser", as in the doc. Rename "Output" as "Output Files" Move --yacc to "Tuning the Parser". * doc/bison.texi: Likewise. --- doc/bison.texi | 64 +++++++++++++++++++++++++------------------------- src/getargs.c | 8 +++---- 2 files changed, 36 insertions(+), 36 deletions(-) diff --git a/doc/bison.texi b/doc/bison.texi index 92254f9f..b3f85e16 100644 --- a/doc/bison.texi +++ b/doc/bison.texi @@ -381,7 +381,7 @@ Bison Options * Operation Modes:: Options controling the global behavior of @command{bison} * Tuning the Parser:: Options changing the generated parsers -* Adjust the Output:: Options controling the output +* Output Files:: Options controling the output Parsers Written In Other Languages @@ -5857,7 +5857,7 @@ states and what is done for each type of lookahead token in that state. @deffn {Directive} %yacc Pretend the option @option{--yacc} was given, i.e., imitate Yacc, including -its naming conventions. @xref{Bison Options}, for more. +its naming conventions. @xref{Tuning the Parser}, for more. @end deffn @@ -5882,7 +5882,7 @@ delimiters) denote finite choice (e.g., a variation of a feature). String values denote remaining cases (e.g., a file name). It is an error if a @var{variable} is defined by @code{%define} multiple -times, but see @ref{Bison Options,,@option{-D @var{name}[=@var{value}]}}. +times, but see @ref{Tuning the Parser,,@option{-D @var{name}[=@var{value}]}}. @end deffn The rest of this section summarizes variables and values that @code{%define} @@ -6779,7 +6779,7 @@ extern int cdebug; Prior to Bison 2.6, a feature similar to @code{api.prefix} was provided by the obsolete directive @code{%name-prefix} (@pxref{Table of Symbols, ,Bison -Symbols}) and the option @option{--name-prefix} (@pxref{Bison Options}). +Symbols}) and the option @option{--name-prefix} (@pxref{Output Files}). @node Interface @chapter Parser C-Language Interface @@ -9970,7 +9970,7 @@ compatibility with previous versions of Bison. @findex %define parse.trace Add the @samp{%define parse.trace} directive (@pxref{%define Summary,,parse.trace}), or pass the @option{-Dparse.trace} option -(@pxref{Bison Options}). This is a Bison extension, which is especially +(@pxref{Tuning the Parser}). This is a Bison extension, which is especially useful for languages that don't use a preprocessor. Unless POSIX and Yacc portability matter to you, this is the preferred solution. @end table @@ -10299,7 +10299,7 @@ option. @menu * Operation Modes:: Options controling the global behavior of @command{bison} * Tuning the Parser:: Options changing the generated parsers -* Adjust the Output:: Options controling the output +* Output Files:: Options controling the output @end menu @node Operation Modes @@ -10358,29 +10358,6 @@ exp:; See the documentation of @option{--feature=fixit} below for more details. -@item -y -@itemx --yacc -Act more like the traditional @command{yacc} command. This can cause -different diagnostics to be generated (it implies @option{-Wyacc}), and may -change behavior in other minor ways. Most importantly, imitate Yacc's -output file name conventions, so that the parser implementation file is -called @file{y.tab.c}, and the other outputs are called @file{y.output} and -@file{y.tab.h}. Also, if generating a deterministic parser in C, generate -@code{#define} statements in addition to an @code{enum} to associate token -numbers with token names. Thus, the following shell script can substitute -for Yacc, and the Bison distribution contains such a script for -compatibility with POSIX: - -@example -#! /bin/sh -bison -y "$@@" -@end example - -The @option{-y}/@option{--yacc} option is intended for use with traditional -Yacc grammars. If your grammar uses Bison extensions like -@samp{%glr-parser}, Bison might not be Yacc-compatible even if this option -is specified. - @item -W [@var{category}] @itemx --warnings[=@var{category}] Output warnings falling in @var{category}. @var{category} can be one @@ -10546,7 +10523,7 @@ Enable colorized diagnostics. @itemx no Disable colorized diagnostics. -@item auto @rm{(default)} +@item auto @r{(default)} @itemx tty Diagnostics will be colorized if the output device is a tty, i.e. when the output goes directly to a text screen or terminal emulator window. @@ -10771,10 +10748,33 @@ This is similar to how most shells resolve commands. @item -k @itemx --token-table Pretend that @code{%token-table} was specified. @xref{Decl Summary}. + +@item -y +@itemx --yacc +Act more like the traditional @command{yacc} command. This can cause +different diagnostics to be generated (it implies @option{-Wyacc}), and may +change behavior in other minor ways. Most importantly, imitate Yacc's +output file name conventions, so that the parser implementation file is +called @file{y.tab.c}, and the other outputs are called @file{y.output} and +@file{y.tab.h}. Also, if generating a deterministic parser in C, generate +@code{#define} statements in addition to an @code{enum} to associate token +numbers with token names. Thus, the following shell script can substitute +for Yacc, and the Bison distribution contains such a script for +compatibility with POSIX: + +@example +#! /bin/sh +bison -y "$@@" +@end example + +The @option{-y}/@option{--yacc} option is intended for use with traditional +Yacc grammars. If your grammar uses Bison extensions like +@samp{%glr-parser}, Bison might not be Yacc-compatible even if this option +is specified. @end table -@node Adjust the Output -@subsection Adjust the Output +@node Output Files +@subsection Output Files @c Please, keep this ordered as in 'bison --help'. @table @option diff --git a/src/getargs.c b/src/getargs.c index d87241c5..f68366e0 100644 --- a/src/getargs.c +++ b/src/getargs.c @@ -368,7 +368,7 @@ The same is true for optional arguments.\n\ fputs (_("\ \n\ -Operation modes:\n\ +Operation Modes:\n\ -h, --help display this help and exit\n\ -V, --version output version information and exit\n\ --print-localedir output directory containing locale-dependent data\n\ @@ -376,7 +376,6 @@ Operation modes:\n\ --print-datadir output directory containing skeletons and XSLT\n\ and exit\n\ -u, --update apply fixes to the source grammar file and exit\n\ - -y, --yacc emulate POSIX Yacc\n\ -W, --warnings[=CATEGORY] report the warnings falling in CATEGORY\n\ --color[=WHEN] whether to colorize the diagnostics\n\ --style=FILE specify the CSS FILE for colorizer diagnostics\n\ @@ -385,7 +384,7 @@ Operation modes:\n\ "), stdout); fputs (_("\ -Parser:\n\ +Tuning the Parser:\n\ -L, --language=LANGUAGE specify the output programming language\n\ -S, --skeleton=FILE specify the skeleton to use\n\ -t, --debug instrument the parser for tracing\n\ @@ -397,13 +396,14 @@ Parser:\n\ deprecated by '-Dapi.prefix=PREFIX'\n\ -l, --no-lines don't generate '#line' directives\n\ -k, --token-table include a table of token names\n\ + -y, --yacc emulate POSIX Yacc\n\ "), stdout); putc ('\n', stdout); /* Keep -d and --defines separate so that ../build-aux/cross-options.pl * won't assume that -d also takes an argument. */ fputs (_("\ -Output:\n\ +Output Files:\n\ --defines[=FILE] also produce a header file\n\ -d likewise but cannot specify FILE (for POSIX Yacc)\n\ -r, --report=THINGS also produce details on the automaton\n\