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 = (); [EMAIL PROTECTED] = ("<code>", "</code>"); [EMAIL PROTECTED] = ("", ""); # # @@ -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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]