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

Re: [Docutils-users] backslash replaced by null character

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

On 2021-05-04, Mariusz Wasiluk wrote:

> Thank you for the answer. Yes, I saw the release notes however I don't
> understand how this behavior is in line with what is stated in
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#escaping-mechanism
> "The backslash is removed from the output" suggests that there will be no
> character in the output, even NULL.

I agree that the documentation needs clarification.
Escape characters are removed from output documents by the Docutils
"writers". Your example uses a representation of the internal document
tree (doctree).

> Currently, my example produces invalid XML (I get parsing error from lxml).

This should not happen and is probably a bug in the asdom() method for
Text nodes.

> So I wonder if my use case is invalid? 

Currently, the XML produced by .asdom().toxml() is not tested.
While not invalid, you may consider it experimental/unsupported.
Contributions improving test coverage are welcome.

> Shall I remove \x00 from the XML output before further processing?

Depending on your needs, you could either restore or remove escaping not
"used up" by Docutils. Docutils provides the nodes.unescape() function
for this purpose (which allows either restoring or removal and also caters
for the special meaning of escaped whitespace).

When you don't want the escapes, you may also consider using the
"xml" writer instead of publish_doctree().

Fixing ...asdom() would also need to consider whether escapes
should be restored or removed.


Günter

> wt., 4 maj 2021 o 19:53 Guenter Milde via Docutils-users <
> doc...@li...> napisał(a):

>> On 2021-05-04, Mariusz Wasiluk wrote:

>> > Hello,

>> > I have following snippet:

>> > from docutils.core import publish_doctree
>> > dom = publish_doctree(r'Foo\\bar').asdom()
>> > print(repr(dom.toxml()))

>> > with docutils>=0.16, I get:
>> > u'<?xml version="1.0" ?><document
>> > source="&lt;string&gt;"><paragraph>Foo\x00\\bar</paragraph></document>'

>> > with previous versions I get:
>> > u'<?xml version="1.0" ?><document
>> > source="&lt;string&gt;"><paragraph>Foo\\bar</paragraph></document>'

>> > Why with the newest docutils versions I'm getting \x00 in the output?

>> This is an intended change:

>> Until 0.16, backslashs were removed prior to storing a Text string in the
>> document tree. Since 0.16 they are stored as NULL.

>> See the HISTORY.txt entry for 0.16:

>>   - Keep `backslash escapes`__ in the document tree. Backslash characters
>> in
>>     text are be represented by NULL characters in the ``text`` attribute of
>>     Doctree nodes and removed in the writing stage by the node's
>>     ``astext()`` method.

>>   __
>> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#escaping-mechanism

>> This change was implemented in order to allow escaping "active characters"
>> also in transforms. The RELEASE_NOTES list one example:

>>     [...] This allows, e.g., escaping of author-separators in
>>     `bibliographic fields`__.

>>   __
>> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#escaping-mechanism
>>   __ docs/ref/rst/restructuredtext.html#bibliographic-fields

>> Another usage is escaping of characters that would otherwise be
>> transformed by
>> the smartquotes__ transform.

>> __ https://docutils.sourceforge.io/docs/user/config.html#smart-quotes


>> 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.


> [-- Skipped Type: text/html --]
> [-- Type: text/plain, Encoding: 7bit --]


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

Re: [Docutils-users] backslash replaced by null character

[Mariusz W. <go...@gm...>]

Thank you for the answer. Yes, I saw the release notes however I don't
understand how this behavior is in line with what is stated in
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#escaping-mechanism
"The backslash is removed from the output" suggests that there will be no
character in the output, even NULL.
Currently, my example produces invalid XML (I get parsing error from lxml).
So I wonder if my use case is invalid? Shall I remove \x00 from the XML
output before further processing?

wt., 4 maj 2021 o 19:53 Guenter Milde via Docutils-users <
doc...@li...> napisał(a):

