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

Tom Tromey
2018-11-28T00:14:55Z

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(+)

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
--
2.17.2