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
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