doc/doc-scripts/g2t

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