dircolors database documentation

[Eric Blake]

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

Now that my copyright papers are finally in the mail, I can contribute
this for eventual inclusion!  I am not very experienced with texinfo yet,
so I would appreciate a proofread (although I did validate that everything
looks readable in info).  When this is applied, we can (once again) patch
src/dcgen to strip comments from the built-in database.

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

        * coreutils.texi (ls invocation): Document effect of
        LS_COLORS on --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

iD8DBQFDU6P784KuGfSFAYARAn9KAKDTWn1hnMLQ7K5RV+wo7GU7TxvHjgCeJWGF
rUUzwef5iWKHzMLN6gqB+M0=
=OciN
-----END PGP SIGNATURE-----

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  17 Oct 2005 13:10:56 -0000
@@ -4558,7 +4558,7 @@ c
 $ paste num2 let3
 1       a
 2       b
-        c
+       @ c
 @end example
 
 Synopsis:
@@ -5235,6 +5235,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 +5821,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 +6206,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 +6251,193 @@ 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
+Dircolors 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 #
+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,
+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
+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
+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
+stdout is a terminal, you should use a shell alias for ls that
+includes '--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
+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.
+
address@hidden EXEC
+The color string for executable files.  If not specified, ls defaults
+this category to @samp{01;32}.
+
address@hidden FIFO
address@hidden PIPE
+The color string for pipes (named fifos).  If not specified, ls
+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, ls defaults
+this category to @samp{0}.
+
address@hidden LEFT
address@hidden LEFTCODE
+The string that begins a terminal escape sequence.  If not specified,
+ls defaults this to @samp{\033[}.
+
address@hidden LINK
address@hidden LNK
address@hidden SYMLINK
+The color string for symbolic links, or the special argument
+``target'' to set the color according to the file type the symbolic
+link points to.  If set to target, then the MISSING category
+determines the color of broken symlinks.  If not specified, ls
+defaults this category to @samp{01;36}.
+
address@hidden MISSING
+The color string for broken symlinks, when LINK is set to
+``target''.  If not specified, ls reuses the FILE specification.
+
address@hidden NORM
address@hidden NORMAL
+The color string for restoring the terminal color sequence to
+normal.  If not specified, ls defaults this category to @samp{0}.
+
address@hidden OPTIONS
+Ignored for compatibility.  Instead, if you want options to be added
+by default to ls when invoked from the command line, consider using a
+shell alias for ls.
+
address@hidden ORPHAN
+The color string for a broken (orphaned) symlink.  If not specified,
+ls reuses the LINK specification.
+
address@hidden OTHER_WRITABLE
address@hidden OWR
+The color string for directories that are world-writable (o+w,-t).
+If not specified, 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,
+ls defaults this to @samp{m}.
+
address@hidden SETGID
address@hidden SGID
+The color string for a setgid (g+s) file.  If not specified, ls
+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, ls
+defaults this category to @samp{37;41}.
+
address@hidden SOCK
+The color string for sockets.  If not specified, 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, ls defaults this category to @samp{30;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, 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 TERM line.  If
+the environment variable @env{TERM} matches the argument of the TERM
+keyword, then the current description affects the output.
+
address@hidden table
 
 
 @node Basic operations