xml-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Berin Loritsch <blorit...@apache.org>
Subject Re: Using C2 for docs
Date Fri, 20 Jul 2001 18:41:24 GMT
Jason van Zyl wrote:
> 
> Hi,
> 
> I'm working on the xmlrpc docs, and I would like to be a C2 guinea pig :-)
> 
> I will take a look at the avalon docs as an example and go from there.
> 
> Berin, can you put something in place for xml.apache.org so I can
> transform the xml docs when I'm done? I'm in no real rush, and I'm
> willing to try the dogfood.

There is a file called site2xhtml.xsl.  This is in XHTML markup with
a couple of tags to transform the menu and the body.  Start by getting
the source for xml.apache.org, and hollow it out so that you know
where the menu goes, and where the body goes.  You will have to make
sure that the markup is proper XHTML.

The next process is to convert the book2menu.xsl file to produce the
proper fragment that goes in there.

The problem with xml.apache.org is that it is very graphics intensive,
and even has some generated images.  I am no expert in SVG, but you
would use that to create the images.

> I've never used C2 so I can't say how it compares to Anakia, but
> I won't know until I go through the process. I am willing to
> give it a shot.

Well, I will admint that Cocoon's command line opperation can be
improved a little bit--and a very important an necessary feature
will be added soon.  This is the ability to list the URLs in a file
and have Cocoon transform them.

As to performance:

Cocoon can run ant, start up a new VM and execute Cocoon, compile the
sitemap, and transform the entire Avalon site in less than 30 seconds
on my machine.  It will slow down considerably when you include SVG
image generation to the mix--but hey, that's something Anakia can't
do anyway.

> Have we arrived at a location for the documentation? I've looked
> at xerces, xml-axis and c2 and they all have different setups:
> 
> docs/ with xml inside
> docs/ with html inside
> xdocs/ with xml inside

When using Cocoon, I would advocate creating a "pseudo-context" for
your documentation.

documentation/xdocs (with xml inside)
documentation/stylesheets (with stylesheets for the site)
documentation/resources (with images/whatever else)

Note that the sitemap included in the Avalon documentation directory
won't need to change much to accomodate the xml.apache.org site.

> I would assume that xdocs/ with xml inside will be the standard?

I believe that this is best.  The name of the directory infers xml
documentation.

> I'm willing to try the system whenever it is in place.

The Avalon site has the system in place--using both the "document"
markup associated with Stylebook, and the official DocBook 4.1
markup.  In fact, there is a stylesheet to convert stylebook markup
to DocBook markup included!

The Avalon project just hasn't gotten around to converting all the
docs to DocBook.

Why DocBook?  Asside from being a standard, there are numerous tools
that work with the DocBook standard (including writing documentation
in a WYSIWYG environment).  I hope to get PDF generation of the site
working as well.

Call to FOP guys:

If you can come up with a DocBook to XSL:FO markup stylesheet that is
standard to all projects, it would help out tremendously.  Start with
the docbook2xhtml.xsl stylesheet I have in Avalon's CVS (as it has the
subset of DocBook we would most be concerned with).

Why did I come up with my own stylesheet instead of using Norman Walsh's?
Because for me it was easier.  I have looked at Norman's stylesheets, and
I quickly get lost due to all the logic he puts in there to automatically
spit out transformed files.  90% of what we need can be produced with 10%
of the effort that goes into Norman's sheets.  The remaining 10% (that
takes up the remaining 90% of the effort) can be added as we need it.
Mime
View raw message