Documentation, man pages, updates and sources (Was: On ecj and @Override annotations for interface methods)

[Mark Wielaard]

Hi Joe,

On Thu, 2008-10-02 at 22:34 -0700, Joseph D. Darcy wrote:
> Mark Wielaard wrote:
> > On Tue, 2008-09-23 at 07:12 -0700, Joseph D. Darcy wrote:
> >   
> >>> Are these manpages written by hand these days? It has a comment that
> >>> says: "Generated by html2man", but it doesn't say what the original html
> >>> file is that it was generated from.
> >>>       
> >> The process used in the past for man pages was that the docs team works 
> >> with us developers to write the HTML man pages, which are in turn 
> >> converted to SGML and *roff for Solaris and Linux, respectively.  It 
> >> looks like the last update to the HTML page, 6392810 "javac manpage 
> >> needs to be updated to include JSR 269 and other Mustang options," did 
> >> not get converted to the other formats.  If the actual *nix man pages, 
> >> regardless of format, are supposed to be generated in this fashion, it 
> >> would admittedly be a better architecture to have them as generated 
> >> files during the build and not track all three versions of the man page 
> >> under version control.
> >
> > So if the preferred form of the for making modifications to these
> > documents is the HTML or SGML version that the doc team maintains it
> > would be good to get those in the openjdk tree. 
> 
> Agreed.
> 
> > Does the documentation
> > team maintain their own repository for these documents?
>
> Yes; at the moment there is a Sun-internal-only repository for these 
> documents.  IMO, at least the master manpages should be moved to a 
> public repository for JDK 7 and the build rearranged so that the *roff 
> and SGML files are generated and not separated tracked under version 
> control.  I'll broach this with the docs team for later in JDK 7.

Any progress on this?

I saw the following Fedora bug report:
"wsgen man page errors"
https://bugzilla.redhat.com/show_bug.cgi?id=477700
As the comments explain that is really hard to fix without the
corresponding source code of the manual pages available.

Thanks,

Mark