doc/doc-docbook/x2man

   1 #! /usr/bin/perl -w
   2
   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
   6 open(IN, "spec.xml") || die "Can't open spec.xml\n";
   7 open(OUT, ">exim.8" ) || die "Can't open exim.8\n";
   8
   9 print OUT <<End;
  10 .TH EXIM 8
  11 .SH NAME
  12 exim \\- a Mail Transfer Agent
  13 .SH SYNOPSIS
  14 .nf
  15 .B exim [options] arguments ...
  16 .B mailq [options] arguments ...
  17 .B rsmtp [options] arguments ...
  18 .B rmail [options] arguments ...
  19 .B runq [options] arguments ...
  20 .B newaliases [options] arguments ...
  21 .fi
  22 .
  23 .SH DESCRIPTION
  24 .rs
  25 .sp
  26 Exim is a mail transfer agent (MTA) developed at the University of Cambridge.
  27 It is a large program with very many facilities. For a full specification, see
  28 the reference manual. This man page contains only a description of the command
  29 line options. It has been automatically generated from the reference manual
  30 source, hopefully without too much mangling.
  31 .P
  32 Like 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
  34 delivery (some operating systems use \\fI/usr/lib/sendmail\\fP). This path is
  35 normally set up as a symbolic link to the Exim binary. It may also be used by
  36 boot scripts to start the Exim daemon. Many of Exim's command line options are
  37 compatible with Sendmail so that it can act as a drop-in replacement.
  38 .
  39 .SH "DEFAULT ACTION"
  40 .rs
  41 .sp
  42 If no options are present that require a specific action (such as starting the
  43 daemon or a queue runner, testing an address, receiving a message in a specific
  44 format, or listing the queue), and there are no arguments on the command line,
  45 Exim outputs a brief message about itself and exits.
  46 .sp
  47 However, if there is at least one command line argument, \\fB-bm\\fR (accept a
  48 local message on the standard input, with the arguments specifying the
  49 recipients) 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
  56 The \\fB-i\\fP option prevents a line containing just a dot from terminating
  57 the message. Only an end-of-file (generated by typing CTRL-D if the input is
  58 from a terminal) does so.
  59 .
  60 .SH "SETTING OPTIONS BY PROGRAM NAME"
  61 .rs
  62 .sp
  63 If 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
  66 \\fBmailq\\fR
  67 Behave as if the option \\fB\\-bp\\fP were present before any other options.
  68 The \\fB\\-bp\\fP option requests a listing of the contents of the mail queue
  69 on the standard output.
  70 .TP
  71 \\fBrsmtp\\fR
  72 Behaves as if the option \\fB\\-bS\\fP were present before any other options,
  73 for compatibility with Smail. The \\fB\\-bS\\fP option is used for reading in a
  74 number of messages in batched SMTP format.
  75 .TP
  76 \\fBrmail\\fR
  77 Behave as if the \\fB\\-i\\fP and \\fB\\-oee\\fP options were present before
  78 any other options, for compatibility with Smail. The name \\fBrmail\\fR is used
  79 as an interface by some UUCP systems. The \\fB\\-i\\fP option specifies that a
  80 dot on a line by itself does not terminate a non\\-SMTP message; \\fB\\-oee\\fP
  81 requests that errors detected in non\\-SMTP messages be reported by emailing
  82 the sender.
  83 .TP
  84 \\fBrunq\\fR
  85 Behave as if the option \\fB\\-q\\fP were present before any other options, for
  86 compatibility with Smail. The \\fB\\-q\\fP option causes a single queue runner
  87 process to be started. It processes the queue once, then exits.
  88 .TP
  89 \\fBnewaliases\\fR
  90 Behave as if the option \\fB\\-bi\\fP were present before any other options,
  91 for compatibility with Sendmail. This option is used for rebuilding Sendmail's
  92 alias file. Exim does not have the concept of a single alias file, but can be
  93 configured to run a specified command if called with the \\fB\\-bi\\fP option.
  94 .
  95 .SH "OPTIONS"
  96 .rs
  97 End
  98
  99 while (<IN>) { last if /^<!-- === Start of command line options === -->\s*$/; }
 100 die "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
 109 while ($next)
 110   {
 111   $_ = $next;
 112   $next = <IN>;
 113
 114   last if /^<!-- === End of command line options === -->\s*$/;
 115
 116   # Start of new option
 117
 118   if (/^<term>(?=<option>-)(.*?)<\/term>$/)
 119     {
 120     print OUT ".TP 10\n";
 121     $_ = "$1\n";
 122     $optstart = 1;
 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
 156   # Literal layout needs to be wrapped with .sp, and indented.
 157
 158   if (/<literallayout/)
 159     {
 160     s/<literallayout[^>]*>/.sp/;
 161     $indent = "  ";
 162     }
 163
 164   $indent = "" if (/<\/literallayout>/);
 165
 166   # Others get marked
 167
 168   s/<para>/.sp/;
 169   s/<simpara>/.sp/;
 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
 204   # We are going to output some data; sort out special characters
 205
 206   s/&lt;/</g;
 207   s/&gt;/>/g;
 208
 209   s/&nbsp;/ /g;
 210   s/&ndash;/-/g;
 211   s/&#x2019;/'/g;
 212
 213   # Escape hyphens to prevent unwanted hyphenation
 214
 215   s/-/\\-/g;
 216
 217   # Put in the indent unless the line starts .sp, and then write the line
 218
 219   s/^/$indent/mg unless /^\.sp/;
 220
 221   print OUT;
 222   }
 223
 224 print OUT <<End;
 225 .
 226 .SH "SEE ALSO"
 227 .rs
 228 .sp
 229 The full Exim specification, the Exim book, and the Exim wiki.
 230 End
 231
 232 # End of x2man