[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH 3/5] doc: put diagnostics related options together
|
From: |
Akim Demaille |
|
Subject: |
[PATCH 3/5] doc: put diagnostics related options together |
|
Date: |
Sun, 7 Jul 2019 08:12:15 +0200 |
* doc/bison.texi (Diagnostics): New section.
Move --warning, --color and --style there.
* src/getargs.c (usage): Likewise.
---
doc/bison.texi | 279 ++++++++++++++++++++++++++-----------------------
src/getargs.c | 27 +++--
2 files changed, 164 insertions(+), 142 deletions(-)
diff --git a/doc/bison.texi b/doc/bison.texi
index b3f85e16..0478d792 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -380,6 +380,7 @@ Invoking Bison
Bison Options
* Operation Modes:: Options controling the global behavior of
@command{bison}
+* Diagnostics:: Options controlling the diagnostics
* Tuning the Parser:: Options changing the generated parsers
* Output Files:: Options controling the output
@@ -10292,12 +10293,12 @@ are unique. When a long option takes an argument,
like
@samp{--file-prefix}, connect the option name and the argument with
@samp{=}.
-Here is a list of options that can be used with Bison, alphabetized by
-short option. It is followed by a cross key alphabetized by long
-option.
+Here is a list of options that can be used with Bison. It is followed by a
+cross key alphabetized by long option.
@menu
* Operation Modes:: Options controling the global behavior of
@command{bison}
+* Diagnostics:: Options controlling the diagnostics
* Tuning the Parser:: Options changing the generated parsers
* Output Files:: Options controling the output
@end menu
@@ -10305,6 +10306,8 @@ option.
@node Operation Modes
@subsection Operation Modes
+Options controling the global behavior of @command{bison}.
+
@c Please, keep this ordered as in 'bison --help'.
@table @option
@item -h
@@ -10358,6 +10361,140 @@ exp:;
See the documentation of @option{--feature=fixit} below for more details.
+@item -f [@var{feature}]
+@itemx --feature[=@var{feature}]
+Activate miscellaneous @var{feature}s. @var{Feature} can be one of:
+@table @code
+@item caret
+@itemx diagnostics-show-caret
+Show caret errors, in a manner similar to GCC's
+@option{-fdiagnostics-show-caret}, or Clang's
+@option{-fcaret-diagnostics}. The location provided with the message is used
+to quote the corresponding line of the source file, underlining the
+important part of it with carets (@samp{^}). Here is an example, using the
+following file @file{in.y}:
+
+@example
+%type <ival> exp
+%%
+exp: exp '+' exp @{ $exp = $1 + $2; @};
+@end example
+
+When invoked with @option{-fcaret} (or nothing), Bison will report:
+
+@example
+@group
+in.y:3.20-23: @derror{error}: ambiguous reference: '$exp'
+ 3 | exp: exp '+' exp @{ @derror{$exp} = $1 + $2; @};
+ | @derror{^~~~}
+@end group
+@group
+in.y:3.1-3: refers to: $exp at $$
+ 3 | @dnotice{exp}: exp '+' exp @{ $exp = $1 + $2; @};
+ | @dnotice{^~~}
+@end group
+@group
+in.y:3.6-8: refers to: $exp at $1
+ 3 | exp: @dnotice{exp} '+' exp @{ $exp = $1 + $2; @};
+ | @dnotice{^~~}
+@end group
+@group
+in.y:3.14-16: refers to: $exp at $3
+ 3 | exp: exp '+' @dnotice{exp} @{ $exp = $1 + $2; @};
+ | @dnotice{^~~}
+@end group
+@group
+in.y:3.32-33: @derror{error}: $2 of 'exp' has no declared type
+ 3 | exp: exp '+' exp @{ $exp = $1 + @derror{$2}; @};
+ | @derror{^~}
+@end group
+@end example
+
+Whereas, when invoked with @option{-fno-caret}, Bison will only report:
+
+@example
+@group
+in.y:3.20-23: @derror{error}: ambiguous reference: '$exp'
+in.y:3.1-3: refers to: $exp at $$
+in.y:3.6-8: refers to: $exp at $1
+in.y:3.14-16: refers to: $exp at $3
+in.y:3.32-33: @derror{error}: $2 of 'exp' has no declared type
+@end group
+@end example
+
+This option is activated by default.
+
+@item fixit
+@itemx diagnostics-parseable-fixits
+Show machine-readable fixes, in a manner similar to GCC's and Clang's
+@option{-fdiagnostics-parseable-fixits}.
+
+Fix-its are generated for duplicate directives:
+
+@example
+@group
+$ @kbd{cat foo.y}
+%define api.prefix @{foo@}
+%define api.prefix @{bar@}
+%%
+exp:;
+@end group
+
+@group
+$ @kbd{bison -ffixit foo.y}
+foo.y:2.1-24: @derror{error}: %define variable 'api.prefix' redefined
+ 2 | @derror{%define api.prefix @{bar@}}
+ | @derror{^~~~~~~~~~~~~~~~~~~~~~~~}
+foo.y:1.1-24: previous definition
+ 1 | @dnotice{%define api.prefix @{foo@}}
+ | @dnotice{^~~~~~~~~~~~~~~~~~~~~~~~}
+fix-it:"foo.y":@{2:1-2:25@}:""
+foo.y: @dwarning{warning}: fix-its can be applied. Rerun with option
'--update'. [@dwarning{-Wother}]
+@end group
+@end example
+
+They are also generated to update deprecated directives, unless
+@option{-Wno-deprecated} was given:
+
+@example
+@group
+$ @kbd{cat /tmp/foo.yy}
+%error-verbose
+%name-prefix "foo"
+%%
+exp:;
+@end group
+@group
+$ @kbd{bison foo.y}
+foo.y:1.1-14: @dwarning{warning}: deprecated directive, use '%define
parse.error verbose' [@dwarning{-Wdeprecated}]
+ 1 | @dwarning{%error-verbose}
+ | @dwarning{^~~~~~~~~~~~~~}
+foo.y:2.1-18: @dwarning{warning}: deprecated directive, use '%define
api.prefix @{foo@}' [@dwarning{-Wdeprecated}]
+ 2 | @dwarning{%name-prefix "foo"}
+ | @dwarning{^~~~~~~~~~~~~~~~~~}
+foo.y: @dwarning{warning}: fix-its can be applied. Rerun with option
'--update'. [@dwarning{-Wother}]
+@end group
+@end example
+
+The fix-its are applied by @command{bison} itself when given the option
+@option{-u}/@option{--update}. See its documentation above.
+
+@item syntax-only
+Do not generate the output files. The name of this feature is somewhat
+misleading as more than just checking the syntax is done: every stage is run
+(including checking for conflicts for instance), except the generation of
+the output files.
+
+@end table
+@end table
+
+@node Diagnostics
+@subsection Diagnostics
+
+Options controlling the diagnostics.
+
+@c Please, keep this ordered as in 'bison --help'.
+@table @code
@item -W [@var{category}]
@itemx --warnings[=@var{category}]
Output warnings falling in @var{category}. @var{category} can be one
@@ -10512,7 +10649,10 @@ they are explicitly enabled by
@option{-Werror=@var{category}}.
Deactivate the error treatment for this @var{category}. However, the warning
itself won't be disabled, or enabled, by this option.
-@item --color[=@var{when}]
+@item --color
+Equivalent to @option{--color=always}.
+
+@item --color=@var{when}
Control whether diagnostics are colorized, depending on @var{when}:
@table @code
@item always
@@ -10528,7 +10668,6 @@ Disable colorized diagnostics.
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.
@end table
-@option{--color} is equivalent to @option{--color=always}.
@item --style=@var{file}
Specifies the CSS style @var{file} to use when colorizing. It has an effect
@@ -10536,137 +10675,13 @@ only when the @option{--color} option is effective.
The
@file{bison-default.css} file provide a good example from which to define
your own style file. See the documentation of libtextstyle for more
details.
-
-@item -f [@var{feature}]
-@itemx --feature[=@var{feature}]
-Activate miscellaneous @var{feature}s. @var{Feature} can be one of:
-@table @code
-@item caret
-@itemx diagnostics-show-caret
-Show caret errors, in a manner similar to GCC's
-@option{-fdiagnostics-show-caret}, or Clang's
-@option{-fcaret-diagnostics}. The location provided with the message is used
-to quote the corresponding line of the source file, underlining the
-important part of it with carets (@samp{^}). Here is an example, using the
-following file @file{in.y}:
-
-@example
-%type <ival> exp
-%%
-exp: exp '+' exp @{ $exp = $1 + $2; @};
-@end example
-
-When invoked with @option{-fcaret} (or nothing), Bison will report:
-
-@example
-@group
-in.y:3.20-23: @derror{error}: ambiguous reference: '$exp'
- 3 | exp: exp '+' exp @{ @derror{$exp} = $1 + $2; @};
- | @derror{^~~~}
-@end group
-@group
-in.y:3.1-3: refers to: $exp at $$
- 3 | @dnotice{exp}: exp '+' exp @{ $exp = $1 + $2; @};
- | @dnotice{^~~}
-@end group
-@group
-in.y:3.6-8: refers to: $exp at $1
- 3 | exp: @dnotice{exp} '+' exp @{ $exp = $1 + $2; @};
- | @dnotice{^~~}
-@end group
-@group
-in.y:3.14-16: refers to: $exp at $3
- 3 | exp: exp '+' @dnotice{exp} @{ $exp = $1 + $2; @};
- | @dnotice{^~~}
-@end group
-@group
-in.y:3.32-33: @derror{error}: $2 of 'exp' has no declared type
- 3 | exp: exp '+' exp @{ $exp = $1 + @derror{$2}; @};
- | @derror{^~}
-@end group
-@end example
-
-Whereas, when invoked with @option{-fno-caret}, Bison will only report:
-
-@example
-@group
-in.y:3.20-23: @derror{error}: ambiguous reference: ‘$exp’
-in.y:3.1-3: refers to: $exp at $$
-in.y:3.6-8: refers to: $exp at $1
-in.y:3.14-16: refers to: $exp at $3
-in.y:3.32-33: @derror{error}: $2 of ‘exp’ has no declared type
-@end group
-@end example
-
-This option is activated by default.
-
-@item fixit
-@itemx diagnostics-parseable-fixits
-Show machine-readable fixes, in a manner similar to GCC's and Clang's
-@option{-fdiagnostics-parseable-fixits}.
-
-Fix-its are generated for duplicate directives:
-
-@example
-@group
-$ @kbd{cat foo.y}
-%define api.prefix @{foo@}
-%define api.prefix @{bar@}
-%%
-exp:;
-@end group
-
-@group
-$ @kbd{bison -ffixit foo.y}
-foo.y:2.1-24: @derror{error}: %define variable 'api.prefix' redefined
- 2 | @derror{%define api.prefix @{bar@}}
- | @derror{^~~~~~~~~~~~~~~~~~~~~~~~}
-foo.y:1.1-24: previous definition
- 1 | @dnotice{%define api.prefix @{foo@}}
- | @dnotice{^~~~~~~~~~~~~~~~~~~~~~~~}
-fix-it:"foo.y":@{2:1-2:25@}:""
-foo.y: @dwarning{warning}: fix-its can be applied. Rerun with option
'--update'. [@dwarning{-Wother}]
-@end group
-@end example
-
-They are also generated to update deprecated directives, unless
-@option{-Wno-deprecated} was given:
-
-@example
-@group
-$ @kbd{cat /tmp/foo.yy}
-%error-verbose
-%name-prefix "foo"
-%%
-exp:;
-@end group
-@group
-$ @kbd{bison foo.y}
-foo.y:1.1-14: @dwarning{warning}: deprecated directive, use '%define
parse.error verbose' [@dwarning{-Wdeprecated}]
- 1 | @dwarning{%error-verbose}
- | @dwarning{^~~~~~~~~~~~~~}
-foo.y:2.1-18: @dwarning{warning}: deprecated directive, use '%define
api.prefix @{foo@}' [@dwarning{-Wdeprecated}]
- 2 | @dwarning{%name-prefix "foo"}
- | @dwarning{^~~~~~~~~~~~~~~~~~}
-foo.y: @dwarning{warning}: fix-its can be applied. Rerun with option
'--update'. [@dwarning{-Wother}]
-@end group
-@end example
-
-The fix-its are applied by @command{bison} itself when given the option
-@option{-u}/@option{--update}. See its documentation above.
-
-@item syntax-only
-Do not generate the output files. The name of this feature is somewhat
-misleading as more than just checking the syntax is done: every stage is run
-(including checking for conflicts for instance), except the generation of
-the output files.
-
-@end table
@end table
@node Tuning the Parser
@subsection Tuning the Parser
+Options changing the generated parsers.
+
@c Please, keep this ordered as in 'bison --help'.
@table @option
@item -t
@@ -10776,6 +10791,8 @@ is specified.
@node Output Files
@subsection Output Files
+Options controling the output.
+
@c Please, keep this ordered as in 'bison --help'.
@table @option
@item --defines[=@var{file}]
diff --git a/src/getargs.c b/src/getargs.c
index f68366e0..e0d647fe 100644
--- a/src/getargs.c
+++ b/src/getargs.c
@@ -365,9 +365,9 @@ Mandatory arguments to long options are mandatory for short
options too.\n\
fputs (_("\
The same is true for optional arguments.\n\
"), stdout);
+ putc ('\n', stdout);
fputs (_("\
-\n\
Operation Modes:\n\
-h, --help display this help and exit\n\
-V, --version output version information and exit\n\
@@ -376,13 +376,27 @@ 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\
+ -f, --feature[=FEATURES] activate miscellaneous features\n\
+\n\
+"), stdout);
+
+ argmatch_feature_usage (stdout);
+ putc ('\n', stdout);
+
+ fputs (_("\
+Diagnostics:\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\
- -f, --feature[=FEATURES] activate miscellaneous features\n\
\n\
"), stdout);
+ warning_usage (stdout);
+ putc ('\n', stdout);
+
+ argmatch_color_usage (stdout);
+ putc ('\n', stdout);
+
fputs (_("\
Tuning the Parser:\n\
-L, --language=LANGUAGE specify the output programming language\n\
@@ -416,18 +430,9 @@ Output Files:\n\
"), stdout);
putc ('\n', stdout);
- argmatch_color_usage (stdout);
- putc ('\n', stdout);
-
- warning_usage (stdout);
- putc ('\n', stdout);
-
argmatch_report_usage (stdout);
putc ('\n', stdout);
- argmatch_feature_usage (stdout);
- putc ('\n', stdout);
-
printf (_("Report bugs to <%s>.\n"), PACKAGE_BUGREPORT);
printf (_("%s home page: <%s>.\n"), PACKAGE_NAME, PACKAGE_URL);
fputs (_("General help using GNU software: "
--
2.22.0