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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
