terminal-colors.d: (man) do not show 'type' as an optional part

That is: remove the square brackets from around 'type' in the synopsis.

Also, do not give the impression that a leading dot by itself is fine
before the 'type'.  That is: a dot is required only when 'name' and/or
'@term' is present.

Also, do not colorize the square brackets as if they were part of the
placeholders.  (And use ++double plus++ passthroughs for the opening
square brackets, to prevent asciidoctor from misinterpreting them.)

Indent the list of file types, for clarity.

And correct or improve some wordings, and remove an inconvenient
blank line in an example.

Signed-off-by: Benno Schulenberg <bensberg@telfort.nl>

diff --git a/lib/terminal-colors.d.5.adoc b/lib/terminal-colors.d.5.adoc
index 40ed8b96600b223cfd71aa46b3063326724f3eca..9704fe413d4e61bac64a22e6550f6954d580fe84 100644 (file)
--- a/lib/terminal-colors.d.5.adoc
+++ b/lib/terminal-colors.d.5.adoc
@@ -21,7 +21,7 @@ terminal-colors.d - configure output colorization for various utilities
 
 == SYNOPSIS
 
-/etc/terminal-colors.d/_[[name][@term].][type]_
+*/etc/terminal-colors.d/*++[++_name_**.**|++[++_name_]**@**_term_**.**]_type_
 
 == DESCRIPTION
 
@@ -32,14 +32,14 @@ The _name_ is a utility name. The name is optional and when none is specified th
 The _term_ is a terminal identifier (the *TERM* environment variable). The terminal identifier is optional and when none is specified then the file is used for all unspecified terminals.
 
 The _type_ is a file type. Supported file types are:
-
+____
 *disable*::
 Turns off output colorization for all compatible utilities. See also the NO_COLOR environment variable below.
 *enable*::
 Turns on output colorization; any matching *disable* files are ignored.
-
 *scheme*::
 Specifies colors used for output. The file format may be specific to the utility, the default format is described below.
+____
 
 If there are more files that match for a utility, then the file with the more specific filename wins. For example, the filename "@xterm.scheme" has less priority than "dmesg@xterm.scheme". The lowest priority are those files without a utility name and terminal identifier (e.g., "disable").
 
@@ -56,15 +56,15 @@ The _name_ is a logical name for the color sequence (for example: *error*).
 The names are specific to the utilities. For more details always see
 the *COLORS* section in the man page for the utility.
 
-The _color-sequence_ is a color name, ASCII color sequences, or escape sequences.
+The _color-sequence_ can be a color name, an ANSI color sequence, or an escape sequence.
 
 === Color names
 
-black, blink, blue, bold, brown, cyan, darkgray, gray, green, halfbright, lightblue, lightcyan, lightgray, lightgreen, lightmagenta, lightred, magenta, red, reset, reverse, and yellow.
+Valid color names are: black, blink, blue, bold, brown, cyan, darkgray, gray, green, halfbright, lightblue, lightcyan, lightgray, lightgreen, lightmagenta, lightred, magenta, red, reset, reverse, and yellow.
 
 === ANSI color sequences
 
-The color sequences are composed of sequences of numbers separated by semicolons. The most common codes are:
+An ANSI color sequence is composed of sequences of numbers separated by semicolons. The most common codes are:
 ____
      0   to restore default color
      1   for brighter colors
@@ -94,7 +94,7 @@ For example, to use a red background for alert messages in the output of *dmesg*
 
 === Escape sequences
 
-An escape sequence is necessary to enter a space, backslash, caret, or any
+An escape sequence is needed to enter a space, backslash, caret, or any
 control character anywhere in a string, as well as a hash mark as the first
 character. These C-style backslash-escapes can be used:
 
@@ -137,31 +137,27 @@ _$HOME/.config/terminal-colors.d_
 
 _/etc/terminal-colors.d_
 
-== EXAMPLE
+== EXAMPLES
 
 Disable colors for all compatible utilities:
-
 ____
 *touch /etc/terminal-colors.d/disable*
 ____
 
 Disable colors for all compatible utils on a vt100 terminal:
-
 ____
 *touch /etc/terminal-colors.d/@vt100.disable*
 ____
 
 Disable colors for all compatible utils except *dmesg*(1):
-
 ____
-*touch /etc/terminal-colors.d/disable*
-
+*touch /etc/terminal-colors.d/disable* +
 *touch /etc/terminal-colors.d/dmesg.enable*
 ____
 
 == COMPATIBILITY
 
-The *terminal-colors.d* functionality is currently supported by all util-linux utilities which provides colorized output. For more details always see the *COLORS* section in the man page for the utility.
+The *terminal-colors.d* functionality is currently supported by all util-linux utilities which provide colorized output. For more details always see the *COLORS* section in the man page for the utility.
 
 include::man-common/bugreports.adoc[]