Review for 7153977

[Brad Wetmore]

I didn't review the entire set of changes, since Somwya interrupted me 
and said it has already been by a couple people.  However, I did make a 
start and had a few comments.

Some teams go ahead and update the copyright dates to say "2012," 
whenever they make changes.  Not required, but something to consider.

Same comments as my previous about the long (>80 char) lines.  IMHO, 
this should be a separate task, and done throughout the JDK.

My only substantial comment is that I noticed that several of your links 
have a trailing "." (see appletviewer, jar), and some places don't.  It 
may be grammatically correct, but people doing a cut/paste might be 
inclined to include the ".", and the link won't resolve.  My personal 
taste would be to not.

   42 .fi
   43 
http://docs.oracle.com/javase/7/docs/technotes/tools/appletviewertags.html.

If that's a conscious decision to include it, so be it, but if it's just 
an artifact of the conversion, then you might want to take that into 
account.

Brad


On 3/19/2012 9:05 PM, Bhavesh Patel wrote:
> Hi Andrew,
>            The map page source pages reside in a closed repository. I have added Sowmya on the email who owns the source pages.
>
> Sowmya,
>         Can you please address the man page content questions that Andrew has?
>
> Thanks,
> Bhavesh.
>
> ----- Original Message -----
> From: ahughes at redhat.com
> To: bhavesh.x.patel at oracle.com
> Cc: jdk7u-dev at openjdk.java.net
> Sent: Monday, March 19, 2012 6:16:46 PM GMT -08:00 US/Canada Pacific
> Subject: Re: Review for 7153977
>
> ----- Original Message -----
>> Hi Kelly/Dalibor,
>>                              I have generated the man pages for 7u4.
>> Apart from the man page source changes, the link pointing to
>> download.oracle.com has been modified by the man page generation
>> script
>> to docs.oracle.com. Can you please review these changes?
>>
>> Webrev: http://cr.openjdk.java.net/~bpatel/7153977/webrev.00/.
>>
>> Thanks,
>> Bhavesh.
>>
>
> I agree with Kelly that this is a little hard to review.  Are these the source files
> for the documentation?  If not, can the source be checked in and these files generated
> during build?
>
> My main concern with this patch is with the addition of HotSpot flag documentation.
> For example,
>
> +\-XXLargePageSizeInBytes=n
> +This option is similar to the \f3\-XX:MaxLargePageSize\fP flag of JRockit.
>
> This is pretty much meaningless unless the user is familiar with the option in JRockit.
> Also, there seems to be some variation in how JRockit is capitalised (JRockit in most
> cases, but Jrockit in others).
>
> Is there a reason why the documentation is being furnished with a profusion of JRockit
> references?  I know Oracle are planning to transition users from JRockit to HotSpot
> but this seems a little overboard, especially given many options don't actually
> contain any information other than what the same option is called in JRockit.
>
> We also have:
>
> +\-XX:+UnlockCommercialFeatures
> +Use this flag to actively unlock the use of commercial features. Commercial features are the products "Oracle Java SE Advanced", or "Oracle Java SE Suite", as defined at
> +.na
> +\f2the Oracle Java SE Products web page\fP @
> +.fi
> +http://www.oracle.com/technetwork/java/javase/terms/products/index.html.
> +.br
> +If this flag is not specified, the default is to run the Java virtual machine without the commercial features being available. Once they are enabled, it is not possible to disable their use at runtime.
>
> I thought this option had been dropped?  I don't think it's appropriate for an open
> source code base and is pretty meaningless on its own.  I also assume what you actually
> mean is proprietary features (i.e. those without source code in OpenJDK) as I don't believe
> there is anything particularly non-commercial about the other features of HotSpot.
>
> Is this patch in OpenJDK8?  My understanding was that patches had to go there first.
>
> Thanks,