So, I've been thinking and investigating the whole XML issue a little
more, and I still don't know what is the best way for httpd-docs to go.
The obvious choice is docbook, which seems to be the standard for
open-source documentation, and has at least a moderate toolset behind it.
This would also force us to structure the docs in a more book-like form.
I think this may be an advantage in helping us to put more structure on
things.
However, I really don't think docbook offers us the correct structure for
the httpd docs. It is designed for technical documentation, but is
heavily slanted towards things like C-Functions and unix-commands.
For httpd, we really need to be able to do something like
<modulesynopsis>
<modulename>mod_env</modulename>
<modulepurpose>This module provides for modifying the environment which
is passed to CGI scripts and SSI pages.</modulepurpose>
<modulestatus>Base</Modulestatus>
[...]
<modulesummary>
<para>This module allows for control of the environment that will be
provided to CGI scripts and SSI pages. Environment variables may be
passed from the shell which invoked the httpd process. Alternatively,
environment variables may be set or unset within the configuration
process.</para>
</modulesummary>
<directivesynopsis>
<directivename>PassEnv</directivename>
<directivesyntax><directive>PassEnv</Directive>
<argument>env-variable</argument></directivesyntax>
<directivecontext>server config, virtual host</directivecontext>
[...]
</directivesynopis>
[...]
</modulesynopsis>
This would obviously be a massive customization of docbook and the
accompanying stylesheets. I think we would need a real docbook/XML/XSL
expert to do something like that, and I am certainly not one.
If we choose not to customize docbook, then we will wind up using
presentation-style markup for the module docs, which seems to defeat the
whole purpose of going to XML.
Anyone have any suggestions or comments?
Joshua.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