> On 2021-05-04, Mariusz Wasiluk wrote:
>
> > Hello,
>
> > I have following snippet:
>
> > from docutils.core import publish_doctree
> > dom = publish_doctree(r'Foo\\bar').asdom()
> > print(repr(dom.toxml()))
>
> > with docutils>=0.16, I get:
> > u'<?xml version="1.0" ?><document
> > source="&lt;string&gt;"><paragraph>Foo\x00\\bar</paragraph></document>'
>
> > with previous versions I get:
> > u'<?xml version="1.0" ?><document
> > source="&lt;string&gt;"><paragraph>Foo\\bar</paragraph></document>'
>
> > Why with the newest docutils versions I'm getting \x00 in the output?
>
> This is an intended change:
>
> Until 0.16, backslashs were removed prior to storing a Text string in the
> document tree. Since 0.16 they are stored as NULL.
>
> See the HISTORY.txt entry for 0.16:
>
>   - Keep `backslash escapes`__ in the document tree. Backslash characters
> in
>     text are be represented by NULL characters in the ``text`` attribute of
>     Doctree nodes and removed in the writing stage by the node's
>     ``astext()`` method.
>
>   __
> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#escaping-mechanism
>
> This change was implemented in order to allow escaping "active characters"
> also in transforms. The RELEASE_NOTES list one example:
>
>     [...] This allows, e.g., escaping of author-separators in
>     `bibliographic fields`__.
>
>   __
> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#escaping-mechanism
>   __ docs/ref/rst/restructuredtext.html#bibliographic-fields
>
> Another usage is escaping of characters that would otherwise be
> transformed by
> the smartquotes__ transform.
>
> __ https://docutils.sourceforge.io/docs/user/config.html#smart-quotes
>
>
> 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] backslash replaced by null character

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

On 2021-05-04, Mariusz Wasiluk wrote:

> Hello,

> I have following snippet:

> from docutils.core import publish_doctree
> dom = publish_doctree(r'Foo\\bar').asdom()
> print(repr(dom.toxml()))

> with docutils>=0.16, I get:
> u'<?xml version="1.0" ?><document
> source="&lt;string&gt;"><paragraph>Foo\x00\\bar</paragraph></document>'

> with previous versions I get:
> u'<?xml version="1.0" ?><document
> source="&lt;string&gt;"><paragraph>Foo\\bar</paragraph></document>'

> Why with the newest docutils versions I'm getting \x00 in the output?

This is an intended change:

Until 0.16, backslashs were removed prior to storing a Text string in the
document tree. Since 0.16 they are stored as NULL.

See the HISTORY.txt entry for 0.16:

  - Keep `backslash escapes`__ in the document tree. Backslash characters in
    text are be represented by NULL characters in the ``text`` attribute of
    Doctree nodes and removed in the writing stage by the node's
    ``astext()`` method.

  __ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#escaping-mechanism

This change was implemented in order to allow escaping "active characters"
also in transforms. The RELEASE_NOTES list one example:

    [...] This allows, e.g., escaping of author-separators in
    `bibliographic fields`__.

  __ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#escaping-mechanism
  __ docs/ref/rst/restructuredtext.html#bibliographic-fields

Another usage is escaping of characters that would otherwise be transformed by
the smartquotes__ transform.

__ https://docutils.sourceforge.io/docs/user/config.html#smart-quotes


Günter

[Docutils-users] backslash replaced by null character

[Mariusz W. <go...@gm...>]

Hello,

I have following snipped:

from docutils.core import publish_doctree
dom = publish_doctree(r'Foo\\bar').asdom()
print(repr(dom.toxml()))

with docutils>=0.16, I get:
u'<?xml version="1.0" ?><document
source="&lt;string&gt;"><paragraph>Foo\x00\\bar</paragraph></document>'

with previous versions I get:
u'<?xml version="1.0" ?><document
source="&lt;string&gt;"><paragraph>Foo\\bar</paragraph></document>'

Why with the newest docutils versions I'm getting \x00 in the output?

Re: [Docutils-users] bad table with with latex writer

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

On 2021-04-17, seb...@ch... wrote:
> Le 16/04/2021 à 18:19, Alan G. Isaac a écrit :
>> With rst2beamer, I'm getting table widths that are far too narrow.

This is a known problem:

  reST-documents line length is assumed to be 80 characters. The
  tablewidth is set relative to this value. If someone produces documents
  with line length of 132 this will lead to suboptimal results.

  -- https://docutils.sourceforge.io/docs/user/latex.html#tables
  
You may use the :width: or :widths: options of the `table directive`__ to
manually set the table column widths.

With the table-style_ option, you can also set document-wide defaults.

