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

[Dr Andrew John Hughes]

On 13:15 Mon 13 Sep     , Omair Majid wrote:
> On 06/17/2009 02:23 PM, Joseph D. Darcy wrote:
> > Mark Wielaard wrote:
> >> 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?
> >
> > Not yet. However, the raw HTML sources are generally what are published
> > for pages like
> >
> > http://download.java.net/jdk7/docs/technotes/tools/share/wsgen.html
> >
> >> I saw the following Fedora bug report:
> >> "wsgen man page errors"t y
> >> 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
> >
> > I've forwarded this bug in the html -> man conversion process to the
> > docs team.
> >
> > -Joe
> >
> 
> Any updates on this? The latest version of the man pages still have this 
> bug.
> 
> Perhaps the html2man tool being used by the docs team can be made 
> available to the public? I am sure someone in the community will step up 
> to fix it and make sure the man pages are generated during the build.
> 
> Thanks,
> Omair

As not much progress seems to have been made on this, and HTML is not an ideal
format for the source document anyway, the most expidient solution would seem
to be to create new source documents from the GPLed man files we do have.  

I'd suggest texinfo as a possible source format.  It seems to be widely supported
as both a source and destination format (http://www.gnu.org/software/texinfo/)
and the tools seem to be readily available on both GNU/Linux and OpenSolaris.
-- 
Andrew :)

Free Java Software Engineer
Red Hat, Inc. (http://www.redhat.com)

Support Free Java!
Contribute to GNU Classpath and the OpenJDK
http://www.gnu.org/software/classpath
http://openjdk.java.net
PGP Key: 94EFD9D8 (http://subkeys.pgp.net)
Fingerprint = F8EF F1EA 401E 2E60 15FA  7927 142C 2591 94EF D9D8