doc/generate_FAQ.pl

   1 #!/usr/bin/perl
   2
   3 $test_data = "";
   4 # uncomment the following to run from named file
   5 #$test_data = "sample.txt";
   6
   7 $faq_url = "http://www.freeciv.org/wiki/FAQ";
   8 $faq_file = "FAQ";
   9
  10 @sections;
  11 @sectStrings;
  12
  13 @content;
  14 $contentLine;
  15 $EOD = 0;
  16 $line;
  17 @graph;
  18
  19 open(FILE, ">$faq_file") || die ("Cannot open file $faq_file for writing.\n");
  20
  21 # collect input data
  22 &init_data;
  23
  24 # read data and write toc
  25 &processToc;
  26
  27 &processAnswers;
  28
  29 close(FILE);
  30
  31 print "File $faq_file has been written successfully\n";
  32
  33 # collect table of contents
  34 sub processToc
  35 {
  36
  37   # clear to FAQ
  38   if ( &clearTo("FAQ") || &clearTo("Contents") ) { die "No TOC found\n"; }
  39
  40   # dump TOC
  41
  42   # header
  43   print FILE <<HEND;
  44                   Freeciv Frequently Asked Questions (FAQ)
  45
  46                  (from $faq_url)
  47
  48    Contents
  49
  50 HEND
  51
  52   for ( ; ; )
  53   {
  54     &readLine || die "Data runout reading TOC\n";
  55     if ( $line =~ /^\s*$/ )
  56     {
  57       print FILE "\n";
  58       return;
  59     }
  60     if ( $line =~ /^\s*(.) ([\.\d]+) (.+)$/ )
  61     {
  62       #handle section or question
  63       my $type = $1;
  64       my $num = $2;
  65       my $name = $3;
  66       my $pattern = " \\$type";
  67       $line =~ s/$pattern//;
  68       if ( $type eq "*" )
  69       {
  70         push( @sections, $name );
  71         my $l = @sections;
  72         if ( $l != $num ) { die "Section $l number is $num\n"; }
  73         push( @sectStrings, [] );
  74       }
  75       else
  76       {
  77         my $ref = $sectStrings[-1];
  78         push( @$ref, $num );
  79       }
  80     }
  81     print FILE "$line\n";
  82   }
  83
  84 }
  85
  86 sub clearTo
  87 {
  88   for ( ; ; )
  89   {
  90     &readLine  || return 1;
  91     if ( $line =~ /^\s*$_[0]$/ ) { last; }
  92   }
  93   &processBlankLine;
  94 }
  95
  96 # get line, required blank
  97 sub processBlankLine
  98 {
  99   if ( ! &readLine ) { die "Data runout in processBlankLine\n"; }
 100   if ( $line!~/^\s*$/ ) { die "processBlankLine read '$line'\n"; }
 101 }
 102
 103 # write answer section
 104 sub processAnswers
 105 {
 106   my $ix = 0;
 107   my $sName;
 108   my @nums;
 109   while ( ! $EOD ) {
 110     my $type = &readGraph;
 111     # handle section or question
 112     if ( $type == 2 )
 113     {
 114       print FILE "-------\n\n";
 115       if ( $graph[0] eq $sections[$ix] )
 116       {
 117         $sName = $sections[$ix];
 118         my $nr = $sectStrings[$ix];
 119         @nums = @$nr;
 120         ++$ix;
 121         &writeGraph( $ix );
 122       }
 123       else
 124       {
 125         my $num = shift( @nums );
 126         &writeGraph( $num );
 127       }
 128     }
 129     else
 130     {
 131       &writeGraph();
 132     }
 133   }
 134 }
 135
 136 # read paragraph, return type
 137 #   0: end of answers
 138 #   1: other (part of answer)
 139 #   2: section or question
 140 sub readGraph
 141 {
 142   &readLine  || die "Data runout in readGraph\n";
 143   if ( $line eq "" ) { die "Expecting graph, read blank line\n"; }
 144   @graph = ( $line );
 145   if ( $line =~ /^\s*^_+$/ ) { return 0; }
 146   # read rest of graph
 147   for ( ; ; )
 148   {
 149     &readLine  || die "Data runout in readGraph\n";
 150     if ( $line eq "" ) { last; }
 151     if ( $line !~ /^\s*_+$/ )
 152     {
 153       push( @graph, $line );
 154     }
 155     else
 156     {
 157       $EOD = 1;
 158       last;
 159     }
 160   }
 161   # test edit tag
 162   if ( &editTag ) { return 2; }
 163   1;
 164 }
 165
 166 # test for and remove edit tag
 167 sub editTag
 168 {
 169   # look for on last line
 170   if ( $graph[-1] =~ s/ \[[^]]*\] Edit$// ) { return 1; }
 171   if ( 2 > @graph ) { return 0; }
 172   if ( $graph[-1] =~ m/^\[[^]]*\] Edit$/ )
 173   {
 174     pop( @graph );
 175     return 1;
 176   }
 177   # look for split
 178   if ( $graph[-1]eq"Edit" && $graph[-2]=~s/ \[[^]]*\]$// )
 179   {
 180     pop( @graph );
 181     return 1;
 182   }
 183   return 0;
 184 }
 185
 186 # write paragraph
 187 sub writeGraph
 188 {
 189   if ( defined $_[0] ) { print FILE "$_[0] "; }
 190   while ( @graph )
 191   {
 192     my $data = shift( @graph );
 193     print FILE "$data\n";
 194   }
 195   print FILE "\n";
 196 }
 197
 198 # pseudo-i/o methods
 199
 200 # 'open' data 'file'
 201 sub init_data
 202 {
 203   $contentLine = 0;
 204   if ( $test_data ) {
 205     print "using test data $test_data\n";
 206     open ( MYDATA, $test_data );
 207     @content = <MYDATA>;
 208     close MYDATA;
 209   } else {
 210     print "using url $faq_url\n";
 211     @content = `lynx -nolist -dump "$faq_url"`;
 212   }
 213   my $count = @content;
 214   print( "$count lines of content\n" );
 215 }
 216
 217 # 'read' data line
 218 sub readLine
 219 {
 220   if ( $contentLine < @content )
 221   {
 222     $line = $content[$contentLine++];
 223     $line =~ s/\s+$//;
 224     1;
 225   }
 226   else
 227   {
 228     0;
 229   }
 230 }