[RFAv2,4/4] Document in NEWS and gdb.texinfo the "help", "apropos" and "show style" changes.
Commit Message
---
gdb/ChangeLog | 5 +++++
gdb/NEWS | 30 ++++++++++++++++++++++++++
gdb/doc/ChangeLog | 6 ++++++
gdb/doc/gdb.texinfo | 52 +++++++++++++++++++++++++++++++++++++++++++--
4 files changed, 91 insertions(+), 2 deletions(-)
Comments
> From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Cc: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Date: Sat, 1 Jun 2019 23:23:31 +0200
>
> ---
> gdb/ChangeLog | 5 +++++
> gdb/NEWS | 30 ++++++++++++++++++++++++++
> gdb/doc/ChangeLog | 6 ++++++
> gdb/doc/gdb.texinfo | 52 +++++++++++++++++++++++++++++++++++++++++++--
> 4 files changed, 91 insertions(+), 2 deletions(-)
This part is OK, with one comment:
> +@smallexample
> +@c @group
> +taas -- Apply a command to all threads (ignoring errors and empty output).
> +Usage: taas COMMAND
> +shortcut for 'thread apply all -s COMMAND'
> +
> +tfaas -- Apply a command to all frames of all threads (ignoring errors and empty output).
This will most probably produce an overfull line, suggest to break
into two lines.
Btw, why did you comment out @group..@end group?
On Sun, 2019-06-02 at 05:38 +0300, Eli Zaretskii wrote:
> > From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> > Cc: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> > Date: Sat, 1 Jun 2019 23:23:31 +0200
> >
> > ---
> > gdb/ChangeLog | 5 +++++
> > gdb/NEWS | 30 ++++++++++++++++++++++++++
> > gdb/doc/ChangeLog | 6 ++++++
> > gdb/doc/gdb.texinfo | 52 +++++++++++++++++++++++++++++++++++++++++++--
> > 4 files changed, 91 insertions(+), 2 deletions(-)
>
> This part is OK, with one comment:
>
> > +@smallexample
> > +@c @group
> > +taas -- Apply a command to all threads (ignoring errors and empty output).
> > +Usage: taas COMMAND
> > +shortcut for 'thread apply all -s COMMAND'
> > +
> > +tfaas -- Apply a command to all frames of all threads (ignoring errors and empty output).
>
> This will most probably produce an overfull line, suggest to break
> into two lines.
Done.
>
> Btw, why did you comment out @group..@end group?
That was a copy/paste of what was just before, I have uncommented
both group instructions.
Thanks for the review
Philippe
@@ -7142,3 +7142,8 @@ End:
(print_help_for_command): Style the command name using title style.
* cli/cli-cmds.c (apropos_command): Parse optional -v flag.
(_initialize_cli_cmds): Describe -v in apropos_command help.
+
+2019-05-31 Philippe Waroquiers <philippe.waroquiers@skynet.be>
+
+ * NEWS: Mention the new set|show style [title|highlight].
+ Mention changes to "show style", "help" and "apropos".
@@ -69,6 +69,36 @@ set logging debugredirect [on|off]
By default, GDB debug output will go to both the terminal and the logfile.
Set if you want debug output to go only to the log file.
+set style title foreground COLOR
+set style title background COLOR
+set style title intensity VALUE
+ Control the styling of titles.
+
+set style highlight foreground COLOR
+set style highlight background COLOR
+set style highlight intensity VALUE
+ Control the styling of highlightings.
+
+* Changed commands
+
+help
+ The "help" command uses the title style to enhance the
+ readibility of its output by styling the classes and
+ command names.
+
+apropos [-v] REGEXP
+ Similarly to "help", the "apropos" command also uses the
+ title style for the command names. "apropos" accepts now
+ a flag "-v" (verbose) to show the full documentation
+ of matching commands and to use the highlight style to mark
+ the documentation parts matching REGEXP.
+
+show style
+ The "show style" and its subcommands are now styling
+ a style name in their output using its own style, to help
+ the user visualize the different styles.
+
+
* New MI commands
-complete
@@ -12875,3 +12875,9 @@ fill-column: 74
version-control: never
coding: utf-8
End:
+
+2019-05-31 Philippe Waroquiers <philippe.waroquiers@skynet.be>
+
+ * gdb.texinfo (Help): Document the new -v apropos flag.
+ (Output Styling): Document the style name styling done by "show style".
+ Document the new title and highlight styles.
@@ -1895,10 +1895,13 @@ With a command name as @code{help} argument, @value{GDBN} displays a
short paragraph on how to use that command.
@kindex apropos
-@item apropos @var{args}
+@item apropos [-v] @var{regexp}
The @code{apropos} command searches through all of the @value{GDBN}
commands, and their documentation, for the regular expression specified in
-@var{args}. It prints out all matches found. For example:
+@var{args}. It prints out all matches found. The optional flag @samp{-v},
+which stands for @samp{verbose}, indicates to output the full documentation
+of the matching commands and highlight the parts of the documentation
+matching @var{regexp}. For example:
@smallexample
apropos alias
@@ -1917,6 +1920,29 @@ delete -- Delete some breakpoints or auto-display expressions
@c @end group
@end smallexample
+@noindent
+while
+
+@smallexample
+apropos -v cut.*thread apply
+@end smallexample
+
+@noindent
+results in the below output, where @samp{cut for 'thread apply}
+is highlighted if styling is enabled.
+
+@smallexample
+@c @group
+taas -- Apply a command to all threads (ignoring errors and empty output).
+Usage: taas COMMAND
+shortcut for 'thread apply all -s COMMAND'
+
+tfaas -- Apply a command to all frames of all threads (ignoring errors and empty output).
+Usage: tfaas COMMAND
+shortcut for 'thread apply all -s frame apply all -s COMMAND'
+@c @end group
+@end smallexample
+
@kindex complete
@item complete @var{args}
The @code{complete @var{args}} command lists all the possible completions
@@ -24784,6 +24810,11 @@ Set the intensity to @var{value}. Valid intensities are @samp{normal}
(the default), @samp{bold}, and @samp{dim}.
@end table
+The @code{show style} command and its subcommands are styling
+a style name in their output using its own style.
+So, use @command{show style} to see the complete list of styles,
+their characteristics and the visual aspect of each style.
+
The style-able objects are:
@table @code
@item filename
@@ -24804,6 +24835,23 @@ foreground color is cyan.
Control the styling of addresses. These are managed with the
@code{set style address} family of commands. By default, this style's
foreground color is blue.
+
+@item title
+Control the styling of titles. These are managed with the
+@code{set style title} family of commands. By default, this style's
+intensity is bold. Commands are using the title style to improve
+the readibility of large output. For example, the commands
+@command{apropos} and @command{help} are using the title style
+for the command names.
+
+@item highlight
+Control the styling of highlightings. These are managed with the
+@code{set style highlight} family of commands. By default, this style's
+foreground color is red. Commands are using the highlight style to draw
+the user attention to some specific parts of their output. For example,
+the command @command{apropos -v REGEXP} uses the highlight style to
+mark the documentation parts matching @var{regexp}.
+
@end table
@node Numbers