doc/doc-docbook/x2man

   1 #! /usr/bin/perl -w
   2
   3 # $Cambridge: exim/doc/doc-docbook/x2man,v 1.3 2006/04/04 14:03:49 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 SETTING OPTIONS BY PROGRAM NAME
  45 .rs
  46 .TP 10
  47 \\fBmailq\\fR
  48 Behave as if the option \\fB\\-bp\\fP were present before any other options.
  49 The \\fB\\-bp\\fP option requests a listing of the contents of the mail queue
  50 on the standard output.
  51 .TP
  52 \\fBrsmtp\\fR
  53 Behaves as if the option \\fB\\-bS\\fP were present before any other options,
  54 for compatibility with Smail. The \\fB\\-bS\\fP option is used for reading in a
  55 number of messages in batched SMTP format.
  56 .TP
  57 \\fBrmail\\fR
  58 Behave as if the \\fB\\-i\\fP and \\fB\\-oee\\fP options were present before
  59 any other options, for compatibility with Smail. The name \\fBrmail\\fR is used
  60 as an interface by some UUCP systems. The \\fB\\-i\\fP option specifies that a
  61 dot on a line by itself does not terminate a non\\-SMTP message; \\fB\\-oee\\fP
  62 requests that errors detected in non\\-SMTP messages be reported by emailing
  63 the sender.
  64 .TP
  65 \\fBrunq\\fR
  66 Behave as if the option \\fB\\-q\\fP were present before any other options, for
  67 compatibility with Smail. The \\fB\\-q\\fP option causes a single queue runner
  68 process to be started. It processes the queue once, then exits.
  69 .TP
  70 \\fBnewaliases\\fR
  71 Behave as if the option \\fB\\-bi\\fP were present before any other options,
  72 for compatibility with Sendmail. This option is used for rebuilding Sendmail's
  73 alias file. Exim does not have the concept of a single alias file, but can be
  74 configured to run a specified command if called with the \\fB\\-bi\\fP option.
  75
  76 .SH OPTIONS
  77 .rs
  78 End
  79
  80 while (<IN>) { last if /^<!-- === Start of command line options === -->\s*$/; }
  81 die "Can't find start of options\n" if ! defined $_;
  82
  83 $optstart = 0;
  84 $indent = "";
  85
  86 # Loop for each individual option
  87
  88 $next = <IN>;
  89
  90 while ($next)
  91   {
  92   $_ = $next;
  93   $next = <IN>;
  94
  95   last if /^<!-- === End of command line options === -->\s*$/;
  96
  97   # Start of new option
  98
  99   if (/^<term>(?=<option>-)(.*?)<\/term>$/)
 100     {
 101     print OUT ".TP 10\n";
 102     $_ = "$1\n";
 103     $optstart = 1;
 104     }
 105
 106   # If a line contains text that is not in <>, read subsequent lines of the
 107   # same form, so that we get whole sentences for matching on references.
 108
 109   if (/^ (?> (<[^>]+>)* ) \s*\S/x)
 110     {
 111     while ($next =~ /^ (?> (<[^>]+>)* ) \s*\S/x)
 112       {
 113       $_ .= $next;
 114       $next = <IN>;
 115       }
 116     }
 117
 118   # Remove sentences or parenthetical comments that refer to chapters or
 119   # sections. The order of these changes is very important:
 120   #
 121   # (1) Remove any parenthetical comments first.
 122   # (2) Then remove any sentences that start after a full stop.
 123   # (3) Then remove any sentences that start at the beginning or a newline.
 124
 125   s/\s?\(  [^()]+ <xref \s linkend="[^"]+" \/ > \)//xg;
 126   s/\s?\.  [^.]+ <xref \s linkend="[^"]+" \/ > [^.]*? \././xg;
 127   s/(^|\n) [^.]+ <xref \s linkend="[^"]+" \/ > [^.]*? \./$1/xg;
 128
 129   # Handle paragraph starts; skip the first one encountered for an option
 130
 131   if ($optstart && /<(sim)?para>/)
 132     {
 133     s/<(sim)?para>//;
 134     $optstart = 0;
 135     }
 136
 137   # Literal layout needs to be treated as a paragraph, and indented
 138
 139   if (/<literallayout/)
 140     {
 141     s/<literallayout[^>]*>/.P/;
 142     $indent = "  ";
 143     }
 144
 145   $indent = "" if (/<\/literallayout>/);
 146
 147   # Others get marked
 148
 149   s/<para>/.P/;
 150   s/<simpara>/.P/;
 151
 152   # Skip index entries
 153
 154   s/<primary>.*?<\/primary>//g;
 155   s/<secondary>.*?<\/secondary>//g;
 156
 157   # Convert all occurrences of backslash into \e
 158
 159   s/\\/\\e/g;
 160
 161   # Handle bold and italic
 162
 163   s/<emphasis>/\\fI/g;
 164   s/<emphasis role="bold">/\\fB/g;
 165   s/<\/emphasis>/\\fP/g;
 166
 167   s/<option>/\\fB/g;
 168   s/<\/option>/\\fP/g;
 169
 170   s/<varname>/\\fI/g;
 171   s/<\/varname>/\\fP/g;
 172
 173   # Handle quotes
 174
 175   s/<\/?quote>/"/g;
 176
 177   # Remove any remaining XML markup
 178
 179   s/<[^>]*>//g;
 180
 181   # If nothing left in the line, ignore.
 182
 183   next if /^\s*$/;
 184
 185   # It turns out that we don't actually want .P; a blank line is needed.
 186   # But we can't set that above, because it will be discarded.
 187
 188   s/^\.P\s*$/\n/;
 189
 190   # We are going to output some data; sort out special characters
 191
 192   s/&lt;/</g;
 193   s/&gt;/>/g;
 194
 195   s/&nbsp;/ /g;
 196   s/&ndash;/-/g;
 197   s/&#x2019;/'/g;
 198
 199   # Escape hyphens to prevent unwanted hyphenation
 200
 201   s/-/\\-/g;
 202
 203   # Put in the indent, and write the line
 204
 205   s/^/$indent/mg;
 206
 207   print OUT;
 208   }
 209
 210 # End of g2man