Re: [Docutils-users] Multi-line classifiers in definition lists

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

On 2019-12-11, Antony Lee wrote:

> Hi,
> Sorry re-raising an old thread, but I had a quick revisit at this again...
> As a reminder, this was about adding backslash-escaped line continuations,
> so that one could write

> term : info more info \

>        and more info

>     the definition


> the idea being that numpydoc docstrings (by far the most widely used
> docstring convention in the scientific python ecosystem) would benefit from
> it.

I like the idea but want it to be general: also long section headings,
say, may benefit from this.

> As it turns out the patch to achieve this is relatively simple:

> diff --git i/docutils/docutils/statemachine.py
> w/docutils/docutils/statemachine.py
> index ec5351887..70aa9baea 100644
> --- i/docutils/docutils/statemachine.py
> +++ w/docutils/docutils/statemachine.py
> @@ -311,6 +311,13 @@ class StateMachine(object):
>             except IndexError:
>                 self.line = None
>                 raise EOFError
> +            while self.line.endswith("\\"):
> +                try:
> +                    self.line_offset += 1
> +                    self.line +=
> self.input_lines[self.line_offset].lstrip()
> +                except IndexError:
> +                    self.line = None
> +                    raise EOFError
>             return self.line
>         finally:
>             self.notify_observers()


> i.e. joining the backslash-escaped lines relatively early in the process.

Unfortunately, this breaks our test suite and shows nasty side-effects in a
small dedicated test file.

> Please let me know the best way to proceed forward.

We would need to sort out the problems and side-effects,
test properly,
document,
and then implement it in the development version.

Thanks for the proposal and remainder,

Günter


Test backslash escaping of line ends
------------------------------------

There are side effects, the test suite fails.

Lets have a closer look:

Section headings
----------------

Breaking long section headings fails:

long and broken section heading\
!
-----------------------------------

long section heading with broken underline
-------------------------------\
-------------------


Paragraphs
----------

This is a paragraph. \
It's quite short.

The text of all lines should be there,
even if a line end is
escaped with a backslash \
somewhere in the middle.

The second line of this paragraph
contains an escaped line break \
and is missing in the output!!

Lists
-----

definition lists
````````````````

using a backslash \
escape
    you can break the definition line

escaping line ends: works in the \
                 additional explanations
    too.

definition term
   and definition with backslash \
   escape. Again a line missing!!

field lists
```````````

:the field \
 name:
   and the content

:a long and broken \
 field name: start of content missing if placed on same line!!
 
:field name: and broken \
   content

literal text
--------------

An example::

      Whitespace, newlines, blank lines, 
        and all kinds of markup \
      must be  preserved by literal blocks.

Also ``inline \
literals`` must keep the backslash and the escaped character!