RFR: 8332239: Improve CSS for block tags

[Pavel Rappo]

On Thu, 16 May 2024 10:56:26 GMT, Hannes Wallnöfer <hannesw 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. This was not an intended change, but is hard to avoid without deeper changes to the markup or CSS:
> 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

Looks good in a rendered form. However, that mix of CSS units that we have -- %, px, em -- always looked suspicious to me.

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

Marked as reviewed by prappo (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/19264#pullrequestreview-2060440321