Bugtrack 1285 - Add docs for omitted dkim_disable_verify.
[exim.git] / doc / doc-docbook / x2man
CommitLineData
168e428f
PH
1#! /usr/bin/perl -w
2
168e428f
PH
3# Script to find the command line options in the DocBook source of the Exim
4# spec, and turn them into a man page, because people like that.
5
168e428f
PH
6open(IN, "spec.xml") || die "Can't open spec.xml\n";
7open(OUT, ">exim.8" ) || die "Can't open exim.8\n";
8
9print OUT <<End;
10.TH EXIM 8
11.SH NAME
12exim \\- a Mail Transfer Agent
13.SH SYNOPSIS
f91ad6b7 14.nf
168e428f 15.B exim [options] arguments ...
168e428f 16.B mailq [options] arguments ...
168e428f 17.B rsmtp [options] arguments ...
168e428f 18.B rmail [options] arguments ...
168e428f 19.B runq [options] arguments ...
168e428f 20.B newaliases [options] arguments ...
f91ad6b7 21.fi
3cb1b51e 22.
168e428f
PH
23.SH DESCRIPTION
24.rs
25.sp
26Exim is a mail transfer agent (MTA) developed at the University of Cambridge.
27It is a large program with very many facilities. For a full specification, see
28the reference manual. This man page contains only a description of the command
29line options. It has been automatically generated from the reference manual
30source, hopefully without too much mangling.
3cb1b51e
PH
31.P
32Like other MTAs, Exim replaces Sendmail, and is normally called by user agents
33(MUAs) using the path \\fI/usr/sbin/sendmail\\fP when they submit messages for
34delivery (some operating systems use \\fI/usr/lib/sendmail\\fP). This path is
35normally set up as a symbolic link to the Exim binary. It may also be used by
36boot scripts to start the Exim daemon. Many of Exim's command line options are
37compatible with Sendmail so that it can act as a drop-in replacement.
38.
39.SH "DEFAULT ACTION"
db9452a9
PH
40.rs
41.sp
b4583215
PH
42If no options are present that require a specific action (such as starting the
43daemon or a queue runner, testing an address, receiving a message in a specific
3cb1b51e
PH
44format, or listing the queue), and there are no arguments on the command line,
45Exim outputs a brief message about itself and exits.
46.sp
47However, if there is at least one command line argument, \\fB-bm\\fR (accept a
48local message on the standard input, with the arguments specifying the
49recipients) is assumed. Thus, for example, if Exim is installed in
50\\fI/usr/sbin\\fP, you can send a message from the command line like this:
51.sp
52 /usr/sbin/exim -i <recipient-address(es)>
53 <message content, including all the header lines>
54 CTRL-D
55.sp
56The \\fB-i\\fP option prevents a line containing just a dot from terminating
57the message. Only an end-of-file (generated by typing CTRL-D if the input is
58from a terminal) does so.
59.
60.SH "SETTING OPTIONS BY PROGRAM NAME"
168e428f 61.rs
3cb1b51e
PH
62.sp
63If an Exim binary is called using one of the names listed in this section
64(typically via a symbolic link), certain options are assumed.
65.TP
168e428f
PH
66\\fBmailq\\fR
67Behave as if the option \\fB\\-bp\\fP were present before any other options.
68The \\fB\\-bp\\fP option requests a listing of the contents of the mail queue
69on the standard output.
70.TP
71\\fBrsmtp\\fR
72Behaves as if the option \\fB\\-bS\\fP were present before any other options,
73for compatibility with Smail. The \\fB\\-bS\\fP option is used for reading in a
74number of messages in batched SMTP format.
75.TP
76\\fBrmail\\fR
77Behave as if the \\fB\\-i\\fP and \\fB\\-oee\\fP options were present before
78any other options, for compatibility with Smail. The name \\fBrmail\\fR is used
79as an interface by some UUCP systems. The \\fB\\-i\\fP option specifies that a
80dot on a line by itself does not terminate a non\\-SMTP message; \\fB\\-oee\\fP
81requests that errors detected in non\\-SMTP messages be reported by emailing
82the sender.
83.TP
84\\fBrunq\\fR
85Behave as if the option \\fB\\-q\\fP were present before any other options, for
86compatibility with Smail. The \\fB\\-q\\fP option causes a single queue runner
87process to be started. It processes the queue once, then exits.
88.TP
89\\fBnewaliases\\fR
90Behave as if the option \\fB\\-bi\\fP were present before any other options,
91for compatibility with Sendmail. This option is used for rebuilding Sendmail's
92alias file. Exim does not have the concept of a single alias file, but can be
93configured to run a specified command if called with the \\fB\\-bi\\fP option.
3cb1b51e
PH
94.
95.SH "OPTIONS"
168e428f
PH
96.rs
97End
98
99while (<IN>) { last if /^<!-- === Start of command line options === -->\s*$/; }
100die "Can't find start of options\n" if ! defined $_;
101
102$optstart = 0;
103$indent = "";
104
105# Loop for each individual option
106
107$next = <IN>;
108
109while ($next)
110 {
111 $_ = $next;
112 $next = <IN>;
113
114 last if /^<!-- === End of command line options === -->\s*$/;
115
116 # Start of new option
117
4f578862 118 if (/^<term>(?=<option>-)(.*?)<\/term>$/)
168e428f
PH
119 {
120 print OUT ".TP 10\n";
9b371988 121 $_ = "$1\n";
168e428f 122 $optstart = 1;
168e428f
PH
123 }
124
125 # If a line contains text that is not in <>, read subsequent lines of the
126 # same form, so that we get whole sentences for matching on references.
127
128 if (/^ (?> (<[^>]+>)* ) \s*\S/x)
129 {
130 while ($next =~ /^ (?> (<[^>]+>)* ) \s*\S/x)
131 {
132 $_ .= $next;
133 $next = <IN>;
134 }
135 }
136
137 # Remove sentences or parenthetical comments that refer to chapters or
138 # sections. The order of these changes is very important:
139 #
140 # (1) Remove any parenthetical comments first.
141 # (2) Then remove any sentences that start after a full stop.
142 # (3) Then remove any sentences that start at the beginning or a newline.
143
144 s/\s?\( [^()]+ <xref \s linkend="[^"]+" \/ > \)//xg;
145 s/\s?\. [^.]+ <xref \s linkend="[^"]+" \/ > [^.]*? \././xg;
146 s/(^|\n) [^.]+ <xref \s linkend="[^"]+" \/ > [^.]*? \./$1/xg;
147
148 # Handle paragraph starts; skip the first one encountered for an option
149
150 if ($optstart && /<(sim)?para>/)
151 {
152 s/<(sim)?para>//;
153 $optstart = 0;
154 }
155
3cb1b51e 156 # Literal layout needs to be wrapped with .sp, and indented.
168e428f
PH
157
158 if (/<literallayout/)
159 {
3cb1b51e 160 s/<literallayout[^>]*>/.sp/;
168e428f
PH
161 $indent = " ";
162 }
163
164 $indent = "" if (/<\/literallayout>/);
165
166 # Others get marked
167
3cb1b51e
PH
168 s/<para>/.sp/;
169 s/<simpara>/.sp/;
168e428f
PH
170
171 # Skip index entries
172
173 s/<primary>.*?<\/primary>//g;
174 s/<secondary>.*?<\/secondary>//g;
175
176 # Convert all occurrences of backslash into \e
177
178 s/\\/\\e/g;
179
180 # Handle bold and italic
181
182 s/<emphasis>/\\fI/g;
183 s/<emphasis role="bold">/\\fB/g;
184 s/<\/emphasis>/\\fP/g;
185
186 s/<option>/\\fB/g;
187 s/<\/option>/\\fP/g;
188
189 s/<varname>/\\fI/g;
190 s/<\/varname>/\\fP/g;
191
192 # Handle quotes
193
194 s/<\/?quote>/"/g;
195
196 # Remove any remaining XML markup
197
198 s/<[^>]*>//g;
199
200 # If nothing left in the line, ignore.
201
202 next if /^\s*$/;
203
168e428f
PH
204 # We are going to output some data; sort out special characters
205
206 s/&lt;/</g;
207 s/&gt;/>/g;
208
9b371988
PH
209 s/&nbsp;/ /g;
210 s/&ndash;/-/g;
168e428f 211 s/&#x2019;/'/g;
168e428f
PH
212
213 # Escape hyphens to prevent unwanted hyphenation
214
215 s/-/\\-/g;
216
3cb1b51e 217 # Put in the indent unless the line starts .sp, and then write the line
168e428f 218
3cb1b51e 219 s/^/$indent/mg unless /^\.sp/;
168e428f
PH
220
221 print OUT;
222 }
223
3cb1b51e
PH
224print OUT <<End;
225.
226.SH "SEE ALSO"
227.rs
228.sp
229The full Exim specification, the Exim book, and the Exim wiki.
230End
231
232# End of x2man