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
