diff --git a/CHANGES b/CHANGES index c761388ee23..39f41d0f369 100644 --- a/CHANGES +++ b/CHANGES @@ -20,7 +20,11 @@ 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) + See :ref:`sphinxbox`. (refs: #11224) +* 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 + optional shadow. See :ref:`additionalcss`. (refs: #11234) Bugs fixed ---------- diff --git a/doc/latex.rst b/doc/latex.rst index 4ed3ad4ab4a..51e9c41d897 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -8,26 +8,34 @@ LaTeX customization \begingroup \sphinxsetup{% - TitleColor={named}{DarkGoldenrod}, - pre_border-width=2pt, - pre_padding=5pt, - pre_border-radius=5pt, - pre_background-TeXcolor={named}{OldLace}, - pre_border-TeXcolor={named}{Gold}, - div.warning_border-width=3pt, - div.warning_padding=6pt, - div.warning_padding-right=18pt, - div.warning_padding-bottom=18pt, - div.warning_border-TeXcolor={named}{DarkCyan}, - div.warning_background-TeXcolor={named}{LightCyan}, - div.warning_box-shadow=-12pt -12pt inset, - div.warning_box-shadow-TeXcolor={named}{Cyan}, - attentionborder=3pt, - attentionBorderColor={named}{Crimson}, - attentionBgColor={named}{FloralWhite}, - noteborder=2pt, - noteBorderColor={named}{Olive}, - hintBorderColor={named}{LightCoral}} + TitleColor={named}{DarkGoldenrod}, + pre_border-width=2pt, + pre_padding=5pt, + pre_border-radius=5pt, + pre_background-TeXcolor={named}{OldLace}, + pre_border-TeXcolor=Gold, + pre_border-TeXcolor=Gold!90, + % + div.warning_border-width=3pt, + div.warning_padding=6pt, + div.warning_padding-right=18pt, + div.warning_padding-bottom=18pt, + div.warning_border-TeXcolor=DarkCyan, + div.warning_background-TeXcolor=LightCyan, + div.warning_box-shadow=-12pt -12pt inset, + div.warning_box-shadow-TeXcolor=Cyan, + % + attentionborder=3pt, + attentionBorderColor=Crimson, + attentionBgColor=FloralWhite, + % + noteborder=1pt, + noteBorderColor=Olive, + noteBgColor=Olive!10, + div.note_border-left-width=0pt, + div.note_border-right-width=0pt, + hintBorderColor=LightCoral, + } \relax Unlike :ref:`the HTML builders `, the ``latex`` builder does not @@ -592,53 +600,80 @@ The colors used in the above are provided by the ``svgnames`` option of the It is possible to insert further uses of the ``\sphinxsetup`` LaTeX macro directly into the body of the document, via the help of the ``raw`` directive. This chapter is styled in the PDF output using the following at the -start of the chapter (which uses keys described later in :ref:`additionalcss`):: +start of the chapter (which uses keys described later in +:ref:`additionalcss`): - .. raw:: latex +.. code-block:: latex + + .. raw:: latex - \begingroup - \sphinxsetup{% + \begingroup + \sphinxsetup{% TitleColor={named}{DarkGoldenrod}, % pre_border-width is 5.1.0 alias for verbatimborder pre_border-width=2pt, - % pre_padding is 5.1.0 alias for verbatimsep + % pre_padding is a 5.1.0 alias for verbatimsep pre_padding=5pt, - % rounded boxes are new at 5.1.0 + % Rounded boxes are new at 5.1.0 pre_border-radius=5pt, - % TeXcolor means syntax must be as for LaTeX \definecolor + % TeXcolor reminds that syntax must be as for LaTeX \definecolor pre_background-TeXcolor={named}{OldLace}, - pre_border-TeXcolor={named}{Gold}, + % ... and since 5.3.0 also xcolor \colorlet syntax is accepted and we + % can thus drop the {named}{...} thing if xcolor is available! + pre_border-TeXcolor=Gold, + % ... and even take more advantage of xcolor syntax: + pre_border-TeXcolor=Gold!90, % - % 5.1.0 alias for warningborder + % This 5.1.0 CSS-named option is alias for warningborder div.warning_border-width=3pt, + % Prior to 5.1.0, padding for admonitions was not customizable div.warning_padding=6pt, div.warning_padding-right=18pt, div.warning_padding-bottom=18pt, - div.warning_border-TeXcolor={named}{DarkCyan}, - div.warning_background-TeXcolor={named}{LightCyan}, + % Assume xcolor has been loaded with its svgnames option + div.warning_border-TeXcolor=DarkCyan, + div.warning_background-TeXcolor=LightCyan, + % This one is the only option with space separated input: div.warning_box-shadow=-12pt -12pt inset, - div.warning_box-shadow-TeXcolor={named}{Cyan}, + div.warning_box-shadow-TeXcolor=Cyan, % - % 5.1.0 new name would be div.attention_border-width + % The 5.1.0 new name would be div.attention_border-width attentionborder=3pt, - % same as div.attention_border-TeXcolor - attentionBorderColor={named}{Crimson}, - % same as div.attention_background-TeXcolor - attentionBgColor={named}{FloralWhite}, + % The 5.1.0 name here would be div.attention_border-TeXcolor + attentionBorderColor=Crimson, + % The 5.1.0 name would be div.attention_background-TeXcolor + attentionBgColor=FloralWhite, + % + % For note/hint/important/tip, the CSS syntax was added at 6.2.0 + % Legacy syntax still works + noteborder=1pt, + noteBorderColor=Olive, + % But setting a background color via the new noteBgColor means that + % it will be rendered using the same interface as warning type + noteBgColor=Olive!10, + % We can customize separately the four border-widths, and mimic + % the legacy "light" rendering, but now with a background color: + div.note_border-left-width=0pt, + div.note_border-right-width=0pt, + % (but using rounded corners would cause the widths of all sides to + % be reset equal to the noteborder setting) % - % no CSS-like names yet at 5.1.0 for note-type admonitions - noteborder=2pt, - noteBorderColor={named}{Olive}, - hintBorderColor={named}{LightCoral}% - } + % As long as only border width and border color are set, *and* using + % for this the old interface, the rendering will be the "light" one + hintBorderColor=LightCoral, + % but if we had used div.hint_border-TeXcolor or *any* CSS-named + % option we would have triggered the more complex "heavybox" code. + } And this is placed at the end of the chapter source to end the scope of -the configuration:: +the configuration: - .. raw:: latex +.. code-block:: latex - \endgroup + .. raw:: latex + + \endgroup LaTeX syntax for boolean keys requires *lowercase* ``true`` or ``false`` e.g ``'sphinxsetup': "verbatimwrapslines=false"``. If setting the @@ -696,7 +731,7 @@ Do not use quotes to enclose values, whether numerical or strings. ``verbatimwithframe`` Boolean to specify if :rst:dir:`code-block`\ s and literal includes are framed. Setting it to ``false`` does not deactivate use of package - "framed", because it is still in use for the optional background colour. + "framed", because it is still in use for the optional background color. Default: ``true``. @@ -792,7 +827,7 @@ Do not use quotes to enclose values, whether numerical or strings. Default: ``true`` .. versionadded:: 1.5.2 - set this option value to ``false`` to recover former behaviour. + set this option value to ``false`` to recover former behavior. ``inlineliteralwraps`` Boolean to specify if line breaks are allowed inside inline literals: but @@ -804,7 +839,7 @@ Do not use quotes to enclose values, whether numerical or strings. Default: ``true`` .. versionadded:: 1.5 - set this option value to ``false`` to recover former behaviour. + set this option value to ``false`` to recover former behavior. .. versionchanged:: 2.3.0 added potential breakpoint at ``\`` characters. @@ -828,7 +863,7 @@ Do not use quotes to enclose values, whether numerical or strings. .. note:: - Values for colour keys must either: + Values for color keys must either: - obey the syntax of the ``\definecolor`` LaTeX command, e.g. something such as ``VerbatimColor={rgb}{0.2,0.3,0.5}`` or ``{RGB}{37,23,255}`` or @@ -838,7 +873,7 @@ Do not use quotes to enclose values, whether numerical or strings. - or obey the syntax of the ``\colorlet`` command from package ``xcolor`` (which then must exist in the LaTeX installation), e.g. ``VerbatimColor=red!10`` or ``red!50!green`` or ``-red!75`` or - ``MyPreviouslyDefinedColour`` or... Refer to xcolor_ documentation for + ``MyPreviouslyDefinedColor`` or... Refer to xcolor_ documentation for this syntax. .. _xcolor: https://ctan.org/pkg/xcolor @@ -847,24 +882,24 @@ Do not use quotes to enclose values, whether numerical or strings. Formerly only the ``\definecolor`` syntax was accepted. ``TitleColor`` - The colour for titles (as configured via use of package "titlesec".) + The color for titles (as configured via use of package "titlesec".) Default: ``{rgb}{0.126,0.263,0.361}`` ``InnerLinkColor`` - A colour passed to ``hyperref`` as value of ``linkcolor`` and + A color passed to ``hyperref`` as value of ``linkcolor`` and ``citecolor``. Default: ``{rgb}{0.208,0.374,0.486}``. ``OuterLinkColor`` - A colour passed to ``hyperref`` as value of ``filecolor``, ``menucolor``, + A color passed to ``hyperref`` as value of ``filecolor``, ``menucolor``, and ``urlcolor``. Default: ``{rgb}{0.216,0.439,0.388}`` ``VerbatimColor`` - The background colour for :rst:dir:`code-block`\ s. + The background color for :rst:dir:`code-block`\ s. Default: ``{gray}{0.95}`` @@ -891,7 +926,7 @@ Do not use quotes to enclose values, whether numerical or strings. .. _tablecolors: ``TableRowColorHeader`` - Sets the background colour for (all) the header rows of tables. + Sets the background color for (all) the header rows of tables. It will have an effect only if either the :confval:`latex_table_style` contains ``'colorrows'`` or if the table is assigned the ``colorrows`` @@ -904,13 +939,13 @@ Do not use quotes to enclose values, whether numerical or strings. Default: ``{gray}{0.86}`` - There is also ``TableMergeColorHeader``. If used, sets a specific colour + There is also ``TableMergeColorHeader``. If used, sets a specific color for merged single-row cells in the header. .. versionadded:: 5.3.0 ``TableRowColorOdd`` - Sets the background colour for odd rows in tables (the row count starts at + Sets the background color for odd rows in tables (the row count starts at ``1`` at the first non-header row). Has an effect only if the :confval:`latex_table_style` contains ``'colorrows'`` or for specific tables assigned the ``colorrows`` class. @@ -922,7 +957,7 @@ Do not use quotes to enclose values, whether numerical or strings. .. versionadded:: 5.3.0 ``TableRowColorEven`` - Sets the background colour for even rows in tables. + Sets the background color for even rows in tables. Default ``{gray}{0.98}`` @@ -974,32 +1009,49 @@ Do not use quotes to enclose values, whether numerical or strings. Default: ``\fboxrule`` |notebdcolors| - The colour for the two horizontal rules used by Sphinx in LaTeX for styling + The color for the two horizontal rules used by Sphinx in LaTeX for styling a :dudir:`note` type admonition. Default: ``{rgb}{0,0,0}`` (black) +|notebgcolors| + The optional color for the background. It is a priori set to white, but + is not used, unless it has been set explicitly, and doing this triggers + Sphinx into switching to the more complex LaTeX code which is employed + also for ``warning`` type admonitions. There are then additional options + which are described in :ref:`additionalcss`. + + Default: ``{rgb}{1,1,1}`` (white) + + .. versionadded:: 6.2.0 + ``noteborder``, ``hintborder``, ``importantborder``, ``tipborder`` The width of the two horizontal rules. + If the background color is set, or the alternative :ref:`additionalcss` + syntax is used (e.g. ``div.note_border-width=1pt`` in place of + ``noteborder=1pt``), or *any* option with a CSS-alike name is used, then + the border is a full frame and this parameter sets its width also for left + and right. + Default: ``0.5pt`` .. only:: not latex |warningbdcolors| - The colour for the admonition frame. + The color for the admonition frame. Default: ``{rgb}{0,0,0}`` (black) .. only:: latex |wgbdcolorslatex| - The colour for the admonition frame. + The color for the admonition frame. Default: ``{rgb}{0,0,0}`` (black) |warningbgcolors| - The background colours for the respective admonitions. + The background colors for the respective admonitions. Default: ``{rgb}{1,1,1}`` (white) @@ -1031,6 +1083,9 @@ Do not use quotes to enclose values, whether numerical or strings. .. |notebdcolors| replace:: ``noteBorderColor``, ``hintBorderColor``, ``importantBorderColor``, ``tipBorderColor`` +.. |notebgcolors| replace:: ``noteBgColor``, ``hintBgColor``, + ``importantBgColor``, ``tipBgColor`` + .. |warningbdcolors| replace:: ``warningBorderColor``, ``cautionBorderColor``, ``attentionBorderColor``, ``dangerBorderColor``, ``errorBorderColor`` @@ -1055,90 +1110,148 @@ Additional CSS-like ``'sphinxsetup'`` keys .. versionadded:: 5.1.0 + For :rst:dir:`code-block`, :dudir:`topic` and :dudir:`contents` directive, + and strong-type admonitions (:dudir:`warning`, :dudir:`error`, ...). -At ``5.1.0`` the LaTeX styling possibilities have been significantly enhanced. -Code-blocks, topic directives, and the five warning-type directives each now -possess: - -- four border-widths parameters, -- four padding parameters, -- four radius parameters (only circular arcs) for the corners, -- optional shadow, with x-offset and y-offset being possibly negative, - and the shadow possibly inset, -- colors for background, border and shadow. +.. versionadded:: 6.2.0 -All those options have been named in a CSS-like way. Indeed, in future it is -envisioned to allow these settings to be specified either in an external file, -or in a string variable which would be parsed to extract from CSS the -selectors and properties which are understood. + Also the :dudir:`note`, :dudir:`hint`, :dudir:`important` and :dudir:`tip` + admonitions can be styled this way. Using for them *any* of the listed + options will trigger usage of a more complex LaTeX code than the one used + per default (``sphinxheavybox`` vs ``sphinxlightbox``). Setting the new + ``noteBgColor`` (or ``hintBgColor``, ...) also triggers usage of + ``sphinxheavybox`` for :dudir:`note` (or :dudir:`hint`, ...). -Currently though this is added via a bunch of new ``'sphinxsetup'`` keys -whose names will be given now. +Perhaps in future these 5.1.0 (and 6.2.0) novel settings could be specified in +an external file, using genuine CSS syntax, but currently they have to be used +via the ``'sphinxsetup'`` interface and CSS-named alike options. .. important:: Low-level LaTeX errors causing a build failure can happen if - the input syntax is not respected. In particular properties for colours, - whose names end with ``TeXcolor``, must be input as for the other colour - related options previously described, i.e. for example:: - - ... - div.warning_border-TeXcolor={rgb}{1,0,0},% - ... - - A colon will not be accepted in place of the equal sign which is - expected by the LaTeX syntax. - Do not insert spaces in the input. With the exception of the - ``box-shadow`` all dimensional parameters expect a unique dimension - not a space separated list of dimensions. - -Options for code-blocks: - -- | ``pre_border-top-width``, - | ``pre_border-right-width``, - | ``pre_border-bottom-width``, - | ``pre_border-left-width``, - | ``pre_border-width``, beware that this is a *single* dimension. Its - default, and the ones of the separate widths is the setting of - ``\fboxrule`` in the preamble, i.e. normally ``0.4pt``. -- ``pre_box-decoration-break`` can be set to ``clone`` or ``slice``, default - is ``slice`` since 6.0.0. (former default was ``clone``). -- | ``pre_padding-top``, - | ``pre_padding-right``, - | ``pre_padding-bottom``, - | ``pre_padding-left``, - | ``pre_padding``, again this is a single dimension. Its default is the - setting of ``\fboxsep`` i.e. normally ``3pt``. -- | ``pre_border-top-left-radius``, - | ``pre_border-top-right-radius``, - | ``pre_border-bottom-right-radius``, - | ``pre_border-bottom-left-radius``, - | ``pre_border-radius``, are all single dimensions (rounded corners are - circular arcs only), which default (since 6.0.0) to ``3pt``. -- ``pre_box-shadow`` is special in so far as it may be the ``none`` keyword, - or a single dimension - which will be assigned to both x-offset and y-offset, or two dimensions, or - two dimensions followed by the word ``inset``. The x-offset and y-offset - may be negative. The defaults is ``none``. -- | ``pre_border-TeXcolor``, - | ``pre_background-TeXcolor``, - | ``pre_box-shadow-TeXcolor``. - - They - default to ``{RGB}{32,32,32}``, ``{gray}{0.95}`` and ``{rgb}{0,0,0}`` - respectively (since 6.0.0). - -.. versionchanged:: 6.0.0 - Formerly ``pre_border-radius`` (aka ``VerbatimBorder``) was ``0pt`` - (i.e. straight corners) and the colours ``pre_border-TeXcolor`` - and ``pre_background-TeXcolor`` (aka ``VerbatimBorderColor`` and - ``VerbatimColor``) where ``{rgb}{0,0,0}`` (black border) and - ``{rgb}{1,1,1}`` (white background) respectively. - Also ``pre_box-decoration-break`` was changed from ``clone`` into - ``slice`` for "open" framing at pagebreaks. - -If one of the radius parameters is positive, the separate border widths will -be ignored and only the value set by ``pre_border-width`` will be used. Also, -if a shadow is present and is inset, the box will be rendered with straight -corners. + the input syntax is not respected. + + * In particular properties for colors, + whose names end with ``-TeXcolor``, must be input as for the other color + related options previously described, i.e. for example:: + + ... + div.warning_border-TeXcolor={rgb}{1,0,0},% + div.error_background-TeXcolor=red!10,% (if xcolor available) + ... + + * A colon will not be accepted in place of the equal sign which is expected + by the LaTeX syntax. Do not insert spaces in the input. + + * All dimensional parameters expect a *unique* dimension, even + ``border-width`` or ``padding``: they can not be used with a value being + a space separated list of dimensions. The sole exception currently is + ``box-shadow``. + + * Dimensions should use TeX units such as ``pt`` or ``cm`` or ``in``. The + ``px`` unit is recognized by ``pdflatex`` and ``lualatex`` but not by + ``xelatex`` or ``platex``. + +The options are all named in a similar pattern which depends on a ``prefix``, +which is then followed by an underscore, then the option name. + +.. csv-table:: + :header: Directive, Option prefix, LaTeX environment + + :rst:dir:`code-block`, ``pre``, ``sphinxVerbatim`` + :dudir:`topic`, ``div.topic``, ``sphinxShadowBox`` + contents_, ``div.topic``, ``sphinxShadowBox`` + :dudir:`note`, ``div.note``, ``sphinxnote`` using ``sphinxheavybox`` + :dudir:`warning`, ``div.warning``, ``sphinxwarning`` (uses ``sphinxheavybox``) + admonition type, ``div.``, ``sphinx`` (using ``sphinxheavybox``) + + +.. _contents: https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents + +Here are now these options as well as their common defaults. +Replace below ```` by the actual prefix as explained above. Don't +forget the underscore separating the prefix from the attribute name. + +- | ``_border-top-width``, + | ``_border-right-width``, + | ``_border-bottom-width``, + | ``_border-left-width``, + | ``_border-width``. The latter can (currently) be only a *single* + dimension which then sets all four others. + The default is that all those dimensions are equal. They are set to: + + * ``\fboxrule`` (i.e. normally ``0.4pt``) for :rst:dir:`code-block`, + * ``\fboxrule`` for :dudir:`topic` or contents_ directive, + * ``1pt`` for :dudir:`warning` and other "strong" admonitions, + * ``0.5pt`` for :dudir:`note` and other "light" admonitions. The framing + style of the "lighbox" used for them in absence of usage of CSS-named + options will be emulated by the richer "heavybox" if setting + ``border-left-width`` and ``border-right-width`` both to ``0pt``. + +- ``_box-decoration-break`` can be set to either ``clone`` or + ``slice``. It is currently *ignored* by all except :rst:dir:`code-block` + (i.e. ``pre`` prefix) and then defaults to ``slice`` since 6.0.0 (former + default was ``clone``). +- | ``_padding-top``, + | ``_padding-right``, + | ``_padding-bottom``, + | ``_padding-left``, + | ``_padding``. The latter can (currently) be only a *single* + dimension which then sets all four others. + The default is that all those dimensions are equal. They are set to: + + * ``\fboxsep`` (i.e. normally ``3pt``) for :rst:dir:`code-block`, + * ``5pt`` for :dudir:`topic` or contents_ directive, + * a special value for :dudir:`warning` and other "strong" admonitions, + which ensures a backward compatible behavior. + + .. important:: Prior to 5.1.0 there was no separate customizability of + padding for warning-type boxes in PDF via LaTeX output. The sum of + padding and border-width (as set for example for :dudir:`warning` by + ``warningborder``, now also named ``div.warning_border-width``) was + kept to a certain constant value. This limited the border-width + to small values else the border could overlap the text contents. + This behavior is kept as default. + + * the same padding behavior is obeyed per default for :dudir:`note` or + other "light" admonitions when using ``sphinxheavybox``. +- | ``_border-top-left-radius``, + | ``_border-top-right-radius``, + | ``_border-bottom-right-radius``, + | ``_border-bottom-left-radius``, + | ``_border-radius``. The latter can (currently) be only a *single* + dimension which then sets all four others (rounded corners are + circular arcs only, no ellipses). + The default is that all those dimensions are equal. They are set to: + + * ``3pt`` for :rst:dir:`code-block` (since 6.0.0). + * ``0pt``, i.e. straight corners for all other directives. +- ``_box-shadow`` is special in so far as it may be the ``none`` + keyword, or a single dimension which will be assigned to both x-offset and + y-offset, or two dimensions separated by a space, or two dimensions + separated by a space and followed by a space and the word ``inset``. The + x-offset and y-offset may be negative. The default is ``none``, *except* + for the :dudir:`topic` or contents_ directives, for which it is ``4pt 4pt``, + i.e. the shadow has a width of ``4pt`` and is on the right and below. +- | ``_border-TeXcolor``, + | ``_background-TeXcolor``, + | ``_box-shadow-TeXcolor``. + These are colors. + + The shadow color defaults in all cases to ``{rgb}{0,0,0}`` i.e. to black. + + Since 6.0.0 the border color and background color of :rst:dir:`code-block`, + i.e. ``pre`` prefix, default respectively to ``{RGB}{32,32,32}`` and + ``{gray}{0.95}``. They previously defaulted to black, respectively white. + + For all other types, the border color defaults to black and the background + color to white (technically, the LaTeX code does not even bother injecting + color commands then). + +.. note:: + + If one of the radii parameters is set to a positive value, the separate + border widths will be ignored and only the value set by + ``_border-width`` will be used. Also, if a shadow is present and is + inset, the box will automatically be rendered with straight corners. .. note:: @@ -1149,116 +1262,38 @@ corners. .. _pict2e: https://ctan.org/pkg/pict2e -Options for topic boxes: - -- | ``div.topic_border-top-width``, - | ``div.topic_border-right-width``, - | ``div.topic_border-bottom-width``, - | ``div.topic_border-left-width``, - | ``div.topic_border-width``, beware that this is a *single* dimension. Its - default, and the ones of the separate widths is the setting of - ``\fboxrule`` in the preamble, i.e. normally ``0.4pt``. -- ``div.topic_box-decoration-break`` is currently ignored. -- | ``div.topic_padding-top``, - | ``div.topic_padding-right``, - | ``div.topic_padding-bottom``, - | ``div.topic_padding-left``, - | ``div.topic_padding``, - again this is a single dimension. Its default is ``5pt``. - - .. versionchanged:: 6.1.2 - These keys had been implemented at 5.1.0 without ``div.`` in - their names. -- | ``div.topic_border-top-left-radius``, - | ``div.topic_border-top-right-radius``, - | ``div.topic_border-bottom-right-radius``, - | ``div.topic_border-bottom-left-radius``, - | ``div.topic_border-radius``. - - They all are single dimensions which default to ``0pt``. -- ``div.topic_box-shadow`` defaults to ``4pt 4pt``. -- | ``div.topic_border-TeXcolor``, - | ``div.topic_background-TeXcolor``, - | ``div.topic_box-shadow-TeXcolor``. - - They default to ``{rgb}{0,0,0}``, ``{rgb}{1,1,1}`` - and ``{rgb}{0,0,0}`` respectively. - -Options for ``warning`` (and similarly for ``caution``, ``attention``, -``danger``, ``error``) directive: - -- | ``div.warning_border-top-width``, - | ``div.warning_border-right-width``, - | ``div.warning_border-bottom-width``, - | ``div.warning_border-left-width``, - | ``div.warning_border-width``, - beware that this is a *single* dimension. Its - default, and the ones of the separate widths is ``1pt``. -- ``div.warning_box-decoration-break`` is currently ignored. -- | ``div.warning_padding-top``, - | ``div.warning_padding-right``, - | ``div.warning_padding-bottom``, - | ``div.warning_padding-left``, - | ``div.warning_padding``, again this is a single dimension. - - .. important:: Prior to ``5.1.0`` there was no separate customizability of - padding for warning-type boxes in PDF via LaTeX output. The sum of - padding and border-width (as set by ``warningborder``, now also named - ``div.warning_border-width``) was kept to a certain constant value (and - this limited the border-width to small values else the border could - overlap the text contents). This behaviour is kept as default. Using - the ``div.warning_padding`` key will cancel for all four paddings the - legacy behaviour, but using only one of the four padding keys leaves the - three other paddings behave as formerly. -- | ``div.warning_border-top-left-radius``, - | ``div.warning_border-top-right-radius``, - | ``div.warning_border-bottom-right-radius``, - | ``div.warning_border-bottom-left-radius``, - | ``div.warning_border-radius``. - - They are all single dimensions which default to ``0pt``. -- ``div.warning_box-shadow`` defaults to ``none``. -- | ``div.warning_border-TeXcolor``, - | ``div.warning_background-TeXcolor``, - | ``div.warning_box-shadow-TeXcolor``. - - They default to ``{rgb}{0,0,0}``, ``{rgb}{1,1,1}`` - and ``{rgb}{0,0,0}`` respectively. - -In the above replace ``warning`` by one of ``caution``, ``attention``, -``danger``, ``error`` to style the respective directives. - -The following legacy behaviour of the PDF layout is currently not -customizable: - -- for code-blocks, padding and border-width and shadow (if one adds one) will - go into the margin; the code lines remain at the same place independently of - the values of the padding and border-width, except for being shifted - vertically of course to not overwrite other text. - -- for topic boxes and warning-type notices only the shadows will go into page - margin, the borders are kept within the text area. - -- ``contents`` and ``topic`` directive are styled the same way. +The following legacy behavior is currently not customizable: -.. note:: +- For :rst:dir:`code-block`, padding and border-width and shadow (if one adds + one) will go into the margin; the code lines remain at the same place + independently of the values of the padding and border-width, except for + being shifted vertically of course to not overwrite other text. + +- For :dudir:`topic` the shadow (if on right) goes into the page + margin, but the border (and the extra padding) are kept within the text + area. Same for admonitions if configured to display a shadow. + +- The contents_ and :dudir:`topic` directives are governed by the same options + with ``div.topic`` prefix: the Sphinx LaTeX mark-up uses for both directives + the same ``sphinxShadowBox`` environment which has currently no additional + branching, contrarily to the ``sphinxadmonition`` environment which branches + according to the admonition directive name, e.g. eitther to ``sphinxnote`` + or ``sphinxwarning`` etc... - The ``note``-style admonition directives admit no such customization - interface at this stage. -Here is a random example (not especially recommended!): +Here is a further (random) example configuration (which is not especially +recommended!), but see perhaps rather the configuration displayed at start of +:ref:`latexsphinxsetup`. .. code-block:: latex latex_elements = { 'sphinxsetup': """% + % For colors, we use throughout this example the \definecolor syntax + % The leaner \colorlet syntax is available if xcolor is on your system pre_background-TeXcolor={RGB}{242,242,242},% alias of VerbatimColor pre_border-TeXcolor={RGB}{32,32,32},% pre_box-decoration-break=slice, - % pre_border-top-width=5pt,% will be ignored due to non-zero radii - % pre_border-right-width=10pt, - % pre_border-bottom-width=15pt, - % pre_border-left-width=20pt, pre_border-width=3pt,% sets equally the four border-widths, % needed for rounded corners pre_border-top-left-radius=20pt, @@ -1286,8 +1321,18 @@ Here is a random example (not especially recommended!): """, } -In future, it is hoped to add further CSS properties such as ``font`` or -``color``. +.. important:: + + In future, it is hoped to add further CSS properties such as ``font`` or + ``color``. For time being if you want to modify the text color in a + :dudir:`warning`, you have to add something such as this in the preamble: + + .. code-block:: latex + + % redefine sphinxwarning environment to color its contents + \renewenvironment{sphinxwarning}[1] + {\begin{sphinxheavybox}\sphinxstrong{#1} \color{red}}% <-- text in red + {\end{sphinxheavybox}} LaTeX macros and environments @@ -1547,7 +1592,7 @@ Environments of the notice, for example ``Warning:`` for :dudir:`warning` directive, if English is the document language). Their default definitions use either the *sphinxheavybox* (for the last 5 ones) or the *sphinxlightbox* - environments, configured to use the parameters (colours, border thickness) + environments, configured to use the parameters (colors, border thickness) specific to each type, which can be set via ``'sphinxsetup'`` string. .. versionchanged:: 1.5 @@ -1557,7 +1602,7 @@ Environments - Environment for the :rst:dir:`seealso` directive: ``sphinxseealso``. It takes one argument which will be the localized string ``See also``. Its - default definition maintains the legacy behaviour: the localized ``See + default definition maintains the legacy behavior: the localized ``See also``, followed with a colon, will be rendered using ``\sphinxstrong``. Nothing particular is done for the contents. diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index fe5f0db64bb..97cedf18cb8 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -186,22 +186,20 @@ will be set to white}% % latter, were used under an aliased name. They got removed at 6.2.0. % % notices/admonitions -% the dimensions for notices/admonitions are kept as macros and assigned to -% \spx@notice@border at time of use, hence \DeclareStringOption is ok for this -\newdimen\spx@notice@border -\DeclareStringOption[0.5pt]{noteborder} -\DeclareStringOption[0.5pt]{hintborder} -\DeclareStringOption[0.5pt]{importantborder} -\DeclareStringOption[0.5pt]{tipborder} -% Compatibility layer to share for these notice types common code -% with the one for warning, danger, ..., in sphinxlatexadmonitions.sty -\def\spx@note@border {\spx@opt@noteborder} -\def\spx@hint@border {\spx@opt@hintborder} -\def\spx@important@border{\spx@opt@importantborder} -\def\spx@tip@border {\spx@opt@tipborder} -% The warning type notices are handled in the "CSS" section below. -% 6.2.0 does not define \spx@opt@warningborder etc... macros -% but only \spx@warning@border etc... +% 5.1.0 added much customizability to warning, caution, attention, danger and +% error types of notices via an enhanced sphinxheavybox environment. +% 6.2.0 has added the possiblity to use the same kind of rendering also for +% note, hint, important, and tip. +% All this is now handled below in the "CSS" section. Legacy user interface +% for options is kept working, but all of it is handled in the "CSS" section. +% We do define here some non-documented booleans which will serve internally. +% There is no reason for user to know about them, except if it is desired to +% toggle mid-way in the document whether note, hint, important, and tip +% should use the "lightbox" or the "heavybox" rendering. +\DeclareBoolOption[false]{heavynote} +\DeclareBoolOption[false]{heavyhint} +\DeclareBoolOption[false]{heavyimportant} +\DeclareBoolOption[false]{heavytip} % footnotes \DeclareStringOption[\mbox{ }]{AtStartFootnote} % we need a public macro name for direct use in latex file @@ -254,11 +252,21 @@ will be set to white}% % Default color chosen to be as in minted.sty LaTeX package! \sphinxDeclareSphinxColorOption{VerbatimHighlightColor}{{rgb}{0.878,1,1}} % admonition boxes, "light" style +% border color defaults to black +% at 6.2.0 also background color is possible, but it then triggers +% usage of the "sphinxheavybox" from sphinxlatexadmonitions.sty. \sphinxDeclareSphinxColorOption{noteBorderColor}{{rgb}{0,0,0}} \sphinxDeclareSphinxColorOption{hintBorderColor}{{rgb}{0,0,0}} \sphinxDeclareSphinxColorOption{importantBorderColor}{{rgb}{0,0,0}} \sphinxDeclareSphinxColorOption{tipBorderColor}{{rgb}{0,0,0}} +\sphinxDeclareSphinxColorOption{noteBgColor}{{rgb}{1,1,1}} +\sphinxDeclareSphinxColorOption{hintBgColor}{{rgb}{1,1,1}} +\sphinxDeclareSphinxColorOption{importantBgColor}{{rgb}{1,1,1}} +\sphinxDeclareSphinxColorOption{tipBgColor}{{rgb}{1,1,1}} % admonition boxes, "heavy" style +% border color defaults to black and background color to white +% As long as the color are not explicitly set via user options, +% the sphinxpackageboxes.sty code will actually not use them anyhow. \sphinxDeclareSphinxColorOption{warningBorderColor}{{rgb}{0,0,0}} \sphinxDeclareSphinxColorOption{cautionBorderColor}{{rgb}{0,0,0}} \sphinxDeclareSphinxColorOption{attentionBorderColor}{{rgb}{0,0,0}} @@ -285,18 +293,18 @@ will be set to white}% \def\spxstring@none{none} \def\spxstring@clone{clone} % -% Refactoring at 6.2.0 -% -------------------- +% Refactoring (and extension) at 6.2.0 +% ------------------------------------ % % - Legacy \dimen registers \sphinxverbatimborder, \sphinxverbatimsep, % \sphinxshadowsep, \sphinxshadowsize, and \sphinxshadowrule, % which had been deprecated have finally been removed, -% - No \dimen registers used at all (at some point the \dimen's -% \spxdimen@pre@border and \spxdimen@topic@border were still defined) -% as all dimensions are stored in macros. Dimen registers are used only -% by the box macros of sphinxpackageboxes.sty, and are initialized from -% the macro storage relative to each type (code-block, topic, ...) -% at time of use. +% +% - No \dimen registers used here, all dimensions are stored in macros. +% +% - "note/hint/..." types of admonitions now accept same user interface as +% for "warning/danger/...", and if this is used, they will be rendered +% using sphinxheavybox, not sphinxlightbox from sphinxlatexadmonitions.sty % % 6.2.0 batch defines in one go all auxiliaries for code blocks, topics, % and warning-type admonitions. Some needed add-ons due to maintaining @@ -351,6 +359,10 @@ will be set to white}% % macro prefix option prefix legacy option init value \spx@tempa{spx@pre@} {pre_} {verbatimborder} \fboxrule \spx@tempa{spx@topic@} {div.topic_} {shadowrule} \fboxrule +\spx@tempa{spx@note@} {div.note_} {noteborder} {0.5pt} +\spx@tempa{spx@hint@} {div.hint_} {hintborder} {0.5pt} +\spx@tempa{spx@important@}{div.important_}{importantborder}{0.5pt} +\spx@tempa{spx@tip@} {div.tip_} {tipborder} {0.5pt} \spx@tempa{spx@warning@} {div.warning_} {warningborder} {1pt} \spx@tempa{spx@caution@} {div.caution_} {cautionborder} {1pt} \spx@tempa{spx@attention@}{div.attention_}{attentionborder}{1pt} @@ -389,10 +401,18 @@ will be set to white}% % #1 macro prefix #6 option prefix init value \spx@tempa{spx@pre@} {pre_} \fboxsep \spx@tempa{spx@topic@} {div.topic_} {5pt} -% MEMO: prior to 5.1.0 padding was not separately customizable -% from border width for warning type admonitions. The below -% keeps the legacy behavior of a constant borderwidth+padding. -% The dim expression is not evaluated yet, only at time of use. +% MEMO: prior to 6.2.0, "note" type admonitions used sphinxlightbox automatically +% and had no interface to set the padding parameters needed by sphinxheavybox. +% At 6.2.0 they acquire such interface and the default is set as for legacy +% default of "warning" type. +\spx@tempa{spx@note@} {div.note_} {\dimexpr.6\baselineskip-\spx@note@border\relax} +\spx@tempa{spx@hint@} {div.hint_} {\dimexpr.6\baselineskip-\spx@hint@border\relax} +\spx@tempa{spx@important@}{div.important_} {\dimexpr.6\baselineskip-\spx@important@border\relax} +\spx@tempa{spx@tip@} {div.tip_} {\dimexpr.6\baselineskip-\spx@tip@border\relax} +% MEMO: prior to 5.1.0 padding was not separately customizable from border +% width for warning type admonitions. The below keeps the legacy behavior of a +% constant borderwidth+padding. The dim expression is not evaluated yet, only +% at time of use. \spx@tempa{spx@warning@} {div.warning_} {\dimexpr.6\baselineskip-\spx@warning@border\relax} \spx@tempa{spx@caution@} {div.caution_} {\dimexpr.6\baselineskip-\spx@caution@border\relax} \spx@tempa{spx@attention@}{div.attention_} {\dimexpr.6\baselineskip-\spx@attention@border\relax} @@ -424,12 +444,16 @@ will be set to white}% % macro prefix option prefix init value \spx@tempa{spx@pre@} {pre_} {3pt}% new default at 6.0.0 \spx@tempa{spx@topic@} {div.topic_} \z@ +\spx@tempa{spx@note@} {div.note_} \z@ % new at 6.2.0 +\spx@tempa{spx@hint@} {div.hint_} \z@ % new at 6.2.0 +\spx@tempa{spx@important@}{div.important_} \z@ % new at 6.2.0 +\spx@tempa{spx@tip@} {div.tip_} \z@ % new at 6.2.0 \spx@tempa{spx@warning@} {div.warning_} \z@ \spx@tempa{spx@caution@} {div.caution_} \z@ \spx@tempa{spx@attention@}{div.attention_} \z@ \spx@tempa{spx@danger@} {div.danger_} \z@ \spx@tempa{spx@error@} {div.error_} \z@ -\spx@tempa{spx@box@} {box_} {3pt}% new and tentative default at 6.2.0 +\spx@tempa{spx@box@} {box_} {3pt}% new at 6.2.0 % Shadow keys % @@ -442,12 +466,16 @@ will be set to white}% % macro prefix \spx@tempa{spx@pre@} \spx@tempa{spx@topic@} +\spx@tempa{spx@note@} % new at 6.2.0 +\spx@tempa{spx@hint@} % new at 6.2.0 +\spx@tempa{spx@important@} % new at 6.2.0 +\spx@tempa{spx@tip@} % new at 6.2.0 \spx@tempa{spx@warning@} \spx@tempa{spx@caution@} \spx@tempa{spx@attention@} \spx@tempa{spx@danger@} \spx@tempa{spx@error@} -\spx@tempa{spx@box@}% new at 6.2.0 +\spx@tempa{spx@box@} % new at 6.2.0 % \def\spx@tempa#1{% #1 = macro prefix \expandafter\spx@tempb @@ -483,6 +511,10 @@ will be set to white}% \spx@tempa{spx@topic@} {div.topic_} % This corresponds to the legacy parameters of ShadowBox \spx@topic@shadow@setter 4pt 4pt {} \@nnil +\spx@tempa{spx@note@} {div.note_} % new at 6.2.0 +\spx@tempa{spx@hint@} {div.hint_} % new at 6.2.0 +\spx@tempa{spx@important@}{div.important_} % new at 6.2.0 +\spx@tempa{spx@tip@} {div.tip_} % new at 6.2.0 \spx@tempa{spx@warning@} {div.warning_} \spx@tempa{spx@caution@} {div.caution_} \spx@tempa{spx@attention@}{div.attention_} @@ -490,7 +522,7 @@ will be set to white}% \spx@tempa{spx@error@} {div.error_} \spx@tempa{spx@box@} {box_}% new at 6.2.0 -% Support for legacy shadowsize +% Support for legacy shadowsize (topic/contents) % This definition was broken at 5.1.0 and fixed at 6.1.2 \define@key{sphinx}{shadowsize}{% \edef\spx@topic@shadow@xoffset{\number\dimexpr#1\relax sp}% @@ -520,6 +552,10 @@ will be set to white}% % macro prefix \spx@tempa{spx@pre@} \spx@tempa{spx@topic@} +\spx@tempa{spx@note@} +\spx@tempa{spx@hint@} +\spx@tempa{spx@important@} +\spx@tempa{spx@tip@} \spx@tempa{spx@warning@} \spx@tempa{spx@caution@} \spx@tempa{spx@attention@} @@ -553,17 +589,21 @@ will be set to white}% \csname KV@sphinx@pre_border-TeXcolor\endcsname \expandafter\let\expandafter\KV@sphinx@VerbatimColor \csname KV@sphinx@pre_background-TeXcolor\endcsname -% macro prefix option prefix color name prefix % MEMO: prior to 6.2.0, internal color names started with sphinxtopic, not % sphinxTopic, and it was sphinxTopicBackgroundColor, not sphinxtopicBgColor. +% macro prefix option prefix color name prefix \spx@tempa{spx@topic@} {div.topic_} {sphinxtopic}% (no legacy interface) +\spx@tempa{spx@note@} {div.note_} {sphinxnote} % new at 6.2.0 +\spx@tempa{spx@hint@} {div.hint_} {sphinxhint} % new at 6.2.0 +\spx@tempa{spx@important@}{div.important_} {sphinximportant} % new at 6.2.0 +\spx@tempa{spx@tip@} {div.tip_} {sphinxtip} % new at 6.2.0 \spx@tempa{spx@warning@} {div.warning_} {sphinxwarning} \spx@tempa{spx@caution@} {div.caution_} {sphinxcaution} \spx@tempa{spx@attention@}{div.attention_} {sphinxattention} \spx@tempa{spx@danger@} {div.danger_} {sphinxdanger} \spx@tempa{spx@error@} {div.error_} {sphinxerror} \spx@tempa{spx@box@} {box_} {sphinxbox}% new at 6.2.0 - % Keep legacy sphinxsetup interface for warning type notices + % Keep legacy sphinxsetup color options interface for "strong" admonitions \def\spx@tempa#1#2{% #1 = option prefix, #2 = legacy option prefix \expandafter\let\csname KV@sphinx@#2BorderColor\expandafter\endcsname \csname KV@sphinx@#1border-TeXcolor\endcsname @@ -576,6 +616,71 @@ will be set to white}% \spx@tempa{div.danger_} {danger} \spx@tempa{div.error_} {error} + % Let us recreate the legacy {note,...}BorderColor option interface + \def\spx@tempa#1#2{% #1 = CSS like option prefix, #2 = legacy option prefix + \expandafter\let\csname KV@sphinx@#2BorderColor\expandafter\endcsname + \csname KV@sphinx@#1border-TeXcolor\endcsname + } + \spx@tempa{div.note_} {note} + \spx@tempa{div.hint_} {hint} + \spx@tempa{div.important_} {important} + \spx@tempa{div.tip_} {tip} + +% For note type admonitions, redefine all CSS-like named options to trigger +% the "heavybox" path. This goes via rather hardcore TeX here. +% +% MEMO: the noteBorderColor and noteborder legacy options have already been +% re-created and they do not trigger the "heavybox" as their meaning will not +% be modified in the loop below contrarily to their CSS counterparts +% border-TeXcolor and border-width. +\def\spx@tempa#1{\if\relax#1\expandafter\@gobble + \else + \toks@{##1}% + \expandafter\def\csname KV@sphinx@div.note_#1\expandafter\endcsname + \the\toks0\expandafter{% + \csname spx@opt@heavynotetrue\expandafter\expandafter\expandafter\endcsname + \csname KV@sphinx@div.note_#1\endcsname{##1}}% + \expandafter\def\csname KV@sphinx@div.hint_#1\expandafter\endcsname + \the\toks0\expandafter{% + \csname spx@opt@heavyhinttrue\expandafter\expandafter\expandafter\endcsname + \csname KV@sphinx@div.hint_#1\endcsname{##1}}% + \expandafter\def\csname KV@sphinx@div.important_#1\expandafter\endcsname + \the\toks0\expandafter{% + \csname spx@opt@heavyimportanttrue\expandafter\expandafter\expandafter\endcsname + \csname KV@sphinx@div.important_#1\endcsname{##1}}% + \expandafter\def\csname KV@sphinx@div.tip_#1\expandafter\endcsname + \the\toks0\expandafter{% + \csname spx@opt@heavytiptrue\expandafter\expandafter\expandafter\endcsname + \csname KV@sphinx@div.tip_#1\endcsname{##1}}% + \fi + \spx@tempa +} +\spx@tempa{border-width}% + {border-top-width}{border-right-width}{border-bottom-width}{border-left-width}% + {box-decoration-break}% + {padding}% + {padding-top}{padding-right}{padding-bottom}{padding-left}% + {border-radius}% + {border-top-left-radius}{border-top-right-radius}% + {border-bottom-right-radius}{border-bottom-left-radius}% + {box-shadow}% + {border-TeXcolor}{background-TeXcolor}{box-shadow-TeXcolor}% +\relax + +% Now we add at 6.2.0 {note,...}BgColor named options which will trigger +% the "heavybox" as they are \let to the background-TeXColor option which has +% already been enhanced to set the boolean for rendering via "heavybox". +% This is in contrast with legacy {note,...}BorderColor. + \def\spx@tempa#1#2{% #1 = CSS like option prefix, #2 = legacy style option prefix + \expandafter\let\csname KV@sphinx@#2BgColor\expandafter\endcsname + \csname KV@sphinx@#1background-TeXcolor\endcsname + } + \spx@tempa{div.note_} {note} + \spx@tempa{div.hint_} {hint} + \spx@tempa{div.important_} {important} + \spx@tempa{div.tip_} {tip} + + \DeclareDefaultOption{\@unknownoptionerror} \ProcessKeyvalOptions* % don't allow use of maxlistdepth via \sphinxsetup. diff --git a/sphinx/texinputs/sphinxlatexadmonitions.sty b/sphinx/texinputs/sphinxlatexadmonitions.sty index 3f4541c40f8..896c711aee2 100644 --- a/sphinx/texinputs/sphinxlatexadmonitions.sty +++ b/sphinx/texinputs/sphinxlatexadmonitions.sty @@ -11,6 +11,7 @@ % This is a dispatch supporting % % - note, hint, important, tip (via sphinxlightbox) +% (also optionally via sphinxheavybox since 6.2.0) % - warning, caution, attention, danger, error (via sphinxheavybox) % % Each sphinx environment can be redefined by user. @@ -35,7 +36,14 @@ % Some are quite plain \newenvironment{sphinxseealso}[1]{\sphinxstrong{#1:}\par\nopagebreak}{} -% the spx@notice@bordercolor etc are set in the sphinxadmonition environment +% This \dimen register is a legacy relic from Sphinx 1.5, as well as +% spx@notice@border@color (used in sphinxlightbox environment and set in +% sphinxadmonition environment) which one could dispose of, using \spx@notice +% which is defined by sphinxadmonition environment. Let's simply keep as used +% since 1.5. +\newdimen\spx@notice@border + +% spx@notice@bordercolor and \spx@notice@border are set in sphinxadmonition environment \newenvironment{sphinxlightbox}{% \par \noindent{\color{spx@notice@bordercolor}% @@ -51,78 +59,59 @@ \rule[\dimexpr.4\baselineskip-\spx@notice@border\relax] {\linewidth}{\spx@notice@border}}\hss}\allowbreak }% end of sphinxlightbox environment definition -% may be renewenvironment'd by user for complete customization + +% note/hint/important/tip notices +% +% Since 1.5 these environments are named individually to allow user to +% redefine them entirely. +% +% The Sphinx definitions were done like this, prior to 6.2.0: +% +% \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. \newenvironment{sphinxnote}[1] - {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}} + {\edef\spx@env{sphinx\ifspx@opt@heavynote heavy\else light\fi box}% + \expanded{\noexpand\begin{\spx@env}}\sphinxstrong{#1} } + {\expandafter\end\expandafter{\spx@env}} \newenvironment{sphinxhint}[1] - {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}} + {\edef\spx@env{sphinx\ifspx@opt@heavyhint heavy\else light\fi box}% + \expanded{\noexpand\begin{\spx@env}}\sphinxstrong{#1} } + {\expandafter\end\expandafter{\spx@env}} \newenvironment{sphinximportant}[1] - {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}} + {\edef\spx@env{sphinx\ifspx@opt@heavyimportant heavy\else light\fi box}% + \expanded{\noexpand\begin{\spx@env}}\sphinxstrong{#1} } + {\expandafter\end\expandafter{\spx@env}} \newenvironment{sphinxtip}[1] - {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}} -% or just use the package options -% these are needed for common handling by notice environment of lightbox -% and heavybox but they are currently not used by lightbox environment -% and there is consequently no corresponding package option -\definecolor{sphinxnoteBgColor}{rgb}{1,1,1} -\definecolor{sphinxhintBgColor}{rgb}{1,1,1} -\definecolor{sphinximportantBgColor}{rgb}{1,1,1} -\definecolor{sphinxtipBgColor}{rgb}{1,1,1} + {\edef\spx@env{sphinx\ifspx@opt@heavytip heavy\else light\fi box}% + \expanded{\noexpand\begin{\spx@env}}\sphinxstrong{#1} } + {\expandafter\end\expandafter{\spx@env}} -% Others get more distinction -% This setup macro has somewhat peculiar names for colors, this is -% heritage of the evolution of code while keeping a common base for both -% "warning"-type and "note"-type notices and backward compatibility -\def\spx@admonitions@boxes@fcolorbox@setup{% - \spx@boxes@fcolorbox@setup - {\spx@noticetype}{spx@notice@bordercolor}% - {spx@notice@bgcolor}% - {sphinx\spx@noticetype ShadowColor}% -} -% rescue code in case sphinxheavybox is used for note-like notices -% (this is executed if there is no radius.topleft associated macro) -\def\spx@admonitions@boxes@fcolorbox@setup@fallback{% - \spx@boxes@border@top \spx@notice@border - \spx@boxes@border@right \spx@notice@border - \spx@boxes@border@bottom\spx@notice@border - \spx@boxes@border@left \spx@notice@border - \spx@boxes@border \spx@notice@border -% legacy behavior for padding - \spx@boxes@padding@top \dimexpr.6\baselineskip-\spx@notice@border\relax - \spx@boxes@padding@right \spx@boxes@padding@top - \spx@boxes@padding@bottom\spx@boxes@padding@top - \spx@boxes@padding@left \spx@boxes@padding@top -% straight corners - \spx@boxes@radius@topleft \z@ - \spx@boxes@radius@topright \z@ - \spx@boxes@radius@bottomright \z@ - \spx@boxes@radius@bottomleft \z@ -% legacy has no shadow (no need to set \ifspx@boxes@shadowinbbox) - \spx@boxes@withshadowfalse - \spx@boxes@insetshadowfalse - \spx@boxes@withshadowcolorfalse -% assume background color although there is no public interface, -% sphinxnoteBgColor et al. are defined above and let to white - \spx@boxes@withbackgroundcolortrue - \sphinxcolorlet{spx@boxes@backgroundcolor}{spx@notice@bgcolor}% -% assume always with border color (for simplicity sake, again, and this -% time there is a public interface) - \spx@boxes@withbordercolortrue - \sphinxcolorlet{spx@boxes@bordercolor}{spx@notice@bordercolor}% - \def\spx@boxes@fcolorbox{\spx@boxes@fcolorbox@rectangle}% -} +% warning/caution/attention/danger/error get more distinction +% % Code adapted from framed.sty's "snugshade" environment. % Nesting works (inner frames do not allow page breaks). \newenvironment{sphinxheavybox}{\par - \ifcsname spx@\spx@noticetype @radius@topleft\endcsname - \expandafter\@firstoftwo - \else - % attempt to use sphinxheavybox without the circa 20 needed style - % parameters, i.e., for one of the light notice types - \expandafter\@secondoftwo - \fi - \spx@admonitions@boxes@fcolorbox@setup - \spx@admonitions@boxes@fcolorbox@setup@fallback + % 6.2.0 allows to not have to distinguish here between warning type notices + % which always use sphinxheavybox or note type notices which might use it. + % (MEMO: it is not a problem here if there is no sphinxShadowColor, + % as it used only if set) + \spx@boxes@fcolorbox@setup + {\spx@noticetype}{spx@notice@bordercolor}% + {spx@notice@bgcolor}% + {sphinx\spx@noticetype ShadowColor}% % Those are used by sphinxVerbatim if the \ifspx@inframed boolean is true \setlength{\FrameRule}{0.5\dimexpr\spx@boxes@border@top+\spx@boxes@border@bottom\relax}% % MEMO: prior to 5.1.0 \FrameSep was determined as 0.6\baselineskip - @@ -183,7 +172,17 @@ % arrange for similar spacing below frame as for "light" boxes. \vskip .4\baselineskip }% end of sphinxheavybox environment definition -% may be renewenvironment'd by user for complete customization + +% - Since 1.5 these environments are named individually to allow user to +% redefine them entirely. +% +% - Since 5.1.0, sphinxheavybox is more versatile and four border widths, four +% padding widths, four corner radii, optional shadow, and three colors can all +% be modified via CSS-named alike options. +% +% - 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. \newenvironment{sphinxwarning}[1] {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}} \newenvironment{sphinxcaution}[1] @@ -194,19 +193,18 @@ {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}} \newenvironment{sphinxerror}[1] {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}} -% or just use package options % 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}% - % set parameters of heavybox/lightbox + % set the parameters common to lightbox and heavybox environments \sphinxcolorlet{spx@notice@bordercolor}{sphinx#1BorderColor}% \sphinxcolorlet{spx@notice@bgcolor}{sphinx#1BgColor}% \spx@notice@border \dimexpr\csname spx@#1@border\endcsname\relax - % start specific environment, passing the heading as argument + % trigger the sphinx environment, #2=heading is passed as argument \begin{sphinx#1}{#2}} - % workaround some LaTeX "feature" of \end command - {\edef\spx@temp{\noexpand\end{sphinx\spx@noticetype}}\spx@temp} + % workaround some LaTeX "feature" of \end command (can't use "sphinx#1" here) + {\expanded{\noexpand\end{sphinx\spx@noticetype}}} \endinput