[prev in list] [next in list] [prev in thread] [next in thread] 

List:       forrest-dev
Subject:    Re: Document DTD vs. Docbook DTD
From:       Christopher Lenz <cmlenz () gmx ! de>
Date:       2002-02-28 21:56:26
[Download RAW message or body]

28.02.2002 17:33:56, Stefano Mazzocchi <stefano@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




[prev in list] [next in list] [prev in thread] [next in thread]