LaTeX: add <prefix>_{TeXcolor,TeXextras} options

And add <type>TextColor and <type>TeXextras for <type>=hint, important, note, tip for variants which do not trigger for sphinxheavybox but still uses sphinxlightbox (suitably enhanced). Similar named TeXcolor and TeXextras options for \sphinxbox.
sphinx-doc · Mar 19, 2023 · 6bf4059 · 6bf4059
1 parent 0194aae
commit 6bf4059
Show file tree

Hide file tree

Showing 7 changed files with 206 additions and 71 deletions.
diff --git a/CHANGES b/CHANGES
@@ -15,6 +15,11 @@ Incompatible changes
 Deprecated
 ----------
 
+* LaTeX: some internals of the ``sphinxadmonition`` environment have been
+  marked for removal at 7.0.0 in the :file:`sphinxlatexadmonitions.sty`.
+  Custom re-definitions of ``sphinxlightbox`` or ``sphinxheavybox`` will have
+  to be updated if they depended upon them.
+
 Features added
 --------------
 

diff --git a/doc/latex.rst b/doc/latex.rst
@@ -1032,6 +1032,29 @@ Do not use quotes to enclose values, whether numerical or strings.
 
     .. versionadded:: 6.2.0
 
+|notetextcolors|
+    The optional color for the contents.
+
+    Default: unset (uses ambient text color, a priori black)
+
+    .. versionadded:: 6.2.0
+
+       To be considered experimental until 7.0.0.  These options have aliases
+       ``div.note_TeXcolor`` (etc) described in :ref:`additionalcss`.  Using
+       the latter will let Sphinx switch to a more complex LaTeX code,
+       which supports the customizability described in :ref:`additionalcss`.
+
+|notetexextras|
+    Some extra LaTeX code (such as ``\bfseries``  or ``\footnotesize``)
+    to be executed at start of the contents.
+
+    Default: empty
+
+    .. versionadded:: 6.2.0
+
+       To be considered experimental until 7.0.0.  These options have aliases
+       ``div.note_TeXextras`` (etc) described in :ref:`additionalcss`.
+
 ``noteborder``, ``hintborder``, ``importantborder``, ``tipborder``
     The width of the two horizontal rules.
 
@@ -1093,6 +1116,12 @@ Do not use quotes to enclose values, whether numerical or strings.
 .. |notebgcolors| replace:: ``noteBgColor``, ``hintBgColor``,
                             ``importantBgColor``, ``tipBgColor``
 
+.. |notetextcolors| replace:: ``noteTextColor``, ``hintTextColor``,
+                            ``importantTextColor``, ``tipTextColor``
+
+.. |notetexextras| replace:: ``noteTeXextras``, ``hintTeXextras``,
+                            ``importantTeXextras``, ``tipTeXextras``
+
 .. |warningbdcolors| replace:: ``warningBorderColor``, ``cautionBorderColor``,
                                ``attentionBorderColor``, ``dangerBorderColor``,
                                ``errorBorderColor``
@@ -1129,14 +1158,6 @@ Additional  CSS-like ``'sphinxsetup'`` keys
    ``noteBgColor`` (or ``hintBgColor``, ...) also triggers usage of
    ``sphinxheavybox`` for :dudir:`note` (or :dudir:`hint`, ...).
 
