cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Hans Ulrich Niedermann <niederm...@isd.uni-stuttgart.de>
Subject Re: C2 documentation
Date Tue, 19 Sep 2000 01:42:07 GMT
Stefano Mazzocchi <stefano@apache.org> writes:

> Hans Ulrich Niedermann wrote:

[ C2 will generate its own documentation ]

> > How will this work btw?
> 
> eh, eh, different from what you'd expect, trust me, but once you get it,
> it will blow you out of this planet... and I mean it.
> 
> I'll write some architectural docs explaining what to do... and what not
> to do.

Then I'll stop doing anything about C2 docs until your explanations
and revelations are available. :-)

> > We were talking about migrating our docs to
> > Docbook in the future but Docbook XSL stylesheets won't generate the
> > Stylebook xml.apache.org look & feel without major additions.
> 
> Hmmm, can you elaborate more on this?

Well, Norm's stylesheets won't generate images at all, much less all
the fancy images necessary for the xml.apache.org layout. Not that I
particularly like this layout, but if we want to keep it, we'll have
to create a lot of stuff around and besides Norm's stylesheets.

> > And I
> > don't have any idea of how to integrate Document DTD, Stylebook
> > generated pages smoothly with Docbook DTD, Docbook XSL generated
> > pages.
> 
> No, that won't happen, we have to get rid of DocumentDTD-based
> stylesheets... everything should pass thru Docbook before being styled.

OK, so we will use

a) "filter stylesheets"
   These filter documentation tags (which contain valid Docbook XML) 
   out of taglibs, sitemaps and all other XML file whose main purpose
   also is not being documentation.
b) "structural reference stylesheets"
   These get information out of XML config files, XSchema definition
   files and other non-document XML files and mark these up as a
   reference. One example would be creation of a reference sheet for
   the sitemap XSchema that summarizes which elements may have which
   attributes and child elements.
c) document2docbook.html
   Converts old docs into docbook. Intermediate solution. Purpose is
   not having to migrate all docs to Docbook immediately.

which all output valid Docbook XML. This Docbook based stuff will then
somehow be converted into web site, HTML docs, PDF docs etc. using the
ingenious "blowing-you-off-the-planet" C2 doc creation method.

Perhaps a) and b) may be combined for the documentation of certain
subsystems. 

> > Perhaps one way to do it is to write Docbook <book>s and generate
> > convenient HTML pages via several XIncludes and stuff. This would
> > allow for printable docs as well as really fancy HTML pages with
> > common navigation bars and looks etc. This would of course require
> > some major additions to the HTML Docbook XSL stylesheets.
> 
> No, we should write our own Docbook XSL stylesheets.

Why is that? To better adapt to C2's abilities with views and stuff?
Or to improve performance by replacing all those
loops-turned-recursive-functions in Norm's XSL stylesheets by "proper"
programming logic?

> This is great, I'll let you know when the stuff is ready to play with
> and what to do.

OK.

First order of business will be to convince C2 to do more than throw a
java.lang.VerifyError on every request, though. :-)

Uli

Mime
View raw message