doc/doc-scripts/g2man

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