# This script was implemented by Bob Cunningham.  It will take a plain-text
#   FAQ file as input and generate a set of excerpt files, one for each
#   item in the table of contents.  It will also generate a hypertext
#   version of the full FAQ.
# I've tried to adequately document this script in explanatory comments.
#   When reading these comments, you should bear in mind that they were
#   added several days after debugging of the script was completed.  Also,
#   I wrote a portion of the script several months ago (to generate
#   fast-FAQ excerpts only.)  It's not impossible that I may have erred 
#   in some places in interpreting what the script does.  I hope not, but 
#   be alert.
# Files may be assigned to different directories by changing any of the
#   following four statements.  In any case, the "excerpts" directory
#   must be a subdirectory of the "output_full_faq" directory.
$input_faq_dir_name = "/aue_si~2/potass~1/" ;
$log_dir_name = "/aue_si~2/potass~1/" ;
$output_full_faq_dir_name = "/aue_si~2/potass~1/" ;
$excerpt_dir_name = $output_full_faq_dir_name . "excerpts/" ;
# You can choose file names of your own by changing any of the following
#   four lines.
$input_file_name = "au970929.tst" ;
$fast_faq_toc_output_file_name = "fast_faq_toc.html" ;
$full_faq_2_out_file_name = "full_faq_with_int_links.shtml" ;
#Restrictions: 
#  URLs must be enclosed in angle brackets.
#  One or more URLs may be embedded in a line, but there must be no 
#    "<"s or ">"s on that line that are not enclosing a URL.
#  For a heading to be used for a target from the table of contents,
#    it must be followed by a line containing one or more hyphens and
#    nothing else.
#  The Table of Contents in the input file must be terminated by a line
#    containing one or more equals signs and nothing else.
#  A title line must be preceded by a line containing only white space.
#  In general, the input FAQ file must continue to use the formatting
#    conventions that Mark Israel used.
# Refinements needed:
# Won't handle a line with both a URL and angle brackets not associated 
#   with a URL.  This means, for example, you couldn't have a URL and an 
#   e-mail address on the the same line.
# Maybe Usenet-group names should be converted to hyperlinks.
#   Also e-mail addresses.
#   Then again, maybe not.
# The file "fast_faq_toc.html" is intended to be copied and pasted to
#   replace the table of contents in a previous version of fast-faq.shtml.
#   This will only be applicable if there is a change to the table of
#   contents in Mark Israel's FAQ.  This is not likely to happen unless
#   Mark chooses to make the change.  One exception to this is that I have
#   added a table-of-contents line "[Prefatory Remarks]".
# "groups_and_email_addresses.html" has nothing to do with the normal operation
#   of the script.  It was inserted for an investigative purpose.
$see_newsgroups_and_email_addresses_file_name = "groups_and_email_addresses.html" ;
$qrs = open ( NEWSGROUPS, ">$output_full_faq_dir_name$see_newsgroups_and_email_addresses_file_name" ) ;
if ( not $qrs ) { die "Open file $output_full_faq_dir_name$see_newsgroups_and_email_addresses_file_name failed " ; }
# The following name refers to a version of the FAQ that has external links
#   converted to hyperlinks, but has no internal links.  No need for this file
#   is foreseen at present, but who knows what future users may want?  The lines
#   for generating this file have been left in place, but commented out.
#$full_faq_out_file_name = "mod_full_faq.html" ;
# The utility "gmtime" retrieves elements that can be used to print out dates and times.
($xsec, $xmin, $xhour, $xmday, $xmon, $xyear, $xwday, $xyday, $xisdst ) = gmtime ( time ) ;
@time_list = ($xsec, $xmin, $xhour, $xmday, $xmon, $xyear, $xwday, $xyday, $xisdst ) ;
@time_list = undef ( @time_list ) ; #This and prev. to make Perl quit complaining about unused variables
if ( $xhour < 10 ) { $xhour = "0$xhour" ; }
if ( $xmin  < 10 ) { $xmin  = "0$xmin"  ; }
if ( $xyear > 99 ) 
   { $xyear -= 100 ;
     if ( $xyear < 10 ) { $xyear = "0$xyear" } ;
     $xyear = "20$xyear" ; }
else 
   { if ( $xyear < 10 ) { $xyear = "0$xyear" } ;
     $xyear = "19$xyear" ; 
   }
@wday_list = qw ( Sunday Monday Tuesday Wednesday Thursday Friday Saturday ) ;
$xwkday = $wday_list [ $xwday ] ;
@month_list = qw ( January February March April May June
                   July August September October November December ) ;
$mon_now = $month_list [ $xmon ] ;
# The string $num_list is used in the generation of unique excerpt-file names,
#   which are also used for target labels in the full FAQ output.
$num_list = '0123456789abcdefghijklmnopqrstuvwxyz' ;
open ( OUTFASTFAQTOC, ">$output_full_faq_dir_name$fast_faq_toc_output_file_name" ) ;
$qrs = open ( INFAQFILE, "$input_faq_dir_name$input_file_name" ) ;
if ( not $qrs ) { die "Open input file A ($input_faq_dir_name$input_file_name) failed " ; }
($sec, $min, $hour, $mday, $mon, $year, $wday, $yday, $isdst ) = gmtime ( time ) ;
$secb = $sec ; $minb = $min ;
if ( $min < 10 ) { $min = "0$min" ; }
if ( $sec < 10 ) { $sec = "0$sec" ; }
print "Start time:   $hour:$min:$sec GMT\n" ;
# The contents of the entire input file will be placed in an array, then 
#   the input file will be closed.  The file with the handle NEWSGROUPS will
#   be used to investigate the possibility of making hot links of e-mail addresses and
#   newsgroup names.
$faq_line_count = 0 ;
while ( <INFAQFILE> ) 
  {
    $faq_array[$faq_line_count] = $_ ;
    if ( $faq_array[$faq_line_count] =~ /(\S*(?:\w\w+\.)+\w\w+\S)/ ) 
      { $group_string = $1 ;
        if ( $group_string !~ /\.html|\.com|\.edu|\.org|\.net|http|www\.|\.shtml/ )
          { print NEWSGROUPS "$group_string\n" ; 
          }
      } 
    $faq_2_array[$faq_line_count++] = $_ ;
  }