With ``--table-style: colwidths-auto``, LaTeX determines table column width
by their content.

Warning

  colwidths-auto is only suited for tables with simple cell content.

  LaTeX puts the content of auto-sized columns on one line (merging
  paragraphs) and may fail with complex content.
  
__ https://docutils.sourceforge.io/docs/ref/rst/directives.html#table
__ https://docutils.sourceforge.io/docs/user/config.html#table-style-latex-writers



>> It looks like this is coming from the latex writer (specifically,
>> get_colspecs).  It appears to produce only about half of
>> the \textwidth as the table width.

>> Unfortunately I am in the middle of a project and cannot explore
>> this further at the moment, but my workaround has been to set
>> the width on the table to far above 100%. Perhaps this report
>> while inadequate will be of some use.

May be there is more at stake here, especially as beamer may have different
default. You may consider to ask back once you have the time to generate
minimal examples ...

Günter

[Docutils-users] release 0.17.1 (mostly fixes)

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

release 0.17.1 is on pypi

fixes two things

* in python3.6 in an ascii environment reading the docutils.sty file
  fails, due to unicode characters in the file.
* provide defaults (fallbacks) for settings (tab_width) if docutils is
  used by third party frontends.

all the best
 e

Re: [Docutils-users] bad table with with latex writer

[<seb...@ch...>]

Le 16/04/2021 à 18:19, Alan G. Isaac a écrit :
> With rst2beamer, I'm getting table widths that are far too narrow.
> It looks like this is coming from the latex writer (specifically,
> get_colspecs).  It appears to produce only about half of
> the \textwidth as the table width.
>
> Unfortunately I am in the middle of a project and cannot explore
> this further at the moment, but my workaround has been to set
> the width on the table to far above 100%. Perhaps this report
> while inadequate will be of some use.
>

Hi Isaac,


The column width is evaluated with the number of letters in each column :

This means that the two following tables will be rendered with different
width :

>
> ====== =======
> |Col1| |Col2|
> ------ -------
> v1      v2
> ====== =======
>
> .. |Col1| replace:: First column with title
> .. |Col2| replace:: 2nd column with title
>
> ======================= =====================
> First column with title 2nd column with title
> ----------------------- ---------------------
> v1                      v2
> ======================= =====================

Sébastien

[Docutils-users] bad table with with latex writer

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

With rst2beamer, I'm getting table widths that are far too narrow.
It looks like this is coming from the latex writer (specifically,
get_colspecs).  It appears to produce only about half of
the \textwidth as the table width.

Unfortunately I am in the middle of a project and cannot explore
this further at the moment, but my workaround has been to set
the width on the table to far above 100%. Perhaps this report
while inadequate will be of some use.

Best, Alan Isaac

Re: [Docutils-users] Regarding https://sourceforge.net/p/docutils/bugs/414/

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

On 2021-04-07, Guenter Milde via Docutils-users wrote:
> On 2021-04-07, Mula, Wojciech (Nokia - PL/Wroclaw) wrote:

>> Hi, I don't have an SF account, so adding a comment here.

>> To reproduce the issue it's sufficient to set LANG=C (or unset LANG at
>> all). It works with Python 3.6 from Redhat 8. I think the correct
>> solution is to open the .sty file in __init__.py with explicitly set
>> encoding to UTF-8.

>> Günter asked why not using UTF-8? In our case we didn't even know that
>> our CI setup does have locale set.

> Thank you for the additional info.

...

Update: you may try with the newest repository version.

Günter

Re: [Docutils-users] Regarding https://sourceforge.net/p/docutils/bugs/414/

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

On 2021-04-07, Mula, Wojciech (Nokia - PL/Wroclaw) wrote:

> Hi, I don't have an SF account, so adding a comment here.

> To reproduce the issue it's sufficient to set LANG=C (or unset LANG at
> all). It works with Python 3.6 from Redhat 8. I think the correct
> solution is to open the .sty file in __init__.py with explicitly set
> encoding to UTF-8.

> Günter asked why not using UTF-8? In our case we didn't even know that
> our CI setup does have locale set.

Thank you for the additional info.

Next question: how come that building HTML with Sphinx wants to load a LaTeX
style file??

Can you provide a full log (to the list or as pm)?

Günter

