Re: dircolors database documentation

[Eric Blake]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

According to Jim Meyering on 10/17/2005 11:02 AM:
> 
>>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.]

Comments addressed.  Try 2:

>>+the beginning of a line and prior to a comment or line end.  There is
>>+no way to quote whitespace.

Turns out I was wrong.  Escape sequences exist, so I documented them (and
\_ is a clever way to get space).

> 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}, ...

Since it is the number, and not its value, that appears in the color code,
I tried this instead:
  @code{0} none, @code{1} bold, ...

>>+The database is divided into a series of terminal descriptions.  Each
>>+terminal description begins with one or more TERM lines, followed by

And I documented globals before the first TERM line, that apply regardless
of $TERM.

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

I was wrong again - it is pure suffix matching and not globbing going on.

>>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}.

You know, since dircolors already outputs shell-specific information, it
wouldn't be too hard to make "COLORS auto" add
alias ls='ls --color=auto' (for -b)
alias ls 'ls --color=auto' (for -c)

along with everything else it outputs.  But I'll leave that up to you.


ChangeLog
2005-10-17  Eric Blake  <address@hidden>

        * src/dcgen: Strip comments, now that documentation is in place.
        * src/dircolors.c (usage): Mention new documentation.

doc/ChangeLog
2005-10-17  Eric Blake  <address@hidden>

        * coreutils.texi (ls invocation): Document LS_COLORS affect in
        --color.
        (dircolors database format): New section.

- --
Life is short - so eat dessert first!

Eric Blake             address@hidden
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org

iD8DBQFDVHQ384KuGfSFAYARAnp8AKCyoGQUEltD2SP8IDLDFez2vWSy2wCggvK2
JxOK5XfKS84gRuBQeLllrDU=
=sccb
-----END PGP SIGNATURE-----

Index: src/dcgen
===================================================================
RCS file: /cvsroot/coreutils/coreutils/src/dcgen,v
retrieving revision 1.8
diff -u -p -r1.8 dcgen
--- src/dcgen   5 Sep 2005 15:06:37 -0000       1.8
+++ src/dcgen   18 Oct 2005 04:01:17 -0000
@@ -39,6 +39,7 @@ my @line;
 while (<>)
   {
     chomp;
+    s/[[:blank:]]*#.*//;
     s/[[:blank:]]+/ /g;
     $_
       and push @line, $_;
Index: src/dircolors.c
===================================================================
RCS file: /cvsroot/coreutils/coreutils/src/dircolors.c,v
retrieving revision 1.93
diff -u -p -r1.93 dircolors.c
--- src/dircolors.c     24 Sep 2005 13:40:50 -0000      1.93
+++ src/dircolors.c     18 Oct 2005 04:01:17 -0000
@@ -98,7 +98,7 @@ usage (int status)
 {
   if (status != EXIT_SUCCESS)
     fprintf (stderr, _("Try `%s --help' for more information.\n"),
-             program_name);
+            program_name);
   else
     {
       printf (_("Usage: %s [OPTION]... [FILE]\n"), program_name);
@@ -116,7 +116,7 @@ Determine format of output:\n\
 \n\
 If FILE is specified, read it to determine which colors to use for which\n\
 file types and extensions.  Otherwise, a precompiled database is used.\n\
-For details on the format of these files, run `dircolors --print-database'.\n\
+For details on the format of these files, run `info dircolors'.\n\
 "), stdout);
       printf (_("\nReport bugs to <%s>.\n"), PACKAGE_BUGREPORT);
     }
Index: doc/coreutils.texi
===================================================================
RCS file: /cvsroot/coreutils/coreutils/doc/coreutils.texi,v
retrieving revision 1.289
diff -u -p -r1.289 coreutils.texi
--- doc/coreutils.texi  16 Oct 2005 07:27:04 -0000      1.289
+++ doc/coreutils.texi  18 Oct 2005 04:01:20 -0000
@@ -278,6 +278,7 @@ Directory listing
 * dir invocation::              Briefly list directory contents
 * vdir invocation::             Verbosely list directory contents
 * dircolors invocation::        Color setup for @command{ls}
+* dircolors database format::   Input for dircolors
 
 @command{ls}:  List directory contents
 
@@ -4558,7 +4559,7 @@ c
 $ paste num2 let3
 1       a
 2       b
-        c
+       @ c
 @end example
 
 Synopsis:
@@ -5235,6 +5236,7 @@ and @command{vdir}, which list informati
 * dir invocation::              Briefly ls.
 * vdir invocation::             Verbosely ls.
 * dircolors invocation::        Color setup for ls, etc.
+* dircolors database format::   Input for dircolors.
 @end menu
 
 
@@ -5820,8 +5822,11 @@ possible in the fewest lines.
 @item --color address@hidden
 @opindex --color
 @cindex color, distinguishing file types with
-Specify whether to use color for distinguishing file types.  @var{when}
-may be omitted, or one of:
+Specify whether to use color for distinguishing file types.  If the
+environment variable @env{LS_COLORS} is set, the color scheme is
+parsed from that variable; otherwise, ls comes with a builtin default
+color scheme.  For more details on setting @env{LS_COLORS}, see
address@hidden invocation}.  @var{when} may be omitted, or one of:
 @itemize @bullet
 @item none
 @vindex none @r{color option}