$num_faq_lines = @faq_array ;
print "File $input_file_name has $num_faq_lines lines.\n" ;
close INFAQFILE ;
$intro_line_count = 0 ;
$faq_line_count = 0 ;
$reading_intro = 0 ;
$toc_line_count = 0 ;
# The beginning of the table of contents is defined by a line in the input file
#   containing only white space and one or more hyphens, preceded by a line
#   containing the string "Table of Contents".  The end of the table of contents
#   is defined by a line containing one or more equal signs starting in column 1.
while ( $faq_line_count <= $num_faq_lines &&
        $faq_array[$faq_line_count] !~ /^\=+$/ )
  { if ( $reading_intro == 0 )
      { if ($faq_array[$faq_line_count+1] =~ /^\s*-+$/ &&
          $faq_array[$faq_line_count] =~ /\s*Table of Contents\s*$/ )
          { print "\nTable of Contents is at line $faq_line_count\n" ;
            $reading_intro = 1 ;
            $toc_array[$toc_line_count++] = "Table of Major Headings\n" ;
            $toc_array[$toc_line_count] = "-----------------------\n" ;
            $intro_start_line = $faq_line_count ;
            $intro_array[0] = $faq_array[$faq_line_count] ;
          }
        ++$faq_line_count ;
      }
# After the beginning of the table of contents has been found, successive lines
#   in the input array will be read into an array called "intro_array".  In the
#   process, each line that begins with a white-space character will have 
#   precatenated to it a link to the item in the text that corresponds to the 
#   table-of-contents line.
# Lines with no leading white space will be put into a table of major headings 
#   in array $toc_array.
    else
      { if ( $faq_array[$faq_line_count] =~ /^[^\s]/ )
          { if ( $toc_line_count > 1 )
              { 
                $toc_one_index = 0 ;
                $toc_two_index = 0 ;
                $name_string = $faq_array[$faq_line_count] ;
                chomp ( $name_string ) ;
                $name_string =~ s/\W//g ;
                if ( length ( $name_string ) < 6 )
                  {
                    $name_string = $name_string . "xxxxxx" ;
                  }
                $toc_a_name = 'tc' . substr ( $name_string, 0, 6 ) ;
# Check to see if the line name is unique.  If not, make it unique.
                while ( exists ($toc_hash{$toc_a_name} ) )
                  { 
                    $toc_a_name = 'tc' . substr ( $name_string, 0, 4 ) .
                                         substr ( $num_list, $toc_one_index, 1 ) .
                                         substr ( $num_list, $toc_two_index++, 1 ) ; 
                    if ( $toc_two_index > 35 ) 
                      { 
                        $toc_two_index = 0 ;
                        ++$toc_one_index ;
                      }
                  } 
                $toc_hash { $toc_a_name } = $toc_a_name ;
                $chomp_faq_array = $faq_array[$faq_line_count] ;
                chomp ( $chomp_faq_array ) ;
# In the Table of Major Headings line, put a link to the corresponding Table of 
#   Contents line.  Put a "name" anchor in the Table of Contents Line.
                $toc_array[$toc_line_count] = '<a href="#' . $toc_a_name . '">' .
                                              $chomp_faq_array . '</a>' . "\n" ;
                $faq_2_array[$faq_line_count] = '<a name="' . $toc_a_name . '">' .
                                                 $chomp_faq_array . "\n" ;
              }
            ++$toc_line_count ; 
          }
        $intro_array[++$intro_line_count] = $faq_array[$faq_line_count++] ; 
      }
  }
if ( $reading_intro == 0 ) 
  { die " Reached end of FAQ file without finding TOC line.\n" ; }
if ( $faq_line_count == $num_faq_lines )
  { die " Reached end of FAQ file without finding '===...=' line.\n" ; }
