LaTeX: add \sphinxbox command
#11224
Conversation
jfbu
force-pushed
the
latex_sphinxbox
branch
2 times, most recently
from
8dca35d
to
0f7e353
Compare
|
In the final version, the key names have changed a bit from what is in my initial message on top, no more a Here is an example rendering: With this in conf.py and Some text before :guilabel:`fa-folder` some text :menuselection:`Edit` some
text :kbd:`Ctrl-x Ctrl-f`as input. |
|
Failure of |
|
Excellent! I made my own with tcolorbox as this package makes it easy. But one thing it cannot do is allowing inline boxes to break between words (even less so inside words). Are these boxes allowed to break? Can it be an option? |
|
@n-peugnet Thanks for comment! About:
Sadly, no. I added a comment in the source: sphinx/sphinx/texinputs/sphinx.sty Lines 807 to 813 in ee3c720 With a few more details: I am not aware of a LaTeX package offering fully functional (i.e. with no or very few restrictions on input) breakable horizontal boxes.
There is a well-known 20+ years old package called soul which attempts to add underlining or other effets, and in particuler background highlighting via its macro For simply adding a background color, the soul In the past I have implemented for Sphinx the line-breaking of long code lines highlighted by Pygments: the As long as you control fully the input mark-up you can probably do something. In the case of highlight code, a very important thing is that the Let's say you have solved all these problems, there is still some work to do for boxing with decorations such as a border or a shadow or rounded corners as provided by Thus if you use Many years ago I had applied some highlighting of my own in the documentation of a LaTeX package I authored. But all the little colorboxes ended up causing some stack overflow problem (not sure if I was using pdflatex or latex+dvipdfmx though, the latter behaving differently in matters of colors, it can not have multiple color stacks). Probably the LuaTeX is the more-or-less sole hope that one can do something general: it offers hooks into the node lists created by TeX. Perhaps, probably one can use that. However this would be heavy-duty LuaTeX thing and I am simply lacking both the knowledge and the will to invest time into it. If it was a matter of a one-hour effort perhaps, but this looks more like weeks... and I searched a bit and did not identify a LuaTeX-specific add-on offering this, perhaps it exists nevertheless. (maybe this on overleaf can be a LuaTeX ouverture). (perhaps if you ask on a LuaTeX forum they will tell you of course it is well-known and you only have to do this or that...) .. [1]: digression: it is a historical legacy from prehistory of package that Sphinx uses |
|
@jfbu Thank you for this very detailed answer. Sorry I could have checked the code myself before asking. I did some research of my own back when I made my version of this (that will probably be replaced by yours once I get to upgrade Sphinx), and I quickly understood that it was very complicated to do in LaTeX. The only beautiful solution I found was indeed based on soulutf8 package combined with Tikz and the code is still quite complicated. |
|
@n-peugnet ah well of course I had forgotten the more modern stuff which uses TikZ ability and multiple passes to put absolute positional marks on the page and then add graphical layers on next run. I am not sure this works also with platex, and I saw problem reports with xetex from 2016 circa, perhaps solved since (pdftex has built-in such things The tikzmark package has a highlighting library, documented starting on page 17 of its pdf documentation, which seems to implement exactly the naive idea one could have about positioning a start and an end, and interpolating. However, you already point out to a more advanced method indeed based upon tikzmark but in combination with soul. Why they have to use soul may have to do with allowing contents of varying height, or allowing pagebreaks. But using About LuaTeX, I should have digged a bit more, there is the lua-ul package whose description is:
The important part here is: the underlined text can use arbitrary commands. However I can not engage into LuaLaTeX only code here at Sphinx. (assuming it is possible to achieve what we want with it). I think though, I can provide an experimental The last two days I completed and finished my on-going refactoring of Sphinx LaTeX internals with adding support for |
|
@n-peugnet I have implemented an experimental breakable box. Maybe I will include this as something to use at your own risk. From previous experience with using many small boxes one next to the other, there may be problems with long documents of pdf color stack.
Example of output:
index.rst: TEST
----
aaaa bbbb some text :guilabel:`some very œîôêç éèàù éèàù éèàù éèàù œîôêç éèàù éèàù
éèàù éèàù œîôêç éèàù éèàù éèàù éèàù œîôêç éèàù éèàù éèàù éèàù œîôêç éèàù éèàù éèàù
éèàù œîôêç éèàù éèàù éèàù éèàù œîôêç éèàù éèàù éèàù éèàù œîôêç éèàù éèàù éèàù éèàù
œîôêç éèàù éèàù éèàù éèàù œîôêç éèàù éèàù éèàù éèàù œîôêç éèàù éèàù éèàù éèàù œîôêç
éèàù éèàù éèàù éèàù œîôêç éèàù éèàù éèàù éèàù œîôêç éèàù éèàù éèàù éèàù œîôêç éèàù
éèàù éèàù éèàù long guilabel` This was a very very long guitlabel. Did it wrap correctly?conf.py: The LaTeX with an extra \sphinxAtStartPar
aaaa bbbb some text \sphinxguilabel{some very œîôêç éèàù éèàù éèàù éèàù œîôêç éèàù éèàù
éèàù éèàù \textit{œîôêç éèàù éèàù éèàù éèàù œîôêç éèàù éèàù éèàù éèàù œîôêç éèàù éèàù éèàù
éèàù œîôêç éèàù éèàù éèàù éèàù œîôêç éèàù éèàù éèàù éèàù œîôêç éèàù éèàù éèàù éèàù
œîôêç éèàù éèàù éèàù éèàù œîôêç éèàù éèàù éèàù éèàù œîôêç éèàù éèàù éèàù éèàù œîôêç
éèàù éèàù éèàù éèàù} œîôêç éèàù éèàù éèàù éèàù œîôêç éèàù éèàù éèàù éèàù œîôêç éèàù
éèàù éèàù éèàù long guilabel} This was a very very long guitlabel. Did it wrap correctly?I tested only UTF-8 with some diacritics useful in my mother tongue. If you want to test it at your locale you should checkout the wip branch https://github.com/jfbu/sphinx/tree/wip_breakable_sphinxbox. The commit is jfbu@e8efd18 |
|
Merge of master into my workbranch wip_breakable_sphinxbox has allowed "breakablebox" to support rounded corners.
But the -one-box-per-character things induces aliasing artifacts at box junctures at least in my evince viewer at some zoom levels. One sees them above. I am not sure if they come from some minuscule differences in coordinates, but many many years ago I experimented with such problems in a context where one was sure all coordinates computed by TeX where perfectly identical from one rectangle to the adjacent one. Then perhaps something happens when converting to PostScript or PDF internals. Typically one sees some fine border but when zooming it sometimes disappear or reappear but never changes size on screen. Personnaly I would prefer occasional problem with a non-breaking box than this. After some polishing I might merge it though, but will not consider this as a feature to be maintained at all costs. There is a big difference between the user point of view who wants things done and the maintainer point of view: already Sphinx for many years allows a lot of LaTeX customization such as using the full TikZ for such Merge of master allows also varying border width also for rounded boxes: |
|
This is very impressive! I didn't expect you to do it when I posted my previous comment. I hope you didn't feel obliged to do it because of me and that it was a fun experiment!
I completely agree with you on this. I was more suggesting the idea and linking to my findings to get your opinion and maybe give you some ideas. 🙂 |
|
@n-peugnet I do understand you feel a bit concerned in view of my recent frenzy of activities in Sphinx LaTeX these last few days and I can confirm that if I were to keep going like this for weeks, it would be time to get me to some psy counseling ;-) If I did it is of course because it was a fun experiment. I do feel a bit depressed though in view of the PDF viewers artefacts at box junctures, but I knew about this already. This only confirms that the kind of approach your findings already identified is definitely better: except in LuaTeX it is not possible to hook into some of TeX's paragraph building at macro level, and the only, and best, way is when graphics drivers provide the means to put absolute marks on the page, and then decorate on top of that. But... the only reasonable things, in view of having to support pdflatex, lualatex, xelatex and platex and uplatex, is to benefit from some existing framework, hence TikZ/pgf which does allow to produce very beautiful graphics but is really a big dependency. So in immediate future it can not be loaded by Sphinx in a systematic way. MetaPost could be another approach. But this may reinforce the LuaLaTeX, as same people who contributed to LuaTeX revived MetaPost these last years. Now yesterday I had this fun experiment with breakable box, and indirectly this caused me to revisit my code from last year doing rounded boxes, and it motivated me to take out from it the use of "stroke" to draw the border, which was causing big hurdles to the breakable boxes, and repalce it all with only "fill path" operations. As it turns out this considerably reduced the complexity of the code (roughly a division by 2 of its length), but I hastily replaced all removed codelines by a lot of possibly repetitive code comments, as is my habit. In total, your initial query about boxing for PDF output came at a time when I had only right then completed an effort to revive and revisit some work from last year to add rounded boxes to Sphinx. Turns out that the further effort for For the next few months, I will have to cater for completely different tasks, so this flood of changes has come to an end today. Only last step is to decide whether or not to add the experimental breakable box code which I will think about in next few days. I added possibility of rounded boxes with very little overload last year, but they become default only at 6.0.0 and only for code-blocks. At 7.0.0 probably some defaults will be chosen for the admonitions to be less dumb than now, and in particular in case of page-breaks. Some years ago warning type notices did not break across pages; and the "shadow box" construct for topic directive did not either; now all of code-blocks, all admonitions, and topic directive all use the same underlying core code and have all the same customizability with only some legacy difference about whether border and padding go to page margin or say in text area. Somewhere in my numerous comment I said it was very simple for users (knowledgeable in LaTeX) to hook TikZ or tcolorbox which uses it into stuff like |
See discussion at sphinx-doc#11224 This is about a variant of Sphinx 6.2.0 \sphinxbox, which will break across lines. The way this is done is to split the input into characters, handling encountered macros in various more or less apt ways in passing and box them separately adapting the shape as first and last must be handled especially. Works with one-character input, even empty input. See the file for more explanations. Decision has been made not to merge into Sphinx. This commit puts the experimental code in a separate package in order to make using it as easy as possible. Simply grab the file, put it at some place where TeX can find it or in your project with latex_additional_files, and add \usepackage{sphinxbreakablebox} to preamble. Use at own risk. It is not excluded that renamings of Sphinx internals could at some future point break the file, but I will try to sync with upstream as long as I contribute maintenance to Sphinx LaTeX.
|
@n-peugnet I did some final wrap-up and my effort is at https://github.com/jfbu/sphinx/tree/wip_breakable_sphinxbox To use, grab the file More comments inside the file. This will not get merged in Sphinx core for time being, too hacky, too much workload to test it thoroughly in Sphinx context, and the problems with the PDF viewers artifacts. |
See discussion at sphinx-doc#11224 This is about a variant of Sphinx 6.2.0 \sphinxbox, which will break across lines. The way this is done is to split the input into characters, handling encountered macros in various more or less apt ways in passing and box them separately adapting the shape as first and last must be handled especially. Works with one-character input, even empty input. See the file for more explanations. Decision has been made not to merge into Sphinx. This commit puts the experimental code in a separate package in order to make using it as easy as possible. Simply grab the file, put it at some place where TeX can find it or in your project with latex_additional_files, and add \usepackage{sphinxbreakablebox} to preamble. Use at own risk. It is not excluded that renamings of Sphinx internals could at some future point break the file, but I will try to sync with upstream as long as I contribute maintenance to Sphinx LaTeX.
See discussion at sphinx-doc#11224 This is about a variant of Sphinx 6.2.0 \sphinxbox, which will break across lines. The way this is done is to split the input into characters, handling encountered macros in various more or less apt ways in passing and box them separately adapting the shape as first and last must be handled especially. Works with one-character input, even empty input. See the file for more explanations. Decision has been made not to merge into Sphinx. This commit puts the experimental code in a separate package in order to make using it as easy as possible. Simply grab the file, put it at some place where TeX can find it or in your project with latex_additional_files, and add \usepackage{sphinxbreakablebox} to preamble. Use at own risk. It is not excluded that renamings of Sphinx internals could at some future point break the file, but I will try to sync with upstream as long as I contribute maintenance to Sphinx LaTeX.
Subject: add
\sphinxboxuser interface for inline boxes with possibly rounded corners, background color, even a shadow.Here is for example what one obtains with the code at time of creation of the PR and this user extra in conf.py:
(edit: see next comment for final syntax, no more
boxborder,boxsep)for customized rendering in PDF via LaTeX of the
:guilabel:role:Code is almost done but still WIP due to desire to proceed further with the refactoring of support for CSS-like
sphinxsetupoptions (already in master branch) as there is still potential for sharing some almost identical TeX code which is currently repeated at various places, and got again repeated in the definition of\sphinxbox.Also perhaps add some
\newsphinxboxin thetcolorboxspirit.And also hesitation about defaults.
(we can discuss separately the specific #11213 question about
:guilabel:, whether to modify its default or not).Expect some force pushes, WIP.
Question about a "display" variant will not be part of this PR, which is only about (unbreakable) "horizontal" boxing, i.e. of inline elements not display elements.
Feature or Bugfix
Related