From 99863fb080f22b8b22f2b0c1d0f11439eee9129e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Mon, 13 Mar 2023 12:25:47 +0100 Subject: [PATCH] LaTeX: encapsulate dimension options in \dimexpr --- doc/latex.rst | 39 ++++++++++++------- sphinx/texinputs/sphinx.sty | 15 ++++--- sphinx/texinputs/sphinxlatexadmonitions.sty | 11 +++--- sphinx/texinputs/sphinxpackageboxes.sty | 43 ++++++++++----------- 4 files changed, 56 insertions(+), 52 deletions(-) diff --git a/doc/latex.rst b/doc/latex.rst index ded888892..ebde07333 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -1130,29 +1130,38 @@ inserted via the :dudir:`raw` directive) and the CSS syntax is only imitated. .. important:: Low-level LaTeX errors causing a build failure can happen if the input syntax is not respected. - * In particular properties for colors, - whose names end with ``-TeXcolor``, must be input as for the other color - related options previously described, i.e. for example:: + * In particular colors must be input as for the other color related options + previously described, i.e. either in the ``\definecolor`` syntax or, if + package ``xcolor`` is available (it is then automatically used) also the + ``\colorlet`` syntax:: ... - div.warning_border-TeXcolor={rgb}{1,0,0},% - div.error_background-TeXcolor=red!10,% (if xcolor available) + div.warning_border-TeXcolor={rgb}{1,0,0},% (always works) + div.error_background-TeXcolor=red!10,% (works only if xcolor is available) ... - * A colon will not be accepted in place of the equal sign which is expected - by the LaTeX syntax. Avoid as a rule extra spaces in the input. + * A colon in place of the equal sign will break LaTeX. - * All dimensional parameters expect a *unique* dimension, even - ``border-width`` or ``padding``: they can not be used with a value being - a space separated list of dimensions. The sole exception currently is + * As a rule, avoid inserting unneeded spaces in the key values. + + * Dimensional parameters such as ``border-width`` or ``padding`` expect a + *unique* dimension: they can not be used so far with space separated + dimensions. The sole property which handles space separated input is ``box-shadow``. - * Dimensions should use TeX units such as ``pt`` or ``cm`` or ``in``. The - ``px`` unit is recognized by ``pdflatex`` and ``lualatex`` but not by - ``xelatex`` or ``platex``. + * Dimension specifications must use TeX units such as ``pt`` or ``cm`` or + ``in``. The ``px`` unit is recognized by ``pdflatex`` and ``lualatex`` + but not by ``xelatex`` or ``platex``. + + * It is allowed for such specifications to be so-called "dimensional + expressions", e.g. ``\fboxsep+2pt`` or ``0.5\baselineskip`` are valid + inputs. The expressions will be evaluated only at the typesetting time. + Be careful though if using as in these examples TeX control sequences to + double the backslash or to employ a raw Python string for the value of + the :ref:`'sphinxsetup' ` key. The options are all named in a similar pattern which depends on a ``prefix``, -which is then followed by an underscore, then the option name. +which is then followed by an underscore, then the property name. .. csv-table:: :header: Directive, Option prefix, LaTeX environment @@ -1296,7 +1305,7 @@ recommended!), but see perhaps rather the configuration displayed at start of latex_elements = { 'sphinxsetup': """% % For colors, we use throughout this example the \definecolor syntax - % The leaner \colorlet syntax is available if xcolor is on your system + % The leaner \colorlet syntax is available if xcolor is on your system. pre_background-TeXcolor={RGB}{242,242,242},% alias of VerbatimColor pre_border-TeXcolor={RGB}{32,32,32},% pre_box-decoration-break=slice, diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index e7a02bbd6..4706a139f 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -504,14 +504,13 @@ will be set to white}% \begingroup\edef\spx@tempa{##1}\expandafter\endgroup \ifx\spx@tempa\spxstring@none #2% - % MEMO: here the code uses an \edef+\number so dimensions are - % evaluated at time of configuration of the option, not at time of - % usage of its value; this is in contrast with other dimension specs. - % These things probably do not matter much, as users will (a priori) - % use only explicit dimension denotations such as "4pt". - \else #1\edef#6{\number\dimexpr##1\relax sp}% - \edef#7{\number\dimexpr##2+\z@\relax sp}% - \if\relax\detokenize{##3}\relax#4\else#3\fi + % MEMO: at 5.1.0 and up to 6.2.0, an \edef+\dimexpr was used here. + % Expansion is now delayed to time of use as for the other dimensions + % handled above. This is synced with the added \dimexpr...\relax + % encapsulation in sphinxpackageboxes.sty's \spx@boxes@fcolorbox@setup. + \else #1% + \def#6{##1}\def#7{##2+\z@}% + \if\relax\detokenize{##3}\relax#4\else#3\fi \fi }% #5none {} {} \@nnil % no shadow by default (except for topic, see below) diff --git a/sphinx/texinputs/sphinxlatexadmonitions.sty b/sphinx/texinputs/sphinxlatexadmonitions.sty index b5b6dee13..12dbcd647 100644 --- a/sphinx/texinputs/sphinxlatexadmonitions.sty +++ b/sphinx/texinputs/sphinxlatexadmonitions.sty @@ -36,14 +36,11 @@ % Some are quite plain \newenvironment{sphinxseealso}[1]{\sphinxstrong{#1:}\par\nopagebreak}{} -% This \dimen register is a legacy relic from Sphinx 1.5, as well as -% spx@notice@border@color (used in sphinxlightbox environment and set in -% sphinxadmonition environment) which one could dispose of, using \spx@notice -% which is defined by sphinxadmonition environment. Let's simply keep as used -% since 1.5. +% This \dimen register is a legacy relic from Sphinx 1.5 which is used now +% only for sphinxlightbox. It is set-up in sphinxadmonition environment. \newdimen\spx@notice@border -% spx@notice@bordercolor and \spx@notice@border are set in sphinxadmonition environment +% The color spx@notice@bordercolor is set in sphinxadmonition environment. \newenvironment{sphinxlightbox}{% \par \noindent{\color{spx@notice@bordercolor}% @@ -201,6 +198,8 @@ % set the parameters common to lightbox and heavybox environments \sphinxcolorlet{spx@notice@bordercolor}{sphinx#1BorderColor}% \sphinxcolorlet{spx@notice@bgcolor}{sphinx#1BgColor}% + % At 6.2.0 this \spx@notice@border is used only for note, hint, important, + % and tip. And only if they are rendered via sphinxlightbox \spx@notice@border \dimexpr\csname spx@#1@border\endcsname\relax % trigger the sphinx environment, #2=heading is passed as argument \begin{sphinx#1}{#2}} diff --git a/sphinx/texinputs/sphinxpackageboxes.sty b/sphinx/texinputs/sphinxpackageboxes.sty index 892a4a1b1..9bd80b16c 100644 --- a/sphinx/texinputs/sphinxpackageboxes.sty +++ b/sphinx/texinputs/sphinxpackageboxes.sty @@ -92,36 +92,33 @@ % \spx@boxes@fcolorbox@rectangle or \spx@boxes@fcolorbox@rounded depending on % the configuration and availability of the pict2e package. % -% Due to varying conventions regarding Color names (border, background, -% and shadow), they have to be passed as parameters #2, #3, #4. % The #1 is one of: pre, topic, warning, danger, etc.... +% Due to varying conventions regarding Color names (border, background, +% and shadow), no unified treatment was possible and they are simply +% passed explicitly as the parameters #2, #3, and #4. +% +% Using \dimexpr for maximal user input flexibility. \def\spx@boxes@fcolorbox@setup#1#2#3#4{% - % All right sides expand to non-terminated dimen expressions (except for - % shadow@xoffset, shadow@yoffset, where the space of EOL terminates sp) - % The \relax are not strictly needed, except the one before the first - % \iftrue, but in case some input is "2.5" in place of "2.5pt" they help - % avoiding LaTeX to issue e.g. some "Missing \begin{document}" error - % rather than more apt "Illegal unit of measure (pt inserted)." - \spx@boxes@border@top \@nameuse{spx@#1@border@top}\relax - \spx@boxes@border@right \@nameuse{spx@#1@border@right}\relax - \spx@boxes@border@bottom\@nameuse{spx@#1@border@bottom}\relax - \spx@boxes@border@left \@nameuse{spx@#1@border@left}\relax - \spx@boxes@border \@nameuse{spx@#1@border}\relax + \spx@boxes@border@top \dimexpr\@nameuse{spx@#1@border@top}\relax + \spx@boxes@border@right \dimexpr\@nameuse{spx@#1@border@right}\relax + \spx@boxes@border@bottom\dimexpr\@nameuse{spx@#1@border@bottom}\relax + \spx@boxes@border@left \dimexpr\@nameuse{spx@#1@border@left}\relax + \spx@boxes@border \dimexpr\@nameuse{spx@#1@border}\relax % - \spx@boxes@padding@top \@nameuse{spx@#1@padding@top}\relax - \spx@boxes@padding@right \@nameuse{spx@#1@padding@right}\relax - \spx@boxes@padding@bottom\@nameuse{spx@#1@padding@bottom}\relax - \spx@boxes@padding@left \@nameuse{spx@#1@padding@left}\relax + \spx@boxes@padding@top \dimexpr\@nameuse{spx@#1@padding@top}\relax + \spx@boxes@padding@right \dimexpr\@nameuse{spx@#1@padding@right}\relax + \spx@boxes@padding@bottom\dimexpr\@nameuse{spx@#1@padding@bottom}\relax + \spx@boxes@padding@left \dimexpr\@nameuse{spx@#1@padding@left}\relax % - \spx@boxes@radius@topleft \@nameuse{spx@#1@radius@topleft}\relax - \spx@boxes@radius@topright \@nameuse{spx@#1@radius@topright}\relax - \spx@boxes@radius@bottomright \@nameuse{spx@#1@radius@bottomright}\relax - \spx@boxes@radius@bottomleft \@nameuse{spx@#1@radius@bottomleft}\relax + \spx@boxes@radius@topleft \dimexpr\@nameuse{spx@#1@radius@topleft}\relax + \spx@boxes@radius@topright \dimexpr\@nameuse{spx@#1@radius@topright}\relax + \spx@boxes@radius@bottomright \dimexpr\@nameuse{spx@#1@radius@bottomright}\relax + \spx@boxes@radius@bottomleft \dimexpr\@nameuse{spx@#1@radius@bottomleft}\relax % \@nameuse{ifspx@#1@withshadow}% \spx@boxes@withshadowtrue - \spx@boxes@shadow@xoffset \@nameuse{spx@#1@shadow@xoffset}\relax - \spx@boxes@shadow@yoffset \@nameuse{spx@#1@shadow@yoffset}\relax + \spx@boxes@shadow@xoffset \dimexpr\@nameuse{spx@#1@shadow@xoffset}\relax + \spx@boxes@shadow@yoffset \dimexpr\@nameuse{spx@#1@shadow@yoffset}\relax \else \spx@boxes@withshadowfalse \fi