Added -dd for daemon debugging.
[users/jgh/exim.git] / doc / doc-scripts / g2h
1 #! /usr/bin/perl -w
2 # $Cambridge: exim/doc/doc-scripts/g2h,v 1.1 2004/10/07 15:04:35 ph10 Exp $
3
4 # This is a script that turns the SGCAL source of Exim's documentation into
5 # HTML. It can be used for both the filter document and the main Exim
6 # specification. The syntax is
7 #
8 #    g2h [-split no|section|chapter] <source file> <title>
9 #
10 # Previously, -split section was used for the filter document, and -split
11 # chapter for the main specification. However, the filter document has gained
12 # some chapters, so they are both split by chapter now. Only one -split can be
13 # specified.
14 #
15 # A number of assumptions about the style of the input markup are made.
16 #
17 # The HTML is written into the directory html/ using the source file base
18 # name as its base.
19
20 # Written by Philip Hazel
21 # Starting 21-Dec-2001
22 # Last modified 26-Nov-2003
23
24 #############################################################################
25
26
27
28 ##################################################
29 #             Open an output file                #
30 ##################################################
31
32 sub openout {
33 open (OUT, ">$_[0]") || die "Can't open $_[0]\n";
34
35 # Boilerplate
36
37 print OUT "<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML//EN\">\n";
38
39 print OUT "<html>\n<head>\n<title>$doctitle" .
40   (($thischapter > 0)? " chapter $thischapter" : "") .
41   (($thissection > 0)? " section $thissection" : "") .
42   "</title>\n</head>\n" .
43   "<body bgcolor=\"#F8F8F8\" text=\"#00005A\" " .
44   "link=\"#FF6600\" alink=\"#FF9933\" vlink=\"#990000\">\n";
45
46 # Forward/backward links when chapter splitting
47
48 if ($chapsplit)
49   {
50   print OUT "<font size=2>\n";
51   printf OUT ("<a href=\"${file_base}_%s.html\">Previous</a>&nbsp;&nbsp;\n",
52     $thischapter - 1) if $thischapter > 1;
53   printf OUT ("<a href=\"${file_base}_%s.html\">Next</a>&nbsp;&nbsp;\n",
54     $thischapter + 1) if $thischapter < $maxchapter;
55   print OUT "<a href=\"${file_base}_toc.html\">Contents</a>\n";
56   print OUT "&nbsp;" x 6, "($doctitle)\n</font><hr>\n";
57   }
58
59 # Forward/backward links when section splitting
60
61 elsif ($sectsplit)
62   {
63   print OUT "<font size=2>\n";
64   printf OUT ("<a href=\"${file_base}_%s.html\">Previous</a>&nbsp;&nbsp;\n",
65     $thissection - 1) if $thissection > 1;
66   printf OUT ("<a href=\"${file_base}_%s.html\">Next</a>&nbsp;&nbsp;\n",
67     $thissection + 1) if $thissection < $maxsection;
68   print OUT "<a href=\"${file_base}_toc.html\">Contents</a>\n";
69   print OUT "&nbsp;" x 6, "($doctitle)\n</font><hr>\n";
70   }
71
72 # Save the final component of the current file name (for TOC creation)
73
74 $_[0] =~ /^(?:.*)\/([^\/]+)$/;
75 $current_file = $1;
76 }
77
78
79
80 ##################################################
81 #              Close an output file              #
82 ##################################################
83
84 # The first argument is one of:
85 #
86 # "CHAP"   a chapter is ending
87 # "SECT"   a section is ending
88 # ""       the whole thing is ending
89 #
90 # In the first two cases $thischapter and $thissection contain the new chapter
91 # and section numbers, respectively. In the third case, we can deduce what is
92 # ending from the flags. The variables contain the current values.
93
94 sub closeout {
95 my($s) = $_[0];
96
97 print OUT "<hr>\n" if !$lastwasrule;
98 &setpar(0);
99
100 if ($s eq "CHAP")
101   {
102   print OUT "<font size=2>\n";
103   printf OUT ("<a href=\"${file_base}_%s.html\">Previous</a>&nbsp;&nbsp;",
104     $thischapter - 2) if ($thischapter > 2);
105   print OUT "<a href=\"${file_base}_$thischapter.html\">Next</a>&nbsp;&nbsp;";
106   print OUT "<a href=\"${file_base}_toc.html\">Contents</a>\n";
107   print OUT "&nbsp;" x 6, "($doctitle)\n</font>\n";
108   }
109
110 elsif ($s eq "SECT")
111   {
112   print OUT "<font size=2>\n";
113   printf OUT ("<a href=\"${file_base}_%s.html\">Previous</a>&nbsp;&nbsp;",
114     $thissection - 2) if ($thissection > 2);
115   print OUT "<a href=\"${file_base}_$thissection.html\">Next</a>&nbsp;&nbsp;";
116   print OUT "<a href=\"${file_base}_toc.html\">Contents</a>\n";
117   print OUT "&nbsp;" x 6, "($doctitle)\n</font>\n";
118   }
119
120 else
121   {
122   if ($chapsplit)
123     {
124     print OUT "<font size=2>\n";
125     printf OUT ("<a href=\"${file_base}_%s.html\">Previous</a>&nbsp;&nbsp;",
126       $thischapter - 1) if ($thischapter > 1);
127     print OUT "<a href=\"${file_base}_toc.html\">Contents</a>\n";
128     print OUT "&nbsp;" x 6, "($doctitle)\n</font>\n";
129     }
130   elsif ($sectsplit)
131     {
132     print OUT "<font size=2>\n";
133     printf OUT ("<a href=\"${file_base}_%s.html\">Previous</a>&nbsp;&nbsp;",
134       $thissection - 1) if ($thissection > 1);
135     print OUT "<a href=\"${file_base}_toc.html\">Contents</a>\n";
136     print OUT "&nbsp;" x 6, "($doctitle)\n</font>\n";
137     }
138   }
139
140 print OUT "</body>\n</html>\n";
141 close(OUT);
142 }
143
144
145
146 ##################################################
147 #            Handle an index line                #
148 ##################################################
149
150 # This function returns an empty string so that it can be called as part
151 # of an s operator when handling index items within paragraphs. The two
152 # arguments are:
153 #
154 #   the text to index, already converted to HTML
155 #   1 for the concept index, 0 for the options index
156
157 sub handle_index {
158 my($text) = $_[0];
159 my($hash) = $_[1]? \%cindex : \%oindex;
160 my ($key,$ref);
161
162 # Up the index count, and compute the reference to the file and the
163 # label within it.
164
165 $index_count++;
166 $ref = $chapsplit?
167       "${file_base}_$thischapter.html#IX$index_count"
168   : $sectsplit?
169       "${file_base}_$thissection.html#IX$index_count"
170   :
171       "#IX$index_count";
172
173 # Create the index key, which consists of the text with all the HTML
174 # coding and any leading quotation marks removed. Turn the primary/secondary
175 # splitting string "||" into ":".
176
177 $text =~ s/\|\|/:/g;
178
179 $key = "$text";
180 $key =~ s/<[^>]+>//g;
181 $key =~ s/&#(\d+);/chr($1)/eg;
182 $key =~ s/^`+//;
183
184 # Turn all spaces in the text into &nbsp; so that they don't ever split.
185 # However, there may be spaces in the HTML that already exists in the
186 # text, so we have to avoid changing spaces inside <>.
187
188 $text =~ s/ (?=[^<>]*(?:<|$))/&nbsp;/g;
189
190 # If this is the first encounter with this index key, we create a
191 # straightforward reference.
192
193 if (!defined $$hash{$key})
194   {
195   $$hash{$key} = "<a href=\"$ref\">$text</a>";
196   }
197
198 # For the second and subsequent encounters, add "[2]" etc. to the
199 # index text. We find out the number by counting occurrences of "<a"
200 # in the existing string.
201
202 else
203   {
204   my($number) = 1;
205   $number++ while $$hash{$key} =~ /<a/g;
206   $$hash{$key} .= " &nbsp;<a href=\"$ref\">[$number]</a>";
207   }
208
209 # Place the name in the current output
210
211 print OUT "<a name=\"IX$index_count\"></a>\n";
212 return "";
213 }
214
215
216
217 ##################################################
218 #             Handle emphasis bars               #
219 ##################################################
220
221 # Set colour green for text marked with "emphasis bars", keeping
222 # track in case the matching isn't perfect.
223
224 sub setinem {
225 if ($_[0])
226   {
227   return "" if $inem;
228   $inem = 1;
229   return "<font color=green>\n";
230   }
231 else
232   {
233   return "" if !$inem;
234   $inem = 0;
235   return "</font>\n";
236   }
237 }
238
239
240
241 ##################################################
242 #          Convert marked-up text                #
243 ##################################################
244
245 # This function converts text from SGCAL markup to HTML markup, with a couple
246 # of exceptions:
247 #
248 # 1. We don't touch $t because that is handled by the .display code.
249 #
250 # 2. The text may contain embedded .index, .em, and .nem directives. We
251 #    handle .em and .nem, but leave .index because it must be done during
252 #    paragraph outputting.
253 #
254 # In a non-"rm" display, we turn $rm{ into cancelling of <tt>. Otherwise
255 # it is ignored - in practice it is only used in that special case.
256 #
257 # The order in which things are done in this function is highly sensitive!
258
259 sub handle_text {
260 my($s) = $_[0];
261 my($rmspecial) = $_[1];
262
263 # Escape all & characters (they aren't involved in markup) but for the moment
264 # use &+ instead of &# so that we can handle # characters in the text.
265
266 $s =~ s/&/&+038;/g;
267
268 # Turn SGCAL literals into HTML literals that don't look like SGCAL
269 # markup, so won't be touched by what follows. Again, use + instead of #.
270
271 $s =~ s/@@/&+064;/g;
272 $s =~ s/@([^@])/"&+".sprintf("%0.3d",ord($1)).";"/eg;
273
274 # Now turn any #s that are markup into spaces, and convert the previously
275 # created literals to the correct form.
276
277 $s =~ s/#/&nbsp;/g;
278 $s =~ s/&\+(\d+);/&#$1;/g;
279
280 # Some simple markup that doesn't involve argument text.
281
282 $s =~ s/\$~//g;                   # turn $~  into nothing
283 $s =~ s/__/_/g;                   # turn __  into _
284 $s =~ s/--(?=$|\s|\d)/&#150;/mg;  # turn --  into endash in text or number range
285 $s =~ s/\(c\)/&copy;/g;           # turn (c) into copyright symbol
286
287 # Use double quotes
288
289 # $s =~ s/`([^']+)'/``$1''/g;
290
291 $s =~ s/`([^']+)'/&#147;$1&#148;/g;
292
293 # This is a fudge for some specific usages of $<; can't just do a global
294 # is it occurs in things like "$<variable name>" as well.
295
296 $s =~ s/(\d)\$<-/$1-/g;  # turn 0$<- into 0-
297 $s =~ s/\$<//g;          # other $< is ignored
298
299 # Turn <<...>> into equivalent SGCAL markup that doesn't involve the use of
300 # < and >, and then escape the remaining < and > characters in the text.
301
302 $s =~ s/<<([^>]*?)>>/<\$it{$1}>/g;   # turn <<xxx>> into <$it{xxx}>
303 $s =~ s/</&#060;/g;
304 $s =~ s/>/&#062;/g;
305
306 # Other markup...
307
308 $s =~ s/\$sm\{//g;              # turn $sm{     into nothing
309 $s =~ s/\$smc\{//g;             # turn $smc{    into nothing
310 $s =~ s/\$smi\{//g;             # turn $smi{    into nothing
311
312 $s =~ s/\$tt\{([^\}]*?)\}/<tt>$1<\/tt>/g;    # turn $tt{xxx} into <tt>xxx</tt>
313 $s =~ s/\$it\{([^\}]*?)\}/<em>$1<\/em>/g;    # turn $it{xxx} into <em>xxx</em>
314 $s =~ s/\$bf\{([^\}]*?)\}/<b>$1<\/b>/g;      # turn $bf{xxx} into <b>xxx</b>
315
316 $s =~ s/\$cb\{([^\}]*?)\}/<tt><b>$1<\/b><\/tt>/g; # turn $cb{xxx} into
317                                                   #   <tt><b>xxx</b></tt>
318
319 $s =~ s/\\\\([^\\]*?)\\\\/<font size=-1>$1<\/font>/g; # turn \\xxx\\ into
320                                                       #  small font
321 $s =~ s/\\\?([^?]*?)\?\\/<a href="$1">$1<\/a>/g;      # turn \?URL?\ into URL
322
323 $s =~ s/\\\(([^)]*?)\)\\/<i>$1<\/i>/g;       # turn \(xxx)\ into <i>xxx</i>
324 $s =~ s/\\\"([^\"]*?)\"\\/<tt>$1<\/tt>/g;    # turn \"xxx"\ into <tt>xxx</tt>
325
326
327 $s =~ s/\\\$([^\$]*?)\$\\/<tt>\$$1<\/tt>/g;  # turn \$xxx$\   into <tt>$xxx</tt>
328 $s =~ s/\\\-([^\\]*?)\-\\/<i>-$1<\/i>/g;     # turn \-xxx-\   into -italic
329 $s =~ s/\\\*\*([^*]*?)\*\*\\/<b>$1<\/b>/g;   # turn \**xxx**\ into <b>xxx</b>
330 $s =~ s/\\\*([^*]*?)\*\\/<i>$1<\/i>/g;       # turn \*xxx*\   into italic
331 $s =~ s/\\%([^*]*?)%\\/<b>$1<\/b>/g;         # turn \%xxx%\   into bold
332 $s =~ s/\\([^\\]*?)\\/<tt>$1<\/tt>/g;        # turn \xxx\     into <tt>xxx</tt>
333 $s =~ s/::([^\$]*?)::/<i>$1:<\/i>/g;         # turn ::xxx::   into italic:
334 $s =~ s/\$\*\$/\*/g;                         # turn $*$       into *
335
336 # Handle $rm{...}
337
338 if ($rmspecial)
339   {
340   $s =~ s/\$rm\{([^\}]*?)\}/<\/tt>$1<tt>/g;  # turn $rm{xxx} into </tt>xxx<tt>
341   }
342 else
343   {
344   $s =~ s/\$rm\{([^\}]*?)\}/$1/g;            # turn $rm{xxx} into xxx
345   }
346
347 # There is one case where the terminating } of an escape sequence is
348 # in another paragraph - this follows $sm{ - it can be fixed by
349 # removing any stray } in a paragraph that contains no { chars.
350
351 $s =~ s/\}//g if !/\{/;
352
353 # Remove any null flags ($$)
354
355 $s =~ s/\$\$//g;
356
357 # If the paragraph starts with $c\b, remove it.
358
359 $s =~ s/^\$c\b//;
360
361 # If the paragraph starts with $e\b, indent it slightly.
362
363 $s =~ s/^\$e\b/&nbsp;&nbsp;/;
364
365 # Handle .em, and .nem directives that occur within the paragraph
366
367 $s =~ s/\.em\s*\n/&setinem(1)/eg;
368 $s =~ s/\.nem\s*\n/&setinem(0)/eg;
369
370 # Explicitly included HTML
371
372 $s =~ s/\[\(([^)]+)\)\]/<$1>/g;  # turn [(...)] into <...>
373
374 # Finally, do the substitutions and return the modified text.
375
376 $s =~ s/~~(\w+)/$var_value{$1}/eg;
377
378 return $s;
379 }
380
381
382
383 ##################################################
384 #            Start/end a paragraph               #
385 ##################################################
386
387 # We want to leave paragraphs unterminated until we know that a horizontal
388 # rule does not follow, to avoid getting space inserted before the rule,
389 # which doesn't look good. So we have this function to help control things.
390 # If the argument is 1 we are starting a new paragraph; if it is 0 we want
391 # to force the ending of any incomplete paragraph.
392
393 sub setpar {
394 if ($inpar)
395   {
396   print OUT "</p>\n";
397   $inpar = 0;
398   }
399 if ($_[0])
400   {
401   print OUT "<p>\n";
402   $inpar = 1;
403   }
404 }
405
406
407
408 ##################################################
409 #            Handle a "paragraph"                #
410 ##################################################
411
412 # Read a paragraph of text, which may contain many lines and may contain
413 # .index, .em, and .nem directives within it. We may also encounter
414 # ".if ~~html" within paragraphs. Process those directives,
415 # convert the markup, and output the rest as an HTML paragraph.
416
417
418 sub handle_paragraph{
419 my($par) = $_;
420 my($htmlcond) = 0;
421 while(<IN>)
422   {
423   if (/^\.if\s+~~html\b/)
424     {
425     $htmlcond = 1;
426     $par =~ s/\s+$//;         # lose unwanted whitespace and newlines
427     next;
428     }
429   elsif ($htmlcond && /^\.else\b/)
430     {
431     while (<IN>) { last if /^\.fi\b/; }
432     $htmlcond = 0;
433     next;
434     }
435   elsif ($htmlcond && /^\.fi\b/)
436     {
437     $htmlcond = 0;
438     next;
439     }
440
441   last if /^\s*$/ || (/^\./ && !/^\.index\b/ && !/^\.em\b/ && !/^\.nem\b/);
442   $par .= $_;
443   }
444 $par = &handle_text($par, 0);
445
446 # We can't handle .index until this point, when we do it just before
447 # outputting the paragraph.
448
449 if ($par !~ /^\s*$/)
450   {
451   &setpar(1);
452   $par =~ s/\.index\s+([^\n]+)\n/&handle_index($1, 1)/eg;
453   print OUT "$par";
454   }
455 }
456
457
458
459 ##################################################
460 #         Handle a non-paragraph directive       #
461 ##################################################
462
463 # The directives .index, .em, and .nem can also appear within paragraphs,
464 # and are then handled within the handle_paragraph() code.
465
466 sub handle_directive{
467 my($new_lastwasitem) = 0;
468
469 $lastwasrule = 0;
470
471 if (/^\.r?set\b/ || /^\.(?:\s|$)/) {}      # ignore .(r)set and comments
472
473 elsif (/^\.justify\b/) {}                  # and .justify
474
475 elsif (/^\.newline\b/) { print OUT "<br>\n"; }
476
477 elsif (/^\.blank\b/ || /^\.space\b/) { print OUT "<br>\n"; }
478
479 elsif (/^\.rule\b/)  { &setpar(0); print OUT "<hr>\n"; $lastwasrule = 1; }
480
481 elsif (/^\.index\s+(.*)/) { &handle_index(&handle_text($1), 1); }
482
483 # Emphasis is handled by colour
484
485 elsif (/^\.em\b/)
486   {
487   &setpar(0);
488   print OUT "<font color=green>" if ! $inem;
489   $inem = 1;
490   }
491
492 elsif (/^\.nem\b/)
493   {
494   &setpar(0);
495   print OUT "</font>" if $inem;
496   $inem = 0;
497   }
498
499 # Ignore tab setting stuff - we use tables instead.
500
501 elsif (/^\.tabs(?:et)?\b/) {}
502
503 # .tempindent is used only to align some of the expansion stuff nicely;
504 # just ignore it. It is used in conjunction with .push/.pop.
505
506 elsif (/^\.(tempindent|push|pop)\b/) {}
507
508 # There are some instances of .if ~~sys.fancy in the source. Some of those
509 # that are not inside displays are two-part things, in which case we just keep
510 # the non-fancy part. For diagrams, however, they are in three parts:
511 #
512 # .if ~~sys.fancy
513 # <aspic drawing stuff for PostScript and PDF>
514 # .elif !~~html
515 # <ascii art for txt and Texinfo>
516 # .else
517 # <HTML instructions for including a gif>
518 # .fi
519 #
520 # In this case, we skip to the third part.
521
522 elsif (/^\.if\s+~~sys\.fancy/ || /^\.else\b/)
523   {
524   while (<IN>)
525     { last if /^\.else\b/ || /^\.elif\s+!\s*~~html/ || /^\.fi\b/; }
526
527   if (/^\.elif\b/)
528     {
529     while (<IN>) { last if /^\.else\b/ || /^\.fi\b/; }
530     }
531   }
532
533 # Similarly, for .if !~~sys.fancy, take the non-fancy part.
534
535 elsif (/^\.if\s+!\s*~~sys.fancy/) {}
536
537 # There are some explicit tests for ~~html for direct HTML inclusions
538
539 elsif (/^\.if\s+~~html\b/) {}
540
541 # There are occasional requirements to do things differently for Texinfo/HTML
542 # and PS/txt versions. The latter are produced by SGCAL, so that's what the
543 # flag is called.
544
545 elsif (/\.if\s+~~sgcal/)
546   {
547   while (<IN>) { last if /\.else\b/ || /\.fi\b/; }
548   }
549
550 # Also there is a texinfo flag
551
552 elsif (/^\.if\s+~~texinfo\b/)
553   {
554   while (<IN>)
555     { last if /^\.else\b/ || /^\.elif\s+!\s*~~html/ || /^\.fi\b/; }
556   }
557
558 # Ignore any other .if, .else, or .fi directives
559
560 elsif (/^\.if\b/ || /^\.fi\b/ || /^\.else\b/) {}
561
562 # Ignore .indent
563
564 elsif (/^\.indent\b/) {}
565
566 # Various flavours of numberpars map to corresponding list types.
567
568 elsif (/^\.numberpars\b/)
569   {
570   $rest = $';
571   &setpar(0);
572
573   if ($rest =~ /(?:\$\.|\" \")/)
574     {
575     unshift @endlist, "ul";
576     unshift @listtype, "";
577     print OUT "<ul>\n<li>";
578     }
579   else
580     {
581     $nptype = ($rest =~ /roman/)? "a" : "1";
582     unshift @endlist, "ol";
583     unshift @listtype, " TYPE=\"$nptype\"";
584     print OUT "<ol>\n<li$listtype[0]>";
585     }
586   }
587
588 elsif (/^\.nextp\b/)
589   {
590   &setpar(0);
591   print OUT "</li>\n<li$listtype[0]>";
592   }
593
594 elsif (/^\.endp\b/)
595   {
596   &setpar(0);
597   print OUT "</li>\n</$endlist[0]>\n";
598   shift @listtype;
599   shift @endlist;
600   }
601
602 # .display asis can use <pre> which uses a typewriter font.
603 # Otherwise, we have to do our own line breaking. Turn tabbed lines
604 # into an HTML table. There will always be a .tabs line first.
605
606 elsif (/^\.display\b/)
607   {
608   my($intable) = 0;
609   my($asis) = /asis/;
610   my($rm) = /rm/;
611   my($eol,$indent);
612
613   # For non asis displays, start a paragraph, and set up to put an
614   # explicit break after every line.
615
616   if (!$asis)
617     {
618     &setpar(1);
619     $eol = "<br>";
620     $indent = "<tt>&nbsp;&nbsp;</tt>";
621     }
622
623   # For asis displays, use <pre> and no explicit breaks
624
625   else
626     {
627     print OUT "<pre>\n";
628     $eol = "";
629     $indent = "&nbsp;&nbsp;";
630     }
631
632   # Now read through until we hit .endd (or EOF, but that shouldn't happen)
633   # and process the lines in the display.
634
635   while (<IN>)
636     {
637     last if /^\.endd\b/;
638
639     # The presence of .tabs[et] starts a table
640
641     if (/^\.tabs/)
642       {
643       $intable = 1;
644       print OUT "<table cellspacing=0 cellpadding=0>\n";
645       }
646
647     # Some displays have an indent setting - ignore
648
649     elsif (/^\.indent\b/) {}
650
651     # Some displays have .blank inside them
652
653     elsif (/^\.blank\b/)
654       {
655       print OUT "<br>\n";
656       }
657       
658     # Some displays have emphasis inside them
659     
660     elsif (/^\.em\b/)
661       {
662       print OUT "<font color=green>" if ! $inem;
663       $inem = 1;
664       }    
665
666     elsif (/^\.nem\b/)
667       {
668       print OUT "</font>" if $inem;
669       $inem = 0;
670       }    
671
672     # There are occasional instances of .if [!]~~sys.fancy inside displays.
673     # In both cases we want the non-fancy alternative. (The only thing that
674     # matters in practice is noticing .tabs[et] actually.) Assume the syntax
675     # is valid.
676
677     elsif (/^\.if\s+~~sys.fancy/ || /^\.else\b/)
678       {
679       while (<IN>)
680         {
681         last if /^\.fi\b/ || /^\.else/;
682         }
683       }
684
685     elsif (/^\.if\s+!\s*~~sys.fancy/) {}
686
687     elsif (/^\.fi\b/) {}
688
689     # Ignore .newline and .linelength
690
691     elsif (/^\.newline\b/ || /^\.linelength\b/) {}
692     
693     # Ignore comments
694     
695     elsif (/^\.(\s|$)/) {}  
696
697     # There shouldn't be any other directives inside displays
698
699     elsif (/^\./)
700       {
701       print "*** Ignored directive inside .display: $_";
702       }
703
704     # Handle a data line within a display. If it's an asis display, the only
705     # conversion is to escape the HTML characters. Otherwise, process the
706     # SGCAL markup.
707
708     else
709       {
710       chomp;
711       if ($asis)
712         {
713         s/&/&#038;/g;
714         s/</&#060;/g;
715         s/>/&#062;/g;
716         }
717       else
718         {
719         $_ = &handle_text($_, !$rm);
720         $_ = "<tt>$_</tt>" if !$rm && $_ ne "";
721         }
722
723       # In a table, break fields at $t. For non-rm we must break the
724       # <tt> group as well.
725
726       if ($intable)
727         {
728         if ($rm)
729           {
730           s/\s*\$t\s*/&nbsp;&nbsp;<\/td><td>/g;
731           }
732         else
733           {
734           s/\s*\$t\s*/&nbsp;&nbsp;<\/tt><\/td><td><tt>/g;
735           }
736         s/<tt><\/tt>//g;
737         print OUT "<tr><td>&nbsp;&nbsp;$_</td></tr>\n";
738         }
739
740       # Otherwise, output straight, with <br> for non asis displays
741
742       else
743         {
744         s/<tt><\/tt>//g;
745         print OUT "$indent$_$eol\n";
746         }
747       }
748     }    # Loop for display contents
749
750   # Finish off the table and the <pre> - leave a paragraph open
751
752   print OUT "</table>\n" if $intable;
753   print OUT "</pre>\n" if $asis;
754   }
755
756 # Handle configuration option definitions
757
758 elsif (/^\.startconf\b/) {}
759
760 elsif (/^\.conf\b/)
761   {
762   my($option, $type, $default) =
763     /^\.conf\s+(\S+)\s+("(?:[^"]|"")+"|\S+)\s+("(?:[^"]|"")+"|.*)/;
764
765   $option =~ s/\@_/_/g;       # Underscore will be quoted in option name
766
767   # If $type ends with $**$, add ",expanded" as there doesn't seem to be
768   # a dagger character generally available.
769
770   $type =~ s/^"([^"]+)"/$1/;
771   $type =~ s/\$\*\*\$/, expanded/;
772
773   # Default may be quoted, and it may also have quotes that are required,
774   # if it is a string.
775
776   $default =~ s/^"(.*)"$/$1/;
777   $default =~ s/""/"/g;
778   $default = &handle_text($default, 0);
779
780   print OUT "<hr>";
781   &setpar(0);
782   &handle_index($option, 0);
783   print OUT "<h3>$option</h3>\n" .
784             "<i>Type:</i>&nbsp; $type<br><i>Default:</i>&nbsp; $default<br>\n";
785   }
786
787 elsif (/^\.endconf\b/)
788   {
789   print OUT "<hr><br>\n";
790   }
791
792
793 # Handle "items" - used for expansion items and the like. We force the
794 # item text into bold, and put a rule between items.
795
796 elsif (/^\.startitems\b/) {}
797
798 elsif (/^\.item\s+(.*)/)
799   {
800   my($arg) = $1;
801   chomp($arg);
802   $arg =~ s/^"(.*)"$/$1/;
803   $arg = &handle_text($arg, 0);
804
805   # If there are two .items in a row, we don't want to put in the
806   # separator line or start a new paragraph.
807
808   if ($lastwasitem)
809     {
810     print OUT "<br>";
811     }
812   else
813     {
814     print OUT "<hr>";
815     &setpar(1);
816     }
817   print OUT "<b>$arg</b>\n";
818   $new_lastwasitem = 1;
819   }
820
821 elsif (/^\.enditems\b/)
822   {
823   print OUT "<hr><br>\n";
824   }
825
826
827 # Handle command line option items
828
829 elsif (/^\.startoptions\b/) {}
830
831 elsif (/^\.option\s+(.*)/)
832   {
833   my($arg) = $1;
834   $arg =~ s/^"(.*)"$/$1/;
835
836   print OUT "<hr>";
837   &setpar(0);
838
839   # For indexing, we want to take up to the first # or < in the line,
840   # before processing.
841
842   my($name) = $arg =~ /^([^#<]+)/;
843   $name = &handle_text($name, 0);
844   &handle_index("-$name", 0);
845
846   # Output as heading, after the index
847
848   $arg = &handle_text($arg, 0);
849   print OUT "<h3>-$arg</h3>\n";
850   }
851
852 elsif (/^\.endoptions\b/)
853   {
854   print OUT "<hr><br>\n";
855   }
856
857 # Found an SGCAL directive that isn't dealt with. Oh dear.
858
859 else
860   {
861   print "*** Unexpected SGCAL directive: line $. ignored:\n";
862   print "$_\n";
863   }
864
865 # Remember if last was a .item, and read the next line
866
867 $lastwasitem = $new_lastwasitem;
868 $_ = <IN>;
869 }
870
871
872
873 ##################################################
874 #         First Pass - collect references        #
875 ##################################################
876
877 sub pass_one{
878 $thischapter = 0;
879
880 open (IN, $source_file) || die "Can't open $source_file (first pass)\n";
881 $_ = <IN>;
882
883 # At the start of the specification text, there are some textual replacement
884 # definitions. They set values, but not cross-references.
885
886 while (/^\.r?set\s+(\S+)\s+"?([^"]+)\"?\s*$/)
887   {
888   $var_value{$1} = $2;
889   $_ = <IN>;
890   }
891
892 # Now skip on till we hit the start of the first chapter. It will be numbered
893 # 0 if we hit ".set chapter -1". There is only ever one unnumbered chapter.
894
895 while (!/^\.chapter/)
896   {
897   $thischapter = -1 if /^\.set\s+chapter\s+-1/;
898   $_ = <IN>;
899   }
900
901 # Loop for handling chapters
902
903 while ($_)
904   {
905   $thischapter++;
906   $thissection = 0;
907
908   # Scan through chapter, setting up cross-references to the chapter
909   # and to the sections within it.
910
911   while (<IN>)
912     {
913     last if /^\.chapter/;
914     chomp;
915
916     if (/^\.section/)
917       {
918       $thissection++;
919       next;
920       }
921
922     # Handle .(r)set directives.
923
924     if (/^\.r?set\s+(\S+)\s+"?([^"]+)\"?\s*$/ && $1 ne "runningfoot")
925       {
926       my($key,$value) = ($1,$2);
927       $value =~ s/~~chapter/$thischapter/e;
928       $value =~ s/~~section/$thissection/e;
929
930       # Only one of $chapsplit or $sectsplit can be set.
931
932       if ($key =~ /^CHAP/)
933         {
934         $value = $chapsplit?
935           "<a href=\"${file_base}_$thischapter.html\">$value</a>"
936           :
937           "<a href=\"#CHAP$thischapter\">$value</a>";
938         }
939
940       elsif ($key =~ /^SECT/)
941         {
942         $value = $chapsplit?
943           "<a href=\"${file_base}_$thischapter.html" .
944             "#SECT$thischapter.$thissection\">$value</a>"
945           :
946           $sectsplit? "<a href=\"${file_base}_$thissection.html\">$value</a>"
947           :
948           "<a href=\"#SECT$thischapter.$thissection\">$value</a>";
949         }
950
951       $var_value{$key} = $value;
952       }
953     }
954   }
955
956 close(IN);
957 }
958
959
960
961
962
963 ##################################################
964 #         Second Pass - generate HTML            #
965 ##################################################
966
967 sub pass_two{
968 my($tocn) = 0;
969 my($inmacro) = 0;
970 my($insection) = 0;
971
972 $inem = 0;
973 $thischapter = 0;
974 $thissection = 0;
975
976 # Open the source file and get the first line
977
978 open (IN, $source_file) || die "Can't open $source_file (2nd pass)\n";
979 $_ = <IN>;
980
981 # Skip on till we hit the start of the first chapter, but note if we
982 # pass ".set chapter -1", which is used to indicate no chapter numbering for 
983 # the first chapter (we number is 0). Keep track of whether we are in macro
984 # definitions or not, and when not, notice occurrences of .index, because this
985 # are the "x see y" type entries.
986
987 while (!/^\.chapter/)
988   {
989   $thischapter = -1 if /^\.set\s+chapter\s+-1/;
990   $inmacro = 1 if /^\.macro/;
991   $inmacro = 0 if /^\.endm/;
992   if (!$inmacro && /^\.index\s+(.*)/)
993     {
994     my($key);
995     my($s) = $1;
996     $s = &handle_text($s, 0);
997     $s =~ s/ /&nbsp;/g;            # All spaces unsplittable
998     $key = "\L$s";
999     $key =~ s/<[^>]+>//g;
1000     $key =~ s/&#(\d+);/chr($1)/eg;
1001     $cindex{$key} = $s;
1002     }
1003   $_ = <IN>;
1004   }
1005   
1006 # Open the TOC file
1007
1008 open (TOC, ">$html/${file_base}_toc.html") ||
1009   die "Can't open $html/${file_base}_toc.html\n";
1010
1011 print TOC "<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML//EN\">\n";
1012 print TOC "<html>\n<head>\n<title>$doctitle Contents</title>\n</head>\n" .
1013   "<body bgcolor=\"#F8F8F8\" text=\"#00005A\" " .
1014   "link=\"#FF6600\" alink=\"#FF9933\" vlink=\"#990000\">\n";
1015 print TOC "<h1>$doctitle</h1><hr>\n<ul>\n";
1016
1017 # Open the data file if we are not splitting at chapters
1018
1019 &openout("$html/${file_base}.html") if !$chapsplit;
1020
1021 # Loop for handling chapters. At the start of this loop, $_ is either EOF,
1022 # or contains a .chapter line.
1023
1024 $firstchapter = $thischapter + 1; 
1025
1026 while ($_)
1027   {
1028   print TOC "</ul>\n" if $insection;
1029   $insection = 0;
1030
1031   $thischapter++;
1032   $thissection = 0;
1033   $lastwasrule = 0;
1034
1035   # Start a new file if required
1036
1037   if ($chapsplit)
1038     {
1039     &closeout("CHAP") if $thischapter != $firstchapter;
1040     &openout("$html/${file_base}_$thischapter.html");
1041     }
1042
1043   # Set up the chapter title. Save it for the TOC. Set up the anchor and
1044   # link back to the TOC and show the title.
1045
1046   $_ =~ /^\.chapter\s+(.*)/;
1047
1048   my($title) = (($thischapter > 0)? "$thischapter. " : "") . &handle_text($1, 0);
1049
1050   $tocn++;
1051   print TOC "<li><a " .
1052     "name=\"TOC$tocn\" " .
1053     "href=\"$current_file#CHAP$thischapter\">$title</a></li>\n";
1054
1055   print OUT "<h1>\n";
1056   print OUT "<a name=\"CHAP$thischapter\" href=\"${file_base}_toc.html#TOC$tocn\">\n";
1057   print OUT "$title\n</a></h1>\n";
1058
1059   # Scan the contents of the chapter
1060
1061   $_ = <IN>;
1062   while ($_)
1063     {
1064     last if /^\.chapter/;
1065
1066     # Handle the start of a new section, starting a new file if required
1067
1068     if (/^\.section\s+(.*)/)
1069       {
1070       $thissection++;
1071
1072       print TOC "<ul>\n" if !$insection;
1073       $insection = 1;
1074
1075       my($title) = (($thischapter > 0)? "$thischapter." : "") .
1076         "$thissection. " . &handle_text($1, 0);
1077
1078       if ($sectsplit)
1079         {
1080         &closeout("SECT");
1081         &openout("$html/${file_base}_$thissection.html");
1082         }
1083
1084       $tocn++;
1085       printf TOC ("<li><a " .
1086         "name=\"TOC$tocn\" " .
1087         "href=\"$current_file#SECT%s$thissection\">%s</a></li>\n",
1088           ($thischapter > 0)? "$thischapter." : "", $title);
1089
1090       &setpar(0);
1091       print OUT "<h2>\n";
1092       printf OUT ("<a name=\"SECT%s$thissection\" ",
1093         ($thischapter > 0)? "$thischapter." : "");
1094       print OUT "href=\"${file_base}_toc.html#TOC$tocn\">\n";
1095       print OUT "$title\n</a></h2>\n";
1096       $_ = <IN>;
1097       $lastwasrule = 0;
1098       }
1099
1100     # Blank lines at this level are ignored
1101
1102     elsif (/^\s*$/)
1103       {
1104       $_ = <IN>;
1105       }
1106
1107     # Directive and non-directive lines are handled independently, though
1108     # in each case further lines may be read. Afterwards, the next line is
1109     # in $_. If .em is at the start of a paragraph, treat it with the
1110     # paragraph, because the matching .nem will be too. Messy!
1111
1112     elsif (/^\./)
1113       {
1114       if (/^\.em\b/)
1115         {
1116         $_=<IN>;
1117         if (/^\./)
1118           {
1119           print OUT "<font color=green>" if ! $inem;
1120           $inem = 1;
1121           # Used to handle it here - but that fails if it is .section.
1122           # Just let the next iteration of the loop handle it.  
1123           # &handle_directive();
1124           }
1125
1126         else
1127           {
1128           $_ = ".em\n" . $_;
1129           &handle_paragraph();
1130           $lastwasrule = 0;
1131           $lastwasitem = 0;
1132           }
1133         }
1134
1135       # Not .em
1136
1137       else
1138         {
1139         &handle_directive();
1140         }
1141       }
1142
1143     # Not a directive
1144
1145     else
1146       {
1147       &handle_paragraph();
1148       $lastwasrule = 0;
1149       $lastwasitem = 0;
1150       }
1151
1152     } # Loop for each line in a chapter
1153   }   # Loop for each chapter
1154
1155 # Close the last file, end off the TOC, and we are done.
1156
1157 &closeout("");
1158
1159 print TOC "</ul>\n" if $insection;
1160
1161 if (defined %cindex)
1162   {
1163   $cindex_tocn = ++$tocn;
1164   print TOC "<li><a name=\"TOC$tocn\" ".
1165     "href=\"${file_base}_cindex.html\">Concept Index</a></li>\n";
1166   }
1167
1168 if (defined %oindex)
1169   {
1170   $oindex_tocn = ++$tocn;
1171   print TOC "<li><a name=\"TOC$tocn\" ".
1172     "href=\"${file_base}_oindex.html\">Option Index</a></li>\n";
1173   }
1174
1175 print TOC "</ul>\n</body>\n</html>\n";
1176 close(TOC);
1177 close(IN);
1178 }
1179
1180
1181
1182
1183 ##################################################
1184 #           Adjust index points                  #
1185 ##################################################
1186
1187 # Because of the way the source is written, there are often index entries
1188 # that immediately follow the start of chapters and sections and the definition
1189 # of "items" like "helo = verify". This gets the correct page numbers for the
1190 # PostScript and PDF formats. However, for HTML we want the index anchor to be
1191 # before the section heading, because browsers tend to put the index point at
1192 # the top of the screen. So we re-read all the files we've just created, and
1193 # move some of the index points about. This is necessary only if indexes exist.
1194 # The files are small enough to be handled entirely in memory.
1195
1196 sub adjust_index_points {
1197 print "Adjusting index points to precede headings\n";
1198
1199 $" = "";
1200
1201 opendir(DIR, "$html") || die "Failed to opendir $html\n";
1202 while ($file = readdir(DIR))
1203   {
1204   my($i);
1205   next unless $file =~ /^${file_base}_\d+\.html$/;
1206
1207   open(IN, "<$html/$file") ||
1208     die "Failed to open $html/$file (read)\n";
1209   my(@lines) = <IN>;
1210   close(IN);
1211
1212   for ($i = 0; $i < @lines; $i++)
1213     {
1214     if ($lines[$i] =~ /^<a name="IX\d+"><\/a>$/)
1215       {
1216       # Handle an index line that follows a heading definition. Move it back
1217       # to just before the <h1> or whatever. This preserves the order of
1218       # multiple index lines, not that that matters.
1219
1220       if ($lines[$i-1] =~ /^<\/a><\/h(\d)>/)
1221         {
1222         my($j);
1223         my($found) = 0;
1224         for ($j = $i-2; $j > 0 && $j > $i - 10; $j--)
1225           {
1226           if ($lines[$j] =~ /<h$1>/)
1227             {
1228             $found = 1;
1229             last;
1230             }
1231           }
1232         if ($found)
1233           {
1234           splice(@lines, $j, 0, splice(@lines, $i, 1));
1235           }
1236         }
1237
1238       # Handle an index line that follows an "item". Move it back one line.
1239
1240       elsif ($lines[$i-1] =~ /^<b>.*<\/b>\s*$/)
1241         {
1242         splice(@lines, $i-1, 0, splice(@lines, $i, 1));
1243         }
1244
1245       # Handle an index line that follows a "conf" definition
1246
1247       elsif ($lines[$i-1] =~ /^<i>Type:<\/i>/ && $lines[$i-2] =~ /^<h3>/)
1248         {
1249         splice(@lines, $i-2, 0, splice(@lines, $i, 1));
1250         }
1251
1252       # Handle an index line that follows an "option" definition
1253
1254       elsif ($lines[$i-1] =~ /^<h3>/)
1255         {
1256         splice(@lines, $i-1, 0, splice(@lines, $i, 1));
1257         }
1258       }
1259     }
1260
1261   open(OUT, ">$html/$file") ||
1262     die "Failed to open $html/$file (write)\n";
1263
1264   print OUT "@lines";
1265   close OUT;
1266   undef @lines;
1267   }
1268 }
1269
1270
1271
1272
1273 ##################################################
1274 #               Create Index                     #
1275 ##################################################
1276
1277 sub create_index{
1278 my($hash)   = $_[0];
1279 my($ifname) = $_[1];
1280 my($ititle) = $_[2];
1281 my(%indexindex);
1282
1283 open(INDEX, ">$html/${file_base}_$_[1].html") ||
1284   die "Failed to open $html/${file_base}_$ifname\n";
1285
1286 print INDEX "<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML//EN\">\n";
1287 print INDEX "<html>\n<head>\n<title>$doctitle $ititle</title>\n";
1288 print INDEX "<base target=\"body\">\n</head>\n";
1289
1290 print INDEX "<body bgcolor=\"#FFFFDF\" text=\"#00005A\" " .
1291   "link=\"#FF6600\" alink=\"#FF9933\" vlink=\"#990000\">\n";
1292
1293 print INDEX "<h3>$ititle</h3>\n";
1294
1295 # We have to scan the keys in the hash twice; first to build the list
1296 # of initial letters, and then to do the business. The first time we
1297 # do not need to sort them.
1298
1299 foreach $key (keys %$hash)
1300   {
1301   my($initial) = substr($key,0,1);
1302   $initial = "\U$initial";
1303   $indexindex{$initial} = 1 if $initial ge "A";
1304   }
1305
1306 print INDEX "<p>\n";
1307 foreach $key (sort keys %indexindex)
1308   {
1309   print INDEX "&nbsp;<a href=\"#$key\" target=\"index\">$key</a>\n";
1310   }
1311 print INDEX "<hr></p>\n";
1312
1313 my($letter) = "";
1314 print INDEX "<p>\n";
1315
1316 foreach $key (sort
1317       { ("\L$a" eq "\L$b")? ("$a" cmp "$b") : ("\L$a" cmp "\L$b") }
1318     keys %$hash)
1319   {
1320   my($initial) = substr($key,0,1);
1321   $initial = "\U$initial";
1322   if ($initial ne $letter)
1323     {
1324     if ($initial ge "A")
1325       {
1326       print INDEX "<br>\n" if $letter ne "";
1327       print INDEX "<a name=\"$initial\"></a>\n";
1328       print INDEX "<font size=\"+1\">\U$initial\E</font><br>\n";
1329       }
1330     $letter = $initial;
1331     }
1332   print INDEX "$$hash{$key}<br>\n";
1333   }
1334
1335 print INDEX "</p>\n";
1336
1337 print INDEX "</body>\n</html>\n";
1338 close(INDEX);
1339 }
1340
1341
1342
1343
1344 ##################################################
1345 #           Show usage and die                   #
1346 ##################################################
1347
1348 sub usage {
1349 die "Usage: g2h [-split no|section|chapter] <source> <title>\n";
1350 }
1351
1352
1353
1354 ##################################################
1355 #           Entry point and main program         #
1356 ##################################################
1357
1358
1359 # Directory in which to put the new HTML files
1360
1361 $html = "html";
1362
1363 # Global variables.
1364
1365 %cindex = ();
1366 %oindex = ();
1367
1368 $chapsplit = 0;
1369 $cindex_tocn = 0;
1370 $file_base = "";
1371 $index_count = 0;
1372 $inem = 0;
1373 $inpar = 0;
1374 $lastwasitem = 0;
1375 $lastwasrule = 0;
1376 $oindex_tocn = 0;
1377 $sectsplit = 0;
1378 $source_file = "";
1379 $thischapter = 0;
1380 $thissection = 0;
1381
1382
1383 # Handle options
1384
1385 my($splitset) = 0;
1386
1387 while (scalar @ARGV > 0 && $ARGV[0] =~ /^-/)
1388   {
1389   if ($ARGV[0] eq "-split" && !$splitset)
1390     {
1391     $splitset = 1;
1392     shift @ARGV;
1393     my($type) = shift @ARGV;
1394     if    ($type eq "section") { $sectsplit = 1; }
1395     elsif ($type eq "chapter") { $chapsplit = 1; }
1396     elsif ($type eq "no"     ) { $sectsplit = $chapsplit = 0; }
1397     else                       { &usage(); }
1398     }
1399   else { &usage(); }
1400   }
1401
1402 # Get the source file and its base
1403
1404 &usage() if scalar @ARGV <= 0;
1405 $source_file = shift @ARGV;
1406 ($file_base) = $source_file =~ /^(.*)\.src$/;
1407
1408 &usage() if scalar @ARGV <= 0;
1409 $doctitle = shift @ARGV;
1410
1411 print "\nCreate HTML for $doctitle from $source_file\n";
1412
1413 # Remove the old HTML files
1414
1415 print "Removing old HTML files\n";
1416 system("/bin/rm -rf $html/${file_base}_*.html");
1417
1418 # First pass identifies all the chapters and sections, and collects the
1419 # values of the cross-referencing variables.
1420
1421 print "Scanning for cross-references\n";
1422 &pass_one();
1423
1424 $maxchapter = $thischapter;      # Used if chapter splitting
1425 $maxsection = $thissection;      # Used if section splitting
1426
1427 # Second pass actually creates the HTML files.
1428
1429 print "Creating the HTML files\n";
1430 &pass_two();
1431
1432 # Reprocess for moving some of the index points, if indexes were created
1433
1434 &adjust_index_points() if scalar(keys %cindex) > 0 || scalar(keys %oindex) > 0;
1435
1436 # Finally, we must create the option and concept indexes if any data
1437 # has been collected for them.
1438
1439 if (scalar(keys %cindex) > 0)
1440   {
1441   print "Creating concept index\n";
1442   &create_index(\%cindex, "cindex", "Concepts");
1443   }
1444
1445 if (scalar(keys %oindex) > 0)
1446   {
1447   print "Creating option index\n";
1448   &create_index(\%oindex, "oindex", "Options");
1449   }
1450
1451 # End of g2h