RFR: JDK-8241693, The paragraphs in the help page should not be in a <ul>

[Jonathan Gibbons]

Thanks for the review, and feedback on the line height.

With respect to the line height, it is hard to know how much the 
appearance was intentional, and how much was accidental side effects of 
setting the increased line height for some other reason.  That being 
said, Mercurial annotations to the rescue! The line-height was set back 
in 2013 in JDK-8016549: jdk7 javadocs are hard to read.
https://bugs.openjdk.java.net/browse/JDK-8016549
The bug is about the content of the Method Summary and Field Summary, 
and does not cite the help page at all.

So, for now, I'm inclined to go with the new appearance, using your 
words: "/the new look is the way normal text is supposed to be spaced./"

-- Jon

On 3/31/20 9:11 AM, Hannes Wallnoefer wrote:
> Jon,
>
> The code changes look good, in fact the HelpWriter code looks much better. The improved CSS class names also show nice attention to detail.
>
> Visually I notice that the help page now uses less space between lines and therefore appears a bit more „cramped“. The reason seems to be that „ul.block-list li.block-list“ has a  line-height: 1.4 declaration which no longer applies.
>
> Is this something we want to preserve for the help page? I guess one could argue that the new look is the way normal text is supposed to be spaced.
>
> Hannes
>
>
>> Am 27.03.2020 um 02:58 schrieb Jonathan Gibbons <jonathan.gibbons at oracle.com>:
>>
>> Please review a simple webrev to eliminate the inappropriate use of a <ul> list for the series of <section> elements on the help page.
>>
>> This <ul> is also one of the instances of the "block-list" CSS class we are trying to clean up, so removing the list fixes that usage!
>>
>> Just removing the list was almost too easy, so I took the opportunity to cleanup/simplify the code, using some of the recent new API for chained method calls.
>>
>> Simply removing the `<ul class="block-list">` did affect the whitespace layout of the page for the bulleted lists. While the bulleted lists previously used simple `<ul>` they inherited margins from the enclosing `<ul class="block-list">` (which is now removed). This was fixed by setting the class name of the bulleted lists to a new class, `help-section-list`, with an appropriate definition in the stylesheet, to restore the whitespace appearance of the lists on the page.
>>
>> I also took the opportunity to rename the poorly-named `emphasized-phrase` to `help-footnote` to better denote its usage.
>>
>> Apart from removing the <ul> and corresponding <li> items, there are no other changes to the visible content of the page. The source of the generated page was compared, with meld, against the version of the page before the change. In addition to that manual test, the TestHelpFile.java test was updated with a simple check for a representative sample of the content of the page, and specifically for the lack of the list elements surrounding the individual sections.
>>
>> -- Jon
>>
>> JBS: https://bugs.openjdk.java.net/browse/JDK-8241693
>> Webrev: http://cr.openjdk.java.net/~jjg/8241693/webrev.00/
>> API: http://cr.openjdk.java.net/~jjg/8241693/api.00/help-doc.html
>>
>>
>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20200331/d0a3a7eb/attachment.htm>