cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <>
Subject Re: C2 documentation
Date Tue, 19 Sep 2000 13:15:31 GMT
Hans Ulrich Niedermann wrote:
> Stefano Mazzocchi <> 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 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 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.

Oh, yeah, I'm totally aware of this.
> > > 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.

right, you could start working on this even now, separation of concerns
DOES work!

> 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.

Right, and increase document contributions (telling people "you have to
use Docbook" may be scary sometimes)
> 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.

I agree... well, up to you, the architecture is totally schema/content
> > > 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?

no, no, nothing like that: views change the way you think and connect
stuff but your documents remain the same.

> Or to improve performance by replacing all those
> loops-turned-recursive-functions in Norm's XSL stylesheets by "proper"
> programming logic?

I honestly don't know Norm's stylesheets well enough to tell you about
> > 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. :-)

cvs checkout jakarta-tomcat-4.0
cd jakarta-tomcat-4.0
cd ..
cvs checkout -r xml-cocoon2 xml-cocoon
cd xml-cocoon2
./ -Dinstall.war=../build/tomcat-4.0/webapps/
-Dinclude.webapp.libs=yes install
cd ../build/tomcat-4.0/

and see C2 in action in Catalina in its whole magnificence :)

Stefano Mazzocchi      One must still have chaos in oneself to be
                          able to give birth to a dancing star.
<>                             Friedrich Nietzsche
 Missed us in Orlando? Make it up with ApacheCON Europe in London!
------------------------- http://ApacheCon.Com ---------------------

View raw message