[Docutils-users] Regarding https://sourceforge.net/p/docutils/bugs/414/

[Mula, W. (N. - PL/Wroclaw) <woj...@no...>]

Hi, I don't have an SF account, so adding a comment here.

To reproduce the issue it's sufficient to set LANG=C (or unset LANG at all). It works with Python 3.6 from Redhat 8. I think the correct solution is to open the .sty file in __init__.py with explicitly set encoding to UTF-8.

Günter asked why not using UTF-8? In our case we didn't even know that our CI setup does have locale set.

best regards
Wojciech

[Docutils-users] docutils 0.17 released

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

Release Notes

* Installing with ``setup.py`` now requires setuptools_.
  Alternatively, install with pip_.

* The generic command line front end tool docutils-cli.py_ allows
  the free selection of reader, parser, and writer components.

* New, experimental wrapper to integrate the
  `recommonmark`__ Markdown parser for use with Docutils.

  __ https://pypi.org/project/recommonmark/

* HTML5 writer:

  - Use the new semantic tags <main>, <section>, <header>,
    <footer>, <aside>, <figure>, and <figcaption>.
    See ``minimal.css`` and ``plain.css`` for styling rule examples.

    Change the `initial_header_level`_ setting's default to "2", as browsers
    use the `same style for <h1> and <h2> when nested in a section`__.

  - 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.

  - New optional style ``responsive.css``, adapts to different screen
    sizes.

  - New option embed_images_.

  .. _initial_header_level: docs/user/config.html#initial-header-level
  __
https://stackoverflow.com/questions/39547412/same-font-size-for-h1-and-h2-in-article
  .. _embed_images: docs/user/config.html#embed-images

* docutils/writers/html5_polyglot/

  - ``minimal.css``: Move non-essential styling to ``plain.css``.
    Code line numbers as pseudo-elements which are skipped when
    copying text.
  - ``plain.css``: Support numbered figures.

* LaTeX writer:

  - New configuration setting `legacy_class_functions`_.

  - The special value "auto" for the `graphicx_option`_ setting
    is no longer supported (it never worked for xetex/luatex).

  - `Styling commands`__ using the legacy ``\docutilsrole`` prefix are
    now ignored. Use ``\DUrole``.

    __ docs/user/latex.html#classes

  - Most helper commands and element definitions are now defined in the
    LaTeX package `docutils.sty`_ and only inserted in the document
    preamble if the stylesheet__ setting does not lists "docutils".

    __ docs/user/config.html#stylesheet-latex-writers

  - Remove legacy LaTeX stylesheet ``docutils-05-compat.sty``.

  - Fixes (thanks to) from John Thorvald Wodder II:
    alignment of nested tables, support memoir document class,

* pseudoxml-writer got a ``--detailled`` option for pretty printing text
nodes.

* odf/odt-writer improved metadata handling.

* manpage-writer fixes #380 commandline option in spinx, #126 title with
spaces,
  #168 empty citation, #394 newline after rubric.

* Miscellaneous:

  - Fixes in Arabic mappings and Korean translations.
  - directives: Prevent infinte inclusion loops.
  - roles: Apply patch #174 `Lowercase new role names on registration`
    by John Thorvald Wodder II.

cheers
 engelbert

[Docutils-users] docutils release 0.17 till april 2nd

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

if no one objects

cheers

Re: [Docutils-users] [Docutils-develop] docutils pre-release 0.17b1

[Komiya T. <i.t...@gm...>]

Hi,

I confirmed new docutils works fine with Sphinx except for the change
of "caption" node.
https://github.com/sphinx-doc/sphinx/pull/8870

Since 0.17, HTML5 writer generates a <figcaption> tag for the caption
node. But we've used it for non-figure items (ex. a caption of ToC
tree). I'd like to know this came from my misunderstanding for the
purpose of the node, or the purpose of the node is changed now. If our
usage was wrong, I'll fix it soon.

Unfortunately, there is no explanation on the doctree document.
https://docutils.sourceforge.io/docs/ref/doctree.html#caption

Thank you for maintaining great software!

Thanks,
Takeshi KOMIYA

2021年2月11日(木) 5:57 engelbert gruber <eng...@gm...>:

