docutils-users — General discussions, questions, help requests.

[Docutils-users] set class on title

[Alan G. I. <ai...@am...>]

1. Using rst2html5, trying to set a class on the title instead sets it on `main`.
Similarly, trying to set it on a header instead sets it on a section.
Is this intentional?

2. Separately, does including a `main` element have a point? Is there some way
to write an reST document that would have content outside of `main`?

Thanks,
Alan Isaac

[Docutils-users] Approachability & documentation, regarding Sphinx use-cases

[Joachim J. <jo...@ja...>]

Hello,

I wanted to let you know that a discussion started in the sphinx tracker, around the developer experience problems surrounding sphinx and docutils, when trying to develop new sphinx extensions.

If that’s something you have an interest in following, I encourage you to take part into the discussion at https://github.com/sphinx-doc/sphinx/issues/8039

Thank you,
Best
Joachim Jablon

[Docutils-users] Registering a transform that always runs, without attaching it to a custom component

[Clément Pit-C. <cpi...@gm...>]

Hi there,

I have a custom directive FooDirective.  It creates a custom pending node to run FooTransform.  FooTransform gathers all pending foo nodes and applies a transformation.
The results are cached in a file, because the transformation runs costly computations.

At the moment, users of the directive just call docutils.directives.register_directive('foo', FooDirective).  There's one problem: I don't have any 'foo's in the document, the cache should be cleared.  But, with no 'foo's, no pending node is added and the transform isn't executed; hence, the cache isn't cleared.

How can I register a directive that always runs? I'm aware of the get_transform method on components, but I don't have a custom component; I'm just writing a directive.

In Sphinx I'd use app.add_transform; is there a Docutils equivalent?
Or is there a better way to do this?

Thanks!

Re: [Docutils-users] Content block expected for the "raw" directive; none found.

[Saša J. <go...@at...>]

Marc Rintsch writes:

> There needs to be an empty line between the directive and its content block.

Ahh...I was convinced that I tried that option and that it failled too,
but you're correct. :-)

Thanks!


Sincerely,
Gour

-- 
A person who is not disturbed by the incessant flow of
desires — that enter like rivers into the ocean, which is
ever being filled but is always still — can alone achieve
peace, and not the man who strives to satisfy such desires.

Re: [Docutils-users] Content block expected for the "raw" directive; none found.

[Marc R. <ma...@ri...>]

On 24.05.20 12:07, Saša Janiška wrote:
> while writing content for Nikola (static-site-generator) I've a need to
> display counter for downloaded links and first of all tried with 'raw'
> directive as in the 2nd definition, but I get: "Content block expected
> for the "raw" directive; none found."
> 
> Then I found some workaround to use it inline, like in the 1st
> definition and that works, but wonder what is wrong with the 2nd
> example?
> 
> - - - - - - - - - - -
> 
> .. role:: raw-html(raw)
>     :format: html
>              
> Lectures
> -----------
> 
> 1. lesson: `Lesson I <https://sub.tld/click.php?id=1>`_ (:raw-html:`<script>ccount_display('1');</script>`)
> 
>     
> 2. lesson `Lesson II <https://sub.tld/click.php?id=2>`_
> 
> .. raw:: html
>     <script>ccount_display('2');</script>
> 
> - - - - - - - - - - - -
> 
> Any hint?

There needs to be an empty line between the directive and its content block.

Ciao,
	Marc 'BlackJack' Rintsch
-- 
“»I'm not going to ride on a magic carpet!« he hissed.
  »I'm afraid of grounds!«
  »You mean heights,« said Conina. »And stop being silly.«
  »I know what I mean! It's the grounds that kill you!«”
                              -- Terry Pratchett, Sourcery

[Docutils-users] Content block expected for the "raw" directive; none found.

[Saša J. <go...@at...>]

Hello,

while writing content for Nikola (static-site-generator) I've a need to
display counter for downloaded links and first of all tried with 'raw'
directive as in the 2nd definition, but I get: "Content block expected
for the "raw" directive; none found."

Then I found some workaround to use it inline, like in the 1st
definition and that works, but wonder what is wrong with the 2nd
example?

