doc/doc-scripts/g2man

   1 #! /usr/bin/perl -w
   2 # $Cambridge: exim/doc/doc-scripts/g2man,v 1.1 2004/10/07 15:04:35 ph10 Exp $
   3
   4 # Script to find the command line options in the Exim spec, and turn them
   5 # into a man page, because people like that.
   6
   7
   8 ##################################################
   9 #            De-markup one line                  #
  10 ##################################################
  11
  12 sub process {
  13 my($x) = $_[0];
  14
  15 # Hide SGCAL escapes
  16
  17 $x =~ s/\@\@/&&a/g;         # @@
  18 $x =~ s/\@\\/&&b/g;         # @\
  19 $x =~ s/\@</&&l/g;          # @<
  20 $x =~ s/\@>/&&g/g;          # @>
  21 $x =~ s/\@\{/&&c/g;         # @{
  22 $x =~ s/\@\}/&&d/g;         # @}
  23 $x =~ s/\@#/&&s/g;          # @#
  24 $x =~ s/\@(.)/$1/g;         # all other @s
  25
  26 # Convert SGCAL markup
  27
  28 $x =~ s/#/ /g;                            # turn #   into a space
  29 $x =~ s/\$~//g;                           # turn $~  into nothing
  30 $x =~ s/__/_/g;                           # turn __  into _
  31 $x =~ s/\$sc\{([^\}]*?)\}/$1/g;           # turn $sc{xxx}   into xxx
  32 $x =~ s/\$st\{([^\}]*?)\}/$1/g;           # turn $st{xxx}   into xxx
  33 $x =~ s/\$si\{([^\}]*?)\}/$1/g;           # turn $si{xxx}   into xxx
  34 $x =~ s/\$tt\{([^\}]*?)\}/$1/g;           # turn $tt{xxx}   into xxx
  35 $x =~ s/\$it\{([^\}]*?)\}/$1/g;           # turn $it{xxx}   into xxx
  36 $x =~ s/\$bf\{([^\}]*?)\}/$1/g;           # turn $bf{xxx}   into xxx
  37 $x =~ s/\$rm\{([^\}]*?)\}/$1/g;           # turn $rm{xxx}   into xxx
  38 $x =~ s/\$cb\{([^\}]*?)\}/$1/g;           # turn $cb{xxx}   into xxx
  39
  40
  41 $x =~ s/\\\\([^\\]*?)\\\\/\U$1/g;         # turn \\xxx\\    into XXX
  42 $x =~ s/\\\(([^)]*?)\)\\/$1/g;            # turn \(xxx)\    into xxx
  43 $x =~ s/\\\"([^\"]*?)\"\\/$1/g;           # turn \"xxx"\    into xxx
  44 $x =~ s/\\\%([^\%]*?)\%\\/"$1"/g;         # turn \%xxx%\    into "xxx"
  45
  46 $x =~   s/\\\?([^?]*?)\?\\/$1/g;          # turn \?URL?\    into URL
  47 $x =~   s/<<([^>]*?)>>/<$1>/g;            # turn <<xxx>>    into <xxx>
  48 $x =~   s/\\\$([^\$]*?)\$\\/\$$1/g;       # turn \$xxx$\    into $xxx
  49 $x =~   s/\\\-([^\\]*?)\-\\/\-$1/g;       # turn \-xxx-\    into -xxx
  50 $x =~   s/\\\*\*([^*]*?)\*\*\\/$1/g;      # turn \**xxx**\  into xxx
  51 $x =~   s/\[\(([\w\/]*)\)\]//g;           # remove inline HTML
  52
  53 $x =~ s/\\\*([^*]*?)\*\\/$1/g;            # turn \*xxx*\    into xxx
  54 $x =~ s/\\([^\\]*?)\\/"$1"/g;             # turn \xxx\      into "xxx"
  55 $x =~ s/\$\*\$/\*/g;                      # turn $*$        into *
  56 $x =~ s/\$t\b//g;                         # turn $t         into nothing
  57
  58 $x =~ s/::([^:]+)::/$1:/g;                # turn ::xxx::    into xxx:
  59
  60 # Put back escaped SGCAL specials
  61
  62 $x =~ s/&&a/\@/g;             # @@ => @
  63 $x =~ s/&&b/\\/g;             # @\ => \
  64 $x =~ s/&&l/</g;              # @< => <
  65 $x =~ s/&&g/>/g;              # @> => >
  66 $x =~ s/&&c/\@{/g;            # @{ => @{
  67 # $x =~ s/&&rc/{/g;             #
  68 # $x =~ s/&&rd/}/g;             #
  69 $x =~ s/&&d/\@}/g;            # @} => @}
  70 $x =~ s/&&s/#/g;              # @#
  71
  72 # Remove any null flags ($$)
  73
  74 $x =~ s/\$\$//g;
  75
  76 $x;
  77 }
  78
  79
  80 ##################################################
  81 #             De-reference a paragraph           #
  82 ##################################################
  83
  84 # Remove sentences or parenthetical comments that contain references.
  85
  86 sub deref {
  87 my($t) = $_[0];
  88
  89 $t =~ s/^(\n*)[^.()]+~~[^.]+\.\s*/$1/;
  90 $t =~ s/\s?\.[^.()]+~~[^.]+\././g;
  91 $t =~ s/\s?\([^~).]+~~[^)]+\)//g;
  92
  93 $t;
  94 }
  95
  96
  97 ##################################################
  98 #            Quote what needs quoting            #
  99 ##################################################
 100
 101 # This is for anything that must be quoted in the final output, independent
 102 # of whether it is in "asis" text or not.
 103
 104 sub mustquote {
 105 my($t) = $_[0];
 106 $t =~ s/(?<!\\)-/\\-/g;
 107
 108 $t;
 109 }
 110
 111
 112
 113 ##################################################
 114 #              Main Program                      #
 115 ##################################################
 116
 117 open(IN, "spec.src") || die "Can't open spec.src\n";
 118 open(OUT, ">exim.8" ) || die "Can't open exim.8\n";
 119
 120 print OUT <<End;
 121 .TH EXIM 8
 122 .SH NAME
 123 exim \\- a Mail Transfer Agent
 124 .SH SYNOPSIS
 125 .B exim [options] arguments ...
 126 .br
 127 .B mailq [options] arguments ...
 128 .br
 129 .B rsmtp [options] arguments ...
 130 .br
 131 .B rmail [options] arguments ...
 132 .br
 133 .B runq [options] arguments ...
 134 .br
 135 .B newaliases [options] arguments ...
 136
 137 .SH DESCRIPTION
 138 Exim is a mail transfer agent (MTA) developed at the University of Cambridge.
 139 It is a large program with very many facilities. For a full specification, see
 140 the reference manual. This man page contains only a description of the command
 141 line options. It has been automatically generated from the reference manual
 142 source, which is why the formatting is poor in some places.
 143
 144 .SH SETTING OPTIONS BY PROGRAM NAME
 145 .TP 10
 146 \\fBmailq\\fR
 147 Behave as if the option \\-bp were present before any other options. The \\-bp
 148 option requests a listing of the contents of the mail queue on the standard
 149 output.
 150 .TP
 151 \\fBrsmtp\\fR
 152 Behaves as if the option \\-bS were present before any other options, for
 153 compatibility with Smail. The \\-bS option is used for reading in a number of
 154 messages in batched SMTP format.
 155 .TP
 156 \\fBrmail\\fR
 157 Behave as if the \\-i and \\-oee options were present before any other options,
 158 for compatibility with Smail. The name \\fBrmail\\fR is used as an interface by
 159 some UUCP systems. The \\-i option specifies that a dot on a line by itself
 160 does not terminate a non\\-SMTP message; \\-oee requests that errors detected in
 161 non\\-SMTP messages be reported by emailing the sender.
 162 .TP
 163 \\fBrunq\\fR
 164 Behave as if the option \\-q were present before any other options, for
 165 compatibility with Smail. The \\-q option causes a single queue runner process
 166 to be started. It processes the queue once, then exits.
 167 .TP
 168 \\fBnewaliases\\fR
 169 Behave as if the option \\-bi were present before any other options, for
 170 compatibility with Sendmail. This option is used for rebuilding Sendmail's
 171 alias file. Exim does not have the concept of a single alias file, but can be
 172 configured to run a specified command if called with the \\-bi option.
 173
 174
 175 .SH OPTIONS
 176 .TP 10
 177 End
 178
 179 while (<IN>) { last if /^\.startoptions/; }
 180 die "Can't find start of options\n" if ! defined $_;
 181
 182 # Find the start of the first option
 183
 184 while (<IN>) { last if /^\.option/; }
 185 die "Can't find start of first option\n" if ! defined $_;
 186
 187 # Loop for each individual option
 188
 189 while (/^\.option (.*)/)
 190   {
 191   $nlpending = 0;
 192   $itemtext = "";
 193
 194   printf OUT ("\\fB\\-%s\\fR\n", &mustquote(&process($1)));
 195
 196   # Process the data for the option
 197
 198   while (<IN>)
 199     {
 200     last if /^\.(?:option|endoptions)/;
 201     next if /^\.index/;
 202     next if /^\.em\s*$/;
 203     next if /^\.nem\s*$/;
 204
 205     if (/^\.display(?:\s+flow)?(?:\s+rm)?\s*$/)
 206       {
 207       print OUT &mustquote(&deref($itemtext));
 208       $itemtext = "";
 209       print OUT "\n";
 210       while (($_ = <IN>) !~ /^\.endd/)
 211         {
 212         print OUT "  ", &mustquote(&deref(&process($_))) if ! /^\./;
 213         }
 214       $nlpending = 1;
 215       }
 216
 217     elsif (/^\.display asis\s*$/)
 218       {
 219       print OUT &mustquote(&deref($itemtext));
 220       $itemtext = "";
 221       print OUT "\n";
 222       while (($_ = <IN>) !~ /^\.endd/)
 223         {
 224         print OUT &mustquote("  $_");
 225         }
 226       $nlpending = 1;
 227       }
 228
 229     elsif (/^\s*$/)
 230       {
 231       print OUT &mustquote(&deref($itemtext));
 232       $itemtext = "";
 233       $nlpending++;
 234       }
 235
 236     else
 237       {
 238       while ($nlpending > 0)
 239         {
 240         $itemtext .= "\n";
 241         $nlpending--;
 242         }
 243       $itemtext .= &process($_);
 244       }
 245     }
 246
 247   print OUT &mustquote(&deref($itemtext));
 248   print OUT ".TP\n";
 249   }
 250
 251 # End of g2man