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

[Docutils-users] Open Access book (scientific visualization) using rst

[Nicolas P. R. (inria) <nic...@in...>]

Hi all,

I've just released an open access PDF book (on scientifif 
visualization) using restructured text that I converted to latex 
with a slightly modified rst2latex.py script and for some pages I 
had no choice but to use raw-latex directives. I think the result 
is nice.

Book: 
https://www.labri.fr/perso/nrougier/scientific-visualization.html
Sources: https://github.com/rougier/scientific-visualization-book

Feel free to copy the book style if you like it.
Cheers,
Nicolas

[Docutils-users] docutils version 0.18.1 released

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

Contents

* nodes.Node.traverse() returns a list again to restore
  backwards compatibility (fixes bug #431).
and Small bugfixes (see HISTORY_).

Re: [Docutils-users] (no subject)

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

On 2021-11-23, Lilian Castro wrote:

> Octocat

Your friendly kraken...

[Docutils-users] (no subject)

[Lilian C. <lib...@gm...>]

Octocat

Re: [Docutils-users] rst2html - option to embed images in output?

[Andreas C. <And...@st...>]

Never mind - I see its been available since 0.17 and now in 0.18 with `image_link`

From: Andreas Christoffersen
Sent: 4. november 2021 09:25
To: 'Doc...@li...' <Doc...@li...>
Subject: rst2html - option to embed images in output?

Rmarkdown embeds images in html files. It would be great if a similar option was available with docutils and rst2html.
I often write documentation which I need to send via email and such. The html format is optimal - but embedding of images is necessary.

This is my first time posting. Not yet subscribed to the mailinglist.

Sincerely

[Docutils-users] rst2html - option to embed images in output?

[Andreas C. <And...@st...>]

Rmarkdown embeds images in html files. It would be great if a similar option was available with docutils and rst2html.
I often write documentation which I need to send via email and such. The html format is optimal - but embedding of images is necessary.

This is my first time posting. Not yet subscribed to the mailinglist.

Sincerely

Re: [Docutils-users] --no-footnote-backlinks but still backlinks ...

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

On 2021-10-22, Alan G. Isaac wrote:
> I am using rst2html5 with --no-footnote-backlinks.
> This is supposed to turn off backlinks from citations too.
> (Hmm; shd't these be separate? Anyway ...)
> It does if the citation reference occurs only once.
> But if the citation reference occurs multiple times,
> then there is still a list of back references.
> There shouldn't be; right?

You are right. It is actually even worse, the once-referenced footnotes and
citations contained a spurious closing tag making the HTML invalid.

Fixed and tested locally, will be in 0.18.1.

Thank you for the report,

Günter

[Docutils-users] docutils releas 0.18

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

done.

Some Of The Changes
==================

* Identifiers:

During identifier normalization
<https://docutils.sourceforge.io/docs/ref/rst/directives.html#identifier-normalization>,
leading number and hyphen characters are no longer stripped from a reference
name
<https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#reference-names>,
if the id_prefix
<https://docutils.sourceforge.io/docs/user/config.html#id-prefix> setting
is non-empty.
* HTML5:

Use the semantic tag <aside> for footnote text and citations, topics
(except abstract and toc), admonitions, and system messages. Use <nav> for
the Table of Contents.

Make "auto" table column widths the default:
* Major refactoring and fixes/additions in docutils/utils/math/math2html.py
and docutils/utils/math/latex2mathml.py

For details consult https://docutils.sourceforge.io/RELEASE-NOTES.html

[Docutils-users] --no-footnote-backlinks but still backlinks ...

[Alan G. I. <ala...@gm...>]

I am using rst2html5 with --no-footnote-backlinks.
This is supposed to turn off backlinks from citations too.
(Hmm; shd't these be separate? Anyway ...)
It does if the citation reference occurs only once.
But if the citation reference occurs multiple times,
then there is still a list of back references.
There shouldn't be; right?

Thanks,
Alan Isaac

Re: [Docutils-users] Option list not implemented according to documentation

[Pierre O. <os...@ce...>]

On 12/10/2021 13:23, Guenter Milde wrote:
> 
> Your example resembles example 7 in
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#option-lists
> 
>      --an-even-longer-option
>             The description can also start on the next line.
> 
> which also states the reasoning behind this behaviour.
> 

Hmm... I completely missed that. :)

> What is missing, is a caveat in the specification of definition lists: the
> term may not start with a hyphen. This is now added in the repository.
> 

That's a nice addition. Especially including a reference to how to 
escape around the issue.

However I would also suggest some adjustments to the parts that tripped 
me up as I re-read the option list definition multiple times:

> Option lists are two-column lists...
                    ^^^^^^^^^^
> There must be at least two spaces between the option(s)...
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^

> +----------------------------+-------------+
> | option [" " argument] "  " | description |
> +-------+--------------------+             |
                           ^^^^

Perhaps a footnote or similar emphasizing that this has an exception? 
And should the permitted trailing single space be explicitly documented?

> 
> Thank you for reporting,
> 

No problem. Trying to spare the next person the head ache. :)

Regards
-- 
Pierre Ossman           Software Development
Cendio AB               https://cendio.com
Teknikringen 8          https://twitter.com/ThinLinc
583 30 Linköping        https://facebook.com/ThinLinc
Phone: +46-13-214600

A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?

Re: [Docutils-users] Option list not implemented according to documentation

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

Hej Pierre,

On 2021-10-11, Pierre Ossman wrote in gmane.text.docutils.user:
> Unfortunately there is a bug/deviation in the docutils implementation of 
> option lists compared to how they are described. This causes it to 
> misparse some definition lists as option lists instead.

> E.g. this:

> 	--something-that-looks-like-an-option
> 		But it really isn't! We just like dashes!

> Will result in an option list in the parsed doctree. But according to 
> the documentation an option list requires two or more spaces after the 
> option. 

Your example resembles example 7 in
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#option-lists

    --an-even-longer-option
           The description can also start on the next line.

which also states the reasoning behind this behaviour.

What is missing, is a caveat in the specification of definition lists: the
term may not start with a hyphen. This is now added in the repository.


Thank you for reporting,

Günter

[Docutils-users] Option list not implemented according to documentation

[Pierre O. <os...@ce...>]

Unfortunately there is a bug/deviation in the docutils implementation of 
option lists compared to how they are described. This causes it to 
misparse some definition lists as option lists instead.

E.g. this:

	--something-that-looks-like-an-option
		But it really isn't! We just like dashes!

Will result in an option list in the parsed doctree. But according to 
the documentation an option list requires two or more spaces after the 
option. So this should really be a definition list.

A casual glance at the code suggests that it is this regexp that is 
incorrect:

           'option_marker': r'%(option)s(, %(option)s)*(  +| ?$)' % pats,

I don't think that last '| ?$' should be there.

This code has been around for at least 19 years, and it even has a test 
that explicitly looks for this behaviour. So I'm not sure what to do 
here. Either the code or the documentation needs to change. Normally I'd 
advocate to fix the code, but I'm not so sure if there are people 
relying on this after it being around for so long.

(not subscribed, so cc on replies would be appreciated)

Regards
-- 
Pierre Ossman           Software Development
Cendio AB               https://cendio.com
Teknikringen 8          https://twitter.com/ThinLinc
583 30 Linköping        https://facebook.com/ThinLinc
Phone: +46-13-214600

A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?

[Docutils-users] docutils beta release 0.18b1 out

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

anyone who wants to try it out can install it from pypi

  pip install --pre docutils

or better in an virtualenvironment

  python3 -m venv du3
  cd du3
  pip install --pre docutils

final release tuesday in two weeks if nothing breaks

all the best

[Docutils-users] double quotes in definition list not rendered

[Guido C. <gu...@gu...>]

Hello, I have a problem with double quotes not being rendered in the
term of an rst definition list in the mpv documentation:

i show-text "Filename: ${filename}"
    shows the filename of the current file when pressing the ``i`` key

The double quotes are rendered in the html version, but not in the
manpage.

With i show-text """Filename: ${filename}"", they are rendered in the
manpage but the html version has all those quotes literally.

If the first " is preceded by a character other than space, the " are
rendered.

Is this a bug or am I missing something?

Re: [Docutils-users] --link-stylesheet path not relative to working directory

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

On 2021-07-07, Alan G. Isaac wrote:
> If I try to link to the stylesheet instead of embedding it
> (in rst2html5) I get a path that is not relative to the
> working directory. Instead it backs up to the root and
> works it's way down. (But that's terrible, since the
> target computer naturally has a different folder
> structure.)

> 1. Is this expected?

> 2. Possibly relevant (?): I invoke a particular Python
> by using it's full path.

Use, depending on your use case, stylesheet__ or stylesheet_path__.
__ https://docutils.sourceforge.io/docs/user/config.html#stylesheet
__ https://docutils.sourceforge.io/docs/user/config.html#stylesheet-path-1

Günter

Re: [Docutils-users] purpose of brackets class?

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

On 2021-07-06, Alan G. Isaac wrote:
> Low priority inquiry: in the HTML writer,
> why does an ``aside`` for a footnote have a ``brackets`` class?

To distinguish it from footnotes using superscript.
https://docutils.sourceforge.io/docs/user/config.html#footnote-references

See also the provided stylesheets how this is handled.

> Wdt it make more sense to add this to the span.label and the
> use CSS to provide the actual brackets?

No. It is actually a recent change to the HTML5 writer (r8734) that the
brackets are written into the source: This way they are present when
copying text from the browser (also with superscript labels, as the
superscript feature is lost).

Günter

Re: [Docutils-users] reference role?

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

On 2021-07-06, Alan G. Isaac wrote:
> Would it make sense to add ``reference`` to the standard roles?

This is a long-standing TODO issue. See
https://docutils.sourceforge.io/docs/dev/todo.html#object-numbering-and-object-references
.

> Related aside: the ``rst2latex`` writer needs to move the figure label
> to *after* the caption, otherwise ``--reference-label=ref``
> does not work correctly (i.e., does not produce the figure number).

This option (like -use-bibtex) is experimental, undocumented and
currently non-maintained.

Could you file an enhancement report?

Günter

[Docutils-users] --link-stylesheet path not relative to working directory

[Alan G. I. <ala...@gm...>]

If I try to link to the stylesheet instead of embedding it
(in rst2html5) I get a path that is not relative to the
working directory. Instead it backs up to the root and
works it's way down. (But that's terrible, since the
target computer naturally has a different folder
structure.)

1. Is this expected?

2. Possibly relevant (?): I invoke a particular Python
by using it's full path.

Thanks, Alan Isaac

[Docutils-users] purpose of brackets class?

[Alan G. I. <ala...@gm...>]

Low priority inquiry: in the HTML writer,
why does an ``aside`` for a footnote have a ``brackets`` class?
Wdt it make more sense to add this to the span.label and the
use CSS to provide the actual brackets?

Thanks,
Alan Isaac

[Docutils-users] reference role?

[Alan G. I. <ala...@gm...>]

Would it make sense to add ``reference`` to the standard roles?

Motivating example: I would like to produce a ``figure-ref`` role
to link to figures with a ``name`` class; I imagine
that this would subclass reference but would be styled differently.
For example, for an HTML writer, as ``target-counter()`` becomes available,
it would make use of the counter.

Related aside: the ``rst2latex`` writer needs to move the figure label
to *after* the caption, otherwise ``--reference-label=ref``
does not work correctly (i.e., does not produce the figure number).

Alan Isaac

Re: [Docutils-users] dfn role? (enhancement)

[Alan G. I. <ala...@gm...>]

The release notes at
https://docutils.sourceforge.io/HISTORY.html#release-0-17-2021-04-03
explain  the use of text level tags by making reference to
inline elements. This misled to me to think that this applied to
the list of inline elements at
https://docutils.sourceforge.io/docs/ref/doctree.html#inline-elements
Instead, follow the examples at
https://docutils.sourceforge.io/test/functional/input/data/html5-text-level-tags.txt

This post is for other users.
Thanks to Günter for helping me understand.

fyi, Alan Isaac

Re: [Docutils-users] dfn role? (enhancement)

[Alan G. I. <ala...@gm...>]

This sounds great.  Here is how I understand this:
if I update from Subversion and install the latest revision (8786)
that I should be able to use my custom `dfn(emphasis)` role and see a `dfn`
element if I use the rst2html5.py script (which, iiuc, uses the
rst2html5_polyglot writer).

However, I still see an `em` element with a `dfn` class.
Have I misunderstood? I'm looking at
https://docutils.sourceforge.io/HISTORY.html#release-0-17-2021-04-03

Thanks, Alan Isaac



On 7/3/2021 5:30 AM, Guenter Milde via Docutils-users wrote:
> This goal is already easy to achieve since version:
> 
>    - Use HTML text-level tags <small>, <s>, <q>, <dfn>, <var>, <samp>, <kbd>,
>      <i>, <b>, <u>, <mark>, and <bdi> if a matching class value
>      is found in `inline` and `literal` elements.
>      Use <ins> and <del> if a matching class value
>      is found in `inline`, `literal`, or `container` elements.
>      Use <small> for generated code line numbers.
> 
>    -- HISTORY.txt

Re: [Docutils-users] dfn role? (enhancement)

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

On 2021-07-02, Alan G. Isaac wrote:
> Might docutils consider adding the `dfn` role? (It is already in Sphinx.)
> For an HTML writer, this would become a `dfn` element.

> Goal: add this semantic content to HTML output.

This goal is already easy to achieve since version:

  - Use HTML text-level tags <small>, <s>, <q>, <dfn>, <var>, <samp>, <kbd>,
    <i>, <b>, <u>, <mark>, and <bdi> if a matching class value
    is found in `inline` and `literal` elements.
    Use <ins> and <del> if a matching class value
    is found in `inline`, `literal`, or `container` elements.
    Use <small> for generated code line numbers.

  -- HISTORY.txt

For an example see the output of

  docutils/test/functional/input/data/html5-text-level-tags.txt
  
in test/functional/expected/standalone_rst2html5.html


I don't think it makes much sense to provide these output-format specific
roles as default roles. I did consider an rST include-file in
"docutils/parsers/rst/include/":

  Standard data files intended for inclusion in reStructuredText
  documents are distributed with the Docutils source code, located in
  the "docutils" package in the ``docutils/parsers/rst/include``
  directory.  To access these files, use the special syntax for standard
  "include" data files, angle brackets around the file name::
  
      .. include:: <isonum.txt>

  -- directives.txt


Günter

[Docutils-users] dfn role? (enhancement)

[Alan G. I. <ala...@gm...>]

Might docutils consider adding the `dfn` role? (It is already in Sphinx.)
For an HTML writer, this would become a `dfn` element.

Goal: add this semantic content to HTML output.

Thanks for considering,
Alan Isaac

Re: [Docutils-users] closing a header block

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

Dear Sidney,

On 2021-05-27, Sidney Cadot wrote:

>> This is not only impossible (with standard rST syntax), it is also an
>> invalid Doctils document tree.
>> https://docutils.sourceforge.io/docs/ref/docutils.dtd
>> https://docutils.sourceforge.io/docs/ref/doctree.html#element-hierarchy

> Ok, that settles it. The restriction seems strange and somewhat arbitrary
> to my programmer's eye, but it is there alright.

With more input and searching in the Docutils sources, I have to correct
myself on both accounts. Details below.

> > >> Second, if not: is there a fundamental reason why the second
> > >> parse-tree would be incompatible with the document model of RsT?
> > >> (If that's the case, why?)

While your second example would be an invalid Docutils document, there
is no need to have a valid document tree before the parsing and
transformations are completed.

In other words, a transient document tree state like

    <document source="/tmp/simple.rst">
        <section ids="first-section" names="first\ section">
            <title>First section</title>
            <paragraph>First lorem ipsum</paragraph>
        </section>
     ← place next element here!

is not invalid per se. it depends on what would be the next element:

* if the next element is <section level="1"> or <section level="2">, fine.
  
* if the next element is *not* a <section> or a <section> with incompatible
  level (outside 1, ..., level_of_the_closed_section + 1), the final
  document tree is invalid.

> > >> Third, if it is possible in principle, but not yet in practice, is
> > >> there a way to implement this without touching the parser; say, by
> > >> adding a docutils Directive?

This should be possible -- directives can do "anything" that is possible in
Python:

As a new section can close the preceding section, there must be a way to
do this programatically. The solution is described in the docstring for
docutils.parser.rst.states.check_subsection():
   
     Check for a valid subsection header.  Return 1 (true) or None (false).

     When a new section is reached that isn't a subsection of the current
     section, back up the line count (use ``previous_line(-x)``), then
     ``raise EOFError``.  The current StateMachine will finish, then the
     calling StateMachine can re-examine the title.  This will work its way
     back up the calling chain until the correct section level isreached.

     @@@ Alternative: Evaluate the title, store the title info & level, and
     back up the chain until that level is reached.  Store in memo? Or
     return in results?

     :Exception: `EOFError` when a sibling or supersection encountered.

It should be possible to "close" a section by a directive raising
`EOFError` and the following rST examples would generate valid documents::


   A section
   ---------
   
   .. close-section::
   
   Another section
   ---------------
   
as well as ::   

   A section
   ---------

   .. close-section::
   
   .. directive-that-generates-a-section-with-compatible-level::
   
OTOH, such a directive will certainly not become part of the Docutils,
because input like ::

   A section
   ---------
   
   Section content

   .. close-section::

   Anything other than the preceding examples.
   
would generate an invalid document.


Therfore, my suggestion would be to incorporate the closing into the 
"directive-that-generates-a-section-with-compatible-level", e.g. so that you
may write, e.g, ::

   A section
   ---------
   
   A subsection
   ~~~~~~~~~~~~

   Subsection content.
   
   .. directive-that-generates-a-section-with-compatible-level::
   
      :section-level: 1

   
Caveats:
  * This is not part of the API but an implementation detail that may
    change in future.
  * I did not test.
  * I don't know about side-effects.



> A similar request was filed to the issue tracker.
>> https://sourceforge.net/p/docutils/feature-requests/74
>> It turned out to be about an intermediate structure (adding sections by a
>> directive). In this case, the resulting doctree would be valid but telling
>> the section-adding-directive where to add these sections seems a better
>> solution than changing rST syntax or adding a section-closing directive in
>> Docutils.


> Yes, that seems very much related to what I was thinking about.

> As it turns out handling this stuff fully at the sphinx level has its own
> set of challenges. Especially the toctree stuff and how it interacts with
> the section headers seems quite badly designed I am sorry to say, to the
> point that the general recommendation seems to be: don't use them in the
> same document -- which is annoying (and hard to defend from a usability
> perspective). I had hoped that some alternative solution with help from the
> docutils level could be useful; but I guess this will need to be fully
> fixed at the sphinx level after all.

I am not familiar with the toctree and Sphinx extensions, so I cannot
recommend here besides the general adwise to balance the gain in usability
with added complexity.

I hope this helps a bit,

Günter