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.
