Re: [Docutils-users] broken ..epigraph in XeTeX?

[Guenter M. <mi...@us...>]

On 2017-02-04, Matěj Cepl wrote:
> So, I have a document which should start like this:


>     Druhý život Petunie Dursleyové
>     ##############################

>     .. epigraph::

>         Co je nejvyšším cílem člověka?

>         Nejvyšším cílem člověka je oslavovat Boha a věčně se 
>         z Něj radovat.

>         -- Westminsterský katechismus, 1647

>     Na cizinecké policii
>     --------------------

>     Hustě sněžilo, obloha byla zatažená a cítila se mizerně. 
>     Její náladě ani nepřidalo to, že budova cizinecké policie 

> This works perfectly with rst2html (or rst2html5 for that 
> matter, which seems a way cooler ... thank you for that!), but 
> it completely breaks rst2xetex.

 I get this LaTeX code for the 
> epigraph:

>     \begin{quote}
>     \DUrole{epigraph}{
>     Co je nejvyšším cílem člověka?

>     Nejvyšším cílem člověka je oslavovat Boha a věčně se z Něj 
>     radovat.
>     \nopagebreak

>     \raggedleft —Westminsterský katechismus, 1647
>     }
>     \end{quote}

> And this error when run through xelatex:

>     Runaway argument?
>     { Co je nejvyšším cílem člověka? 
>     ! Paragraph ended before \DUrole was complete.
>     <to be read again> 
>                        \par 
>     l.71 

The reason for the error is a bug in the LaTeX writer:

\DUrole is a LaTeX macro to give some sort of support for styling via
class arguments in inline markup (Docutils roles).
See http://docutils.sourceforge.net/docs/user/latex.html#custom-interpreted-text-roles

It is defined with \providecommand* -- the starred version does not allow
paragraph breaks withing the argument to allow better error reporting.
This is good for inline markup.

Unfortunatly, this limitation was not accounted for when the "ersatz class
mechnism" was used for some block-level objects (e.g. "quote").


> How can I have a paragraph break inside of ..epigraph?

Unless you intend a special styling for epigraphs, using a standard quote
is the most simple workaround.

E.g. by removing the "directive dots"::

   .. epigraph (currently the LaTeX writer fails with epigraph)
    
        Co je nejvyšším cílem člověka?

        ...
	
Explanation:

The `epigraph` directive is just syntactic sugar for::

  .. class:: epigraph
  
  ..
  
      The epigraph text
    
i.e. the content is converted to a quote element with class argument
"epigraph" by Docutils during the parsing.


A fix will follow, but needs some more discussion and thougts about the
optimal approach.

Günter