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

[Joe Darcy]

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.

No, unfortunately no progress on this to report yet.

-Joe