sinjdoc vs gjdoc

[Mark Wielaard]

Hi,

I am happy to see sinjdoc in Fedora rawhide. And I used that package to
create a generic version of the classpath docs:
http://developer.classpath.org/sinjdoc/
But as you can see it is not as nicely looking (imho of course) as the
old gjdoc version: http://developer.classpath.org/doc/
Also it doesn't seem to do highlighted source code linking, a feature I
really like in gjdoc.

So for non-generic/1.5 code I would like to have gjdoc still around, but
is seems sinjdoc actually replaces gjdoc. Does it have to?

Thanks,

Mark

[Andrew Haley]

Mark Wielaard writes:

>  I am happy to see sinjdoc in Fedora rawhide. And I used that package
> to
>  create a generic version of the classpath docs:
>  http://developer.classpath.org/sinjdoc/
>  But as you can see it is not as nicely looking (imho of course) as the
>  old gjdoc version: http://developer.classpath.org/doc/
>  Also it doesn't seem to do highlighted source code linking, a feature I
>  really like in gjdoc.
>  
>  So for non-generic/1.5 code I would like to have gjdoc still around, but
>  is seems sinjdoc actually replaces gjdoc. Does it have to? 
I think so.  If I didn't like the look of sinjdoc ouput I'd write a
patch for it.

Andrew.

-- 
Red Hat UK Ltd, Amberley Place, 107-111 Peascod Street, Windsor, Berkshire, SL4 1TE, UK
Registered in England and Wales No. 3798903

[Mark Wielaard]

On Fri, 2007-04-06 at 11:14 +0100, Andrew Haley wrote:
>  Mark Wielaard writes:
>   > So for non-generic/1.5 code I would like to have gjdoc still around, but
>   > is seems sinjdoc actually replaces gjdoc. Does it have to?
>  
>  I think so.  If I didn't like the look of sinjdoc ouput I'd write a
>  patch for it. 
Sure, I assume you are fine with the default look of the sinjdoc output
then. But it isn't just the look, sinjdoc doesn't support a couple of
features from gjdoc, like the -linksource, -licensetext, -validhtml,
@Link support in comments, etc. So it isn't just a trivial patchlet to
get all the things back.

Cheers,

Mark

[Andrew Haley]

Mark Wielaard writes:
>  On Fri, 2007-04-06 at 11:14 +0100, Andrew Haley wrote:
>  > Mark Wielaard writes:
>  >  > So for non-generic/1.5 code I would like to have gjdoc still around, but
>  >  > is seems sinjdoc actually replaces gjdoc. Does it have to?
>  > 
>  > I think so.  If I didn't like the look of sinjdoc ouput I'd write a
>  > patch for it.
>  
>  Sure, I assume you are fine with the default look of the sinjdoc output
>  then. But it isn't just the look, sinjdoc doesn't support a couple of
>  features from gjdoc, like the -linksource, -licensetext, -validhtml,
>  @Link support in comments, etc. So it isn't just a trivial patchlet to
>  get all the things back. 
Well let's fix it then.  Continuing to maintain gjdoc is not a plan.

Andrew.

-- 
Red Hat UK Ltd, Amberley Place, 107-111 Peascod Street, Windsor, Berkshire, SL4 1TE, UK
Registered in England and Wales No. 3798903

[Thomas Fitzsimmons]

Mark Wielaard wrote:
>  Hi,
>  
>  I am happy to see sinjdoc in Fedora rawhide. And I used that package to
>  create a generic version of the classpath docs:
>  http://developer.classpath.org/sinjdoc/
>  But as you can see it is not as nicely looking (imho of course) as the
>  old gjdoc version: http://developer.classpath.org/doc/
>  Also it doesn't seem to do highlighted source code linking, a feature I
>  really like in gjdoc.
>  
>  So for non-generic/1.5 code I would like to have gjdoc still around, but
>  is seems sinjdoc actually replaces gjdoc. Does it have to? 
Not necessarily.  But Andrew Overholt, the Fedora maintainer of gjdoc, wanted to 
drop it from the distribution so that he wouldn't have to maintain it anymore. 
But it could be re-introduced as a new package in Fedora Extras.

But instead of keeping gjdoc, I'd prefer to see sinjdoc's output improved to 
match gjdoc's, and highlighted source code linking support added to it, in the 
interests of limiting maintenance overhead (plus it's simpler to point people at 
one free javadoc solution).

Tom

[Tom Tromey]

> >>>> "Tom" == Thomas Fitzsimmons
> <fitzsim(a)redhat.com&gt; writes: 
Tom> But instead of keeping gjdoc, I'd prefer to see sinjdoc's output
Tom> improved to match gjdoc's, and highlighted source code linking support
Tom> added to it, in the interests of limiting maintenance overhead (plus
Tom> it's simpler to point people at one free javadoc solution).

I think that the real issue isn't what we do in Fedora, but that gjdoc
is more or less unmaintained upstream.  So, while we were upgrading
the whole toolchain to deal with Java 5, gjdoc got left behind.  Then
we had to find the cheapest way to pick up the pieces ... not very fun
and not the best results :(

Longer term I suppose OpenJDK will be opening their javadoc "soon".

Tom