[OpenJDK 2D-Dev] [2d dev] [8] Review request for JDK-8028272 : Tidy warnings cleanup for javax.print package

[Jim Graham]

A general problem with hand-written HTML is that container elements are 
treated as in-line affects.  In particular, we sprinkle <p> tags like 
they are a command to insert a paragraph break, but that is a misnomer, 
they are the start of a paragraph block and we never end any of them. 
Most parsers give us the benefit of the doubt that if we start another 
paragraph, then they will end a previous paragraph implicitly (i.e. a 
bare "<p>" inside another "<p>" is implicitly interpreted as "</p><p>". 
  But, a bare "<p>" still leaves a paragraph open and if you then 
encounter another block tag, you have an unclosed paragraph inside it. 
I don't think an implicit "</p>" is inserted in the general case of 
encountering another block tag.  In particular, I don't think blocks are 
allowed inside of a paragraph.  In the case of "<li>", that is only 
valid within an immediately enclosing <ul> or <ol>, but if there is an 
unclosed paragraph tag, then the immediately enclosing context is not 
compatible with <li> until you close the paragraph to "pop" the stack.

Note that <li> is supposed to be closed with </li>, but we are being 
forgiven that in most cases by an implicit close when an other <li> is 
encountered (or the final </ul> or </ol> is encountered).

In the case of the list of items in the Doc.java I actually found the 
extra space to be distracting because it was not very uniformly used. 
The extra spacing between and around items for the <ul> should probably 
be achieved some other way, like CSS.  But, replacing the bare "<p>" 
with a paired "<p></p>" would probably fix the warnings without changing 
the nature of the formatting...

			...jim

On 12/5/13 9:58 AM, Phil Race wrote:
> Hi,
>
> I am not happy with approving this until I have had a chance to review
> 1) The actual warnings from tidy
> 2) The effect on the generated javadoc.
>
> I think <P> adds extra space that <br> does not, so don't jump to
> conclusions
> about what the original author was trying to achieve.
>
> -phil.
>
> On 11/21/2013 4:54 AM, Sergey Lugovoy wrote:
>> Hi Joe.
>>
>> In most cases the author used this stray "<p>" as a line break.
>> A line break is necessary indeed but if it is followed by a block
>> element, it is  considered erroneous by tidy.
>> So adding <br> does, in fact, better correspond to the author original
>> idea.
>>
>>
>> On Wednesday, November 20, 2013 04:46:59 PM Joe Darcy wrote:
>>> Hello,
>>>
>>> I'm not an HTML expert, but it seems preferable to me to just remove an
>>> unnecessary "<p>" tag rather than replacing it with "<br/>".
>>>
>>> Is there a reason to prefer "<br/>"?
>>>
>>> Otherwise the changes look fine.
>>>
>>> Thanks,
>>>
>>> -Joe
>>>
>>> On 11/20/2013 1:47 AM, Sergey Lugovoy wrote:
>>>> Hi all,
>>>> please review the fix.
>>>> bug: https://bugs.openjdk.java.net/browse/JDK-8028272
>>>> webrev : http://cr.openjdk.java.net/~yan/8028272/webrev.00/
>>>>
>>>> This patch cleanup tidy warnings for generated html documentation for
>>>> javax.print package, and do not affect the appearance of the
>>>> documentation.
>>>> The patch is created against jdk8/tl team repository according to
>>>> requirements of this cleanup project.
>>>>
>>>>
>>>> Best regards,
>>>> Serge V. Lugovoy
>