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