Review request: New man page files

[Stuart Marks]

On 6/18/13 12:49 AM, alexey zhebel wrote:
> We are moving to a new process for generating man pages. I checked in the two
> that changed for 7u40 (java and jcmd):
> http://cr.openjdk.java.net/~azhebel/8016767/
>
> Please review.
>
> Note that the copyright/license information format was approved by Donald Smith
> who worked with legal.

Hi, I have some comments about the roff markup that's in these generated man 
pages. The formatting that's inconsistent with more typical man pages.

The formatting is easier to see given the typeset roff output. I've uploaded 
the typeset version of a grep man page [1] as an example of a typical formatted 
man page. I also formatted the java.1 man page as proposed by this webrev [2]. 
Please refer to these versions when reading these comments.

Source lines cited below are from the "new" version of src/linux/doc/man/java.1.

-------

   30 .pl 99999

This sets the page length to a large number, so that there are no page breaks 
when the man page is displayed by nroff in a terminal. Unfortunately it seems 
to cause problems with page breaks in the typeset output [2] so the text simply 
runs off the bottom of the first page. I recommend this instead:

      .if n .pl 99999

so that this is done for nroff only.

-------

   31 .TH java 1 "6 August 2013" "JDK 7" "Basic Tools"

The command name is conventionally written in all caps, though this convention 
isn't universally followed. But I'd recommend:

      .TH JAVA 1 "6 August 2013" "JDK 7" "Basic Tools"

-------

   53 java \- Launches a Java application\&.

The description in the NAME section is typically a sentence fragment, not 
capitalized, with no period. I'd recommend:

      java \- launches a Java application

-------

   56 java [ \fIoptions\fR ] class [ \fIargument \&.\&.\&.\fR ]
   59 java [ \fIoptions\fR ] \-jar file\&.jar [ \fIargument \&.\&.\&.\fR ]

Conventionally the command name, options, and keywords that are actually typed 
are in boldface, whereas names of things to be substituted with something else 
in the actual command in are in italics. Thus these would change to

      \fBjava\fR [ \fIoptions\fR ] \fIclass\fR [ \fIargument \&.\&.\&.\fR ]
      \fBjava\fR [ \fIoptions\fR ] \fB\-jar\fR \fIfile\&.jar\fR [ \fIargument 
\&.\&.\&.\fR ]

-------

   63 Command-line options\&. See Options \&.

There's a space between the last word and the \&. This is visible in the 
typeset output. This occurs in several other locations.

Since "Options" is a reference to a section, it should probably be bolded.

A \& appears to occur before every . character. Not clear why this is the case, 
though it doesn't necessarily do any harm.

      Command-line options\&. See \fBOptions\fR\&.


-------

   65 class
   69 The name of the JAR file to be called\&. Used only with the \fI-jar\fR 
command\&.
   74 The \fIjava\fR command starts a Java application\&. It does this ...

The word "class" needs to be in italics. The word "-jar" and the "java" command 
name should be in bold. Also, should probably use an en-dash for consistency.

      \fIclass\fR

      The name of the JAR file to be called\&. Used only with the \fB\-jar\fR 
command\&.

      The \fBjava\fR command starts a Java application\&. It does this ...

There are similar formatting issues throughout. I won't list them all.

-------

   77 .nf
   78 public static void main(String args[]
   79 .fi
   80 .nf
   81 .fi

Missing close paren. Also this uses the anachonistic form of arrays, where the 
brackets follow the argument name, instead of the preferred formatting of 
having the brackets follow the type. There are extra .nf/.fi pairs here and 
elsewhere in the file. Probably also want to indent this code example and add 
blank lines. Suggest:

      .RS
      .nf

      public static void main(String[] args)

      .fi
      .RE

-------

The "OPTIONS" section is very short and is introduced with a .SH (section 
heading) directive. What follow are two large subsections "STANDARD OPTIONS" 
and "NONSTANDARD OPTIONS". These are introduced with .SS (subsection) 
directives and are formatted completely differently:

   91 .SS STANDARD\ OPTIONS
   92 .RE
   93 .PP
   94 -client
   95 .RS 4
   96 Selects the Java HotSpot VM client\&. ...

I think the intent is for these subsections to be nested within the main 
OPTIONS section. While logically proper, textual documents do not lend 
themselves to large-scale block structure. I'd recommend simply having the 
STANDARD OPTIONS and NONSTANDARD OPTIONS as top-level sections introduced with 
.SH, using the usual .TP directives to introduce tagged paragraphs, which is 
typical for options. In addition, this section is malformatted, probably caused 
by the reveral of the .RE and .RS directives. The .RS directive starts an 
indent level and .RE ends it. These are reversed so it seems to end up 
"outdenting" instead. Finally, options should be embolded and should use 
en-dash. This results in:

      .SH STANDARD\ OPTIONS
      .TP
      \fB\-client\fR
      Selects the Java HotSpot VM client\&. ...

The remaining options should be reformatted similarly.

-------

I've modified the markup by hand and reformatted it. The output is visible at 
[3]. (I've only applied the mods to the first page.)

Yours for better 1970s typesetting technology. :-)

s'marks


[1] http://cr.openjdk.java.net/~smarks/images/grep.pdf

[2] http://cr.openjdk.java.net/~smarks/images/java.orig.pdf

[3] http://cr.openjdk.java.net/~smarks/images/java.mod.pdf