Use a box in the pdf output for guilabel

[12rambau]

currently guilabel are displayed as little boxes in the html outputs in most of the the theme I know like rdt:

In the latex build it's only represented as a Italic word. what if instead we use a little box around the text to display it as an actual guilabel as this example:

to build this I simply added the tcolorbox package and created a custom command:

\newtcbox{\sphinxbtn}[1][]{box align=base, nobeforeafter, size=small, boxsep=2pt, #1}

My proposal here is to replace the \guilabel one. What do you think ?

[jfbu]

The mark-up is via LaTeX macro \sphinxguilabel. Its default definition

\protected\def\sphinxguilabel#1{\emph{#1}}

is indeed a bit dull. But you can replace it by

\protected\def\sphinxguilabel#1{\mybtn{#1}}

with \mybtn defined via \newtcbox. The \protected\def rather than \renewcommand is for reasons of the thing ending up in titles, which LaTeX always has trouble with ("moving arguments", "fragile macros", "token not allowed in a PDF string", this kind of things).

Two remarks

1. we will not load tcolorbox per default. It has tremendous LaTeX dependencies and if one uses it extensively slows down the build significantly. I tested this with using it systematically for code boxes, and it was an order of magnitude slow-down compared to the pict2e based approach which has been added to Sphinx at 5.1.0 and activated per default at 6.0.0.
2. the latex support code available in Sphinx since 5.1.0 for rounded boxes with background color and more has its user interface via 'sphinxsetup' options, but no such interface exists for using directly for other purposes, as in your guilabel proposal, with a tcolorbox-like key=value syntax. Surely this could be added to our support file sphinxpackageboxes.sty and adding this as feature request.

Once such a friendly user interface is added, you could have a \sphinxbox[bgcolor=.., width=..., radius=..., ]{contents} kind of thing. The support code is in Sphinx since 5.1.0, but is lacking high-level access.

update: working on this for 6.2.0

[jfbu]

11224 starts implementing user interface for a \sphinxbox which will do most of what a \tcbox would do, only more efficiently. The command \sphinxbox will take a key-value comma separated list where the keys are named as in https://www.sphinx-doc.org/en/master/latex.html#additional-css-like-sphinxsetup-keys: you can take all options described there for code-blocks, i.e. those with pre_ prefix, and the options for \sphinxbox will be named similarly except for box_ prefix. Also the boxborder and boxsep are aliases for box_border-width and box_padding respectively. In particular the code already supports adding a shadow, which can be external or inset. And there are colors for the border, the background, and the optional shadow.

[12rambau]

thanks for starting the PR, I will look closely to what you're doing, to be fair I would be glad to use something else than tcbox so I'll wait and see what happens next

[jfbu]

@12rambau I have now merged #11224 for 6.2.0. This completes some intense refactoring and streamlining so that the already available toolbox could be made usable via a user level command \sphinxbox. Once this refactoring was complete, adding the \sphinxbox cost only a dozen or two dozen lines (plus documentation).

So your question becomes now: should we by default employ \sphinxbox for elements such as :guilabel:. I am rather in favor, as I initiated improvments to the LaTeX looks recently by adopting rounded corners for code-blocks and usage of a background color. But I have left so far other display elements as in their legacy state, i.e. admonitions and topics.

With 'sphinxsetup' and \sphinxsetup all these display elements can be customized and now inline text elements can be rendered in nice color boxes if desired using \sphinxbox.

It would thus be possible to develop now LaTeX theming quite analogous to HTML theming.

If you have a specific design favorite for :guilabel: please open a PR with the corresponding modifications in sphinxlatexstyletext.sty of the default configuration for \sphinxguilabel, where you can now use \sphinxbox. Then this PR if nobody objects againts can be merged.

[12rambau]

thanks @jfbu and sorry for leaving this on stale for so long. I'll have a look at a PR in the upcoming weeks.