cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Berin Loritsch <blorit...@apache.org>
Subject Re: Documentation
Date Wed, 03 Jan 2001 02:26:13 GMT
Ulrich Mayring wrote:

> Hi folks,
> 
> undoubtedly many of you have in the companies they work for the same
> problem as the cocoon project: how to document code in a sensible way?
> Of course we "XML people" think that documentation should be written in
> XML and there should be a stylesheet to generate printable docs (e.g.
> PDF via fop) and one for generating HTML docs for viewing online.

Ah, a subject near and dear to my heart.

> Now, I think we all agree that simply writing some kind of XML doesn't
> really do the trick either, there should be a standard. That's why the
> cocoon project uses StyleBook, which - correct me if I'm wrong - is a
> tool for working with the DocBook DTD. The problem with DocBook is that
> it is very complex and the problem with StyleBook is that is doesn't
> work online.

You are correct in stating that there should be a standard.
As to your assumption about StyleBook, let me correct you:
it is DocBook like meaning that it is not interchangable.
You are correct in both of your conclusions in the last
sentence.  The main difference is that you can use the
Stylebook markup and Cocoon to generate the docs.  In fact,
that is what we did at http://www.infoplanning.com.  A
word of caution: the entities described in the DTD don't
get properly translated to netscape clients.

> We have now internally decided to evaluate XMetal as an editor for
> writing docs and are now thinking about using the DocBook DTD with it.

You will find XMetal to be an excellent editor.  You will
find that you would be better to define a subset of
DocBook that is more limited in your choices of construction.
That way you will be able to have sane XSL stylesheets.
Norman Walsh (http://www.nwalsh.com) has some comprehensive
stylesheets for DocBook.  You will find them unsuitable
for live transformation.  It takes 5-7 seconds for the
stylesheet to be read and created, and up to a minute for
the document to be constructed.

> My questions:
> 
> - does this combination make it easy enough to write docs, so that even
> a lawyer or PR guy can use it?

The editor approaches that ease of use you are looking for.
Out of all the editors I evaluated, it is the best--bar none.
Most of the other XML editors have a lot of catching up to do.
Again I would suggest either using a subset of DocBook, or
the StyleBook markup.

> - are there other editors comparable to XMetal, perhaps even OpenSource?

I have looked and looked.  Unfortunately, I have not found
anything as easy to use.  If you are comfortable with the
markup itself, Allaire's HomeSite tool is excellent.

> - which way is the cocoon project headed?

That's a general question with a general answer.  Cocoon 2
has both live generation and command line generation
capabilities.  At this time, the live generation is much
more current and workable.

> - are there any other ideas? Am I perhaps on the wrong track?

I have come to the conclusion that DocBook, while a great
and mature standard, is too complex for web enabled
environments.  Take a subset of the DocBook definition
that has the features of StyleBook (otherwise you will
limit yourself too much).

DocBook was written initially as an SGML based markup,
with static generation tools.  In this role, it performs
very well.  In a more dynamic role, it is too complex.
Perhaps when computers can transform the entire DocBook
stylesheets in less than a second it won't be an issue.

> 
> Ulrich


Mime
View raw message