For review, changes to java.1 nroff page as part of OpenJDK 8u40 nroff review

[raymond gallardo]

Hi all,

The following changes to the java.1 nroff pages have been made as part 
of the OpenJDK 8u40 review. The file itself can be obtained here:

http://cr.openjdk.java.net/~rgallard/java.1

=====================================
[The sentence "*This option is ignored when tiered compilation is 
enabled; see the option -XX:+TieredCompilation." was added.]*

-XX:CompileThreshold=invocations
Sets the number of interpreted method invocations before compilation. By 
default, in the server JVM, the JIT compiler performs 10,000 interpreted 
method invocations to gather information for efficient compilation. For 
the client JVM, the default setting is 1,500 invocations. *This option 
is ignored when tiered compilation is enabled; see the option 
-XX:+TieredCompilation. *The following example shows how to set the 
number of interpreted method invocations to 5,000:

-XX:CompileThreshold=5000

You can completely disable interpretation of Java methods before 
compilation by specifying the -Xcomp option.

=====================================

[The sentence "*The initial code cache size should be not less than the 
system's minimal memory page size." was added.]*

-XX:InitialCodeCacheSize=size
Sets the initial code cache size (in bytes). Append the letter k or K to 
indicate kilobytes, m or M to indicate megabytes, g or G to indicate 
gigabytes. The default value is set to 500 KB. *The initial code cache 
size should be not less than the system's minimal memory page size.*The 
following example shows how to set the initial code cache size to 32 KB:

-XX:InitialCodeCacheSize=32k

=====================================
[The sentences "*This option has a limit of 2 GB; otherwise, an error is 
generated. The maximum code cache size should not be less than the 
initial code cache size; see the option -XX:InitialCodeCacheSize" were 
added.]*

-XX:ReservedCodeCacheSize=size
Sets the maximum code cache size (in bytes) for JIT-compiled code. 
Append the letter k or K to indicate kilobytes, m or M to indicate 
megabytes, g or G to indicate gigabytes. *This option has a limit of 2 
GB; otherwise, an error is generated. The maximum code cache size should 
not be less than the initial code cache size; see the option 
-XX:InitialCodeCacheSize.*This option is equivalent to -Xmaxjitcodesize.

=====================================
["-XX:+UseRTMLocking" was changed from "-XX:UseRTMLocking".]

-XX:+UseRTMDeopt
Auto-tunes RTM locking depending on the abort ratio. This ratio is 
specified by -XX:RTMAbortRatio option. If the number of aborted 
transactions exceeds the abort ratio, then the method containing the 
lock will be deoptimized and recompiled with all locks as normal locks. 
This option is disabled by default. The *-XX:+UseRTMLocking*option must 
be enabled.

=====================================

Thanks,
--Raymond

On 2014-10-10 2:53 PM, raymond gallardo wrote:
> Hi all,
>
> Just a reminder that the nroff files for 8u40 are up for review. 
> Please send us your feedback by the end of the day today, Friday, 
> October, 10.
>
> Thanks,
> --The Java SE Documentation team
>
> On 2014-10-08 2:12 PM, raymond gallardo wrote:
>>
>>
>> Hello Reviewers,
>>
>> As part of the OpenJDK review processes, and the next Java SE 8u40
>> release, the OpenJDK 8 nroff files for Java tools are up for review,
>> which is available here as a zip file:
>>
>> http://cr.openjdk.java.net/~rgallard/openjdk_nroff_8u40.zip
>>
>> You can obtain the webrev here:
>>
>> http://cr.openjdk.java.net/~rgallard/openjdk_webrev_8u40.zip
>>
>> Please provide your feedback by Friday, October 10, 2014.
>>
>> The following sections describe what kinds of review comments we're
>> looking for and what has changed for Java SE 8u40. Please contact us if
>> you have any questions.
>>
>>     Summary of Changes
>>     Scope of Review
>>     Provide Feedback
>>     How to View a Man Page
>>
>> Summary of Changes
>>
>> 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.
>>
>> The following lists significant changes made to the Java tool nroff
>> pages for this release as well as the engineer who reviewed the content.
>>
>> java:
>>
>> JDK-8054382 : (JDK-8054376 : Move RTM flags from Experimental to
>> Product) Update RTM documentation, staffan.friberg at oracle.com and
>> vladimir.kozlov at oracle.com.
>> JDK-8043965 : Xverify:remote description is wrong, David Buck
>> JDK-8040180 : Extend and improve documentation about Large pages,
>> staffan.friberg at oracle.com and stefan.karlsson at oracle.com
>> JDK-8040176 : Document -XX:ObjectAlignmentInBytes flag, Vladimir Kozlov
>> JDK-8037590 : The name for PerfDataSaveToFile flag is incorrect in
>> HotSpot VM Options document, masato.yoshida at oracle.com
>> JDK-8032725 : Description of default maximum heap size need correction,
>> masato.yoshida at oracle.com
>>
>> keytool:
>>
>> JDK-8050813 : Option values are not italicized on JDK 8 keytool
>> documentation page, Jason Uh
>>
>> javapackager and javafxpackager (Note that changes to javapackager and
>> javafxpackager will not appear in the webrev because they will be pushed
>> to a different repository):
>>
>> RT-37898, Danno Ferrin
>> RT-37876, Danno Ferrin
>>
>> javac:
>>
>> JDK-8016641 : Cross compilation not as documented, Maurizio Cimadamore
>>
>> jjs:
>>
>> JDK-8041730 : Nashorn documentation bug, Sundararajan Athijegannathan
>> JDK-8038292 : whitespace missing in examples in jjs tool doc page,
>> Sundararajan Athijegannathan
>>
>> policytool:
>>
>> JDK-8059076 : Spacing bug in policytool.html
>>
>> jstat:
>>
>> JDK-8040079 : jstat documentation needs to be updated for metaspace,
>> erik.helin at oracle.com
>>
>> javadoc:
>>
>> New -javafx option added
>>
>>
>> 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 October
>> 10, 2014.
>>
>> All feedback will be triaged. Severe technical inaccuracies and other
>> small bugs will be fixed. Due to Java SE 8u40 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_8u40.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_8u40.zip
>>
>> This creates a sub-directory named openjdk_nroff_8u40 in the current
>> directory.
>>
>> 4. Change directory to openjdk_nroff_8u40 as follows:
>>
>> $ cd openjdk_nroff_8u40
>>
>> 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 OS X 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.
>>
>> Thank you,
>> The Java SE 8 Documentation Team
>>
>>
>>
>