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

Re: [Docutils-users] SVG images in ODT (was: Does the doctree reader work?)

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

On Mon Feb 2, 2026 at 11:15 AM CET, Guenter Milde via Docutils-users wrote:
> Did you try it?

Yes, see `tests/`.

> I was stopped by a missing dependency documentation (which "odg" package or
> module is used?).

https://pypi.org/project/odfpy/ … there is no other one, AFAIK.

> Docutils currently can be installed without any dependency except Python.

Yes, that’s a problem. I usually hate dependencies as well (see the long
list of dependencies for M2Crypto,
https://git.sr.ht/~mcepl/m2crypto/tree/master/item/setup.cfg ;)). We
could make it into an optional dependency, but I think that manipulating
OpenDocument files is such nasty business, that perhaps it is not out of
the question. Patches to remove the dependency would be more than
welcome, of course!

> We may consider "light" dependencies for core services (like
> "romannumerals" for rST parsing). However, adding a large dependency for
> a rarely used feature like ODT export is not planned.
> (We may provide SVG - ODT "on the fly" as an "optional" feature similar to
> syntax highlighting with Pygments.)

Yes, the RPM package is 1.4 MiB installed. I am not sure what’s The
Right Thing™ here. Yeah, I think that some kind of `pip install
docutils[odt]` could be helpful, but I am not much happier about it
either.

Best,

Matěj

-- 
http://matej.ceplovi.cz/blog/, @mc...@en...
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
“Promise me you’ll look after yourself. … Stay out of trouble. …”
“I always do, Mrs. Weasley,” said Harry. “I like a quiet life,
you know me.”
  -- Harry Potter and the Half-Blood Prince, chapter 17

Re: [Docutils-users] SVG images in ODT (was: Does the doctree reader work?)

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

On 2026-02-01, Matěj Cepl wrote:
> On Wed Jan 28, 2026 at 11:24 AM CET, Guenter Milde via Docutils-users wrote:
>> We might go the easy way and start with implementing support for ODG images.
>> Then, authors may use the tool of their choice to convert PDF, SVG or other
>> vector formats to ODG (or export their own creations in ODG format) and
>> use this in rST or Markdown documents intended for docutils --writer=odg.

> OK, that's probably one avenue of the attack.

It should be the first step, there is no gain in a svg2odg tool when the
generated file cannot be inserted.

> While sitting here at FOSDEM and listening to presentation I have vibe
> coded https://git.sr.ht/~mcepl/svg2odg What do you think?

Did you try it?

I was stopped by a missing dependency documentation (which "odg" package or
module is used?).

Docutils currently can be installed without any dependency except Python.
We may consider "light" dependencies for core services (like
"romannumerals" for rST parsing). However, adding a large dependency for
a rarely used feature like ODT export is not planned.
(We may provide SVG - ODT "on the fly" as an "optional" feature similar to
syntax highlighting with Pygments.)

Günter

Re: [Docutils-users] SVG images in ODT (was: Does the doctree reader work?)

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

On Wed Jan 28, 2026 at 11:24 AM CET, Guenter Milde via Docutils-users wrote:
> We might go the easy way and start with implementing support for ODG images.
> Then, authors may use the tool of their choice to convert PDF, SVG or other
> vector formats to ODG (or export their own creations in ODG format) and
> use this in rST or Markdown documents intended for docutils --writer=odg.

OK, that's probably one avenue of the attack.

While sitting here at FOSDEM and listening to presentation I have vibe
coded https://git.sr.ht/~mcepl/svg2odg What do you think?

> A simplified variant of Sphinx's "only" directive may be helpfull in case
> a document source should be converted to several formats:
>
> ~~~ (future rST)
>
> .. only:: html xml
>  
>    .. image:: cute-cat.svg

XeTeX can manipulate SVG format as well.

> .. only:: latex xetex
>
>    .. image:: cute-cat.pdf
>    
> .. only:: odt
>    
>    .. image:: cute-cat.odg

That's probably a good idea.

Best,

Matěj
-- 
http://matej.ceplovi.cz/blog/, @mc...@en...
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

Re: [Docutils-users] SVG images in ODT (was: Does the doctree reader work?)

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

On 2026-01-27, Matěj Cepl wrote:
> On Tue Jan 27, 2026 at 2:11 PM CET, Guenter Milde via Docutils-users wrote:

> Gemini wrote to me this
> https://paste.sr.ht/~mcepl/6dc49185a90e19ba623fd940f3e48d1b20f5ee0d, but
> I am afraid it hallucinated most of the code, I cannot find that module
> `svg2odg` anywhere. I guess, we would have to try to vibe-code that
> converter anew (hopefully, conversion between two XML-based formats
> should be something LLM should be able to do).

> What do you think?

We might go the easy way and start with implementing support for ODG images.
Then, authors may use the tool of their choice to convert PDF, SVG or other
vector formats to ODG (or export their own creations in ODG format) and
use this in rST or Markdown documents intended for docutils --writer=odg.

A simplified variant of Sphinx's "only" directive may be helpfull in case
a document source should be converted to several formats:

~~~ (future rST)

.. only:: html xml
 
   .. image:: cute-cat.svg
   
.. only:: latex xetex

   .. image:: cute-cat.pdf
   
.. only:: odt
   
   .. image:: cute-cat.odg
   
~~~   

but this is an independent feature proposal...


https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-only


Günter



Günter

Re: [Docutils-users] SVG images in ODT (was: Does the doctree reader work?)

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

On Tue Jan 27, 2026 at 2:11 PM CET, Guenter Milde via Docutils-users wrote:
>>     ```{image} parent_and_child.png
>>     :alt: A schematic image of large adult facing a child
>>     :width: 50%
>>     :align: center
>>     ```
>> ```
>
> Uh, does it really also fail with a PNG image? (It works here.)

Sorry, that's a typo … I have switched to .png afterwards to avoid this
problem and then left it in the test case. I am sorry. Yes, PNG works
just fine.

> Possible workarounds include
>
> * using exporting to LaTeX and compile to PDF
> * using a PNG image
> * post-process the document after the export in the LibreOffice writer.

Gemini wrote to me this
https://paste.sr.ht/~mcepl/6dc49185a90e19ba623fd940f3e48d1b20f5ee0d, but
I am afraid it hallucinated most of the code, I cannot find that module
`svg2odg` anywhere. I guess, we would have to try to vibe-code that
converter anew (hopefully, conversion between two XML-based formats
should be something LLM should be able to do).

What do you think?

Matěj

-- 
http://matej.ceplovi.cz/blog/, @mc...@en...
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
… one of the main causes of the fall of the Roman Empire was
that, lacking zero, they had no way to indicate successful
termination of their C programs.
  -- Robert Firth

[Docutils-users] SVG images in ODT (was: Does the doctree reader work?)

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

On 2026-01-26, Matěj Cepl wrote:

> When running suggested command `docutils --parser=myst --writer=odt
> becoming_adult.md becoming_adult.odt` I get this error:

> $ docutils --verbose --traceback --parser=myst --writer=odt bec
> oming_adult.md becoming_adult.odt
> Traceback (most recent call last):
...
> PIL.UnidentifiedImageError: cannot identify image file 'parent_and_child.svg'

> If it is a known limitation of the ODT writer, is there a ticket for it?

Known limitations to image formats are (or are supposed to be) documented in
https://docutils.sourceforge.io/docs/ref/rst/directives.html#images

The documentation lists SVG and PDF as supported, however: SVG and PDF
vector graphics are supported by the ODT format but currently not by the
ODT writer.
This will be fixed in the documentation ASAP.

Unresolved exceptions (aborting processing and asking for --traceback)
are bugs.

> I cannot find anything on https://sourceforge.net/p/docutils/bugs/

The ODT writer's "traceback" on unsupported image formats is not yet reported.


> The minimal reproducer can be:

> ```markdown
>     ----
>     date: 2026-01-25T11:00:00
>     category: faith
>     tags: [innerHealing, sermon, PCF]
>     ----

>     # Becoming adult

>     ```{image} parent_and_child.png
>     :alt: A schematic image of large adult facing a child
>     :width: 50%
>     :align: center
>     ```
> ```

Uh, does it really also fail with a PNG image? (It works here.)

> Any thoughts?

The HTML writers use the PIL library to get the image size from the
graphics file for the :scale: option -- as a result, the :scale: option
does not work with SVG images (PIL only works with raster image formats).

I checked, whether a similar restriction applies to adjusting the size 
with :height: or :width: in the ODT writer. Unfortunately, also the truely
minimal example::

  .. image:: we-rgb.svg

failed.
Unfortunately, I don't know how to insert graphics into OTD, so there may be
no quick fix.

Possible workarounds include

* using exporting to LaTeX and compile to PDF
* using a PNG image
* post-process the document after the export in the LibreOffice writer.

Günter

Re: [Docutils-users] Does the doctree reader work?

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

On Mon Jan 26, 2026 at 11:42 AM CET, Guenter Milde via Docutils-users wrote:
> On 2026-01-24, Matěj Cepl wrote:
> Docutils supports the use of 3rd party parsers like "MySt" with the
> "generic front-end":
>
> To generate a HTML5 document from Markdown input, use
>
>   docutils --parser=myst
>
> To get ODT output from Markdown documents, try
>
>   docutils --parser=myst --writer=odt

I see! Thank you, I missed that, it makes much more sense. Unfortunately
for me, is it correct to say that docutils odt writer doesn’t support
vector images? Which format is supported?

See text of my yesterday’s sermon on https://git.sr.ht/~mcepl/2026-01-25-adulthood/tree

When running suggested command `docutils --parser=myst --writer=odt
becoming_adult.md becoming_adult.odt` I get this error:

$ docutils --verbose --traceback --parser=myst --writer=odt bec
oming_adult.md becoming_adult.odt
Traceback (most recent call last):
  File "/home/matej/.bin/docutils", line 8, in <module>
    sys.exit(main())
             ~~~~^^
  File "/usr/lib/python3.13/site-packages/docutils/__main__.py", line 84, in main
    publish_cmdline(reader=args.reader,
    ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^
                    parser=args.parser,
                    ^^^^^^^^^^^^^^^^^^^
    ...<2 lines>...
                    description=description,
                    ^^^^^^^^^^^^^^^^^^^^^^^^
                    argv=remainder)
                    ^^^^^^^^^^^^^^^
  File "/usr/lib/python3.13/site-packages/docutils/core.py", line 442, in publish_cmdline
    output = publisher.publish(
        argv, usage, description, settings_spec, settings_overrides,
        config_section=config_section, enable_exit_status=enable_exit_status)
  File "/usr/lib/python3.13/site-packages/docutils/core.py", line 272, in publish
    output = self.writer.write(self.document, self.destination)
  File "/usr/lib/python3.13/site-packages/docutils/writers/__init__.py", line 97, in write
    self.translate()
    ~~~~~~~~~~~~~~^^
  File "/usr/lib/python3.13/site-packages/docutils/writers/odf_odt/__init__.py", line 511, in translate
    self.document.walkabout(self.visitor)
    ~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^
  File "/usr/lib/python3.13/site-packages/docutils/nodes.py", line 232, in walkabout
    if child.walkabout(visitor):
       ~~~~~~~~~~~~~~~^^^^^^^^^
  File "/usr/lib/python3.13/site-packages/docutils/nodes.py", line 232, in walkabout
    if child.walkabout(visitor):
       ~~~~~~~~~~~~~~~^^^^^^^^^
  File "/usr/lib/python3.13/site-packages/docutils/nodes.py", line 232, in walkabout
    if child.walkabout(visitor):
       ~~~~~~~~~~~~~~~^^^^^^^^^
  File "/usr/lib/python3.13/site-packages/docutils/nodes.py", line 224, in walkabout
    visitor.dispatch_visit(self)
    ~~~~~~~~~~~~~~~~~~~~~~^^^^^^
  File "/usr/lib/python3.13/site-packages/docutils/writers/odf_odt/__init__.py", line 1554, in dispatch_visit
    nodes.GenericNodeVisitor.dispatch_visit(self, node)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^
  File "/usr/lib/python3.13/site-packages/docutils/nodes.py", line 2734, in dispatch_visit
    return method(node)
  File "/usr/lib/python3.13/site-packages/docutils/writers/odf_odt/__init__.py", line 2187, in visit_image
    self.generate_image(node, source, destination, el2)
    ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.13/site-packages/docutils/writers/odf_odt/__init__.py", line 2414, in generate_image
    width, height = self.get_image_scaled_width_height(node, source)
                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^
  File "/usr/lib/python3.13/site-packages/docutils/writers/odf_odt/__init__.py", line 2270, in get_image_scaled_width_height
    with PIL.Image.open(filename, 'r') as img:
         ~~~~~~~~~~~~~~^^^^^^^^^^^^^^^
  File "/home/matej/.local/lib/python3.13/site-packages/PIL/Image.py", line 3580, in open
    raise UnidentifiedImageError(msg)
PIL.UnidentifiedImageError: cannot identify image file 'parent_and_child.svg'
$ 

If it is a known limitation of the ODT writer, is there a ticket for it?
I cannot find anything on https://sourceforge.net/p/docutils/bugs/

The minimal reproducer can be:

```markdown
    ----
    date: 2026-01-25T11:00:00
    category: faith
    tags: [innerHealing, sermon, PCF]
    ----

    # Becoming adult

    ```{image} parent_and_child.png
    :alt: A schematic image of large adult facing a child
    :width: 50%
    :align: center
    ```
```

Any thoughts?

Best,

Matěj

-- 
http://matej.ceplovi.cz/blog/, @mc...@en...
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
I love deadlines. I like the whooshing sound they make as they
fly by.
  -- Douglas Adams, The Salmon of Doubt

Re: [Docutils-users] Does the doctree reader work?

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

On 2026-01-24, Matěj Cepl wrote:

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

> I was trying to compensate for openSUSE package of python3-myst-reader
> missing script for missing `myst-docutils-odt` script by trying to pipe
> the output of `myst-docutils-xml` to `docutils` and the result doesn't
> seem to work:
...
>     AttributeError: 'str' object has no attribute 'transformer' and no __dict__ for setting new attributes

The "xml" writer generates an XML document in the "Docutils XML" format
that can be written to a file or saved as string.

The "doctree" writer generates a Python data structure that can be passed on
to a writer, processed, or stored/pickled by other Python functions,
classes, or modules.

Docutils supports the use of 3rd party parsers like "MySt" with the
"generic front-end":

To generate a HTML5 document from Markdown input, use

  docutils --parser=myst

To get ODT output from Markdown documents, try

  docutils --parser=myst --writer=odt

To get ODT output from Docutils-XML documents, use

  docutils --parser=xml --writer=odt


Caveats:

* parsing "Markdown" input with 3rd party parsers myst, pycmark, or
  recommonmark requires Docutils >= 0.19 (2022-07-05)

* parsing "Docutils XML" requires Docutils >= 0.22 (2025-07-29)

* The MyST parser is not extensively tested with Docutils writers.

* The OTD writer has known (and unknown) limitations.

Pleas report problems with the Docutils parsers and writers here (or in the
bug tracker) and problems with the MyST parser to the original author.

To find out whether the problem is with MyST or Docutils, it may help to
validate the generated "doctree":

   docutils --parser=myst --validate --writer=xml minimal-example.md
   

Ahoj

Günter
   

[Docutils-users] Does the doctree reader work?

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

I was trying to compensate for openSUSE package of python3-myst-reader
missing script for missing `myst-docutils-odt` script by trying to pipe
the output of `myst-docutils-xml` to `docutils` and the result doesn't
seem to work:

    $ myst-docutils-xml becoming_adult.md | docutils --traceback --reader=doctree --writer=odt - becoming_adult.odt
    Traceback (most recent call last):
      File "/home/matej/.bin/docutils", line 8, in <module>
        sys.exit(main())
                 ~~~~^^
      File "/usr/lib/python3.13/site-packages/docutils/__main__.py", line 84, in main
        publish_cmdline(reader=args.reader,
        ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^
                        parser=args.parser,
                        ^^^^^^^^^^^^^^^^^^^
        ...<2 lines>...
                        description=description,
                        ^^^^^^^^^^^^^^^^^^^^^^^^
                        argv=remainder)
                        ^^^^^^^^^^^^^^^
      File "/usr/lib/python3.13/site-packages/docutils/core.py", line 442, in publish_cmdline
        output = publisher.publish(
            argv, usage, description, settings_spec, settings_overrides,
            config_section=config_section, enable_exit_status=enable_exit_status)
      File "/usr/lib/python3.13/site-packages/docutils/core.py", line 269, in publish
        self.document = self.reader.read(self.source, self.parser,
                        ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
                                         self.settings)
                                         ^^^^^^^^^^^^^^
      File "/usr/lib/python3.13/site-packages/docutils/readers/__init__.py", line 95, in read
        self.parse()
        ~~~~~~~~~~^^
      File "/usr/lib/python3.13/site-packages/docutils/readers/doctree.py", line 44, in parse
        self.document.transformer = transforms.Transformer(self.document)
        ^^^^^^^^^^^^^^^^^^^^^^^^^
    AttributeError: 'str' object has no attribute 'transformer' and no __dict__ for setting new attributes
    $ 

Is this supposed to work?

Best,

Matěj

-- 
http://matej.ceplovi.cz/blog/, @mc...@en...
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
He was born poor, died rich, and never hurt anyone along the way.
  -- Duke Ellington said about Louis Armstrong

[Docutils-users] docutils 0.22.4 released

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

Hei everybody,

another quick release, docutils 0.22.4 containing

reStructuredText Specification:
  - Clarify indentation rules: minimal indentation is *one* space.
  - Clarify comment syntax: Comments begin with two dots and *whitespace*.

HTML writers:
  - New value "auto" for the initial_header_level_ setting.
  - Bugfixes in the provisional style-sheet "responsive.css".

see https://docutils.sourceforge.io/HISTORY.html for details

thanks to Günter for his work

all the best
 e

[Docutils-users] docutils 0.22.3 released

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

Hei everyone,

on very short notice a very small release
Quick tiny release for two important bugfixes.

1. The longstanding issue with combining characters in grid tables is finally
  solved.

2. A fix for a problem for Sphinx users with Docutils 0.22.2 is solved as well.

cheers and all the best
 e

Re: [Docutils-users] comments vs. directives

[Schimon J. <sc...@fe...>]

Günter. Good afternoon.

I have just had a new realization, consequent to your mention of CSV.

On Fri, 10 Oct 2025 10:20:51 -0000 (UTC)
Guenter Milde via Docutils-users <doc...@li...>
wrote:

> On 2025-10-10, Schimon Jehudah via Docutils-users wrote:
> 
> >> > > >> >> The preamble [...] looks confusingly similar to 
> >> > > >> >> reStructuredtext directives.    
> 
> > Then, do you imply, by that statement, that it be a preferable
> > practice for preambles to differ from reStructuredtext directives?  
> 
> I would have chosen a different syntax.
> 
> However, considering the actual situation, I suggest keeping the
> current syntax (maybe even reverting to use a semicolon).
> 

I have changed preambles in accordance with The Atom Syndication
Format, which the publishing project software "Rivista Voyager"
focuses at.

Applying CSV tables to preambles with multiple values would further
allow, due to the built-in "csv" module of Python, to have a single
function to handle different preambles, which would further allow to
care for new attributes if needed.

.. author:
   name,uri
   Schimon Jehudah Zachary , xmpp:sc...@pi...?message

.. links:
   title,href,rel
   Metalinker.org - Why Metalink? , https://metalinker.org/why.html , related
   Metalinker: Integrating HTTP, FTP and P2P , https://torrentfreak.com/metalinker-integrating-http-ftp-and-p2p/ , related
   Metalink @ Packages Resources , http://metalink.packages.ro , related
   Shareaza Wiki , https://shareaza.sourceforge.net/mediawiki/Main_Page , related
   Gnutella2 Developer Network , https://g2.doxu.org , related

Instead of spliting and counting and guessing of types of values of
those preambles, those could be handled by this shorter code.

import csv
lines = csv_string.strip().split('\n')
for i in csv.DictReader(lines): i

Though, I would later solve how to retain values that
include commas. "Quotation marks" do not solve this.

Nevertheless, incorporating CSV is significantly better.

> Günter
> 

Schimon

Re: [Docutils-users] comments vs. directives

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

On 2025-10-10, Schimon Jehudah via Docutils-users wrote:

>> > > >> >> The preamble [...] looks confusingly similar to 
>> > > >> >> reStructuredtext directives.  

> Then, do you imply, by that statement, that it be a preferable practice
> for preambles to differ from reStructuredtext directives?

I would have chosen a different syntax.

However, considering the actual situation, I suggest keeping the current
syntax (maybe even reverting to use a semicolon).

Günter

Re: [Docutils-users] [SPAM] Re: Atom Syndication Format minimal example.

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

Dear Schimon,

thanks for the new example.

On 2025-10-10, Schimon Jehudah via Docutils-users wrote:
> On Thu, 9 Oct 2025 17:22:42 -0000 (UTC)
> Guenter Milde via Docutils-users <doc...@li...>
> wrote:

>> I just want a `minimal working example` as (opposed to illustrative
>> examples):

>>   The important feature of a minimal reproducible example is that it
>>   is as small and as simple as possible, such that it is just
>>   sufficient to demonstrate the problem, [...]
>>   -- https://en.wikipedia.org/wiki/Minimal_reproducible_example

...

> Are the attached files qualified as a proper example, or should I
> create a reduced version of the code that realizes that task?

Is getting close, but I would still call it an "illustrative example"
or "use case".  A "minimal example" could be even smaller.

For example, the content could be just two small paragraphs.
(However, it should keep containing at least one element that
distinguishes reStructuredText from plain text or other markup.)

Generally, a "minimal working example" would also include a description
of the steps to get the result.  
However, currently I will not try to reproduce the results, so this is
not required here. 

Günter


> [-- Type: text/x-rst, Encoding: 7bit, Filename: rst.rst --]

> .. authors: Schimon Jehudah Zachary , xmpp:sc...@pi...?message
> .. date: 2025-07-14 00:00:00 UTC
> .. description: A markup syntax.
> .. link: rst
> .. related:
>    reStructuredText homesite , https://docutils.sourceforge.io/rst.html
>    reStructuredText tutorials , https://docutils.sourceforge.io/docs/ref/rst/
> .. slug: rst
> .. tags:
>    Documentation, Publishing, Python Computer language, reStructuredText, rST
> .. title: reStructuredText
> .. type: text

> reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext
> markup syntax and parser system. It is useful for in-line program documentation
> (such as Python docstrings), for quickly creating simple internet pages, and for
> standalone documents.

...

> .. epigraph::
>    "reStructuredText" is ONE word, not two!

Re: [Docutils-users] comments vs. directives

[Schimon J. <sc...@fe...>]

Günter. Good afternoon.

On Fri, 10 Oct 2025 10:53:29 +0200
Guenter Milde <gm...@e-...> wrote:

> Dear Schimon,
> 
> Am 10.10.25 schrieb Schimon Jehudah:
> 
> ...
> > I have created a test file which is based only on your text.  
> 
> > Upon executing command rst2xml, Docutils outputs a couple of errors,
> > one for author and one for date.  
> 
> > I assume that these are errors of the directives author:: and date::
> > with two colons.  
> 
> Correct. 
> 
> With two colons, it is rST directive syntax.
> With one colon, it is rST comment syntax.
> 
> Add/remove one colon and you get unexpected results.
> 

Now, I realize this.

> This is what I meant with my statement that
> 
> > > >> >> The preamble [...] looks confusingly similar to 
> > > >> >> reStructuredtext directives.  
> 

Then, do you imply, by that statement, that it be a preferable practice
for preambles to differ from reStructuredtext directives?

> ...
> 
> > > * Optionally repeat with
> > > 
> > >     .. date: 2025-10-09
> > > 
> > >     .. date: 2025-10-09
> > >   
> 
> > Did you mean to add two consequent colons to the second instance of
> > "date" (i.e. "date::")?  
> 
> Yes. I was confused.
> 

Thank you.

> Günter

Schimon

Re: [Docutils-users] comments vs. directives

[Schimon J. <sc...@fe...>]

Guenter. Good day.

I think that I already did that, after you asked, but upon my documents.

I have created a test file which is based only on your text.

Upon executing command rst2xml, Docutils outputs a couple of errors,
one for author and one for date.

I assume that these are errors of the directives author:: and date::
with two colons.


$ rst2xml rst_preambles_and_directives_sample.rst >rst_preambles_and_directives_sample.xml
rst_preambles_and_directives_sample.rst:7: (ERROR/3) Unknown directive type "author".

.. author:: My Lin

rst_preambles_and_directives_sample.rst:11: (ERROR/3) Invalid context: the "date" directive can only be used within a substitution definition.


Schimon

On Thu, 9 Oct 2025 18:46:31 -0000 (UTC)
Guenter Milde via Docutils-users <doc...@li...>
wrote:

> On 2025-10-09, Schimon Jehudah via Docutils-users wrote:
> ...
> 
> 
> >> >> The preamble seems to use no standard but a home-grown syntax
> >> >> that looks confusingly similar to reStructuredtext directives.
> >> >>   
> 
> >> > How so?    
> 
> ...
> 
> Steps to find out why I call the current Rivista metadata syntax 
> "confusingly similar" to Docutils directives:
> 
> * create a file containing
> 
>     .. title: My simple example
> 
>     .. title:: My simple example
> 
> * convert with rst2xml to see how the two statements are interpreted
> by the docutils "rst" parser.
>   
> * Optionally repeat with
> 
>     .. author: My Lin
> 
>     .. author:: My Lin
> 
> * Optionally repeat with
> 
>     .. date: 2025-10-09
> 
>     .. date: 2025-10-09
> 

Did you mean to add two consequent colons to the second instance of
"date" (i.e. "date::")?

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

[Docutils-users] [SPAM] Re: Atom Syndication Format minimal example.

[Schimon J. <sc...@fe...>]

Guenter. Good day.

Are the attached files qualified as a proper example, or should I
create a reduced version of the code that realizes that task?

Kindly,

Schimon

On Thu, 9 Oct 2025 17:22:42 -0000 (UTC)
Guenter Milde via Docutils-users <doc...@li...>
wrote:

> On 2025-10-09, Schimon Jehudah via Docutils-users wrote:
> > On Thu, 9 Oct 2025 Guenter Milde via Docutils-users wrote:  
> >> ...  
> 
> >> Please provide a **minimal** example.
> >> (e.g. input to generate something like
> >> https://en.wikipedia.org/wiki/Atom_(web_standard)#Example_of_an_Atom_1.0_feed)
> >>  
> 
> > Pardon. I do not realize what is this for, unless you mean that by
> > "standard" I should comply with the fields (XML elements) of The
> > Atom Syndication Format.   
> 
> I just want a `minimal working example` as (opposed to illustrative
> examples):
> 
>   The important feature of a minimal reproducible example is that it
> is as small and as simple as possible, such that it is just
> sufficient to demonstrate the problem, [...]
> 
>   -- https://en.wikipedia.org/wiki/Minimal_reproducible_example
> 
> Günter
> 

[Docutils-users] comments vs. directives

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

On 2025-10-09, Schimon Jehudah via Docutils-users wrote:
...


>> >> The preamble seems to use no standard but a home-grown syntax that
>> >> looks confusingly similar to reStructuredtext directives.  

>> > How so?  

...

Steps to find out why I call the current Rivista metadata syntax 
"confusingly similar" to Docutils directives:

* create a file containing

    .. title: My simple example

    .. title:: My simple example

* convert with rst2xml to see how the two statements are interpreted by
  the docutils "rst" parser.
  
* Optionally repeat with

    .. author: My Lin

    .. author:: My Lin

* Optionally repeat with

    .. date: 2025-10-09

    .. date: 2025-10-09


Günter

[Docutils-users] [SPAM] Re: Docutils standards

[Schimon J. <sc...@fe...>]

Guenter. Good evening.

On Thu, 9 Oct 2025 16:30:13 -0000 (UTC)
Guenter Milde via Docutils-users <doc...@li...>
wrote:

> Dear Schimon,
> 
> On 2025-10-09, Schimon Jehudah via Docutils-users wrote:
> 
> > I want to conclude these realizations.  
> 
> > * Docutils has standard Preambles (Metadata) of its own.  
> 
> Docutils has no formal standards (RFCs or similar).
> 
> However, the Docutils project maintains 2 formal specifications as
> part of the public API. 
> 
> a) The `reStructuredText Markup Specification`__
> 
>    __
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html 
> b) The Docutils document model: 
>    `The Docutils Document Tree`__
>    `Docutils Generic XML document type definition`__
>    
>    __ https://docutils.sourceforge.io/docs/ref/doctree.html
>    __ https://docutils.sourceforge.io/docs/ref/docutils.dtd
> 
> The `reStructuredText Markup Specification` includes the definition of
> `bibliographic fields`__. "This bibliographic data corresponds to the
> front matter of a book, such as the title page and copyright page."
> Whether the bibliographic fields can cleanly map to Atom Syndication
> metadata is an open question.
> 
> __
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bibliographic-fields
> 
> There is also the `meta`__ standard directive and <meta> `Doctree
> element`__ which provides an alternative to a comment for meta-data
> that should be extracted from the XML version.
> For example, the rST ::
> 
>     .. meta::
>        :keywords: plaintext, markup language
>        :description lang=en: An amusing story
>        :description lang=fr: Une histoire amusante
> 
> is parsed into the XML elements::
> 
>     <meta content="plaintext, markup language" name="keywords"></meta>
>     <meta content="An amusing story" lang="en"
> name="description"></meta> <meta content="Une histoire amusante"
> lang="fr" name="description"></meta>
> 
> __
> https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata
> __ https://docutils.sourceforge.io/docs/ref/doctree.html#meta
> 
> 

I will consider these metadata entries in addition to thise of The Atom
Syndication Format, as project Rivista Voyager has a specific niche for
the Atom format due to the idea of an XML-based internet implemented
with Atom and XLink.

gemini://woodpeckersnest.space/~schapps/journal/2025-10-08-a-hope-for-further-internet-federation-via-http.gmi
gemini://woodpeckersnest.space/~schapps/journal/2025-08-10-an-analyses-of-the-benefits-of-ace.gmi
gemini://woodpeckersnest.space/~schapps/journal/2025-07-29-announcing-ace.gmi

> 
> > * It be preferable to comply with the standard structure of
> > Docutils.  
> 
> I concluded from your answers so far, that you want to use
> reStructuredText (rST) as input file format (as opposed to 
> rST content embedded in a file with different format).
> 

Yes. Indeed.

> In this scenario, I suggest utilising rST syntax constructs to
> structure the meta-data. Then, the Docutils rST parser can provide
> the meta-data in a structured form.
> 
> Currently, meta-data is included as a series of rST comments and
> parsed according to a simple ad-hoc format that is intuitive and
> "natural" --- for its creator.
> 

I will explore this.

> 
> > * With XSLT, it is possible to transform Docutils XML into Atom,
> > CSV, HTML, JSON, TSV, Twtxt, XHTML, etc.  
> 
> This is my understanding of the power of XSLT:
> 
> * Docutils can generate output in its well defined, valid XML format.
> * With the correct set of rules, XSLT can convert any valid XML to
> other XML formats and more.
> 
> Whether there are some limitations and whether writing the XSLT
> rules/styles/templates required for this task is simpler than coding a
> Docutils "writer" class in Python exceeds my knowledge.
> (I am familiar with Python but not with XSLT.)
> 

There are no limitations. There is only a consideration which is to
include in produced XML files the necessary data for XSLT to process.

Post script
-----------

XSLT is XML or XHTML with XPath rules which have more possibilities and
functionalities that CSS Selectors.

I am a lawyer and I studied XSLT within less than 14 days while creating
a stylesheet for Atom, RDF, and RSS. The first attempt was not
spectacular, but it worked and it did the desired task well.

https://git.xmpp-it.net/sch/StreamBurner

XSLT is similar to so called "templating engines" such as Bottle.py,
Django, Jinja2, PHP, Embedded Ruby (ERB), et cetera, yet unlike
"templating engines" XSLT is standard and can be realized with any
computer language which has modules for parsing of XML.

> 
> Regards, 
> Günter
> 

Thank you very much!

Best,

Schimon.

[Docutils-users] Atom Syndication Format minimal example.

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

On 2025-10-09, Schimon Jehudah via Docutils-users wrote:
> On Thu, 9 Oct 2025 Guenter Milde via Docutils-users wrote:
>> ...

>> Please provide a **minimal** example.
>> (e.g. input to generate something like
>> https://en.wikipedia.org/wiki/Atom_(web_standard)#Example_of_an_Atom_1.0_feed)

> Pardon. I do not realize what is this for, unless you mean that by
> "standard" I should comply with the fields (XML elements) of The Atom
> Syndication Format. 

I just want a `minimal working example` as (opposed to illustrative
examples):

  The important feature of a minimal reproducible example is that it is
  as small and as simple as possible, such that it is just sufficient to
  demonstrate the problem, [...]

  -- https://en.wikipedia.org/wiki/Minimal_reproducible_example

Günter

Re: [Docutils-users] Docutils standards

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

Dear Schimon,

On 2025-10-09, Schimon Jehudah via Docutils-users wrote:

> I want to conclude these realizations.

> * Docutils has standard Preambles (Metadata) of its own.

Docutils has no formal standards (RFCs or similar).

However, the Docutils project maintains 2 formal specifications as part
of the public API. 

a) The `reStructuredText Markup Specification`__

   __ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
   
b) The Docutils document model: 
   `The Docutils Document Tree`__
   `Docutils Generic XML document type definition`__
   
   __ https://docutils.sourceforge.io/docs/ref/doctree.html
   __ https://docutils.sourceforge.io/docs/ref/docutils.dtd

The `reStructuredText Markup Specification` includes the definition of
`bibliographic fields`__. "This bibliographic data corresponds to the
front matter of a book, such as the title page and copyright page."
Whether the bibliographic fields can cleanly map to Atom Syndication
metadata is an open question.

__ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bibliographic-fields

There is also the `meta`__ standard directive and <meta> `Doctree element`__
which provides an alternative to a comment for meta-data that should be
extracted from the XML version.
For example, the rST ::

    .. meta::
       :keywords: plaintext, markup language
       :description lang=en: An amusing story
       :description lang=fr: Une histoire amusante

is parsed into the XML elements::

    <meta content="plaintext, markup language" name="keywords"></meta>
    <meta content="An amusing story" lang="en" name="description"></meta>
    <meta content="Une histoire amusante" lang="fr" name="description"></meta>

__ https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata
__ https://docutils.sourceforge.io/docs/ref/doctree.html#meta



> * It be preferable to comply with the standard structure of Docutils.

I concluded from your answers so far, that you want to use
reStructuredText (rST) as input file format (as opposed to 
rST content embedded in a file with different format).

In this scenario, I suggest utilising rST syntax constructs to structure
the meta-data. Then, the Docutils rST parser can provide the meta-data in
a structured form.

Currently, meta-data is included as a series of rST comments and parsed
according to a simple ad-hoc format that is intuitive and "natural"
--- for its creator.


> * With XSLT, it is possible to transform Docutils XML into Atom, CSV,
>   HTML, JSON, TSV, Twtxt, XHTML, etc.

This is my understanding of the power of XSLT:

* Docutils can generate output in its well defined, valid XML format.
* With the correct set of rules, XSLT can convert any valid XML to other
  XML formats and more.

Whether there are some limitations and whether writing the XSLT
rules/styles/templates required for this task is simpler than coding a
Docutils "writer" class in Python exceeds my knowledge.
(I am familiar with Python but not with XSLT.)


Regards, 
Günter

Re: [Docutils-users] XLink as a solution for references

[Schimon J. <sc...@fe...>]

Sorry, I forgot to add XSLT.

rST > (Docutils) > Docutils-XML > (XSLT) > Atom Syndication Format
rST > (Docutils) > Docutils-XML > (XSLT) > JSON Feed
rST > (Docutils) > Docutils-XML > (XSLT) > Twtxt
rST > (Docutils) > Docutils-XML > (XSLT) > (X)HTML

Schimon

On Thu, 9 Oct 2025 17:56:33 +0300
Schimon Jehudah <sc...@fe...> wrote:

> Guenter. Good evening.
> 
> Please see a newly proposed diagram.
> 
> On Thu, 9 Oct 2025 17:19:26 +0300
> Schimon Jehudah via Docutils-users
> <doc...@li...> wrote:
> 
> > On Thu, 9 Oct 2025 12:48:47 -0000 (UTC)
> > Guenter Milde via Docutils-users
> > <doc...@li...> wrote:
> >   
> > > On 2025-10-09, Schimon Jehudah via Docutils-users wrote:
> > >     
> > > >> What I am missing, is a user documentation.      
> > >     
> > > > There is no documentation yet. This software is subjected to
> > > > further development.      
> > > 
> > > It helps to write/update user documentation in parallel (at least
> > > a stub):
> > > 
> > >    If the implementation is hard to explain, it's a bad idea.
> > >    If the implementation is easy to explain, it may be a good
> > > idea. 
> > >    -- python -m this
> > >     
> > 
> > Thank you for this comment. I will do so.
> >   
> > > >> Also, I cannot find a description of the input format.        
> > >     
> > > >> The preamble seems to use no standard but a home-grown syntax
> > > >> that looks confusingly similar to reStructuredtext directives.
> > > >>    
> > >     
> > > > How so?      
> > > 
> > > ::
> > > 
> > >   .. title: My simple example
> > > 
> > >   .. title:: My simple example
> > > 
> > > Convert with rst2xml and rst2html to see the difference.
> > >     
> > 
> > In HTML, "Title ::" is realized into element "title" under element
> > "head".
> > 
> > In XML, "Title ::" is realized into attribute "title" of element
> > "document".
> > 
> > I think that the placement of these propertoes as attributes would
> > definitely facilitate the XSL Transformation of XML Docutils into
> > Atom Syndication Format with a designated XSLT stylesheet.
> > 
> > Yet, I stil do not realize the reason for your comment.
> > 
> > Is ityour comment, an explanatory comment or a comment that my rST
> > documents have issues?
> >   
> > >     
> > > > Do you mean that the use of multiple lines in which each
> > > > semicolon segregates "title" and "address" is not to be
> > > > considered as standard?      
> > > 
> > > It could be considered as CSV-variant. You would have to 
> > > 
> > > * document/motivate the use of this CSV variant
> > >   in the preamble fields of an rST document and 
> > > * write your own parser (or XSLT extraction rules) 
> > >   to parse the raw field content.¹
> > >     
> > 
> > If I would produce CSV, then I would use my own parser, as I think
> > that XSLT only works with JSON and XML, and probably other formats
> > that can be queried.
> > 
> > Nevertheless, I think that I realize your answer.
> >   
> > > Also, the semicolon clashes with rST syntax in "authors" fields:
> > > https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#authors
> > >     
> > 
> > Thank you for this additional information.
> > 
> > I will act upon this in a few hours.
> >   
> > > ¹ rST supports CSV with the "CSV-table" directive 
> > >   (and the separator defaulting to ",").
> > >   https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table
> > >   
> > >   Howver, you won't like to write::
> > >   
> > >   :authors: .. csv-table::
> > >     
> > 
> > I apologise for asking this again, I think, yet I want to be
> > certain.
> > 
> > Is this fine to write this? (comma)
> > 
> > .. author:
> >    BabylonObserver.com , https://babylonobserver.com
> >    The Babylon Observer , mailto:in...@ba...
> > 
> > Or would it be appropriate to write this? (greater > and lesser <
> > than)
> > 
> > .. author:
> >    BabylonObserver.com <https://babylonobserver.com>
> >    The Babylon Observer <mailto:in...@ba...>
> > 
> >   
> > > 
> > >     
> > > >> > I think that it would be nice for Docutils to have features
> > > >> > for XML.        
> > >     
> > > >> If you want XML, you may try the docutils-XML writer --
> > > >> Docutils XML is a well defined XML format.      
> > >     
> > > >> It should be possible to generate HTML from Docutils XML with
> > > >> XSLT styles. This could be a way to achieve a HTML variant that
> > > >> is impossible via the Docutils HTML writers (but is lots of
> > > >> work).      
> > > 
> > >     
> > > > This is interesting.      
> > >     
> > > > Then, it is possible to utilize an XSLT stylesheet to transform
> > > > that XML to Atom Syndication Format, and an additional XSLT
> > > > stylesheet to transform that XML to HTML;      
> > >     
> > > > Docutils XML > (XSLT) > Atom      
> > >     
> > > > Docutils XML > (XSLT) > HTML      
> > >     
> > > > Of course, it is also possible to utilize the current stylesheet
> > > > which already transforms Atom to HTML.      
> > >     
> > > > Docutils XML > (XSLT) > Atom > (XSLT) > HTML      
> > > 
> > > 
> > > I'd try to re-use as much as possible.    
> > 
> > So, you advise to use the standard of Docutils instead of
> > information that may be related to Atom or otherwise, are yes?
> >   
> > > Atom is XML with the content embedded as HTML,
> > > so maybe:
> > > 
> > > * rST > (Rivista) > rST-preamble + rST-content
> > > 
> > > * rST-preamble > (Docutils) > Docutils-XML
> > >   rST-content  > (Docutils) > HTML
> > >       
> >   
> 
> Reading the XML output, and seeing elements "paragraph", "block_quote"
> for paragraphs, and "reference" for IRI/URI/URL (equivalent to HTML
> element "a"), I thik that it should be possible to create an XSLT
> styleshet which would transform the who Docutils XML documents into an
> Atom Syndication Format document.
> 
> rST > (Docutils) > Docutils-XML > Atom Syndication Format
> rST > (Docutils) > Docutils-XML > JSON Feed
> rST > (Docutils) > Docutils-XML > Twtxt
> rST > (Docutils) > Docutils-XML > (X)HTML
> 
> > This is what I currently do, and intend to further finalize.
> > 
> > rST-preamble > (Docutils) > Atom-dict (title, summary, link, etc.)
> > 
> > rST-content > (Docutils) > HTML > Atom-dict (content)
> > 
> > Atom-dict > Atom-XML
> >   
> > > * XML-preamble + HTML-content (XSLT) > Atom-XML
> > >     
> > 
> > I think that I would have to merge the XML-preamble and
> > HTML-content, in order to be able to produce an Atom-XML.
> >   
> > > * Atom > (XSLT) > HTML  
> > >     
> > 
> > This procedure is already done.
> > 
> > # Generate HTML of Atom
> > filepath_xslt_atom = os.path.join(
> >     publish_properties.directory_xslt, filename_xslt)
> > atom_as_element_tree = ParserXml.create_element_tree_from_file(
> >     filepath_atom)
> > atom_html_as_str = ParserXslt.transform_data(
> >     atom_as_element_tree, filepath_xslt_atom)
> > filepath_atom_html = os.path.join(
> >     directory_html, directory, identifier, "index.html")
> > with open(filepath_atom_html, "w") as fn: fn.write(atom_html_as_str)
> >   
> > > 
> > > Günter
> > >     
> > 
> > Schimon
> > 
> >   
> 
> Schimon

Re: [Docutils-users] XLink as a solution for references

[Schimon J. <sc...@fe...>]

Guenter. Good evening.

Please see a newly proposed diagram.

On Thu, 9 Oct 2025 17:19:26 +0300
Schimon Jehudah via Docutils-users
<doc...@li...> wrote:

> On Thu, 9 Oct 2025 12:48:47 -0000 (UTC)
> Guenter Milde via Docutils-users
> <doc...@li...> wrote:
> 
> > On 2025-10-09, Schimon Jehudah via Docutils-users wrote:
> >   
> > >> What I am missing, is a user documentation.    
> >   
> > > There is no documentation yet. This software is subjected to
> > > further development.    
> > 
> > It helps to write/update user documentation in parallel (at least a
> > stub):
> > 
> >    If the implementation is hard to explain, it's a bad idea.
> >    If the implementation is easy to explain, it may be a good idea.
> >    
> >    -- python -m this
> >   
> 
> Thank you for this comment. I will do so.
> 
> > >> Also, I cannot find a description of the input format.      
> >   
> > >> The preamble seems to use no standard but a home-grown syntax
> > >> that looks confusingly similar to reStructuredtext directives.
> > >>  
> >   
> > > How so?    
> > 
> > ::
> > 
> >   .. title: My simple example
> > 
> >   .. title:: My simple example
> > 
> > Convert with rst2xml and rst2html to see the difference.
> >   
> 
> In HTML, "Title ::" is realized into element "title" under element
> "head".
> 
> In XML, "Title ::" is realized into attribute "title" of element
> "document".
> 
> I think that the placement of these propertoes as attributes would
> definitely facilitate the XSL Transformation of XML Docutils into Atom
> Syndication Format with a designated XSLT stylesheet.
> 
> Yet, I stil do not realize the reason for your comment.
> 
> Is ityour comment, an explanatory comment or a comment that my rST
> documents have issues?
> 
> >   
> > > Do you mean that the use of multiple lines in which each semicolon
> > > segregates "title" and "address" is not to be considered as
> > > standard?    
> > 
> > It could be considered as CSV-variant. You would have to 
> > 
> > * document/motivate the use of this CSV variant
> >   in the preamble fields of an rST document and 
> > * write your own parser (or XSLT extraction rules) 
> >   to parse the raw field content.¹
> >   
> 
> If I would produce CSV, then I would use my own parser, as I think
> that XSLT only works with JSON and XML, and probably other formats
> that can be queried.
> 
> Nevertheless, I think that I realize your answer.
> 
> > Also, the semicolon clashes with rST syntax in "authors" fields:
> > https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#authors
> >   
> 
> Thank you for this additional information.
> 
> I will act upon this in a few hours.
> 
> > ¹ rST supports CSV with the "CSV-table" directive 
> >   (and the separator defaulting to ",").
> >   https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table
> >   
> >   Howver, you won't like to write::
> >   
> >   :authors: .. csv-table::
> >   
> 
> I apologise for asking this again, I think, yet I want to be certain.
> 
> Is this fine to write this? (comma)
> 
> .. author:
>    BabylonObserver.com , https://babylonobserver.com
>    The Babylon Observer , mailto:in...@ba...
> 
> Or would it be appropriate to write this? (greater > and lesser <
> than)
> 
> .. author:
>    BabylonObserver.com <https://babylonobserver.com>
>    The Babylon Observer <mailto:in...@ba...>
> 
> 
> > 
> >   
> > >> > I think that it would be nice for Docutils to have features for
> > >> > XML.      
> >   
> > >> If you want XML, you may try the docutils-XML writer -- Docutils
> > >> XML is a well defined XML format.    
> >   
> > >> It should be possible to generate HTML from Docutils XML with
> > >> XSLT styles. This could be a way to achieve a HTML variant that
> > >> is impossible via the Docutils HTML writers (but is lots of
> > >> work).    
> > 
> >   
> > > This is interesting.    
> >   
> > > Then, it is possible to utilize an XSLT stylesheet to transform
> > > that XML to Atom Syndication Format, and an additional XSLT
> > > stylesheet to transform that XML to HTML;    
> >   
> > > Docutils XML > (XSLT) > Atom    
> >   
> > > Docutils XML > (XSLT) > HTML    
> >   
> > > Of course, it is also possible to utilize the current stylesheet
> > > which already transforms Atom to HTML.    
> >   
> > > Docutils XML > (XSLT) > Atom > (XSLT) > HTML    
> > 
> > 
> > I'd try to re-use as much as possible.  
> 
> So, you advise to use the standard of Docutils instead of information
> that may be related to Atom or otherwise, are yes?
> 
> > Atom is XML with the content embedded as HTML,
> > so maybe:
> > 
> > * rST > (Rivista) > rST-preamble + rST-content
> > 
> > * rST-preamble > (Docutils) > Docutils-XML
> >   rST-content  > (Docutils) > HTML
> >     
> 

Reading the XML output, and seeing elements "paragraph", "block_quote"
for paragraphs, and "reference" for IRI/URI/URL (equivalent to HTML
element "a"), I thik that it should be possible to create an XSLT
styleshet which would transform the who Docutils XML documents into an
Atom Syndication Format document.

rST > (Docutils) > Docutils-XML > Atom Syndication Format
rST > (Docutils) > Docutils-XML > JSON Feed
rST > (Docutils) > Docutils-XML > Twtxt
rST > (Docutils) > Docutils-XML > (X)HTML

> This is what I currently do, and intend to further finalize.
> 
> rST-preamble > (Docutils) > Atom-dict (title, summary, link, etc.)
> 
> rST-content > (Docutils) > HTML > Atom-dict (content)
> 
> Atom-dict > Atom-XML
> 
> > * XML-preamble + HTML-content (XSLT) > Atom-XML
> >   
> 
> I think that I would have to merge the XML-preamble and HTML-content,
> in order to be able to produce an Atom-XML.
> 
> > * Atom > (XSLT) > HTML  
> >   
> 
> This procedure is already done.
> 
> # Generate HTML of Atom
> filepath_xslt_atom = os.path.join(
>     publish_properties.directory_xslt, filename_xslt)
> atom_as_element_tree = ParserXml.create_element_tree_from_file(
>     filepath_atom)
> atom_html_as_str = ParserXslt.transform_data(
>     atom_as_element_tree, filepath_xslt_atom)
> filepath_atom_html = os.path.join(
>     directory_html, directory, identifier, "index.html")
> with open(filepath_atom_html, "w") as fn: fn.write(atom_html_as_str)
> 
> > 
> > Günter
> >   
> 
> Schimon
> 
> 

Schimon

[Docutils-users] Docutils standards

[Schimon J. <sc...@fe...>]

Guenter. Good evening.

I am stil contemplating after reading the recent couple of email
messages, and I do not want to further bother you, especially when it
is not necessary.

I am writing this message just so that we have a clear context of the
concern which we discuss of, and just for that purpose.

I want to conclude these realizations.

* Docutils has standard Preambles (Metadata) of its own.

* It be preferable to comply with the standard structure of Docutils.

* With XSLT, it is possible to transform Docutils XML into Atom, CSV,
  HTML, JSON, TSV, Twtxt, XHTML, etc.

Are these correct conclusions?

Kindly,
Schimon

Re: [Docutils-users] XLink as a solution for references

[Schimon J. <sc...@fe...>]

On Thu, 9 Oct 2025 12:48:47 -0000 (UTC)
Guenter Milde via Docutils-users <doc...@li...>
wrote:

> On 2025-10-09, Schimon Jehudah via Docutils-users wrote:
> 
> >> What I am missing, is a user documentation.  
> 
> > There is no documentation yet. This software is subjected to further
> > development.  
> 
> It helps to write/update user documentation in parallel (at least a
> stub):
> 
>    If the implementation is hard to explain, it's a bad idea.
>    If the implementation is easy to explain, it may be a good idea.
>    
>    -- python -m this
> 

Thank you for this comment. I will do so.

> >> Also, I cannot find a description of the input format.    
> 
> >> The preamble seems to use no standard but a home-grown syntax that
> >> looks confusingly similar to reStructuredtext directives.  
> 
> > How so?  
> 
> ::
> 
>   .. title: My simple example
> 
>   .. title:: My simple example
> 
> Convert with rst2xml and rst2html to see the difference.
> 

In HTML, "Title ::" is realized into element "title" under element
"head".

In XML, "Title ::" is realized into attribute "title" of element
"document".

I think that the placement of these propertoes as attributes would
definitely facilitate the XSL Transformation of XML Docutils into Atom
Syndication Format with a designated XSLT stylesheet.

Yet, I stil do not realize the reason for your comment.

Is ityour comment, an explanatory comment or a comment that my rST
documents have issues?

> 
> > Do you mean that the use of multiple lines in which each semicolon
> > segregates "title" and "address" is not to be considered as
> > standard?  
> 
> It could be considered as CSV-variant. You would have to 
> 
> * document/motivate the use of this CSV variant
>   in the preamble fields of an rST document and 
> * write your own parser (or XSLT extraction rules) 
>   to parse the raw field content.¹
> 

If I would produce CSV, then I would use my own parser, as I think that
XSLT only works with JSON and XML, and probably other formats that can
be queried.

Nevertheless, I think that I realize your answer.

> Also, the semicolon clashes with rST syntax in "authors" fields:
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#authors
> 

Thank you for this additional information.

I will act upon this in a few hours.

> ¹ rST supports CSV with the "CSV-table" directive 
>   (and the separator defaulting to ",").
>   https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table
>   
>   Howver, you won't like to write::
>   
>   :authors: .. csv-table::
> 

I apologise for asking this again, I think, yet I want to be certain.

Is this fine to write this? (comma)

.. author:
   BabylonObserver.com , https://babylonobserver.com
   The Babylon Observer , mailto:in...@ba...

Or would it be appropriate to write this? (greater > and lesser < than)

.. author:
   BabylonObserver.com <https://babylonobserver.com>
   The Babylon Observer <mailto:in...@ba...>


> 
> 
> >> > I think that it would be nice for Docutils to have features for
> >> > XML.    
> 
> >> If you want XML, you may try the docutils-XML writer -- Docutils
> >> XML is a well defined XML format.  
> 
> >> It should be possible to generate HTML from Docutils XML with XSLT
> >> styles. This could be a way to achieve a HTML variant that is
> >> impossible via the Docutils HTML writers (but is lots of work).  
> 
> 
> > This is interesting.  
> 
> > Then, it is possible to utilize an XSLT stylesheet to transform that
> > XML to Atom Syndication Format, and an additional XSLT stylesheet to
> > transform that XML to HTML;  
> 
> > Docutils XML > (XSLT) > Atom  
> 
> > Docutils XML > (XSLT) > HTML  
> 
> > Of course, it is also possible to utilize the current stylesheet
> > which already transforms Atom to HTML.  
> 
> > Docutils XML > (XSLT) > Atom > (XSLT) > HTML  
> 
> 
> I'd try to re-use as much as possible.

So, you advise to use the standard of Docutils instead of information
that may be related to Atom or otherwise, are yes?

> Atom is XML with the content embedded as HTML,
> so maybe:
> 
> * rST > (Rivista) > rST-preamble + rST-content
> 
> * rST-preamble > (Docutils) > Docutils-XML
>   rST-content  > (Docutils) > HTML
>   

This is what I currently do, and intend to further finalize.

rST-preamble > (Docutils) > Atom-dict (title, summary, link, etc.)

rST-content > (Docutils) > HTML > Atom-dict (content)

Atom-dict > Atom-XML

> * XML-preamble + HTML-content (XSLT) > Atom-XML
> 

I think that I would have to merge the XML-preamble and HTML-content,
in order to be able to produce an Atom-XML.

> * Atom > (XSLT) > HTML  
> 

This procedure is already done.

# Generate HTML of Atom
filepath_xslt_atom = os.path.join(
    publish_properties.directory_xslt, filename_xslt)
atom_as_element_tree = ParserXml.create_element_tree_from_file(
    filepath_atom)
atom_html_as_str = ParserXslt.transform_data(
    atom_as_element_tree, filepath_xslt_atom)
filepath_atom_html = os.path.join(
    directory_html, directory, identifier, "index.html")
with open(filepath_atom_html, "w") as fn: fn.write(atom_html_as_str)

> 
> Günter
> 

Schimon