xml doclet?

["Nick Wesselman, @home" <ni...@usa.net>]

I'm a moderately experienced Java developer who's interested in the xml
doclet that's part of the Cocoon project. It would be very helpful for a
personal project of mine, so I'd like to offer my help on it.

What is the current status of the doclet? Has anything been done for it
since the revision posted in March (1.1)? It seems that the mini-project
could use the following work, based on the source & what discussions on it I
could dig up:

--implementation of XML namespaces for HTML and other tags within the
documentation
--addition of command-line options to specify this namespace and other
details, such as the output target
--support for packages within packages?
--support for new 1.3 @docRoot?

Maybe some of this has already been done and I'm not aware? Archived
messages from October discussed the use of namespaces, yet from what I can
tell they don't seem to be fully implemented yet.

Thanks!!!

Nick

Re: xml doclet?

[Hans Ulrich Niedermann <ni...@isd.uni-stuttgart.de>]

Stefano Mazzocchi <st...@apache.org> writes:

[ XML doclets ]

> No, I was going to write a stylesheet for the generated doclet DTD to
> output the javadocs in a way that looks seemless with our xml.apache.org
> stylesheets but never found the time to do it.
> 
> Having all documentation (including javadocs) with a common look and
> feel would be killer.

Ahem. How does this connect with the planned doc format transition to
Docbook? What will the future docs look like now?

a) doclet   -> apache-style HTML
   document -> apache-style HTML
   docbook  -> docbook-style HTML

b) doclet   -> docbook
   document -> docbook
               docbook -> apache-style HTML

c) whatever?

Uli

Re: xml doclet?

["Nick Wesselman, @home" <ni...@usa.net>]

> One thing I would like to see in a XMLDoclet is that a
> seperate file is created for each class. So from
> com/biz/MyClass.java you end up with
> com/biz/MyClass.xdoc.

Sounds reasonable to me--but how would this effect the DTD? Are there any
kind of specs/guidelines for XML structure accross multiple files? Maybe
this solution would require separate DTDs for doc structure and specific
class info? I must admit ignorance here.

> This means you have to deal with less
> monolithic xml files and it also means you can easily merge
> multiple source trees. (Ie you javadoc org.apache.cocoon and
> org.apache.avalon seperatly but just copy *.xdoc to same
> base and they are the same as if run full belt). This has
> other benefits too. You can limit the number of packages
> javadoced by just comparing timestamps of xdoc vs java for
> each file in package and if any are changed then need to
> redoo package and update said classes. This could also be
> very good if combined with alexandria project.

Could someone send me some info on what exactly the alexandria project is?

Nick

Re: xml doclet?

[do...@mad.scientist.com]

Hi,

One thing I would like to see in a XMLDoclet is that a
seperate file is created for each class. So from
com/biz/MyClass.java you end up with
com/biz/MyClass.xdoc. This means you have to deal with less
monolithic xml files and it also means you can easily merge
multiple source trees. (Ie you javadoc org.apache.cocoon and
org.apache.avalon seperatly but just copy *.xdoc to same
base and they are the same as if run full belt). This has
other benefits too. You can limit the number of packages
javadoced by just comparing timestamps of xdoc vs java for
each file in package and if any are changed then need to
redoo package and update said classes. This could also be
very good if combined with alexandria project.

I tried this once but failed as I knew nothing of XSL but I
would be very very very appreciative of functionality
similar :P

Cheers,

Pete

*--------------------------------------------------*
| Latrobe University,     |                        |
| Bundoora, Australia     | Does the name 'Pavlov' |
| Office: PW220           |    ring a bell ?       |
| Ex: 2503                |                        |
*--------------------------------------------------*

Re: xml doclet?

[Stefano Mazzocchi <st...@apache.org>]

"Nick Wesselman, @home" wrote:
> 
> I'm a moderately experienced Java developer who's interested in the xml
> doclet that's part of the Cocoon project. It would be very helpful for a
> personal project of mine, so I'd like to offer my help on it.

Great, welcome aboard.
 
> What is the current status of the doclet?

Idle, nobody has been working on it since it was donated. The original
author left the project due to lack of time.

> Has anything been done for it since the revision posted in March (1.1)? 

Not that I know about.

> It seems that the mini-project
> could use the following work, based on the source & what discussions on it I
> could dig up:
> 
> --implementation of XML namespaces for HTML and other tags within the
> documentation

correct

> --addition of command-line options to specify this namespace and other
> details, such as the output target

yes

> --support for packages within packages?

Uh, didn't know this one but I didn't dive into it that deeply.

> --support for new 1.3 @docRoot?

good
 
> Maybe some of this has already been done and I'm not aware? Archived
> messages from October discussed the use of namespaces, yet from what I can
> tell they don't seem to be fully implemented yet.

No, I was going to write a stylesheet for the generated doclet DTD to
output the javadocs in a way that looks seemless with our xml.apache.org
stylesheets but never found the time to do it.

Having all documentation (including javadocs) with a common look and
feel would be killer.

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