<Swing Dev> [13] RFR JDK-8220250: fix headings in java.desktop

[Prasanta Sadhukhan]

Any more comments on this 
http://cr.openjdk.java.net/~psadhukhan/8220250/webrev.2/

Regards
Prasanta
On 11-Mar-19 2:16 PM, Prasanta Sadhukhan wrote:
> The 2nd URL is based on webrev.1. I have placed new docs for webrev.2 
> here 
> http://cr.openjdk.java.net/~psadhukhan/8220250/docs.webrev2/docs/api/java.desktop/module-summary.html 
>
>
> Regards
> Prasanta
> On 10-Mar-19 9:17 PM, Jonathan Gibbons wrote:
>> If it helps, I have a utility to extract headers from an API bundle, 
>> that can generate a new bundle showing just the headers for each 
>> page, and their metadata. I'll run that on the two bundles you list 
>> below, and post the new URLs here.
>>
>> -- Jon
>>
>> On 3/9/19 10:59 PM, Philip Race wrote:
>>> It might have been intentional but I think it is wrong.
>>>
>>> It is useful to look at the old :
>>> https://docs.oracle.com/en/java/javase/11/docs/api/java.desktop/module-summary.html 
>>>
>>> and the new :
>>> http://cr.openjdk.java.net/~psadhukhan/8220250/docs/api/java.desktop/module-summary.html 
>>>
>>>
>>> to compare.
>>>
>>>
>>> What was H3 is in italics and what follows in regular style is intended
>>> to be a sub-section.
>>>
>>> -phil.
>>>
>>> On 3/10/19, 9:30 AM, Sergey Bylokhov wrote:
>>>> When I check the first version, I thought it was intentional change.
>>>>
>>>> https://docs.oracle.com/en/java/javase/11/docs/api/java.desktop/javax/print/attribute/package-summary.html 
>>>>
>>>>
>>>> All of them looks similar headers described something about 
>>>> attributes:
>>>>   1. <h4><a id="role"></a>Attribute Roles</h4>
>>>>   2. <h3>Attribute Sets</h3>
>>>>
>>>> Why the first uses <h4> and the second uses <h3>?
>>>>
>>>> On 09/03/2019 01:54, Prasanta Sadhukhan wrote:
>>>>> Thanks Jon for the pointer. I have modified that file
>>>>>
>>>>> http://cr.openjdk.java.net/~psadhukhan/8220250/webrev.2/
>>>>>
>>>>> Any more comments?
>>>>>
>>>>> Regards
>>>>> Prasanta
>>>>> On 09-Mar-19 2:24 AM, Jonathan Gibbons wrote:
>>>>>> Prasanta,
>>>>>>
>>>>>> You should double check this file:
>>>>>>
>>>>>> http://cr.openjdk.java.net/~psadhukhan/8220250/webrev.1/src/java.desktop/share/classes/javax/print/attribute/package-info.java.udiff.html 
>>>>>>
>>>>>>
>>>>>> Previously, it was a mixture of <h3> and <h4>, suggesting that 
>>>>>> the <h4> were subheadings of the enclosing logical <h3> section.  
>>>>>> Now, you have changed them all to <h2>, meaning that now they are 
>>>>>> all equivalent headings.
>>>>>>
>>>>>> -- Jon
>>>>>>
>>>>>> On 3/8/19 7:09 AM, Prasanta Sadhukhan wrote:
>>>>>>> Hi Phil,
>>>>>>>
>>>>>>>
>>>>>>> On 08-Mar-19 9:17 AM, Philip Race wrote:
>>>>>>>> Apart from making sure all the files are fixed there are two 
>>>>>>>> things to look for :
>>>>>>>>
>>>>>>>> 1) If by moving a heading up from H3 to H2 you've now created a 
>>>>>>>> similar error
>>>>>>>> because there is now no H3 before an H4. To be sure of this I 
>>>>>>>> think you'd
>>>>>>>> need to run Jon's tool - how did you verify it ?
>>>>>>>>
>>>>>>> I missed one case in TextAttribute which I rectified
>>>>>>> http://cr.openjdk.java.net/~psadhukhan/8220250/webrev.1/
>>>>>>>  It will be good to have Jon's tool so cc-ed him...
>>>>>>>> 2) If in a case like UIManager where you've moved some 
>>>>>>>> subsequent headings
>>>>>>>> up from H3 to H2 to match the new size at the reported error 
>>>>>>>> site , would it
>>>>>>>> have been better visually to leave them as H3 ? ... probably 
>>>>>>>> not .. but if there
>>>>>>>> were generated doc for us to look at posted that would be 
>>>>>>>> easier to tell.
>>>>>>> I am using make docs to verify and the docs output can be found at
>>>>>>> http://cr.openjdk.java.net/~psadhukhan/8220250/docs/api/java.desktop/module-summary.html 
>>>>>>>
>>>>>>>
>>>>>>> Regards
>>>>>>> Prasanta
>>>>>>>>
>>>>>>>> -phil.
>>>>>>>>
>>>>>>>> On 3/8/19, 3:37 AM, Sergey Bylokhov wrote:
>>>>>>>>> Looks fine.
>>>>>>>>>
>>>>>>>>> On 07/03/2019 03:37, Prasanta Sadhukhan wrote:
>>>>>>>>>> Hi All,
>>>>>>>>>>
>>>>>>>>>> Bug: https://bugs.openjdk.java.net/browse/JDK-8220250
>>>>>>>>>> webrev: http://cr.openjdk.java.net/~psadhukhan/8220250/webrev.0/
>>>>>>>>>>
>>>>>>>>>> Please review a doc fix to fix heading style to improve the 
>>>>>>>>>> accessibility JDK API documentation of java.desktop module.
>>>>>>>>>>
>>>>>>>>>> Main approach taken for fixing heading style are:
>>>>>>>>>> - headings in documentation comments for modules, packages 
>>>>>>>>>> and types should start at <h2> - Headings should be 
>>>>>>>>>> hierarchical, and without ascending gaps, so <h1> should be 
>>>>>>>>>> followed by <h2>, <h2> should be followed by <h3> or another 
>>>>>>>>>> <h2> Regards Prasanta
>>>>>>>>>
>>>>>>>>>
>>>>>>>
>>>>>
>>>>
>>>>
>