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