- - - - - - - - - - -

.. role:: raw-html(raw)
   :format: html
            
Lectures
-----------

1. lesson: `Lesson I <https://sub.tld/click.php?id=1>`_ (:raw-html:`<script>ccount_display('1');</script>`)

   
2. lesson `Lesson II <https://sub.tld/click.php?id=2>`_

.. raw:: html
   <script>ccount_display('2');</script>

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

Any hint?


Sincerely,
Gour

-- 
For him who has conquered the mind, the mind is the best of
friends; but for one who has failed to do so, his mind will
remain the greatest enemy.

Re: [Docutils-users] Formatting a reStructredText document

[Matěj C. <mc...@ce...>]

On 2020-05-04, 10:57 GMT, Eric Chinaka wrote:
> How do you inset page numbers?

You don’t. docutils are platform independent and page numbers 
have any meaning only paged output (e.g., LaTeX), whereas they 
are completely meaningless elsewhere (HTML, ePub). Therefore, 
page numbers are matter of the particular output filters and 
they can be fiddled with in the particular section of your 
`docutils.conf`_.

Best,

Matěj

.. _`docutils.conf`:
    https://docutils.sourceforge.io/docs/user/config.html

[Docutils-users] Formatting a reStructredText document

[Eric C. <Eri...@ne...>]

I am trying to format a document in reStructredText.

How do you inset page numbers?

Regards.




Eric Chinaka

Scientist

Tel: 012 305 5428

Fax: +27 12 305 5166

Cell: +27 71 917 6270

Email: Eri...@ne...

Website: www.necsa.co.za<http://www.necsa.co.za>

[cid:image507b84.JPG@0c6da7e5.4b860146]<http://>

[Facebook]<https://web.facebook.com/necsasoc/>  [Twitter] <https://twitter.com/necsa_Ltd>       [LinkedIn] <https://www.linkedin.com/company/necsa/>



________________________________

This message contains confidential information and is intended only for the individual named. If you are not the named addressee you should not disseminate, distribute or copy this e-mail. Please notify the sender immediately by e-mail if you have received this e-mail by mistake and delete this e-mail from your system. E-mail transmission cannot be guaranteed to be secure or error-free as information could be intercepted, corrupted, lost, destroyed, arrive late or incomplete, or contain viruses. The sender therefore does not accept liability for any errors or omissions in the contents of this message, which arise as a result of e-mail transmission. If verification is required please request a hard-copy version from NECSA.



#####################################################################################
Scanned by MailMarshal - Trustwave's comprehensive email content security solution. 
Download a free evaluation of MailMarshal at www.trustwave.com
#####################################################################################

Re: [Docutils-users] Docutils XML namespace?

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

On 2020-03-31, engelbert gruber wrote:

> [-- Type: text/plain, Encoding:  --]

> dont know (yet hopefully)
> but what is wrong with  tools/rst2xml.py ?


> On Tue, 31 Mar 2020 at 17:04, Mikhail Edoshin <mi...@on...> wrote:

>> Hi Engelbert,

>> I know docutils has a DTD for its XML. Does it have an official XML
>> namespace?

AFAIK, there is no official Docutils namespace name.

>> Context: I'm working with a tool that parses reST files into XML for use
>> in XML workflow. With all-XML workflow it's convenient to use a
>> dedicated namespace for reST, especially if it's reST with custom
>> extensions that may provide their own namespace. (E.g. one of such
>> extensions is going to be a generic '.. object:: XML' that embeds
>> literal foreign XML into reST.) 

Embedding literal XML is possible with ``.. raw::``.
What would a new "object" directive add?

>> I handle the conversion to XML myself
>> and right now I use a private namespace for reST elements. As I'm about
>> to publish the tool I wonder if there's an official reST namespace I
>> should be using instead. The tool is in its infancy and I can always
>> change things later, so it's not urgent.

Günter

Re: [Docutils-users] Docutils XML namespace?

[engelbert g. <eng...@gm...>]

dont know (yet hopefully)
but what is wrong with  tools/rst2xml.py ?


