doc/doc-txt/NewStuff: note the ratelimit changes.
[users/jgh/exim.git] / doc / doc-scripts / f2wiki
1 #!/usr/bin/perl
2 #
3 # Script to convert Exim FAQ into wiki markup - moin flavour
4 #
5 # $Cambridge: exim/doc/doc-scripts/f2wiki,v 1.2 2004/11/12 15:25:39 nm4 Exp $
6 #
7 use strict;
8 use integer;
9 use bytes;
10 use Data::Dumper;
11 use IO::File;
12
13 sub mkwikiname (@) {
14     my @in = @_;
15
16     my @bits;
17     foreach my $str (@in) {
18         $str =~ tr/0-9A-Za-z _//cd;
19         push(@bits, $str);
20     }
21     return join('/', @bits);
22 }
23
24 \f
25
26 sub mkwikifilename ($) {
27     my $wn = shift;
28
29     $wn =~ s/([^A-Za-z0-9])/sprintf("_%02x",ord($1))/eg;
30
31     return $wn;
32 }
33
34 \f
35
36 sub format_wiki_question_header ($) {
37     my $lp = shift;
38
39     my @lines = @{$lp};
40     my $i;
41     for($i =0; ($i <= $#lines); $i++) {
42         unless (defined($lines[$i])) {
43             splice(@lines, $i);
44             last;
45         }
46         $lines[$i] =~ s/^\s+//;
47     }
48     return('= ' . join(' ', @lines) . ' =');
49 }
50
51 \f
52
53 sub wikiref ($$) {
54     my $meta = shift;
55     my $qref = shift;
56
57     my $qtag = $meta->qtags->{$qref};
58     unless ($qtag) {
59         warn "Unknown qtag $qref\n";
60         return $qref;
61     }
62
63     return join(':', '[', $qref->{wikiname}, $qref . ']');
64 }
65
66 \f
67
68 sub wiki_markup ($$) {
69     my $meta = shift;
70     my $s = shift;
71
72     $s =~ s/@\\/\@\@backslash\@\@/g;            # @\ temporarily hidden
73
74     $s =~ s/\\#/ /g;                             # \# is a hard space
75
76     $s =~ s/\\\*\*([^*]*)\*\*\\/'''$1'''/g;     # \**...**\   => bold
77     $s =~ s/\\\*([^*]*)\*\\/''$1''/g;           # \*.....*\   => italic
78     $s =~ s/\\"([^"]*)"\\/`$1`/g;               # \"....."\   => fixed pitch
79     $s =~ s/\\\$([^\$]*)\$\\/''\$$1''/g;        # \$.....$\   => $italic
80     $s =~ s/\\\\([^\\]*)\\\\/<small>$1<\/small>/g; # \\.....\\   => small
81     $s =~ s/\\\(([^)]*)\)\\/''$1''/g;           # \(.....)\   => italic
82     $s =~ s/\\-([^\\]*)-\\/'''-$1'''/g;         # \-.....-\   => -bold
83     $s =~ s/\\\[([^]]*)\]\\/''$1''/gx;          # \[.....]\   => <italic>
84     $s =~ s/\\\?(.*?)\?\\/$1/g;                 # \?.....?\   => URL
85     $s =~ s/\\\^\^([^^]*)\^\^\\/''$1''/g;       # \^^...^^\   => italic
86     $s =~ s/\\\^([^^]*)\^\\/''$1''/g;           # \^.....^\   => italic
87     $s =~ s/\\%([^%]*)%\\/'''$1'''/g;           # \%.....%\   => bold
88     $s =~ s/\\\/([^\/]*)\/\\/''$1''/g;          # \/...../\   => italic
89     $s =~ s/\\([^\\]+)\\/`$1`/g;                # \.......\   => fixed pitch
90
91     $s =~ s"//([^/\"]*)//"''$1</i>"g;           # //.....//   => italic
92     $s =~ s/::([^:]*)::/''$1:''/g;              # ::.....::   => italic:
93
94     $s =~ s/``(.*?)''/&#147;$1&#148;/g;                   # ``.....''   => quoted text
95
96     #$s =~ s/\s*\[\[br\]\]\s*/<br>/g;           # [[br]]      => <br>
97
98     $s =~ s/\@\@backslash\@\@/\\/g;                     # Put back single backslash
99
100     $s =~ s/^(\s*\(\d\)\s)/$1&nbsp;/;           # Extra space after (1), etc.
101
102     # Cross references within paragraphs
103
104     $s =~ s/Q(\d{4})(?!:)/wikiref($meta, $1)/xg;
105
106     # References to configuration samples
107
108     ##$s =~ s/\b([CFLS]\d\d\d)\b/<a href="$1.txt">$1<\/a>/g;
109
110     # Remove white space preceding a newline in the middle of paragraphs,
111     # to keep the file smaller (and for human reading when debugging).
112
113     ##$s =~ s/^\s+//mg;
114
115     return $s;
116 }
117
118 \f
119
120 sub clip_paragraph ($) {
121     my $lines = shift;
122
123     my $ret;
124     my $flags;
125     my $offlen;
126
127     # split off and throw initial para breaks
128     while (($#{$lines} >= 0) && (!defined($lines->[0]))) {
129         shift @{$lines};
130     }
131
132     # if nothing else return
133     return('', 'empty')
134       unless ($#{$lines} >= 0);
135
136     # deal with example chunks
137     if ($lines->[0] =~ /^(\=\=\>\s+)\S/) {
138         $offlen = length($1);
139         while (($#{$lines} >= 0) && (defined($lines->[0]))) {
140             my $txt = substr(shift @{$lines}, $offlen);
141             $ret .= (defined($ret)) ? "\n$txt" : $txt;
142         }
143         return ($ret, 'code');
144     }
145
146     my $skipone;
147     # deal with rest - numeric lines first
148     if ($lines->[0] =~ /^(\s+\(\d+\)\s*)/) {
149         $offlen = length($1);
150         $flags = 'numlist';
151         $skipone = 0;
152     } elsif ($lines->[0] =~ /^(\s+)\S/) {
153         $offlen = length($1);
154         $flags = 'normal';
155         $skipone = 0;
156     } else {
157         $offlen = 7;
158         $flags = 'normal';
159         $skipone = 1;
160     }
161
162     while (($#{$lines} >= 0) && (defined($lines->[0]))) {
163         my $txt = $skipone ?
164           shift @{$lines} :
165             substr(shift @{$lines}, $offlen);
166         $ret .= $txt;
167         $ret .= ' ';
168         $skipone = 0;
169     }
170     return ($ret, $flags);
171 }
172
173 \f
174
175 sub format_wiki_text ($$) {
176     my $meta = shift;
177     my $lp = shift;
178
179     my @lines = @{$lp};
180
181     my $out;
182     while ($#lines >= 0) {
183         my($para, $flags) = clip_paragraph(\@lines);
184         if ($flags eq 'code') {
185             $out .= "{{{\n" . $para . "\n}}}\n";
186         } elsif ($flags eq 'numlist') {
187             $out .= ' 1. ' . wiki_markup($meta, $para) . "\n";
188         } elsif ($flags eq 'empty') {
189         } else {
190             $out .= wiki_markup($meta, $para) . "\n";
191         }
192     }
193     return $out;
194 }
195
196 \f
197
198 sub output_wiki_header ($$$) {
199     my $fh = shift;
200     my $meta = shift;
201     my $qset = shift;
202
203     $fh->print(join("\n",
204                     '##language:en',
205                     '#pragma section-numbers off',
206                     '## Autogenerated by f2wiki',
207                     join('', '["FAQ"] / [:', 
208                          $qset->{section}->{wikiname},
209                          ':',
210                          $qset->{section}->{title},
211                          '] / ',
212                          $qset->{qtag}),
213                     '----',
214                     '[[Navigation(siblings)]]',
215                     '----',
216                     ''));
217 }
218
219 \f
220
221 sub output_wiki_question ($$$$) {
222     my $fh = shift;
223     my $meta = shift;
224     my $qset = shift;
225     my $lines = shift;
226
227     $fh->print(join("\n",
228                     ('= ' . $qset->{qtag} . ' ='),
229                     '',
230                     '=== Question ===',
231                     '##qstart',
232                     format_wiki_text($meta, $lines),
233                     '##qend',
234                     ''));
235 }
236
237 \f
238
239 sub output_wiki_answer ($$$$) {
240     my $fh = shift;
241     my $meta = shift;
242     my $qset = shift;
243     my $lines = shift;
244
245     $fh->print(join("\n",
246                     '=== Answer ===',
247                     format_wiki_text($meta, $lines),
248                     ''));
249 }
250
251 \f
252
253 sub output_wiki_trailer ($$$) {
254     my $fh = shift;
255     my $meta = shift;
256     my $qset = shift;
257
258     $fh->print(join("\n",
259                     '----',
260                     '[[Navigation(siblings)]]',
261                     '----',
262                     join('', '["FAQ"] / [:', 
263                          $qset->{section}->{wikiname},
264                          ':',
265                          $qset->{section}->{title},
266                          '] / ',
267                          $qset->{qtag}),
268                     '----',
269                     'CategoryFrequentlyAskedQuestions',
270                     ''));
271 }
272
273 \f
274
275 sub build_tocs ($) {
276     my $meta = shift;
277
278     my $tfh = IO::File->new('FAQ', 'w');
279     my @sections = sort { $a->{num} <=> $b->{num} }
280       values %{$meta->{sections}};
281     foreach my $sect (@sections) {
282         my $fh = IO::File->new($sect->{wikifile}, 'w');
283         $fh->print(join("\n",
284                         '##language:en',
285                         '#pragma section-numbers off',
286                         '## Autogenerated by f2wiki',
287                         join('', '["FAQ"] / [:', 
288                              $sect->{wikiname},
289                              ':',
290                              $sect->{title},
291                              '] '),
292                         '----',
293                         '[[Navigation(siblings,1)]]',
294                         '----',
295                         '[[Navigation(children)]]',
296                         '----',
297                         '',
298                         '',
299                        '= ' . $sect->{title} . ' =',
300                        '',
301                        join('',
302                             '[[Include(^',
303                             $sect->{wikiname},
304                             '/.*,,2,from="##qstart",to="##qend")]]'),
305                         '',
306                         '----',
307                         '[[Navigation(siblings,1)]]',
308                         '----',
309                         '[[Navigation(children)]]',
310                         '----',
311                         join('', '["FAQ"] / [:', 
312                              $sect->{wikiname},
313                              ':',
314                              $sect->{title},
315                              '] '),
316                         '----',
317                         'CategoryFrequentlyAskedQuestions',
318                         ''));
319
320         $tfh->print(' * [:', $sect->{wikiname}, ':', $sect->{title}, "]\n");
321     }
322 }
323
324 \f
325
326 sub process_qset ($$$$) {
327     my $meta = shift;
328     my $qset = shift;
329     my $qlines = shift;
330     my $alines = shift;
331
332     unless ($qset->{wikifile}) {
333         print(join("\n#",
334                    $qset->{qtag},
335                    $qset->{wikiname},
336                    $qset->{wikifile}),
337               "\n");
338         return;
339     }
340     my $fh = IO::File->new($qset->{wikifile}, 'w') ||
341       die "$qset->{wikifile} OUT $!";
342     output_wiki_header($fh, $meta, $qset);
343     output_wiki_question($fh, $meta, $qset, $qlines);
344     output_wiki_answer($fh, $meta, $qset, $alines);
345     output_wiki_trailer($fh, $meta, $qset);
346 }
347
348 \f
349
350 sub parse_faqsrc ($$) {
351     my $fh = shift;
352     my $meta = shift;
353
354     my $section;
355     my $sect;
356
357     while(<$fh>) {
358         chomp;
359         unless(defined($section)) {
360             unless (/^\d+\.\s/) {
361                 if (/^\s+\d+\./) {
362                     my($junk,
363                        $secnum,
364                        $sectitle) = split(/\s+/, $_, 3);
365                     $secnum =~ tr/0-9//cd;
366                     my $wikiname = mkwikiname('FAQ', $sectitle);
367                     my $wikifile = mkwikifilename($wikiname);
368                     $meta->{sections}->{$secnum} =
369                       {title    => $sectitle,
370                        num      => $secnum,
371                        wikiname => $wikiname,
372                        wikifile => $wikifile,
373                        qtags    => []};
374                 }
375                 next;
376             }
377         }
378         if (/^(\d+)\.\s/) {
379             $section = $1;
380             $sect = $meta->{sections}->{$section};
381             $sect->{seen}++;
382         } elsif (/^(Q\d+):/) {
383             my $qtag = $1;
384             my $wikiname = mkwikiname('FAQ', $sect->{title}, $qtag);
385             my $wikifile = mkwikifilename($wikiname);
386             my $qset = {section         => $sect,
387                         qtag            => $qtag,
388                         wikiname        => $wikiname,
389                         wikifile        => $wikifile};
390             $meta->{qtags}->{$qtag} = $qset;
391             push(@{$sect->{qtags}}, $qset);
392         }
393     }
394 }
395
396 \f
397
398 sub process_faqsrc ($$) {
399     my $fh = shift;
400     my $meta = shift;
401
402     my $qset;
403     my $qlines = [];
404     my $alines = [];
405     my $clines = $qlines;
406
407     while(<$fh>) {
408         chomp;
409         next if (/^#/);
410         # skip preceding stuff....
411         unless(defined($qset)) {
412             next unless (/^Q\d+/);
413         }
414
415         if (/^(\d+)\.\s/) {
416             # just skip section boundaries - we have done those before
417             next;
418         } elsif (/^([QA]\d+):\s+(.+)$/) {
419             my $qtag = $1;
420             my $line = $2;
421             if (substr($1, 0, 1) eq 'Q') {
422                 process_qset($meta, $qset, $qlines, $alines);
423                 $qlines = [];
424                 $alines = [];
425                 $clines = $qlines;
426                 $qset = $meta->{qtags}->{$qtag};
427             } else {
428                 $clines = $alines;
429             }
430             push(@{$clines}, $line);
431         } elsif (/^\s*$/) {
432             push(@{$clines}, undef);
433         } else {
434             push(@{$clines}, $_);
435         }
436     }
437     # mop up last q&a
438     process_qset($meta, $qset, $qlines, $alines);
439
440     # now build the tocs
441     build_tocs($meta);
442 }
443
444 \f
445
446 # main
447 {
448     my $section;
449
450     my $fh = IO::File->new(shift, 'r') || die $!;
451     my $state = {};
452     parse_faqsrc($fh, $state);
453     $fh->seek(0,0);
454 #    print Dumper($state);
455     process_faqsrc($fh, $state);
456
457 }
458
459 # -*-perl-*-