From 9df853e98b043f29666b55f9a75fd316e8d36734 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Fri, 5 Jul 2024 15:22:44 +0200 Subject: [PATCH] Renewed choices for admonition icons; suppress space if no icon And set box-decoration-break to "slice" (not "clone") for all admonitions. --- sphinx/texinputs/sphinx.sty | 134 ++++++++++---------- sphinx/texinputs/sphinxlatexadmonitions.sty | 41 +++--- sphinx/texinputs/sphinxpackageboxes.sty | 2 +- 3 files changed, 94 insertions(+), 83 deletions(-) diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index e426597f10a..9c813f8d5ec 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -37,18 +37,24 @@ } %% important build warnings use an undefined reference to induce latexmk %% into complaining (once per warning) at very end of console output -\newcommand\sphinxbuildwarning[1]{% - \ifcsname sphinx_emitted_#1\endcsname +\newcommand\sphinxbuildwarning[2][]{% + \ifcsname sphinx_emitted_#2\endcsname \else - \global\expandafter\let\csname sphinx_emitted_#1\endcsname\@empty + \global\expandafter\let\csname sphinx_emitted_#2\endcsname\@empty \AtEndDocument{\hbox{% should the printing of text be made conditional on - % some boolean? + % some boolean? (7.4.0 answers this by adding an + % optional argument and testing it here for emptiness + % but no usage is made of this novelty yet.) + \if\relax\detokenize{#1}\relax + % No [], print a red warning text at very end of document \bfseries\color{red}% - \@nameuse{sphinx_buildwarning_#1}% + \@nameuse{sphinx_buildwarning_#2}% + \fi % place an undefined reference deliberately \let\nfss@text\@gobble % no ?? - \ref{!!\@nameuse{sphinx_buildwarning_#1}}% - }}% + \ref{!!\@nameuse{sphinx_buildwarning_#2}}% + }% + }% \fi } \@namedef{sphinx_buildwarning_badtitlesec}{% @@ -60,10 +66,6 @@ \@namedef{sphinx_buildwarning_badfootnotes}{% Footnote rendering may have had problems, due to extra package or document class; check latex log for instructions}% -\@namedef{sphinx_buildwarning_fontawesome5ismissing}{% - As fontawesome5 LaTeX package is not found, admonition titles - default to not using icons; check div.note\string_title-icon and - similar options for how to configure your own.} %% OPTION HANDLING % @@ -102,13 +104,13 @@ \def\spx@definecolor{\expandafter\definecolor\spx@definedcolor} % These internals refactored at 7.4.0: \newcommand*{\spx@DeclareColorOption}[3][]{% -% #1 = almost always "sphinx" but left empty for a few +% #1 = almost always "sphinx" but left empty for a few for legacy reasons % #2 = option name, but internal colour name is #1#2 (i.e. with prefix) % #3 = initial default colour with either \definecolor or \colorlet syntax - % set the initial default + % Set the initial default \spx@defineorletcolor{#1#2}#3\relax - % set the key handler to accept both \definecolor and \colorlet syntax - % the key name does not have the #1 prefix from the colour name + % Set the key handler to accept both \definecolor and \colorlet syntax + % The key name does not have the #1 prefix from the colour name \define@key{sphinx}{#2}{\spx@defineorletcolor{#1#2}##1\relax}% }% @@ -214,11 +216,12 @@ \spx@DeclareColorOption{TitleColor}{{rgb}{0.126,0.263,0.361}} \spx@DeclareColorOption{InnerLinkColor}{{rgb}{0.208,0.374,0.486}} \spx@DeclareColorOption{OuterLinkColor}{{rgb}{0.216,0.439,0.388}} +% The Verbatim ones are "legacy" only since 5.1.0... call it "new-legacy" ;-) \spx@DeclareColorOption{VerbatimColor}{{RGB}{242,242,242}}% same as {gray}{0.95} \spx@DeclareColorOption{VerbatimBorderColor}{{RGB}{32,32,32}} % All other colours will be internally assigned a "sphinx" prefix -% Table row colors +% Table row colors (since 6.0.0) % ---------------- \spx@DeclareColorOption[sphinx]{TableRowColorHeader}{{gray}{0.86}} \spx@DeclareColorOption[sphinx]{TableRowColorOdd}{{gray}{0.92}} @@ -332,7 +335,7 @@ % ------------------------------------------------------------- % % So far the 5.1.0 added possibilities for fancier boxes had been used by -% default only for code-blocks, admonitions kept their old-fashioned +% default only for code-blocks, and admonitions kept their old-fashioned % legacy styles. At 7.4.0, as a follow-up to the revamped styles of % admonitions in the HTML sphinx13 theme (PR #12439), it is decided to % apply similar styling for PDF output. Also the seealso directive @@ -343,7 +346,7 @@ % % Border keys % At 7.4.0 refactoring to avoid defining legacy \spx@@border -% macros which are used nowhere, only @top, @right, @bottom, @left. +% macros which are (now) used nowhere, only @top, @right, @bottom, @left. \def\spx@tempa#1{% #1 = macro prefix \expandafter\spx@tempb \csname #1border@top\expandafter\endcsname @@ -354,7 +357,7 @@ \csname #1border@opentrue\expandafter\endcsname \csname #1border@openfalse\endcsname }% -\def\spx@tempb #1#2#3#4#5#6#7#8{% #8 = option prefix +\def\spx@tempb #1#2#3#4#5#6#7#8#9{% #8 = option prefix \define@key{sphinx}{#8border-top-width}{\def#1{##1}}% \define@key{sphinx}{#8border-right-width}{\def#2{##1}}% \define@key{sphinx}{#8border-bottom-width}{\def#3{##1}}% @@ -364,21 +367,24 @@ \def#1{##1}\let#2#1\let#3#1\let#4#1% }% \newif#5% + % 6.2.0 has added support for box-decoration-break also to admonition + % directives, formerly the option setting was ignored for them. \define@key{sphinx}{#8box-decoration-break}% {\begingroup\edef\spx@tempa{##1}\expandafter\endgroup \ifx\spx@tempa\spxstring@clone#7\else#6\fi}% - \spx@tempc{#8}% option prefix -} -\def\spx@tempc #1#2{% #1 = option prefix, #2 = legacy option name + % 7.4.0 sets the default behaviour to "slice" not only for code-blocks but + % also for admonitions, as the latter now have a background colour each. + #6% + % #8 = option prefix (with underscore), #9 = legacy option name % keep legacy option names as aliases to new-named options - \expandafter\let\csname KV@sphinx@#2\expandafter\endcsname - \csname KV@sphinx@#1border-width\endcsname + \expandafter\let\csname KV@sphinx@#9\expandafter\endcsname + \csname KV@sphinx@#8border-width\endcsname % init border-width (fetches next argument) - \csname KV@sphinx@#1border-width\endcsname + \csname KV@sphinx@#8border-width\endcsname } % MEMO: from 6.2.0 to 7.4.0 (excluive) \fboxrule was used in the first % two, and was resolved only at location of use. At 7.4.0, we again -% use 0.4pt rather which is its default. +% use 0.4pt rather and not \fboxrule dimen register. % macro prefix option prefix legacy option init value \spx@tempa{spx@pre@} {pre_} {verbatimborder} {0.4pt} \spx@tempa{spx@topic@} {div.topic_} {shadowrule} {0.4pt} @@ -394,10 +400,9 @@ \spx@tempa{spx@error@} {div.error_} {errorborder} {2pt} % mod. at 7.4.0 % this one new at 6.2.0: (we do not create a "legacy name" for it) \spx@tempa{spx@box@} {box_} {box_border-width}{0.4pt} -% Set default box-decoration-break style for codeblocks to slice -\spx@pre@border@opentrue % new default at 6.0.0: slice, not clone -% 6.2.0 has added support for box-decoration-break=slice to all -% other directives, formerly the option setting was ignored for them. +% Reset default box-decoration-break style to "clone" for \sphinxbox, +% but anyhow this is ignored as \sphinxbox produces unbreakable boxes. +\spx@box@border@openfalse % Padding keys % At 7.4.0, \spx@@padding internal macros removed, only @top, @right, @@ -466,8 +471,10 @@ } % The init value for corner radius in code-blocks was \z@ (i.e. 0pt) prior % to 6.0.0., then 3pt, then \fboxsep at 6.2.0 as padding was also \fboxsep. -% At 7.4.0 the 3pt is used (which is normal value of \fboxsep). -% At 7.4.0 some admonitions use rounded corners as well. +% At 7.4.0: +% - the 3pt is used (which is normal value of \fboxsep). +% - some admonitions use rounded corners as well. +% - topic boxed have only their bottom right corner rounded. % macro prefix option prefix tl tr br bl \spx@tempa{spx@pre@} {pre_} {3pt}{3pt}{3pt}{3pt} \spx@tempa{spx@topic@} {div.topic_} \z@ \z@ {12pt} \z@ @@ -562,7 +569,6 @@ % This definition was broken due to a typo at 5.1.0 and got fixed at 6.1.2 % MEMO: at 6.2.0 this no longer does \number\dimexpr in an \edef. Reason is to % keep in sync with div.topic_box-shadow handling of xoffset and yoffset. -% Attention in particular to \ifdim context, we add a \dimexpr to the one here. \define@key{sphinx}{shadowsize}{% \def\spx@topic@shadow@xoffset{#1}% \let\spx@topic@shadow@yoffset\spx@topic@shadow@xoffset @@ -586,13 +592,13 @@ % only internally used. % % For topic directive, "legacy" (around 2016-2017) had no interface for -% colors, so some internals could be changed with no breakage during 5.x up to -% 6.2.0. For example topic (shadowbox) could be unified with admonitions -% (sphinxheavybox), and the "set-up" macros could all be moved into a single +% colours, so some internals could be changed with no breakage during 5.x up +% to 6.2.0. For example topic (shadowbox) could be unified with admonitions +% (sphinxheavybox), and the "setup" macros could all be moved into a single % one in the sphinxpackageboxes.sty file, with only one argument holding the % directive type. % -% It was then needed only for sphinxlatexliterals.sty to let its +% It was then needed only by sphinxlatexliterals.sty to let its emitted % \spx@verb@boxes@fcolorbox@setup incorporate some extra adjustment. % % 7.4.0 removes usages of booleans relative to usage of a colour for @@ -753,21 +759,20 @@ % The support for default icons: \IfFileExists{fontawesome5.sty}{% \RequirePackage{fontawesome5} - \@namedef{sphinx-icon-pencil}{\faIcon{pencil-alt}} - \@namedef{sphinx-icon-question}{\faIcon{question-circle}} - \@namedef{sphinx-icon-info}{\faIcon{info-circle}} - \@namedef{sphinx-icon-flame}{\faIcon{fire-alt}} - \@namedef{sphinx-icon-spark}{\faIcon{radiation}}% we did not find a good match - % to sphinx13.css svg spark icon in fontawesome 5 LaTeX package - \@namedef{sphinx-icon-warning}{\faIcon{exclamation-triangle}} - \@namedef{sphinx-icon-failure}{\faIcon{skull-crossbones}}% - % but times-circle would be more alike sphinx13.css --icon-failure + \def\spx@faIcon{\faIcon} }% -{% no fontawasome5.sty - \sphinxbuildwarning{fontawesome5ismissing}% - \PackageWarningNoLine{sphinx}{fontawesome5 not available!\MessageBreak - Default admonition titles will use no icons.\MessageBreak - Check div.note_title-icon and similar options} +{% no fontawesome5.sty + % After some hesitation no warning is emitted: it is cumbersome to add code + % to emit a warning only if user has not made explicit usage of the title-icon + % keys. + % + % The hacky definition of \spx@faIcon below will still be operative for all + % remaining not set by user title-icon keys. It has the effect to prevent + % the execution of \sphinxtitlerowaftericonspacecmd (see + % \sphinxdotitlerowwithicon in sphinxlatexadmonitions.sty). If user sets a + % title-icon key to some LaTeX code of their own, of course \spx@faIcon is + % not executed and the inserted space will thus be there, as expected. + \let\spx@faIcon\@gobbletwo } % Now use the above colours as default settings, following the choices @@ -799,19 +804,20 @@ % % TODO: implement todo (sic) % -% Icon defaults. These names are copied over from sphinx13.css -% and their actual LaTeX definitions are above and emulate the svg -% icons, if fontawesome5 was found, else they expand to do nothing. - div.note_title-icon=\@nameuse{sphinx-icon-pencil}, - div.hint_title-icon=\@nameuse{sphinx-icon-question}, - div.tip_title-icon=\@nameuse{sphinx-icon-info}, - div.seealso_title-icon=\@nameuse{sphinx-icon-info}, - div.important_title-icon=\@nameuse{sphinx-icon-flame}, - div.caution_title-icon=\@nameuse{sphinx-icon-spark}, - div.warning_title-icon=\@nameuse{sphinx-icon-warning}, - div.attention_title-icon=\@nameuse{sphinx-icon-warning}, - div.danger_title-icon=\@nameuse{sphinx-icon-spark}, - div.error_title-icon=\@nameuse{sphinx-icon-failure}, +% Icon defaults. +% Warning: \spx@faIcon is defined to do some trick if fontawesome5 +% is absent, it is *not* a public macro to be used in custom user-level +% usage of the title-icon keys below! + div.note_title-icon =\spx@faIcon{info-circle}, + div.hint_title-icon =\spx@faIcon{lightbulb}, + div.tip_title-icon =\spx@faIcon{lightbulb}, + div.seealso_title-icon =\spx@faIcon{share}, + div.important_title-icon =\spx@faIcon{pause-circle}, + div.caution_title-icon =\spx@faIcon{radiation}, + div.warning_title-icon =\spx@faIcon{exclamation-triangle}, + div.attention_title-icon =\spx@faIcon{exclamation-triangle}, + div.danger_title-icon =\spx@faIcon{radiation}, + div.error_title-icon =\spx@faIcon{skull-crossbones}, } \newif\ifspx@opt@box@addstrut diff --git a/sphinx/texinputs/sphinxlatexadmonitions.sty b/sphinx/texinputs/sphinxlatexadmonitions.sty index 44f20d649f7..5db578212e5 100644 --- a/sphinx/texinputs/sphinxlatexadmonitions.sty +++ b/sphinx/texinputs/sphinxlatexadmonitions.sty @@ -7,30 +7,30 @@ % % - sphinxseealso environment added at 6.1.0. % -% At 7.4.0 it too now uses sphinxheavybox, and has the same -% associated sphinxsetup CSS keys as admonitions do. +% At 7.4.0 it too now uses sphinxheavybox, and has the same associated +% sphinxsetup CSS keys as admonitions do. % % - sphinxadmonition (environment) -% This is a dispatch which originally configured +% This is a dispatch which formerly configured % -% - note, hint, important, tip to use sphinxlightbox or optionnaly -% sphinxheavybox since 6.2.0. +% - note, hint, important, tip to use sphinxlightbox (or optionally +% sphinxheavybox since 6.2.0), % - warning, caution, attention, danger, error to use sphinxheavybox. % -% At 7.4.0 all admonitions use sphinxheavybox. +% At 7.4.0 all admonitions use sphinxheavybox. % -% - all environments sphinxnote, sphinxwarning, etc... can be redefined -% as will by user. Thay have one parameter #1 which is the title. +% - All environments sphinxnote, sphinxwarning, etc... can be redefined as +% will by user. Thay have a single parameter #1 which is the title. % -% - all default sphinxnote, sphinxwarning, etc... use associated -% one-argment macros \sphinxstylenotetitle, \sphinxstylewarningtitle, -% etc which can be redefined, and whose default is to use -% \sphinxdotitlerowwithicon to typeset the title in a coloured header -% row at top of the admonition. (new with 7.4.0) +% - The default sphinxnote, sphinxwarning, etc... use associated +% one-argument macros \sphinxstylenotetitle, \sphinxstylewarningtitle, etc +% which can be redefined. Their default is to use \sphinxdotitlerowwithicon +% to typeset the title in a coloured header row at top of the +% admonition. (new with 7.4.0) % -% The sphinxlightbox environment is kept only for projects with LaTeX -% code which used it via custom definitions done in preamble or -% via raw latex directive. +% The sphinxlightbox environment is kept for backward compatiblity, for user +% custom code which used it via custom definitions done in preamble or via +% raw latex directive. % % Requires: \RequirePackage{sphinxpackageboxes} @@ -301,8 +301,13 @@ \sphinxcolorlet{spx@boxes@backgroundcolor}{sphinx#1TtlBgColor}% \spx@boxes@fcolorbox{% \makebox[\linewidth][l]{% - \textcolor{sphinx#1TtlFgColor}{\@nameuse{sphinx#1TtlIcon}}% - \sphinxtitlerowaftericonspacecmd + \textcolor{sphinx#1TtlFgColor}{% + \@nameuse{sphinx#1TtlIcon}% + % This macro is located here and not after the closing brace + % for reasons of fall-back \spx@faIcon definition in sphinx.sty + % in case fontawesome5 package not found. + \sphinxtitlerowaftericonspacecmd + }% \sphinxstrong{#2}% \strut}% }% diff --git a/sphinx/texinputs/sphinxpackageboxes.sty b/sphinx/texinputs/sphinxpackageboxes.sty index 6784225ea63..234505147d5 100644 --- a/sphinx/texinputs/sphinxpackageboxes.sty +++ b/sphinx/texinputs/sphinxpackageboxes.sty @@ -525,7 +525,7 @@ \def\spx@boxes@fcolorbox@insetshadow{% % BACKGROUND % draw background and move back to reference point - % 6.4.0 always assumes a background color + % 7.4.0 always assumes a background color {\color{spx@boxes@backgroundcolor}% \vrule\@height\ht\spx@tempboxa \@depth\dp\spx@tempboxa