LaTeX: box padding (t,r,b,l), borders (t,r,b,l), shadows (x,y) or radii

[jfbu]

• Implement an enhanced coloured box allowing 4 padding parameters, 4 border widths, a shadow with possibly negative x-offset/y-offset, and possibly inset, and colours for background, border and shadow

• Do also with rounded corners with one radius per corner (circle arcs only) and constant border widths.

• Also do rounded boxes with shadows

• At page breaks, implement "open" style variant. Done at this stage for code-blocks via a verbatimopenframe LaTeX-key added to 'sphinxsetup'. But perhaps this option wll migrate to the envisioned CSS style (see next items). Indeed: Finally using pre_box-decoration-break=slice syntax.

• Provide some interface to configure make latexpdf to actually use the above styling possibility

This is a big enhancement of LaTeX PDF.

---

TL;DR:
Short story: I have implemented all as 'sphinxsetup' options but with CSS-like names. In future it is to be hoped some automatic conversion from true CSS will be added.

Long musings:

My idea was to add perhaps a configuration variable latex_style which could be for example a string in simple CSS with styling for nav.contents, aside.topic, admonition, note, ..., warning, ..., pre. Rather than extending again the \sphinxsetup. Via this latex_style either a parsing of it by Python (we don't need a full fledged CSS parser, but on the other hand if users see that CSS syntax work, they will want copy paste from HTML CSS then parsing becomes complicated), or to some extent I can parse by TeX, but this will not be good for future maintenance. But this would be feasible for example to support the CSS syntax for color specs (with some difficulties for rgb(R%,G%,B%) input, so a Python replace would replace % by \% for example which can then be used by TeX macro programmer).

I was also thinking one could allow "body" in the latex_style for example to set a page background color in PDF, or configure the font. And each of the above selectors could be with font-weight etc.., styling too, as well as color.

Apart from rounded boxes with varying border width which I have not yet done (the problem is that I recall some PDF viewer prefer border to be drawn latest, else I would fill the path and then overlay the background on a small path; so here I have to do lineto's plus one path to fill for each corner, which is work), the LaTeX is basically done.

The problem is how best to present a user-interface for the 4 paddings, 4 border-widths, 2 shadow sizes, and various colours...

...as said above I thought the most convenient for Sphinx user would be a CSS input.

Any advice? I can't now do this soon. Also, titles for admonitions are a bit problematic for styling because the current LaTeX rendering maps if we were to emulate it via CSS style is something like this

p.admonition-title { display: inline; }
p.admonition-title + p  { display: inline; }
p.admonition-title:after { content: ":\0020"; } 

(in LaTeX there are 2 space tokens after the colon for legacy reasons). This is very complicated way here to represent the actual legacy LaTeX behaviour...

An example of box with varying padding and 4 distinct radii:

An example of "openness" at page breaks:

Feature or Bugfix

• Feature: code-blocks can have shadows, can behave in a "slice" manner at page-breaks, topic boxes can have background color and separated customizability of all border widths, rounded corners, warning-type notices can have 4 borderwidths, 4 paddings, rounded corners, shadows... etc...

• Bugfix: LaTeX: color leaks for code-line inside a warning-type admonition since page-breaks can happen in the middle of wrapped highlighted code-lines #10650, LaTeX: overlap of contents if warning directive border-width set by warningborder key is about 8p or 9pt #10651

Relates

#10639

[jfbu]

I had used aside.topic influenced by recent addition to our basic.css_t but div.topic is better after all because it is still there in basic.css_t and in PDF output topic boxes are in the vertical flow, they are not really typeset "aside".

[jfbu]

I noticed in the latex code some obsoleted comments which I will update (done).

In this review I make some comments to try to explain aspects of the design of this large PR. Backwards compatiblity is respected, apart from one minor aspect, see comment about warning type boxes and their border and padding.

[jfbu]

Reason for TeXcolor and not color is due to input syntax one sees on right side. I could add a parser of HTML color specs but well, that would still extend TeX code and may introduce frailties, better to wait for a more general approach which would allow general CSS input then extract from it stuff that this PR can interpret as options for 'sphinxsetup' with TeX syntax.

[jfbu]

refer above comment

[jfbu]

here a bunch of \dimen's are defined for ease of usage, but the dimensions specified by options will be stored in macros before being assigned to them to avoid having to allocate dozens of \dimen's

[jfbu]

this \hbox is started here and ended in another macro depending whether with inset shadow or not

[tk0miya]

LGTM.

[jfbu]

I have ensured legacy implicit computation of padding from the border-width user setting of warning type notices (via warningborder etc...) will apply, so no change to PDF even for proojects having used warningborder etc...

Will merge after testing completes.