LaTeX: add \sphinxnotetitle et al.

In passing I reverted some deprecation I had added at 6bf4059 to some internals of the sphinxadmonition environment, as it does not look that pressing anyhow and the redundant namings of two colors in particular may nevertheless prove useful to user \renewcommand's, as they avoid to have to refer to \spx@noticetype.
sphinx-doc · Mar 26, 2023 · 90d298b · 90d298b
1 parent 7d65fc6
commit 90d298b
Show file tree

Hide file tree

Showing 4 changed files with 101 additions and 41 deletions.
diff --git a/CHANGES b/CHANGES
@@ -35,6 +35,9 @@ 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)
+* LaTeX: add ``\sphinxnotetitle``, ..., ``\sphinxwarningtitle``, ..., for
+  an extra layer of mark-up freeing up ``\sphinxstrong`` for other uses.
+  See :ref:`latex-macros`.
 * LaTeX: :dudir:`note`, :dudir:`hint`, :dudir:`important` and :dudir:`tip` can
   now each be styled as the other admonitions, i.e. possibly with a background
   color, individual border widths and paddings, possibly rounded corners, and
@@ -58,7 +61,7 @@ Bugs fixed
   respective to contents (when using rounded corners)
 * #11235: LaTeX: added ``\color`` in topic (or admonition) contents may cause color
   leak to the shadow and border at a page break
