RFR: 8332239: Improve CSS for block tags

[Hannes Wallnöfer]

On Thu, 16 May 2024 11:21:14 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Please review a change to improve the layout of definition lists used to display block tags:
>> 
>>  - Add indentation to the `<dd>` elements used for block tag details
>>  - Set the margin of lists within block tag details so they do not appear as nested lists, except for lists with CSS classes `tag-list` or `tag-list-long`, which are used for block tags containing lists, such as `@see`. 
>> 
>> Before/after comparison (contains `java.base` and `java.compiler` modules):
>> https://cr.openjdk.org/~hannesw/8332239/api.00/index.html
>> https://cr.openjdk.org/~hannesw/8332239/api.01/index.html
>> 
>> Comparison for block tag layout:
>> https://cr.openjdk.org/~hannesw/8332239/api.00/java.base/java/lang/Object.html#hashCode()
>> https://cr.openjdk.org/~hannesw/8332239/api.01/java.base/java/lang/Object.html#hashCode()
>> 
>> Example of very long block tag details containing a list:
>> https://cr.openjdk.org/~hannesw/8332239/api.00/java.compiler/javax/lang/model/util/package-summary.html
>> https://cr.openjdk.org/~hannesw/8332239/api.01/java.compiler/javax/lang/model/util/package-summary.html
>> 
>> Note that the indentation also applies to the definition lists at the top of class/interface documentation as they use the same markup as block tags:
>> https://cr.openjdk.org/~hannesw/8332239/api.00/java.base/java/lang/Exception.html
>> https://cr.openjdk.org/~hannesw/8332239/api.01/java.base/java/lang/Exception.html
>> 
>>  This was not an intended change but might or might not be desirable. It could be avoided with some additional CSS changes.
>
> Looks good in a rendered form. However, that mix of CSS units that we have -- %, px, em -- always looked suspicious to me.

Thanks @pavelrappo.

> However, that mix of CSS units that we have -- %, px, em -- always looked suspicious to me.

There are reasons for using one or the other. `em` is the font size of the local element, so it can be used to space things relative to the element's font size. `1em` is the default top and bottom margin for top-level lists, so the list will be laid out correctly independent of the list's font.

`px` on the other hand is an absolute unit. We use it to set the default font size to `14px` as the default `16px` will look too big, and to set up the basic layout of the page. In this case, the indentation should be the same regardless of font size (which might vary for proportional and monospaced font, for example).

-------------

PR Comment: https://git.openjdk.org/jdk/pull/19264#issuecomment-2115027428