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