$num_intro_lines = @intro_array ;
print "There are $num_intro_lines intro lines.\n" ;
$num_toc_lines = @toc_array ;
print "There are $num_toc_lines table-of-contents lines.\n" ;
$nofindlogname = "$log_dir_name" . "no_find_log.txt" ;
$qrs = open ( OUTNOFIND, ">$nofindlogname" ) ;
if ( not $qrs ) { die "Open no-find log file $nofindlogname failed " ; }
#The file "excptlog.txt" was used for troubleshooting.
#$outlogname = "$log_dir_name" . "excptlog.txt" ;
#$qrs = open ( OUTLOGFILE, ">$outlogname" ) ;
#if ( not $qrs ) { die "Open out log file $outlogname failed " ; }
# The file OUTFULLFAQ was a full FAQ with external links but no internal
#   links.  The lines to process that file are left in place but commented
#   out, in case someone wants to use them in the future.
#open ( OUTFULLFAQ, ">$output_full_faq_dir_name$full_faq_out_file_name" ) ;
#print OUTFULLFAQ '<!DOCTYPE html PUBLIC "-//IETF//DTD HTML 2.0//EN">' . "\n" ;
#print OUTFULLFAQ '<html>' . "\n"  ;
#print OUTFULLFAQ '<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
' . "\n"  ;
#print OUTFULLFAQ '<title>' . "\n" ;
#print OUTFULLFAQ 'Almost plain ASCII AUE FAQ (external hyperlinks only)'  . "\n"  ;
#print OUTFULLFAQ '</title>' . "\n"  ;
#print OUTFULLFAQ '</head>' . "\n"  ;
#print OUTFULLFAQ '<body bgcolor="e0ffe0">' . "\n"  ;
#print OUTFULLFAQ '<!-- faqshortname Plain FAQ -->' . "\n"  ;
#print OUTFULLFAQ '<font color="#996600"><small><i>This file is an updated ' . "\n" ;
#print OUTFULLFAQ 'version of the September 1997 edition of Mark Israel\'s AUE FAQ.' . "\n"  ;
#print OUTFULLFAQ "It has Mark's original text intact, except where obsolete URLs have " . "\n"  ;
#print OUTFULLFAQ 'been replaced with &quot;[...]&quot;.  Wherever this has been done,' . "\n"  ;
#print OUTFULLFAQ 'a note has been added, indented and in square brackets, commenting'  . "\n"  ;
#print OUTFULLFAQ 'on the obsolete URL and providing an updated URL if possible. ' . "\n"  ;
#print OUTFULLFAQ 'All URLs containing &quot;http&quot; have been converted to'  . "\n"  ;
#print OUTFULLFAQ 'hyperlinks. <br>' . "\n"  ;
#print OUTFULLFAQ "This file was generated by a Perl script (faqexcpt.pl) $xwkday 
#                  $xmday $mon_now $xyear $xhour:$xmin GMT<br>" . "\n"  ;
#print OUTFULLFAQ '</i></small></font>' . "\n"  ;
#print OUTFULLFAQ '<hr size=1>' . "\n"  ;
#print OUTFULLFAQ '<pre>'  . "\n" ;
# The file OUT2FULLFAQ will contain the output FAQ file with both external and
#   internal links.
$qrs = open ( OUT2FULLFAQ, ">$output_full_faq_dir_name$full_faq_2_out_file_name" ) ;
if ( not $qrs ) { die "Open no-find log file $output_full_faq_dir_name$full_faq_2_out_file_name failed " ; }
# Write to the output FAQ file the HTML header and the part of the body containing
#   introductory and explanatory comments.
print OUT2FULLFAQ '<!DOCTYPE html PUBLIC "-//IETF//DTD HTML 2.0//EN">' . "\n" ;
print OUT2FULLFAQ '<html>' . "\n"  ;
print OUT2FULLFAQ '<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
' . "\n"  ;
print OUT2FULLFAQ '<title>' . "\n" ;
print OUT2FULLFAQ "Mark Israel's AUE FAQ with internal hyperlinks"  . "\n"  ;
print OUT2FULLFAQ '</title>' . "\n"  ;
print OUT2FULLFAQ '</head>' . "\n"  ;
print OUT2FULLFAQ '<body bgcolor="e0ffe0">' . "\n"  ;
print OUT2FULLFAQ '<a name=topoffile></a>' ."\n" ;
print OUT2FULLFAQ '<!-- faqshortname Plain FAQ -->' . "\n"  ;
print OUT2FULLFAQ '<font color="#996600"><small><i>This file is an updated ' . "\n" ;
print OUT2FULLFAQ 'version of the September 1997 edition of Mark Israel\'s AUE FAQ.' . "\n"  ;
print OUT2FULLFAQ "It has Mark's original text intact, except where obsolete URLs have " . "\n"  ;
print OUT2FULLFAQ 'been replaced with &quot;[...]&quot;.  Wherever this has been done,' . "\n"  ;
print OUT2FULLFAQ 'a note has been added, indented and in square brackets, commenting'  . "\n"  ;
print OUT2FULLFAQ 'on the obsolete URL and providing an updated URL if possible.' . "\n"  ;
print OUT2FULLFAQ 'There are also indented and bracketed notes to provide other' . "\n" ;
print OUT2FULLFAQ 'kinds of updates or to point to supplementary information.' . "\n" ;
print OUT2FULLFAQ 'All URLs containing &quot;http&quot; have been converted to'  . "\n"  ;
print OUT2FULLFAQ 'hyperlinks. <br>' . "\n"  ;
print OUT2FULLFAQ "This file was generated by a Perl script (faqexcpt.pl) $xwkday 
                  $xmday $mon_now $xyear $xhour:$xmin GMT<br>" . "\n"  ;
