httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From c...@hyperreal.org
Subject cvs commit: apache-devsite/apidoc mkapidict
Date Sun, 03 May 1998 20:00:23 GMT
coar        98/05/03 13:00:23

  Added:       apidoc   mkapidict
  Log:
  	This is the Perl script that turns the api-dict.html template,
  	the api.list definition file, and the dict-*.html entity
  	documentation files into a single monolithic cross-referenced
  	dictionary.
  
  Revision  Changes    Path
  1.1                  apache-devsite/apidoc/mkapidict
  
  Index: mkapidict
  ===================================================================
  #!/usr/local/bin/perl
  #
  # Read from STDIN, produce HTML.  Simple, really.  The first argument on the
  # command line ($ARGV[0]) is the name of the file which provides the
  # framework into which the generated text is inserted.
  #
  # Edit history:
  #
  #  1998-05-03 Ken Coar
  #       Cleaned up a little bit, from horrible to bad, before checking in to
  #       CVS.
  #  1998-04-?? Ken Coar
  #       Prototyped..
  #
  
  if (! $ARGV[0]) {
      print "Template file must be specified.\n";
      die ("missing required input.");
  };
  
  $InFile = $ARGV[0];
  $OutFile = "$ARGV[0].bak";
  
  %Routine = ();
  %Constant = ();
  %Structure = ();
  %Cell = ();
  %Entity = ();
  %SeeAlso = ();
  @Prologue = ();
  @Epilogue = ();
  
  #
  #
  # Just in case the input template was the output from a previous run,
  # save it in case *this* run doesn't work as expected.
  #
  # Now copy the input file to a backup, extracting the prologue and
  # epilogue sections as we go.
  #
  open INFILE, "<$InFile" || dir ("Can't open input file $InFile");
  open OUTFILE, ">$OutFile" || die ("Can't open output file $OutFile");
  $state = 1;
  while ($line = <INFILE>) {
      print OUTFILE $line;
      if ($state == 1) {
  	push (@Prologue, $line);
      } elsif ($state == 2) {
  	push (@Epilogue, $line);
      };
      if ($line =~ m:<!--.*%%BEGIN%%.*-->:) {
  	$state = 0;
      } elsif ($line =~ m:<!--.*%%END%%.*-->:) {
  	push (@Epilogue, $line);
  	$state = 2;
      };
  };
  close INFILE;
  close OUTFILE;
  
  $DataLine = 0;
  
  while (! eof(STDIN)) {
      local (@field) = ("", "", "", "", "", "", "", "");
      local ($rec);
  
      $rec = &get_record(1);
      next if (! $rec);
      chomp($rec);
      @field = split(m:\|:, $rec);
      $rec =~ s:\$\*:$field[1]:g;
      @field = split(m:\|:, $rec);
      if ($field[0] !~ m:^[RSCDX]$:i) {
  	print STDERR "Unrecognised record identifier /$field[0]/ ",
  		     "for record ending on line $DataLine;\n",
  	             "\tmissing continuation character?\n";
  	next;
      };
      if ($Entity{$field[1]}) {
  	print STDERR "Entity $field[1] redefined at line $DataLine.\n";
      };
      $Entity{$field[1]} = 1;
      if ($field[0] =~ /R/i) {
  	$Routine{$field[1]} = $rec;
      } elsif ($field[0] =~ /S/i) {
  	$Structure{$field[1]} = $rec;
      } elsif ($field[0] =~ /C/i) {
  	$Constant{$field[1]} = $rec;
      } elsif ($field[0] =~ /D/i) {
  	$Cell{$field[1]} = $rec;
      } elsif ($field[0] =~ /X/i) {
  	$SeeAlso{$field[1]} = $field[4];
      };
  };
  
  #
  # Done reading in the input.. time to make the doughnuts.
  #
  print @Prologue;
  print <<EOHT;
    <H2>Table of Contents</H2>
    <UL>
     <LI><A HREF="#Routines">Routine Descriptions</A>
     </LI>
     <LI><A HREF="#Structures">Data Structure Definitions</A>
     </LI>
     <LI><A HREF="#Cells">Global Data Cells</A>
     </LI>
     <LI><A HREF="#Constants">Constant Definitions</A>
     </LI>
    </UL>
    <HR>
  EOHT
  
  print <<EOHT;
    <H2>
     <A NAME="Routines">
      Routine Descriptions
     </A>
    </H2>
    <HR>
  EOHT
  &dump_list(%Routine);
  
  print <<EOHT;
    <H2>
     <A NAME="Structures">
      Data Structure Definitions
     </A>
    </H2>
    <HR>
  EOHT
  &dump_list(%Structure);
  
  print <<EOHT;
    <H2>
     <A NAME="Cells">
      Global Data Cells
     </A>
    </H2>
    <HR>
  EOHT
  &dump_list(%Cell);
  
  print <<EOHT;
    <H2>
     <A NAME="Constants">
      Constant Definitions
     </A>
    </H2>
     <P>
     Many of the compile-time choices are determined by the settings of
     various constants created with <CODE>#define</CODE> statements.
     Things like the maximum size of fixed-length buffers, the server
     version string, and operating system-specific code fragment compilation
     are controlled by constants.
     </P>
     <P>
     Some of the Apache Web server's constants (such as
     <A HREF="#SERVER_VERSION"><SAMP>SERVER_VERSION</SAMP></A>)
     can be overridden with
     compile-time definitions on the compiler command line.  Others, like
     <A HREF="#MAX_STRING_LEN"><SAMP>MAX_STRING_LEN</SAMP></A>,
     are provided as conveniences, and shouldn't be modified except under
     special circumstances.  Still others, such as
     <A HREF="#OR_LIMIT"><SAMP>OR_LIMIT</SAMP></A>,
     have specific values that <STRONG>must not</STRONG> be altered.
     </P>
    <HR>
  EOHT
  &dump_list(%Constant);
  print @Epilogue;
  
  #
  # Dump a hash in alphabetical order.
  #
  sub dump_list {
      local (%list) = @_;
      local (@keys) = sort {uc($a) cmp uc($b)} (keys(%list));
  
      foreach $key (@keys) {
  	my ($edited, $iname, $idef, $isamp, $iref, $idesc) =
  	    split(m:\|:, $list{$key});
          print <<EOHT;
    <H3>
     <A NAME="$iname">
      $iname
     </A>
    </H3>
  EOHT
          $edited = &edit_inline($idef, $iname);
  	if (! $edited) {
  	   $edited = "No prototype or definition available.";
  	};
  	print <<EOHT;
     <P>
     Definition:
     </P>
     <DL>
      <DD>
       <PRE>
  $edited
       </PRE>
      </DD>
     </DL>
  EOHT
          $edited = &edit_inline($isamp, $iname);
  	if (! $edited) {
  	   $edited = "No examples available.";
  	};
  	print <<EOHT;
     <P>
     Usage example:
     </P>
     <DL>
      <DD>
       <PRE>
  $edited
       </PRE>
      </DD>
     </DL>
  EOHT
  	if (! $idesc) {
  	    print <<EOHT;
     <P>
     No documentation available.
     </P>
  EOHT
          } elsif (! -r $idesc) {
  	    print <<EOHT;
     <P>
     Documentation file not accessible.
     </P>
  EOHT
          } else {
  	    open DFILE, "<$idesc";
  	    print <DFILE>;
  	    close (DFILE);
          };
          $edited = $iref;
          $edited =~ s/[\s,]//g;
  	if ($edited) {
  	    local ($ref) = $iref;
  	    local ($ref_list) = "    <DD>";
  	    local ($sees) = "";
  
  	    $ref =~ s/\s+//g;
  	    print <<EOHT;
     <DL COMPACT>
      <DT><EM>See also:</EM>
      </DT>
  EOHT
  #
  # Expand any aliased 'see-also' entries.
  #
              foreach (split(m:,:, $ref)) {
  		if ($SeeAlso{$_}) {
  		    $sees .= ",$SeeAlso{$_}";
  		} else {
  		    $sees .= ",$_";
  		};
  	    };
  	    $ref = $sees;
  	    foreach (sort(split(m:,:, $ref))) {
  		local ($item) = "<SAMP>$_</SAMP>";
  	        
  		next if (($_ eq "") || ($_ eq $iname));
  		if ($Entity{$_}) {
  		    $item = "<A HREF=\"#$_\">$item</A>";
  	        } else {
  		    print STDERR "$iname cross-references to undefined ";
  		    print STDERR "entity $_.\n";
  		};
  	        $ref_list .= $item . ",\n        ";
  	    };
  	    $ref_list =~ s:,\n        $:\n:;
  	    print $ref_list;
  	    print <<EOHT;
      </DD>
     </DL>
  EOHT
          };
          print "  <HR>\n";
      };
  };
  
  #
  # Turn any inline references to other structures or constants into links.
  #
  sub edit_inline {
      local ($wip, $rname) = @_;
      local ($ref);
  
      foreach $ref (keys(%Entity)) {
  	if ($ref ne $rname) {
  	    $wip =~ s:\b$ref\b:<A HREF="#$ref">$ref</A>:g;
  	};
      };
      return $wip;
  };
  
  #
  # Read a record from the input stream.  Comments are trimmed, as is
  # trailing whitespace.  Leading whitespace is trimmed IFF the argument to the
  # functional evaluates as true.  A terminal slosh indicates that the next
  # line should be read and the record re-processed.  All '\n' occurrences
  # in the input are converted to newlines before being returned.
  #
  sub get_record {
      local ($trim_leading_ws) = @_;
      local ($trim_next) = 1;
      my ($line);
  
      $line = <STDIN> || return "";
      $DataLine++;
      chomp ($line);
      $line =~ s/#;.*//;
      $line =~ s/\s+$//;
      if ($trim_leading_ws) {
  	$line =~ s/^\s+//;
      };
      if ($line =~ m:\\$:) {
  	$line =~ s:\\n\s+\\$:\\n\\:;
  	$line =~ s:\\$::;
  	$trim_next = 0 if ($line =~ m:\\n$:);
  	$line .= &get_record($trim_next);
      };
      $line =~ s:\\n:\n:g;
      return ($line);
  };
  
  
  

Mime
View raw message