From 90d298bdb6755a32d83f02e162d8127ef9a0e606 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Sun, 26 Mar 2023 20:05:07 +0200 Subject: [PATCH] LaTeX: add \sphinxnotetitle et al. In passing I reverted some deprecation I had added at 6bf40599e 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. --- CHANGES | 5 +- doc/latex.rst | 21 +++++ sphinx/texinputs/sphinxlatexadmonitions.sty | 90 ++++++++++++--------- sphinx/texinputs/sphinxlatexstyletext.sty | 26 +++++- 4 files changed, 101 insertions(+), 41 deletions(-) diff --git a/CHANGES b/CHANGES index 5a2749ba4b4..db25ab557ae 100644 --- 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 index 08b2ace85e3..38e24a7abc8 100644 --- 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}`` + ``\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 index b1f29c7188b..4d23898a34a 100644 --- a/sphinx/texinputs/sphinxlatexadmonitions.sty +++ b/sphinx/texinputs/sphinxlatexadmonitions.sty @@ -23,10 +23,20 @@ \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 environments to replace at 6.2.0 +% formerly hard-coded \sphinxstrong{#1} +% Their definitions are in sphinxlatexstyletext.sty. Also \sphinxseealsotitle + % Provides: (also in sphinxlatexliterals.sty) \providecommand*\sphinxvspacefixafterfrenchlists{% @@ -34,20 +44,15 @@ } % 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 _TeXcolor options for text color. -% 6.2.0: use directly sphinxBorderColor, 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} 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} 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 sphinxBorderColor 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 environment, #2=heading is passed as argument \begin{sphinx#1}{#2}% % 6.2.0 support of div._TeX{color,extras} options diff --git a/sphinx/texinputs/sphinxlatexstyletext.sty b/sphinx/texinputs/sphinxlatexstyletext.sty index b6a320a4a6d..c828a909701 100644 --- 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}}