You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@httpd.apache.org by co...@apache.org on 2001/05/16 13:23:35 UTC
cvs commit: httpd-docs-1.3/apidoc/tools mkapidict
coar 01/05/16 04:23:34
Modified: apidoc APIdict.pm README api.list
apidoc/tools mkapidict
Removed: apidoc findapi mkapidict todo.pl
Log:
Add some definitions to the list, move the tools into a
subdirectory, and add a way of saying 'no hyperlinks'
(needed to generate output suitable for inclusion in a
non-hyper medium).
Revision Changes Path
1.3 +37 -2 httpd-docs-1.3/apidoc/APIdict.pm
Index: APIdict.pm
===================================================================
RCS file: /home/cvs/httpd-docs-1.3/apidoc/APIdict.pm,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -u -r1.2 -r1.3
--- APIdict.pm 2000/09/27 02:11:52 1.2
+++ APIdict.pm 2001/05/16 11:23:23 1.3
@@ -5,6 +5,9 @@
#
# Edit history:
#
+# 2001-05-04 Ken Coar
+# Add 'hyperlink' Boolean setting.
+#
# 2000-09-15 Ken Coar
# Pull the relevant parts out of the mkapidict script so that
# other tools can use them (like a source scanner).
@@ -18,6 +21,8 @@
# Public methods
#
+$hyperlinks = 1;
+
#
# Package constructor
#
@@ -33,11 +38,31 @@
# All other public methods appear in lexical order.
#
+sub insert_link {
+ my($self, $a_text, $prefix, $postfix, $a_target) = @_;
+ my($ref);
+
+ #
+ # This is an incredibly brute-force O(n^2) algorithm, but at least it's
+ # clear and only run when updating the docco.
+ #
+ if (! $a_target) {
+ $a_target = $a_text;
+ }
+ if ($hyperlinks) {
+ $ref = "<a href=\"$a_target\">$prefix$a_text$postfix</a>";
+ }
+ else {
+ $ref = "$prefix$a_text$postfix";
+ }
+ return $ref;
+}
+
#
# Turn any inline references to other entities into links.
#
sub add_links {
- my($self, $wip, $rname, %HREF) = @_;
+ my($self, $wip, $rname, $a_prefix, $a_postfix, %HREF) = @_;
my($ref);
#
@@ -47,7 +72,8 @@
foreach $ref (keys(%Entity)) {
my($href) = $HREF{"$ref"};
if ($ref ne $rname) {
- $wip =~ s:([^-</]*)\b$ref\b:$1<a href="$href">$ref</a>:g;
+ $nref = &insert_link($ref, $prefix, $postfix, $href);
+ $wip =~ s:([^-</]*)\b$ref\b:$1$nref:g;
}
}
return $wip;
@@ -204,6 +230,15 @@
delete($items{"$item"});
@result = sort {uc($a) cmp uc($b)} (keys(%items));
return @result;
+}
+
+#
+# Enable/disable the use of hyperlinks in add_links.
+#
+sub hyperlinks {
+ my($self, $setting) = @_;
+
+ return ($hyperlinks = $setting);
}
#
1.4 +13 -3 httpd-docs-1.3/apidoc/README
Index: README
===================================================================
RCS file: /home/cvs/httpd-docs-1.3/apidoc/README,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -u -r1.3 -r1.4
--- README 2001/02/06 16:26:07 1.3
+++ README 2001/05/16 11:23:24 1.4
@@ -1,6 +1,6 @@
This directory (apidoc) is the development area for an effort to document
the Apache Web server API (Application Programing Interface). In its
-current incarnation, there are four types of files here:
+current incarnation, there are five types of files here:
. a data file (api.list) that contains a record for each API entity; this
file is internally documented as to format
@@ -8,8 +8,16 @@
assembled documentation
. HTML fragment files (e.g., dict-ap_destroy_pool.html), one per API
entity, that contain the actual documentation for the entities
- . a Perl script (mkapidict) which puts all of these together to generate
+ . a set of assembled documentation HTML files, output from mkapidict
+ . the APIdict.pm Perl module used by the scripts in the ./tools/ directory
+
+There is also a ./tools/ subdirectory which contains the scripts used
+to assemble and deal with the HTML files. It includes
+
+ . mkapidict, a Perl script which puts all of these together to generate
the actual HTML documentation
+ . todo.pl, which examines the API dictionary and reports on the
+ items which are incomplete (use the output to manually update TODO)
There are currently four types of API entities defined: routines,
constants, structures, and global data cells.
@@ -20,10 +28,12 @@
-l0 Put each entity into its own HTML file
-l1 Build a single complete monolithic file
-l2 Same as layout 1, only streamlined (but still huge)
+ -l3 Same as layout 2, but with no links
Layout 0 should be used for generating the online Web-accessed
documentation; layouts 1 and 2 are good for producing something
-suitable for printing.
+suitable for printing. Layout 3 is good for making something
+that can be included in an offline document.
Entity references in specifications and examples (but not descriptions)
are automatically linked to the appropriate definitions (e.g., the
1.37 +69 -18 httpd-docs-1.3/apidoc/api.list
Index: api.list
===================================================================
RCS file: /home/cvs/httpd-docs-1.3/apidoc/api.list,v
retrieving revision 1.36
retrieving revision 1.37
diff -u -u -r1.36 -r1.37
--- api.list 2001/02/06 16:26:07 1.36
+++ api.list 2001/05/16 11:23:24 1.37
@@ -3512,28 +3512,79 @@
|SA-dirstat\
|<dict-$*.html
#;
-#; HTTP status code declarations.
+#; HTTP status code declarations. Largely cadged from httpd.h.
#;
X|SA-httpcodes\
|ap_status_drops_connection,ap_is_HTTP_INFO,ap_is_HTTP_SUCCESS\
,ap_is_HTTP_REDIRECT,ap_is_HTTP_ERROR,ap_is_HTTP_CLIENT_ERROR\
- ,ap_is_HTTP_SERVER_ERROR,HTTP_CONTINUE,HTTP_SWITCHING_PROTOCOLS\
- ,HTTP_OK,HTTP_CREATED,HTTP_ACCEPTED,HTTP_NON_AUTHORITATIVE\
- ,HTTP_NO_CONTENT,HTTP_RESET_CONTENT,HTTP_PARTIAL_CONTENT\
- ,HTTP_MULTIPLE_CHOICES,HTTP_MOVED_PERMANENTLY,HTTP_MOVED_TEMPORARILY\
- ,HTTP_SEE_OTHER,HTTP_NOT_MODIFIED,HTTP_USE_PROXY,HTTP_BAD_REQUEST\
- ,HTTP_UNAUTHORIZED,HTTP_PAYMENT_REQUIRED,HTTP_FORBIDDEN,HTTP_NOT_FOUND\
- ,HTTP_METHOD_NOT_ALLOWED,HTTP_NOT_ACCEPTABLE\
- ,HTTP_PROXY_AUTHENTICATION_REQUIRED,HTTP_REQUEST_TIME_OUT,HTTP_CONFLICT\
- ,HTTP_GONE,HTTP_LENGTH_REQUIRED,HTTP_PRECONDITION_FAILED\
- ,HTTP_REQUEST_ENTITY_TOO_LARGE,HTTP_REQUEST_URI_TOO_LARGE\
- ,HTTP_UNSUPPORTED_MEDIA_TYPE,HTTP_INTERNAL_SERVER_ERROR\
- ,HTTP_NOT_IMPLEMENTED,HTTP_BAD_GATEWAY,HTTP_SERVICE_UNAVAILABLE\
- ,HTTP_GATEWAY_TIME_OUT,HTTP_VERSION_NOT_SUPPORTED\
- ,HTTP_VARIANT_ALSO_VARIES,HTTP_PROCESSING,HTTP_RANGE_NOT_SATISFIABLE\
- ,HTTP_EXPECTATION_FAILED,HTTP_UNPROCESSABLE_ENTITY,HTTP_LOCKED\
- ,HTTP_FAILED_DEPENDENCY,HTTP_INSUFFICIENT_STORAGE,HTTP_NOT_EXTENDED\
+ ,ap_is_HTTP_SERVER_ERROR\
,HTTP_VERSION,HTTP_VERSION_MAJOR,HTTP_VERSION_MINOR\
+ ,HTTP_CONTINUE\
+ ,HTTP_SWITCHING_PROTOCOLS\
+ ,HTTP_PROCESSING\
+ ,HTTP_OK\
+ ,HTTP_CREATED\
+ ,HTTP_ACCEPTED\
+ ,HTTP_NON_AUTHORITATIVE\
+ ,HTTP_NO_CONTENT\
+ ,HTTP_RESET_CONTENT\
+ ,HTTP_PARTIAL_CONTENT\
+ ,HTTP_MULTI_STATUS\
+ ,HTTP_MULTIPLE_CHOICES\
+ ,HTTP_MOVED_PERMANENTLY\
+ ,HTTP_MOVED_TEMPORARILY\
+ ,HTTP_SEE_OTHER\
+ ,HTTP_NOT_MODIFIED\
+ ,HTTP_USE_PROXY\
+ ,HTTP_TEMPORARY_REDIRECT\
+ ,HTTP_BAD_REQUEST\
+ ,HTTP_UNAUTHORIZED\
+ ,HTTP_PAYMENT_REQUIRED\
+ ,HTTP_FORBIDDEN\
+ ,HTTP_NOT_FOUND\
+ ,HTTP_METHOD_NOT_ALLOWED\
+ ,HTTP_NOT_ACCEPTABLE\
+ ,HTTP_PROXY_AUTHENTICATION_REQUIRED\
+ ,HTTP_REQUEST_TIME_OUT\
+ ,HTTP_CONFLICT\
+ ,HTTP_GONE\
+ ,HTTP_LENGTH_REQUIRED\
+ ,HTTP_PRECONDITION_FAILED\
+ ,HTTP_REQUEST_ENTITY_TOO_LARGE\
+ ,HTTP_REQUEST_URI_TOO_LARGE\
+ ,HTTP_UNSUPPORTED_MEDIA_TYPE\
+ ,HTTP_RANGE_NOT_SATISFIABLE\
+ ,HTTP_EXPECTATION_FAILED\
+ ,HTTP_UNPROCESSABLE_ENTITY\
+ ,HTTP_LOCKED\
+ ,HTTP_FAILED_DEPENDENCY\
+ ,HTTP_INTERNAL_SERVER_ERROR\
+ ,HTTP_NOT_IMPLEMENTED\
+ ,HTTP_BAD_GATEWAY\
+ ,HTTP_SERVICE_UNAVAILABLE\
+ ,HTTP_GATEWAY_TIME_OUT\
+ ,HTTP_VERSION_NOT_SUPPORTED\
+ ,HTTP_VARIANT_ALSO_VARIES\
+ ,HTTP_INSUFFICIENT_STORAGE\
+ ,HTTP_NOT_EXTENDED\
+ ,DOCUMENT_FOLLOWS\
+ ,PARTIAL_CONTENT\
+ ,MULTIPLE_CHOICES\
+ ,MOVED\
+ ,REDIRECT\
+ ,USE_LOCAL_COPY\
+ ,BAD_REQUEST\
+ ,AUTH_REQUIRED\
+ ,FORBIDDEN\
+ ,NOT_FOUND\
+ ,METHOD_NOT_ALLOWED\
+ ,NOT_ACCEPTABLE\
+ ,LENGTH_REQUIRED\
+ ,PRECONDITION_FAILED\
+ ,SERVER_ERROR\
+ ,NOT_IMPLEMENTED\
+ ,BAD_GATEWAY\
+ ,VARIANT_ALSO_VARIES\
|\
|\
|
@@ -3957,7 +4008,7 @@
|
X|SA-methods\
|M_GET,M_PUT,M_POST,M_DELETE,M_CONNECT,M_OPTIONS,M_TRACE,M_PATCH,\
- ,M_PROPFIND,M_MKCOL,M_COPY,M_MOVE,M_LOCK,M_UNLOCK,M_INVALID\
+ ,M_PROPFIND,M_PROPPATCH,M_MKCOL,M_COPY,M_MOVE,M_LOCK,M_UNLOCK,M_INVALID\
|\
|\
|
1.18 +59 -26 httpd-docs-1.3/apidoc/tools/mkapidict
Index: mkapidict
===================================================================
RCS file: /home/cvs/httpd-docs-1.3/apidoc/tools/mkapidict,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -u -r1.17 -r1.18
--- mkapidict 2001/03/01 02:54:08 1.17
+++ mkapidict 2001/05/16 11:23:33 1.18
@@ -21,6 +21,9 @@
# 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.
@@ -33,6 +36,8 @@
#
# 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.
@@ -78,7 +83,7 @@
@errors = ();
$ofh = \*STDOUT;
-getopts("Dd:l:o:t:v", \%arg);
+getopts("Dd:l:no:t:v", \%arg);
$Verbose = defined($arg{'v'});
$Debug = defined($arg{'D'});
@@ -96,6 +101,9 @@
&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");
}
@@ -121,6 +129,7 @@
}
$dict = new APIdict($Dfile);
+$dict->hyperlinks(! $nolinks);
$OutFile = "$InFile.bak";
@@ -128,6 +137,8 @@
%HREF = ();
@Prologue = ();
@Epilogue = ();
+@code_bracket = ("<code>", "</code>");
+@no_bracket = ("", "");
#
#
@@ -173,13 +184,18 @@
$line =~ s"(\$Generated by:).*\$"$1 $command_line \$";
print $ofh $line;
}
+$x_routines = $dict->insert_link('Routine Descriptions', "", "", '#Routines');
+$x_structs = $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><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>
+ <li>$x_routines</li>
+ <li>$x_structures</li>
+ <li>$x_cells</li>
+ <li>$x_consts</li>
</ul>
<hr>
EOHT
@@ -221,7 +237,7 @@
&verbose("Dumping data cells.");
&dump_list('D', @keys);
-print $ofh <<EOHT;
+$etext = <<EOHT;
<h2><a name="Constants">Constant Definitions</a></h2>
<p>
Many of the compile-time choices are determined by the settings of
@@ -231,19 +247,20 @@
are controlled by constants.
</p>
<p>
- Some of the Apache Web server's constants (such as
- <a href="$HREF{'SERVER_VERSION'}"><samp>SERVER_VERSION</samp></a>)
+ 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
- <a href="$HREF{'MAX_STRING_LEN'}"><samp>MAX_STRING_LEN</samp></a>,
+ MAX_STRING_LEN,
are provided as conveniences, and shouldn't be modified except under
special circumstances. Still others, such as
- <a href="$HREF{'OR_LIMIT'}"><samp>OR_LIMIT</samp></a>,
+ 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);
@@ -291,11 +308,10 @@
foreach (sort {uc($a) cmp uc($b)} (@items)) {
my ($uri) = $HREF{"$_"};
-
- print $ofh <<EOHT;
- <li><a href="$uri"><code>$_</code></a></li>
-EOHT
+ print $ofh " <li>"
+ . $dict->insert_link($_, @code_bracket, $uri)
+ . "</li>\n";
}
print $ofh <<EOHT;
@@ -406,7 +422,7 @@
}
print $ofh "<a name=\"$uri\"><pre>$edited</pre></a>\n";
}
- $edited = $dict->add_links($isamp, $iname, %HREF);
+ $edited = $dict->add_links($isamp, $iname, @code_bracket, %HREF);
if ((! $edited) && ($Layout < 2)) {
$edited = "No examples available.";
&verbose("$0: no examples for $iname");
@@ -429,7 +445,8 @@
$idesc = $dict->description($key);
if ($idesc) {
- $idesc = $dict->add_links($idesc, $key, %HREF);
+ $idesc = $dict->add_links($idesc, $key,
+ @code_bracket, %HREF);
print $ofh <<EOHT if ($Layout < 2);
$idesc
EOHT
@@ -469,7 +486,8 @@
# Expand any aliased 'see-also' entries.
#
$sees = join(",\n ", $dict->expanded_seealso($key));
- $edited = $dict->add_links($sees, $key, %HREF);
+ $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";
@@ -486,15 +504,13 @@
if ($Layout == 0) {
if ($previous) {
- $previous = '<a href="' . $HREF{"$previous"} . '">'
- . "<code>$previous</code></a>";
+ $previous = $dict->insert_link($previous, @code_bracket);
}
else {
$previous = "(none)";
}
if ($next) {
- $next = '<a href="' . $HREF{"$next"} . '">'
- . "<code>$next</code></a>";
+ $next = $dict->insert_link($next, @code_bracket);
}
else {
$next = "(none)";
@@ -506,11 +522,11 @@
Next: $next
</p>
<p>
- <a href="$arg{'o'}">Table of Contents</a>
- (<a href="$arg{'o'}#Routines">Routines</a>,
- <a href="$arg{'o'}#Structures">Structures</a>,
- <a href="$arg{'o'}#Cells">Data Cells</a>,
- <a href="$arg{'o'}#Constants">Constants</a>)
+ &link('Table of Contents', $arg{'o'})
+ (&link('Routines', "$arg{'o'}#Routines"),
+ &link('Structures', "$arg{'o'}#Structures"),
+ &link('Data Cells', "$arg{'o'}#Cells"),
+ &link('Constants', "$arg{'o'}#Constants"))
</p>
</body>
</html>
@@ -562,3 +578,20 @@
return 1;
}
+sub link {
+ my($anchor, $href) = @_;
+ 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'");
+ }
+ return $result;
+}
---------------------------------------------------------------------
To unsubscribe, e-mail: apache-docs-unsubscribe@apache.org
For additional commands, e-mail: apache-docs-help@apache.org