DSN: fix null deref when bounce is due to conn-timeout. Bug 1630
[users/jgh/exim.git] / 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