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