doc/doc-scripts/g2t

   1 #! /usr/bin/perl -w
   2 # $Cambridge: exim/doc/doc-scripts/g2t,v 1.2 2005/01/27 10:25:35 ph10 Exp $
   3
   4 # A Perl script to turn the SGCAL source of the Exim documentation into
   5 # Texinfo input, more or less...
   6
   7 # Supply the source file names as arguments.
   8 # The output goes to the standard output.
   9
  10
  11 ##################################################
  12 #         Ensure unique node name                #
  13 ##################################################
  14
  15 # Node names must be unique. Occasionally in the Exim spec there are duplicate
  16 # section names, and it's become too much of a hassle to keep them distinct
  17 # manually. So it is now automated.
  18
  19 ########### Never really got this working. Abandoned ###############
  20
  21 sub unique {
  22 my($node) = $_[0];
  23 if (defined $node_names{$node})
  24   {
  25   $node_names{$node} += 1;
  26   $node = "$node ($node_names{$node})";
  27
  28 print STDERR "+++ $node\n";
  29
  30   }
  31 else
  32   {
  33   $node_names{$node} = 0;
  34   }
  35 $node;
  36 }
  37
  38
  39
  40 ##################################################
  41 #         De-comma a node name                   #
  42 ##################################################
  43
  44 # Commas, colons, and apostrophes are not permitted in Texinfo
  45 # node names. I find this incredible, but it is clearly documented.
  46 # The Exim manual has been re-organized not to have colons or
  47 # apostrophes in any chapter or section titles, but I can't manage
  48 # without commas. This function turns "," into " and", which is
  49 # the best that can be done; we can use some clever Perlery to
  50 # just take out commas before "and".
  51
  52 # Sigh. The Sendmail option -p<rval>:<sval> now means that there's a colon
  53 # in the node name for that option. Turn the colon into <colon>. This is also
  54 # done for menus.
  55
  56 # Another thing that causes problems in node names in some versions of
  57 # Texinfo is the use of @sc{xxx} for small caps. Just turn these all into
  58 # real caps. This is also done for menus.
  59
  60 sub decomma {
  61 $_[0] =~ s/,(?!\sand)/ and/g;
  62 $_[0] =~ s/,//g;
  63 $_[0] =~ s/\@sc\{([^}]*)\}/\U$1/g;
  64 $_[0] =~ s/:/<colon>/g;
  65 $_[0];
  66 }
  67
  68
  69
  70 ##################################################
  71 #           De-quote a string                    #
  72 ##################################################
  73
  74 # @x is turned into x, except when x=@, or when asis is set,
  75 # in which case single @ must turn into @@. A single substitute
  76 # doesn't work in the non-asis case, because of the problems of
  77 # handling things like @@@$, so we do it the hard way.
  78
  79 sub dequote {
  80 if ($asis) { $_[0] =~ s/@/@@/g; } else
  81   {
  82   $_[0] =~ s/@@/&at&/g;
  83   $_[0] =~ s/@([^@])/$1/g;
  84   $_[0] =~ s/&at&/@@/g;
  85   }
  86 $_[0];
  87 }
  88
  89
  90 ##################################################
  91 #           Get next line                        #
  92 ##################################################
  93
  94 # Called from handle_directive, to get the next source line
  95 # into $_.
  96
  97 sub get_next_line {
  98 if ($processing_subsection)
  99   { return $_ = shift @SUBBUFFER; }
 100 else
 101   { return $_ = <>; }
 102 }
 103
 104
 105
 106 ##################################################
 107 #           Handle text lines                    #
 108 ##################################################
 109
 110 # This function is handed whole paragraphs, and we assume that
 111 # SGCAL font changing markup is always complete within a paragraph.
 112 # We have to replace escaped versions of significant characters with
 113 # some magic before performing general transformations, and then
 114 # put them back afterwards. The character & is not common in the text,
 115 # and && is unknown, so we use that.
 116
 117 sub handle_text {
 118 $_ = $_[0];
 119
 120 if ($asis)
 121   {
 122   $_ = dequote($_);
 123   s/(\{|\})/\@$1/g;
 124   return $_;
 125   }
 126
 127 while (/~~/)
 128   {
 129   $left = $`;
 130   ($name) = $' =~ /^(\w+)/;
 131   $right = $';
 132
 133   $value = $references{$name};
 134   $value = "" if !defined($value);
 135
 136   if ($value =~ /\*\*\*\*/)
 137     {
 138     $value = ($` eq $current_chapter)? "\"$'\"" :
 139       "\"$'\" in chapter \"$`\"";
 140     $value = "" if $value eq "\"\"";
 141     }
 142   elsif ($value !~ /^[0-9]+\.[0-9]+$/)   # quote unless version number
 143     {
 144     $value = "\"$value\"";
 145     }
 146
 147   $_ = "${left}${value}${right}";
 148   }
 149
 150 s/\@\@/&&a/g;         # @@
 151 s/\@\\/&&b/g;         # @\
 152 s/\@</&&l/g;          # @<
 153 s/\@>/&&g/g;          # @>
 154 s/\@\{/&&c/g;         # @{
 155 s/\@\}/&&d/g;         # @}
 156 s/\@#/&&s/g;          # @#
 157
 158 # Now remove all other @'s
 159
 160 $_ = dequote($_);
 161
 162 # Convert SGCAL markup
 163
 164 s/#/ /g;                            # turn #   into a space
 165 s/\$~//g;                           # turn $~  into nothing
 166 s/__/_/g;                           # turn __  into _
 167 s/\$sm\{//g;                        # turn $sm{     into nothing
 168 s/\$sc\{([^\}]*?)\}/$1/g;           # turn $sc{xxx} into xxx
 169 s/\$st\{([^\}]*?)\}/$1/g;           # turn $st{xxx} into xxx
 170 s/\$si\{([^\}]*?)\}/$1/g;           # turn $si{xxx} into xxx
 171 s/\$tt\{([^\}]*?)\}/$1/g;           # turn $tt{xxx} into xxx
 172
 173 s/\$it\{([^\}]*?)\}/$1/g;           # turn $it{xxx} into xxx
 174
 175 s/\$bf\{([^\}]*?)\}/$1/g;           # turn $bf{xxx} into xxx
 176 s/\$rm\{([^\}]*?)\}/$1/g;           # turn $rm{xxx} into xxx
 177 s/\$cb\{([^\}]*?)\}/$1/g;           # turn $cb{xxx} into xxx
 178
 179 # This is a fudge for some specific usages of $<; can't just do a global
 180 # is it occurs in things like $<variable name> as well.
 181
 182 s/\[\$<\]/[]/g;                     # turn [$<]     into []
 183 s/&&b\$<\./&&b./g;                  # turn \$<.     into \.  (\ == &&b by now)
 184 s/(\d)\$<-/$1-/g;                   # turn 0$<-     into 0-
 185
 186 # There is one case where the terminating } of an escape sequence is
 187 # in another paragraph - this follows $sm{ - it can be fixed by
 188 # removing any stray } in a paragraph that contains no { chars.
 189
 190 s/\}//g if !/\{/;
 191
 192 # Any remaining {} must be escaped to prevent Texinfo from complaining
 193
 194 s/(\{|\})/\@$1/g;
 195
 196 # Now to conversions that put {} into the file.
 197 # Change <<..>> from @var to just <...> as the caps that Texinfo
 198 # uses look far too shouty.
 199
 200 s/\\\\([^\\]*?)\\\\/\@sc\{\L$1\}/g; # turn \\xxx\\  into @sc{xxx}
 201 s/\\\(([^)]*?)\)\\/\@file\{$1\}/g;  # turn \(xxx)\  into @file{xxx}
 202 s/\\\"([^\"]*?)\"\\/\@file\{$1\}/g; # turn \"xxx"\  into @file{xxx}
 203
 204 s/\\\?([^?]*?)\?\\/$1/g;            # turn \?URL?\    into URL
 205 s/<<([^>]*?)>>/<$1>/g;              # turn <<xxx>>    into <xxx>
 206 s/\\\$([^\$]*?)\$\\/\$$1/g;         # turn \$xxx$\    into $xxx
 207 s/\\\-([^-]*?)\-\\/\-$1/g;          # turn \-xxx-\    into -xxx
 208 s/\\\*\*([^*]*?)\*\*\\/$1/g;        # turn \**xxx**\  into xxx
 209 s/\[\(([\w\/]*)\)\]//g;             # remove inline HTML
 210
 211 s/\\\*([^*]*?)\*\\/\@dfn\{$1\}/g;     # turn \*xxx*\    into @dfn{xxx}
 212 s/\\%([^*]*?)%\\/\@dfn\{$1\}/g;       # turn \%xxx%\    into @dfn{xxx}
 213 s/:::([^:]*?)::/\@dfn\{:$1:\}/g;      # turn :::xxx::   into @dfn{:xxx:}
 214 s/::([^:]*?)::/\@dfn\{$1:\}/g;        # turn ::xxx::    into @dfn{xxx:}
 215 s/\\([^\\]*?)\\/\@dfn\{$1\}/g;        # turn \xxx\      into @dfn{xxx}
 216 s/\$\*\$/\*/g;                        # turn $*$        into *
 217
 218 # Put back escaped SGCAL specials
 219
 220 s/&&a/\@\@/g;
 221 s/&&b/\\/g;
 222 s/&&l/</g;
 223 s/&&g/>/g;
 224 s/&&c/\@{/g;
 225 s/&&rc/{/g;
 226 s/&&rd/}/g;
 227 s/&&d/\@}/g;
 228 s/&&s/#/g;
 229
 230 # Remove any null flags ($$)
 231
 232 s/\$\$//g;
 233
 234 # If the paragraph starts with $c\b, change this into @center. Assume
 235 # we don't ever get two of these in a row.
 236
 237 s/^\$c\b/\@center /;
 238
 239 # If the paragraph starts with $e\b, stuff some tabs in there, as
 240 # Texinfo can't do this on its own (as far as I can see). They must
 241 # tabs; Texinfo treats them as different to spaces. Sigh.
 242
 243 s/^\$e\b/\t\t\t\t\t\t\t/;
 244
 245 # Handle $t. The Exim spec only ever has one tab per line. Er, not
 246 # quite true, but a good enough assumption. $t is always followed
 247 # by a non-word character.
 248
 249 # The .tabs directive has stashed the value in the $tab variable.
 250 # Don't count Texinfo font chars.
 251
 252 while (/(^|.+?\n)(.+?)\$t(\W.*\n)/)
 253   {
 254   $before = $` . $1;
 255   $after = $';
 256   $left = $2;
 257   $right = $3;
 258
 259   $left =~ s/\s$//;
 260   $right =~ s/^\s+//;
 261
 262   $plainleft = $left;
 263   $plainleft =~ s/\@[a-z]+\{([^}]+?)\}/$1/g;
 264   $plainleft =~ s/\@//g;
 265
 266   $_ = $before . $left . (" " x ($tab - length($plainleft))) . $right . $after;
 267
 268   # Fudge for the one case where there are two tabs
 269
 270   if ($tab2 != 0)
 271     {
 272     $temp = $tab;
 273     $tab = $tab2;
 274     $tab2 = $temp;
 275     }
 276   }
 277
 278 # Return the new line (paragraph)
 279
 280 $_;
 281 }
 282
 283
 284
 285 ##################################################
 286 #           Handle directive lines               #
 287 ##################################################
 288
 289 # Use get_next_line() instead of <> because this is called to process
 290 # stacked up subsection lines
 291
 292 sub handle_directive {
 293
 294 my($new_lastwasitem) = 0;
 295
 296 # Chapter directives just require . => @; however, dequoting the
 297 # line thereafter will remove the first @, so just force it back
 298 # afterwards. If the chapter is is one describing a driver, set
 299 # the driver name.
 300
 301 if (/\.chapter/)
 302   {
 303   tr/./@/;
 304   push(@ONESECTION, "@" . &dequote("$_\n"));
 305   $driver_name = (/The\s+(\S+)\s+(director|router|transport|authenticator)/)? $1 :
 306     (/Generic options common to both directors and routers/)?
 307       "director or router" :
 308     (/[Gg]eneric\s+options for (\S+)s/)? $1 : "";
 309   $driver_name = &dequote($driver_name);
 310   }
 311
 312 # Section directives just require . => @; however, dequoting the
 313 # line thereafter will remove the first @, so just force it back
 314 # afterwards. Remove any colons in section titles as they cause
 315 # Texinfo trouble. Also remove any \\ (small caps) markup, which
 316 # appears in a couple of cases.
 317
 318 elsif (/\.section/)
 319   {
 320   tr/./@/;
 321   s/://;
 322   s"\\\\""g;
 323   push(@ONESECTION, "@" . &dequote("$_\n"));
 324
 325   # Horrible magic fudge to cope with the fact that exim_lock has
 326   # -v and -q options, just like the main program.
 327
 328   $driver_name = "exim_lock" if /Mailbox maintenance/;
 329
 330   # Similar magic for exiqgrep, which also duplicates options
 331
 332   $driver_name = "exiqgrep" if /Selective queue listing/;
 333   }
 334
 335 # .newline must put @* on the end of the previous line, if any, except
 336 # inside a display, where it causes trouble.
 337
 338 elsif (/\.newline/)
 339   {
 340   if (@ONESECTION > 0 && ! $indisplay)
 341     {
 342     $_ = pop(@ONESECTION);
 343     s/(\n*)$/\@*$1/;
 344     push(@ONESECTION, $_);
 345     }
 346   }
 347
 348 # .blank turns into @sp, adding 1 if no argument
 349
 350 elsif (/\.blank/)
 351   {
 352   s/\.blank\s+(\d+)/\@sp $1/;
 353   s/\.blank/\@sp 1/;
 354   push(@ONESECTION, $_);
 355   }
 356
 357 # .rule turns into a line of hyphens
 358
 359 elsif (/\.rule/)
 360   {
 361   push(@ONESECTION, ("-" x ($in_itemize? 68 : 73)) . "\@*\n");
 362   }
 363
 364 # There's one explicit .tabset setting for two tab stops
 365
 366 elsif (/\.tabset\s*/)
 367   {
 368   $rest = $';
 369   ($first,$second) = $rest =~ /(\d+)em\s+(\d+)em/;
 370   $tab = ($first * 7)/6;
 371   $tab2 = $tab + ($second * 7)/6;
 372   }
 373
 374 # .tabs remembers the first (and only) tab setting
 375
 376 elsif (/\.tabs\s*/)
 377   {
 378   $tab = ($' * 7)/6;
 379   $tab2 = 0;
 380   }
 381
 382 # .tempindent is used only to align some of the expansion stuff nicely;
 383 # just ignore it. It is used in conjunction with .push/.pop.
 384
 385 elsif (/\.(tempindent|push|pop)\s*/)
 386   {
 387   }
 388
 389 # There are some instances of .if ~~sys.fancy in the source. Some of these
 390 # are two-part things, in which case we just keep the non-fancy. For diagrams,
 391 # however, they are in three parts:
 392 #
 393 # .if ~~sys.fancy
 394 # <aspic drawing stuff>
 395 # .elif ~~nothtml
 396 # <ascii art for txt and Texinfo>
 397 # .else
 398 # <HTML instructions for including a gif>
 399 # .fi
 400
 401 elsif (/\.if \~\~sys\.fancy/)
 402   {
 403   while (&get_next_line())
 404     { last if /\.else\b/ || /\.elif\s+\~\~nothtml/ || /\.fi\b/; }
 405
 406   if (/\.elif/)
 407     {
 408     $skip_else = 1;
 409     }
 410   }
 411
 412 # There are occasional requirements to do things differently for
 413 # Texinfo/HTML and the PS/txt versions, and there are also some
 414 # HTML-specific things.
 415
 416 elsif (/\.if\s+~~sgcal/ || /\.if\s+~~html/)
 417   {
 418   while (&get_next_line()) { last if /\.else\b/ || /\.fi\b/; }
 419   }
 420
 421 # We may also have Texinfo-specific bits
 422
 423 elsif (/^\.if\s+~~texinfo/)
 424   {
 425   $skip_else = 1;
 426   }
 427
 428 # Ignore any other .if directives
 429
 430 elsif (/\.if/) {}
 431
 432 # Skip else part if flag set
 433
 434 elsif (/\.else/ && $skip_else)
 435   {
 436   while (&get_next_line()) { last if /\.fi\b/; }
 437   $skip_else = 0;
 438   }
 439
 440 # Ignore other .fi and .else as any .if directives are handled specially
 441
 442 elsif (/\.fi/ || /\.else/) {}
 443
 444 # Ignore .indent
 445
 446 elsif (/\.indent/) {}
 447
 448 # Plain .index goes to @cindex - the "concept" index. Also, there
 449 # are some calls to vindex and findex in the SGCAL source - treated
 450 # as synonymous with .index - which are split into the equivalent
 451 # indexes here.
 452
 453 elsif (/\.(.?)index/)
 454   {
 455   $rest = $';
 456   $letter = ($1 eq "")? "c" : $1;
 457   tr/./@/;                           # .index -> @index
 458
 459   $rest =~ s/\\\(//g;                # Remove markup
 460   $rest =~ s/\)\\//g;
 461   $rest =~ s/\\%//g;
 462   $rest =~ s/%\\//g;
 463   $rest =~ s/\\\*//g;
 464   $rest =~ s/\*\\//g;
 465   $rest =~ s/\\"//g;
 466   $rest =~ s/"\\//g;
 467   $rest =~ s/:://g;
 468   $rest =~ s/\\-/-/g;
 469   $rest =~ s/-\\//g;
 470   $rest =~ s/~~//g;
 471
 472   $rest =~ tr/\\//d;                 # Remove \
 473
 474   $rest =~ s/\@\$/\$/g;              # @$  -> $
 475   $rest =~ s/\@_/_/g;                # @_  -> _
 476   $rest =~ s/\@\+/+/g;               # @+  -> +
 477   $rest =~ s/\$\*\$/\*/g;            # $*$ -> *
 478   $rest =~ s/\$([^\$]+)\$/\$$1/g;    # $x$ -> $x
 479
 480   $rest =~ s/^\s+//;                 # Remove leading spaces
 481   $rest =~ s/\s+$//;                 # Remove trailing spaces
 482   $rest =~ s/\|\|/:/;                # || -> :
 483   push(@ONESECTION, "\@${letter}index $rest\n");
 484
 485   # Duplicate entries for things that were listed as "x see y"
 486
 487   if (defined $indirections{$rest})
 488     {
 489     push(@ONESECTION, "\@${letter}index $indirections{$rest}\n");
 490     }
 491   }
 492
 493 # Various flavours of numberpars map to itemize and enumerate.
 494 # Haven't found a way of having a blank space 'bullet' yet, so
 495 # currently using minus.
 496
 497 elsif (/\.numberpars/)
 498   {
 499   $rest = $';
 500   $type = "enumerate";
 501   $flag = "";
 502
 503   if    ($rest =~ /\$\./)  { $flag = " \@bullet"; $type = "itemize" }
 504   elsif ($rest =~ /\" \"/) { $flag = " \@minus";  $type = "itemize"; }
 505   elsif ($rest =~ /roman/) { $flag = " a"; $type = "enumerate"; }
 506
 507   push(@ONESECTION, "\n\@$type$flag\n\n\@item\n");
 508   push(@ENDLIST, $type);
 509   $in_itemize++;
 510   }
 511
 512 elsif (/\.nextp/)
 513   {
 514   push(@ONESECTION, "\n\@item\n");
 515   }
 516
 517 elsif (/\.endp/)
 518   {
 519   $endname = pop(@ENDLIST);
 520   push(@ONESECTION, "\@end $endname\n\n");
 521   $in_itemize--;
 522   }
 523
 524 # The normal .display (typewriter font) => @example, while the rm
 525 # form goes to @display (no change of font). For Texinfo we need a
 526 # blank line after @display.
 527
 528 elsif (/\.display/)
 529   {
 530   $type = /rm/? "display" : "example";
 531   $asis = 1 if /asis/;
 532   $indisplay = 1;
 533   push(@ONESECTION, "\@$type\n\n");
 534   push(@ENDLIST, $type);
 535   }
 536
 537 elsif (/\.endd/)
 538   {
 539   $asis = 0;
 540   $indisplay = 0;
 541   $endname = pop(@ENDLIST);
 542   push(@ONESECTION, "\@end $endname\n\n");
 543   }
 544
 545 elsif (/\.conf/)
 546   {
 547   ($option, $type, $default) =
 548     /\.conf\s+(\S+)\s+("(?:[^"]|"")+"|\S+)\s+("(?:[^"]|"")+"|.*)/;
 549
 550   $option = &dequote($option);
 551
 552   # If $type ends with $**$ (turned into a dagger for PS version),
 553   # replace with ", expanded". Remove any surrounding quotes.
 554
 555   $type =~ s/^"([^"]+)"/$1/;
 556   $type =~ s/\$\*\*\$/, expanded/;
 557
 558   # Default may be quoted, and it may also have quotes that are required,
 559   # if it is a string.
 560
 561   $default =~ s/^"(.*)"$/$1/;
 562   $default =~ s/""/"/g;
 563   $default = &handle_text($default);
 564
 565   push(@ONESECTION, "\nType: $type\@*\nDefault: $default\n\n");
 566   }
 567
 568 # Handle .startitems, .enditems, and .item
 569
 570 elsif (/\.startitem/ || /\.enditem/) {}
 571
 572 elsif (/\.item/)
 573   {
 574   $arg = $';
 575   $arg =~ s/^\s*"//;
 576   $arg =~ s/"\s*$//;
 577   $arg = &dequote($arg);
 578   $arg = &handle_text("\\**$arg**\\");
 579
 580   # If there are two .items in a row, we don't want to put in the
 581   # separator line.
 582
 583 #  push(@ONESECTION, "\n\@example\n");
 584   push(@ONESECTION, "\n");
 585   if (! $lastwasitem)
 586     {
 587     push(@ONESECTION, "_" x 75, "\n\n");
 588     }
 589 #  push(@ONESECTION, "$arg\n\@end example\n\n");
 590   push(@ONESECTION, "$arg\n\n");
 591   $new_lastwasitem = 1;
 592   }
 593
 594 elsif (/\.option/)
 595   {
 596   chomp($arg = $');
 597   $arg =~ s/^\s*//;
 598   $arg = &dequote("-$arg");
 599   $arg = &handle_text($arg);
 600   }
 601
 602 # Texinfo has no facility for emphasis bars.
 603
 604 elsif (/\.em/) {}
 605 elsif (/\.nem/) {}
 606
 607 # Just ignore any .(r)set directives pro tem (or maybe always!)
 608
 609 elsif (/\.r?set/) {}
 610
 611 # Ignore .space, .linelength, and .justify
 612
 613 elsif (/\.space/ || /\.justify/ || /\.linelength/) {}
 614
 615 # Found an SGCAL directive that isn't dealt with. Oh dear.
 616 # Turn the embarrassing characters into question marks and
 617 # output it in an emphasized way.
 618
 619 else
 620   {
 621   tr/@{}/???/;
 622   push(@ONESECTION, "\n\>>>>>>> $_\n") if ! /^\.( |$)/;
 623   }
 624
 625 $lastwasitem = $new_lastwasitem;
 626 }
 627
 628
 629
 630 ##################################################
 631 #             Flush a section                    #
 632 ##################################################
 633
 634 # $section_name is the name of the next section.
 635 # $current_section is the name of the one we have buffered up.
 636 # If it is unset, we are at the first section of a chapter.
 637 # $previous_node is the section we last flushed if it was a node.
 638
 639 sub flush_section {
 640
 641 # If there is no text in the section, omit it entirely. However, it
 642 # will have had a pointer set up at the start of the previous section.
 643 # Remember what to replace this with when the chapter gets flushed.
 644
 645 my($skip) = 1;
 646 foreach $s (@ONESECTION)
 647   {
 648   if ($s !~ /^(\@cindex|\@section|\s*$)/) { $skip = 0; last }
 649   }
 650
 651 if ($skip)
 652   {
 653   pop @section_list;
 654   $rewrite{$current_section} = $section_name;
 655   @ONESECTION = ();
 656   return;
 657   }
 658
 659 # There is data in the section: write it out to the chapter file
 660
 661 if ($current_section)
 662   {
 663   printf ONECHAPTER ("\@node %s, %s, %s, %s\n",
 664     &decomma($current_section), &decomma($section_name),
 665     &decomma($previous_node), &decomma($current_up));
 666   $previous_node = $current_section;
 667   while(scalar(@ONESECTION))
 668     { print ONECHAPTER shift(@ONESECTION); }
 669   }
 670 else
 671   {
 672   while(scalar(@ONESECTION))
 673     { push(@TOPSECTION, shift(@ONESECTION)); }
 674   }
 675 }
 676
 677
 678
 679 ##################################################
 680 #          Handle a "subsection"                 #
 681 ##################################################
 682
 683 # A "subsection" is a set of options that must have their own
 684 # local menu. Do two passes; the first just collects the names
 685 # for the menu. This is called for .conf and .option items.
 686
 687 sub handle_subsection{
 688 my($type) = $_[0];
 689 my($save_up) = $current_up;
 690
 691 $current_up = $current_section? $current_section : $current_chapter;
 692
 693 @sublist = ();
 694 @SUBBUFFER = ();
 695
 696 while (<>)
 697   {
 698   last if /^\.end$type/;
 699   push(@SUBBUFFER, $_);
 700
 701   # .conf takes the first non-space string as the name, but as there are
 702   # duplicate confs in various parts of the spec, use the driver name to
 703   # de-duplicate; .option takes the entire rest of arg as the name, but
 704   # removes any sequence of ... because this disturbs TexInfo. Also, it
 705   # turns @- into -.
 706
 707   if (/^\.$type\s+(\S+)(.*)/)
 708     {
 709     if ($type eq "conf")
 710       {
 711       $name = &handle_text($1);
 712       $name .= " ($driver_name)" if ($driver_name ne "");
 713       }
 714     else
 715       {
 716       chomp($name = &handle_text("-$1$2"));
 717       $name =~ s/\s*\.\.\.//g;
 718
 719       $name .= " ($driver_name)" if ($driver_name ne "");
 720
 721       # There seems to be a major problem in texinfo with the string "--".
 722       # In the text it gets turned into a single hyphen. This happens if it
 723       # is used as a menu item, but *not* as a node name. Exim has a command
 724       # line option "--". With no special action, this appears in the menu
 725       # as "-", but then the info software complains there is no node called
 726       # "-". If we triple it in the menu it gets displayed OK, but building
 727       # software complains about non-existent cross references etc.
 728
 729       # I have gone for the horrid kludge of turning it into "-<hyhen>"
 730       # in the menus and nodes.
 731
 732       # Exim 4 has added --help, which has the same problem.
 733
 734       $name = "-<hyphen>" if ($name eq "--");
 735       $name = "-<hyphen>help" if ($name eq "--help");
 736       }
 737     push(@sublist, $name);
 738     }
 739   }
 740
 741 push (@ONESECTION, "\n\@sp 2\n\@menu\n");
 742 for ($i = 0; $i < scalar(@sublist); $i++)
 743   {
 744   $mitem = $sublist[$i];
 745   $mitem =~ s/\@sc\{([^}]*)\}/\U$1/g;       # Get rid of small caps
 746   $mitem =~ s/:/<colon>/g;                  # Get rid of colons
 747   push (@ONESECTION, "* ${mitem}::\n");
 748   }
 749 push (@ONESECTION, "\@end menu\n\n");
 750
 751 $prevsub = $current_up;
 752 $processing_subsection = 1;
 753 while ($_ = shift(@SUBBUFFER))
 754   {
 755   if (/^\.$type\s+(\S+)/)
 756     {
 757     $name = shift @sublist;
 758     $next = (scalar(@sublist))? $sublist[0] : "";
 759     push @ONESECTION, sprintf("\@node %s, %s, %s, %s\n",
 760       &decomma($name), &decomma($next), &decomma($prevsub),
 761       &decomma($current_up));
 762
 763     if ($name eq "-<hyphen>")    # Fudge for Texinfo
 764       {
 765       push(@ONESECTION,
 766            "\@findex $name\n",
 767            "\@unnumberedsubsec --- option\n");
 768       push(@ONESECTION,
 769            "This option consists of two consecutive hyphens. It appears in\n",
 770            "the menu as \"-<hyphen>\" because otherwise Texinfo gets\n",
 771            "confused with its cross-referencing.\n");
 772       }
 773     elsif ($name eq "-<hyphen>help")    # Fudge for Texinfo
 774       {
 775       push(@ONESECTION,
 776            "\@findex $name\n",
 777            "\@unnumberedsubsec ---help option\n");
 778       push(@ONESECTION,
 779            "This option consists of \"help\" preceded by two consecutive\n" .
 780            "hyphens. It appears in the menu as \"-<hyphen>help\" because\n" .
 781            "otherwise Texinfo gets confused with its cross-referencing.\n");
 782       }
 783     else
 784       {
 785       push(@ONESECTION,
 786            "\@findex $name\n",
 787            "\@unnumberedsubsec $name option\n");
 788       }
 789
 790     $prevsub = $name;
 791     }
 792
 793   # Then handle as text or directive
 794
 795   if (substr($_, 0, 1) eq ".")
 796     { handle_directive(); }
 797   else
 798     {
 799     while($nextline = shift(@SUBBUFFER))
 800       {
 801       last if $nextline =~ /^(\.|\s*$)/;
 802       $_ .= $nextline;
 803       }
 804     push(@ONESECTION, handle_text($_));
 805     $_ = $nextline;
 806     last if !defined($_);
 807     redo;
 808     }
 809   }
 810
 811 $processing_subsection = 0;
 812 $section_pending = 1;
 813 $current_up = $save_up;
 814 }
 815
 816
 817
 818
 819 ##################################################
 820 #            Handle a single chapter             #
 821 ##################################################
 822
 823 sub handle_chapter{
 824 chop;
 825 ($current_chapter) = /^\.chapter (.*)/;
 826 $current_chapter = &dequote($current_chapter);
 827
 828 $current_chapter = $current_chapter;
 829
 830 my($tmp) = $current_chapter;
 831 $tmp =~ s/\[\[\[\]\]\]/./;
 832 print STDERR "processing chapter: $tmp\n";
 833
 834 # Remember the chapter name for the top-level menu
 835
 836 push(@chapter_list, $current_chapter);
 837
 838 # Open a temporary file to hold the chapter's text while collecting
 839 # all its sections for a chapter-level menu.
 840
 841 $ONECHAPTER = "/tmp/ONECHAPTER.$$";
 842 open(ONECHAPTER, ">$ONECHAPTER") || die "Can't open $ONECHAPTER for writing";
 843
 844 # Initialize for handling sections
 845
 846 @section_list = ();
 847 %rewrite = ();
 848 @ONESECTION = ();
 849 @TOPSECTION = ();
 850 undef $current_section;
 851 undef $next_node;
 852
 853 $processing_subsection = 0;
 854
 855 $previous_node = $current_up = $current_chapter;
 856 $section_pending = 0;
 857
 858 # Handle the .chapter directive as the first text of a section without
 859 # a section title.
 860
 861 handle_directive();
 862
 863 # Loop, handling each section. Assume they are sufficiently short that
 864 # we can buffer the text in store, in an array called ONESECTION, instead
 865 # of thrashing yet another file.
 866
 867 while (<>)
 868   {
 869   last if /^\.chapter /;
 870
 871   # Handle a new section, preserving $_ (handle_text flattens it).
 872   # It seems we cannot get a fullstop into a Texinfo node name; use a magic
 873   # character string that gets turned back into a dot by the post-processing.
 874
 875   if (/^\.section\s+/)
 876     {
 877     $save = $_;
 878     $section_name = $';
 879     $section_name =~ s/(\s|\n)+$//;
 880     $section_name =~ s/://;
 881     $section_name = &handle_text($section_name);
 882     flush_section();
 883     push(@section_list, $section_name);
 884     $current_section = $section_name;
 885     $next_node = $section_name if !$next_node;
 886     $section_pending = 0;
 887     $_ = $save;
 888     }
 889
 890   # The .startconf macro introduces a set of .conf's which must have
 891   # their own local set of menus. Suspend processing the section while
 892   # we sort out the menu and copy their data. This is all done in a
 893   # subroutine that is shared with options.
 894
 895   elsif (/^\.startconf\s+(.*)/)
 896     {
 897     $confuse = $1;
 898     $confuse = &dequote($confuse);
 899     handle_subsection("conf");
 900     next;
 901     }
 902
 903   elsif (/^\.startoption/)
 904     {
 905     handle_subsection("option");
 906     next;
 907     }
 908
 909   # Deal with the actual data lines; if there's a section pending
 910   # start a new section on hitting some text. We hope this happens
 911   # only once per chapter...
 912
 913   if (substr($_, 0, 1) eq ".")
 914     {
 915     handle_directive();
 916     }
 917   else
 918     {
 919     while($nextline = <>)
 920       {
 921       last if $nextline =~ /^(\.|\s*$)/;
 922       $_ .= $nextline;
 923       }
 924     if ($section_pending && !/^\s*$/)
 925       {
 926       $section_name = (defined $current_section)?
 927         "$current_section (continued)" :
 928         "$current_chapter (continued)" ;
 929       flush_section();
 930       push(@section_list, $section_name);
 931       $current_section = $section_name;
 932       $next_node = $section_name if !$next_node;
 933       $section_pending = 0;
 934       }
 935
 936     push(@ONESECTION, handle_text($_));
 937     $_ = $nextline;
 938     last if !defined($_);
 939     redo;
 940     }
 941   }
 942
 943 # Flush any pending text, making its next field null.
 944 # and fudging section_name for the final section of the previous.
 945
 946 $section_name = "";
 947 flush_section();
 948
 949 # Set up section name as the start of the next chapter
 950
 951 $section_name = "Concept Index" if (!$doing_filter);
 952
 953 if (defined $_ && /^\.chapter (.*)/)
 954   {
 955   $section_name = $1;
 956   $section_name = &dequote($section_name);
 957   }
 958 $next_node = $section_name;
 959
 960 # Write out the chapter to the CHAPTERS file, sticking the chapter
 961 # menu after the text that came before the first section heading. This
 962 # will always at least contain the chapter title.
 963
 964 printf CHAPTERS ("\@node %s, %s, %s, Top\n",
 965   &decomma($current_chapter), &decomma($next_node),
 966   &decomma($previous_chapter));
 967
 968 # The pre-section stuff; if we hit an @end menu line, it is the menu of
 969 # a "subsection" before the first section. In that case, we need to put
 970 # the chapter's menu one the end of it, and then resume with the rest of
 971 # the TOPSECTION data afterwards. We also need to thread together this
 972 # "subsection"s nodes because they are all at the same level under the
 973 # chapter.
 974
 975 $in_menu = 0;
 976 while(scalar(@TOPSECTION))
 977   {
 978   $s = shift(@TOPSECTION);
 979   if ($s =~ /^\@end menu/)
 980     {
 981     $in_menu = 1;
 982     last;
 983     }
 984   print CHAPTERS $s;
 985   }
 986
 987 # Menu for sections
 988
 989 undef $next_actual_section;
 990 undef $point_back;
 991
 992 if (scalar(@section_list))
 993   {
 994   print CHAPTERS "\n\@sp 2\n\@menu\n" if ! $in_menu;
 995   $next_actual_section = $section_list[0];
 996   for ($i = 0; $i < scalar(@section_list); $i++)
 997     {
 998     $section_name = $section_list[$i];
 999     $section_name =~ s/\@sc\{([^}]*)\}/\U$1/g;
1000     print CHAPTERS "* ${section_name}::\n";
1001     }
1002   $in_menu = 1;
1003   }
1004 print CHAPTERS "\@end menu\n\n" if $in_menu;
1005
1006 # Remainder of topsection; we must arrange that the final @node in
1007 # it (which will have a blank "next" field) actually points on to
1008 # the next section, if any. If this happens, then the next section
1009 # must point back to the final @node.
1010
1011 while(scalar(@TOPSECTION))
1012   {
1013   $s = shift(@TOPSECTION);
1014   if ($next_actual_section && $s =~
1015          /^\@node\s+([^,]+),\s*,\s*([^,]*),\s*(.*)/)
1016     {
1017     my($t1, $t2, $t3) = ($1, $2, $3);    # So can be decomma'd
1018     printf CHAPTERS ("\@node %s, %s, %s, %s\n", &decomma($t1),
1019       &decomma($next_actual_section), &decomma($t2), &decomma($t3));
1020     $point_back = $1;
1021     }
1022   else { print CHAPTERS $s; }
1023   }
1024
1025 close(ONECHAPTER);
1026 open(ONECHAPTER, "$ONECHAPTER") || die "Can't open $ONECHAPTER for reading";
1027
1028 # While copying the chapter data, check for node references to empty
1029 # sections that got omitted and correct them, and correct the prev pointer
1030 # in the first node if necessary.
1031
1032 while ($buff = <ONECHAPTER>)
1033   {
1034   foreach $key (keys %rewrite)
1035     {
1036     $buff =~ s/$key/$rewrite{$key}/;
1037     }
1038   if ($point_back && $buff =~ /^\@node\s+([^,]+),\s*([^,]*),\s*([^,]*),\s*(.*)/)
1039     {
1040     my($t1, $t2, $t4) = ($1, $2, $4);   # so can be decomma'd
1041     printf CHAPTERS ("\@node %s, %s, %s, %s\n", &decomma($t1),
1042       &decomma($t2), &decomma($point_back), &decomma($t4));
1043     undef $point_back;
1044     }
1045   else { print CHAPTERS $buff; }
1046   }
1047
1048 $previous_chapter = $current_chapter;
1049
1050 close(ONECHAPTER);
1051 unlink($ONECHAPTER);
1052 }
1053
1054
1055
1056 ##################################################
1057 #                Main Program                    #
1058 ##################################################
1059
1060 # This is a two-pass algorithm. The first pass goes through and gets the
1061 # variable names for cross references. The second pass does the real work,
1062 # but we can't just read through doing the translation in one pass. We need
1063 # to know the list of chapters in order to build a top-level menu, and for
1064 # each chapter we need to know the sections in order to build a section
1065 # menu. Consequently, make use of temporary files to buffer things.
1066
1067 # This script is used for the filter document and the overview as well;
1068 # flags tell it if it is doing one of them.
1069
1070 $doing_filter = 0;
1071 $skip_else = 0;
1072 $in_itemize = 0;
1073 $lastwasitem = 0;
1074 $confuse = "";
1075
1076 $chapter_number = 0;
1077 $section_number = 0;
1078
1079 if ($#ARGV >= 0 && $ARGV[0] eq "-filter")
1080   {
1081   $doing_filter = 1;
1082   shift @ARGV;
1083   }
1084
1085 # First pass: Just fish out variable settings. Save the arguments so that
1086 # they can be reinstated for a second pass.
1087
1088 print STDERR "Scanning for references\n";
1089 @save_argv = @ARGV;
1090
1091 # Pick up any .set directives right at the very start
1092
1093 while (<>)
1094   {
1095   last if ! /^\.set\s+(\S+)\s+(.+)$/;
1096   $name = $1;
1097   $value = $2;
1098   $value =~ s/^\"?(.*?)\"?\s*$/$1/;
1099   $references{$name} = $value;
1100   }
1101
1102 # Now skip everything before the first .chapter except for
1103 # .index lines that set up indirections. Save these so that
1104 # the relevant index entries can be duplicated.
1105
1106 while (<>)
1107   {
1108   if (/^\.chapter\s+(.+)$/)
1109     {
1110     $chapter_number++;
1111     $section_number = 0;
1112     $current_chapter = $1;
1113     $current_chapter = $current_chapter;
1114     $current_section = "";
1115     last;
1116     }
1117
1118   if (/^\.index\s+([^\$]+)\s+\$it\{see\s+([^}]+)\}\s*$/)
1119     {
1120     $indirections{"$2"} = $1;
1121     }
1122   }
1123
1124 # Do the business
1125
1126 while (<>)
1127   {
1128   if (/^\.chapter\s+(.+)$/)
1129     {
1130     $current_chapter = $1;
1131     $current_chapter = &dequote($current_chapter);
1132     $current_section = "";
1133     }
1134   elsif (/^\.section\s+(.+)$/)
1135     {
1136     $current_section = $1;
1137     $current_section = &dequote($current_section);
1138     $current_section =~ s/://;
1139     }
1140   elsif (/^\.r?set\s+(\S+)\s+(.+)$/ && $1 ne "runningfoot")
1141     {
1142     $name = $1;
1143     $value = $2;
1144
1145     # Only set the first time. This handles a few special cases in part2
1146     # which is included in the filter text as well.
1147
1148     if (!exists($references{$name}))
1149       {
1150       $value =~ s/^\"?(.*?)\"?\s*$/$1/;
1151       $value =~ s/~~chapter\./~~chapter****/;
1152       $value =~ s/~~chapter/$current_chapter/;
1153       $value =~ s/~~section/$current_section/;
1154       $references{$name} = $value;
1155       }
1156     }
1157   }
1158
1159 $final_chapter = defined($current_chapter)? $current_chapter : "";
1160
1161 # Reinstate ARGV with the list of files and proceed to the main pass
1162
1163 @ARGV = @save_argv;
1164
1165 # $asis is set true when processing .display asis blocks, to stop
1166 # characters getting interpreted.
1167
1168 $asis = 0;
1169
1170 # $indisplay is set true while processing .display blocks, to stop
1171 # .newlines being handled therein (adding @* wrecks alignment)
1172
1173 $indisplay = 0;
1174
1175 # $tab is set to the value of the tab stop - only one stop is ever used
1176 # in the Exim source.
1177
1178 $tab = 0;
1179
1180 # Current driver name, for disambiguating nodes
1181
1182 $driver_name = "";
1183
1184 # $section_pending is set if a new section is to be started on hitting
1185 # any data lines.
1186
1187 $section_pending = 0;
1188
1189 # Open a file to buffer up the entire set of chapters
1190
1191 $CHAPTERS = "/tmp/CHAPTERS.$$";
1192 open(CHAPTERS, ">$CHAPTERS") || die "Can't open $CHAPTERS for writing";
1193
1194 # Skip everything before the first .chapter
1195
1196 while (<>) { last if /^\.chapter /; }
1197
1198 # Loop, handling each chapter
1199
1200 $current_up = "";
1201 $previous_chapter = "Top";
1202 $previous_node = "Top";
1203
1204 $chapter_number = 0;
1205 $section_number = 0;
1206
1207 while (defined ($_) && /^\.chapter /)
1208   {
1209   handle_chapter();
1210   }
1211
1212 # Output the stuff at the start of the file
1213
1214 print "\\input texinfo\n";
1215
1216 print "\@set{wmYear} 2003\n";
1217 print "\@set{wmAuthor} Philip Hazel\n";
1218 print "\@set{wmAuthor_email} <ph10\@\@cus.cam.ac.uk>\n";
1219 print "\@set{COPYRIGHT1} Copyright \@copyright{} \@value{wmYear} University of Cambridge\n";
1220
1221 print "\@c %**start of header\n";
1222
1223 if (!$doing_filter)
1224   {
1225   print "\@setfilename spec.info\n";
1226   print "\@settitle Exim Specification\n";
1227   }
1228 else
1229   {
1230   print "\@setfilename filter.info\n";
1231   print "\@settitle Exim Filter Specification\n";
1232   }
1233
1234 print "\@paragraphindent 0\n";
1235 print "\@c %**end of header\n\n";
1236
1237
1238 print "\@titlepage\n";
1239 print "\@title The Exim Mail Transfer Agent\n";
1240 print "\@author \@value{wmAuthor}\n";
1241
1242 print "\@page\n";
1243 print "\@vskip 0pt plus 1filll\n";
1244
1245 print "Permission is granted to make and distribute verbatim copies of this manual provided the\n";
1246 print "copyright notice and this permission notice are preserved on all copies.\n";
1247
1248 print "\@sp2\n";
1249 print "\@value{COPYRIGHT1}\@*\n";
1250
1251 print "\@end titlepage\n\n";
1252
1253 # Output the top-level node and its introductory blurb
1254
1255 print "\@node       Top,       $chapter_list[0], (dir), (dir)\n";
1256 print "\@top\n";
1257
1258 if (!$doing_filter)
1259 {
1260 print <<End;
1261 The Exim Mail Transfer Agent\@*
1262 ****************************
1263
1264 The specification of the Exim Mail Transfer Agent is converted mechanically
1265 into Texinfo format from its original marked-up source. Some typographic
1266 representations are changed, chapters and sections cannot be numbered, and
1267 Texinfo lacks the ability to mark updated parts of the specification with
1268 change bars.
1269
1270 Because the chapters and sections are unnumbered, cross references are set to
1271 their names. This makes the English a bit odd, with phrases like \`see chapter
1272 \"Retry configuration\"\' but it seemed very cumbersome to change this to \`see
1273 the chapter entitled \"Retry configuration\"\' each time.
1274
1275 Each chapter, section, and configuration option has been placed in a separate
1276 Texinfo node. Texinfo doesn\'t allow commas, colons, or apostrophes in node
1277 names, which is a rather nasty restriction. I have arranged not to use colons
1278 or apostrophes in section titles, but cannot bring myself to omit them from
1279 titles such as \"The foo, bar and baz commands\". For the corresponding node
1280 names I have just used multiple occurrences of \"and\", though it looks very
1281 ugly.
1282
1283 If a chapter or section continues after a list of configuration options that is
1284 not in a new section, a new node is started, using the chapter\'s or section\'s
1285 name plus \`(continued)\'. The \`Up\' operation from a section or configuration
1286 option returns to the start of the current chapter; the \`Up\' operation at a
1287 chapter start returns to the top of the document; the \`Up\' in a list of
1288 configuration options within a section returns to the top of that section.
1289
1290 A number of drivers have options with the same name, so they have been
1291 disambiguated by adding the name of the driver to its option names in order to
1292 create node names. Thus, for example, the specification of the \`command\'
1293 options of the \`lmtp\' and \`pipe\' transports are in nodes called \`command
1294 (lmtp)\' and \`command (pipe)\', respectively.
1295
1296 End
1297 }
1298
1299 else
1300 {
1301 print <<End;
1302 Filtering with the Exim Mail Transfer Agent\@*
1303 *******************************************
1304
1305 The specifications of the Exim Mail Transfer Agent\'s filtering facility is
1306 converted mechanically into Texinfo format from its original marked-up source.
1307 Some typographic representations are changed, chapters and sections cannot be
1308 numbered, and Texinfo lacks the ability to mark updated parts of the
1309 specification with change bars.
1310
1311 Because the chapters and sections are unnumbered, cross references are set to
1312 their names. This makes the English a bit odd, with phrases like \`see section
1313 \"Multiple personal mailboxes\"\' but it seemed very cumbersome to change this to
1314 \`see the section entitled \"Multiple personal mailboxes\"\' each time.
1315
1316 End
1317 }
1318
1319 # Output the top-level menu
1320
1321 print "\@menu\n";
1322
1323 while (scalar(@chapter_list))
1324   {
1325   $name = &decomma(shift(@chapter_list));
1326   print "* ${name}::\n";
1327   }
1328 print "* Concept Index::\n" if (!$doing_filter);
1329 print "\@end menu\n\n";
1330
1331 # Copy the chapters, then delete the temporary file
1332
1333 close(CHAPTERS);
1334 open(CHAPTERS, "$CHAPTERS") || die "Can't open $CHAPTERS for reading";
1335 print $buff while($buff = <CHAPTERS>);
1336 close(CHAPTERS);
1337 unlink($CHAPTERS);
1338
1339 # Output the finishing off stuff
1340
1341 if (!$doing_filter)
1342   {
1343   print "\@node Concept Index, , $final_chapter, Top\n";
1344   print "\@chapter Concept Index\n\@printindex cp\n";
1345   print "\@chapter Function Index\n\@printindex fn\n";
1346   }
1347 print "\@contents\n";
1348 print "\@bye\n";
1349
1350 # End