From 8f9bac9c4f5d399f8085870dd30570aa32bbf48a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Mon, 27 Mar 2023 14:54:41 +0200 Subject: [PATCH] LaTeX: rename ``\sphinxnotetitle`` into ``\sphinxstylenotetitle`` (etc) Follow-up to #11266. Using \sphinxstyle prefix looked a posteriori better, for coherency, although it is a bit long. --- CHANGES | 6 +- doc/latex.rst | 97 ++++++++++----------- sphinx/texinputs/sphinxlatexadmonitions.sty | 26 +++--- sphinx/texinputs/sphinxlatexstyletext.sty | 20 ++--- 4 files changed, 73 insertions(+), 76 deletions(-) diff --git a/CHANGES b/CHANGES index 4f78b39610a..85c36f618bb 100644 --- a/CHANGES +++ b/CHANGES @@ -35,9 +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`. (refs: #11266) +* LaTeX: add ``\sphinxstylenotetitle``, ..., ``\sphinxstylewarningtitle``, ..., + for an extra layer of mark-up freeing up ``\sphinxstrong`` for other uses. + See :ref:`latex-macros`. (refs: #11267) * 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 diff --git a/doc/latex.rst b/doc/latex.rst index 90420f6154a..5da029a0f1a 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -1464,16 +1464,6 @@ 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 @@ -1488,27 +1478,6 @@ 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 - } - \renewcommand{\sphinxnotetitle}[1]{% - \textit{\textbf{\sphinxremovefinalcolon{#1}}}\par\nobreak - % LaTeX syntax is complex and we would be better off using \hrule here. - {\parskip0pt\noindent}% - \raisebox{1ex}% - {\makebox[\linewidth]{\textcolor{sphinxnoteBorderColor}{\dotfill}}} - % It is complex to obtain nice vertical spacing for both a paragraph or - % a list following up; this set-up is better for a text paragraph next. - \par\vskip-\parskip - } - - More text styling: .. csv-table:: @@ -1516,25 +1485,35 @@ Macros :align: left :delim: ; - ``\sphinxstyleindexentry``; ``\texttt{#1}`` - ``\sphinxstyleindexextra``; ``(\emph{#1})`` (with a space upfront) - ``\sphinxstyleindexpageref``; ``, \pageref{#1}`` - ``\sphinxstyleindexpagemain``; ``\textbf{#1}`` - ``\sphinxstyleindexlettergroup``; ``{\Large\sffamily#1}\nopagebreak\vspace{1mm}`` + ``\sphinxstyleindexentry``; ``\texttt{#1}`` + ``\sphinxstyleindexextra``; ``(\emph{#1})`` (with a space upfront) + ``\sphinxstyleindexpageref``; ``, \pageref{#1}`` + ``\sphinxstyleindexpagemain``; ``\textbf{#1}`` + ``\sphinxstyleindexlettergroup``; ``{\Large\sffamily#1}\nopagebreak\vspace{1mm}`` ``\sphinxstyleindexlettergroupDefault``; check source, too long for here - ``\sphinxstyletopictitle``; ``\textbf{#1}\par\medskip`` - ``\sphinxstylesidebartitle``; ``\textbf{#1}\par\medskip`` - ``\sphinxstyleothertitle``; ``\textbf{#1}`` - ``\sphinxstylesidebarsubtitle``; ``~\\\textbf{#1} \smallskip`` - ``\sphinxstyletheadfamily``; ``\sffamily`` (*this one has no argument*) - ``\sphinxstyleemphasis``; ``\emph{#1}`` - ``\sphinxstyleliteralemphasis``; ``\emph{\sphinxcode{#1}}`` - ``\sphinxstylestrong``; ``\textbf{#1}`` - ``\sphinxstyleliteralstrong``; ``\sphinxbfcode{#1}`` - ``\sphinxstyleabbreviation``; ``\textsc{#1}`` - ``\sphinxstyleliteralintitle``; ``\sphinxcode{#1}`` - ``\sphinxstylecodecontinued``; ``{\footnotesize(#1)}}`` - ``\sphinxstylecodecontinues``; ``{\footnotesize(#1)}}`` + ``\sphinxstyletopictitle``; ``\textbf{#1}\par\medskip`` + ``\sphinxstylesidebartitle``; ``\textbf{#1}\par\medskip`` + ``\sphinxstyleothertitle``; ``\textbf{#1}`` + ``\sphinxstylesidebarsubtitle``; ``~\\\textbf{#1} \smallskip`` + ``\sphinxstyletheadfamily``; ``\sffamily`` (*this one has no argument*) + ``\sphinxstyleemphasis``; ``\emph{#1}`` + ``\sphinxstyleliteralemphasis``; ``\emph{\sphinxcode{#1}}`` + ``\sphinxstylestrong``; ``\textbf{#1}`` + ``\sphinxstyleliteralstrong``; ``\sphinxbfcode{#1}`` + ``\sphinxstyleabbreviation``; ``\textsc{#1}`` + ``\sphinxstyleliteralintitle``; ``\sphinxcode{#1}`` + ``\sphinxstylecodecontinued``; ``{\footnotesize(#1)}}`` + ``\sphinxstylecodecontinues``; ``{\footnotesize(#1)}}`` + ``\sphinxstylenotetitle``; ``\sphinxstrong{#1}`` + ``\sphinxstylehinttitle``; *idem* + ``\sphinxstyleimportanttitle``; *idem* + ``\sphinxstyletiptitle``; *idem* + ``\sphinxstylewarningtitle``; *idem* + ``\sphinxstylecautiontitle``; *idem* + ``\sphinxstyleattentiontitle``; *idem* + ``\sphinxstyledangertitle``; *idem* + ``\sphinxstyleerrortitle``; *idem* + ``\sphinxstyleseealsotitle``; ``\sphinxstrong{#1}\par\nopagebreak`` .. versionadded:: 1.5 These macros were formerly hard-coded as non customizable ``\texttt``, @@ -1550,6 +1529,26 @@ Macros .. versionadded:: 1.8 ``\sphinxstyleindexlettergroup``, ``\sphinxstyleindexlettergroupDefault``. + .. versionadded:: 6.2.0 + ``\sphinxstylenotetitle`` 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. Examples: + + .. code-block:: latex + + \renewcommand\sphinxstylewarningtitle[1]{% + \underline{\textbf{\sphinxremovefinalcolon{#1}}}\par + } + \renewcommand{\sphinxstylenotetitle}[1]{% + \textit{\textbf{\sphinxremovefinalcolon{#1}}}\par\nobreak + % LaTeX syntax is complex and we would be better off using \hrule. + {\parskip0pt\noindent}% + \raisebox{1ex}% + {\makebox[\linewidth]{\textcolor{sphinxnoteBorderColor}{\dotfill}}} + % It is complex to obtain nice vertical spacing for both a paragraph + % or a list following up; this set-up is better for a paragraph next. + \par\vskip-\parskip + } - ``\sphinxtableofcontents``: A wrapper (defined differently in :file:`sphinxhowto.cls` and in :file:`sphinxmanual.cls`) of standard diff --git a/sphinx/texinputs/sphinxlatexadmonitions.sty b/sphinx/texinputs/sphinxlatexadmonitions.sty index 3ae19de9fef..a31ae4ce3a2 100644 --- a/sphinx/texinputs/sphinxlatexadmonitions.sty +++ b/sphinx/texinputs/sphinxlatexadmonitions.sty @@ -26,16 +26,14 @@ % % - 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 +% - \sphinxstylenotetitle, ..., \sphinxstylewarningtitle, 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 +% Their definitions are in sphinxlatexstyletext.sty. % Provides: (also in sphinxlatexliterals.sty) @@ -44,7 +42,7 @@ } % Some are quite plain -\newenvironment{sphinxseealso}[1]{\sphinxseealsotitle{#1}}{} +\newenvironment{sphinxseealso}[1]{\sphinxstyleseealsotitle{#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. @@ -94,19 +92,19 @@ % code in sphinxVerbatim. \newenvironment{sphinxnote}[1] {\edef\spx@env{sphinx\ifspx@opt@heavynote heavy\else light\fi box}% - \expandafter\begin\expandafter{\spx@env}\sphinxnotetitle{#1}} + \expandafter\begin\expandafter{\spx@env}\sphinxstylenotetitle{#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}\sphinxhinttitle{#1}} + \expandafter\begin\expandafter{\spx@env}\sphinxstylehinttitle{#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}\sphinximportanttitle{#1}} + \expandafter\begin\expandafter{\spx@env}\sphinxstyleimportanttitle{#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}\sphinxtiptitle{#1}} + \expandafter\begin\expandafter{\spx@env}\sphinxstyletiptitle{#1}} {\expandafter\end\expandafter{\spx@env}} % warning/caution/attention/danger/error get more distinction @@ -208,15 +206,15 @@ % \renewcommand{\sphinxwarningtitle}[1]{\textbf{#1}\par\smallskip % {\color{sphinxwarningBorderColor}\hrule height1pt}\smallskip} \newenvironment{sphinxwarning}[1] - {\begin{sphinxheavybox}\sphinxwarningtitle{#1}}{\end{sphinxheavybox}} + {\begin{sphinxheavybox}\sphinxstylewarningtitle{#1}}{\end{sphinxheavybox}} \newenvironment{sphinxcaution}[1] - {\begin{sphinxheavybox}\sphinxcautiontitle{#1}}{\end{sphinxheavybox}} + {\begin{sphinxheavybox}\sphinxstylecautiontitle{#1}}{\end{sphinxheavybox}} \newenvironment{sphinxattention}[1] - {\begin{sphinxheavybox}\sphinxattentiontitle{#1}}{\end{sphinxheavybox}} + {\begin{sphinxheavybox}\sphinxstyleattentiontitle{#1}}{\end{sphinxheavybox}} \newenvironment{sphinxdanger}[1] - {\begin{sphinxheavybox}\sphinxdangertitle{#1}}{\end{sphinxheavybox}} + {\begin{sphinxheavybox}\sphinxstyledangertitle{#1}}{\end{sphinxheavybox}} \newenvironment{sphinxerror}[1] - {\begin{sphinxheavybox}\sphinxerrortitle{#1}}{\end{sphinxheavybox}} + {\begin{sphinxheavybox}\sphinxstyleerrortitle{#1}}{\end{sphinxheavybox}} % the main dispatch for all types of notices \newenvironment{sphinxadmonition}[2]{% #1=type, #2=heading diff --git a/sphinx/texinputs/sphinxlatexstyletext.sty b/sphinx/texinputs/sphinxlatexstyletext.sty index 213814d30bb..913bc8210a6 100644 --- a/sphinx/texinputs/sphinxlatexstyletext.sty +++ b/sphinx/texinputs/sphinxlatexstyletext.sty @@ -8,16 +8,16 @@ % But those arise rather from the default definitions of the respective % latex environments done in sphinxlatexadmonitions.sty -\def\sphinxnotetitle#1{\sphinxstrong{#1} } -\let\sphinxhinttitle \sphinxnotetitle % #1 holds the localized notice name -\let\sphinximportanttitle\sphinxnotetitle % followed by a colon -\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} +\def\sphinxstylenotetitle #1{\sphinxstrong{#1} } +\let\sphinxstylehinttitle \sphinxstylenotetitle % #1 holds the localized notice name +\let\sphinxstyleimportanttitle\sphinxstylenotetitle % followed by a colon +\let\sphinxstyletiptitle \sphinxstylenotetitle +\let\sphinxstylewarningtitle \sphinxstylenotetitle +\let\sphinxstylecautiontitle \sphinxstylenotetitle +\let\sphinxstyleattentiontitle\sphinxstylenotetitle +\let\sphinxstyledangertitle \sphinxstylenotetitle +\let\sphinxstyleerrortitle \sphinxstylenotetitle +\def\sphinxstyleseealsotitle#1{\sphinxstrong{#1}\par\nopagebreak} % % A utility to remove a final colon. Removing last token is not easy in % LaTeX, and there are additional complications: