From b635150bc7817017df9866d0a0f704ea8727aad1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Mon, 6 Mar 2023 12:31:14 +0100 Subject: [PATCH] LaTeX: ``\sphinxbox`` for boxing inline text elements --- CHANGES | 4 ++ doc/latex.rst | 65 +++++++++++++++++++++++-- sphinx/texinputs/sphinx.sty | 58 ++++++++++++++++++---- sphinx/texinputs/sphinxpackageboxes.sty | 24 +++++++++ 4 files changed, 138 insertions(+), 13 deletions(-) diff --git a/CHANGES b/CHANGES index adeac9dbdd3..c761388ee23 100644 --- a/CHANGES +++ b/CHANGES @@ -18,6 +18,10 @@ Deprecated Features added -------------- +* LaTeX: a command ``\sphinxbox`` for styling text elements with a (possibly + rounded) box, optional background color and shadow, has been added. + See :ref:`sphinxbox`. (refs #11224) + Bugs fixed ---------- diff --git a/doc/latex.rst b/doc/latex.rst index 9b34a4176d7..8861d7ad03b 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -35,7 +35,7 @@ benefit from prepared themes. The :ref:`latex-options`, and particularly the :ref:`latex_elements ` variable, provides much of the interface for customization. For example: -.. code-block:: python +.. code-block:: latex # inside conf.py latex_engine = 'xelatex' @@ -233,7 +233,7 @@ Keys that you may want to override include: ``'extrapackages'`` Additional LaTeX packages. For example: - .. code-block:: python + .. code-block:: latex latex_elements = { 'extrapackages': r'\usepackage{isodate}' @@ -1248,7 +1248,7 @@ customizable: Here is a random example (not especially recommended!): -.. code-block:: +.. code-block:: latex latex_elements = { 'sphinxsetup': """% @@ -1446,6 +1446,65 @@ Macros - ``\sphinxcite``: A wrapper of standard ``\cite`` for citation references. + +.. _sphinxbox: + +The ``\sphinxbox`` command +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 6.2.0 + +It can be used to "box" inline text elements with all the customizability which +has been described in :ref:`additionalcss`. It is a LaTeX command with one +optional argument, which is a comma-separated list of key=value pairs, as for +:ref:`latexsphinxsetup`. Here is the complete list of keys: + +- ``border-width``, +- ``border-top-width``, ``border-right-width``, ``border-bottom-width``, + ``border-left-width``, +- ``box-decoration-break``, +- ``padding``, +- ``padding-top``, ``padding-right``, ``padding-bottom``, ``padding-left``, +- ``border-radius``, +- ``border-top-left-radius``, ``border-top-right-radius``, + ``border-bottom-right-radius``, ``border-bottom-left-radius``, +- ``box-shadow``, +- ``border-TeXcolor``, ``background-TeXcolor``, ``box-shadow-TeXcolor``. + +Refer to :ref:`additionalcss` for important syntax information. The default +configuration uses no shadow, a border-width of ``\fboxrule``, a padding of +``\fboxsep``, rounded corners (with radius ``\fboxsep``) and background and +border colors as for the default rendering of code-blocks. One can modify +these defaults via using ``\sphinxboxsetup[key=value,...]`` or also via +``\sphinxsetup`` but all key names must then be prefixed with ``box_``. + +A utility ``\newsphinxbox`` if provided to create an alternative, +e.g. ``\foo`` to ``\sphinxbox`` with a different set of defaults, but which +otherwise behaves the same. Here is a random example of use: + +.. code-block:: latex + + latex_elements = { + 'preamble': r''' + % define a sphinxbox with some defaults: + \newsphinxbox[border-width=4pt,% + border-radius=4pt,% + background-TeXcolor=yellow!20]{\foo} + % use this \foo to redefine rendering of some text elements: + \protected\def\sphinxguilabel#1{\foo{#1}} + \protected\def\sphinxmenuselection#1{\foo[background-TeXcolor=green!20, + border-width=1pt, + box-shadow=3pt 3pt, + box-shadow-TeXcolor=gray]{#1}} + % and this one will use \sphinxbox directly + % one can also add options within square brackets as in usage of \foo above + \protected\def\sphinxkeyboard#1{\sphinxbox{\sphinxcode{#1}}} + ''', + } + +In the above example, you can probably use ``\renewcommand`` syntax if you +prefer (with ``[1]`` in place of ``#1`` then). + Environments ~~~~~~~~~~~~ diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 31f0fb97b28..2c23e9f30c7 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -311,8 +311,6 @@ will be set to white}% % Except that \sphinxbox is for boxing inline elements (no linebreak, no % pagebreak). % -% (this addition happens in a descendant commit of this one) -% % MEMO: the 6.2.0 refactoring induced a change that the default \fboxrule used % by verbatimborder and shadowrule is now not expanded to its value immediately in % preamble (no assignment to a \dimen register is done, only storage in a @@ -361,6 +359,8 @@ will be set to white}% \spx@tempa{spx@attention@}{div.attention_}{attentionborder}{1pt} \spx@tempa{spx@danger@} {div.danger_} {dangerborder} {1pt} \spx@tempa{spx@error@} {div.error_} {errorborder} {1pt} +% this one new at 6.2.0: (we do not create a "legacy name" for it) +\spx@tempa{spx@box@} {box_} {box_border-width}\fboxrule % Set default box-decoration-break style for codeblocks to slice \spx@pre@border@opentrue % new default at 6.0.0: slice, not clone @@ -401,17 +401,11 @@ will be set to white}% \spx@tempa{spx@attention@}{div.attention_} {\dimexpr.6\baselineskip-\spx@attention@border\relax} \spx@tempa{spx@danger@} {div.danger_} {\dimexpr.6\baselineskip-\spx@danger@border\relax} \spx@tempa{spx@error@} {div.error_} {\dimexpr.6\baselineskip-\spx@error@border\relax} +\spx@tempa{spx@box@} {box_} \fboxsep % new at 6.2.0 % define legacy verbatimsep key as alias of pre_padding key \expandafter\let\expandafter\KV@sphinx@verbatimsep\csname KV@sphinx@pre_padding\endcsname % define legacy shadowsep key as alias of div.topic_padding key \expandafter\let\expandafter\KV@sphinx@shadowsep\csname KV@sphinx@div.topic_padding\endcsname -% (temporary explanation: this next comment and code line belong to a descendant -% commit down the line for \sphinxbox support, left-overs from a rebase) -% also define a boxsep key as alias of box_padding key, because we defined boxborder -% boxborder was defined only as collateral of batch definitions so some hesitation -% we do keep these boxborder and boxsep as they configure the probably two most -% important parameters; still I feel not definitive about what is best to do -\expandafter\let\expandafter\KV@sphinx@boxsep\csname KV@sphinx@box_padding\endcsname % Corner radii keys % @@ -438,6 +432,7 @@ will be set to white}% \spx@tempa{spx@attention@}{div.attention_} \z@ \spx@tempa{spx@danger@} {div.danger_} \z@ \spx@tempa{spx@error@} {div.error_} \z@ +\spx@tempa{spx@box@} {box_} {3pt}% new and tentative default at 6.2.0 % Shadow keys % @@ -455,6 +450,7 @@ will be set to white}% \spx@tempa{spx@attention@} \spx@tempa{spx@danger@} \spx@tempa{spx@error@} +\spx@tempa{spx@box@}% new at 6.2.0 % \def\spx@tempa#1{% #1 = macro prefix \expandafter\spx@tempb @@ -495,6 +491,7 @@ will be set to white}% \spx@tempa{spx@attention@}{div.attention_} \spx@tempa{spx@danger@} {div.danger_} \spx@tempa{spx@error@} {div.error_} +\spx@tempa{spx@box@} {box_}% new at 6.2.0 % Support for legacy shadowsize % This definition was broken at 5.1.0 and fixed at 6.1.2 @@ -531,6 +528,7 @@ will be set to white}% \spx@tempa{spx@attention@} \spx@tempa{spx@danger@} \spx@tempa{spx@error@} +\spx@tempa{spx@box@}% new at 6.2.0 % \def\spx@tempa#1{% #1 = macro prefix \expandafter\spx@tempb @@ -567,6 +565,7 @@ will be set to white}% \spx@tempa{spx@attention@}{div.attention_} {sphinxattention} \spx@tempa{spx@danger@} {div.danger_} {sphinxdanger} \spx@tempa{spx@error@} {div.error_} {sphinxerror} +\spx@tempa{spx@box@} {box_} {sphinxbox}% new at 6.2.0 % Keep legacy sphinxsetup interface for warning type notices \def\spx@tempa#1#2{% #1 = option prefix, #2 = legacy option prefix \expandafter\let\csname KV@sphinx@#2BorderColor\expandafter\endcsname @@ -597,7 +596,7 @@ will be set to white}% % No need for the \hspace{0pt} trick (\hskip\z@skip) with luatex \ifdefined\directlua\let\sphinxAtStartPar\@empty\fi % user interface: options can be changed midway in a document! -\newcommand\sphinxsetup[1]{\setkeys{sphinx}{#1}} +\newcommand\sphinxsetup{\setkeys{sphinx}} %% MISCELLANEOUS CONTEXT @@ -680,6 +679,45 @@ will be set to white}% %% FRAMED ENVIRONMENTS % +% \sphinxbox added at 6.2.0, its definition is in sphinxpackageboxes. +% +% It would be nice to have a \setkeys which would allow an argument +% holding an assumed tacit prefix, which here would be "box_", allowing +% the user to not have to use it and thus abbreviate the key names. +% But kvoptions does not provide it seems this on top of keyval. +% So I decided to alias all already defined options. +% - advantage: \sphinxbox options are shorter for user: no box_ prefix +% - inconventient: this \sphinxboxsetup can not customize other things +\@tfor\x:={border-width}% + {border-top-width}% + {border-right-width}% + {border-bottom-width}% + {border-left-width}% + {box-decoration-break}% + {padding}% + {padding-top}% + {padding-right}% + {padding-bottom}% + {padding-left}% + {border-radius}% + {border-top-left-radius}% + {border-top-right-radius}% + {border-bottom-right-radius}% + {border-bottom-left-radius}% + {box-shadow}% + {border-TeXcolor}% + {background-TeXcolor}% + {box-shadow-TeXcolor}% +\do{\expandafter\let\csname KV@sphinxbox@\x\expandafter\endcsname + \csname KV@sphinx@box_\x\endcsname} +\newcommand\sphinxboxsetup{\setkeys{sphinxbox}} +% some of these defaults got already set directly +\sphinxboxsetup{border-width=\fboxrule, + padding=\fboxsep, + border-radius=\fboxsep, + border-TeXcolor=VerbatimBorderColor, + background-TeXcolor=VerbatimColor,% + }% \RequirePackage{sphinxpackageboxes} \def\spx@RequirePackage@PictIIe{% \IfFileExists{pict2e.sty} diff --git a/sphinx/texinputs/sphinxpackageboxes.sty b/sphinx/texinputs/sphinxpackageboxes.sty index c894f4eed0c..5d858fc424c 100644 --- a/sphinx/texinputs/sphinxpackageboxes.sty +++ b/sphinx/texinputs/sphinxpackageboxes.sty @@ -135,6 +135,30 @@ \fi } +%%%%%%%%%%%%%%%% +% \sphinxbox (added at 6.2.0) +% +% For an inline box, possibly rounded. +\newcommand\sphinxbox[1][]{% #1 stands for the options, they are... optional! + \begingroup + \sphinxboxsetup{#1}% only "box_" options, with no "box_" prefix + \spx@boxes@fcolorbox@setup + {box} + {sphinxboxBorderColor} + {sphinxboxBgColor} + {sphinxboxShadowColor}% + \setbox0\hbox\bgroup\aftergroup\spx@boxes@sphinxbox@a + \let\next=% +} +\def\spx@boxes@sphinxbox@a{\spx@boxes@fcolorbox{\box\z@}\endgroup} + +\newcommand\newsphinxbox[2][]{% + \newcommand#2[1][]{\sphinxbox[#1,##1]}% +} +\newcommand\renewsphinxbox[2][]{% + \renewcommand#2[1][]{\sphinxbox[#1,##1]}% +} + %%%%%%%%%%%%%%%% % MACROS %