forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Christopher Lenz <>
Subject Re: Document DTD vs. Docbook DTD
Date Fri, 01 Mar 2002 13:22:14 GMT
01.03.2002 10:38:19, Stefano Mazzocchi <> wrote:
>Steven Noels wrote:
>> Stefano wrote:
>> > This is a holy war and I don't want to fight it.
>> It is, indeed. Docbook tries to be everything to anyone, and as such is
>> a very complex authoring DTD to fully support, if only for relatively
>> short webpages. Plus I like having meaningful elements when authoring
>> specific documents, hence project-info.xml and the like. But maybe that
>> is because I am using a 'real' DTD-configured XML editor for such
>> tasks - perhaps text-editor-users are more than happy with a template
>> document.
>No, many people expressed the *exact* same concerns.
>If there was no documentation written for docbook, I would throw it down
>the drain *now* and forget about it.
>As far as documentation goes, that argument doesn't hold: sure, there is
>a book on docbook and no book on our Document DTD, but our stuff is so
>similar to 'clean HTML', once you realize that, nobody can have problems
>to write stuff using our DTD, if you look at the amount of documentation
>we have, it's growin much quicker than any other documentation effort,
>because the entry gap is reduced.

IMO it's growing mainly because documentation on Apache projects is generally on 
the weak side, and some people seem to feel a need. Now why isn't the Cocoon 
documentation provided as PDF, and why does Avalon use DocBook for their PDF 
'Developing with Avalon' ? I personally think that the document DTD, in it's 
similarity with XHTML, doesn't provide the semantic power needed to produce 
vastly different output formats (how do you want to generate an index, for 
example, how differentiate between internal and external links, ...)

>Ken suggests to use Docbook as an intermediate language for our
>stylesheets.... but I don't like that because it's not true that DocBook
>is more expressive than our DTD: for example, document_v11 uses nesting
>"sections" while docbook forces you to number your sections.

Not true. Nestable, not numbered sections are the preferred way in DocBook.

>I don't like that.
>Besides, docbook is *extremely* complex and while I see that could be
>useful for high-profile and good-looking printed document, I'm not sure
>that this is what we need, expecially given the fact that nobody is
>paying us to write the docs, so you can't expect the O'Reilly

Geeze, DocBook isn't that complex, sure it's got lots of tags, but nobody forces 
you to use every single on. For Apache concerns, there could be a document 
telling you which tags should not be used, also because they won't be handled by 
the stylesheet. And marking up filenames with a <filename>-tag, emphasized 
phrases with an <emphasis>-tag, etc provides more semantic information, and is 
actually very intuitive.

>For example: docbook has markup for escaping commands, code,
>shortcuts.... nobody ever needed those and the 'semantic' associated to
>those elements is not *that* important for us... I mean, nobody will
>ever markup those with that precision unless payed. Period.

see above

>The argument that many stylesheets already exist for docbook doesn't
>hold either: have you see them? they all suck! No matter how much Norman
>tries to build a stylesheet that serves *all* needs, the docbook
>stylesheets are *huge* and nobody ever tries to modify them because they
>are very monolithic... I don't want that, it's getting back to stylebook
>over again.

But they can be used as examples on how to handle some more complex topics, like 
auto-index, auto-toc.

>IMO, we should do the opposite: move from docbook to document_v11.
>> > Just one thing: there is a lot of content already written in
>> > docbook in
>> > the world and a lot of content written using Document DTD (various
>> > versions, but almost equivalent), so we should support both
>> > in order to
>> > avoid loosing some content.
>> >
>> > But how should we do that?
>> I'm not convinced we should transform 'across Docbook' other than for
>> showing off Cocoon's pipeline power. We could however support Docbook
>> for specific content types such as (user/reference) manuals and more
>> lenghty documents.

That's what I'd like to see. But it seems we're not getting there :(

 /=/ cmlenz at

View raw message