[16/16] Document the "set style" commands

Message ID 20181128001435.12703-17-tom@tromey.com
State New
Headers show
Series
  • Add styling to the gdb CLI and TUI
Related show

Commit Message

Tom Tromey Nov. 28, 2018, 12:14 a.m.
This documents the new "set style" commands.

gdb/ChangeLog
2018-11-27  Tom Tromey  <tom@tromey.com>

	* NEWS: Mention terminal styling.

gdb/doc/ChangeLog
2018-11-27  Tom Tromey  <tom@tromey.com>

	* gdb.texinfo (Output Styling): New node.
---
 gdb/ChangeLog       |  4 +++
 gdb/NEWS            | 30 +++++++++++++++++++
 gdb/doc/ChangeLog   |  4 +++
 gdb/doc/gdb.texinfo | 72 +++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 110 insertions(+)

-- 
2.17.2

Comments

Eli Zaretskii Nov. 28, 2018, 6:51 a.m. | #1
> From: Tom Tromey <tom@tromey.com>

> Cc: Tom Tromey <tom@tromey.com>

> Date: Tue, 27 Nov 2018 17:14:35 -0700

> 

> +For example, the style of file names can be controlled using the

> +@code{set style filename} group of commands:

> +

> +@table @code

> +@kindex set style filename background

> +@item set style filename background @var{color}

> +Set the background to @var{color}.  Valid colors are @samp{none}

> +(meaning the terminal's default color), @samp{black}, @samp{red},

> +@samp{green}, @samp{yellow}, @samp{vlue}, @samp{magenta}, @samp{cyan},

> +and@samp{white}.

> +

> +@kindex set style filename foreground

> +@item set style filename foreground @var{color}

> +Set the foreground to @var{color}.  Valid colors are @samp{none}

> +(meaning the terminal's default color), @samp{black}, @samp{red},

> +@samp{green}, @samp{yellow}, @samp{vlue}, @samp{magenta}, @samp{cyan},

> +and@samp{white}.

> +

> +@kindex set style filename intensity

> +@item set style filename intensity @var{value}

> +Set the intensity to @var{value}.  Valid intensities are @samp{normal}

> +(the default), @samp{bold}, and @samp{dim}.

> +@end table

> +

> +The style-able objects are:

> +@table @code

> +@kindex set style filename

> +@item filename

> +Control the styling of file names.

> +

> +@kindex set style function

> +@item function

> +Control the styling of function names.  These are managed with the

> +@code{set style function} family of commands.

> +

> +@kindex set style variable

> +@item variable

> +Control the styling of variable names.  These are managed with the

> +@code{set style variable} family of commands.

> +

> +@kindex set style address

> +@item address

> +Control the styling of addresses.  These are managed with the

> +@code{set style address} family of commands.

> +@end table


The text is OK, but you have numerous "set style" index entries that
all start with the same substring and will point to almost the same
page.  This is not useful, IME.  I suggest just a single index entry
about "set style" instead.

Thanks.
Tom Tromey Dec. 28, 2018, 7:19 p.m. | #2
>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:


Eli> The text is OK, but you have numerous "set style" index entries that
Eli> all start with the same substring and will point to almost the same
Eli> page.  This is not useful, IME.  I suggest just a single index entry
Eli> about "set style" instead.

I've made this change.

Tom

Patch

diff --git a/gdb/NEWS b/gdb/NEWS
index 9ecbb83d99..a5e677bc84 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -40,6 +40,11 @@ 
 
 * The RISC-V target now supports target descriptions.
 
+* Terminal styling is now available for the CLI and the TUI.  GNU
+  Source Highlight can additionally be used to provide styling of
+  source code snippets.  See the "set style" commands, below, for more
+  information.
+
 * New targets
 
   NXP S12Z		s12z-*-elf
@@ -116,6 +121,31 @@  set tui tab-width NCHARS
 show tui tab-width NCHARS
   "set tui tab-width" replaces the "tabset" command, which has been deprecated.
 
+set style enabled [on|off]
+show style enabled
+  Enable or disable terminal styling.  Styling is enabled by default
+  on most hosts.
+
+set style filename foreground COLOR
+set style filename background COLOR
+set style filename intensity VALUE
+  Control the styling of file names.
+
+set style function foreground COLOR
+set style function background COLOR
+set style function intensity VALUE
+  Control the styling of function names.
+
+set style variable foreground COLOR
+set style variable background COLOR
+set style variable intensity VALUE
+  Control the styling of variable names.
+
+set style address foreground COLOR
+set style address background COLOR
+set style address intensity VALUE
+  Control the styling of addresses.
+
 * MI changes
 
   ** The '-data-disassemble' MI command now accepts an '-a' option to
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 7350d94573..4d7b085f35 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -24196,6 +24196,7 @@  described here.
 * Editing::                     Command editing
 * Command History::             Command history
 * Screen Size::                 Screen size
+* Output Styling::              Output styling
 * Numbers::                     Numbers
 * ABI::                         Configuring the current ABI
 * Auto-loading::                Automatically loading associated files
@@ -24503,6 +24504,77 @@  Options, -batch}) also automatically disables pagination.
 Show the current pagination mode.
 @end table
 
+@node Output Styling
+@section Output Styling
+@cindex styling
+@cindex colors
+
+@value{GDBN} can style its output on a capable terminal.  This is
+enabled by default on most systems.  Various style settings are
+available; and styles can also be disabled entirely.
+
+@table @code
+@kindex set style enabled
+@item set style enabled @samp{on|off}
+Enable or disable all styling.  The default is host-dependent, with
+most hosts defaulting to @samp{on}.
+
+@kindex show style enabled
+@item show style enabled
+Show the current state of styling.
+@end table
+
+Subcommands of @code{set style} control specific forms of styling.
+These subcommands all follow the same pattern: each style-able object
+can be styled with a foreground color, a background color, and an
+intensity.
+
+For example, the style of file names can be controlled using the
+@code{set style filename} group of commands:
+
+@table @code
+@kindex set style filename background
+@item set style filename background @var{color}
+Set the background to @var{color}.  Valid colors are @samp{none}
+(meaning the terminal's default color), @samp{black}, @samp{red},
+@samp{green}, @samp{yellow}, @samp{vlue}, @samp{magenta}, @samp{cyan},
+and@samp{white}.
+
+@kindex set style filename foreground
+@item set style filename foreground @var{color}
+Set the foreground to @var{color}.  Valid colors are @samp{none}
+(meaning the terminal's default color), @samp{black}, @samp{red},
+@samp{green}, @samp{yellow}, @samp{vlue}, @samp{magenta}, @samp{cyan},
+and@samp{white}.
+
+@kindex set style filename intensity
+@item set style filename intensity @var{value}
+Set the intensity to @var{value}.  Valid intensities are @samp{normal}
+(the default), @samp{bold}, and @samp{dim}.
+@end table
+
+The style-able objects are:
+@table @code
+@kindex set style filename
+@item filename
+Control the styling of file names.
+
+@kindex set style function
+@item function
+Control the styling of function names.  These are managed with the
+@code{set style function} family of commands.
+
+@kindex set style variable
+@item variable
+Control the styling of variable names.  These are managed with the
+@code{set style variable} family of commands.
+
+@kindex set style address
+@item address
+Control the styling of addresses.  These are managed with the
+@code{set style address} family of commands.
+@end table
+
 @node Numbers
 @section Numbers
 @cindex number representation