RFR: 8332239: Improve CSS for block tags

[Jonathan Gibbons]

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

Nice. It works well for short collections of block tags. It works less well for the really long ones,, but it is definitely better than before. Maybe we should still consider other ways of rendering very large block tags. But this is a good first step.

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

Marked as reviewed by jjg (Reviewer).

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