Re: [Docutils-users] epigraph reacts to comments in rst2html5

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

On 2021-06-01, Alan G. Isaac wrote:
> Adding a comment within an epigraph directive produces
> an extra (empty) blockquote element in the output.  E.g.,

> .. epigraph::

>     An epigraph.

>     -- A.U. Thor

>     .. a comment

I am not surprised:

* The “epigraph” directive produces an “epigraph”-class block quote.

  -- docutils/docs/ref/rst/directives.html#epigraph

* Multiple block quotes may occur consecutively if terminated with
  attributions.

  -- docutils/docs/ref/rst/directives.html#epigraph

* The directive block consists of any text on the first line of the
  directive after the directive marker, and any subsequent indented text.
 
  -- docutils/docs/ref/rst/restructuredtext.html#directives

  The attribution only closes the block-quote, not the
  directive.
  
* The directive block consists of any text on the first line of the
  directive after the directive marker, and any subsequent indented text.
 
  -- docutils/docs/ref/rst/restructuredtext.html#directives

  The attribution only closes the block-quote, not the
  directive::
  
   .. epigraph::
  
       An epigraph.
  
       -- S. Ource
  
       Another epigraph

* Comments may replace text blocks in syntax constructs::

     This is a paragraph
     
        .. this is a comment in a block-quote

  See the pseudo-xml output of this example.

* The directive block consists of any text on the first line of the
  directive after the directive marker, and any subsequent indented text.
 
  -- docutils/docs/ref/rst/restructuredtext.html#directives

  The attribution only closes the block-quote, not the
  directive.
  
I agree that other outcomes may be equally feasible but I cannot see a clear
winner in any other handling of the given input example.

If you really want a block quote after the attribution without the
"epigraph" class, the two input alternatives give the same result
(except for the different place of the empty comment)::


.. epigraph::

  a block quote
  
  -- by someone
  
..

  the next block-quote: no epigraph

.. class:: epigraph

..
  
  a block quote
  
  -- by someone
  
  the next block-quote: no longer epigraph


Günter