On Tue, 31 Mar 2020 at 17:04, Mikhail Edoshin <mi...@on...> wrote:

> Hi Engelbert,
>
> I know docutils has a DTD for its XML. Does it have an official XML
> namespace?
>
> Context: I'm working with a tool that parses reST files into XML for use
> in XML workflow. With all-XML workflow it's convenient to use a
> dedicated namespace for reST, especially if it's reST with custom
> extensions that may provide their own namespace. (E.g. one of such
> extensions is going to be a generic '.. object:: XML' that embeds
> literal foreign XML into reST.) I handle the conversion to XML myself
> and right now I use a private namespace for reST elements. As I'm about
> to publish the tool I wonder if there's an official reST namespace I
> should be using instead. The tool is in its infancy and I can always
> change things later, so it's not urgent.
>
> Kind regards,
> Mikhail
>
>
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>

[Docutils-users] Docutils XML namespace?

[Mikhail E. <mi...@on...>]

Hi Engelbert,

I know docutils has a DTD for its XML. Does it have an official XML 
namespace?

Context: I'm working with a tool that parses reST files into XML for use 
in XML workflow. With all-XML workflow it's convenient to use a 
dedicated namespace for reST, especially if it's reST with custom 
extensions that may provide their own namespace. (E.g. one of such 
extensions is going to be a generic '.. object:: XML' that embeds 
literal foreign XML into reST.) I handle the conversion to XML myself 
and right now I use a private namespace for reST elements. As I'm about 
to publish the tool I wonder if there's an official reST namespace I 
should be using instead. The tool is in its infancy and I can always 
change things later, so it's not urgent.

Kind regards,
Mikhail

Re: [Docutils-users] HTML5 Translator footnote brackets missing

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

On 2020-02-24, Jan 'oglop' Gazda wrote:

> Hello,
> I've been playing around with a html5 translator for my pelican page and I
> noticed that html5 translator
> (docutils.writers.html5_polyglot.HTMLTranslator) is missing override
> of visit_footnote_reference which adds brackets around the numbers like
> this "Note [1]".
> This looks like a major change (maybe not intentional) but I could not find
> any reference in issues/bug or docs.

It is part of a major change, documented in
https://docutils.sourceforge.io/docs/user/html.html#html5-polyglot

  There is no hard-coded formatting information in the HTML document.
  Correct rendering of elements not directly supported by HTML depends on
  a CSS style sheet. 

> So I have a few questions:
> 1) What is the reason for dropping the brackets? (Bug or feature)

The "footnote-references" setting is translated to a class argument by
the "html5_polyglot" writer. The appearance of footnote reference markers
is defined using CSS. The default rules in "minimal.css" define::
  
      a.footnote-reference.brackets:before,
      dt.label > span.brackets:before { content: "["; }
      a.footnote-reference.brackets:after,
      dt.label > span.brackets:after { content: "]"; }


> 2) Would you recommend to use html5 translator or not yet?

This depends on your needs. The html5 writer is supported and ready to be
used but less "road tested". Also, it may still evolve so it may be
necessary to adapt custom style-sheets or define some configuration
setting for full backwards compatibility. For example, we may make use of
the more liberal rules of ID values in HTMTL5 to allow more sensible IDs
of sections with Greek or Russian headings or headings starting with
numbers (https://sourceforge.net/p/docutils/feature-requests/66/).

An overview of the various HTML export options is given in
https://docutils.sourceforge.io/docs/user/html.html
More details and background around the differences between the html4 and
html5 writers can be seen in the commented source
https://docutils.sourceforge.io/docutils/writers/html5_polyglot/__init__.py


> 3) Are there any plans or would devs consider a change or docs website
> style 

There are currently no plans for a major revamp. The documentation is
intentionally also a *showcase of Docutil's default output*.
This means that many aspects (fonts, font size, colours) are left at the
browser default settings and comfortable site navigation a la `Sphinx`__ is
not implemented.

OTOH, we are, of course, interested in a good user experience and open
for suggestions to improve.

> - it's really difficult to navigate
> and especially hard to read for people with dyslexia (me)?

