#339 literal block with caret symbol inside an admonition causes failed PDF build from latex

[jfbu]

Test file:

Test
====

.. important::

   This is a power::

     x^2

Then do rst2latex.py test.rst test.tex and latex test.tex. Gives error:

! Missing $ inserted.
<inserted text> 
                $
l.69 }

This is caused by alltt environment being encapsulated as argument to \DUadmonition[important] macro hence too late to change catcodes.

[Günter Milde]

It seems we need the new "class environments" for admontions, too.
The \DUadmonition command pre-dates the introduction of "class environments" for
block level elements in version 0.14 and was not changed then.

The attached example emulates an admonition including a literal block using your
fbox/savebox example from https://tex.stackexchange.com/questions/145812/using-fbox-in-a-newenvironment.

[jfbu]

Can you try with attached file

[jfbu]

I should have used \linewidth, not \textwidth. But I don't know to what extends admonitions are nestable in quoted environments (lists) with rst2latex.py ...

[Günter Milde]

Admonitions are nestable and should use 0.9\linewidth (this is also wrong with the current implementation).

[jfbu]

caret2.rst contains some mysterious \vbox{} but this was only to reinstore some vertical space due to the quote environment being in a minipage. In general there is no reason a quote environment is last thing in the admonition, hence my method is no good for that. I have deadlines currently so I can not research that more in the immediate future (in Sphinx we use framed package not an unbreakable minipage, but this requires a lot of tuning up and I briefly tried here but could not immediately get same position of frame, due to a sequence of LaTeX features). The lrbox is not compatible with lists inside the contents, this is why I use a minipage, because otherwise it is very hard to communicate to LaTeX wished-for dimensions, e.g. "use a margin of 1cm more on left", this has no user interface in LaTeX standard classes (the more or less only way is to use custom list parameters) but is easier in KOMA-script for example. In software it is very surprising but true that even very deficient frameworks can end up ruling an entire ecological system!

[Günter Milde]

Thank you for your work on investigating the issue and possible workarounds.
I hope we can find an universally working, simple solution even if this may take some time.

The "framed" package may be overkill (a new dependency on a package that is considered "extra" by Debian) and the default use case for admonitions is also served with unbreakable boxes. Of course it should be possible to use "framed" in a class-based customization.

[jfbu]

Hi Günter, can you try out this attachment. I have not done more testing but it might be ok solution.

[jfbu]

s/textwidth/linewidth/g in caret4.rst (again ...)

[Günter Milde]

A comparison of several alternatives is attached (LaTeX and PDF, as rSTt would require a custom preamble).

• The "framed" and "mdframed" variants are most simple in terms of definition but require additional packages.
• There is no need to exactly reproduce the current look (or the look in HTML). I'd prefer a simple, failproof implementation and documentation on how to style this in the preamble.
• With paragraph separation by "parskip.sty", the "vertical-space fixed" alternative does not differ from the simpler lrbox approach.
• We could also just fully escape TeX special characters in a literal block. However, IMV it is cleaner to change to an "admonition environment", because admonitions are block-level elements.

[Günter Milde]

Test output (with "parskip").

[Günter Milde]

The following patch should fix the problem (using the lrbox approach).
For backwards compatibility, the setting "new-class-functions" or cmdline option --new-class-functions" must be given for this change to be active. (The idea is to offer users with custom style sheets a smooth upgrade and change the default in some future version.)

[Günter Milde]

Realising that

• the problem also affects footnote text,
• using an environment makes it harder to print admonitions as margin notes (cf. http://docutils.sourceforge.net/docs/user/latex.html#admonitions),
• there is already an exception from using "alltt" (cells in an "auto" withds table),
  I decided against changing "DUadmontion" to an environment and to fix the problem with inclusion of admonitions and footnotes in the exception list.
  Fixed in [r8391] .