Review of OpenJDK Java tools nroff documentation

Kumar Srinivasan kumar.x.srinivasan at oracle.com
Tue Nov 12 09:21:11 PST 2013


I looked at java(1), pack200(1) and unpack200(1), I also glossed
over javac(1), javap(1), javadoc(1) and javah(1) on Solaris, and I
could not find anything wrong.

Of course on Solaris there is the  line-break issue bug with man(1),
I take it someone from TechPubs will file a bug against Solaris.

Kumar

On 11/11/2013 10:18 AM, raymond gallardo wrote:
>
> 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
>     <imap://kumar%2Esrinivasan%40oracle%2Ecom@stbeehive.oracle.com:993/fetch%3EUID%3E/java.net/discuss%3E2155?header=quotebody&part=1.1.2.2&filename=External_review_november_11.html>
>   * Provide Feedback
>     <imap://kumar%2Esrinivasan%40oracle%2Ecom@stbeehive.oracle.com:993/fetch%3EUID%3E/java.net/discuss%3E2155?header=quotebody&part=1.1.2.3&filename=External_review_november_11.html>
>   * How to View a Man Page
>     <imap://kumar%2Esrinivasan%40oracle%2Ecom@stbeehive.oracle.com:993/fetch%3EUID%3E/java.net/discuss%3E2155?header=quotebody&part=1.1.2.4&filename=External_review_november_11.html>
>   * What's Changed
>     <imap://kumar%2Esrinivasan%40oracle%2Ecom@stbeehive.oracle.com:993/fetch%3EUID%3E/java.net/discuss%3E2155?header=quotebody&part=1.1.2.5&filename=External_review_november_11.html>
>   * Summary of Changes
>     <imap://kumar%2Esrinivasan%40oracle%2Ecom@stbeehive.oracle.com:993/fetch%3EUID%3E/java.net/discuss%3E2155?header=quotebody&part=1.1.2.6&filename=External_review_november_11.html>
>
>
>     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.
>
>     Download the |openjdk_nroff_nov_11.zip| file to a directory of
>     your choice. (The exact zip file name will vary depending upon the
>     exact man page bundle and creation date.)
>
> 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
>       o Removed references to "Classic VM", replaced with "JVM" where
>         applicable.
>   * apt
>       o Removed fro JDK 8
>   * jar
>       o Removed references to "Classic VM", replaced with "JVM" where
>         applicable.
>       o Compact Profiles
>   * java
>       o Completely reworked.
>       o -XX:UseStringCache deprecated
>       o JDK-6453675 Request for documentation of
>         -XX:+PrintTenuringDistribution output
>       o JFR options: -XX:+FlightRecorder -XX:StartFlightRecording
>         -XX:FlightRecorderOptions
>       o MaxFDLimit option
>       o Added serviceability options
>       o Added garbage collection options
>       o Non-Standard options
>       o Modified structure (General/Advanced Options). Added info
>         about launching JavaFX
>       o Changed -XX:{+|-}OptionName to -XX:+OptionName
>       o Method Parameter Reflection
>   * javac
>       o Xdoclint
>       o Method Parameter Reflection
>       o Compact Profiles (-profile)
>       o Bug JDK-8023877
>   * javadoc
>       o Removed info that it prints an error to add parentheses and
>         arguments to a method name.
>       o Replaced reference to DocCheck with a reference to javadoc
>         -Xdoclint.
>       o Javadoc Access API
>       o Doclint
>   * pack200
>       o fixed two option variants in one Term
>   * extcheck, javah, javap, jdb, pack200, unpack200
>       o No significant changes
>
>
>       IDL
>
>   * servertool
>       o Added missing information about ORBInitialPort
>   * idlj, orbd, tnameserv
>       o No significant changes
>
>
>       Internationalization
>
>   * native2ascii
>       o No significant changes
>
>
>       Monitoring
>
>   * jstat
>       o JDK-8006740: removal of the permanent generation in HotSpot.
>   * jcmd
>       o Completely reworked.
>       o JDK-8016282: Docs for [jcmd] recording name with spaces can
>         not be just surrounded with \" \" or \' \'
>   * jmc
>       o New tool in 7u40, not changed for jdk8.
>       o Removed from OpenJDK versions of tools pages
>   * jps, jstatd
>       o No significant changes
>
>
>       Nashorn
>
>   * jjs
>       o New tool in jdk8.
>       o Added options
>
>
>       RMI
>
>   * rmic, rmid
>       o Some updates
>   * rmiregistry, serialver
>       o No significant changes
>
>
>       Scripting
>
>   * jrunscript
>       o No significant changes
>
>
>       Security
>
>   * jarsigner
>       o JDK-8024302: Clarify jar verifications
>       o JDK-8009636: Added -tsapolicyid option
>       o JDK-8025927: tool doc change for 8024402 and 8023338 (affects
>         jarsigner)
>   * keytool
>       o JDK-8010125 keytool -importkeystore could create a pkcs12
>         keystore with different storepass and keypass
>       o (JDK-8025941) keytool docs change due to 8008296. Added the
>         new -importpassword command
>   * policytool
>       o No significant changes
>
>
>       Troubleshooting
>
>   * jmap
>       o JDK-8010507 The option -permstat for jmap has been renamed to
>         -clstats
>       o JDK-7199147. Moved description of interned Strings to -heap
>         option.
>   * jconsole, jhat, jinfo, jsadebugd, jstack
>       o No significant changes
>
>
>       Web Services
>
>   * schemagen, wsgen, wsimport, xjc
>       o No significant changes
>
>
>       Web Start
>
>   * javaws
>       o Added note that this command is not available on Oracle Solaris
>
>
>       Additional New Features
>
>   * jvisualvm
>       o New feature
>   * jdeps
>       o Compact Profiles
>       o Updated examples on jdeps
>
> Thank you,
>
> The Java SE 8 Documentation Team
>



More information about the jdk8-dev mailing list