>
> is on pypi
>
> any feedback is welcome
>
> possible test path::
>
>   python3 -m venv dutest
>   cd dutest
>   . bin/activate
>   pip install --no-deps --pre docutils
>
> till b2
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>
> Please use "Reply All" to reply to the list.

[Docutils-users] docutils pre-release 0.17b1

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

is on pypi

any feedback is welcome

possible test path::

  python3 -m venv dutest
  cd dutest
  . bin/activate

  pip install --no-deps --pre docutils

till b2

Re: [Docutils-users] RTL languages in reStructredText (docutils)

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

On 2021-01-15, Abdullah Al-hadab wrote:

> Hi ,

> I have translated docutils to Arabic, and it is working fine, however,
> I am getting the direction wrong ( text is aligned to left)
> [cid:image003.jpg@01D6EB29.AA4121B0]

> I saw these two scripts on Docutils FAQ (Frequently Asked Questions)
> (sourceforge.io)<https://docutils.sourceforge.io/FAQ.html#can-i-produce-documents-in-right-to-left-languages>
> , which should solve this issue.

If it is only about alignment, maybe you just need a custom stylesheet.
Maybe we can design a "rtl.css" stylesheet for use with RTL languages?
(Unfortunately, I don't understand any language that uses an RTL script.)

Did you set --language=arabic (or farsi, hebrew,...)?

You can also set the language for individual elements with the "class"
argument or "class" directive. A class value of "language-mylang" is
written as `lang=mylang` in HTML.


> I followed the instruction but when I run rst2html_bidi I get the
> following error

> AttributeError: 'Element' object has no attribute 'dir'
> Exiting due to error.  Use "--traceback" to diagnose.
> Please report errors to <doc...@li...>.
> Include "--traceback" output, Docutils version (0.17b.dev [release]),
> Python version (3.7.9), your OS type & version, and the
> command line used.

Looking at docutils/docs/ref/doctree.html, I realize that "dir" is not
standard attribute in Docutils. It seems to be an addition by the
"hibidy"-enhanced custom writer.

> Traceback (most recent call last):
>   File "./rst2html_hibidi.py", line 38, in <module>
>     publish_cmdline(writer=HiBiDiWriter(), description=description)
>   File "/home/geohadab/github/docutils/docutils/docutils/core.py", line 355, in publish_cmdline
>     config_section=config_section, enable_exit_status=enable_exit_status)
>   File "/home/geohadab/github/docutils/docutils/docutils/core.py", line 220, in publish
>     output = self.writer.write(self.document, self.destination)
>   File "/home/geohadab/github/docutils/docutils/docutils/writers/__init__.py", line 79, in write
>     self.translate()
>   File "./rst2html_hibidi.py", line 30, in translate
>     self.output = hibidi.hibidi_unicode(self.output, encoding=self.destination.encoding)
>   File "/home/geohadab/github/hibidi.py", line 34, in hibidi_unicode
>     return hibidi_str(u.encode(encoding), root).decode(encoding)
>   File "/home/geohadab/github/hibidi.py", line 39, in hibidi_str
>     hibidi_dom(doc, root)
>   File "/home/geohadab/github/hibidi.py", line 50, in hibidi_dom
>     assign_dirs(node)
>   File "/home/geohadab/github/hibidi.py", line 101, in assign_dirs
>     assign_dirs(child, node.dir)
>   File "/home/geohadab/github/hibidi.py", line 101, in assign_dirs
>     assign_dirs(child, node.dir)
>   File "/home/geohadab/github/hibidi.py", line 97, in assign_dirs
>     if not node.dir:
> AttributeError: 'Element' object has no attribute 'dir'

This shows that the problem is in the 3rt-party module "hibidy.py".
Maybe making line 97 failproof changing it to something like

     if not getattr(node, "dir"):

helps. (But I don't know which default to use and whether
there are other follow-up errors.)

Günter

[Docutils-users] RTL languages in reStructredText (docutils)

[Abdullah Al-h. <al...@ho...>]

Hi ,

I have translated docutils to Arabic, and it is working fine, however, I am getting the direction wrong ( text is aligned to left)
[cid:image003.jpg@01D6EB29.AA4121B0]

I saw these two scripts on Docutils FAQ (Frequently Asked Questions) (sourceforge.io)<https://docutils.sourceforge.io/FAQ.html#can-i-produce-documents-in-right-to-left-languages> , which should solve this issue.

