forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <stef...@apache.org>
Subject Re: Document DTD vs. Docbook DTD
Date Fri, 01 Mar 2002 19:57:46 GMT
Christopher Lenz wrote:
> 
> 01.03.2002 10:38:19, Stefano Mazzocchi <stefano@apache.org> 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. 

I disagree. Before we had xml-based doc generating tools like
stylebook/anakia/cocoon, things were much worse.

> Now why isn't the Cocoon
> documentation provided as PDF, and why does Avalon use DocBook for their PDF
> 'Developing with Avalon'?

This is because I consider what Berin did for chapter aggregation a
hack and I didn't want to replicate it, but rather think a better ways
of doing things (this project!)

The expressivity of DocBook has nothing to do with it.

> 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, ...)

by parsing the links? the information is there, requiring you to change
the semantics of a tag because you change it's payload is an indication
of bad design to me.

> >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.

But both tags are provided and you have to write stylesheets that
support both, thus effort duplication.

> >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
> >polishness.
> 
> Geeze, DocBook isn't that complex, sure it's got lots of tags, but nobody forces
> you to use every single on.

But it forces us to write stylesheets to match all of them.

> 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. 

I don't want this. All good XML editors are DTD-based and I want the
editor to
give me the right choices, not a bunch of them that I have to ignore
because the 'apache stylesheets' will ignore them anyway.

> And marking up filenames with a <filename>-tag, emphasized
> phrases with an <emphasis>-tag, etc provides more semantic information, and is
> actually very intuitive.

Document has <em> does exactly that and <filename> is way too specific:
people will simply write the filename and forget/ignore to mark it up
(I've
seen this happening *so* much in the past, believe me)

> >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.

<p> is equivalently semantic than <para>, so is <section>... why should
be simpler to write an auto-index with Docbook?

> >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 :(

I'd rather augment Document than artificially reduce Docbook.

That's my point.

-- 
Stefano Mazzocchi      One must still have chaos in oneself to be
                          able to give birth to a dancing star.
<stefano@apache.org>                             Friedrich Nietzsche
--------------------------------------------------------------------


Mime
View raw message