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

[Joe Darcy]

On 07/19/2013 03:39 PM, Stuart Marks wrote:
> 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.

I agree that is a reasonable way to proceed.

Cheers,

-Joe