Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 1 commit into from Jul 14, 2022

Conversation

jfbu
Copy link
Contributor

@jfbu jfbu commented Jul 7, 2022

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

Capture d’écran 2022-07-07 à 23 08 01

An example of "openness" at page breaks:

Capture d’écran 2022-07-08 à 10 35 51

Feature or Bugfix

Relates

#10639

@jfbu jfbu added type:enhancement enhance or introduce a new feature builder:latex labels Jul 7, 2022
@jfbu jfbu added this to the 5.x milestone Jul 7, 2022
@jfbu jfbu marked this pull request as draft July 7, 2022 21:53
@jfbu jfbu force-pushed the latex_enhancedboxes branch 2 times, most recently from 1045dcd to 19f9aac Compare July 8, 2022 12:40
@jfbu jfbu force-pushed the latex_enhancedboxes branch 4 times, most recently from 1341fb4 to 0430893 Compare July 9, 2022 21:30
@jfbu jfbu modified the milestones: 5.x, 5.1.0 Jul 9, 2022
@jfbu jfbu marked this pull request as ready for review July 9, 2022 21:39
@jfbu jfbu force-pushed the latex_enhancedboxes branch 4 times, most recently from a9d8813 to 3b42def Compare July 10, 2022 07:45
@jfbu
Copy link
Contributor Author

jfbu commented Jul 10, 2022

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

Copy link
Contributor Author

@jfbu jfbu left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

doc/latex.rst Outdated Show resolved Hide resolved
doc/latex.rst Outdated
cautionBgColor={named}{LightCyan}}
div.caution_border-width=3pt,
div.caution_border-TeXcolor={named}{Cyan},
div.caution_background-TeXcolor={named}{LightCyan}}
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

doc/latex.rst Show resolved Hide resolved
hintBorderColor={named}{LightCoral},
attentionborder=3pt,
attentionBorderColor={named}{Crimson},
attentionBgColor={named}{FloralWhite},
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

refer above comment

doc/latex.rst Show resolved Hide resolved
sphinx/texinputs/sphinxpackageboxes.sty Outdated Show resolved Hide resolved
\newdimen\spx@boxes@radius@topleft % only circular arcs, x-radius same as y-radius
\newdimen\spx@boxes@radius@topright
\newdimen\spx@boxes@radius@bottomright
\newdimen\spx@boxes@radius@bottomleft
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

sphinx/texinputs/sphinxpackageboxes.sty Outdated Show resolved Hide resolved
% The parameters are interpreted as they would as CSS properties.
% For the shadow inset variant see separate \spx@boxes@fcolorbox@insetshadow
\long\def\spx@boxes@fcolorbox#1{%
\hbox\bgroup
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

sphinx/texinputs/sphinxpackageboxes.sty Outdated Show resolved Hide resolved
Copy link
Member

@tk0miya tk0miya left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM.

@jfbu jfbu mentioned this pull request Jul 13, 2022
- LaTeX: box padding (t,r,b,l), borders (t,r,b,l), shadows (x,y) or radii

- LaTeX: fix sphinx-doc#10650 via usage of our own sophisticated \fcolorbox

- LaTeX: user interface via 'sphinxsetup' to enhanced code-blocks frames

- LaTeX: user interface via 'sphinxsetup' to enhanced topic boxes

- LaTeX: CSS-named-alikes 'sphinxsetup' options for code-blocks and
  topics

- LaTeX: CSS-named-alikes 'sphinxsetup' keys for warning type notices
  (fix sphinx-doc#10651)

- LaTeX: documentation of the new CSS-like options

- LaTeX: remove sphinx-doc#10619 documentation, as the sphinx-doc#10619 added
  shadowBorderColor and shadowShadowColor now named respectively:

  aside.topic_border-TeXcolor and aside.topic_box-shadow-TeXcolor

- LaTeX: use div.topic option prefix and not aside.topic for CSS-like
  options

- LaTeX: keep the implicit legacy padding of warning type boxes as
  default behaviour
@jfbu
Copy link
Contributor Author

jfbu commented Jul 14, 2022

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.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
builder:latex type:enhancement enhance or introduce a new feature
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants