Start

1 files changed, 1347 insertions, 0 deletions

diff --git a/doc/doc-scripts/g2t b/doc/doc-scripts/g2t
new file mode 100755
index 000000000..30c713c08
--- /dev/null
+++ b/doc/doc-scripts/g2t
@@ -0,0 +1,1347 @@
+#! /usr/bin/perl -w
+# $Cambridge: exim/doc/doc-scripts/g2t,v 1.1 2004/10/07 15:04:35 ph10 Exp $
+
+# A Perl script to turn the SGCAL source of the Exim documentation into
+# Texinfo input, more or less...
+
+# Supply the source file names as arguments.
+# The output goes to the standard output.
+
+
+##################################################
+#         Ensure unique node name                #
+##################################################
+
+# Node names must be unique. Occasionally in the Exim spec there are duplicate
+# section names, and it's become too much of a hassle to keep them distinct
+# manually. So it is now automated.
+
+########### Never really got this working. Abandoned ###############
+
+sub unique {
+my($node) = $_[0];
+if (defined $node_names{$node})
+  {
+  $node_names{$node} += 1; 
+  $node = "$node ($node_names{$node})"; 
+  
+print STDERR "+++ $node\n";
+ 
+  }
+else
+  {
+  $node_names{$node} = 0;
+  }
+$node;
+}  
+
+
+
+##################################################
+#         De-comma a node name                   #
+##################################################
+
+# Commas, colons, and apostrophes are not permitted in Texinfo
+# node names. I find this incredible, but it is clearly documented.
+# The Exim manual has been re-organized not to have colons or
+# apostrophes in any chapter or section titles, but I can't manage
+# without commas. This function turns "," into " and", which is
+# the best that can be done; we can use some clever Perlery to
+# just take out commas before "and".
+
+# Sigh. The Sendmail option -p<rval>:<sval> now means that there's a colon
+# in the node name for that option. Turn the colon into <colon>. This is also
+# done for menus.
+
+# Another thing that causes problems in node names in some versions of
+# Texinfo is the use of @sc{xxx} for small caps. Just turn these all into
+# real caps. This is also done for menus.
+
+sub decomma {
+$_[0] =~ s/,(?!\sand)/ and/g;
+$_[0] =~ s/,//g;
+$_[0] =~ s/\@sc\{([^}]*)\}/\U$1/g;
+$_[0] =~ s/:/<colon>/g;
+$_[0];
+}
+
+
+
+##################################################
+#           De-quote a string                    #
+##################################################
+
+# @x is turned into x, except when x=@, or when asis is set,
+# in which case single @ must turn into @@. A single substitute
+# doesn't work in the non-asis case, because of the problems of
+# handling things like @@@$, so we do it the hard way.
+
+sub dequote {
+if ($asis) { $_[0] =~ s/@/@@/g; } else
+  {
+  $_[0] =~ s/@@/&at&/g;
+  $_[0] =~ s/@([^@])/$1/g;
+  $_[0] =~ s/&at&/@@/g;
+  }
+$_[0];
+}
+
+
+##################################################
+#           Get next line                        #
+##################################################
+
+# Called from handle_directive, to get the next source line
+# into $_.
+
+sub get_next_line {
+if ($processing_subsection)
+  { return $_ = shift @SUBBUFFER; }
+else
+  { return $_ = <>; }
+}
+
+
+
+##################################################
+#           Handle text lines                    #
+##################################################
+
+# This function is handed whole paragraphs, and we assume that
+# SGCAL font changing markup is always complete within a paragraph.
+# We have to replace escaped versions of significant characters with
+# some magic before performing general transformations, and then
+# put them back afterwards. The character & is not common in the text,
+# and && is unknown, so we use that.
+
+sub handle_text {
+$_ = $_[0];
+
+if ($asis)
+  {
+  $_ = dequote($_);
+  s/(\{|\})/\@$1/g;
+  return $_;
+  }
+
+while (/~~/)
+  {
+  $left = $`;
+  ($name) = $' =~ /^(\w+)/;
+  $right = $';
+
+  $value = $references{$name};
+  $value = "" if !defined($value);
+
+  if ($value =~ /\*\*\*\*/)
+    {
+    $value = ($` eq $current_chapter)? "\"$'\"" :
+      "\"$'\" in chapter \"$`\"";
+    $value = "" if $value eq "\"\"";
+    }
+  elsif ($value !~ /^[0-9]+\.[0-9]+$/)   # quote unless version number
+    {                                                
+    $value = "\"$value\"";                          
+    }
+
+  $_ = "${left}${value}${right}";
+  }
+
+s/\@\@/&&a/g;         # @@
+s/\@\\/&&b/g;         # @\
+s/\@</&&l/g;          # @<
+s/\@>/&&g/g;          # @>
+s/\@\{/&&c/g;         # @{
+s/\@\}/&&d/g;         # @}
+s/\@#/&&s/g;          # @#
+
+# Now remove all other @'s
+
+$_ = dequote($_);
+
+# Convert SGCAL markup
+
+s/#/ /g;                            # turn #   into a space
+s/\$~//g;                           # turn $~  into nothing
+s/__/_/g;                           # turn __  into _
+s/\$sm\{//g;                        # turn $sm{     into nothing
+s/\$sc\{([^\}]*?)\}/$1/g;           # turn $sc{xxx} into xxx
+s/\$st\{([^\}]*?)\}/$1/g;           # turn $st{xxx} into xxx
+s/\$si\{([^\}]*?)\}/$1/g;           # turn $si{xxx} into xxx
+s/\$tt\{([^\}]*?)\}/$1/g;           # turn $tt{xxx} into xxx
+
+s/\$it\{([^\}]*?)\}/$1/g;           # turn $it{xxx} into xxx
+
+s/\$bf\{([^\}]*?)\}/$1/g;           # turn $bf{xxx} into xxx
+s/\$rm\{([^\}]*?)\}/$1/g;           # turn $rm{xxx} into xxx
+s/\$cb\{([^\}]*?)\}/$1/g;           # turn $cb{xxx} into xxx
+
+# This is a fudge for some specific usages of $<; can't just do a global
+# is it occurs in things like $<variable name> as well.
+
+s/\[\$<\]/[]/g;                     # turn [$<]     into []
+s/&&b\$<\./&&b./g;                  # turn \$<.     into \.  (\ == &&b by now)
+s/(\d)\$<-/$1-/g;                   # turn 0$<-     into 0-
+
+# There is one case where the terminating } of an escape sequence is
+# in another paragraph - this follows $sm{ - it can be fixed by
+# removing any stray } in a paragraph that contains no { chars.
+
+s/\}//g if !/\{/;
+
+# Any remaining {} must be escaped to prevent Texinfo from complaining
+
+s/(\{|\})/\@$1/g;
+
+# Now to conversions that put {} into the file.
+# Change <<..>> from @var to just <...> as the caps that Texinfo
+# uses look far too shouty.
+
+s/\\\\([^\\]*?)\\\\/\@sc\{\L$1\}/g; # turn \\xxx\\  into @sc{xxx}
+s/\\\(([^)]*?)\)\\/\@file\{$1\}/g;  # turn \(xxx)\  into @file{xxx}
+s/\\\"([^\"]*?)\"\\/\@file\{$1\}/g; # turn \"xxx"\  into @file{xxx}
+
+s/\\\?([^?]*?)\?\\/$1/g;            # turn \?URL?\    into URL
+s/<<([^>]*?)>>/<$1>/g;              # turn <<xxx>>    into <xxx>
+s/\\\$([^\$]*?)\$\\/\$$1/g;         # turn \$xxx$\    into $xxx
+s/\\\-([^-]*?)\-\\/\-$1/g;          # turn \-xxx-\    into -xxx
+s/\\\*\*([^*]*?)\*\*\\/$1/g;        # turn \**xxx**\  into xxx
+s/\[\(([\w\/]*)\)\]//g;             # remove inline HTML
+
+s/\\\*([^*]*?)\*\\/\@dfn\{$1\}/g;     # turn \*xxx*\    into @dfn{xxx}
+s/\\%([^*]*?)%\\/\@dfn\{$1\}/g;       # turn \%xxx%\    into @dfn{xxx}
+s/:::([^:]*?)::/\@dfn\{:$1:\}/g;      # turn :::xxx::   into @dfn{:xxx:}
+s/::([^:]*?)::/\@dfn\{$1:\}/g;        # turn ::xxx::    into @dfn{xxx:}
+s/\\([^\\]*?)\\/\@dfn\{$1\}/g;        # turn \xxx\      into @dfn{xxx}
+s/\$\*\$/\*/g;                        # turn $*$        into *
+
+# Put back escaped SGCAL specials
+
+s/&&a/\@\@/g;
+s/&&b/\\/g;
+s/&&l/</g;
+s/&&g/>/g;
+s/&&c/\@{/g;
+s/&&rc/{/g;
+s/&&rd/}/g;
+s/&&d/\@}/g;
+s/&&s/#/g;
+
+# Remove any null flags ($$)
+
+s/\$\$//g;
+
+# If the paragraph starts with $c\b, change this into @center. Assume
+# we don't ever get two of these in a row.
+
+s/^\$c\b/\@center /;
+
+# If the paragraph starts with $e\b, stuff some tabs in there, as
+# Texinfo can't do this on its own (as far as I can see). They must
+# tabs; Texinfo treats them as different to spaces. Sigh.
+
+s/^\$e\b/\t\t\t\t\t\t\t/;
+
+# Handle $t. The Exim spec only ever has one tab per line. Er, not
+# quite true, but a good enough assumption. $t is always followed
+# by a non-word character.
+
+# The .tabs directive has stashed the value in the $tab variable.
+# Don't count Texinfo font chars.
+
+while (/(^|.+?\n)(.+?)\$t(\W.*\n)/)
+  {
+  $before = $` . $1;
+  $after = $';
+  $left = $2;
+  $right = $3;
+
+  $left =~ s/\s$//;
+  $right =~ s/^\s+//;
+
+  $plainleft = $left;
+  $plainleft =~ s/\@[a-z]+\{([^}]+?)\}/$1/g;
+  $plainleft =~ s/\@//g;
+
+  $_ = $before . $left . (" " x ($tab - length($plainleft))) . $right . $after;
+
+  # Fudge for the one case where there are two tabs
+
+  if ($tab2 != 0)
+    {
+    $temp = $tab;
+    $tab = $tab2;
+    $tab2 = $temp;
+    }
+  }
+
+# Return the new line (paragraph)
+
+$_;
+}
+
+
+
+##################################################
+#           Handle directive lines               #
+##################################################
+
+# Use get_next_line() instead of <> because this is called to process
+# stacked up subsection lines
+
+sub handle_directive {
+
+my($new_lastwasitem) = 0;
+
+# Chapter directives just require . => @; however, dequoting the
+# line thereafter will remove the first @, so just force it back
+# afterwards. If the chapter is is one describing a driver, set
+# the driver name.
+
+if (/\.chapter/)
+  {
+  tr/./@/;
+  push(@ONESECTION, "@" . &dequote("$_\n"));
+  $driver_name = (/The\s+(\S+)\s+(director|router|transport|authenticator)/)? $1 :
+    (/Generic options common to both directors and routers/)?
+      "director or router" :
+    (/[Gg]eneric\s+options for (\S+)s/)? $1 : "";
+  $driver_name = &dequote($driver_name);
+  }
+
+# Section directives just require . => @; however, dequoting the
+# line thereafter will remove the first @, so just force it back
+# afterwards. Remove any colons in section titles as they cause
+# Texinfo trouble. Also remove any \\ (small caps) markup, which
+# appears in a couple of cases.
+
+elsif (/\.section/)
+  {
+  tr/./@/;
+  s/://;
+  s"\\\\""g;
+  push(@ONESECTION, "@" . &dequote("$_\n"));
+
+  # Horrible magic fudge to cope with the fact that exim_lock has
+  # -v and -q options, just like the main program.
+
+  $driver_name = "exim_lock" if /Mailbox maintenance/;
+  
+  # Similar magic for exiqgrep, which also duplicates options
+  
+  $driver_name = "exiqgrep" if /Selective queue listing/;  
+  }
+
+# .newline must put @* on the end of the previous line, if any, except
+# inside a display, where it causes trouble.
+
+elsif (/\.newline/)
+  {
+  if (@ONESECTION > 0 && ! $indisplay)
+    {
+    $_ = pop(@ONESECTION);
+    s/(\n*)$/\@*$1/;
+    push(@ONESECTION, $_);
+    }
+  }
+
+# .blank turns into @sp, adding 1 if no argument
+
+elsif (/\.blank/)
+  {
+  s/\.blank\s+(\d+)/\@sp $1/;
+  s/\.blank/\@sp 1/;
+  push(@ONESECTION, $_);
+  }
+
+# .rule turns into a line of hyphens
+
+elsif (/\.rule/)
+  {
+  push(@ONESECTION, ("-" x ($in_itemize? 68 : 73)) . "\@*\n");
+  }
+
+# There's one explicit .tabset setting for two tab stops
+
+elsif (/\.tabset\s*/)
+  {
+  $rest = $';
+  ($first,$second) = $rest =~ /(\d+)em\s+(\d+)em/;
+  $tab = ($first * 7)/6;
+  $tab2 = $tab + ($second * 7)/6;
+  }
+
+# .tabs remembers the first (and only) tab setting
+
+elsif (/\.tabs\s*/)
+  {
+  $tab = ($' * 7)/6;
+  $tab2 = 0;
+  }
+
+# .tempindent is used only to align some of the expansion stuff nicely;
+# just ignore it. It is used in conjunction with .push/.pop.
+
+elsif (/\.(tempindent|push|pop)\s*/)
+  {
+  }
+
+# There are some instances of .if ~~sys.fancy in the source. Some of these
+# are two-part things, in which case we just keep the non-fancy. For diagrams,
+# however, they are in three parts:
+#
+# .if ~~sys.fancy
+# <aspic drawing stuff>
+# .elif ~~nothtml
+# <ascii art for txt and Texinfo>
+# .else
+# <HTML instructions for including a gif>
+# .fi
+
+elsif (/\.if \~\~sys\.fancy/)
+  {
+  while (&get_next_line())
+    { last if /\.else\b/ || /\.elif\s+\~\~nothtml/ || /\.fi\b/; }
+
+  if (/\.elif/)
+    {
+    $skip_else = 1;
+    }
+  }
+
+# There are occasional requirements to do things differently for
+# Texinfo/HTML and the PS/txt versions, and there are also some
+# HTML-specific things.
+
+elsif (/\.if\s+~~sgcal/ || /\.if\s+~~html/)
+  {
+  while (&get_next_line()) { last if /\.else\b/ || /\.fi\b/; }
+  }
+
+# We may also have Texinfo-specific bits
+
+elsif (/^\.if\s+~~texinfo/)
+  {
+  $skip_else = 1;
+  }
+
+# Ignore any other .if directives
+
+elsif (/\.if/) {}
+
+# Skip else part if flag set
+
+elsif (/\.else/ && $skip_else)
+  {
+  while (&get_next_line()) { last if /\.fi\b/; }
+  $skip_else = 0;
+  }
+
+# Ignore other .fi and .else as any .if directives are handled specially
+
+elsif (/\.fi/ || /\.else/) {}
+
+# Ignore .indent
+
+elsif (/\.indent/) {}
+
+# Plain .index goes to @cindex - the "concept" index. Also, there
+# are some calls to vindex and findex in the SGCAL source - treated
+# as synonymous with .index - which are split into the equivalent
+# indexes here.
+
+elsif (/\.(.?)index/)
+  {
+  $rest = $';
+  $letter = ($1 eq "")? "c" : $1;
+  tr/./@/;                           # .index -> @index
+  
+  $rest =~ s/\\\(//g;                # Remove markup
+  $rest =~ s/\)\\//g; 
+  $rest =~ s/\\%//g;
+  $rest =~ s/%\\//g;
+  $rest =~ s/\\\*//g;
+  $rest =~ s/\*\\//g;    
+  $rest =~ s/\\"//g;
+  $rest =~ s/"\\//g;
+  $rest =~ s/:://g;
+  $rest =~ s/\\-/-/g;
+  $rest =~ s/-\\//g;
+  $rest =~ s/~~//g;     
+ 
+  $rest =~ tr/\\//d;                 # Remove \
+   
+  $rest =~ s/\@\$/\$/g;              # @$  -> $
+  $rest =~ s/\@_/_/g;                # @_  -> _
+  $rest =~ s/\@\+/+/g;               # @+  -> +
+  $rest =~ s/\$\*\$/\*/g;            # $*$ -> *
+  $rest =~ s/\$([^\$]+)\$/\$$1/g;    # $x$ -> $x
+   
+  $rest =~ s/^\s+//;                 # Remove leading spaces
+  $rest =~ s/\s+$//;                 # Remove trailing spaces
+  $rest =~ s/\|\|/:/;                # || -> : 
+  push(@ONESECTION, "\@${letter}index $rest\n");
+
+  # Duplicate entries for things that were listed as "x see y"
+
+  if (defined $indirections{$rest})
+    {
+    push(@ONESECTION, "\@${letter}index $indirections{$rest}\n");
+    }
+  }
+
+# Various flavours of numberpars map to itemize and enumerate.
+# Haven't found a way of having a blank space 'bullet' yet, so
+# currently using minus.
+
+elsif (/\.numberpars/)
+  {
+  $rest = $';
+  $type = "enumerate";
+  $flag = "";
+
+  if    ($rest =~ /\$\./)  { $flag = " \@bullet"; $type = "itemize" }
+  elsif ($rest =~ /\" \"/) { $flag = " \@minus";  $type = "itemize"; }
+  elsif ($rest =~ /roman/) { $flag = " a"; $type = "enumerate"; }
+
+  push(@ONESECTION, "\n\@$type$flag\n\n\@item\n");
+  push(@ENDLIST, $type);
+  $in_itemize++;
+  }
+
+elsif (/\.nextp/)
+  {
+  push(@ONESECTION, "\n\@item\n");
+  }
+
+elsif (/\.endp/)
+  {
+  $endname = pop(@ENDLIST);
+  push(@ONESECTION, "\@end $endname\n\n");
+  $in_itemize--;
+  }
+
+# The normal .display (typewriter font) => @example, while the rm
+# form goes to @display (no change of font). For Texinfo we need a
+# blank line after @display.
+
+elsif (/\.display/)
+  {
+  $type = /rm/? "display" : "example";
+  $asis = 1 if /asis/;
+  $indisplay = 1;
+  push(@ONESECTION, "\@$type\n\n");
+  push(@ENDLIST, $type);
+  }
+
+elsif (/\.endd/)
+  {
+  $asis = 0;
+  $indisplay = 0;
+  $endname = pop(@ENDLIST);
+  push(@ONESECTION, "\@end $endname\n\n");
+  }
+
+elsif (/\.conf/)
+  {
+  ($option, $type, $default) =
+    /\.conf\s+(\S+)\s+("(?:[^"]|"")+"|\S+)\s+("(?:[^"]|"")+"|.*)/;
+
+  $option = &dequote($option);
+
+  # If $type ends with $**$ (turned into a dagger for PS version),
+  # replace with ", expanded". Remove any surrounding quotes.
+
+  $type =~ s/^"([^"]+)"/$1/;
+  $type =~ s/\$\*\*\$/, expanded/;
+
+  # Default may be quoted, and it may also have quotes that are required,
+  # if it is a string.
+
+  $default =~ s/^"(.*)"$/$1/;
+  $default =~ s/""/"/g;
+  $default = &handle_text($default);
+
+  push(@ONESECTION, "\nType: $type\@*\nDefault: $default\n\n");
+  }
+
+# Handle .startitems, .enditems, and .item
+
+elsif (/\.startitem/ || /\.enditem/) {}
+
+elsif (/\.item/)
+  {
+  $arg = $';
+  $arg =~ s/^\s*"//;
+  $arg =~ s/"\s*$//;
+  $arg = &dequote($arg);
+  $arg = &handle_text("\\**$arg**\\");
+
+  # If there are two .items in a row, we don't want to put in the
+  # separator line.
+
+#  push(@ONESECTION, "\n\@example\n");
+  push(@ONESECTION, "\n");
+  if (! $lastwasitem)
+    {
+    push(@ONESECTION, "_" x 75, "\n\n");
+    }
+#  push(@ONESECTION, "$arg\n\@end example\n\n");
+  push(@ONESECTION, "$arg\n\n");
+  $new_lastwasitem = 1;
+  }
+
+elsif (/\.option/)
+  {
+  chomp($arg = $');
+  $arg =~ s/^\s*//;
+  $arg = &dequote("-$arg");
+  $arg = &handle_text($arg);
+  }
+
+# Texinfo has no facility for emphasis bars.
+
+elsif (/\.em/) {}
+elsif (/\.nem/) {}
+
+# Just ignore any .(r)set directives pro tem (or maybe always!)
+
+elsif (/\.r?set/) {}
+
+# Ignore .space, .linelength, and .justify
+
+elsif (/\.space/ || /\.justify/ || /\.linelength/) {}
+
+# Found an SGCAL directive that isn't dealt with. Oh dear.
+# Turn the embarrassing characters into question marks and
+# output it in an emphasized way.
+
+else
+  {
+  tr/@{}/???/;
+  push(@ONESECTION, "\n\>>>>>>> $_\n") if ! /^\.( |$)/;
+  }
+
+$lastwasitem = $new_lastwasitem;
+}
+
+
+
+##################################################
+#             Flush a section                    #
+##################################################
+
+# $section_name is the name of the next section.
+# $current_section is the name of the one we have buffered up.
+# If it is unset, we are at the first section of a chapter.
+# $previous_node is the section we last flushed if it was a node.
+
+sub flush_section {
+
+# If there is no text in the section, omit it entirely. However, it
+# will have had a pointer set up at the start of the previous section.
+# Remember what to replace this with when the chapter gets flushed.
+
+my($skip) = 1;
+foreach $s (@ONESECTION)
+  {
+  if ($s !~ /^(\@cindex|\@section|\s*$)/) { $skip = 0; last }
+  }
+
+if ($skip)
+  {
+  pop @section_list;
+  $rewrite{$current_section} = $section_name;
+  @ONESECTION = ();
+  return;
+  }
+
+# There is data in the section: write it out to the chapter file
+
+if ($current_section)
+  {
+  printf ONECHAPTER ("\@node %s, %s, %s, %s\n",
+    &decomma($current_section), &decomma($section_name),
+    &decomma($previous_node), &decomma($current_up));
+  $previous_node = $current_section;
+  while(scalar(@ONESECTION))
+    { print ONECHAPTER shift(@ONESECTION); }
+  }
+else
+  {
+  while(scalar(@ONESECTION))
+    { push(@TOPSECTION, shift(@ONESECTION)); }
+  }
+}
+
+
+
+##################################################
+#          Handle a "subsection"                 #
+##################################################
+
+# A "subsection" is a set of options that must have their own
+# local menu. Do two passes; the first just collects the names
+# for the menu. This is called for .conf and .option items.
+
+sub handle_subsection{
+my($type) = $_[0];
+my($save_up) = $current_up;
+
+$current_up = $current_section? $current_section : $current_chapter;
+
+@sublist = ();
+@SUBBUFFER = ();
+
+while (<>)
+  {
+  last if /^\.end$type/;
+  push(@SUBBUFFER, $_);
+
+  # .conf takes the first non-space string as the name, but as there are
+  # duplicate confs in various parts of the spec, use the driver name to
+  # de-duplicate; .option takes the entire rest of arg as the name, but
+  # removes any sequence of ... because this disturbs TexInfo. Also, it
+  # turns @- into -.
+
+  if (/^\.$type\s+(\S+)(.*)/)
+    {
+    if ($type eq "conf")
+      {
+      $name = &handle_text($1);
+      $name .= " ($driver_name)" if ($driver_name ne "");
+      }
+    else
+      {
+      chomp($name = &handle_text("-$1$2"));
+      $name =~ s/\s*\.\.\.//g;
+
+      $name .= " ($driver_name)" if ($driver_name ne "");
+
+      # There seems to be a major problem in texinfo with the string "--".
+      # In the text it gets turned into a single hyphen. This happens if it
+      # is used as a menu item, but *not* as a node name. Exim has a command
+      # line option "--". With no special action, this appears in the menu
+      # as "-", but then the info software complains there is no node called
+      # "-". If we triple it in the menu it gets displayed OK, but building
+      # software complains about non-existent cross references etc.
+
+      # I have gone for the horrid kludge of turning it into "-<hyhen>"
+      # in the menus and nodes.
+
+      # Exim 4 has added --help, which has the same problem.
+
+      $name = "-<hyphen>" if ($name eq "--");
+      $name = "-<hyphen>help" if ($name eq "--help");
+      }
+    push(@sublist, $name);
+    }
+  }
+
+push (@ONESECTION, "\n\@sp 2\n\@menu\n");
+for ($i = 0; $i < scalar(@sublist); $i++)
+  {
+  $mitem = $sublist[$i];
+  $mitem =~ s/\@sc\{([^}]*)\}/\U$1/g;       # Get rid of small caps
+  $mitem =~ s/:/<colon>/g;                  # Get rid of colons
+  push (@ONESECTION, "* ${mitem}::\n");
+  }
+push (@ONESECTION, "\@end menu\n\n");
+
+$prevsub = $current_up;
+$processing_subsection = 1;
+while ($_ = shift(@SUBBUFFER))
+  {
+  if (/^\.$type\s+(\S+)/)
+    {
+    $name = shift @sublist;
+    $next = (scalar(@sublist))? $sublist[0] : "";
+    push @ONESECTION, sprintf("\@node %s, %s, %s, %s\n",
+      &decomma($name), &decomma($next), &decomma($prevsub),
+      &decomma($current_up));
+
+    if ($name eq "-<hyphen>")    # Fudge for Texinfo
+      {
+      push(@ONESECTION,
+	   "\@findex $name\n",
+	   "\@unnumberedsubsec --- option\n");
+      push(@ONESECTION,
+           "This option consists of two consecutive hyphens. It appears in\n",
+           "the menu as \"-<hyphen>\" because otherwise Texinfo gets\n",
+           "confused with its cross-referencing.\n");
+      }
+    elsif ($name eq "-<hyphen>help")    # Fudge for Texinfo
+      {
+      push(@ONESECTION,
+	   "\@findex $name\n",
+	   "\@unnumberedsubsec ---help option\n");
+      push(@ONESECTION,
+           "This option consists of \"help\" preceded by two consecutive\n" .
+           "hyphens. It appears in the menu as \"-<hyphen>help\" because\n" .
+           "otherwise Texinfo gets confused with its cross-referencing.\n");
+      }
+    else
+      {
+      push(@ONESECTION,
+	   "\@findex $name\n",
+	   "\@unnumberedsubsec $name option\n");
+      }
+
+    $prevsub = $name;
+    }
+
+  # Then handle as text or directive
+
+  if (substr($_, 0, 1) eq ".")
+    { handle_directive(); }
+  else
+    {
+    while($nextline = shift(@SUBBUFFER))
+      {
+      last if $nextline =~ /^(\.|\s*$)/;
+      $_ .= $nextline;
+      }
+    push(@ONESECTION, handle_text($_));
+    $_ = $nextline;
+    last if !defined($_);
+    redo;
+    }
+  }
+
+$processing_subsection = 0;
+$section_pending = 1;
+$current_up = $save_up;
+}
+
+
+
+
+##################################################
+#            Handle a single chapter             #
+##################################################
+
+sub handle_chapter{
+chop;
+($current_chapter) = /^\.chapter (.*)/;
+$current_chapter = &dequote($current_chapter);
+
+$current_chapter = $current_chapter;
+
+my($tmp) = $current_chapter;
+$tmp =~ s/\[\[\[\]\]\]/./;
+print STDERR "processing chapter: $tmp\n";
+
+# Remember the chapter name for the top-level menu
+
+push(@chapter_list, $current_chapter);
+
+# Open a temporary file to hold the chapter's text while collecting
+# all its sections for a chapter-level menu.
+
+$ONECHAPTER = "/tmp/ONECHAPTER.$$";
+open(ONECHAPTER, ">$ONECHAPTER") || die "Can't open $ONECHAPTER for writing";
+
+# Initialize for handling sections
+
+@section_list = ();
+%rewrite = ();
+@ONESECTION = ();
+@TOPSECTION = ();
+undef $current_section;
+undef $next_node;
+
+$processing_subsection = 0;
+
+$previous_node = $current_up = $current_chapter;
+$section_pending = 0;
+
+# Handle the .chapter directive as the first text of a section without
+# a section title.
+
+handle_directive();
+
+# Loop, handling each section. Assume they are sufficiently short that
+# we can buffer the text in store, in an array called ONESECTION, instead
+# of thrashing yet another file.
+
+while (<>)
+  {
+  last if /^\.chapter /;
+
+  # Handle a new section, preserving $_ (handle_text flattens it).
+  # It seems we cannot get a fullstop into a Texinfo node name; use a magic
+  # character string that gets turned back into a dot by the post-processing.
+
+  if (/^\.section\s+/)
+    {
+    $save = $_;
+    $section_name = $';
+    $section_name =~ s/(\s|\n)+$//;
+    $section_name =~ s/://;
+    $section_name = &handle_text($section_name);
+    flush_section();
+    push(@section_list, $section_name);
+    $current_section = $section_name;
+    $next_node = $section_name if !$next_node;
+    $section_pending = 0;
+    $_ = $save;
+    }
+
+  # The .startconf macro introduces a set of .conf's which must have
+  # their own local set of menus. Suspend processing the section while
+  # we sort out the menu and copy their data. This is all done in a
+  # subroutine that is shared with options.
+
+  elsif (/^\.startconf/)
+    {
+    handle_subsection("conf");
+    next;
+    }
+
+  elsif (/^\.startoption/)
+    {
+    handle_subsection("option");
+    next;
+    }
+
+  # Deal with the actual data lines; if there's a section pending
+  # start a new section on hitting some text. We hope this happens
+  # only once per chapter...
+
+  if (substr($_, 0, 1) eq ".")
+    {
+    handle_directive();
+    }
+  else
+    {
+    while($nextline = <>)
+      {
+      last if $nextline =~ /^(\.|\s*$)/;
+      $_ .= $nextline;
+      }
+    if ($section_pending && !/^\s*$/)
+      {
+      $section_name = (defined $current_section)?
+        "$current_section (continued)" :
+        "$current_chapter (continued)" ;
+      flush_section();
+      push(@section_list, $section_name);
+      $current_section = $section_name;
+      $next_node = $section_name if !$next_node;
+      $section_pending = 0;
+      }
+
+    push(@ONESECTION, handle_text($_));
+    $_ = $nextline;
+    last if !defined($_);
+    redo;
+    }
+  }
+
+# Flush any pending text, making its next field null.
+# and fudging section_name for the final section of the previous.
+
+$section_name = "";
+flush_section();
+
+# Set up section name as the start of the next chapter
+
+$section_name = "Concept Index" if (!$doing_filter);
+
+if (defined $_ && /^\.chapter (.*)/)
+  {
+  $section_name = $1;
+  $section_name = &dequote($section_name);
+  }
+$next_node = $section_name;
+
+# Write out the chapter to the CHAPTERS file, sticking the chapter
+# menu after the text that came before the first section heading. This
+# will always at least contain the chapter title.
+
+printf CHAPTERS ("\@node %s, %s, %s, Top\n",
+  &decomma($current_chapter), &decomma($next_node),
+  &decomma($previous_chapter));
+
+# The pre-section stuff; if we hit an @end menu line, it is the menu of
+# a "subsection" before the first section. In that case, we need to put
+# the chapter's menu one the end of it, and then resume with the rest of
+# the TOPSECTION data afterwards. We also need to thread together this
+# "subsection"s nodes because they are all at the same level under the
+# chapter.
+
+$in_menu = 0;
+while(scalar(@TOPSECTION))
+  {
+  $s = shift(@TOPSECTION);
+  if ($s =~ /^\@end menu/)
+    {
+    $in_menu = 1;
+    last;
+    }
+  print CHAPTERS $s;
+  }
+
+# Menu for sections
+
+undef $next_actual_section;
+undef $point_back;
+
+if (scalar(@section_list))
+  {
+  print CHAPTERS "\n\@sp 2\n\@menu\n" if ! $in_menu;
+  $next_actual_section = $section_list[0];
+  for ($i = 0; $i < scalar(@section_list); $i++)
+    {
+    $section_name = $section_list[$i];
+    $section_name =~ s/\@sc\{([^}]*)\}/\U$1/g;
+    print CHAPTERS "* ${section_name}::\n";
+    }
+  $in_menu = 1;
+  }
+print CHAPTERS "\@end menu\n\n" if $in_menu;
+
+# Remainder of topsection; we must arrange that the final @node in
+# it (which will have a blank "next" field) actually points on to
+# the next section, if any. If this happens, then the next section
+# must point back to the final @node.
+
+while(scalar(@TOPSECTION))
+  {
+  $s = shift(@TOPSECTION);
+  if ($next_actual_section && $s =~
+         /^\@node\s+([^,]+),\s*,\s*([^,]*),\s*(.*)/)
+    {
+    my($t1, $t2, $t3) = ($1, $2, $3);    # So can be decomma'd
+    printf CHAPTERS ("\@node %s, %s, %s, %s\n", &decomma($t1),
+      &decomma($next_actual_section), &decomma($t2), &decomma($t3));
+    $point_back = $1;
+    }
+  else { print CHAPTERS $s; }
+  }
+
+close(ONECHAPTER);
+open(ONECHAPTER, "$ONECHAPTER") || die "Can't open $ONECHAPTER for reading";
+
+# While copying the chapter data, check for node references to empty
+# sections that got omitted and correct them, and correct the prev pointer
+# in the first node if necessary.
+
+while ($buff = <ONECHAPTER>)
+  {
+  foreach $key (keys %rewrite)
+    {
+    $buff =~ s/$key/$rewrite{$key}/;
+    }
+  if ($point_back && $buff =~ /^\@node\s+([^,]+),\s*([^,]*),\s*([^,]*),\s*(.*)/)
+    {
+    my($t1, $t2, $t4) = ($1, $2, $4);   # so can be decomma'd
+    printf CHAPTERS ("\@node %s, %s, %s, %s\n", &decomma($t1),
+      &decomma($t2), &decomma($point_back), &decomma($t4));
+    undef $point_back;
+    }
+  else { print CHAPTERS $buff; }
+  }
+
+$previous_chapter = $current_chapter;
+
+close(ONECHAPTER);
+unlink($ONECHAPTER);
+}
+
+
+
+##################################################
+#                Main Program                    #
+##################################################
+
+# This is a two-pass algorithm. The first pass goes through and gets the
+# variable names for cross references. The second pass does the real work,
+# but we can't just read through doing the translation in one pass. We need
+# to know the list of chapters in order to build a top-level menu, and for
+# each chapter we need to know the sections in order to build a section
+# menu. Consequently, make use of temporary files to buffer things.
+
+# This script is used for the filter document and the overview as well;
+# flags tell it if it is doing one of them.
+
+$doing_filter = 0;
+$skip_else = 0;
+$in_itemize = 0;
+$lastwasitem = 0;
+
+$chapter_number = 0;
+$section_number = 0;
+
+if ($#ARGV >= 0 && $ARGV[0] eq "-filter")
+  {
+  $doing_filter = 1;
+  shift @ARGV;
+  }
+
+# First pass: Just fish out variable settings. Save the arguments so that
+# they can be reinstated for a second pass.
+
+print STDERR "Scanning for references\n";
+@save_argv = @ARGV;
+
+# Pick up any .set directives right at the very start
+
+while (<>)
+  {
+  last if ! /^\.set\s+(\S+)\s+(.+)$/;
+  $name = $1;
+  $value = $2;
+  $value =~ s/^\"?(.*?)\"?\s*$/$1/;
+  $references{$name} = $value;
+  }
+
+# Now skip everything before the first .chapter except for
+# .index lines that set up indirections. Save these so that
+# the relevant index entries can be duplicated.
+
+while (<>)
+  {
+  if (/^\.chapter\s+(.+)$/)
+    {
+    $chapter_number++;
+    $section_number = 0;
+    $current_chapter = $1;
+    $current_chapter = $current_chapter;
+    $current_section = "";
+    last;
+    }
+
+  if (/^\.index\s+([^\$]+)\s+\$it\{see\s+([^}]+)\}\s*$/)
+    {
+    $indirections{"$2"} = $1;
+    }
+  }
+
+# Do the business
+
+while (<>)
+  {
+  if (/^\.chapter\s+(.+)$/)
+    {
+    $current_chapter = $1;
+    $current_chapter = &dequote($current_chapter);
+    $current_section = "";
+    }
+  elsif (/^\.section\s+(.+)$/)
+    {
+    $current_section = $1;
+    $current_section = &dequote($current_section);
+    $current_section =~ s/://;
+    }
+  elsif (/^\.r?set\s+(\S+)\s+(.+)$/ && $1 ne "runningfoot")
+    {
+    $name = $1;
+    $value = $2;
+
+    # Only set the first time. This handles a few special cases in part2
+    # which is included in the filter text as well.
+
+    if (!exists($references{$name}))
+      {
+      $value =~ s/^\"?(.*?)\"?\s*$/$1/;
+      $value =~ s/~~chapter\./~~chapter****/;
+      $value =~ s/~~chapter/$current_chapter/;
+      $value =~ s/~~section/$current_section/;
+      $references{$name} = $value;
+      }
+    }
+  }
+
+$final_chapter = defined($current_chapter)? $current_chapter : "";
+
+# Reinstate ARGV with the list of files and proceed to the main pass
+
+@ARGV = @save_argv;
+
+# $asis is set true when processing .display asis blocks, to stop
+# characters getting interpreted.
+
+$asis = 0;
+
+# $indisplay is set true while processing .display blocks, to stop
+# .newlines being handled therein (adding @* wrecks alignment)
+
+$indisplay = 0;
+
+# $tab is set to the value of the tab stop - only one stop is ever used
+# in the Exim source.
+
+$tab = 0;
+
+# Current driver name, for disambiguating nodes
+
+$driver_name = "";
+
+# $section_pending is set if a new section is to be started on hitting
+# any data lines.
+
+$section_pending = 0;
+
+# Open a file to buffer up the entire set of chapters
+
+$CHAPTERS = "/tmp/CHAPTERS.$$";
+open(CHAPTERS, ">$CHAPTERS") || die "Can't open $CHAPTERS for writing";
+
+# Skip everything before the first .chapter
+
+while (<>) { last if /^\.chapter /; }
+
+# Loop, handling each chapter
+
+$current_up = "";
+$previous_chapter = "Top";
+$previous_node = "Top";
+
+$chapter_number = 0;
+$section_number = 0;
+
+while (defined ($_) && /^\.chapter /)
+  {
+  handle_chapter();
+  }
+
+# Output the stuff at the start of the file
+
+print "\\input texinfo\n";
+
+print "\@set{wmYear} 2003\n";
+print "\@set{wmAuthor} Philip Hazel\n";
+print "\@set{wmAuthor_email} <ph10\@\@cus.cam.ac.uk>\n";
+print "\@set{COPYRIGHT1} Copyright \@copyright{} \@value{wmYear} University of Cambridge\n";
+
+print "\@c %**start of header\n";
+
+if (!$doing_filter)
+  {
+  print "\@setfilename spec.info\n";
+  print "\@settitle Exim Specification\n";
+  }
+else
+  {
+  print "\@setfilename filter.info\n";
+  print "\@settitle Exim Filter Specification\n";
+  }
+
+print "\@paragraphindent 0\n";
+print "\@c %**end of header\n\n";
+
+
+print "\@titlepage\n";
+print "\@title The Exim Mail Transfer Agent\n";
+print "\@author \@value{wmAuthor}\n";
+
+print "\@page\n";
+print "\@vskip 0pt plus 1filll\n";
+
+print "Permission is granted to make and distribute verbatim copies of this manual provided the\n";
+print "copyright notice and this permission notice are preserved on all copies.\n";
+
+print "\@sp2\n";
+print "\@value{COPYRIGHT1}\@*\n";
+
+print "\@end titlepage\n\n";
+
+# Output the top-level node and its introductory blurb
+
+print "\@node       Top,       $chapter_list[0], (dir), (dir)\n";
+print "\@top\n";
+
+if (!$doing_filter)
+{
+print <<End;
+The Exim Mail Transfer Agent\@*
+****************************
+
+The specification of the Exim Mail Transfer Agent is converted mechanically
+into Texinfo format from its original marked-up source. Some typographic
+representations are changed, chapters and sections cannot be numbered, and
+Texinfo lacks the ability to mark updated parts of the specification with
+change bars.
+
+Because the chapters and sections are unnumbered, cross references are set to
+their names. This makes the English a bit odd, with phrases like \`see chapter
+\"Retry configuration\"\' but it seemed very cumbersome to change this to \`see
+the chapter entitled \"Retry configuration\"\' each time.
+
+Each chapter, section, and configuration option has been placed in a separate
+Texinfo node. Texinfo doesn\'t allow commas, colons, or apostrophes in node
+names, which is a rather nasty restriction. I have arranged not to use colons
+or apostrophes in section titles, but cannot bring myself to omit them from
+titles such as \"The foo, bar and baz commands\". For the corresponding node
+names I have just used multiple occurrences of \"and\", though it looks very
+ugly.
+
+If a chapter or section continues after a list of configuration options that is
+not in a new section, a new node is started, using the chapter\'s or section\'s
+name plus \`(continued)\'. The \`Up\' operation from a section or configuration
+option returns to the start of the current chapter; the \`Up\' operation at a
+chapter start returns to the top of the document; the \`Up\' in a list of
+configuration options within a section returns to the top of that section.
+
+A number of drivers have options with the same name, so they have been
+disambiguated by adding the name of the driver to its option names in order to
+create node names. Thus, for example, the specification of the \`command\'
+options of the \`lmtp\' and \`pipe\' transports are in nodes called \`command
+(lmtp)\' and \`command (pipe)\', respectively.
+
+End
+}
+
+else
+{
+print <<End;
+Filtering with the Exim Mail Transfer Agent\@*
+*******************************************
+
+The specifications of the Exim Mail Transfer Agent\'s filtering facility is
+converted mechanically into Texinfo format from its original marked-up source.
+Some typographic representations are changed, chapters and sections cannot be
+numbered, and Texinfo lacks the ability to mark updated parts of the
+specification with change bars.
+
+Because the chapters and sections are unnumbered, cross references are set to
+their names. This makes the English a bit odd, with phrases like \`see section
+\"Multiple personal mailboxes\"\' but it seemed very cumbersome to change this to
+\`see the section entitled \"Multiple personal mailboxes\"\' each time.
+
+End
+}
+
+# Output the top-level menu
+
+print "\@menu\n";
+
+while (scalar(@chapter_list))
+  {
+  $name = &decomma(shift(@chapter_list));
+  print "* ${name}::\n";
+  }
+print "* Concept Index::\n" if (!$doing_filter);
+print "\@end menu\n\n";
+
+# Copy the chapters, then delete the temporary file
+
+close(CHAPTERS);
+open(CHAPTERS, "$CHAPTERS") || die "Can't open $CHAPTERS for reading";
+print $buff while($buff = <CHAPTERS>);
+close(CHAPTERS);
+unlink($CHAPTERS);
+
+# Output the finishing off stuff
+
+if (!$doing_filter)
+  {
+  print "\@node Concept Index, , $final_chapter, Top\n";
+  print "\@chapter Concept Index\n\@printindex cp\n";
+  print "\@chapter Function Index\n\@printindex fn\n";
+  }
+print "\@contents\n";
+print "\@bye\n";
+
+# End