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

[Jonathan Gibbons]

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
>>>>>>>
>>>>>>>
>>>>>
>>>
>>
>>