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

List:       forrest-dev
Subject:    Re: analysis paralysis :-)
From:       Christopher Lenz <cmlenz () gmx ! de>
Date:       2002-02-28 9:38:49
[Download RAW message or body]

Hi all,

27.02.2002 17:29:52, Stefano Mazzocchi <stefano@apache.org> wrote:
>John Morrison wrote:
[snip]
>> Without doubt they should use xml.  Question is - should they all 
>>*have* to use the same DTD/schema?
>
>I would be a great plus if they did, don't you think?
>
>But it's utopical to think they will do just because we tell them to 
>do it.
>
>So we have to come up with an easy and appealing transition process.

Okay, I'll have to jump in here... I've recently been working on a 
reorganization of the docs for the Jakarta Slide project. Feeling that 
the documentation build process, the webpage structure, but also the 
flexibility and power of the "document" DTD are not quite 
satisfactory, I've been following the Forrest effort with some 
interest.

As for the Slide docs, after lots of of different attempts and 
thinking, I'm currently basing it all on the Cocoon 2 CLI, but using 
DocBook XML as DTD for the "real" documentation (i.e. the notorious 
User's Guide, Developer's Guide). [Note none of this is in CVS yet, 
and hasn't been approved by the other committers, but neither has it 
been vetoed]

There are a couple of reasons why I've chosen the DocBook format:
- it's a standard, used by many projects (OS or not)
- it's very expressive and probably features all the tags everyone 
could want for documentation, with a sophisticated structure
- the DTD is maintained by a group of experts, and is well tested in 
production environments
- there exist stylesheets to HTML/XHTML/FO etc. that handle most of 
the DocBook tags quite well, which is great to base custom stylesheets 
on
- DocBook is a pretty much ideal source format for transforming to FO.
- but most importantly: DocBook is very well documented (particulary 
by Norman Walsh's online/offline book)

Of course, there are con's too, the two most important would be:
- DocBook is complex (which I don't think is a good argument, as 
nobody *needs* to use all of the tags)
- It's not as similar to HTML as the Apache document DTD

Okay, now I've heard there have been wars about this topic before, but 
I just wanted remind you that projects might be already using a vastly 
more sophisticated DTD than what you intend to "transition" them to 
(look at Xindice for an example from the xml.apache.org world.) I 
think it would be nice if Forrest didn't require them to transition, 
and eventually even provide direct support for DocBook someday.

-chris
________________________________________________________________
cmlenz at gmx.de



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