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

[Omair Majid]

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