cvs commit: httpd-docs-1.3/apidoc README

[co...@locus.apache.org]

coar        00/07/24 13:26:35

  Modified:    apidoc   README
  Log:
  	Update the README with some reasonable instructions.
  
  Revision  Changes    Path
  1.2       +32 -14    httpd-docs-1.3/apidoc/README
  
  Index: README
  ===================================================================
  RCS file: /home/cvs/httpd-docs-1.3/apidoc/README,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -u -r1.1 -r1.2
  --- README	1998/05/03 01:24:10	1.1
  +++ README	2000/07/24 20:26:33	1.2
  @@ -8,25 +8,43 @@
       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 (mkapi) which puts all of these together to generate a
  -    single monolithic documentation file
  +  . a Perl script (mkapidict) which puts all of these together to generate
  +    the actual HTML documenation
   
  -There are currently four types of API entities defined: routines, constants,
  -structures, and global data cells.
  +There are currently four types of API entities defined: routines,
  +constants, structures, and global data cells.
   
  -The assembled output file labels each entity as a link target; the name
  -of the target is the entity name (e.g., HREF="#OK", HREF="ap_die").
  -Entity references in specifications and examples are automatically linked
  -to the appropriate definitions (e.g., the 'request_rec' text in the example
  -"ap_child_terminate(rerquest_rec *r)" is automatically a link to the
  -definition of the request_rec structure).
  +The mkapidict script can currently produce three different styles of
  +documentation; the style is controlled by the '-l' (layout) switch:
   
  + -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)
  +
  +Layout 0 should be used for generating the online Web-accessed
  +documentation; layouts 1 and 2 are good for producing something
  +suitable for printing.
  +
  +Entity references in specifications and examples (but not descriptions)
  +are automatically linked to the appropriate definitions (e.g., the
  +'request_rec' text in the example "ap_child_terminate(request_rec *r)"
  +is automatically a link to the definition of the request_rec structure).
  +Since the HTML fragments can't tell which layout is in use, they
  +MUST NOT link to other API entities.  It is safe for them to link
  +to items outside the API documentation, however, such as the documentation
  +page for an Apache module or directive.
  +
   Documentation fragment files should look like this (leading whitespace
   included):
   
  -  <P>
  +  <p>
     ..entity documentation..
  -  </P>
  -  <P>
  +  </p>
  +  <p>
     ..more docco..
  -  </P>
  +  </p>
  +
  +To build the documentation for the online Web site, use the following
  +command:
  +
  +    ./mkapidict -l0 -d api.list -o index.html -t api-dict.html -v