httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From c...@apache.org
Subject cvs commit: httpd-docs-1.3/apidoc/tools mkapidict
Date Wed, 16 May 2001 11:23:35 GMT
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


Mime
View raw message