I followed the instruction but when I run rst2html_bidi  I get the following error

AttributeError: 'Element' object has no attribute 'dir'
Exiting due to error.  Use "--traceback" to diagnose.
Please report errors to <doc...@li...>.
Include "--traceback" output, Docutils version (0.17b.dev [release]),
Python version (3.7.9), your OS type & version, and the
command line used.


Traceback (most recent call last):
  File "./rst2html_hibidi.py", line 38, in <module>
    publish_cmdline(writer=HiBiDiWriter(), description=description)
  File "/home/geohadab/github/docutils/docutils/docutils/core.py", line 355, in publish_cmdline
    config_section=config_section, enable_exit_status=enable_exit_status)
  File "/home/geohadab/github/docutils/docutils/docutils/core.py", line 220, in publish
    output = self.writer.write(self.document, self.destination)
  File "/home/geohadab/github/docutils/docutils/docutils/writers/__init__.py", line 79, in write
    self.translate()
  File "./rst2html_hibidi.py", line 30, in translate
    self.output = hibidi.hibidi_unicode(self.output, encoding=self.destination.encoding)
  File "/home/geohadab/github/hibidi.py", line 34, in hibidi_unicode
    return hibidi_str(u.encode(encoding), root).decode(encoding)
  File "/home/geohadab/github/hibidi.py", line 39, in hibidi_str
    hibidi_dom(doc, root)
  File "/home/geohadab/github/hibidi.py", line 50, in hibidi_dom
    assign_dirs(node)
  File "/home/geohadab/github/hibidi.py", line 101, in assign_dirs
    assign_dirs(child, node.dir)
  File "/home/geohadab/github/hibidi.py", line 101, in assign_dirs
    assign_dirs(child, node.dir)
  File "/home/geohadab/github/hibidi.py", line 97, in assign_dirs
    if not node.dir:
AttributeError: 'Element' object has no attribute 'dir'


Could you please help


Thank you

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

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

On 2021-01-15, Clément Pit-Claudel wrote:
> On 1/15/21 6:18 AM, Guenter Milde via Docutils-users wrote:
>>> At the moment, users of the directive just call
>>> docutils.directives.register_directive('foo', FooDirective). 

>> Where is this done? A custom front-end?

> Exactly.

>>> 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.

>> I have never done this, but I'd try to get inspiration from the function
>> that processes the list returned by component.get_transform(). This is
>> transforms.Transformer.populate_from_components() where you will find::

>> So, maybe calling ::

>>   document.transformer.add_transform(FooTransform)

> This looks good, but how would I get a handle on the `document` object?

Here, you may have to re-create the working of the `publish_*()` function.
It may turn out that a custom component may be easier...
... or a post-processing step that removes not-required cache files.

Günter

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

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

On 1/15/21 6:18 AM, Guenter Milde via Docutils-users wrote:
>> At the moment, users of the directive just call
>> docutils.directives.register_directive('foo', FooDirective). 
> 
> Where is this done? A custom front-end?

Exactly.

>> 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.
> 
> I have never done this, but I'd try to get inspiration from the function
> that processes the list returned by component.get_transform(). This is
> transforms.Transformer.populate_from_components() where you will find::
> 
> So, maybe calling ::
> 
>   document.transformer.add_transform(FooTransform)

This looks good, but how would I get a handle on the `document` object?

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

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

On 2021-01-14, Clément Pit-Claudel wrote:
> 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). 

Where is this done? A custom front-end?

> 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.

I have never done this, but I'd try to get inspiration from the function
that processes the list returned by component.get_transform(). This is
transforms.Transformer.populate_from_components() where you will find::

        for component in components:
            if component is None:
                continue
            self.add_transforms(component.get_transforms())
            self.components[component.component_type] = component
 
So, maybe calling ::

  document.transformer.add_transform(FooTransform)
  
will do the trick (this is not tested and most probably needs adaption).



> In Sphinx I'd use app.add_transform; is there a Docutils equivalent?

> Or is there a better way to do this?

You may also consider subclassing a suitable component that adds the
transform. This can be done in the same module/script that also registers
the directive.

Günter

[Docutils-users] RTL languages in reStructredText (docutils)

[Abdullah Al-h. <al...@ho...>]

Hi ,

