scripts/gen-FAQ.pl

   1 #! /usr/bin/perl
   2
   3 =pod
   4 This is a silly little program for generating the libc FAQ.
   5
   6 The input format is:
   7 top boilerplate
   8 ^L
   9 ? section name (one line)
  10 ?? question...
  11 ...
  12 {ID} answer...
  13 ...
  14 ^L
  15 {ID} name <email@address>
  16 ...
  17
  18 which gets mapped to:
  19
  20 top boilerplate
  21 ^L
  22 1. section 1...
  23 1.1. q1.1
  24 1.2. q1.2
  25 ...
  26 ^L
  27 1. section 1...
  28
  29 1.1. q1.1
  30
  31 answer 1.1....
  32
  33
  34 ^L
  35 Answers were provided by:
  36 ...
  37
  38 =cut
  39
  40 # We slurp the whole file into a pair of assoc arrays indexed by
  41 # the 'section.question' number.
  42 %questions = ();
  43 %answers = ();
  44 $question = 0;
  45
  46 # These arrays and counter keep track of the sections.
  47 @sectcount = ();
  48 @sections = ();
  49 $section = 0;
  50
  51 # Cross reference list.
  52 %refs = ();
  53
  54 # Separators.
  55 $sepmaj = "\f\n" . ('~ ' x 36) . "\n\n";
  56 $sepmin = "\f\n" . ('. ' x 36) . "\n\n";
  57
  58 # Pass through the top boilerplate.
  59 while(<>)
  60 {
  61     last if $_ eq "\f\n";
  62     print;
  63 }
  64
  65 # Now the body.
  66 while(<>)
  67 {
  68     /\f/ && do
  69     {
  70         $sectcount[$section] = $question;
  71         last;
  72     };
  73
  74     s/^\?\s+// && do
  75     {
  76         chomp;
  77         $sectcount[$section] = $question if $section > 0;
  78         $section++;
  79         $sections[$section] = $_;
  80         $question = 0;
  81         next;
  82     };
  83     s/^\?\?(\w*?)\s+// && do
  84     {
  85         $cur = \%questions;
  86         $question++;
  87         $questions{$section,$question} = $_;
  88         $refs{$1} = "$section.$question" if $1 ne "";
  89         next;
  90     };
  91     /^\{/ && do
  92     {
  93         $cur = \%answers;
  94         $answers{$section,$question} .= $_;
  95         next;
  96     };
  97
  98     ${$cur}{$section,$question} .= $_;
  99 }
 100
 101 # Now we have to clean up the newlines and deal with cross references.
 102 foreach(keys %questions) { $questions{$_} =~ s/\n+$//; }
 103 foreach(keys %answers)
 104 {
 105     $answers{$_} =~ s/\n+$//;
 106     $answers{$_} =~ s/(\s)\?(\w+)\b/$1 . "question " . ($refs{$2} or badref($2,$_), "!!$2")/eg;
 107 }
 108
 109 # Now output the formatted FAQ.
 110 print $sepmaj;
 111 for($i = 1; $i <= $section; $i++)
 112 {
 113     print "$i. $sections[$i]\n\n";
 114     for($j = 1; $j <= $sectcount[$i]; $j++)
 115     {
 116         print "$i.$j.\t$questions{$i,$j}\n";
 117     }
 118     print "\n";
 119 }
 120
 121 print $sepmaj;
 122 for($i = 1; $i <= $section; $i++)
 123 {
 124     print "$i. $sections[$i]\n\n";
 125     for($j = 1; $j <= $sectcount[$i]; $j++)
 126     {
 127         print "$i.$j.\t$questions{$i,$j}\n\n";
 128         print $answers{$i,$j}, "\n\n";
 129         print "\n" if $j < $sectcount[$i];
 130     }
 131     print $sepmin if $i < $section;
 132 }
 133
 134 print $sepmaj;
 135
 136 # Pass through the trailer.
 137 while(<>) { print; }
 138
 139 sub badref
 140 {
 141     my($ref,$quest) = @_;
 142     $quest =~ s/$;/./;
 143     print STDERR "Undefined reference to $ref in answer to Q$quest\n";
 144 }