[PATCH 2/5] doc: move -y's documentation into "Tuning the Parser"

[Akim Demaille]

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