httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pque...@apache.org
Subject svn commit: r821352 [34/34] - /httpd/site/trunk/docs/dev/apidoc/
Date Sat, 03 Oct 2009 16:20:35 GMT
Added: httpd/site/trunk/docs/dev/apidoc/mkapidict
URL: http://svn.apache.org/viewvc/httpd/site/trunk/docs/dev/apidoc/mkapidict?rev=821352&view=auto
==============================================================================
--- httpd/site/trunk/docs/dev/apidoc/mkapidict (added)
+++ httpd/site/trunk/docs/dev/apidoc/mkapidict Sat Oct  3 16:20:11 2009
@@ -0,0 +1,601 @@
+#!/usr/local/bin/perl
+#
+# Build documentation from a definition file, a template, and possibly
+# a bunch of individual description files.
+#
+# -d identifies the definition file (see api.list for documentation).
+#
+# -l specifies a layout type:
+#
+#    0 means full, with each entry in a separate document starting with an
+#      H3 heading and the main document containing a linked subtable of
+#      contents for each type of entry (routines, constants, et cetera);
+#    1 is the same as 0, except everything is in a single monolithic file;
+#    2 means simpler, with no tables of subcontents and each entry jumping
+#      right to the definition without the preamble.
+#
+#    Layout 2 results in reduced file size (though it's still huge), but
+#    is slightly susceptible to potentially confusing display values if
+#    an entry has no definition in the data file.  Layout 1 guarantees
+#    a little more text in such a case, but at a significant cost in file size.
+#    Layout 0 is the best for reference work, but scanning through
+#    definitions is more difficult since they're in separate files.
+#
+# -n indicates that there should be NO hyperlinks in the output.  (Useful
+#    if destined for inclusion in a on-electronic format.)
+#
+# -o specifies the name of the master output file, or "-" for stdout.
+#    Note that "-" is not permitted in combination with "-l 0" because this
+#    name is used in anchors with that layout.
+#
+# -t specifies the template file for the main dictionary page.
+#
+# -v enables verbose mode.
+#
+# -D enable debug messages (if any are implemented).
+#
+# Edit history:
+#
+#  2001-05-04 Ken Coar
+#	Added -n option (no hyperlinks).
+#  2000-09-16 Ken Coar
+#	Reworked to use the APIdict.pm module, to which a lot of the
+#	file reading/writing functionality has been moved.
+#  2000-07-23 Ken Coar
+#	Fix up the handling of '\\' in the formatter.  Also added
+#	messages when description files are missing or not specified.
+#  2000-07-12 Ken Coar
+#	Add some more verbosity, and fix item emission for layout styles > 0.
+#  1999-12-08 Ken Coar
+#       Downcase the HTML tags and do some line merging.
+#  1999-03-31 Ken Coar
+#       Get rid of the ARGV processing and use command-line options
+#       instead.  Add a third level of layout; 0 now means 'full,'
+#       with each definition in its own file.
+#  1998-06-23 Chuck Murcko
+#       Bug fix for ARGV[1] processing of arguments with value 0.
+#  1998-05-26 Ken Coar
+#       Change missing-args message to a 'usage' display, change <B> references
+#       to <STRONG>s, clean up some style issues, and document what Ben's
+#       changes meant and how to use them.
+#  1998-05-25 Ben Laurie
+#       Add capability for alternate, simpler, layout of output.  ARGV[1] is
+#       either 0 for full cross-linked output or 1 for simple.
+#  1998-05-03 Ken Coar
+#       Cleaned up a little bit, from horrible to bad, before checking in to
+#       CVS.
+#  1998-04-?? Ken Coar
+#       Prototyped..
+#
+
+use APIdict;
+
+#
+# Make sure that anything we utter to stderr shows up instanter..
+#
+$tfh = select(STDERR);
+$| = 1;
+select($tfh);
+
+$command_line = join(" ", $0, @ARGV);
+use Getopt::Std;
+
+@errors = ();
+$ofh = \*STDOUT;
+
+getopts("Dd:l:no:t:v", \%arg);
+$Verbose = defined($arg{'v'});
+$Debug = defined($arg{'D'});
+
+if (! defined($arg{'d'})) {
+    push(@errors, "definition file (-d option) is required");
+}
+else {
+    $Dfile = $arg{'d'};
+}
+if ((! defined($arg{'l'})) || ($arg{'l'} < 0) || ($arg{'l'} > 2)) {
+    push(@errors, "layout type (-l option) must be a value 0-2");
+}
+else {
+    $Layout = $arg{'l'};
+    &verbose("Using layout style $Layout");
+}
+
+$nolinks = $arg{'n'};
+&verbose("Hyperlinking is " . ($nolinks ? "OFF" : "ON"));
+
+if ((! defined($arg{'o'})) && ($Layout < 1)) {
+    push(@errors, "output filename (-o option) is required with -l 0");
+}
+elsif (($arg{'o'} eq '-') && ($Layout < 1)) {
+    push(@errors, "output filename (-o options) may not be '-' with -l 0");
+}
+elsif (defined($arg{'o'}) && ($arg{'o'} ne '-')) {
+    open $ofh, ">$arg{'o'}" || die "can't open output file";
+}
+if (! defined($arg{'t'})) {
+    push(@errors, "output template file (-t option) is required");
+}
+else {
+    $InFile = $arg{'t'};
+}
+
+if ($#errors > -1) {
+    foreach (@errors) {
+	print STDERR "$0: $_\n";
+    }
+    &usage();
+    exit(1);
+}
+
+$dict = new APIdict($Dfile);
+$dict->hyperlinks(! $nolinks);
+
+$OutFile = "$InFile.bak";
+
+%URL = ();
+%HREF = ();
+@Prologue = ();
+@Epilogue = ();
+@code_bracket = ("<code>", "</code>");
+@no_bracket = ("", "");
+
+#
+#
+# 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.
+#
+&verbose("Copying input template ($InFile) to backup ($OutFile)");
+open INFILE, "<$InFile" || die ("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;
+
+foreach $item ($dict->entity_list()) {
+    $URL{$item} = &makeURL($item, %URL);
+    $HREF{$item} = &makeHREF($item, %URL);
+}
+
+#
+# Done reading in the input.. time to make the doughnuts.
+#
+&verbose("Dumping prologue.");
+foreach $line (@Prologue) {
+    $line =~ s"(\$Generated by:).*\$"$1 $command_line \$";
+    print $ofh $line;
+}
+$x_routines = $dict->insert_link('Routine Descriptions', "", "",  '#Routines');
+$x_structures = $dict->insert_link('Data Structure Descriptions', "", "",
+                                   '#Structures');
+$x_cells = $dict->insert_link('Data Cell Descriptions', "", "",  '#Cells');
+$x_consts = $dict->insert_link('Constant Descriptions', "", "",  '#Constants');
+print $ofh <<EOHT;
+  <h2>Table of Contents</h2>
+  <ul>
+   <li>$x_routines</li>
+   <li>$x_structures</li>
+   <li>$x_cells</li>
+   <li>$x_consts</li>
+  </ul>
+  <hr>
+EOHT
+
+print $ofh <<EOHT;
+  <h2><a name="Routines">Routine Descriptions</a></h2>
+  <hr>
+EOHT
+
+&verbose("Analysing routines: \\c");
+@keys = $dict->routine_list();
+push(@keys, $dict->macro_list());
+&list_items(@keys);
+&verbose(($#keys + 1) . " found.");
+&verbose("Dumping routines.");
+&dump_list('R', @keys);
+
+print $ofh <<EOHT;
+  <h2><a name="Structures">Data Structure Definitions</a></h2>
+  <hr>
+EOHT
+
+&verbose("Analysing structures: \\c");
+@keys = $dict->structure_list();
+&list_items(@keys);
+&verbose(($#keys + 1) . " found.");
+&verbose("Dumping structures.");
+&dump_list('S', @keys);
+
+print $ofh <<EOHT;
+  <h2><a name="Cells">Global Data Cells</a></h2>
+  <hr>
+EOHT
+
+&verbose("Analysing data cells: \\c");
+@keys = $dict->cell_list();
+&list_items(@keys);
+&verbose(($#keys + 1) . " found.");
+&verbose("Dumping data cells.");
+&dump_list('D', @keys);
+
+$etext = <<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 SERVER_VERSION)
+   can be overridden with
+   compile-time definitions on the compiler command line.  Others, like
+   MAX_STRING_LEN,
+   are provided as conveniences, and shouldn't be modified except under
+   special circumstances.  Still others, such as
+   OR_LIMIT,
+   have specific values that <strong>must not</strong> be altered.
+   </p>
+  <hr>
+EOHT
+
+$etext = $dict->add_links($etext, "", %HREF);
+print $ofh $etext;
+&verbose("Analysing constants: \\c");
+@keys = $dict->constant_list();
+&list_items(@keys);
+&verbose(($#keys + 1) . " found.");
+&verbose("Dumping constants.");
+&dump_list('C', @keys);
+
+&verbose("Dumping epilogue.");
+print $ofh @Epilogue;
+exit(0);
+#
+# Dump a hash in alphabetical order.
+#
+sub dump_list {
+    local($prefix, @keys) = @_;
+    my($i) = 0;
+
+    @keys = sort {uc($a) cmp uc($b)} (@keys);
+    foreach $key (@keys) {
+	local (*dfh);
+	local ($previous, $next) = ("", "");
+
+	$previous = $keys[$i - 1] if ($i > 0);
+	$next = $keys[$i + 1] if ($i < $#keys);
+	if ($Layout == 0) {
+	    open(dfh, ">$URL{$key}");
+	    &dump_item(\*dfh, $prefix, $key, $list{$key}, $previous, $next);
+	    close(dfh);
+	}
+	else {
+	    &dump_item($ofh, $prefix, $key, $list{$key}, $previous, $next);
+	}
+	$i++;
+    }
+}
+
+sub list_items {
+    local(@items) = @_;
+
+    if ($Layout == 0) {
+
+	print $ofh <<EOHT;
+  <ol compact>
+EOHT
+
+        foreach (sort {uc($a) cmp uc($b)} (@items)) {
+	    my ($uri) = $HREF{"$_"};
+
+	    print $ofh "   <li>"
+                . $dict->insert_link($_, @code_bracket, $uri)
+                . "</li>\n";
+        }
+
+	print $ofh <<EOHT;
+  </ol>
+EOHT
+
+    }
+
+    print $ofh <<EOHT;
+  <hr>
+EOHT
+
+    return 0;
+}
+
+#
+# Turn an entry into a URL according to the layout.
+#
+sub makeURL {
+    local ($key, %URL) = @_;
+    my ($prefix, $postfix) = ("", "");
+
+    if ($Layout == 0) {
+	$prefix = "apidoc_";
+	$postfix = ".html";
+    }
+    return "$prefix$key$postfix";
+    
+}
+
+#
+# Turn an entry into a anchor reference according to the layout.
+#
+sub makeHREF {
+    local ($key, %URL) = @_;
+    my ($prefix, $postfix) = ("", "");
+
+    if ($Layout == 0) {
+	$prefix = "apidoc_";
+	$postfix = ".html";
+    }
+    else {
+	$prefix = "#";
+    }
+    return "$prefix$key$postfix";
+    
+}
+
+sub dump_item {
+    my($ofh, $prefix, $key, $record, $previous, $next) = @_;
+    my($rtype) = $dict->category($key);
+    my($iname) = $key;
+    my($idef) = $dict->definition($key);
+    my($isamp) = $dict->example($key);
+    my($iref) = $dict->see_also($key);
+    my($idesc) = $dict->description($key);
+    my($uri) = $URL{$iname};
+    my($href) = $HREF{$iname};
+    my($edited);
+
+    print $ofh <<EOHT if ($Layout == 0);
+<!doctype html public "-//W3C//DTD HTML 4.0 Transitional//EN"
+ "http://www.w3.org/TR/REC-html40/loose.dtd">
+<html>
+ <head>
+  <title>Apache 1.3 API: $iname</title>
+ </head>
+ <body>
+  <h1>Apache 1.3 API Documentation</h1>
+EOHT
+
+    my($p) = $dict->category_name($rtype);
+    if ($Layout == 0) {
+    print $ofh <<EOHT;
+  <h3>$p $iname</h3>
+EOHT
+    }
+    else {
+	print <<EOHT;
+  <h3><a name="$uri">$p $iname</a></h3>
+EOHT
+    }
+    $edited = $dict->add_links($idef, $iname, %HREF);
+    if (! $edited) {
+	$edited = "No prototype or definition available.";
+	&verbose("$0: no definition for $iname");
+    }
+    if ($Layout < 2) {
+	print $ofh <<EOHT;
+   <p>
+   Definition:
+   </p>
+   <dl>
+    <dd>
+     <pre>
+$edited
+     </pre>
+    </dd>
+   </dl>
+EOHT
+        }
+	else {
+	    if ($edited =~ /$iname/) {
+		$edited =~ s/$iname/<b>$iname<\/b>/;
+	    }
+	    else {
+		$edited="<b>$iname:</b> $edited";
+	    }
+	    print $ofh "<a name=\"$uri\"><pre>$edited</pre></a>\n";
+	}
+        $edited = $dict->add_links($isamp, $iname, @code_bracket, %HREF);
+	if ((! $edited) && ($Layout < 2)) {
+	   $edited = "No examples available.";
+	   &verbose("$0: no examples for $iname");
+	}
+	if (($Layout < 2) || $edited) {
+
+	    print $ofh <<EOHT;
+   <p>
+   Usage example:
+   </p>
+   <dl>
+    <dd>
+     <pre>
+$edited
+     </pre>
+    </dd>
+   </dl>
+EOHT
+        }
+
+        $idesc = $dict->description($key);
+	if ($idesc) {
+            $idesc = $dict->add_links($idesc, $key,
+                                      @code_bracket, %HREF);
+	    print $ofh <<EOHT if ($Layout < 2);
+$idesc
+EOHT
+        }
+        elsif (! ($idname = $dict->description_file($key))) {
+	    &verbose("$0: no details listed for $iname");
+	    print $ofh <<EOHT if ($Layout < 2);
+   <p>
+   No documentation available.
+   </p>
+EOHT
+        }
+	elsif (! -r $idname) {
+            &verbose("$0: detail file does not exist: $idname for $iname");
+                print $ofh <<EOHT;
+   <p>
+   Documentation file not accessible.
+   </p>
+EOHT
+        }
+        else {
+            print STDERR "Shouldn't get here!\n";
+        }
+        $edited = $iref;
+        $edited =~ s/[\s,]//g;
+	if ($edited) {
+	    local ($ref) = $iref;
+	    local ($ref_list) = "    <dd>";
+	    local ($sees) = "";
+
+	    $ref =~ s/\s+//g;
+	    print $ofh <<EOHT;
+   <dl compact>
+    <dt><i>See also:</i></dt>
+EOHT
+#
+# Expand any aliased 'see-also' entries.
+#
+            $sees = join(",\n        ", $dict->expanded_seealso($key));
+            $edited = $dict->add_links($sees, $key,
+                                       @code_bracket, %HREF);
+            $edited =~ s:(">)([^<]+)(</a):$1<samp>$2</samp>$3:g;
+#		    print STDERR "$0: undefined cross-reference: "
+#			. "$iname references undefined entity $_.\n";
+	    print $ofh <<EOHT;
+    <dd>$edited
+    </dd>
+   </dl>
+EOHT
+    }
+
+    print $ofh <<EOHT;
+  <hr>
+EOHT
+
+    if ($Layout == 0) {
+	if ($previous) {
+	    $previous = $dict->insert_link($previous, @code_bracket,
+                                           $HREF{$previous});
+	}
+	else {
+	    $previous = "(none)";
+	}
+	if ($next) {
+	    $next = $dict->insert_link($next, @code_bracket, $HREF{$next});
+	}
+	else {
+	    $next = "(none)";
+	}
+
+	print $ofh <<EOHT;
+  <p>
+  Previous: $previous
+  Next: $next
+  </p>
+  <p>
+EOHT
+        print $ofh &link('Table of Contents', $arg{'o'}) . "\n";
+        print $ofh "(" . &link('Routines', "$arg{'o'}#Routines") . ",\n";
+        print $ofh &link('Structures', "$arg{'o'}#Structures") . ",\n";
+        print $ofh &link('Data Cells', "$arg{'o'}#Cells") . ",\n";
+        print $ofh &link('Constants', "$arg{'o'}#Constants") . ")\n";
+	print $ofh <<EOHT;
+  </p>
+ </body>
+</html>
+EOHT
+    }
+}
+
+sub usage {
+    print STDERR "Usage:\n    $0 -l [0|1|2] -t template-file -d api-data "
+	. "-o dict-file\n";
+    exit 1;
+}
+
+sub verbose {
+    my(@lines) = @_;
+    my($suffix);
+
+    if ($Verbose) {
+	foreach (@lines) {
+	    if (m:\\c$:) {
+		$suffix = "";
+	      s:\\c$::;
+	    }
+	    else {
+		$suffix = "\n";
+	    }
+	    print STDERR $_, $suffix;
+	}
+    }
+    return 1;
+}
+
+sub debug {
+    my(@lines) = @_;
+    my($suffix);
+
+    if ($Debug) {
+	foreach (@lines) {
+	    if (m:\\c$:) {
+		$suffix = "";
+	      s:\\c$::;
+	    }
+	    else {
+		$suffix = "\n";
+	    }
+	    print STDERR $_, $suffix;
+	}
+    }
+    return 1;
+}
+
+sub link {
+    my($anchor, $href, $sayso) = @_;
+    my($result);
+
+    if (! $href) {
+        $href = $HREF{$anchor};
+    }
+    if ($nolinks) {
+        $result = "<code>$anchor</code>";
+        &verbose("No link for '$anchor'");
+    }
+    else {
+        $result = "<a href=\"$href\"><code>$anchor</code></a>";
+        &verbose("Hyperlinking '$anchor'")
+             if ($sayso);
+    }
+    return $result;
+}



Mime
View raw message