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

Re: [Docutils-users] Type hints for Docutils - docutils-stubs or types-docutils?

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

Dear Matt,

On 2021-12-21, Matt Documatt wrote:
> Hi, there are at least two projects trying to do the same - provide
> type hints for Docutils.

> In past, I used docutils-stub
> (https://github.com/tk0miya/docutils-stubs), but it doesn't cover a few
> past versions. It is the work of great Sphinx guy Takeshi Komya.

> Recently, I discovered types-docutils
> (https://pypi.org/project/types-docutils/) that look "official" as it
> is part of typeshed.

> Which one to use? Who maintains the second one?

Both are 3rd party projects. While Takeshi Komya is a regular
contributor to docutils-devel and the ticket system, types-docutils is
completely independent. It seems to be a "community project" with several
contributors visible in
https://github.com/python/typeshed/tree/master/stubs/docutils.
I am not aware of problem reports for either of them.


After dropping support for Python 2.7, Docutils may start annotating public
classes, functions, and methods.

Günter

[Docutils-users] Type hints for Docutils - docutils-stubs or types-docutils?

[Matt D. <ma...@do...>]

Hi,
there are at least two projects trying to do the same - provide type hints for Docutils.

In past, I used docutils-stub (https://github.com/tk0miya/docutils-stubs), but it doesn't cover a few past versions. It is the work of great Sphinx guy Takeshi Komya.

Recently, I discovered types-docutils (https://pypi.org/project/types-docutils/) that look "official" as it is part of typeshed.

Which one to use? Who maintains the second one?

--
Matt
https://techwriter.documatt.com

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

[Martin K. <m...@ef...>]

Thanks for sharing!
What have been the advantages of using rST over raw latex, and why did you
make that choice?
Thanks,
Martin

On Tue, Nov 23, 2021 at 8:45 PM Nicolas P. Rougier (inria) <
nic...@in...> wrote:

>
> It's a regular bibtex file but I use a \nocite{*} in the latex
> template so it's not totally automated.
>
> Nicolas
>
> "Alan G. Isaac" <ala...@gm...> writes:
>
> > Wow!
> > Thanks for sharing!
> >
> > Did you create the bibliography by hand?
> >
> > Alan Isaac
> >
> >
> > On 11/23/2021 1:26 PM, Nicolas P. Rougier (inria) wrote:
> >> 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 mailing list
> >> Doc...@li...
> >> https://lists.sourceforge.net/lists/listinfo/docutils-users
> >> Please use "Reply All" to reply to the list.
> >
> >
> > _______________________________________________
> > 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 mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>

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

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

I find Latex markup/syntax a bit too intrusive when writing. Using 
rst was a great way to stick to content without paying too much 
attention to layout.

Nicolas

Martin Koutecký <m...@ef...> writes:

> Thanks for sharing!
> What have been the advantages of using rST over raw latex, and 
> why did
> you make that choice?
> Thanks,
> Martin
>
> On Tue, Nov 23, 2021 at 8:45 PM Nicolas P. Rougier (inria)
> <nic...@in...> wrote:
>
>     It's a regular bibtex file but I use a \nocite{*} in the 
>     latex 
>     template so it's not totally automated.
>
>     Nicolas
>
>     "Alan G. Isaac" <ala...@gm...> writes:
>
>     > Wow!
>     > Thanks for sharing!
>     >
>     > Did you create the bibliography by hand?
>     >
>     > Alan Isaac
>     >
>     >
>     > On 11/23/2021 1:26 PM, Nicolas P. Rougier (inria) wrote:
>     >> 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 mailing list
>     >> Doc...@li...
>     >> https://lists.sourceforge.net/lists/listinfo/docutils-users
>     >> Please use "Reply All" to reply to the list.
>     >
>     >
>     > _______________________________________________
>     > 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 mailing list
>     Doc...@li...
>     https://lists.sourceforge.net/lists/listinfo/docutils-users
>
>     Please use "Reply All" to reply to the list.

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

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

It's a regular bibtex file but I use a \nocite{*} in the latex 
template so it's not totally automated.

Nicolas

"Alan G. Isaac" <ala...@gm...> writes:

> Wow!
> Thanks for sharing!
>
> Did you create the bibliography by hand?
>
> Alan Isaac
>
>
> On 11/23/2021 1:26 PM, Nicolas P. Rougier (inria) wrote:
>> 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 mailing list
>> Doc...@li...
>> https://lists.sourceforge.net/lists/listinfo/docutils-users
>> Please use "Reply All" to reply to the list.
>
>
> _______________________________________________
> 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] Open Access book (scientific visualization) using rst

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

Wow!
Thanks for sharing!

Did you create the bibliography by hand?

Alan Isaac


On 11/23/2021 1:26 PM, Nicolas P. Rougier (inria) wrote:
> 
> 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 mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
> 
> Please use "Reply All" to reply to the list.

[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