httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Joshua Slive <sl...@commerce.ubc.ca>
Subject Re: xml docs: It's gonna happen (perhaps)
Date Wed, 13 Feb 2002 02:59:51 GMT

On Tue, 12 Feb 2002, Rich Bowen wrote:

> On Tue, 12 Feb 2002, Joshua Slive wrote:
>
> > I plan to proceed with this quite soon, before I lose my momentum.  So
> > please speak now or forever hold your peace.
>
> Just for posterity and my failing memory, can you tell us why this is a
> good idea?

Sure:

The current system of pure xhtml is very difficult to manage.  We can't
give the pages a nice style and we can't keep them in a consistent format.
I don't think I have heard anyone argue that pure-xhtml docs are a good
choice for a project of any size.

Taking as a premise that we need a new documentation format, there are
tons of different ones to choose from.  I think xml is a good choice for a
bunch of reasons, including the fact that it seems to be the new
"standard", we have several good Apache Software Foundation projects
supporting it, and it can actually be rendered directly with xsl
stylesheets in the latest browsers.  Now, we could choose to go with a
"cookbook" dtd like "docbook".  The problem with that is that the semantic
content of docbook does not match very closely with the needs of the httpd
docs.  Docbook elements are either too vague to give the right meaning, or
too tied to its original job of documenting a programming language.  In
addition, docbook is quite a complicated dtd, and can be difficult to use.

The benefits of the new format:

- Easy to style everything at once simply by changing the .xsl file.

- Much easier to "repurpose" the docs.  For example, an apache gui
designer could easily (programmatically) grab the correct parts to create
a help interface.  It should also be possible to create stylesheets to
generate pdf, windows help, etc.

- Easier to write.  Obviously, this is matter of taste, but I think you'll
find that the .xml is much clearer and, in fact, shorter than the old
.html.  Personally, writing <directive
href="#SetEnvIf">SetEnvIf</directive> feels much better to me than writing
<code><a href="#SetEnvIf">SetEnvIf</a></code>[1].

- Sticks very closely to the old doc format that we know and "love?".

- Will make it much easier to programmatically generate things like the
directive index, the module index, etc.  It already automatically
generates the "in page" index of directives.

I am very open to hearing counter-arguments and other ideas.  But every
time this has come up in the past, my conclusion has been that custom-xml
is really the only way to go.

[1] By the way, I'm trying to detmine whether it would be worthwhile to
change that to <directive module="mod_mime">AddLanguage</directive> and
have the xsl magically contruct the URL.  Any opinions?  The only
complication would be dealing with relative links when we get outside the
modules directory.

Joshua.


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org


Mime
View raw message