You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by Stefano Mazzocchi <st...@apache.org> on 2002/02/28 17:33:56 UTC
Document DTD vs. Docbook DTD
This is a holy war and I don't want to fight it.
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?
Ideas are welcome.
--
Stefano Mazzocchi One must still have chaos in oneself to be
able to give birth to a dancing star.
<st...@apache.org> Friedrich Nietzsche
--------------------------------------------------------------------
Re: Document DTD vs. Docbook DTD
Posted by Nicola Ken Barozzi <ba...@nicolaken.com>.
From: "Stefano Mazzocchi" <st...@apache.org>
> This is a holy war and I don't want to fight it.
>
> 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?
Centipede currently uses a modified version of the stylesheets of Avalon.
If you look at the sitemap, every document is transformed in Docbook, then
in Html.
I think that this makes sense, because Docbook is much more expressive and
there are already made stylesheets to convert Docbook to other formats.
If we do this, the Document DTD is basically becomes a simplified version
for writing content.
Transforming a simple format to a complex one is easy.
The other way round, you loose information.
--
Nicola Ken Barozzi barozzi@nicolaken.com
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Document DTD vs. Docbook DTD
Posted by Andreas Hartmann <de...@cocooncenter.de>.
*********** REPLY SEPARATOR ***********
On 28.02.2002 at 18:31 Nicola Ken Barozzi wrote:
>From: "Andreas Hartmann" <de...@cocooncenter.de>
>
>> Just a question - are there any XSL:FO stylesheets to create
>> PDF from a Document DTD document? Some people might be missing
>> a printable version (with TOC and page numbers) of the docs ...
>
>There's a stylesheet that does this from Docbook.
I know.
>And since there is also one that transforms Document DTD to Docbook...
That would require converting a document to DocBook.
If this works without any problems, it could be used to create
dynamic PDF documentation (e. g., with Cocoon).
I must admit that I had some problems creating PDF from DocBook
documents with Cocoon. Maybe newer versions will work better.
Andreas
Re: Document DTD vs. Docbook DTD
Posted by Nicola Ken Barozzi <ba...@nicolaken.com>.
From: "Andreas Hartmann" <de...@cocooncenter.de>
> Just a question - are there any XSL:FO stylesheets to create
> PDF from a Document DTD document? Some people might be missing
> a printable version (with TOC and page numbers) of the docs ...
There's a stylesheet that does this from Docbook.
And since there is also one that transforms Document DTD to Docbook...
--
Nicola Ken Barozzi barozzi@nicolaken.com
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Document DTD vs. Docbook DTD
Posted by Andreas Hartmann <de...@cocooncenter.de>.
*********** REPLY SEPARATOR ***********
On 28.02.2002 at 17:33 Stefano Mazzocchi wrote:
>This is a holy war and I don't want to fight it.
>
>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?
Just a question - are there any XSL:FO stylesheets to create
PDF from a Document DTD document? Some people might be missing
a printable version (with TOC and page numbers) of the docs ...
Andreas
Re: Document DTD vs. Docbook DTD
Posted by Christopher Lenz <cm...@gmx.de>.
28.02.2002 17:33:56, Stefano Mazzocchi <st...@apache.org> wrote:
>This is a holy war and I don't want to fight it.
Agreed (- didn't want to start a "war", I was just feeling that no
consideration of the topic isn't good either.)
>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.
I think it's not so much about supporting 'legacy' formats.
DocBook is a very good format for writing technical documentation that
can be transformed into 25+ page PDF documents for nice offline
reading. The need for such printable, well-structured documentation is
the reason I've started migrating to DocBook for Slide.
>But how should we do that?
>
>Ideas are welcome.
For the typical "Welcome to project Dada. Project Dada enables you to
do ... You can grab the latest release here, or view the online user's
guide here..." webpage, DocBook arguably may not be the right way to
go, especially when considering dynamic generation and integration
with graphs, todos/changelogs etc. But for "User's Guide" style
documentation it is ideal.
Projects might want to choose DocBook for such documentation with good
reasons. But still, they want this documentation to be available as
integrated-looking webpages within the project website.
So what I would like Forrest to provide (and yes, I'd contribute if I
feel Forrest is going into a direction that I find useful for the most
urgent task: real documentation) would be:
- For generation of the website, provide stylesheets to transform
DocBook to the Document-DTD (which should probably always be done
offline)
- Provide stylesheets that transform DocBook into FO/PDF, featuring a
look that is common across Apache projects, and that work with Apache
technologies.
So maybe, directly supporting DocBook isn't the highest priority task
after all. But making it easier for projects to generate high-quality,
printable documentation should be more important than generating
maling-list-subscriber graphs, IMHO.
-chris
________________________________________________________________
cmlenz at gmx.de
Re: Document DTD vs. Docbook DTD
Posted by Nicola Ken Barozzi <ba...@nicolaken.com>.
From: "Stefano Mazzocchi" <st...@apache.org>
> 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
I'm +1 with all your comments on this issue, and IMO this point is *very*
true.
I tried using docbook on other project and:
1- I couldn't understand it, the DTD is not complex, it's incomprehensible,
at least to me
2- It's really too much more than one usually needs
3- Simplified docbook is not so much better
4- Docbook has so many tags that I happened to see many times that one
couldn't decide which tag to use in a particular situation; the DTD should
help you, not the opposite.
So yes, I totally agree.
My suggestion was just a technical possibility, and now I would change my 0
to -1 for Docbook.
I will remove the intermediate step in the xsl I'm writing from your
proposal.
--
Nicola Ken Barozzi barozzi@nicolaken.com
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Document DTD vs. Docbook DTD
Posted by Gianugo Rabellino <gi...@apache.org>.
Stefano Mazzocchi wrote:
>>So, we'd definitely need an aggregation-doctype, or whatever you
>>prefer to call it. The book-cocoon-v10.dtd seems to go into that
>>direction, but is obviously strongly focussed on website-generation
>>(menu-items, eh?), and doesn't provide enough information for FO-
>>transformation: global copyright/legalities, global title/subtitle,
>>possibly foreword/preface.
>>
>>If I find some time, I'll experiment with using/extending the
>>document1.1 DTD and a new aggregation-doctype to generate FO, and
>>report back what I find.
>>
>
> Thanks. We need all the ideas/comments/suggestions we can find.
>
OK, so here are my 0.2euros. I needed such a beast and came up with the
idea of generating TOCs automatically via XPath. Cocoon has the ability
to "XPath-query" directories both file system and XML:DB based (AKA
Collections). The idea was simple as running an XPath Query against a
bunch of document, extracting the proper informations and formatting
them. Easy and dynamic: I don't like the idea of having to edit both a
document and an "aggregation" document. True, it might be good to come
up with some sort of DTD for aggregated documents, provided that the
generation of such documents is dynamic. Makes sense?
Ciao,
--
Gianugo Rabellino
Re: Document DTD vs. Docbook DTD
Posted by Stefano Mazzocchi <st...@apache.org>.
Christopher Lenz wrote:
>
> [snip lots]
> 01.03.2002 20:57:46, Stefano Mazzocchi <st...@apache.org> wrote:
> >Christopher Lenz wrote:
> >> 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?
>
> You're talking about Table-Of-Contents (TOC) generation here I think,
> not about index generation. To generate an index (usually found at the
> end of any at least half-decent book), you'll have to require the
> author to markup terms that should appear in the index, and the index
> will be generated from this information. I hope you agree that an
> index is a *very* important part of any large document (ie when you
> aggregate all the 'documents' into a 'book'), also because you don't
> have a search command for printed documentation.
Yes, you're right: document lacks indexing markup functionalities.
> [snip]
> >I'd rather augment Document than artificially reduce Docbook.
> >
> >That's my point.
>
> Okay, okay, so most of you dudes don't like DocBook. I respect that,
> especially because I'm just a user of the technologies provided, and
> don't want to pretend I could design the optimal, all-the-power-
> needed-but-none-of-the-overhead system myself. So if there was an
> Apache-recommended alternative to DocBook for large (aggregated, if
> you want), printable documentation I'd use it. Simple as that.
There will probably be no apache recommendation of sort.. we'll provide
you with a system that does all that you require, then, if you like it,
you use it, if not, you won't.
Simple as that :)
> So, we'd definitely need an aggregation-doctype, or whatever you
> prefer to call it. The book-cocoon-v10.dtd seems to go into that
> direction, but is obviously strongly focussed on website-generation
> (menu-items, eh?), and doesn't provide enough information for FO-
> transformation: global copyright/legalities, global title/subtitle,
> possibly foreword/preface.
>
> If I find some time, I'll experiment with using/extending the
> document1.1 DTD and a new aggregation-doctype to generate FO, and
> report back what I find.
Thanks. We need all the ideas/comments/suggestions we can find.
--
Stefano Mazzocchi One must still have chaos in oneself to be
able to give birth to a dancing star.
<st...@apache.org> Friedrich Nietzsche
--------------------------------------------------------------------
Re: Document DTD vs. Docbook DTD
Posted by Christopher Lenz <cm...@gmx.de>.
[snip lots]
01.03.2002 20:57:46, Stefano Mazzocchi <st...@apache.org> wrote:
>Christopher Lenz wrote:
>> 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?
You're talking about Table-Of-Contents (TOC) generation here I think,
not about index generation. To generate an index (usually found at the
end of any at least half-decent book), you'll have to require the
author to markup terms that should appear in the index, and the index
will be generated from this information. I hope you agree that an
index is a *very* important part of any large document (ie when you
aggregate all the 'documents' into a 'book'), also because you don't
have a search command for printed documentation.
[snip]
>I'd rather augment Document than artificially reduce Docbook.
>
>That's my point.
Okay, okay, so most of you dudes don't like DocBook. I respect that,
especially because I'm just a user of the technologies provided, and
don't want to pretend I could design the optimal, all-the-power-
needed-but-none-of-the-overhead system myself. So if there was an
Apache-recommended alternative to DocBook for large (aggregated, if
you want), printable documentation I'd use it. Simple as that.
So, we'd definitely need an aggregation-doctype, or whatever you
prefer to call it. The book-cocoon-v10.dtd seems to go into that
direction, but is obviously strongly focussed on website-generation
(menu-items, eh?), and doesn't provide enough information for FO-
transformation: global copyright/legalities, global title/subtitle,
possibly foreword/preface.
If I find some time, I'll experiment with using/extending the
document1.1 DTD and a new aggregation-doctype to generate FO, and
report back what I find.
-chris
________________________________________________________________
cmlenz at gmx.de
Re: Document DTD vs. Docbook DTD
Posted by Stefano Mazzocchi <st...@apache.org>.
Christopher Lenz wrote:
>
> 01.03.2002 10:38:19, Stefano Mazzocchi <st...@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.
<st...@apache.org> Friedrich Nietzsche
--------------------------------------------------------------------
Re: Document DTD vs. Docbook DTD
Posted by Nicola Ken Barozzi <ba...@nicolaken.com>.
From: "Steven Noels" <st...@outerthought.org>
> If we can agree on the usage of Docbook for complex documents (user and
> reference manuals seem like the relevant cases for this), and somebody
> jumps in this bandwagon to address our concerns against Docbook in terms
> of:
>
> - creating compact stylesheets to transform into Forrest HTML & PDF
> look&feel, not carrying the weight of Norman's stylesheets
> - describing what Docbook tags one should use (and those we don't
> support),
> It seems like we all agree Docbook being overweight as an authoring
> format for simple documents(web-pages being a good example), nor as a
> cross-transformation intermediate step.
Before deciding to support any type of Docbook, I would suggest we have a
real-life document that we will need to generate, see why Document DTD is
not enough, and maybe decide that a more complete Document DTD could
suffice.
Why would Docbook be better that a more complete Document DTD?
--
Nicola Ken Barozzi barozzi@nicolaken.com
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
RE: Document DTD vs. Docbook DTD
Posted by Steven Noels <st...@outerthought.org>.
Christopher Lenz wrote:
> Steven Noels wrote:
>
> >> 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 :(
Well, that depends...
If we can agree on the usage of Docbook for complex documents (user and
reference manuals seem like the relevant cases for this), and somebody
jumps in this bandwagon to address our concerns against Docbook in terms
of:
- creating compact stylesheets to transform into Forrest HTML & PDF
look&feel, not carrying the weight of Norman's stylesheets
- describing what Docbook tags one should use (and those we don't
support),
I see no problem in supporting Docbook for these specific document
types.
It seems like we all agree Docbook being overweight as an authoring
format for simple documents(web-pages being a good example), nor as a
cross-transformation intermediate step.
So what do you think?
Are you ready to take up the task? ;-)
</Steven>
Re: Document DTD vs. Docbook DTD
Posted by Christopher Lenz <cm...@gmx.de>.
01.03.2002 10:38:19, Stefano Mazzocchi <st...@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. 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
>polishness.
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 :(
-chris
_______________________________________________
/=/ cmlenz at gmx.de
Re: Document DTD vs. Docbook DTD
Posted by Stefano Mazzocchi <st...@apache.org>.
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.
<st...@apache.org> Friedrich Nietzsche
--------------------------------------------------------------------
RE: Document DTD vs. Docbook DTD
Posted by Andreas Hartmann <de...@cocooncenter.de>.
*********** REPLY SEPARATOR ***********
On 28.02.2002 at 18:34 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.
>
>> 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.
<precocious mode>
The more complicated the DTD is, the less people will want to write
documentation.
</precocious mode>
I agree.
>
>Having some logical-page-after-aggregation-document-type is much more
>important, I guess, as in
>http://www.martinfowler.com/isa/htmlRenderer.html.
>
>Being a standards advocate, Docbook is one of the exceptions to my rule
>that one should adopt standards as much as possible.
>
>Commenting in our 'own' DTD's: why is the title of a section hidden
>inside an attribute?
Yes, this is a little strange. I wondered how to create some text
decoration inside the heading when I wrote one of my tutorials.
Andreas
RE: Document DTD vs. Docbook DTD
Posted by Steven Noels <st...@outerthought.org>.
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.
> 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.
Being a standards advocate, Docbook is one of the exceptions to my rule
that one should adopt standards as much as possible.
Commenting in our 'own' DTD's: why is the title of a section hidden
inside an attribute?
</Steven>