doc/doc-docbook/x2man

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