-* #11264: LaTeX: missing space before colon after "Voir aussi" for :dudir:`seealso`
+* #11264: LaTeX: missing space before colon after "Voir aussi" for :rst:dir:`seealso`
   directive in French (refs: #6744)
 * #11147: Fix source file/line number info in object description content and in
   other uses of ``nested_parse_with_titles``.  Patch by Jeremy Maitin-Shepard.

diff --git a/doc/latex.rst b/doc/latex.rst
@@ -1464,6 +1464,16 @@ Macros
      ``\sphinxsamedocref``;     ``\emph{#1}``
      ``\sphinxparam``;          ``\emph{#1}``
      ``\sphinxoptional``; ``[#1]`` with larger brackets, see source
+     ``\sphinxnotetitle``;      ``\sphinxstrong{#1}<space>``
+     ``\sphinxhinttitle``;      *idem*
+     ``\sphinximportanttitle``; *idem*
+     ``\sphinxtiptitle``;       *idem*
+     ``\sphinxwarningtitle``;   *idem*
+     ``\sphinxcautiontitle``;   *idem*
+     ``\sphinxattentiontitle``; *idem*
+     ``\sphinxdangertitle``;    *idem*
+     ``\sphinxerrortitle``;     *idem*
+     ``\sphinxseealsotitle``;   ``\sphinxstrong{#1}\par\nopagebreak``
 
   .. versionadded:: 1.4.5
      Use of ``\sphinx`` prefixed macro names to limit possibilities of conflict
@@ -1478,6 +1488,17 @@ Macros
   .. versionadded:: 6.2.0
      ``\sphinxparam``, ``\sphinxsamedocref``
 
+  .. versionadded:: 6.2.0
+     ``\sphinxnotetitle`` et al.  The ``#1`` is the localized name of the
+     directive, with a final colon.  Wrap it as ``\sphinxremovefinalcolon{#1}``
+     if this final colon is to be removed.  Example:
+
+     .. code-block:: latex
+
+        \renewcommand\sphinxwarningtitle[1]{%
+          \underline{\textbf{\sphinxremovefinalcolon{#1}}}\par
+        }
+
 - More text styling:
 
   .. csv-table::

diff --git a/sphinx/texinputs/sphinxlatexadmonitions.sty b/sphinx/texinputs/sphinxlatexadmonitions.sty
@@ -23,31 +23,36 @@
 \RequirePackage{framed}% used by sphinxheavybox
 %
 % Dependencies (they do not need to be defined at time of loading):
+%
 % - of course the various colour and dimension options handled via sphinx.sty
+%
 % - \sphinxstrong (for sphinxlightbox and sphinxheavybox)
+%
 % - dimension register \spx@image@maxheight from sphinxlatexgraphics.sty
+%
 % - \savenotes/\spewnotes from sphinxpackagefootnote (for sphinxheavybox)
+%
+% - \sphinxnotetitle, ..., \sphinxwarningtitle, etc... which are used by
+%   default in the corresponding sphinx<notice> environments to replace at 6.2.0
+%   formerly hard-coded \sphinxstrong{#1}<space>
+%   Their definitions are in sphinxlatexstyletext.sty.  Also \sphinxseealsotitle
+
 
 % Provides: (also in sphinxlatexliterals.sty)
 \providecommand*\sphinxvspacefixafterfrenchlists{%
    \ifvmode\ifdim\lastskip<\z@ \vskip\parskip\fi\else\par\fi
 }
 
 % Some are quite plain
-\newenvironment{sphinxseealso}[1]{\sphinxstrong{#1}\par\nopagebreak}{}
+\newenvironment{sphinxseealso}[1]{\sphinxseealsotitle{#1}}{}
 
 % This \dimen register is a legacy relic from Sphinx 1.5 which is used now
 % only for sphinxlightbox.  It is set in the sphinxadmonition environment.
 \newdimen\spx@notice@border
 
-% 6.2.0: add support for the <type>_TeXcolor options for text color.
-% 6.2.0: use directly sphinx<type>BorderColor, not spx@notice@bordercolor,
-%        as the latter will probably be removed altogether at 7.0.0
 \newenvironment{sphinxlightbox}{%
-  % done in sphinxadmonition but its place should be here
-  % \spx@notice@border \dimexpr\csname spx@\spx@noticetype @border\endcsname\relax
   \par
-  \noindent{\color{sphinx\spx@noticetype BorderColor}%
+  \noindent{\color{spx@notice@bordercolor}%
             \rule{\linewidth}{\spx@notice@border}}%
   \par\nobreak
   {\parskip\z@skip\noindent}%
@@ -57,7 +62,7 @@
   % (we can't cancel that any earlier \vskip introduced a potential pagebreak)
   \sphinxvspacefixafterfrenchlists
   \nobreak\vbox{\noindent\kern\@totalleftmargin
-      {\color{sphinx\spx@noticetype BorderColor}%
+      {\color{spx@notice@bordercolor}%
        \rule[\dimexpr.4\baselineskip-\spx@notice@border\relax]
              {\linewidth}{\spx@notice@border}}\hss}\allowbreak
   }% end of sphinxlightbox environment definition
@@ -72,33 +77,36 @@
 % \newenvironment{sphinxhint}[1]
 %   {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
 %
-% It was possible for user to \renewenvironment this to use sphinxheavybox,
-% but this had stopped functioning at 5.1.0 which had greatly enhanced the
-% sphinxheavybox environment and the needed support macros existed only for
-% warning, caution, attention, danger, and error admonitions.  At 6.1.0 a
-% patch was added to allow the \renewenvironment method to work again for
-% note, hint, important, tip to use sphinxheavybox.
-%
-% Then at 6.2.0, note, hint, important, tip can now access full customization
-% of sphinxheavybox: CSS-named alike options (if used) trigger sphinxheavybox.
-% The \renewenvironment method still works but then only common border width,
-% non-configurable padding, straight corners and no shadow are all implied,
-% as long as the related CSS-named options are not used.
+% The more complex definition below will branch to sphinxheavybox if a certain
+% boolean associated to the notice type is true.  This boolean is set to true
+% whenever a CSS-named alike options for the notice type has been used in
+% sphinxsetup.  The old coding as above would still work, but then the new
+% options are simply ignored.  A user redefinition will probably either use
+% directly sphinxlightbox or sphinxheavybox or something else, no need to test
+% the boolean.
+%
+% 6.2.0 also adds one layer of mark-up via \sphinxnotetitle etc..., because
+% the former \sphinxstrong{#1}<space> used a too generic \sphinxstrong.  But
+% perhaps the #1 should be passed over to sphinx{light,heavy}box as parameter.
+% Unfortunately replacing these environments with one-parameter environments
+% is a potentially breaking change.  Anyway, the sphinxpackageboxes do not
+% provided a "titled" box, e.g. the caption of code-blocks is handled by extra
+% code in sphinxVerbatim.
 \newenvironment{sphinxnote}[1]
   {\edef\spx@env{sphinx\ifspx@opt@heavynote heavy\else light\fi box}%
-   \expandafter\begin\expandafter{\spx@env}\sphinxstrong{#1} }
+   \expandafter\begin\expandafter{\spx@env}\sphinxnotetitle{#1}}
   {\expandafter\end\expandafter{\spx@env}}
 \newenvironment{sphinxhint}[1]
   {\edef\spx@env{sphinx\ifspx@opt@heavyhint heavy\else light\fi box}%
-   \expandafter\begin\expandafter{\spx@env}\sphinxstrong{#1} }
+   \expandafter\begin\expandafter{\spx@env}\sphinxhinttitle{#1}}
   {\expandafter\end\expandafter{\spx@env}}
 \newenvironment{sphinximportant}[1]
   {\edef\spx@env{sphinx\ifspx@opt@heavyimportant heavy\else light\fi box}%
-   \expandafter\begin\expandafter{\spx@env}\sphinxstrong{#1} }
+   \expandafter\begin\expandafter{\spx@env}\sphinximportanttitle{#1}}
   {\expandafter\end\expandafter{\spx@env}}
 \newenvironment{sphinxtip}[1]
   {\edef\spx@env{sphinx\ifspx@opt@heavytip heavy\else light\fi box}%
-   \expandafter\begin\expandafter{\spx@env}\sphinxstrong{#1} }
+   \expandafter\begin\expandafter{\spx@env}\sphinxtiptitle{#1}}
   {\expandafter\end\expandafter{\spx@env}}
 
 % warning/caution/attention/danger/error  get more distinction
@@ -193,31 +201,35 @@
 % - Since 6.2.0, also note/hint/important/tip notices can use these options
 % and then they go automatically via sphinxheavybox.  If only the legacy options
 % are used, they keep using sphinxlightbox.
+%
+% - Since 6.2.0, \sphinxwarningtitle etc... add one level of mark-up (they
+% expand to \sphinxstrong{#1}<space> which was former hard-coded mark-up).
+% Example:
+% \renewcommand{\sphinxwarningtitle}[1]{\textbf{#1}\par\smallskip
+%   {\color{sphinxwarningBorderColor}\hrule height1pt}\smallskip}
 \newenvironment{sphinxwarning}[1]
-  {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
+  {\begin{sphinxheavybox}\sphinxwarningtitle{#1}}{\end{sphinxheavybox}}
 \newenvironment{sphinxcaution}[1]
-  {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
+  {\begin{sphinxheavybox}\sphinxcautiontitle{#1}}{\end{sphinxheavybox}}
 \newenvironment{sphinxattention}[1]
-  {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
+  {\begin{sphinxheavybox}\sphinxattentiontitle{#1}}{\end{sphinxheavybox}}
 \newenvironment{sphinxdanger}[1]
-  {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
+  {\begin{sphinxheavybox}\sphinxdangertitle{#1}}{\end{sphinxheavybox}}
 \newenvironment{sphinxerror}[1]
-  {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
+  {\begin{sphinxheavybox}\sphinxerrortitle{#1}}{\end{sphinxheavybox}}
 
 % the main dispatch for all types of notices
 \newenvironment{sphinxadmonition}[2]{% #1=type, #2=heading
   % can't use #1 directly in definition of end part
   \def\spx@noticetype {#1}%
-      % At 6.2.0, these definitions of spx@notice@bordercolor and
-      % spx@notice@bgcolor serve nothing at all for sphinxheavybox.  And the
-      % sphinxlightbox uses sphinx<type>BorderColor directly.  Not removing
-      % though, in case some people have redefined sphinxlightbox (or even
-      % sphinxheavybox) and expect these things to exist.
-      %
-      % This is marked for removal at 7.0.0.
-      \sphinxcolorlet{spx@notice@bordercolor}{sphinx#1BorderColor}%
-      \sphinxcolorlet{spx@notice@bgcolor}{sphinx#1BgColor}%
-      \spx@notice@border \dimexpr\csname spx@#1@border\endcsname\relax
+  % those next three are a remnant of legacy code; they are not used at
+  % all by sphinxheavybox, and their usage could be disposed of by sphinxlightbox
+  % but we keep for backward compatibility and also because it may be simpler
+  % for user redefinitions to employ for example "spx@notice@bgcolor" and not
+  % the more bulky "sphinx\spx@noticetype BgColor".
+  \sphinxcolorlet{spx@notice@bordercolor}{sphinx#1BorderColor}%
+  \sphinxcolorlet{spx@notice@bgcolor}{sphinx#1BgColor}%
+  \spx@notice@border \dimexpr\csname spx@#1@border\endcsname\relax
   % trigger the sphinx<type> environment, #2=heading is passed as argument
   \begin{sphinx#1}{#2}%
   % 6.2.0 support of div.<type>_TeX{color,extras} options

diff --git a/sphinx/texinputs/sphinxlatexstyletext.sty b/sphinx/texinputs/sphinxlatexstyletext.sty
@@ -1,11 +1,35 @@
 %% TEXT STYLING
 %
 % change this info string if making any custom modification
-\ProvidesFile{sphinxlatexstyletext.sty}[2022/07/02 text styling]
+\ProvidesFile{sphinxlatexstyletext.sty}[2023/03/26 text styling]
 
 % Basically everything here consists of macros which are part of the latex
 % markup produced by the Sphinx latex writer
 
+% But those arise rather from default defintions of the respective
+% notice-related latex environments in sphinxlatexadmonitions.sty
+\def\sphinxnotetitle#1{\sphinxstrong{#1} }
+\let\sphinxhinttitle     \sphinxnotetitle % #1 holds the localized notice name
+\let\sphinximportanttitle\sphinxnotetitle
+\let\sphinxtiptitle      \sphinxnotetitle
+\let\sphinxwarningtitle  \sphinxnotetitle
+\let\sphinxcautiontitle  \sphinxnotetitle
+\let\sphinxattentiontitle\sphinxnotetitle
+\let\sphinxdangertitle   \sphinxnotetitle
+\let\sphinxerrortitle    \sphinxnotetitle
+\def\sphinxseealsotitle#1{\sphinxstrong{#1}\par\nopagebreak}
+%
+% A utility to remove a final colon
+% (one must be certain the semi-colon is there)
+\protected\def\sphinxremovefinalcolon #1{%
+   % complications due to : possibly "active"
+   \begingroup\ifnum\catcode`:=\active
+                    \lccode`~=`:\lowercase{\def\x##1~}{##1}%
+               \else\def\x##1:{##1}\fi
+   \expandafter\endgroup\x#1%
+}%
+% See doc/latex.rst for an example.
+
 % Some custom font markup commands.
 \protected\def\sphinxstrong#1{\textbf{#1}}
 \protected\def\sphinxcode#1{\texttt{#1}}