Review request: New man page files (original) (raw)

Stuart Marks stuart.marks at oracle.com
Tue Jun 25 17:27:48 PDT 2013

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

More information about the jdk7u-dev mailing list