You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@cocoon.apache.org by Andrew Savory <an...@luminas.co.uk> on 2003/03/20 18:37:53 UTC
Sorting out the docs
Hi,
Here's what I'm going to do to try and resolve some of the documentation
issues we're having (the issues I see are maintenance of multiple
documentation branches, indicating deprecation in documentation,
extracting meaningful documentation from the code, and increasing semantic
quality of content):
- Take a look at Forrest and try and get the Cocoon Forrest transition
complete. This will probably include hassling the Forrest folk to add
deprecation to their DTDs.
- Try merging a few sample documents from the 2.0 and 2.1 tree into a c2
common version to see how it might work. Particular sticking points might
be the INSTALL doc which will vary greatly and version-specific docs - how
do we act if no version is given?
- Try out a few examples of literate programming on the logicsheets
(putting documentation into the XSL and processing in a similar way to
javadocs)
- Look at how the literate XSL documentation will affect the current
documentation. I expect the current documentation will become more
"howto/example/demo" related, and possibly even obsolete in favour of the
wiki.
I'll keep you posted as I progress. Here come some sleepless nights! :-)
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
Re: Sorting out the docs
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Bertrand Delacretaz wrote, On 21/03/2003 10.47:
> Le Vendredi, 21 mars 2003, à 10:27 Europe/Zurich, Andrew Savory a écrit :
>
>> ...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?
I have already committed the old javadoc-xml doclet, along with javasrc,
to Alexandria. I'm going to update the site too (in CVS it's already
done and uses Forrest).
XSLDoc is still in the pipeline, but haven't gotten yet the license
grant paper AFAIK, but we can put it in as a jar and use it from there
probably.
Noe that I'm reducing my exposition in Avalon (and I'm not chair
anymore), I'll concentrate more on this stuff.
> Bart Guijt posted a JavadocSource patch a while ago, it might help, see
>
> http://nagoya.apache.org/bugzilla/show_bug.cgi?id=16523
> http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=104401023423515&w=2
Cool!
I am also going to commit ASAP a javascript "javadoc" generator (cool
for the flow) and an ant doc generator.
I want to have a comprehensive javadoc for the whole project docs, all
interlinked.
Wanna help? alexandria-dev-subscribe@jakarta.apache.org
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Sorting out the docs
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
Le Vendredi, 21 mars 2003, à 10:27 Europe/Zurich, Andrew Savory a écrit
:
> ...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?
Bart Guijt posted a JavadocSource patch a while ago, it might help, see
http://nagoya.apache.org/bugzilla/show_bug.cgi?id=16523
http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=104401023423515&w=2
-Bertrand
Re: Sorting out the docs
Posted by Andrew Savory <an...@luminas.co.uk>.
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
Re: Sorting out the docs
Posted by David Crossley <cr...@indexgeo.com.au>.
Andrew Savory wrote:
> Here's what I'm going to do to try and resolve some of the documentation
> issues we're having (the issues I see are maintenance of multiple
> documentation branches, indicating deprecation in documentation,
> extracting meaningful documentation from the code, and increasing semantic
> quality of content):
>
> - Take a look at Forrest and try and get the Cocoon Forrest transition
> complete. This will probably include hassling the Forrest folk to add
> deprecation to their DTDs.
Please join the effort. The transition will definitely
take more than one person. I presume that you have seen
the Wiki ForrestProposal.
No need to "hassle" .. forrest-dev is keen to facilitate any
real-world need. Just clearly define what is needed here and
we will then post to forrest-dev list.
Here is the reference that Diana was looking for in another thread:
http://cvs.apache.org/viewcvs.cgi/xml-forrest/etc/DTD_DEFICIENCIES.txt?rev=HEAD&content-type=text/vnd.viewcvs-markup
> - Try merging a few sample documents from the 2.0 and 2.1 tree into a c2
> common version to see how it might work. Particular sticking points might
> be the INSTALL doc which will vary greatly and version-specific docs - how
> do we act if no version is given?
We tried not to have many differences between the xdocs
in 2.1 and 2.0 ... Diana, and various other people, worked
hard to keep it in sync. It just needs a uniform way to
note which branch certain paragraphs refer to. There are
only a few documents where there are specific differences
in each branch (they could certainly be unified).
> - 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".
> - Look at how the literate XSL documentation will affect the current
> documentation. I expect the current documentation will become more
> "howto/example/demo" related, and possibly even obsolete in
> favour of the wiki.
I expect that the Cocoon xdocs evolve into a truly
excellent and authoritative resource. I doubt that the
Wiki will replace that. Wiki is great as a breeding ground
and for supplemental documentation. However, i fear that
it could needlessly duplicate stuff that is in xdocs.
> I'll keep you posted as I progress. Here come some sleepless nights! :-)
Glad that you are keen.
--David
Re: Sorting out the docs
Posted by Tony Collen <tc...@neuagency.com>.
On 21 Mar 2003, David Crossley wrote:
> I do not understand why you want to go this roundabout way
> and why change to a different format for docs. The current docs
> can evolve and get improved navigation after the transition with
> Forrest.
I was just proposing a possible alternate organization for the docs we
have on the site now and will have once they get written ;^) It was never
my intention to change how they're navigated to or how they're written or
marked up. I was just using the plain text as a super-quick way of
fleshing out a bunch of ideas I was having too fast to Wikify. Which I
will be doing very shortly.
Regards,
Tony
Re: Sorting out the docs
Posted by David Crossley <cr...@indexgeo.com.au>.
Bertrand Delacretaz wrote:
> David Crossley a écrit :
>
> > Tony Collen wrote:
> >> ....I'm still considering using the PHP manual [1] as a skeleton...
> >
> > ...I do not understand why you want to go this roundabout way
> > and why change to a different format for docs....
>
> What I like from Tony's idea is the "refactoring" the existing
> docs to create a better organization/navigation on the site.
Oh yeah, i do agree with that, but after sorting things
out with Forrest. Besides, Forrest brings better ways
to build the navigation aspects of the site.
--David
> Prototyping this in another format is fine but you're right that
> there's no need to change the format of the docs (except moving to
> Forrest DTDs).
>
> -Bertrand
>
Re: Sorting out the docs
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
Le Vendredi, 21 mars 2003, à 07:46 Europe/Zurich, David Crossley a
écrit :
> Tony Collen wrote:
>> ....I'm still considering using the PHP manual [1] as a skeleton...
>
> ...I do not understand why you want to go this roundabout way
> and why change to a different format for docs....
What I like from Tony's idea is the "refactoring" the existing docs to
create a better organization/navigation on the site.
Prototyping this in another format is fine but you're right that
there's no need to change the format of the docs (except moving to
Forrest DTDs).
-Bertrand
Re: Sorting out the docs
Posted by David Crossley <cr...@indexgeo.com.au>.
Tony Collen wrote:
> Bertrand Delacretaz wrote:
>
> > A while ago we discussed a plan for the differents types of docs, see
> > http://wiki.cocoondev.org/Wiki.jsp?page=CocoonDocsPlan . Reorganizing
> > the existing docs around these "axes" might help too.
>
> I'm still considering using the PHP manual [1] as a skeleton and start
> dropping what we have into a format like that, and put it into XML after
> the content is all written up. I'd probably pick and choose fom the wiki
> and current docs in CVS... this might be a project for a bored weekend it
> looks like.
I do not understand why you want to go this roundabout way
and why change to a different format for docs. The current docs
can evolve and get improved navigation after the transition with
Forrest.
If you have spare weekends then cocoon-d* has a place for
you to spend them :-)
--David
Re: Sorting out the docs
Posted by Diana Shannon <sh...@apache.org>.
On Thursday, March 20, 2003, at 05:17 PM, Tony Collen wrote:
> On Thu, 20 Mar 2003, Bertrand Delacretaz wrote:
>
>> Le Jeudi, 20 mars 2003, à 22:47 Europe/Zurich, Tony Collen a écrit :
>>
>>> ...I'm still considering using the PHP manual [1] as a skeleton and
>>> start
>>> dropping what we have into a format like that...
>>
>> Agreed - starting from scratch with a better/simpler navigation
>> structure would certainly help make our docs more accessible.
>
> Alright, here's a quick skeleton of what I whipped out in the past half
> hour or so. I'm starting to be very optimistic about this....
Thanks for doing this Tony.
Thoughts:
- Input on this will be easier on wiki, don't you think?
- did you check out
http://xml.apache.org/cocoon/plan/proposed-toc.html
- I think the FAQ section is rather limited. I don't think all existing
FAQs will be consolidated into How-Tos or Tutorials.
Diana
Re: Sorting out the docs
Posted by Tony Collen <tc...@neuagency.com>.
On Thu, 20 Mar 2003, Bertrand Delacretaz wrote:
> Le Jeudi, 20 mars 2003, � 22:47 Europe/Zurich, Tony Collen a �crit :
>
> > ...I'm still considering using the PHP manual [1] as a skeleton and
> > start
> > dropping what we have into a format like that...
>
> Agreed - starting from scratch with a better/simpler navigation
> structure would certainly help make our docs more accessible.
Alright, here's a quick skeleton of what I whipped out in the past half
hour or so. I'm starting to be very optimistic about this....
Tony
-----------------
The Cocoon Manual
-----------------
(c) 1999-2003 Apache Software Foundation
----------------------------------------
Table of Contents
Preface
-------
Getting Started
---------------
Intro / History
Installation
Blocks
Configuring Cocoon
Logging Levels
Security Concerns
Component Reference
-------------------
(This section will not have any "How-To" or Tutorial type material) This
section must be 100% reference material: how the components work (quickly
explained) and any parameters they might need.)
Actions
Authentication
Generators
Flow Layer
Function Reference
Logicsheets
Matchers
Readers
Selectors
Serializers
Sitemap
Transformers
XMLForms
Extending Cocoon
----------------
Custom Components
Actions
Generators
Matchers
Readers
Selectors
Serializers
Transformers
Connecting Cocoon to a Database
Other Avalon Components
Blocks
How-Tos / Tutorials
-------------------
Any articles (Such as the current WebServiceProxyGenerator docs)
regarding how to accomplish a specific task will be put here. No
reference material here!! There is lots of material in the current docs
under "User Guide", as well as "Dev Guide", "FAQs" and "Tutorials" that
can all be consolidated under this section.
1.
2.
3.
FAQ: Frequently Asked Questions
-------------------------------
Bug Database
Cocoon Bylaws
Mail List Archives
Mail Lists
cocoon-users
cocoon-dev
cocoon-docs
Getting Cocoon
Releases
Binary
Source
CVS
Installing Cocoon
Build Problems
Appendix
--------
Debugging Cocoon
Components
Flow
Sitemap
XSLT
History of Cocoon
Hosting Services
Links about Cocoon
Livesites
Migrating from Cocoon 1 to Cocoon 2.x
TODO
Re: Sorting out the docs
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
Le Jeudi, 20 mars 2003, à 22:47 Europe/Zurich, Tony Collen a écrit :
> ...I'm still considering using the PHP manual [1] as a skeleton and
> start
> dropping what we have into a format like that...
Agreed - starting from scratch with a better/simpler navigation
structure would certainly help make our docs more accessible.
-Bertrand
Re: Sorting out the docs
Posted by Tony Collen <tc...@neuagency.com>.
On Thu, 20 Mar 2003, Bertrand Delacretaz wrote:
> A while ago we discussed a plan for the differents types of docs, see
> http://wiki.cocoondev.org/Wiki.jsp?page=CocoonDocsPlan . Reorganizing
> the existing docs around these "axes" might help too.
I'm still considering using the PHP manual [1] as a skeleton and start
dropping what we have into a format like that, and put it into XML after
the content is all written up. I'd probably pick and choose fom the wiki
and current docs in CVS... this might be a project for a bored weekend it
looks like.
Regards,
Tony
[1] http://www.php.net/manual/en/
Re: Sorting out the docs
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
Le Jeudi, 20 mars 2003, à 18:37 Europe/Zurich, Andrew Savory a écrit :
. . .
<snip-sounds-exciting/>
> ...I expect the current documentation will become more
> "howto/example/demo" related, and possibly even obsolete in favour of
> the
> wiki.
This wiki vs. CVS/xdocs issue is a tough one I think - there are great
examples of wiki-based documentation around
(http://hibernate.bluemars.net/1.html), but OTOH having the wiki as a
scratchpad and documentation breeding ground is great. In the case of
hibernate I think the wiki is a closed one, not everyone is allowed to
write on it, that's an important difference for "official" docs.
Part of the problem might be that the current docs (or their
navigation) are not very well organized. Forrestizing and rethinking
the navigation should help a lot, and once the CVS-based docs look good
we might finally be able to move the best stuff from the wiki to CVS
and keep on using the wiki as a scratchpad.
A while ago we discussed a plan for the differents types of docs, see
http://wiki.cocoondev.org/Wiki.jsp?page=CocoonDocsPlan . Reorganizing
the existing docs around these "axes" might help too.
> I'll keep you posted as I progress. Here come some sleepless nights!
> :-)
We'll be watching this space...it is great to see more action on this
list and around the docs!
-Bertrand
Re: Sorting out the docs
Posted by Diana Shannon <sh...@apache.org>.
On Thursday, March 20, 2003, at 12:37 PM, Andrew Savory wrote:
> - Take a look at Forrest and try and get the Cocoon Forrest transition
> complete. This will probably include hassling the Forrest folk to add
> deprecation to their DTDs.
>
> - Try merging a few sample documents from the 2.0 and 2.1 tree into a c2
> common version to see how it might work. Particular sticking points
> might
> be the INSTALL doc which will vary greatly and version-specific docs -
> how
> do we act if no version is given?
Cool. Keep us posted on your progress.
> - Try out a few examples of literate programming on the logicsheets
> (putting documentation into the XSL and processing in a similar way to
> javadocs)
This would be **very** useful.
> - Look at how the literate XSL documentation will affect the current
> documentation. I expect the current documentation will become more
> "howto/example/demo" related, and possibly even obsolete in favour of
> the
> wiki.
In other words, that users may best contribute how-tos/examples/demos
while the Cocoon project might best contribute reference-oriented docs.
You could be right, but the concept is a bit too radical for me to
absorb ATM.
Thanks for your willingness and enthusiasm -- even sleepless
nights?? ;-) -- to tackle all of the above.
Diana
Re: Sorting out the docs
Posted by Tony Collen <tc...@neuagency.com>.
I've put up my rough outline up on the Wiki at [1]. Please check it out,
and help flush it out more. I think there's a lot from [2] that could be
rolled into this outline, for instance the pipeline and pool tuning part
could go into the newer outline. It's starting to look good!!
Tony
[1] http://wiki.cocoondev.org/Edit.jsp?page=DocsReorgProposal
[2] http://xml.apache.org/cocoon/plan/proposed-toc.html