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 09:38:19 GMT
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.

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.

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.

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.

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.

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.
> 
> Having some logical-page-after-aggregation-document-type is much more
> important, I guess, as in
> http://www.martinfowler.com/isa/htmlRenderer.html.

Totally agreed and Docbook clearly doesn't fir that need.

> Being a standards advocate, Docbook is one of the exceptions to my rule
> that one should adopt standards as much as possible.

I don't think you are second to nobody here for standards advocation,
but for sure, I'm not the one that advocates to use a standard that was
written for something else (an SGML markup for describing printed books)
just because it's good that doing what it was designed for and a part of
what we're doing overlaps with that.

With those arguments, nobody would even invent anything.

> Commenting in our 'own' DTD's: why is the title of a section hidden
> inside an attribute?

Because the other option was

 <section>
  <title>...</title>
  ...
 </section>

but there was a mismatch between 'structural' elements (title) and block
elements (...), then a cleaner alternative was

 <section>
  <title>..</title>
  <content>
   ...
  </content>
 </section>

but it's way more verbose than

 <section title="...">
  ...
 </section>

and besides:

 1) every section has one and only one title
 2) didn't see no need for having nested markup in a title
 3) with XSLT and CSS2 there is no difference if some content is stored
in elements or attributes

but if you guys think differently I'm more than willing to reconsider
it.

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