Include string_interpret_escape() in COMPILE_UTILITY cases.
[exim.git] / doc / doc-scripts / f2h
CommitLineData
495ae4b0 1#!/usr/bin/perl
495ae4b0
PH
2
3# Script to turn the Exim FAQ into HTML.
4
5use integer;
6
7# Function to do text conversions that apply to both displays and non displays
8
9sub process_both {
10my($s) = $_[0];
11$s =~ s/</&#60;/g; # Deal with < and >
12$s =~ s/>/&#62;/g;
13return $s;
14}
15
16
17# Function to do text conversions to display paragraphs
18
19sub process_display {
20my($s) = $_[0];
21$s =~ s/^==>/ /;
22my($indent) = $s =~ /^(\s+)/;
23my($remove) = " " x (length($indent) - 3);
24$s =~ s/^$remove//mg;
25$s = &process_both($s);
26return $s;
27}
28
29
30# Function to do text conversions to paragraphs not in displays.
31
32sub process_non_display {
33my($s) = &process_both($_[0]);
34
35$s =~ s/@\\/@@backslash@@/g; # @\ temporarily hidden
36
37$s =~ s/\\#/&nbsp;/g; # \# is a hard space
38
39$s =~ s/\\\*\*([^*]*)\*\*\\/<b>$1<\/b>/g; # \**...**\ => bold
40$s =~ s/\\\*([^*]*)\*\\/<i>$1<\/i>/g; # \*.....*\ => italic
41$s =~ s/\\"([^"]*)"\\/<tt>$1<\/tt>/g; # \"....."\ => fixed pitch
42$s =~ s/\\\$([^\$]*)\$\\/<i>\$$1<\/i>/g; # \$.....$\ => $italic
43$s =~ s/\\\\([^\\]*)\\\\/<small>$1<\/small>/g; # \\.....\\ => small
44$s =~ s/\\\(([^)]*)\)\\/<i>$1<\/i>/g; # \(.....)\ => italic
45$s =~ s/\\-([^\\]*)-\\/<b>-$1<\/b>/g; # \-.....-\ => -bold
46$s =~ s/\\\[([^]]*)\]\\/&\#60;<i>$1<\/i>&\#62;/gx; # \[.....]\ => <italic>
47$s =~ s/\\\?(.*?)\?\\/<a href="$1">$1<\/a>/g; # \?.....?\ => URL
48$s =~ s/\\\^\^([^^]*)\^\^\\/<i>$1<\/i>/g; # \^^...^^\ => italic
49$s =~ s/\\\^([^^]*)\^\\/<i>$1<\/i>/g; # \^.....^\ => italic
50$s =~ s/\\%([^%]*)%\\/<b>$1<\/b>/g; # \%.....%\ => bold
51$s =~ s/\\\/([^\/]*)\/\\/<i>$1<\/i>/g; # \/...../\ => italic
52$s =~ s/\\([^\\]+)\\/<tt>$1<\/tt>/g; # \.......\ => fixed pitch
53
54$s =~ s"//([^/\"]*)//"<i>$1</i>"g; # //.....// => italic
55$s =~ s/::([^:]*)::/<i>$1:<\/i>/g; # ::.....:: => italic:
56
57$s =~ s/``(.*?)''/&#147;$1&#148;/g; # ``.....'' => quoted text
58
59$s =~ s/\s*\[\[br\]\]\s*/<br>/g; # [[br]] => <br>
60
61$s =~ s/@@backslash@@/\\/g; # Put back single backslash
62
63$s =~ s/^(\s*\(\d\)\s)/$1&nbsp;/; # Extra space after (1), etc.
64
65# Cross references within paragraphs
66
67$s =~ s/Q(\d{4})(?!:)/<a href="$xref{$1}">$&<\/a>/xg;
68
69# References to configuration samples
70
71$s =~ s/\b([CFLS]\d\d\d)\b/<a href="$1.txt">$1<\/a>/g;
72
73# Remove white space preceding a newline in the middle of paragraphs,
74# to keep the file smaller (and for human reading when debugging).
75
76$s =~ s/^\s+//mg;
77
78return $s;
79}
80
81
82# Main program
83
84# We want to read the file paragraph by paragraph; Perl only does this if the
85# separating lines are truly blank. Having been caught by lines containing
86# whitespace before, do a detrailing pass first.
87
88open(IN, "$ARGV[0]") || die "can't open $ARGV[0] (preliminary)\n";
89open(OUT, ">$ARGV[0]-$$") || die "can't open $ARGV[0]-$$\n";
90while (<IN>)
91 {
92 s/[ \t]+$//;
93 print OUT;
94 }
95close(IN);
96close(OUT);
97rename("$ARGV[0]-$$", "$ARGV[0]") ||
98 die "can't rename $ARGV[0]-$$ as $ARGV[0]\n";
99
100# The second argument is the name of a directory into which to put multiple
101# HTML files. We start off with FAQ.html.
102
103$hdir = $ARGV[1];
104open(OUT, ">$hdir/FAQ.html") || die "can't open $hdir/FAQ.html\n";
105
106# Initial output
107
108print OUT <<End ;
109<html>
110<head>
111<title>The Exim FAQ</title>
112</head>
113<body bgcolor="#F8F8F8" text="#00005A" link="#0066FF" alink="#0066FF" vlink="#000099">
114<h1>The Exim FAQ</h1>
115End
116
117$/ = "";
118
119# First pass to read the titles and questions and create the table of
120# contents. We save it up in a vector so that it can be written after the
121# introductory paragraphs.
122
123open(IN, "$ARGV[0]") || die "can't open $ARGV[0] (first time)\n";
124
125$toc = 0;
126$sec = -1;
127$inul = 0;
128
129while ($_ = <IN>)
130 {
131 $count = s/\n/\n/g - 1; # Number of lines in paragraph
132
133 if ($count == 1 && /^\d+\./) # Look for headings
134 {
135 chomp;
136 push @toc, "</ul>" if $inul;
137 $inul = 0;
138 push @toc, "<br>\n\n" if $sec++ >= 0;
139 push @toc, "<a name=\"TOC$toc\" href=\"FAQ_$sec.html\">$_</a>\n";
140 $toc++;
141
142 ($number,$title) = /^(\d+)\.\s+(.*)$/;
143 if ($title ne "UUCP" && $title ne "IRIX" && $title ne "BSDI" &&
144 $title ne "HP-UX")
145 {
146 ($initial,$rest) = $title =~ /^(.)(.*)$/;
147 $title = "$initial\L$rest";
148 $title =~ s/isdn/ISDN/;
149 $title =~ s/\btls\b/TLS/;
150 $title =~ s/\bssl\b/SSL/;
151 $title =~ s/ os x/ OS X/;
152 }
153 push @seclist, "<a href=\"FAQ_$sec.html\">$number. $title</a>";
154
155 next;
156 }
157
158 if (/^(Q\d{4})/) # Q initial paragraph
159 {
160 if (!$inul)
161 {
162 push @toc, "<ul>\n";
163 $inul = 1;
164 }
165 $num = $1;
166 $rest = $';
167 $xref{substr($num,1)} = "FAQ_$sec.html#TOC$toc";
168 $rest =~ s/^: /:&nbsp;&nbsp;/;
169 $rest = &process_non_display($rest);
170 push @toc, "<li><a name=\"TOC$toc\" href=\"FAQ_$sec.html#TOC$toc\">$num</a>$rest<br><br></li>\n";
171 $toc++;
172 next;
173 }
174 }
175
176push @toc, "</ul>\n" if $inul;
177close(IN);
178
179
180# This is the main processing pass. We have to detect the different kinds of
181# "paragraph" and do appropriate things.
182
183open(IN, "$ARGV[0]") || die "can't open $ARGV[0] (second time)\n";
184
185# Skip the title line
186
187$_ = <IN>;
188
189# Handle the rest of the file
190
191$toc = 0;
192$maxsec = $sec;
193$sec = -1;
194
195while ($_ = <IN>)
196 {
197 $count = s/\n/\n/g - 1; # Number of lines in paragraph
198 chomp; # Trailing newlines
199
200 if (/^The FAQ is divided into/)
201 {
202 my($count) = scalar(@seclist);
203 my($cols) = ($count + 1)/2;
204
205 print OUT "<hr><a name=\"TOC\"><h1>Index</h1></a>\n";
206 print OUT "<p>A <i>Keyword-in-context</i> <a href=\"FAQ-KWIC_A.html\">index</a> " .
207 "to the questions is available. This is usually the " .
208 "quickest way to find information in the FAQ.</p>\n";
209
210 print OUT "<h1>Contents</h1>\n";
211 print OUT "<p>The FAQ is divided into the following sections:<br><br></p>\n";
212
213 print OUT "<table>\n";
214
215 for ($i = 0; $i < $cols; $i++)
216 {
217 print OUT "<tr>\n";
218 print OUT " <td>", "&nbsp;" x 4, "</td>\n";
219 print OUT " <td>&nbsp;$seclist[$i]</td>\n";
220 print OUT " <td>", "&nbsp;" x8, "$seclist[$cols+$i]</td>\n"
221 if $cols+$i < $count;
222 print OUT "</tr>\n";
223 }
224 print OUT "</table><br><p>\n<hr><br>\n";
225 print OUT "<h1>List of questions</h1>\n";
226
227 $_ = <IN>; # Skip section list
228 next;
229 }
230
231 if ($count == 1 && /^\d+\./) # Look for headings
232 {
233 if (@toc != 0) # TOC when hit first heading
234 {
235 while (@toc != 0) { print OUT shift @toc; }
236 }
237
238 # Output links at the bottom of this page
239
240 print OUT "<hr><br>\n";
241 print OUT "<a href=\"FAQ.html#TOC\">Contents</a>&nbsp;&nbsp;\n";
242 if ($sec > 0)
243 {
244 printf OUT ("<a href=\"FAQ_%d.html\">Previous</a>&nbsp;&nbsp;\n", $sec-1);
245 }
246 printf OUT ("<a href=\"FAQ_%d.html\">Next</a>\n", $sec+1);
247
248 # New section goes in new file
249
250 print OUT "</body>\n</html>\n";
251 close OUT;
252
253 $sec++;
254 open(OUT, ">$hdir/FAQ_$sec.html") ||
255 die "Can't open $hdir/FAQ_$sec.html\n";
256
257 print OUT "<html>\n<head>\n" .
258 "<title>The Exim FAQ Section $sec</title>\n" .
259 "</head>\n" .
260 "<body bgcolor=\"#F8F8F8\" text=\"#00005A\" " .
261 "link=\"#FF6600\" alink=\"#FF9933\" vlink=\"#990000\">\n";
262
263 printf OUT "<h1>The Exim FAQ</h1>\n";
264
265 print OUT "<a href=\"FAQ.html#TOC\">Contents</a>&nbsp;&nbsp;\n";
266 if ($sec > 0)
267 {
268 printf OUT ("<a href=\"FAQ_%d.html\">Previous</a>&nbsp;&nbsp;\n", $sec-1);
269 }
270 if ($sec < $maxsec)
271 {
272 printf OUT ("<a href=\"FAQ_%d.html\">Next</a>\n", $sec+1);
273 }
274
275 print OUT "<hr><br>\n";
276
277 print OUT "<h2><a href=\"FAQ.html#TOC$toc\">$_</a></h2>\n";
278 $toc++;
279 next;
280 }
281
282 s/^([QA]\d{4}|[CFLS]\d{3}): /$1:&nbsp;&nbsp;/;
283
284 if (/^(Q\d{4}:)/) # Q initial paragraph
285 {
286 print OUT "<p>\n<a name=\"TOC$toc\" href=\"FAQ.html#TOC$toc\">$1</a>";
287 $_ = &process_non_display($');
288 print OUT "$_\n</p>\n";
289 $toc++;
290 next;
291 }
292
293 if (/^A\d{4}:/) # A initial paragraph
294 {
295 $_ = &process_non_display($_);
296 s/^(A\d{4}:)/<font color="#00BB00">$1<\/font>/;
297 print OUT "<p>\n$_\n</p>\n";
298 next;
299 }
300
301 # If a paragraph begins ==> it is a display which must remain verbatin
302 # and not be reformatted. The flag gets turned into spaces.
303
304 if ($_ =~ /^==>/)
305 {
306 $_ = &process_display($_);
307 chomp;
308 print OUT "<pre>\n$_</pre>\n";
309 }
310
311 # Non-display paragraph; massage the final line & my sig.
312
313 elsif (/^\*\*\* End of Exim FAQ \*\*\*/)
314 {
315 }
316
317 else
318 {
319 $_ = &process_non_display($_);
320 if (/^Philip Hazel/)
321 {
322 s/\n/<br>\n/g;
323 s/<br>$/<hr><br>/;
324 }
325 print OUT "<p>\n$_\n</p>\n";
326 }
327 }
328
329close(IN);
330
331print OUT "<hr><br>\n";
332print OUT "<a href=\"FAQ.html#TOC\">Contents</a>&nbsp;&nbsp;\n";
333printf OUT ("<a href=\"FAQ_%d.html\">Previous</a>\n", $sec-1);
334
335print OUT "</body>\n</html>\n";
336close(OUT);
337End