Commit 3e347086 3e347086423b7bf1cd93e6b7c9311cafcbb375f1 by Sam Roberts

Document use of ~/.<program>rc.

1 parent 623d8529
...@@ -30,30 +30,38 @@ inconvenient to specify them in the command line each time you run ...@@ -30,30 +30,38 @@ inconvenient to specify them in the command line each time you run
30 a mailutils utility. The @dfn{configuration files} provide a way to 30 a mailutils utility. The @dfn{configuration files} provide a way to
31 add default command line arguments without having to type them in 31 add default command line arguments without having to type them in
32 the command line. Upon startup, each mailutils utility scans and 32 the command line. Upon startup, each mailutils utility scans and
33 processes the contents of the two startup files: the site-wide 33 processes the contents of the three startup files: the site-wide
34 configuration file @file{mailutils.rc} and user-specific configuration 34 configuration file @file{mailutils.rc}, the user-specific configuration
35 file @file{.mailutils}. The site-wide configuration file is searched 35 file @file{.mailutils}, and the program-specific configuration
36 file @file{.<program>rc}. The site-wide configuration file is searched
36 in your system configuration directory (usually, @file{/etc} or 37 in your system configuration directory (usually, @file{/etc} or
37 @file{/usr/local/etc}), the user-specific configuration file is searched 38 @file{/usr/local/etc}), the user-specific and program-specific
38 in user home directory. 39 configuration files are searched in the user's home directory.
39 40
40 Both files have simple line-oriented syntax. Comments begin with the 41 These files have simple line-oriented syntax. Comments begin with the
41 pound sign (@samp{#}) and extend through the end of the line 42 pound sign (@samp{#}) and extend through the end of the line
42 @footnote{If @samp{#} is not the first character on the line, it 43 @footnote{If @samp{#} is not the first character on the line, it
43 should be separated from the previous word by any amount of whitespace.}. 44 should be separated from the previous word by any amount of whitespace.}.
44 Very long lines may be split across several lines by escaping final newline 45 Very long lines may be split across several lines by escaping final newline
45 with a backslash (@samp{\}) character. 46 with a backslash (@samp{\}) character.
46 47
47 Any non-comment line starts with a @dfn{tag}. A tag is either a name 48 In the non-program-specific configuration files, any non-comment line
48 of a particular mailutils utility or @dfn{option group}, prefixed with 49 must start with a @dfn{tag}. In the program-specific configuration
49 colon (@samp{:}). The command line options common for several mailutils 50 file the tag must not be present, all options are for the specific
50 programs are divided into @dfn{option groups} or @dfn{capabilities}, 51 program.
51 e.g. the options @option{--maildir} and @option{--license} form group 52
52 @samp{mailutils}. These groups are discussed in detail below. 53 A tag is either a name of a particular mailutils utility or @dfn{option
53 54 group}, prefixed with colon (@samp{:}). The command line options common for
54 When processing the configuration file, a mailutils utility selects 55 several mailutils programs are divided into @dfn{option groups} or
55 those lines, whose tag is either the name of that utility or the name 56 @dfn{capabilities}, e.g. the options @option{--maildir} and
56 of the option group supported by it. For each line found, its tag 57 @option{--license} form group @samp{mailutils}. These groups are discussed
58 in detail below.
59
60 When processing the non-program-specific configuration files
61 (@file{mailutils.rc} and @file{.mailutils}), a mailutils utility selects
62 those lines whose tag is either the name of that utility or the name
63 of the option group supported by it. In the program-specific configuration
64 file, all lines are selected. For each line found, its tag (if present)
57 is stripped away, and the rest of the line is split up into words. 65 is stripped away, and the rest of the line is split up into words.
58 These words are regarded as command line options and are inserted to 66 These words are regarded as command line options and are inserted to
59 the program arguments @emph{before} any options from the command line. 67 the program arguments @emph{before} any options from the command line.
......