@@ -6202,8 +6207,9 @@ eval "`dircolors address@hidden@dots{} [
 
 If @var{file} is specified, @command{dircolors} reads it to determine which
 colors to use for which file types and extensions.  Otherwise, a
-precompiled database is used.  For details on the format of these files,
-run @samp{dircolors --print-database}.
+precompiled database is used, whose contents are visible by running
address@hidden --print-database}.  For details on the format of these
+files, see @ref{dircolors database format}.
 
 @vindex LS_COLORS
 @vindex SHELL @r{environment variable, and color}
@@ -6246,12 +6252,215 @@ Output C shell commands.  This is the de
 @cindex database for color setup, printing
 @cindex printing color database
 Print the (compiled-in) default color configuration database.  This
-output is itself a valid configuration file, and is fairly descriptive
-of the possibilities.
+output is itself a valid configuration file, although it is rather
+compact.
 
 @end table
 
 @exitstatus
+
+
address@hidden dircolors database format
address@hidden @command{dircolors} database format: Input for 
@command{dircolors}
+
address@hidden dircolors file format
address@hidden input format, dircolors
address@hidden format, dircolors input file
address@hidden parses a database to determine the color
+configuration that is appropriate for the current @env{TERM}.  It
+consists of a series of lines containing a keyword and argument,
+separated by whitespace.  A @samp{#} character starts a comment
+anywhere in the line, except inside of a @samp{.} or @samp{*} suffix
+keyword.  Blank lines are ignored, and whitespace is ignored at the
+beginning of a line and prior to a comment or line end.
+
+It is an error if a keyword does not contain an argument, or if an
+unrecognized keyword is encountered.  Except for @samp{.} and @samp{*}
+suffix keywords, case is ignored when recognizing keywords, although
+the keywords are usually written in uppercase.
+
+In arguments and suffix keywords, the following backslash escape
+sequences are recognized: @samp{\nnn} octal notation, @samp{\xnn} and
address@hidden hex notation, @samp{\a} for bell, @samp{\b} for backspace,
address@hidden for escape, @samp{\f} for form feed, @samp{\n} for newline,
address@hidden for carriage return, @samp{\t} for tab, @samp{\v} for
+vertical tab, @samp{\?} for delete, @samp{\_} for space, and
+everything else (including @samp{\} and @samp{^}) represents itself.
+Also, control sequences are recognized with caret escape sequences,
+such as @samp{^m} or @samp{^M} for carriage return in an
address@hidden environment.  Since trailing whitespace and comments
+are ignored, you must use escape sequences to represent some patterns.
+
+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 @code{0} none, @code{1} bold, @code{4}
+underscore, @code{5} blink, @code{7} reverse, and @code{8} concealed.
+The foreground colors can be set with @code{30} black, @code{31} red,
address@hidden green, @code{33} yellow, @code{34} blue, @code{35} magenta,
address@hidden cyan, and @code{37} white.  The background colors can be set
+with @code{40} black, @code{41} red, @code{42} green, @code{43}
+yellow, @code{44} blue, @code{45} magenta, @code{46} cyan, and
address@hidden white.  For example, on a terminal that recognizes
address@hidden colors, the line @code{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.  Every
+line before the first @code{TERM} line is global, and applies
+regardless of the current @env{TERM} environment setting.  Beyond
+that, each terminal description section begins with one or more
address@hidden lines, followed by any number of address@hidden lines
+that will apply only to any of the terminal types mentioned in the
address@hidden 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 rule, equivalent to @code{*.<string>}.  For example,
address@hidden 01;31} will color file names that end in @code{.tar} with a
+bright red foreground on an @acronym{ANSI} system.  Applies only to
+files that fit in the @code{FILE} category.
+
address@hidden *<string>
+A suffix rule.  Everything following the leading @samp{*} is treated
+as a suffix to compare against file names that fit in the @code{FILE}
+category, case sensitively.  There are no default suffix rules in
address@hidden, so you must use @command{dircolors} to get coloration
+based on suffix.
+
address@hidden BLK
address@hidden BLOCK
+The color string for block special devices.  If not specified,
address@hidden defaults this category to @samp{01;33}.
+
address@hidden CHAR
address@hidden CHR
+The color string for character special devices.  If not specified,
address@hidden defaults this category to @samp{01;33}.
+
address@hidden COLOR
+Ignored for compatibility.  Instead, to turn @command{ls} coloring on
+when stdout is a terminal, you should use a shell alias for
address@hidden that 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, @command{ls} defaults this
+category to @samp{01;34}.
+
address@hidden DOOR
+The color string for doors, on systems that support this file type.
+If not specified, @command{ls} defaults this category to @samp{01;35}.
+
address@hidden EIGHTBIT
+Ignored for compatibility.  GNU @command{ls} is eight-bit clean by
+default, but you may need to change your shell settings.  You may also
+be interested in adding the @option{--quoting-style} argument in your
+alias for @command{ls}.
+
address@hidden END
address@hidden ENDCODE
+The string to use to reset the terminal to normal coloration.  If not
+specified, @command{ls} uses the sequence @code{LEFT}, @code{NORM},
address@hidden
+
address@hidden EXEC
+The color string for executable files.  If not specified, @command{ls}
+defaults this category to @samp{01;32}.
+
address@hidden FIFO
address@hidden PIPE
+The color string for pipes (named fifos).  If not specified,
address@hidden defaults this category to @samp{33}.
+
address@hidden FILE
+The color string for files that do not fit any of the other categories
+or string matching rules.  If not specified, @command{ls} defaults
+this category to @samp{0}.  Suffix rules only apply to files that
+would otherwise receive @code{FILE} coloring.
+
address@hidden LEFT
address@hidden LEFTCODE
+The string that begins a terminal escape sequence.  If not specified,
address@hidden defaults this to @samp{\033[}.
+
address@hidden LINK
address@hidden LNK
address@hidden SYMLINK
+The color string for symbolic links, or the special argument
address@hidden to set the color according to the file type the symbolic
+link points to.  If set to target, then the @code{MISSING} category
+determines the color of broken symlinks.  If not specified,
address@hidden defaults this category to @samp{01;36}.
+
address@hidden MISSING
+The color string for broken symlinks, when @code{LINK} is set to
address@hidden  If not specified, @command{ls} reuses the @code{FILE}
+specification.
+
address@hidden NORM
address@hidden NORMAL
+The color string for restoring the terminal color sequence to normal.
+If not specified, @command{ls} defaults this category to @samp{0}.
+
address@hidden OPTIONS
+Ignored for compatibility.  Instead, if you want options to be added
+by default to @command{ls} when invoked from the command line,
+consider using a shell alias for @command{ls}.
+
address@hidden ORPHAN
+The color string for a broken (orphaned) symlink.  If not specified,
address@hidden reuses the @code{LINK} specification.
+
address@hidden OTHER_WRITABLE
address@hidden OWR
+The color string for directories that are world-writable (o+w,-t).  If
+not specified, @command{ls} defaults this category to @samp{34;42}.
+
address@hidden RIGHT
address@hidden RIGHTCODE
+The string that ends a terminal escape sequence.  If not specified,
address@hidden defaults this to @samp{m}.
+
address@hidden SETGID
address@hidden SGID
+The color string for a setgid (g+s) file.  If not specified,
address@hidden defaults this category to @samp{30;43}.
+
address@hidden SETUID
address@hidden SUID
+The color string for a setuid (u+s) file.  If not specified,
address@hidden defaults this category to @samp{37;41}.
+
address@hidden SOCK
+The color string for sockets.  If not specified, @command{ls} defaults
+this category to @samp{01;35}.
+
address@hidden STICKY
+The color string for directories with only the sticky bit set
+(+t,o-w).  If not specified, @command{ls} defaults this category to
address@hidden;42}.
+
address@hidden STICKY_OTHER_WRITABLE
address@hidden OWT
+The color string for directories with both the sticky bit set and
+world-writable (+t,o+w).  If not specified, @command{ls} defaults this
+category to @samp{30;42}.
+
address@hidden TERM
+Add a terminal type to the current terminal description, beginning a
+new terminal description if the previous line was not a @code{TERM}
+line.  If the environment variable @env{TERM} matches the argument of
+the @code{TERM} keyword, then the current description affects the
+output.
+
address@hidden table
 
 
 @node Basic operations