print OUT2FULLFAQ '</i></small></font>' . "\n"  ;
print OUT2FULLFAQ '<hr size=1>' . "\n"  ;
print OUT2FULLFAQ '<pre>'  . "\n" ;
$intro_line_num = 0 ;
# Prepare to use the contents of the current line number as a hyperlink to the
#   corresponding section of the text.  
INTRO_LOOP: while ( $intro_line_num < $num_intro_lines )
  {
# Reject the line if it's all blank, if it contains only hyphens, if it starts
#   with "<", or if it starts with "Last modification".
    if ( $intro_array[$intro_line_num] =~ /^\s*$/ ||
         $intro_array[$intro_line_num] =~ /^-+$/ ||
         $intro_array[$intro_line_num] =~ /^</ ||
         $intro_array[$intro_line_num] =~ /^Last modification/ )
      {
        ++$intro_line_num ;
        next ;
      }
    else
      {
# Accept the line as a candidate hyperlink.  Remove all "["s and "]"s, all white space,
#   and all double quotes, periods, and exclamation marks.  Convert the line to lowercase.
        $search_arg = $intro_array[$intro_line_num] ;
        chomp ( $search_arg ) ;
        $search_arg =~ s/[\[\]]//g ;
        $search_arg =~ s/^\s*// ;
        $search_arg =~ s/[".!]//g ; 
        $search_arg = lc ( $search_arg ) ;
#       print OUTLOGFILE "\$search_arg is $search_arg\n" ;
# If a line in the Table of Contents is not identical to the corresponding
#   heading line, the search argument is adjusted accordingly in one of the
#   following "if" or "elsif" statements.  Where a line in the Table of
#   Contents corresponds to a line that has no associated text, an "elsif"
#   statement causes that line to be ignored.  See for example 'recommended
#   books' below.
        if ( $search_arg eq 'books on mathematical exposition' ) #'book'
          { $search_arg = 'book on mathematical exposition' ; }
        elsif ( $search_arg eq 'recommended books' )
          { ++$intro_line_num ;
            next INTRO_LOOP ; 
          }
        elsif ( $search_arg eq 'table of contents' )
          { ++$intro_line_num ;
            next INTRO_LOOP ; 
          }
        elsif ( $search_arg eq 'welcome to altusageenglish' )
          { $search_arg = '        welcome to altusageenglish' ; }
        elsif ( $search_arg eq 'artificial dialects' )
          { ++$intro_line_num ;
            next INTRO_LOOP ; 
          }
        elsif ( $search_arg eq 'pronunciation' )
          { ++$intro_line_num ;
            next INTRO_LOOP ; 
          }
        elsif ( $search_arg eq 'usage disputes' )
          { ++$intro_line_num ;
            next INTRO_LOOP ; 
          }
        elsif ( $search_arg eq 'punctuation' )
          { ++$intro_line_num ;
            next INTRO_LOOP ; 
          }
        elsif ( $search_arg eq 'word origins' )
          { ++$intro_line_num ;
            next INTRO_LOOP ; 
          }
        elsif ( $search_arg eq 'phrase origins' )
          { ++$intro_line_num ;
            next INTRO_LOOP ; 
          }
        elsif ( $search_arg eq 'words frequently sought' )
          { ++$intro_line_num ;
            next INTRO_LOOP ; 
          }
        elsif ( $search_arg eq 'miscellany' )
          { ++$intro_line_num ;
            next INTRO_LOOP ; 
          }
        elsif ( $search_arg eq 'spelling' )
          { ++$intro_line_num ;
            next INTRO_LOOP ; 
          }
        elsif ( $search_arg eq "foreigners' faqs" )
          { $search_arg = "        foreigners' faqs" ; }
        elsif ( $search_arg eq 'plurals' )
          { ++$intro_line_num ;
            next INTRO_LOOP ; 
          }
        elsif ( $search_arg eq 'plurals of latin and greek words' )
          { $search_arg = 'plurals of latin/greek words' ; }
        elsif ( $search_arg eq 'plurals => english singulars' )
          { $search_arg = 'foreign plurals => english singulars' ; }
        elsif ( $search_arg eq 'shall vs will, would vs should' )
          { $search_arg = 'shall vs will, should vs would' ; }
        elsif ( $search_arg eq 'iso' )
          { $search_arg = 'iso by mark brader' ; }
        elsif ( $search_arg eq 'limerence' )
          { $search_arg = 'limerence/limerent' ; }
        elsif ( $search_arg eq 'suck=be very unsatisfying' )
          { $search_arg = 'suck=be very unsatisfying by john davies' ; }
        elsif ( $search_arg eq 'spitting image/spit and image' )
          { $search_arg = 'spit and image/spitting image' ; }
        elsif ( $search_arg eq 'list of language terms' )
          { $search_arg = 'what is the language term for?' ; }
        elsif ( $search_arg eq 'grass strip between road and sidewalk' )
          { $search_arg = 'what do you call the grass strip between the road and the sidewalk?' ; }
        elsif ( $search_arg eq 'deliberate mistakes in dictionaries' )
          { $search_arg = 'do publishers put false info in dictionaries to catch plagiarists?' ; }
        elsif ( $search_arg eq 'why do we say 30 years old but a 30-year-old man?' )
          { $search_arg = 'why do we say 30 years old, but a 30-year-old man?' ; }
        elsif ( $search_arg eq 'possessive apostrophes' )
          { $search_arg = 'where to put apostrophes in possessive forms' ; }
# The search argument will be compared with each line in the input array that is
#   followed by a line that contains only hyphens, until a match is found.
        $faq_line_num = 0 ;
        while ( $faq_line_num < $num_faq_lines - 1 )
          {
            if ( $faq_array[$faq_line_num+1] !~ /-+$/ )
               { 
                  ++$faq_line_num ;
                  next ;
               }            
            else
              {
# Prepare the current faq-array line to be used as a compare argument.  Remove
#   all "["s, "]"s, "."s, double quotes, and "!"s.  Convert the line to lowercase.
#   If the line contains the string "(notes by<.*>)", where I'm using '<.*>' with
#   a different meaning from what it has in Perl (that is, to stand for any
#   number of characters that are not ")", remove that string.  Remove all white
#   space.
                $compare_arg = $faq_array[$faq_line_num] ;
                chomp ( $compare_arg ) ;
                $compare_arg =~ s/[\[\]]//g ;
                $compare_arg =~ s/[".!]//g ;
                $compare_arg = lc ( $compare_arg ) ;
                $compare_arg =~ s/\(notes by[^\)]*\)// ;
                $compare_arg =~ s/\s*$// ;
                if ( $compare_arg eq $search_arg )
# A hit has been found.  This line in the input array will be the start of
#   Fast-FAQ file, and will also be the target of an anchor in the table of contents.
#   A unique name will be built for the Fast-FAQ file corresponding to the
#   search argument.  It will consist of "fx" followed by the first six letters of 
#   the compare argument unless that string is not unique, in which case it
#   will consist of "fx" followed by the first four letters of the compare
#   argument followed by a unique two-digit number.  The same name will be used for
#   the link from the table of contents to the text.
                  { 
                    $pick_one_index = 0 ;
                    $pick_two_index = 0 ;
                    $name_string = $search_arg ;
                    $name_string =~ s/\W//g ;
                    chomp ( $name_string ) ;
                    if ( length ( $name_string ) < 6 )
                       {
                         $name_string = $name_string . "xxxxxx" ;
                       }
# The name will the "fx" followed by the first six characters of the search argument,
#   unless that name is not unique, in which case the name will consist of "fx"
#   followed by the first four characters of the search argument, followed by a 
#   unique two-digit number.
                    $fx_file_base = 'fx' . 
                                    substr ( $name_string, 0, 6 ) ;
                    $fx_file_name = "$fx_file_base" . '.html' ;
                    while ( exists ($fx_hash{$fx_file_name} ) )
                      { 
                        $fx_file_base = 'fx' . 
                             substr ( $name_string, 0, 4 ) .
                             substr ( $num_list, $pick_one_index, 1 ) .
                             substr ( $num_list, $pick_two_index++, 1 ) ; 
                        $fx_file_name = "$fx_file_base" . '.html' ;
                        if ( $pick_two_index > 35 ) 
                          { 
                            $pick_two_index = 0 ;
                            ++$pick_one_index ;
                          }
                      } 
                    $fx_hash { $fx_file_name } = $search_arg ;
                    $chomp_faq_array = $faq_2_array[$faq_line_num-1] ;
                    chomp ( $chomp_faq_array ) ;
                    $faq_2_array[$faq_line_num-1] =
                         '<a name="' . 
                         "$fx_file_base" .
                         '">' .
                         "$chomp_faq_array" .
                         "</a>" . "\n" ;
                    $url_label = $faq_2_array[$intro_start_line + $intro_line_num] ;
                    $url_label =~ s/^\s*// ;
                    $url_label =~ s/\s*$// ;
# Three items in the table of major headings must be given special treatment because
#   they have text material of their own following them.
                    if ( $fx_file_base eq 'fxprefat' || $fx_file_base eq 'fxwelcom' ||
                         $fx_file_base eq 'fxfore00' )
                      {
                        $white_lead = "" ;
                      }
                    elsif ( $fx_file_base eq 'fxplural' || $fx_file_base eq 'fxforeig' )
                      {
                        $white_lead = "        " ;
                      }
                    else
                      { 
                        $white_lead = "    " ;
                      }
                    $faq_2_array[$intro_start_line + $intro_line_num] =
                         "$white_lead" .
                         '<a href="' .
                         "#$fx_file_base" .
                         '">' .
                         "$url_label" .
                         "</a>" . "\n" ;
# The following lines will convert a line typified by
#   '<a href="#fxprefat"><a name="tcPrefat">[Prefatory remarks]</a>' to
#   '<a name="tcPrefat"><a href="#fxprefat">[Prefatory remarks]</a>'.
# Further below, the '<a name="tcPrefat">' will be moved to the previous line.
                    if ( $fx_file_base eq 'fxprefat' || $fx_file_base eq 'fxwelcom' ||
                         $fx_file_base eq 'fxfore00' )
                      { $faq_string = $faq_2_array[$intro_start_line + $intro_line_num] ;
                        $faq_string =~ s/(^<[^>]+>)(<[^>]+>)([^<]*<\/a>$)/$2$1$3/ ;
                        $faq_2_array[$intro_start_line + $intro_line_num] = $faq_string ;
                      }
# The file OUTLOGFILE was used for information during debugging.
#                   print OUTLOGFILE "  \$compare_arg is at line $faq_line_num in the FAQ.\n" ;
#                   print OUTLOGFILE "  \$fx_file_name is $fx_file_name\n" ;
# Output the header and introductory lines for the current FAQ-excerpt file.
                    open ( OUTEXCERPT, ">$excerpt_dir_name$fx_file_name" ) ;
                    print OUTEXCERPT '<!DOCTYPE html PUBLIC "-//IETF//DTD HTML 2.0//EN">' . "\n" ;
                    print OUTEXCERPT '<html>' . "\n"  ;
                    print OUTEXCERPT '<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
' . "\n"  ;
                    print OUTEXCERPT '<title>' . "\n" ;
                    print OUTEXCERPT 'AUE FAQ excerpt: ' . $faq_array[$faq_line_num] . "\n"  ;
                    print OUTEXCERPT '</title>' . "\n"  ;
                    print OUTEXCERPT '</head>' . "\n"  ;
                    print OUTEXCERPT '<body bgcolor="e0ffe0">' . "\n"  ;
                    print OUTEXCERPT '<!-- faqshortname FX -->' . "\n"  ;
                    print OUTEXCERPT '<font color="#996600"><small><i>This file is an excerpt ' . "\n" ;
                    print OUTEXCERPT "from the September 1997 version of Mark Israel\'s AUE FAQ.<br>" . "\n"  ;
                    print OUTEXCERPT "The file was re-generated $xwkday 
                        $xmday $mon_now $xyear $xhour:$xmin GMT with URLs updated where 
                        necessary and if possible.<br>" . "\n"  ;
                    print OUTEXCERPT 'To see the full AUE FAQ, click <a href="/">here</a>.' . "\n"  ;
                    print OUTEXCERPT '</i></small></font>' . "\n"  ;
                    print OUTEXCERPT '<hr size=1>' . "\n"  ;
                    print OUTEXCERPT '<pre>'  . "\n" ;
                    $start_body_line_num = $faq_line_num ;
                    $body_line_num = $faq_line_num + 2 ;
# Find the last line of the text of the current FAQ excerpt file.  This will be the
#   third line preceding any line containing one or more hyphens starting in column one, 
#   followed by end-of-line.
                    $test_string = $faq_array[$body_line_num] ;
                    $test_string =~ s/^\s*// ;
                    while ( $test_string !~ /^\-+$/ )
                      {
                        $test_string = $faq_array[$body_line_num++] ;
                        $test_string =~ s/^\s*// ;
                      }
                    $end_body_line_num = $body_line_num - 3 ;
                    $body_line_num = $start_body_line_num ;
# Output the text of the current Fast-FAQ file.
                    while ( $body_line_num < $end_body_line_num )
                      {
                        $full_html = $faq_array[$body_line_num] ;
                        $h_index = index ( $full_html, "http://", 0 ) ;
                        $last_h = 0 ;
# If a line containing "http://" is found, convert it to a hyperlink.
                        while ( $h_index >= 0 )
# Different treatment is needed depending upon whether the URL is at the 
#   beginning of the line or within the line.  Also depending upon whether the
#   URL is already enclosed in angle brackets.               
                           { if ( $h_index > 0 )
# URL is within the line.
                              { if ( substr ( $full_html, $h_index - 1, 1 ) eq "<" )
                                  { $g_index = index ( $full_html, ">", $h_index ) ;
                                    $url = substr ( $full_html, $h_index, $g_index - $h_index ) ;
                                    $front_part = substr ( $full_html, 0, $h_index - 1 ) ;
                                    $mid_part = '<a href="' . $url . '">&lt;' . $url . "&gt;</a>" ;
                                    $back_part = substr ( $full_html, $g_index + 1 ) ;
                                    $full_html = $front_part . $mid_part . $back_part ;
                                  }
                                else
                                  { $front_part = substr ( $full_html, 0, $h_index - 1 ) ; 
                                    $lenurl = length ( $full_html ) - length ( $front_part ) ;
                                    $url = substr ( $full_html, $h_index, $lenurl ) ;
                                    $back_part = '<a href="' . $url . '">' . $url . "</a>" ;
                                    $full_html = $front_part . $back_part ;
                                  }
                              }
                             else
# URL is at the beginning of the line.
                              { $full_html = '<a href="_-_full_html-_.html">' . $full_html . '</a>' ;
                              }
                             $last_h = $h_index + 2 * length ( $url ) + 18 ;
                             $h_index = index ( $full_html, "http://", $last_h ) ;
                          }
                        $faq_array[$body_line_num] = $full_html ;
                        $faq_2_array[$body_line_num] = $full_html ;
# If the current line does not contain a URL, all "<"s and ">"s will be converted
#   to escape sequences.  This works okay with the present FAQ contents, but there's
#   no reason why a line with a URL shouldn't also have angle brackets for other 
#   reasons, so this should be refined.
                        if ( $faq_array[$body_line_num] !~ /http:\/\// )
                          {
                            $faq_array[$body_line_num] =~ s/</&lt;/g ;
                            $faq_array[$body_line_num] =~ s/>/&gt;/g ;
                            $faq_2_array[$body_line_num] =~ s/</&lt;/g ;
                            $faq_2_array[$body_line_num] =~ s/>/&gt;/g ;
                          }
                        if ( $faq_array[$body_line_num] !~ /^=+$/ )
                          {
# The "Addlink" feature was incorporated and was at first used, but I see no
#   occurrence ot "Addlink" in the file au970929.mod, so I must have decided I
#   no longer needed it.
                            if ( $faq_array[$body_line_num] =~  /\[([^`]*)`\s*Addlink:\s*([^`]*)`([^]]*)]/ )
                              { 
                                $faq_array[$body_line_num] = "<font color=#996600><i>       \[$1$2$3]</i></font>/" . "\n" ;
                                $faq_array[$body_line_num] =~ s/&lt;/</g ;
                                $faq_array[$body_line_num] =~ s/&gt;/>/g ;
                                $faq_array[$body_line_num] =~ s/href=\"/href=\"..\//
                              }
# When the script encounters "`setital`", it changes the font to italics and a
# different color until a "`/setital`" is found.  There are three possibilities:
# 1. There is a "`setital`" with no "`/setital`" on the same line.  Italicization
#    will be initiated: 
                            elsif ( $faq_array[$body_line_num] =~ /`setital`/ &&
                                      $faq_array[$body_line_num] !~ /`\/setital`/ )
                                { $faq_array[$body_line_num] =~ s/(^\s*)`setital`(.*)/$1$2/ ;
                                  $faq_array[$body_line_num] = "<font color=#996600><i>" . "$faq_array[$body_line_num]" ;
                                }
# 2. There are a "`setital`" and a "`/setital`" on the same line.  Only this
#    line will be italicized:
                            elsif ( $faq_array[$body_line_num] =~ /`setital`/ &&
                                    $faq_array[$body_line_num] =~ /`\/setital`/ )
                              { chomp ( $faq_array[$body_line_num] ) ;
                                $faq_array[$body_line_num] =~ s/(^\s*)`setital`(.*)/$1$2/ ;
                                $faq_array[$body_line_num] =~ s/(.*)`\/setital`/$1/ ;
                                $faq_array[$body_line_num] = "<font color=#996600><i>" . "$faq_array[$body_line_num]" . "</i></font>\n" ;
                              }
# 3. There is a "`/setital`" with no "`setital`" on the same line.  Italicization
#    will be stopped after this line is italicized:
                            elsif ( $faq_array[$body_line_num] =~ /`\/setital`/ )
                              { chomp ( $faq_array[$body_line_num] ) ;
                                $faq_array[$body_line_num] =~ s/([^`]*)`\/setital`/$1/ ;
                                $faq_array[$body_line_num] = "$faq_array[$body_line_num]" . "</i></font>\n" ;
                              }
# A URL within an italicized region is formatted as typified by the following:
# `setital`[Click `a href="deja_comments.html"`here` for additional comments about deja.com.]`/setital`
# The following lines convert this to the following:
# <font color=#996600><i>     [Click <a href="deja_comments.html">here</a> for additional comments about deja.com.]</i></font>
                            if ( $faq_array[$body_line_num] =~ /(^[^`]*)`a href="([^`]*)`([^`]*)`(.*)/ )
                              { $faq_array[$body_line_num] = "$1<a href=". '"' . "\.\.\/$2>$3<\/a>$4\n" ; }
# The following line writes each line, modified or not, to the excerpt file.
                            print OUTEXCERPT $faq_array[$body_line_num++] ;
                          }
                        else
                          {
                            ++$body_line_num ;
                          }
                      }
# Write the ending lines to the excerpt file and close the file.
                    print OUTEXCERPT '</pre>' ;
                    print OUTEXCERPT '</body>' ;
                    print OUTEXCERPT '</html>' ;
                    close OUTEXCERPT ;
#
                    $hot_string = $intro_array[$intro_line_num] ;
                    chomp ( $hot_string ) ;
# The following lines will insert a link to the excerpt file between any
# leading white-space characters and the beginning of the non-white-space.
# If there are no leading white-space characters, the link will be inserted
# at the beginning of the line.
# I now observe that the following "if" will always be satisfied, since any
# line will have at its beginning zero or more white-space characters followed
# by one character that is not a white-space character.  This is harmless.
                    if ( $hot_string =~ /(^\s*)\S/ )
                      {
                        $leading_white = $1 ;
                        $hot_string =~ s/^\s*// ;
                      }
                    $intro_array[$intro_line_num] = 
                         $leading_white . "\<a href=\"\.\/excerpts\/$fx_file_name\"\>" .
                         $hot_string . "\<\/a\>\n" ;
# Note that from this point on, the array $intro_array will be used only to write
#   the Fast-FAQ table of contents file.
                    ++$intro_line_num ;
                    next INTRO_LOOP ;
                  }
                else
# compare_arg did not equal search_arg:
                  {
                     {
                        ++$faq_line_num ;
                     }
                  }
              }
          }
          ++$intro_line_num ;
          if ( $faq_line_num ge $num_faq_lines )
            {
              print OUTNOFIND "'$search_arg' not found.\n" ;
            }
      }
  }
# Write the table of major headings to the output full-FAQ file:
$toc_line_num = 0 ;
while ( $toc_line_num < $num_toc_lines )
  { print OUT2FULLFAQ $toc_array[$toc_line_num++] ;
  }
print OUT2FULLFAQ "\n" ;
# Before the output FAQ array is written to the full-FAQ file, a variety 
#   of processing steps must be carried out:
$faq_line_num = 0 ;
$new_entry_flag = 0 ;
$start_line_num = 0 ;
while ( $faq_line_num < $num_faq_lines )
  { 
#    print OUTFULLFAQ $faq_array[$faq_line_num] ;
# If a line does not contain a URL or a "a=name" anchor, replace all "<"s
#   and ">"s with escape sequences.
    if ( $faq_2_array[$faq_line_num] !~ /http:\/\//g &&
         $faq_2_array[$faq_line_num] !~ /a href=/g &&
         $faq_2_array[$faq_line_num] !~ /a name=/g )
      {
        $faq_2_array[$faq_line_num] =~ s/</&lt;/g ;
        $faq_2_array[$faq_line_num] =~ s/>/&gt;/g ;
      }
# As explained earlier, I have apparently decided at some point not to use
#   the "Addlink" feature any longer.
    if ( $faq_2_array[$faq_line_num] =~  /\[([^`]*)`\s*Addlink:\s*([^`]*)`([^]]*)]/ )
      { 
        $faq_2_array[$faq_line_num] = "<font color=#cc9900><i>       \[$1$2$3]</i></font>" . "\n" ;
        $faq_2_array[$faq_line_num] =~ s/&lt;/</g ;
        $faq_2_array[$faq_line_num] =~ s/&gt;/>/g ;
       }
# Lines contains "`setital" and "`/setital`" were previously processed for the
#   excerpt files.  They will now be processed in the same way for the output
#   full-FAQ file:
# There are three possibilities with respect to "`setital`" and "`/setital`":
# 1. The line contains "`setital`" and not "`/setital`".  Italicization
#    will be initiated:
    elsif ( $faq_2_array[$faq_line_num] =~ /`setital`/ &&
            $faq_2_array[$faq_line_num] !~ /`\/setital`/ )
      { $faq_2_array[$faq_line_num] =~ s/(^\s*)`setital`(.*)/$1$2/ ;
        $faq_2_array[$faq_line_num] = "<font color=#996600><i>" . "$faq_2_array[$faq_line_num]" ;
      }
# 2. The line contains both "`setital`" and "`/setital`".  Only this line
#    will be italicized:
    elsif ( $faq_2_array[$faq_line_num] =~ /`setital`/ &&
            $faq_2_array[$faq_line_num] =~ /`\/setital`/ )
      { chomp ( $faq_2_array[$faq_line_num] ) ;
        $faq_2_array[$faq_line_num] =~ s/(^\s*)`setital`(.*)/$1$2/ ;
        $faq_2_array[$faq_line_num] =~ s/(.*)`\/setital`/$1/ ;
        $faq_2_array[$faq_line_num] = "<font color=#996600><i>" . "$faq_2_array[$faq_line_num]" . "</i></font>\n" ;
      }
# 3. The line contains "`/setital" and not "`setital`".  Italicization
#    will be stopped after this line is italicized:
    elsif ( $faq_2_array[$faq_line_num] =~ /`\/setital`/ )
      { chomp ( $faq_2_array[$faq_line_num] ) ;
        $faq_2_array[$faq_line_num] =~ s/([^`]*)`\/setital`/$1/ ;
        $faq_2_array[$faq_line_num] = "$faq_2_array[$faq_line_num]" . "</i></font>\n" ;
      }
# A URL within an italicized region is formatted as typified by the following:
#   `setital`[Click `a href="deja_comments.html"`here` for additional comments about deja.com.]`/setital`
#   The following lines convert this to the following:
#   <font color=#996600><i>     [Click <a href="deja_comments.html">here</a> for additional comments about deja.com.]</i></font>
    if ( $faq_2_array[$faq_line_num] =~ /(^[^`]*)`(a href=[^`]*)`([^`]*)`(.*)/ )
      { $faq_2_array[$faq_line_num] = "$1<$2>$3<\/a>$4\n" ; }
# The following lines convert the section "New entries this year" to
#   hyperlinks:
    if ( $faq_2_array[$faq_line_num] =~ /^New entries this year/ )
      { $new_entry_flag = 1 ; }
    elsif ( $new_entry_flag == 1 && 
            $faq_2_array[$faq_line_num] =~ /^<a name=\"fxprefat\"><\/a>/ )
      { $new_entry_flag = 0 ; }
    if ( $new_entry_flag == 1 )
      { 
        $search_string = $faq_2_array[$faq_line_num] ;
        chomp ( $search_string ) ;
        $search_string =~ s/\s*$// ;
        $search_string =~ s/^\s+(\S.*$)/$1/ ;
        if ( $start_line_num == 0 )
          { 
            $search_line_num = $faq_line_num + 1 ;
            while ( ! ($faq_2_array[$search_line_num] =~ /^Table of Contents\s*$/ &&
                    $faq_2_array[$search_line_num+1] =~ /^-+\s*$/ ) )
                    { ++$search_line_num ;
                    }
            $start_line_num = $search_line_num ;
          }
        else
          { 
            $search_line_num = $start_line_num ;
            $hit = 0 ;
            while ( $faq_2_array[$search_line_num] !~ /^<a name=\"fxprefat\"><\/a>/ &&
                    $search_line_num < $num_faq_lines && $hit == 0 )
              { $try_string = $faq_2_array[$search_line_num] ;
                chomp ( $try_string ) ;
                $try_string =~ s/\s*$// ;
                $try_string =~ s/^\s+(\S.*$)/$1/ ;
                $try_string =~ s/^<[^>]*>([^<]*).*$/$1/ ;
                if ( $try_string eq $search_string )
                  { $faq_2_array[$faq_line_num] = $faq_2_array[$search_line_num] ;
                    $hit = 1 ;
                  }
                else
                  { ++$search_line_num ;
                  }
              }
          }
      }
# Because Netscape 6 doesn't work the same as other browsers when the "a name="
#   tag is on the same line as the intended destination, the following
#   line will move it to the previous line:
    if ( $faq_2_array[$faq_line_num+1] =~ /^(<a name=[^>]+>)(<a href=[^>]+>)(.*$)/ )
      { $name_string = $1 ;
        $href_string = $2 ;
        $tail_string = $3 ;
        $faq_2_array[$faq_line_num] = $name_string . $faq_2_array[$faq_line_num] ;
        $faq_2_array[$faq_line_num+1] = $href_string . $tail_string . "\n" ;
      }
# Write the current line to the output full-FAQ file:
    print OUT2FULLFAQ $faq_2_array[$faq_line_num++] ;
  }
# Write the ending statements to the output full-FAQ file: 
#print OUTFULLFAQ '</pre>'  . "\n" ;
#print OUTFULLFAQ '</body>'  . "\n" ;
#print OUTFULLFAQ '</html>'  . "\n" ;
print OUT2FULLFAQ '</pre>'  . "\n" ;
print OUT2FULLFAQ '</body>'  . "\n" ;
print OUT2FULLFAQ '</html>'  . "\n" ;
# Write the fast-FAQ table of contents to a file.  As mentioned above, this
#   file is intended to be copied and pasted to previous versions of
#   Fast-FAQ.html and Intro_F.html. 
print OUTFASTFAQTOC "<pre>\n" ;
for ( $idx = 0 ; $idx < $num_intro_lines ; $idx++ )
  {
    print OUTFASTFAQTOC $intro_array[$idx] ;
  }
print OUTFASTFAQTOC "</pre>\n" ;
# Use "gmtime" to load date-time variables in preparation for reporting the ending and
#   elapsed times.
($sece, $mine, $houre, $mday, $mon, $year, $wday, $yday, $isdst ) = gmtime ( time ) ;
if ( $sece < 10 )
  { $sece = "0$sece" ; }
if ( $mine < 10 ) 
  { $mine = "0$mine" ; } 
print "End time:     $houre:$mine:$sece GMT\n" ;
if ( $sece < $secb ) 
  { $sece += 60 ;
    $mine -= 1 ; }
if ( $mine < $minb )
  { $mine += 60 ; 
    $houre -= 1 ; }
if ( $houre < $hour )
  { $houre += 24 ; }
$secd = $sece - $secb ;
$mind = $mine -	$minb ;
$hourd = $houre - $hour ;
if ( $secd < 10 ) { $secd = "0$secd" ; }
if ( $mind < 10 ) { $mind = "0$mind" ; }
print "Elapsed time: $hourd:$mind:$secd\n" ;