You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@cocoon.apache.org by Jeff Turner <je...@apache.org> on 2003/01/24 14:48:58 UTC
Re: [ANN]JavaDoc generation using Cocoon
On Thu, Jan 23, 2003 at 04:45:31PM +0100, Stephan Michels wrote:
> Hi,
>
> first of all, I want thank you for your great work at forrest. I'm
> now using it for my documentation(http://chaperon.sourceforge.net/).
Nice :)
Mind if we add it to the 'live sites' page?
> I have made a webapp as example for my Chaperon parser, which
> generates documentation sites for source code similar to JavaDoc.
>
> http://vern.chem.tu-berlin.de/~stephan/chaperon/net/sourceforge/chaperon/adapter/cocoon/ParserTransformer.class.html
>
> http://vern.chem.tu-berlin.de/~stephan/chaperon/net/sourceforge/chaperon/adapter/cocoon/ParserTransformer.java.html
Wow.. impressive!
Cc'ing the cocoon-docs people, where there were some efforts to create a
Javadoc Generator for building Cocoon 'manpages':
http://outerthought.net/wiki/Wiki.jsp?page=FileGeneratorManPage
Any Forrest volunteers to implement a colourizer for inline code
snippets?
<source type="java">
public void foo() {
System.out.println("colourize me!");
}
</source>
--Jeff
> These sites are generated by Cocoon and the Chaperon components,
> and nothing more.
>
> It not very verbose, not very pretty, and not yet finished,
> but maybe your are interested.
>
> Stephan Michels.
Re: [ANN]JavaDoc generation using Cocoon
Posted by Steven Noels <st...@outerthought.org>.
Vadim Gritsenko wrote:
> Me think you want:
>
> RedirectMatch /wiki/(.*)$ http://wiki.cocoondev.org/$1
Nope :-( - that doesn't preserve the ?Page=blabla request parameter.
Come on, Stefan & Vadim, I know you can beat each other ;-)
I have this in httpd.conf right now:
<Location "/wiki">
RedirectMatch /wiki/(.*)$ http://wiki.cocoondev.org/$1
</Location>
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org stevenn at apache.org
Re: [ANN]JavaDoc generation using Cocoon
Posted by Steven Noels <st...@outerthought.org>.
Vadim Gritsenko wrote:
> Me think you want:
>
> RedirectMatch /wiki/(.*)$ http://wiki.cocoondev.org/$1
Nope :-( - that doesn't preserve the ?Page=blabla request parameter.
Come on, Stefan & Vadim, I know you can beat each other ;-)
I have this in httpd.conf right now:
<Location "/wiki">
RedirectMatch /wiki/(.*)$ http://wiki.cocoondev.org/$1
</Location>
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org stevenn at apache.org
Re: [ANN]JavaDoc generation using Cocoon
Posted by Vadim Gritsenko <va...@verizon.net>.
Steven Noels wrote:
> Jeff Turner wrote:
>
>> http://outerthought.net/wiki/Wiki.jsp?page=FileGeneratorManPage
>
>
> Jeff, the wiki has been moved to http://wiki.cocoondev.org/ for quite
> some time now. The new location of that document is
> http://wiki.cocoondev.org/Wiki.jsp?page=FileGeneratorManPage.
>
> If someone knows enough mod_rewrite to make that an automated
> redirect, please speak up (I'm being lazy).
From /www/cocoon.apache.org/.htaccess:
RedirectMatch (.*)$ http://xml.apache.org/cocoon$1
Me think you want:
RedirectMatch /wiki/(.*)$ http://wiki.cocoondev.org/$1
Vadim
> </Steven>
Re: [ANN]JavaDoc generation using Cocoon
Posted by Vadim Gritsenko <va...@verizon.net>.
Steven Noels wrote:
> Jeff Turner wrote:
>
>> http://outerthought.net/wiki/Wiki.jsp?page=FileGeneratorManPage
>
>
> Jeff, the wiki has been moved to http://wiki.cocoondev.org/ for quite
> some time now. The new location of that document is
> http://wiki.cocoondev.org/Wiki.jsp?page=FileGeneratorManPage.
>
> If someone knows enough mod_rewrite to make that an automated
> redirect, please speak up (I'm being lazy).
From /www/cocoon.apache.org/.htaccess:
RedirectMatch (.*)$ http://xml.apache.org/cocoon$1
Me think you want:
RedirectMatch /wiki/(.*)$ http://wiki.cocoondev.org/$1
Vadim
> </Steven>
Re: [ANN]JavaDoc generation using Cocoon
Posted by Steven Noels <st...@outerthought.org>.
Jeff Turner wrote:
> http://outerthought.net/wiki/Wiki.jsp?page=FileGeneratorManPage
Jeff, the wiki has been moved to http://wiki.cocoondev.org/ for quite
some time now. The new location of that document is
http://wiki.cocoondev.org/Wiki.jsp?page=FileGeneratorManPage.
If someone knows enough mod_rewrite to make that an automated redirect,
please speak up (I'm being lazy).
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org stevenn at apache.org
Re: [ANN]JavaDoc generation using Cocoon
Posted by Steven Noels <st...@outerthought.org>.
Jeff Turner wrote:
> http://outerthought.net/wiki/Wiki.jsp?page=FileGeneratorManPage
Jeff, the wiki has been moved to http://wiki.cocoondev.org/ for quite
some time now. The new location of that document is
http://wiki.cocoondev.org/Wiki.jsp?page=FileGeneratorManPage.
If someone knows enough mod_rewrite to make that an automated redirect,
please speak up (I'm being lazy).
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
Read my weblog at http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org stevenn at apache.org
Re: [ANN]JavaDoc generation using Cocoon
Posted by "Peter B. West" <pb...@powerup.com.au>.
Nicola,
After all of the breathless excitement, where do I get JavaSRc?
Peter
Nicola Ken Barozzi wrote:
>
>
> Something like this?
> http://jakarta.apache.org/poi/javadocs/javasrc/
>
> JavaSRc has been donated to Apache. We can use it to precreate these
> docs in a much faster way and using less memory.
>
> We can then add a "javasrc:" scheme to link to the java files, to the
> appropriate method.
--
Peter B. West pbwest@powerup.com.au http://www.powerup.com.au/~pbwest/
"Lord, to whom shall we go?"
Re: [ANN]JavaDoc generation using Cocoon
Posted by "Peter B. West" <pb...@powerup.com.au>.
Nicola Ken Barozzi wrote:
>
>
> Peter B. West wrote:
>
>>
>> Any Forrest volunteers for generating full htmlized Java source files,
>> including ids for methods and data structures? Documentation can then
>> at least have a reference to the latest version of the source, without
>> requiring modifications while the targets remain the same.
>
>
> Something like this?
> http://jakarta.apache.org/poi/javadocs/javasrc/
>
> JavaSRc has been donated to Apache. We can use it to precreate these
> docs in a much faster way and using less memory.
A big sloppy kiss on each cheek for Nicola! *SMACK* *SMACK* It's gorgeous.
> We can then add a "javasrc:" scheme to link to the java files, to the
> appropriate method.
>
> I don't know if having the output of the java source is a good idea;
> neat indeed, but it creates out-of-sync versions of the docs, and I
> don't see the source I am talking about.
If I am trying to document the current source, I want to show it. If I
fall behind with my descriptive documentation, be it on my head. At
least the build can faithfully create the current source with make-up,
which is one less (major) element I don't have to worry about when
writing my documentation. If I use line-number references, I will get
into trouble quickly, but method and field references will be more stable.
> Also, usually we never inline live code in the docs, just examples.
> References-links instead to real source code are used a lot.
>
Inline is exactly where I want the code. I want the reader of my
documentation to see the code of method frobnicate() right alongside my
description of it, and where it fits into the grand scheme of things.
Which brings me to the subject of frames. I tried to use inline frames
for code, but found that they were badly-behaved under resizing, when
used with Mozilla. I fell back to standard frames. In the long run,
inlines would be the go, and would play much better with Forrest, I
imagine. There may be a clean way to integrate frames with Forrest,
but, not being a Forrest developer, only a mere user, and wishing to
abide by a strict SoC, I will await advice. In the meantime I will
slash and burn as necessary. The results so far are not pretty.
Peter
--
Peter B. West pbwest@powerup.com.au http://www.powerup.com.au/~pbwest/
"Lord, to whom shall we go?"
Re: [ANN]JavaDoc generation using Cocoon
Posted by Stephan Michels <st...@apache.org>.
On Sat, 25 Jan 2003, Nicola Ken Barozzi wrote:
>
>
> Peter B. West wrote:
>
> >
> > Any Forrest volunteers for generating full htmlized Java source files,
> > including ids for methods and data structures? Documentation can then
> > at least have a reference to the latest version of the source, without
> > requiring modifications while the targets remain the same.
>
> Something like this?
> http://jakarta.apache.org/poi/javadocs/javasrc/
>
> JavaSRc has been donated to Apache. We can use it to precreate these
> docs in a much faster way and using less memory.
Just for a comment, the lexer of the Chaperon project is very lightwight,
but the parser is a other thing, it's like the little birds and big
cannonballs ;-)
The Chaperon parser helps you to parse every text document, which can be
described with a context free grammar, like Java, ANSI C, Fortran, Wiki.
With a special technique, you can also parse non context free formats
like XML.
For a CSV format I wouldn't use the chaperon parser ;-)
Stephan Michels.
Re: [ANN]JavaDoc generation using Cocoon
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Peter B. West wrote:
>
> Any Forrest volunteers for generating full htmlized Java source files,
> including ids for methods and data structures? Documentation can then
> at least have a reference to the latest version of the source, without
> requiring modifications while the targets remain the same.
Something like this?
http://jakarta.apache.org/poi/javadocs/javasrc/
JavaSRc has been donated to Apache. We can use it to precreate these
docs in a much faster way and using less memory.
We can then add a "javasrc:" scheme to link to the java files, to the
appropriate method.
I don't know if having the output of the java source is a good idea;
neat indeed, but it creates out-of-sync versions of the docs, and I
don't see the source I am talking about.
Also, usually we never inline live code in the docs, just examples.
References-links instead to real source code are used a lot.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [ANN]JavaDoc generation using Cocoon
Posted by "Peter B. West" <pb...@powerup.com.au>.
Stephan Michels wrote:
>
> On Sat, 25 Jan 2003, Jeff Turner wrote:
>
>
>>On Thu, Jan 23, 2003 at 04:45:31PM +0100, Stephan Michels wrote:
>>
....
>
>>>I have made a webapp as example for my Chaperon parser, which
>>>generates documentation sites for source code similar to JavaDoc.
>>>
>>>http://vern.chem.tu-berlin.de/~stephan/chaperon/net/sourceforge/chaperon/adapter/cocoon/ParserTransformer.class.html
>>>
>>>http://vern.chem.tu-berlin.de/~stephan/chaperon/net/sourceforge/chaperon/adapter/cocoon/ParserTransformer.java.html
>>
....
>
>>Any Forrest volunteers to implement a colourizer for inline code
>>snippets?
>>
>><source type="java">
>> public void foo() {
>> System.out.println("colourize me!");
>> }
>></source>
>
>
> Should not be difficult.
> There are three stages to do.
>
> 1.Mark text for the LexicalTransformer.
> 2.The LexicalTransformer 'tokenize' the text, using a lexicon file.
> 3.Change to the tokens into <font>...</font>, whatever.
>
> This can also be done for XML.
Any Forrest volunteers for generating full htmlized Java source files,
including ids for methods and data structures? Documentation can then
at least have a reference to the latest version of the source, without
requiring modifications while the targets remain the same.
Peter
--
Peter B. West pbwest@powerup.com.au http://www.powerup.com.au/~pbwest/
"Lord, to whom shall we go?"
Re: [ANN]JavaDoc generation using Cocoon
Posted by Stephan Michels <st...@apache.org>.
On Sat, 25 Jan 2003, Jeff Turner wrote:
> On Thu, Jan 23, 2003 at 04:45:31PM +0100, Stephan Michels wrote:
> > Hi,
> >
> > first of all, I want thank you for your great work at forrest. I'm
> > now using it for my documentation(http://chaperon.sourceforge.net/).
>
> Nice :)
>
> Mind if we add it to the 'live sites' page?
Why not.
> > I have made a webapp as example for my Chaperon parser, which
> > generates documentation sites for source code similar to JavaDoc.
> >
> > http://vern.chem.tu-berlin.de/~stephan/chaperon/net/sourceforge/chaperon/adapter/cocoon/ParserTransformer.class.html
> >
> > http://vern.chem.tu-berlin.de/~stephan/chaperon/net/sourceforge/chaperon/adapter/cocoon/ParserTransformer.java.html
>
> Wow.. impressive!
Thanks.
> Any Forrest volunteers to implement a colourizer for inline code
> snippets?
>
> <source type="java">
> public void foo() {
> System.out.println("colourize me!");
> }
> </source>
Should not be difficult.
There are three stages to do.
1.Mark text for the LexicalTransformer.
2.The LexicalTransformer 'tokenize' the text, using a lexicon file.
3.Change to the tokens into <font>...</font>, whatever.
This can also be done for XML.
Stephan Michels.