Could you elaborate?

You may also consider generating local HTML documentation from the sources
shipped with the Docutils package. This allows using the HTML5 writer as
well as experimenting with the configuration settings or CSS styles.

Thanks,
Günter

__ https://www.sphinx-doc.org

Re: [Docutils-users] FileNotFoundError: [Errno 2] No such file or directory: '/usr/local/lib/python3.8/site-packages/html5css3/thirdparty/revealjs/css/theme/league.css'

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

Dear Patrick,

thank you for reporting a problem with rst2html5.

It seems that this is caused by an add-on not maintained as part of Docutils.

On 2020-02-23, Patrick Levell wrote:

> *COMMAND:* rst2html5 --jquery --reveal-js --pretty-print-code --traceback
> fortune.rst >deck1.html && o deck1.html

The settings "--jquery --reveal-js --pretty-print-code" are not supported by
the Docutils html5 writer.


> *Traceback* (most recent call last):
>   File "/usr/local/bin/rst2html5", line 11, in <module>
>     load_entry_point('rst2html5-tools==0.5.3', 'console_scripts',
> 'rst2html5')()
>   File "/usr/local/lib/python3.8/site-packages/html5css3/main.py", line 32,

The directory "html5css3" is not part of Docutils.
It seems to be from an alternative 3rd-party HTML5 writer.

Depending on your needs, you may try the Docutils html5 writer or report to
the author of the alternative implementation.


Günter

Re: [Docutils-users] Role for different human language?

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

Ahoj Matěj,

On 2020-02-23, Matěj Cepl wrote:
> On 2020-02-23, 16:23 GMT, Guenter Milde via Docutils-users wrote:
>> There is a method for defining the language of text parts: The 
>> HTML and LaTeX writers convert a "class" argument starting 
>> with ``language-`` in a language argument with the remainder,

> It really works for HTML5 and LaTeX, but unfortunately it 
> doesn’t for ODT.

This is a convention used in the HTML and LaTeX writers (the two I
regularely work with and on).

...

> I was trying a bug for this at 
> https://sourceforge.net/p/docutils/bugs, but I couldn’t find 
> anything. And I know, unsupported magical feature means it is 
> unsupported, but still it would be lovely to have the ODT 
> generator following the suite. Do you know whether there is such 
> bug?

I don't think it is a *bug*: The documentation says that class arguments
may be ignored by some writers.

I recommend filing an `enhancement request`__.

Thanks,
Günter

__ https://sourceforge.net/p/docutils/feature-requests/66/

[Docutils-users] HTML5 Translator footnote brackets missing

[Jan 'o. G. <1o...@gm...>]

Hello,
I've been playing around with a html5 translator for my pelican page and I
noticed that html5 translator
(docutils.writers.html5_polyglot.HTMLTranslator) is missing override
of visit_footnote_reference which adds brackets around the numbers like
this "Note [1]".
This looks like a major change (maybe not intentional) but I could not find
any reference in issues/bug or docs.

So I have a few questions:
1) What is the reason for dropping the brackets? (Bug or feature)
2) Would you recommend to use html5 translator or not yet?
3) Are there any plans or would devs consider a change or docs website
style - it's really difficult to navigate and especially hard to read for
people with dyslexia (me)?

Thank you
----
Jan

[Docutils-users] FileNotFoundError: [Errno 2] No such file or directory: '/usr/local/lib/python3.8/site-packages/html5css3/thirdparty/revealjs/css/theme/league.css'

[Patrick L. <pat...@gm...>]

*COMMAND:* rst2html5 --jquery --reveal-js --pretty-print-code --traceback
fortune.rst >deck1.html && o deck1.html

*Traceback* (most recent call last):
  File "/usr/local/bin/rst2html5", line 11, in <module>
    load_entry_point('rst2html5-tools==0.5.3', 'console_scripts',
'rst2html5')()
  File "/usr/local/lib/python3.8/site-packages/html5css3/main.py", line 32,
