cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andrew Savory <and...@luminas.co.uk>
Subject Re: Sorting out the docs
Date Fri, 21 Mar 2003 09:27:01 GMT

Hi,

On Fri, 21 Mar 2003, David Crossley wrote:

> Please join the effort. The transition will definitely
> take more than one person. I presume that you have seen
> the Wiki ForrestProposal.

Yep, working my way through.

> > - Try out a few examples of literate programming on the logicsheets
> > (putting documentation into the XSL and processing in a similar way to
> > javadocs)
>
> Would you please explain a bit more about what you mean by
> "literate programming".

Sure. See http://www.literateprogramming.com/ but essentially, by adding
some specifically formatted comments to our XSL we can extract meaningful
documentation (think javadoc). There's already some stylesheets marked up
minimally in this fashion (see for example action.xsl in
o/a/c/components/language/markup/xsp/java), and the chello demo at
chello.sourceforge.net includes xsldoc to do the transformations.

I was trying to work out yesterday if xsldoc was ever bundled with Cocoon,
or if it's possible to replace the xsldoc functionality with some XSL of
our own so that we can use Cocoon to generate the XSL docs.

This is where I ping Nicola, for saying "Cocoon-docs needs a javadoc
generator, and Alexandria needs to restart, along with javasrc and xsldoc
codebases". Nicola, did you have any particular solution in mind?

http://216.239.33.100/search?q=cache:2L3XxFG8CzYC:www.freeroller.net/page/nicolaken/20021210+verba+volant+cocoon-docs+xsldoc&hl=en&ie=UTF-8

As an example of how I see it implemented: the elements reference table on
http://xml.apache.org/cocoon/userdocs/xsp/request.html could easily be
generated dynamically (should be generated dynamically!) so that we know
it always reflects the current content of the logicsheet - assuming the
developers keep the comments up-to-date, which is a whole different
problem ;-)


Andrew.

-- 
Andrew Savory                                Email: andrew@luminas.co.uk
Managing Director                              Tel:  +44 (0)870 741 6658
Luminas Internet Applications                  Fax:  +44 (0)700 598 1135
This is not an official statement or order.    Web:    www.luminas.co.uk

Mime
View raw message