[Docutils-develop] [ docutils-Bugs-3484857 ] "invalid option block" for roles that start new lines

[SourceForge.net <no...@so...>]

Bugs item #3484857, was opened at 2012-02-06 00:34
Message generated for change (Comment added) made by milde
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=422030&aid=3484857&group_id=38414

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: None
Group: None
Status: Open
Resolution: None
Priority: 5
Private: No
Submitted By: Michael Forbes (mforbes)
Assigned to: Nobody/Anonymous (nobody)
Summary: "invalid option block" for roles that start new lines

Initial Comment:
If a role even incidentally starts a new line, the "invalid option block" is triggered.

I am not completely sure if this is a bug in the code or in the definition of the rst format
but it is highly counter-intuitive and can be triggered "automatically" when code is wrapped.
Is there a simple consistent workaround?  I would have expected that, since I have started
the text in the block, that the "option searcher" would stop looking for an options block and
simply process the role.

Here is a complete MWE:
-----------------------
# This is okay since the second line starts with text
okay = """
.. note:: Hi.  Here is an
   equation :math:`a=b`
"""

# This fails because the second line starts with the :math: role
bad = """
.. note:: Hi.  Here is an equation
   :math:`a=b`
"""
import docutils.utils
import docutils.parsers.rst

p = docutils.parsers.rst.Parser()
d = docutils.utils.new_document(
    'bug',
    docutils.frontend.OptionParser(components=(p,)).get_default_values())

p.parse(okay, d)
p.parse(bad, d)
-----------------------

Running this yields:
-------------
bug:2: (ERROR/3) Error in "note" directive:
invalid option block.

.. note:: Hi.  Here is an equation
   :math:`a=b`
--------------

Michael.

P.S. I doubt this is relevant, but here is the system information:
Mac OS X 10.5.8
Python 2.7.2 -- EPD 7.2-1 (32-bit)
Docutils Version '0.8.1'


----------------------------------------------------------------------

>Comment By: Günter Milde (milde)
Date: 2012-02-06 07:23

Message:
> I would have expected that, since I have started the text in the block,
that the "option searcher" would stop looking for an options block and
simply process the role.

This would prevent options for short notes like:

  .. note:: A note with option
    :name: example 1

However, as a field list can be distinguished from a role by the whitespace
required aftter the
field-marker, the problem can be solved by looking for a field-marker
instead of looking for
lines starting with a colon.

Note:  you still need a blank line before the content if it is a field
list.

Note: in the rare case of a field-list marker lookalike on the start of a
line, you need a blank line, too::

  .. note:: This is a strange example
    :that: fails because of the colon-wrapped :that: at beginning of the
line.


----------------------------------------------------------------------

Comment By: Michael Forbes (mforbes)
Date: 2012-02-06 00:40

Message:
The workaround is to *always* include a blank line before the content. 
(This looks poor, but is safe):

-------
.. note::
    
    This example is fine even though the equation
    :math:`a=b` starts a new line.
------

Michael.

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=422030&aid=3484857&group_id=38414