-.. versionadded:: 6.2.0
-
-   All "admonition" directives as well as :dudir:`topic` and contents_ now
-   support their respective ``box-decoration-break`` to be set to ``slice``.
-   Formerly, only :rst:dir:`code-block` did.  It is undecided though if this
-   should inhibit the display of a bottom shadow, if set.  Currently the shadow,
-   if set, is shown nevertheless but this is to be considered unstable.
-
 Perhaps in future these 5.1.0 (and 6.2.0) novel settings will be optionally
 imported from some genuine CSS external file, but currently they have to be used
 via the ``'sphinxsetup'`` interface (or the ``\sphinxsetup`` LaTeX command
@@ -1260,7 +1281,8 @@ forget the underscore separating the prefix from the property names.
   margin.
 - | ``<prefix>_border-TeXcolor``,
   | ``<prefix>_background-TeXcolor``,
-  | ``<prefix>_box-shadow-TeXcolor``.
+  | ``<prefix>_box-shadow-TeXcolor``,
+  | ``<prefix>_TeXcolor``.
     These are colors.
 
   The shadow color defaults in all cases to ``{rgb}{0,0,0}`` i.e. to black.
@@ -1272,21 +1294,63 @@ forget the underscore separating the prefix from the property names.
   For all other types, the border color defaults to black and the background
   color to white.
 
+  The ``<prefix>_TeXcolor`` stands for the CSS property "color", i.e. it
+  influences the text color of the contents.  As for the three other options,
+  the naming ``TeXcolor`` is to stress that the input syntax is the TeX one
+  for colors not an HTML/CSS one.  If set, a ``\color`` command is inserted at
+  start of the directive contents; for admonitions, this happens after the
+  heading which reproduces the admonition type.
+
+- ``<prefix>_TeXextras``: if set, its value must be some LaTeX command or
+  commands, for example ``\itshape``.  These commands will be inserted at the
+  start of the contents; for admonitions, this happens after the heading which
+  reproduces the admonition type.
+
 .. note::
 
-   - Prior to 6.2.0, rounded corners forced a constant border width, the
+   - All directives support ``box-decoration-break`` to be set to ``slice``.
+
+     .. versionchanged:: 6.2.0
+
+        Formerly, only :rst:dir:`code-block` did.  The default remains
+        ``clone`` for all other directives, but this will probably change at
+        7.0.0.
+
+   - Prior to 6.2.0, rounded corners forced a constant border width: the
      separate settings were ignored in favor of the sole
      ``<prefix>_border-width``.  Now (up to) 4 distinct radii happily cohabit
      with (up to) 4 distinct border widths.
 
-   - Inset shadows are currently incompatible with rounded corners.  In case
+   - Inset shadows are incompatible with rounded corners.  In case
      both are specified the inset shadow will simply be ignored.
 
      .. versionchanged:: 6.2.0
 
         Formerly it was to the contrary the rounded corners which were ignored
         in case an inset shadow was specified.
 
+   - ``<prefix>_TeXcolor`` and ``<prefix>_TeXextras`` are new with 6.2.0.
+
+     Usefulness is doubtful in the case of :rst:dir:`code-block`:
+
+     - ``pre_TeXcolor`` will influence only the few non-Pygments highlighted
+       tokens; it does color the line numbers, but if one wants to color
+       *only* them one has to go through the ``fancyvrb`` interface.
+
+     - ``pre_TeXextras=\footnotesize`` for example may be replaced by usage of
+       the :confval:`latex_elements` key ``'fvset'``.  For ``'lualatex'`` or
+       ``'xelatex'`` Sphinx includes in the preamble already
+       ``\fvset{fontsize=\small}`` and this induces ``fancyvrb`` into
+       overriding a ``\footnotesize`` coming from ``pre_TeXextras``.  One has
+       to use ``pre_TeXextras=\fvset{fontsize=\footnotesize}`` syntax.
+       Simpler to set directly the :confval:`latex_elements` key
+       ``'fvset'``...
+
+     Consider these options experimental and that some implementation details
+     may change.  For example if the ``pre_TeXextras`` LaTeX commands were put
+     by Sphinx in another location it could override the ``'fvset'`` effect,
+     perhaps this is what will be done in a future release.
+
    - Rounded boxes are done using the pict2e_ interface to some basic PDF
      graphics operations.  If this LaTeX package can not be found the build
      will proceed and render all boxes with straight corners.
@@ -1553,14 +1617,16 @@ Here is the complete list of keys:
   ``border-bottom-right-radius``, ``border-bottom-left-radius``,
 - ``box-shadow``,
 - ``border-TeXcolor``, ``background-TeXcolor``, ``box-shadow-TeXcolor``,
+  ``TeXcolor``,
+- ``TeXextras``,
 - and ``addstrut`` which is a boolean key, i.e. to be used as ``addstrut=true``,
   or ``addstrut`` alone where ``=true`` is omitted, or ``addstrut=false``.
 
 This last key is specific to ``\sphinxbox`` and it means to add a ``\strut``
 so that heights and depths are equalized across various instances,
 independently of text content.  The combination ``addstrut,
 padding-bottom=0pt, padding-top=1pt``  is often satisfactory.  The default is
-``addstrut=false``.e
+``addstrut=false``.
 
 Refer to :ref:`additionalcss` for important syntax information regarding the
 other keys.  The default
@@ -1578,43 +1644,40 @@ The effect is cumulative, if one uses this command multiple times.  Here the
 options are a mandatory argument so are within curly braces, not square
 brackets.
 
-   The comma separated key-value list is to be used within curly braces with
-   ``\sphinxsetup`` (keys must then be prefixed with ``box_``) or
-   ``\sphinxboxsetup``.  In contrast key-value options given to ``\sphinxbox``
-   must be within square brackets, are they are... options.  See examples
-   below.
-
-A utility ``\newsphinxbox`` is provided to create a new boxing macro, say
-``\foo`` which will act exactly like ``\sphinxbox`` but with a possibly
-different set of initial default option values.  Here is some example:
+Here is some 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}}}
+   % modify globally the defaults
+   \sphinxboxsetup{border-width=2pt,%
+                   border-radius=4pt,%
+                   background-TeXcolor=yellow!20}
+   % configure some styling element with some extra specific options:
+   \protected\def\sphinxkeyboard#1{\sphinxbox[border-TeXcolor=green]{\sphinxcode{#1}}}
    ''',
    }
 
-In the above example, you can probably use ``\renewcommand`` syntax if you
-prefer (with ``[1]`` in place of ``#1`` then).  There is also
-``\renewsphinxbox`` which one can imagine inserting in the midst of a document
-via the :dudir:`raw` directive, so that from that point on, all the custom
-text elements using ``\foo`` will start using re-defined box parameters,
-without having to redefine for example ``\sphinxguilabel`` as it already uses
-``\foo``.
+A utility ``\newsphinxbox`` is provided to create a new boxing macro, say
+``\foo`` which will act exactly like ``\sphinxbox`` but with a given extra
+configuration:
+
+.. code-block:: latex
+
+   % the specific options to \foo are within brackets
+   \newsphinxbox[border-radius=0pt, box-shadow=2pt 2pt]{\foo}
+   % then use this \foo, possibly with some extra options still:
+   \protected\def\sphinxguilabel#1{\foo{#1}}
+   \protected\def\sphinxmenuselection#1{\foo[box-shadow-TeXcolor=gray]{#1}}
+
+Boxes rendered with ``\foo`` obey as the ones using directly ``\sphinxbox``
+the current configuration as set possibly mid-way in document via
+``\sphinxboxsetup`` (from a :dudir:`raw` LaTeX mark-up), the only difference
+is that they have an initial additional set of default extras.
+
+In the above examples, you can probably use ``\renewcommand`` syntax if you
+prefer it to ``\protected\def`` (with ``[1]`` in place of ``#1`` then).
 
 
 Environments

diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty
@@ -565,7 +565,7 @@ will be set to white}%
 }%
 
 % Color keys
-% (three of them: border, background, shadow)
+% (four of them: border, background, shadow and the text color)
 %
 % Some problems due to legacy naming scheme which had diverging conventions
 % for code-blocks (VerbatimBorderColor, VerbatimColor) and admonitions
@@ -591,9 +591,10 @@ will be set to white}%
   \expandafter\spx@tempb
   \csname if#1withshadowcolor\expandafter\endcsname
   \csname if#1withbordercolor\expandafter\endcsname
-  \csname if#1withbackgroundcolor\endcsname
+  \csname if#1withbackgroundcolor\expandafter\endcsname
+  \csname if#1withtextcolor\endcsname
 }%
-\def\spx@tempb#1#2#3{\newif#1\newif#2\newif#3}%
+\def\spx@tempb#1#2#3#4{\newif#1\newif#2\newif#3\newif#4}%
 %          macro prefix
 \spx@tempa{spx@pre@}
 \spx@tempa{spx@topic@}
@@ -612,15 +613,18 @@ will be set to white}%
   \expandafter\spx@tempb
   \csname #1withbordercolortrue\expandafter\endcsname
   \csname #1withbackgroundcolortrue\expandafter\endcsname
-  \csname #1withshadowcolortrue\endcsname
+  \csname #1withshadowcolortrue\expandafter\endcsname
+  \csname #1withtextcolortrue\endcsname
 }
-\def\spx@tempb#1#2#3#4#5{% #4 = option prefix, #5 = color name prefix
-  \define@key{sphinx}{#4border-TeXcolor}%
-     {#1\spx@defineorletcolor{#5BorderColor}##1\relax}%
-  \define@key{sphinx}{#4background-TeXcolor}%
-     {#2\spx@defineorletcolor{#5BgColor}##1\relax}%
-  \define@key{sphinx}{#4box-shadow-TeXcolor}%
-     {#3\spx@defineorletcolor{#5ShadowColor}##1\relax}%
+\def\spx@tempb#1#2#3#4#5#6{% #5 = option prefix, #6 = color name prefix
+  \define@key{sphinx}{#5border-TeXcolor}%
+     {#1\spx@defineorletcolor{#6BorderColor}##1\relax}%
+  \define@key{sphinx}{#5background-TeXcolor}%
+     {#2\spx@defineorletcolor{#6BgColor}##1\relax}%
+  \define@key{sphinx}{#5box-shadow-TeXcolor}%
+     {#3\spx@defineorletcolor{#6ShadowColor}##1\relax}%
+  \define@key{sphinx}{#5TeXcolor}%
+     {#4\spx@defineorletcolor{#6TextColor}##1\relax}%
 }
 %          macro prefix    option prefix    color name prefix
 \spx@tempa{spx@pre@}      {pre_}            {Verbatim}
@@ -662,9 +666,44 @@ will be set to white}%
     \spx@tempa{div.error_}      {error}
 
     % Keep legacy sphinxsetup <type>BorderColor for <type>=note, hint, ...
+    % which will not trigger sphinxheavybox
+    % Add "legacy" hintTextColor etc... that will not trigger sphinxheavybox
     \def\spx@tempa#1#2{% #1 = CSS like option prefix, #2 = legacy option prefix
       \expandafter\let\csname KV@sphinx@#2BorderColor\expandafter\endcsname
                       \csname KV@sphinx@#1border-TeXcolor\endcsname
+      \expandafter\let\csname KV@sphinx@#2TextColor\expandafter\endcsname
+                      \csname KV@sphinx@#1TeXcolor\endcsname
+    }
+    \spx@tempa{div.note_}       {note}
+    \spx@tempa{div.hint_}       {hint}
+    \spx@tempa{div.important_}  {important}
+    \spx@tempa{div.tip_}        {tip}
+
+% The TeXextras key
+%
+\def\spx@tempa#1{% #1 = macro prefix
+  \expandafter\spx@tempb\csname #1TeXextras\endcsname
+}
+\def\spx@tempb#1#2{% #2 = option prefix
+  \define@key{sphinx}{#2TeXextras}{\def#1{##1}}%
+}
+%          macro prefix   option prefix
+\spx@tempa{spx@pre@}      {pre_}
+\spx@tempa{spx@topic@}    {div.topic_}
+\spx@tempa{spx@note@}     {div.note_}
+\spx@tempa{spx@hint@}     {div.hint_}
+\spx@tempa{spx@important@}{div.important_}
+\spx@tempa{spx@tip@}      {div.tip_}
+\spx@tempa{spx@warning@}  {div.warning_}
+\spx@tempa{spx@caution@}  {div.caution_}
+\spx@tempa{spx@attention@}{div.attention_}
+\spx@tempa{spx@danger@}   {div.danger_}
+\spx@tempa{spx@error@}    {div.error_}
+\spx@tempa{spx@box@}      {box_}
+    % Add "legacy" hintTeXextras etc... that will not trigger sphinxheavybox
+    \def\spx@tempa#1#2{% #1 = CSS like option prefix, #2 = legacy option prefix
+      \expandafter\let\csname KV@sphinx@#2TeXextras\expandafter\endcsname
+                      \csname KV@sphinx@#1TeXextras\endcsname
     }
     \spx@tempa{div.note_}       {note}
     \spx@tempa{div.hint_}       {hint}
@@ -678,7 +717,7 @@ will be set to white}%
 % re-created and they do not trigger the "heavybox" as their meaning will not
 % be modified in the loop below contrarily to their CSS counterparts
 % div.note_border-TeXcolor and div.note_border-width, and to the noteBgColor
-% next.
+% etc... which are handled below.
 %
 % This goes via rather hardcore TeX here.
 \def\spx@tempa#1{\if\relax#1\expandafter\@gobble
@@ -712,13 +751,15 @@ will be set to white}%
           {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}%
+          {border-TeXcolor}{background-TeXcolor}{box-shadow-TeXcolor}{TeXcolor}%
+          {TeXextras}%
 \relax
 
 % Now we add at 6.2.0 <type>BgColor et al. options which will trigger the
 % "heavybox" as they are \let to the div.<type>_background-TeXColor option
 % which has already been enhanced to set the boolean for rendering via
-% "heavybox".  This is in contrast with legacy <type>BorderColor.
+% "heavybox".  This is in contrast with legacy <type>BorderColor,
+% and with the new <type>TeXcolor and <type>TeXextras.
     \def\spx@tempa#1#2{% #1 = CSS like option prefix, #2 = legacy style option prefix
       \expandafter\let\csname KV@sphinx@#2BgColor\expandafter\endcsname
                       \csname KV@sphinx@#1background-TeXcolor\endcsname
@@ -854,8 +895,8 @@ will be set to white}%
           {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}%
-          {addstrut}{addstrut@default}%
+          {border-TeXcolor}{background-TeXcolor}{box-shadow-TeXcolor}{TeXcolor}%
+          {TeXextras}{addstrut}{addstrut@default}%
 \do{\expandafter\let\csname KV@sphinxbox@\x\expandafter\endcsname
                     \csname KV@sphinx@box_\x\endcsname}
 % Let \sphinxboxsetup also prepare a "reset", which will be used by nested
@@ -889,6 +930,7 @@ will be set to white}%
                 border-TeXcolor={RGB}{32,32,32},%  the default VerbatimBorderColor
                 background-TeXcolor={gray}{0.95},% the default VerbatimColor
                 box-shadow-TeXcolor={rgb}{0,0,0},%
+                TeXextras={},%
                 addstrut=false% (a final comma here would not hurt)
                }%
 \RequirePackage{sphinxpackageboxes}