Review of OpenJDK Java tools nroff documentation

[raymond gallardo]

Hello Reviewers,

As part of the OpenJDK review processes, the OpenJDK 8 nroff files for 
Java tools are up for review, which are attached as a zip file.

Please provide your feedback by Monday November 18th, 2013.

The following sections describe what kinds of review comments we're 
looking for and what has changed for JDK 8. Please contact us if you 
have any questions.

     Scope of Review
     Provide Feedback
     How to View a Man Page
     What's Changed
     Summary of Changes

Scope of Review

Please provide a sanity check of content as opposed to reviewing the 
nroff markup itself.

A line-by-line comparison between the html and nroff versions is not needed.
Provide Feedback

Please indicate your approval and provide feedback by e-mail by Monday, 
November 18th, 2013.

All feedback will be triaged. Severe technical inaccuracies and other 
small bugs will be fixed. Due to JDK 8 release plan deadlines, bugs will 
be filed for large scale changes and will most likely be handled in a 
future update release.
How To View A Man Page

1.  Retrieve the file jdk_nroff_nov_11/openjdk_nroff_nov_11.zip from the 
server cr.openjdk.java.net via a secure method secure methods (rsync, 
scp, and sftp). For more information, see 
http://openjdk.java.net/guide/codeReview.html.

     Download this file to a directory of your choice.

2.  Open a terminal window. Change to the directory that contains the 
zip file.

3.  Extract the contents of the zip file as follows:

     $ unzip openjdk_nroff_nov_11.zip

     This creates a sub-directory named openjdk_nroff_nov_11 in the 
current directory.

4.  Change directory to openjdk_nroff_nov_11 as follows:

     $ cd openjdk_nroff_nov_11

5.  View a man page with a command of the following form:

     $ man -M man <page name>

     For example, to view the javap man page, run the following command:

     $ man -M man javap

Notes

     (Linux and Mac only.) The -t option to the man command will 
generate typeset output in PostScript format and send it to stdout:

     $ man -M man -t javap > javap.ps

     PostScript can be displayed using Preview (on Mac) and by the Gnome 
Document Viewer (Linux/Gnome). (On Solaris, the man -t option will send 
the output to a printer, which might not be what you want.)

     If bullets render as a funny character, set the remote character 
set to UTF-8. For example, if you are using PuTTY, an SSH and telnet 
client, you can specify the remote character set by selecting from the 
context menu Change Settings... > Window > Translation > Remote 
character set > UTF-8.

What's Changed

     A new nroff generator is being used to generate the nroff man pages 
for Java tools documentation. Consequently, the diff between JDK 7 and 
JDK 8 man pages will be considerably different. A webrev will be 
meaningless and has thus not been provided for this review.
     All tools pages have gone through an editorial review.
     Technical content changes related to JDK 8 features have been made. 
These changes have already been reviewed by the engineer responsible for 
each feature.
     HTML documentation for Java tools has also been generated, which 
has the same content as the nroff files up for review, and which will be 
available on download.java.net.

Summary of Changes

The following lists significant changes for each Java tool nroff page:
Basic

     appletviewer
         Removed references to "Classic VM", replaced with "JVM" where 
applicable.
     apt
         Removed fro JDK 8
     jar
         Removed references to "Classic VM", replaced with "JVM" where 
applicable.
         Compact Profiles
     java
         Completely reworked.
         -XX:UseStringCache deprecated
         JDK-6453675 Request for documentation of 
-XX:+PrintTenuringDistribution output
         JFR options: -XX:+FlightRecorder -XX:StartFlightRecording 
-XX:FlightRecorderOptions
         MaxFDLimit option
         Added serviceability options
         Added garbage collection options
         Non-Standard options
         Modified structure (General/Advanced Options). Added info about 
launching JavaFX
         Changed -XX:{+|-}OptionName to -XX:+OptionName
         Method Parameter Reflection
     javac
         Xdoclint
         Method Parameter Reflection
         Compact Profiles (-profile)
         Bug JDK-8023877
     javadoc
         Removed info that it prints an error to add parentheses and 
arguments to a method name.
         Replaced reference to DocCheck with a reference to javadoc 
-Xdoclint.
         Javadoc Access API
         Doclint
     pack200
         fixed two option variants in one Term
     extcheck, javah, javap, jdb, pack200, unpack200
         No significant changes

IDL

     servertool
         Added missing information about ORBInitialPort
     idlj, orbd, tnameserv
         No significant changes

Internationalization

     native2ascii
         No significant changes

Monitoring

     jstat
         JDK-8006740: removal of the permanent generation in HotSpot.
     jcmd
         Completely reworked.
         JDK-8016282: Docs for [jcmd] recording name with spaces can not 
be just surrounded with \" \" or \' \'
     jmc
         New tool in 7u40, not changed for jdk8.
         Removed from OpenJDK versions of tools pages
     jps, jstatd
         No significant changes

Nashorn

     jjs
         New tool in jdk8.
         Added options

RMI

     rmic, rmid
         Some updates
     rmiregistry, serialver
         No significant changes

Scripting

     jrunscript
         No significant changes

Security

     jarsigner
         JDK-8024302: Clarify jar verifications
         JDK-8009636: Added -tsapolicyid option
         JDK-8025927: tool doc change for 8024402 and 8023338 (affects 
jarsigner)
     keytool
         JDK-8010125 keytool -importkeystore could create a pkcs12 
keystore with different storepass and keypass
         (JDK-8025941) keytool docs change due to 8008296. Added the new 
-importpassword command
     policytool
         No significant changes

Troubleshooting

     jmap
         JDK-8010507 The option -permstat for jmap has been renamed to 
-clstats
         JDK-7199147. Moved description of interned Strings to -heap option.
     jconsole, jhat, jinfo, jsadebugd, jstack
         No significant changes

Web Services

     schemagen, wsgen, wsimport, xjc
         No significant changes

Web Start

     javaws
         Added note that this command is not available on Oracle Solaris

Additional New Features

     jvisualvm
         New feature
     jdeps
         Compact Profiles
         Updated examples on jdeps

Thank you,

The Java SE 8 Documentation Team