RE: cvs commit: httpd-2.0/docs/manual env.xml filter.xml handler.xml env.html.en filter.html.en handler.html.en

[James Cox <im...@php.net>]

Silly question,

but why aren't we using DocBook for this?

 -- James

RE: cvs commit: httpd-2.0/docs/manual env.xml filter.xml handler.xml env.html.en filter.html.en handler.html.en

[Joshua Slive <jo...@slive.ca>]

On Sat, 27 Jul 2002, James Cox wrote:

> Silly question,
>
> but why aren't we using DocBook for this?

Not really a silly question.  It was debated extensively, although not
necessarily on this list.  (I tried to start the debate here, but most
not many people seemed insterested in arguing the other side.)  Some of my
opinions on the topic are
http://www.apachelabs.org/httpd-docs/200107.mbox/%3CPine.WNT.4.33.0107262016130.-2033491-100000@jgcomputer%3E
and
http://www.apachelabs.org/httpd-docs/200202.mbox/%3CPine.WNT.4.33.0202122137250.-1759159-100000@jgcomputer%3E

To summarize a few on the key reasons:

- Docbook doesn't have the semantic structure to properly mark-up an HTTP
Server manual.  It is designed for a programming language, and we would
need to really warp some of the meaning to get it to work for us.  This is
particularly true in the module documentation, but is also somewhat true
in the rest of the docs.

- The current format is heavily based on xhtml, and therefore it is rather
easy to convert the current docs to this format.

- Docbook is somewhat difficult to use.  It has tons of tags (although
this could be partly solved by using one of the "simple docbook" dtds) and
some things like the table markup are very obtuse.

My other response to this question is that, regardless of the format that
we choose, more structure is better.  So, for example, I would guess that
if we later decide to go with docbook, it should be possible to write some
xslt to transform the current format into something close to docbook.
Doing the same from raw xhtml would be much more difficult.

When I've been adding new tags (as opposed to borrowing from xhtml), I've
tried to match them as closely as possible to docbook.  But I can't claim
I've been entirely successful in that.

Joshua.