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

[Joseph D. Darcy]

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