Review request for JDK-8016767: Provide man pages generated from DARB for OpenJDK

[Stuart Marks]

Hi Alexey,

The new man pages are a big improvement over the previous ones.

There are still a number of formatting issues that need to be corrected, but 
these can be postponed until later, as I understand the difficulties of trying 
to fix up the toolchain under a release deadline.

I think I may have mentioned this in a different review thread, but I'll 
mention some issues here so that we can revisit them in the future when we have 
more time to work on the toolchain.

1. Indentation is now too large, whereas previously it was negative. I think 
some pairs of .RS .RE can be removed. This is mainly around options listings.

2. En-dash markup \- is used in a bunch of places where a bare hyphen - is 
appropriate.

3. The tags for the tagged paragraphs description options, e.g. -client, 
-server, -classpath, -d32 should be emboldened. Where text is a placeholder to 
be filled in, e.g. -Dproperty=value, "property" and "value" should be italicized.

4. Formatting in the example under -agentlib:libname[=options] could use work. 
Less spacing between the lines, and more spacing before and after.

5. Occasional unnecessarily repeated .LP directives. Unnecessary .fl and .br 
directives.

6. Use of 'o' instead of \(bu for bullet items.

Again, it seems sensible to proceed with the man pages as they stand, and to 
work on fixing up these finer points of markup for future releases.

s'marks



On 7/18/13 3:46 AM, alexey zhebel wrote:
> Thanks to Mikael, Joe, and Stuart for the previous reviews and feedback!
>
> We generated the fixed versions of the two man pages (java and jcmd). The
> copyright and license text has been corrected and several formatting issues
> have been fixed. Due to constraints within the tool chain and release
> deadlines, other remaining issues will be discussed and resolved later.
>
> Please review the pages.
>
> The webrev is located here:
> http://cr.openjdk.java.net/~azhebel/8016767/
>
> And here is the bug if you need it:
> https://jbs.oracle.com/bugs/browse/JDK-8016767
>