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