Re: dircolors database documentation

[Jim Meyering]

Eric Blake <address@hidden> wrote:
> Now that my copyright papers are finally in the mail, I can contribute
> this for eventual inclusion!

Great!

> I am not very experienced with texinfo yet,
> +lines containing a keyword and argument, separated by whitespace.  A #

Please use @samp{#}, so it renders as `#'.
[same for `.' and `*' below.]

> +character starts a comment anywhere in the line, except inside of a .
> +or * keyword.  Blank lines are ignored, and whitespace is ignored at
> +the beginning of a line and prior to a comment or line end.  There is
> +no way to quote whitespace.
> +
> +It is an error if a keyword does not contain an argument, or if an
> +unrecognized keyword is encountered.  Except for . and * keywords,
> +case is ignored when recognizing keywords, although the keywords are
> +usually written in uppercase.
> +
> +Most arguments are color descriptions, strings that are echoed
> +verbatim inside of a terminal escape sequence.  Most terminals these
> +days recognize @acronym{ANSI} color sequences.  @acronym{ANSI} color
> +sequences are a semicolon-separated list of numbers.  The font
> +attributes can be set with 0=none, 1=bold, 4=underscore, 5=blink,

These literals need some mark-up.
I'm inclined to use @code, so these show up in a fixed width font:

  @code{0=none}, @code{1=bold}, ...

I prefer @code over @samp here, since these are sort of program-like
elements, and especially since there are so many, we avoid all of the
quotes we'd get with @samp.  These days, I tend to use @samp almost
exclusively for single-character literals, but I see that the style used
in coreutils.texi is not uniform.  Take your pick.

> +7=reverse, and 8=concealed.  The foreground colors can be set with
> +30=black, 31=red, 32=green, 33=yellow, 34=blue, 35=magenta, 36=cyan,
> +and 37=white.  The background colors can be set with 40=black, 41=red,
> +42=green, 43=yellow, 44=blue, 45=magenta, 46=cyan, and 47=white.  For
> +example, on a terminal that recognizes @acronym{ANSI} colors, the line
> +``DIR 01;34'' would set the color of directory entries to a bold blue
> +on the default background.
> +
> +The database is divided into a series of terminal descriptions.  Each
> +terminal description begins with one or more TERM lines, followed by

@code{TERM}

> +any number of non-TERM lines that will apply to any of the terminal
> +types mentioned in the TERM lines.  This capability allows a single
> +database to specify different escape codes for different terminals, by
> +using multiple terminal descriptions.  A terminal type can be named in
> +more than one terminal section; the effect is cumulative.  If more
> +than one rule applies to a file, the last one specified takes
> +precedence.
> +
> +The following keywords are recognized.
> +
> address@hidden @samp
> address@hidden .<string>
> +A suffix pattern-matching rule, equivalent to *.<string>.  For
> +example, @samp{.tar 01;31} will color files that match *.tar with a
> +bright red foreground.
> +
> address@hidden *<string>
> +A pattern-matching rule.  The entire keyword, including the leading *,
> +is treated as a shell glob, case sensitively.  Files that match the

s/Files/File names/

> +glob will be colored by this rule.  There are no default
> +pattern-matching rules in ls, so you must use dircolors to get
> +pattern-matching.
> +
> address@hidden BLK
> address@hidden BLOCK
> +The color string for block special devices.  If not specified, ls
> +defaults this category to @samp{01;33}.
> +
> address@hidden CHAR
> address@hidden CHR
> +The color string for character special devices.  If not specified, ls
> +defaults this category to @samp{01;33}.
> +
> address@hidden COLOR
> +Ignored for compatibility.  Instead, to turn ls coloring on when

Please use @command{ls} everywhere.

> +stdout is a terminal, you should use a shell alias for ls that
> +includes '--color=auto'.

Use @option here:
  includes @option{--color=auto}.

> address@hidden DIR
> +The color string for directories that are not sticky (+t) and not
> +world-writable (o+w).  If not specified, ls defaults this category to
> address@hidden;34}.
> +
> address@hidden DOOR
> +The color string for doors, on systems that support this file type.
> +If not specified, ls defaults this category to @samp{01;35}.
> +
> address@hidden EIGHTBIT
> +Ignored for compatibility.  GNU ls is eight-bit clean by default, but
> +you may need to change your shell settings.  You may also be
> +interested in adding the --quoting-style argument in your alias for

@option, again

> +ls.
> +
> address@hidden END
> address@hidden ENDCODE
> +The string to use to reset the terminal to normal coloration.  If not
> +specified, ls uses the sequence LEFT, NORM, RIGHT.

Use @code (or @samp) for these:
  specified, ls uses the sequence @code{LEFT}, @code{NORM}, @code{RIGHT}.

etc...