I have translated docutils to Arabic, and it is working fine, however, I am getting the direction wrong ( text is aligned to left)
[cid:image003.jpg@01D6EB29.AA4121B0]

I saw these two scripts on Docutils FAQ (Frequently Asked Questions) (sourceforge.io)<https://docutils.sourceforge.io/FAQ.html#can-i-produce-documents-in-right-to-left-languages> , which should solve this issue.

I followed the instruction but when I run rst2html_bidi  I get the following error

AttributeError: 'Element' object has no attribute 'dir'
Exiting due to error.  Use "--traceback" to diagnose.
Please report errors to <doc...@li...>.
Include "--traceback" output, Docutils version (0.17b.dev [release]),
Python version (3.7.9), your OS type & version, and the
command line used.


Traceback (most recent call last):
  File "./rst2html_hibidi.py", line 38, in <module>
    publish_cmdline(writer=HiBiDiWriter(), description=description)
  File "/home/geohadab/github/docutils/docutils/docutils/core.py", line 355, in publish_cmdline
    config_section=config_section, enable_exit_status=enable_exit_status)
  File "/home/geohadab/github/docutils/docutils/docutils/core.py", line 220, in publish
    output = self.writer.write(self.document, self.destination)
  File "/home/geohadab/github/docutils/docutils/docutils/writers/__init__.py", line 79, in write
    self.translate()
  File "./rst2html_hibidi.py", line 30, in translate
    self.output = hibidi.hibidi_unicode(self.output, encoding=self.destination.encoding)
  File "/home/geohadab/github/hibidi.py", line 34, in hibidi_unicode
    return hibidi_str(u.encode(encoding), root).decode(encoding)
  File "/home/geohadab/github/hibidi.py", line 39, in hibidi_str
    hibidi_dom(doc, root)
  File "/home/geohadab/github/hibidi.py", line 50, in hibidi_dom
    assign_dirs(node)
  File "/home/geohadab/github/hibidi.py", line 101, in assign_dirs
    assign_dirs(child, node.dir)
  File "/home/geohadab/github/hibidi.py", line 101, in assign_dirs
    assign_dirs(child, node.dir)
  File "/home/geohadab/github/hibidi.py", line 97, in assign_dirs
    if not node.dir:
AttributeError: 'Element' object has no attribute 'dir'


Could you please help


Thank you

[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] Is there a plan to integrate fenced code blocks in rst?

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

On 2020-12-07, Gökçe Aydos wrote:

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

> On 07/12/2020 18:07, Alan G. Isaac wrote:
>> The include directive allows literal inclusion of fragments:

> Very good idea if I have a single file where I get my code blocks.

> I have many code snippets which are build on top of each other, or are 
> independent.

> I could put all the code fragments in a single file and address them 
> using the include directive. Then I would have to find a way to 
> synchronize the two views. I find this still inconvenient compared to a 
> single file solution.

> Does someone have a better solution?

* PyLit__, the bidirectional text/code converter.

* An editor with support for rectangular regions and/or (un)indenting.

* Markdown (with Docutils version 0.17b.dev).

Günter

__ https://pypi.org/project/pylit/

Re: [Docutils-users] Is there a plan to integrate fenced code blocks in rst?

[Gökçe A. <goe...@th...>]

On 07/12/2020 18:07, Alan G. Isaac wrote:
> The include directive allows literal inclusion of fragments:

Very good idea if I have a single file where I get my code blocks.

I have many code snippets which are build on top of each other, or are 
independent.

I could put all the code fragments in a single file and address them 
using the include directive. Then I would have to find a way to 
synchronize the two views. I find this still inconvenient compared to a 
single file solution.

Does someone have a better solution?

Re: [Docutils-users] Is there a plan to integrate fenced code blocks in rst?

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

The include directive allows literal inclusion of fragments:
https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment

hth, Alan Isaac


On 12/6/2020 3:01 PM, Gökçe Aydos wrote:
> Thanks, that is a good idea for longer code Alan!
> 
> My case is different. For example in one document I have about 50 code blocks, which are about 2 to 8 lines long. Creating 50 files for this purpose would be 
> very inconvenient.


 > On 06/12/2020 20:34, Alan G. Isaac wrote:
 >> Why copy/paste at all when you can just ``include`` code?
 >