Skip to content

Commit

Permalink
LaTeX: rename \sphinxnotetitle into \sphinxstylenotetitle (etc)
Browse files Browse the repository at this point in the history 
Follow-up to #11266.  Using \sphinxstyle prefix looked a posteriori
better, for coherency, although it is a bit long.
  • Loading branch information
@jfbu
jfbu committed Mar 27, 2023
1 parent 64bf782 commit 8f9bac9
Show file tree
Hide file tree
Showing 4 changed files with 73 additions and 76 deletions.
6 changes: 3 additions & 3 deletions CHANGES
View file
Expand Up @@ -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
Expand Down
97 changes: 48 additions & 49 deletions doc/latex.rst
View file
Expand Up @@ -1464,16 +1464,6 @@ 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
Expand All @@ -1488,53 +1478,42 @@ 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::
:header: Name, ``maps argument #1 to:``
: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}<space>``
``\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``,
Expand All @@ -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
Expand Down
26 changes: 12 additions & 14 deletions sphinx/texinputs/sphinxlatexadmonitions.sty
View file
Expand Up @@ -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<notice> environments to replace at 6.2.0
% formerly hard-coded \sphinxstrong{#1}<space>
% Their definitions are in sphinxlatexstyletext.sty. Also \sphinxseealsotitle
% Their definitions are in sphinxlatexstyletext.sty.


% Provides: (also in sphinxlatexliterals.sty)
Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
20 changes: 10 additions & 10 deletions sphinx/texinputs/sphinxlatexstyletext.sty
View file
Expand Up @@ -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:
Expand Down

0 comments on commit 8f9bac9

Please sign in to comment.