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

[Philip Race]

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