in main
    publish_cmdline(writer_name='html5', writer=html5css3.Writer(),
  File "/home/patrick/.local/lib/python3.8/site-packages/docutils/core.py",
line 353, in publish_cmdline
    output = pub.publish(
  File "/home/patrick/.local/lib/python3.8/site-packages/docutils/core.py",
line 220, in publish
    output = self.writer.write(self.document, self.destination)
  File
"/home/patrick/.local/lib/python3.8/site-packages/docutils/writers/__init__.py",
line 78, in write
    self.translate()
  File "/usr/local/lib/python3.8/site-packages/html5css3/__init__.py", line
257, in translate
    processor(tree, embed, params)
  File
"/usr/local/lib/python3.8/site-packages/html5css3/postprocessors.py", line
156, in revealjs
    head.append(css(theme_path, embed))
  File
"/usr/local/lib/python3.8/site-packages/html5css3/postprocessors.py", line
48, in css
    content = read_file(abspath(path))
  File
"/usr/local/lib/python3.8/site-packages/html5css3/postprocessors.py", line
21, in read_file
    return open(path).read()
FileNotFoundError: [Errno 2] No such file or directory:
'/usr/local/lib/python3.8/site-packages/html5css3/thirdparty/revealjs/css/theme/league.css'


*Docutils version (0.16 [release]),Python version (3.8.1)*
*Ubuntu Linux 18.04.3*

Re: [Docutils-users] Role for different human language?

[Matěj C. <mc...@ce...>]

On 2020-02-23, 16:23 GMT, Guenter Milde via Docutils-users wrote:
> There is a method for defining the language of text parts: The 
> HTML and LaTeX writers convert a "class" argument starting 
> with ``language-`` in a language argument with the remainder, 

Wow! Thank you. We have even undocumented functions in docutils! 
Kewl!

Thank you,

Matěj Cepl
-- 
https://matej.ceplovi.cz/blog/, Jabber: mc...@ce...
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
One reason that life is complex is that it has a real part and an
imaginary part.
    -- Andrew König

Re: [Docutils-users] Role for different human language?

[Matěj C. <mc...@ce...>]

On 2020-02-23, 16:23 GMT, Guenter Milde via Docutils-users wrote:
> There is a method for defining the language of text parts: The 
> HTML and LaTeX writers convert a "class" argument starting 
> with ``language-`` in a language argument with the remainder,

It really works for HTML5 and LaTeX, but unfortunately it 
doesn’t for ODT.

So, this rST:

    In the end both options happened. Uncle Harry in secret 
    asked the French :language-fr:`Bureau des Aurors` to sent 
    somebody to start the investigation,

gives me this lovely HTML:

    <p>In the end both options happened. Uncle Harry in secret 
    asked the French <span lang="fr">Bureau des Aurors</span> to 
    sent somebody to start the investigation,</p>

and this LaTeX (and the generator even managed to translate “ft” 
-> “french”):

    In the end both options happened. Uncle Harry in secret 
    asked the French \foreignlanguage{french}{Bureau des Aurors} 
    to sent somebody to start the investigation,

but ODT generator doesn’t catch this trick and creates a new 
empty style (which actually is not visible in the style tools in 
OOWriter):

    <text:p text:style-name="rststyle-textbody">In the end both 
    options happened. Uncle Harry in secret asked the French 
    <text:span text:style-name="rststyle-language-fr">Bureau des 
    Aurors</text:span>to sent somebody to start the 
    investigation,</text:p>

I was trying a bug for this at 
https://sourceforge.net/p/docutils/bugs, but I couldn’t find 
anything. And I know, unsupported magical feature means it is 
unsupported, but still it would be lovely to have the ODT 
generator following the suite. Do you know whether there is such 
bug?

Best,

Matěj
-- 
https://matej.ceplovi.cz/blog/, Jabber: mc...@ce...
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
Roses are red;
    Violets are blue.
I'm schizophrenic,
    And so am I.

Re: [Docutils-users] Role for different human language?

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

On 2020-02-22, Matěj Cepl wrote:
> I am looking for some markup which say that the phrase in the 
> text is of different human language. E.g., I have this paragraph 
> (written in otherwise English story):

>     In the end both options happened. Uncle Harry in secret 
>     asked the French Bureau des Aurors to sent somebody to start 
>     the investigation, and so I spent two afternoons in small 
>     café near my University with the French lady, who asked me 
>     very thoroughly about my story.

> Now, I would like to mark the term “Bureau des Aurors” so that 
> screen reader or other software know that it is not English and 
> behave accordingly. Is there a standard way how to do it? Yes, 
> I understand I can define my own custom role for it (translating 
> to ``<span lang="fr_FR">``), but isn’t there a standard role?

There is a method for defining the language of text parts: The HTML and
LaTeX writers convert a "class" argument starting with ``language-`` in a
language argument with the remainder, e.g.
::

  .. role:: language-de

  Let's count in German :language-de:`eins zwei drei`.

becomes in HTML::

  Let's count in German <span lang="de">eins zwei drei</span>.

and in LaTeX::

  Let’s count in German \foreignlanguage{ngerman}{eins zwei drei}.
  

For block-level elements, you can use the ``.. class::`` directive or
the :class: directive option.

See:
https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/test/functional/input/data/custom_roles.txt
https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/test/functional/expected/standalone_rst_html5.html#l1221
https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/test/functional/expected/standalone_rst_latex.tex#l1766

(Also, have a look for "Die Trichter" in these documents to see an example
to define a block's language.)

Hope this helps,

Günter

Re: [Docutils-users] Why smart quotes by default ?

[Matěj C. <mc...@ce...>]

On 2019-12-21, 04:09 GMT, Wes Hurd wrote:
> documentation cannot be expected to put all code
> snippets in code blocks.

This is the point where I disagree. That is exactly what is 
expected.

Matěj
-- 
https://matej.ceplovi.cz/blog/, Jabber: mc...@ce...
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
kakistocracy, n.: Government by the least qualified or most
unprincipled citizens.
  -- first used by Thomas Love Peacock in 1829

[Docutils-users] Role for different human language?

[Matěj C. <mc...@ce...>]

I am looking for some markup which say that the phrase in the 
text is of different human language. E.g., I have this paragraph 
(written in otherwise English story):

    In the end both options happened. Uncle Harry in secret 
    asked the French Bureau des Aurors to sent somebody to start 
    the investigation, and so I spent two afternoons in small 
    café near my University with the French lady, who asked me 
    very thoroughly about my story.

Now, I would like to mark the term “Bureau des Aurors” so that 
screen reader or other software know that it is not English and 
behave accordingly. Is there a standard way how to do it? Yes, 
I understand I can define my own custom role for it (translating 
to ``<span lang="fr_FR">``), but isn’t there a standard role?

Thank you for any ideas,

Matěj
-- 
https://matej.ceplovi.cz/blog/, Jabber: mc...@ce...
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
This is a test of the emergency signature system. Were this an
actual signature, you would see amusing mottos, disclaimers,
a zillion net addresses, or edifying philosophical statements.
this is only test.

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

[Antony L. <ann...@gm...>]

No, but thanks for pointing to it.
Antony

On Fri, Feb 7, 2020 at 5:45 PM Guenter Milde via Docutils-users <
doc...@li...> wrote:

> On 2020-02-06, Antony Lee wrote:
>
> > Thanks for providing a nice list of test cases; I'll work on them.
>
> This is good news.
>
> Are you aware of the `Docutils test suite`__?
> I did not include examples of every test failure there in my test document.
>
> __ https://docutils.sourceforge.io/docs/dev/testing.html
>
>
> Günter
>
>
>
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>

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

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

On 2020-02-06, Antony Lee wrote:

> Thanks for providing a nice list of test cases; I'll work on them.

This is good news.

Are you aware of the `Docutils test suite`__?
I did not include examples of every test failure there in my test document.

__ https://docutils.sourceforge.io/docs/dev/testing.html


Günter

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

[Antony L. <ant...@in...>]

Thanks for providing a nice list of test cases; I'll work on them.
Antony

On Fri, Feb 7, 2020 at 1:41 PM Guenter Milde via Docutils-users <
doc...@li...> wrote:

> 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!
>
>
>
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>

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!