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

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

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

Guenter. Good day.

On Tue, 7 Oct 2025 20:13:23 -0000 (UTC)
Guenter Milde via Docutils-users <doc...@li...>
wrote:

> On 2025-10-06, Schimon Jehudah via Docutils-users wrote:
> 
> > I forgot to attach the reStructuredText file.  
> ...
> 
> > .. authors: LAFKON Publishing ; mailto:ha...@la...
> > .. category: journal
> > .. comments: true
> > .. date: 2004-09-09 0:00:00 UTC  
> 
> ...
> 
> There are actually 2 ways to specify meta-data in rST, so you don't
> need to resort to comments:
> 
> a) bibliographic fields (for "visible" metadata)
>    https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bibliographic-fields
> 
>    A "visible" document start could look like::
> 
>      a short animated video about computers and trust
>      ------------------------------------------------
>      
>      :author: LAFKON Publishing <ha...@la...>
>      :author: `LAFKON Publishing <mailto:ha...@la...>`__
>      :abstract:
>         This is a short animated video (3:30 minutes) about computers
> and trust. “Trusted Computing” - ever heard of it?
>         This motion graphic style documentary explains what the term
> “trust” has in common with “Trusted Computing” and where you will
> meet this so-called technology in the near future.
>         Computers and Internet gave you freedom. TCPA is designed
> against freedom! It is crucial that you listen to it.
>      
>      :date: 2004-09-09 0:00:00 UTC
>      :slug: 2004-09-09-trusted-computing-2004
>      :tags: control, computing, iot, lafkon, lagrande, 
>      :type: text
> 

This is interesting, and it might be helpful to me. Thank you.

> b) the "meta" directive (for "invisible" metadata)
>    https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata
> 
>    Example::
>    
>      .. meta::
>         :authors: LAFKON Publishing <mailto:ha...@la...>
>         :category: journal
>         :comments: true
>         :date: 2004-09-09 0:00:00 UTC
>         :description:
>         :slug: 2004-09-09-trusted-computing-2004
>         :tags: control, computing, iot, lafkon, lagrande, 
>         :type: text
> 
> Both can be combined.
> 

I did not know of it; yet, that is probably not useful for project
Rivista Voyager, because it stores metadata references in Atom
Syndication Format elements, and XSLT is the only mean to transform
Atom Syndication Format to XHTML.

Tags are placed inside element "atom:category", and XSLT stylesheet
extracts values of "atom"categories" to (X)HTML metadata.

<xsl:if test="atom:category">
  <xsl:element name="meta">
    <xsl:attribute name="name">
      <xsl:text>keywords</xsl:text>
    </xsl:attribute>
    <xsl:attribute name="content">
      <xsl:for-each select="atom:category">
        <xsl:value-of select="@term"/>
        <xsl:text>, </xsl:text>
      </xsl:for-each>
    </xsl:attribute>
  </xsl:element>
</xsl:if>

View the source code of these documents (XML and HTML).

This is Atom (XSLT: client-side)
https://journal.woodpeckersnest.eu/posts/2004-09-09-trusted-computing-2004/index.atom

This is HTML (XSLT: server-side)
https://journal.woodpeckersnest.eu/posts/2004-09-09-trusted-computing-2004/index.html

Additionally, as element "atom:category" provides attribute "label",
the reStructuredText tags field will be designed as.

.. tags:
   BitTorrent ; bittorrent
   eDonkey2000 ; ed2k
   Gnutella ; gnutella
   IPFS ; ipfs
   Linux ; linux
   MUTE; mute
   ReactOS ; reactos

Concerning to field "authors"; I have deliberately added semicolon as
it it easier to "split" title from address.

.. authors: LAFKON Publishing ; mailto:ha...@la...

> ...
> 
> > .. title: Trusted Computing (2004)  
> 
> Besides the "visible" title (via first section)
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#document-title
> there is also the "invisible" title via directive:
> https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata-document-title
> 

I did not know of it. I will explore this concern.

> ...
> 
> > .. image:: https://lafkon.net/work/trustedcomputing.jpg
> >    :alt: Trusted Computing
> >    :loading: lazy
> >    :target: https://lafkon.net/work/trustedcomputing.jpg
> >    :width: 100%  
> 
> The "target" option is intended for cases where you want to use an
> image as link like::
> 
>    .. image:: restructuredtext.svg
>       :alt: reStructuredText
>       :target: https://docutils.sourceforge.io/rst.html
>       

Yes. I did so for G2DN https://g2.doxu.org

https://journal.woodpeckersnest.eu/posts/2026-01-01-gnutella2-and-internet-publications/

https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/data/pages/posts/2026-01-01-gnutella2-and-internet-publications.rst

> You may also use it to get a standalone image or an image from a
> thumbnail In most cases, there is no need to repeat the image URI as
> "target".
> 

Thank you. I intend to do this.

> ...
> 
> > Mail `ha...@la... <mailto:ha...@la...>`_  
> 
> This could be simplified, as Docutils recognizes e-mail addresses as
> standalone hyperlinks (the telephone may also be simplified if you
> accept a slightly different link text).
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#standalone-hyperlinks
> 

I am not sure why you wrote it, so I hope that I answer to the correct
context.

For most links, I resort to element "atom:link" which is handled by the
software which handles Atom Syndication Format documents; in this case,
the XSLT stylesheet is a software which handles those links for me.

I did so with Hypercore and IPFS URIs.

https://journal.woodpeckersnest.eu/help/gemini/

https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/data/pages/help/gemini.rst

I further utilize that syntax in the content of a document, yet I am
lesser fond of that linking syntax, and I would be glad to have an
additional directive for links.

And considering XLink, I would be glad to have something of this sort,
even if XLink was not a concern.

.. link:: ed2k://|file|TrustedComputing_LAFKON_HIGH.mov|50834053|68D9B8032FCF0CA5A0515B65998F8376|/
:text: TrustedComputing_LAFKON_HIGH.mov
   :id: trusted-computing-link
   :class: ed2k-link
   :xlink: ed2k-trusted-computing

> 
> Günter
> 
> 

Regards,

Schimon

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

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

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

> I forgot to attach the reStructuredText file.
...

> .. authors: LAFKON Publishing ; mailto:ha...@la...
> .. category: journal
> .. comments: true
> .. date: 2004-09-09 0:00:00 UTC

...

There are actually 2 ways to specify meta-data in rST, so you don't need to
resort to comments:

a) bibliographic fields (for "visible" metadata)
   https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bibliographic-fields

   A "visible" document start could look like::

     a short animated video about computers and trust
     ------------------------------------------------
     
     :author: LAFKON Publishing <ha...@la...>
     :author: `LAFKON Publishing <mailto:ha...@la...>`__
     :abstract:
        This is a short animated video (3:30 minutes) about computers and trust.
        “Trusted Computing” - ever heard of it?
        This motion graphic style documentary explains what the term “trust” has in
        common with “Trusted Computing” and where you will meet this so-called
        technology in the near future.
        Computers and Internet gave you freedom. TCPA is designed against freedom!
        It is crucial that you listen to it.
     
     :date: 2004-09-09 0:00:00 UTC
     :slug: 2004-09-09-trusted-computing-2004
     :tags: control, computing, iot, lafkon, lagrande, 
     :type: text

b) the "meta" directive (for "invisible" metadata)
   https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata

   Example::
   
     .. meta::
        :authors: LAFKON Publishing <mailto:ha...@la...>
        :category: journal
        :comments: true
        :date: 2004-09-09 0:00:00 UTC
        :description:
        :slug: 2004-09-09-trusted-computing-2004
        :tags: control, computing, iot, lafkon, lagrande, 
        :type: text

Both can be combined.

...

> .. title: Trusted Computing (2004)

Besides the "visible" title (via first section)
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#document-title
there is also the "invisible" title via directive:
https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata-document-title

...

> .. image:: https://lafkon.net/work/trustedcomputing.jpg
>    :alt: Trusted Computing
>    :loading: lazy
>    :target: https://lafkon.net/work/trustedcomputing.jpg
>    :width: 100%

The "target" option is intended for cases where you want to use an image as
link like::

   .. image:: restructuredtext.svg
      :alt: reStructuredText
      :target: https://docutils.sourceforge.io/rst.html
      
You may also use it to get a standalone image or an image from a thumbnail
In most cases, there is no need to repeat the image URI as "target".

...

> Mail `ha...@la... <mailto:ha...@la...>`_

This could be simplified, as Docutils recognizes e-mail addresses as
standalone hyperlinks (the telephone may also be simplified if you accept a
slightly different link text).
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#standalone-hyperlinks


Günter

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

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

Guenter. Good night.

I am not yet familiar with Docutils Generic DTD.

Thank you for the references.

Please. Read the rest of the message further.

On Tue, 7 Oct 2025 18:41:51 -0000 (UTC)
Guenter Milde via Docutils-users <doc...@li...>
wrote:

> Dear Schimon,
> 
> On 2025-10-06, Schimon Jehudah via Docutils-users wrote:
> >> On 2025-09-28, Schimon Jehudah via Docutils-users wrote:  
> 
> >> > XLink might be helpful for both, Atom and (X)HTML, in order to
> >> > set accurate links to references.    
> 
> I don't think using XLink will give advantages to (X)HTML, as browser
> support is missing. (Except inside SVG, but even this is deprecated.)
> https://en.wikipedia.org/wiki/XLink#Implementations
> https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Attribute/xlink:href
> 

XLink is fine to them, for toying with SVG, because they fear that with
XLink people would migrate to PPN (P2P) systems instead of having those
spyware software that are referred to as "(spider) web browsers".

Please read the attached article by Mr. Hank Simon (September 29, 2000).

Source: http://intelligententerprise.com/000929/supplychain.shtml

I do not listen to them. They have also depectated RSS, both versions
of Microsummaries (Plain text and XML template addon), and they most
recently try to deprecate XSLT.

They have conspired to establish the so called "web extension" system
which, unlike XPCOM and XUL, has no support for TCP nor UDP and
therefore trying to censor FTP, Gemini, Gopher, IRC, SSH, and XMPP.

They are not an authority of anything, and I do not use those sso
called "internet browsers".

As far as am concerned, they terrorise us by trying to perpetuate
HTTP and centralized means, and they try to suppress FTP, Gemini
and Gopher, and also decentralized means such as eDonkey2000, Freenet
(Hyphanet), and Gnutella. They have been doing this for more than
twenty years.

https://digdeeper.neocities.org/articles/mozilla.xhtml#hydra

As brother Dr. Kent Hovind used to say about such people: They should
quit their "jobs" and switch tires or do something else useful.

> I don't know about Atom but it is not listed as a specification
> supporting XLink
> https://en.wikipedia.org/wiki/XLink#Within_other_specifications
> 

XML allows to mix elements and namespaces, so I suppose that it be
feasible, especially with the assistance of XSLT.

Also, XLink has no format of its own, and it is meant to be
incorporated into existing formats.

Read the attached article from Mr. Hank Simon.

> The Docutils Doctree documentation may gain a bit, when we could add a
> formal description of internal links (the "refid" and "refname"
> attributes) as an "xlink:href" with an XPath fragment specifier that
> for the "refid" value "my-id" would mean 'the element that contains
> "my-id" in the space-separated list of IDs that is the value of its
> "ids" attribute.'
> https://docutils.sourceforge.io/docs/ref/doctree.html#refid
> 
> ...
> 

I will explore this.

> >> Can you provide a **minimal** working example of what you want to
> >> achieve?  
> 
> > Yes. I can.  
> 
> > I am working on a publication platform of which all produced
> > documents are XML (Atom Syndication Format), and these documents
> > are transformed to XHTML with XSLT stylesheets.  
> 
> How do you produce the XML (Atom) documents? 
> With a custom Docutils writer or with XSLT from a standard output
> format?
> 

The system produces and Atom Syndication Format document, which
receives the XHTML data from Docutils; Docutils converts *only the
content* to XHTML.

The process can be observed at.
https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/publish/xhtml.py

Docutils conversion.
https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/utility/document.py

Atom formation.
https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/parser/atom.py

> > As this platform utilizes The Atom Syndication Format, there is
> > element "atom:link" which is almost identical to element "link" of
> > HTML.  
> 
> > The element "atom:link" is utilized to list related resources (i.e.
> > references) and attachments (i.e. enclosures).  
> 
> > I am interested to link to those links in a local fashion (i..e
> > utilizing the sign hash/number/pound (#), utilizing XSLT
> > directives.  
> 
> ...
> 
> I have only basic understanding of XML and a vague idea of XSLT so I
> cannot help with details. 
> 

I think that it would be nice for Docutils to have features for XML.

In this case, of utilizing Atom Syndication Format with XSLT, XSLT is
mostly an XHTML document with XPath directives to extract data from an
Atom document.

> I suppose it should be possible with XSLT to convert the "ids"
> attribute, https://docutils.sourceforge.io/docs/ref/doctree.html#ids,
> to an "id" attribute (maybe just discarding eventual "alias IDs" and
> keeping just the first ID), e.g. ::
> 
>     - <citation ids="elk-70" names="elk:70">
>     + <citation id="elk-70">
> 
> Then, a "refid" can be replaced by a "refuri" (or "href") attribute
> with simple fragment syntax::
> 
>     - <reference name="Elk:70" refid="elk-70">Elk:70</reference>
>     + <link href="#elk-70">Elk:70</link>
> 

I will explore Docutils Generic DTD and see what can be done.

Thank you for this vital information.

> 
> Günter
> 
> 

Best,

Schimon

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

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

Dear Schimon,

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

>> > XLink might be helpful for both, Atom and (X)HTML, in order to set
>> > accurate links to references.  

I don't think using XLink will give advantages to (X)HTML, as browser
support is missing. (Except inside SVG, but even this is deprecated.)
https://en.wikipedia.org/wiki/XLink#Implementations
https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Attribute/xlink:href

I don't know about Atom but it is not listed as a specification supporting
XLink https://en.wikipedia.org/wiki/XLink#Within_other_specifications


The Docutils Doctree documentation may gain a bit, when we could add a
formal description of internal links (the "refid" and "refname"
attributes) as an "xlink:href" with an XPath fragment specifier that for
the "refid" value "my-id" would mean 'the element that contains "my-id"
in the space-separated list of IDs that is the value of its "ids"
attribute.'
https://docutils.sourceforge.io/docs/ref/doctree.html#refid

...

>> Can you provide a **minimal** working example of what you want to
>> achieve?

> Yes. I can.

> I am working on a publication platform of which all produced documents
> are XML (Atom Syndication Format), and these documents are transformed
> to XHTML with XSLT stylesheets.

How do you produce the XML (Atom) documents? 
With a custom Docutils writer or with XSLT from a standard output format?

> As this platform utilizes The Atom Syndication Format, there is element
> "atom:link" which is almost identical to element "link" of HTML.

> The element "atom:link" is utilized to list related resources (i.e.
> references) and attachments (i.e. enclosures).

> I am interested to link to those links in a local fashion (i..e
> utilizing the sign hash/number/pound (#), utilizing XSLT directives.

...

I have only basic understanding of XML and a vague idea of XSLT so I cannot
help with details. 

I suppose it should be possible with XSLT to convert the "ids" attribute,
https://docutils.sourceforge.io/docs/ref/doctree.html#ids,
to an "id" attribute (maybe just discarding eventual "alias IDs" and
keeping just the first ID), e.g. ::

    - <citation ids="elk-70" names="elk:70">
    + <citation id="elk-70">

Then, a "refid" can be replaced by a "refuri" (or "href") attribute with
simple fragment syntax::

    - <reference name="Elk:70" refid="elk-70">Elk:70</reference>
    + <link href="#elk-70">Elk:70</link>


Günter

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

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

Greetings.

I forgot to attach the reStructuredText file.

Kindly,

Schimon

On Mon, 6 Oct 2025 14:40:08 +0300
Schimon Jehudah via Docutils-users
<doc...@li...> wrote:

> Guenter. Good afternoon.
> 
> Thank you for this information.
> 
> I have wrote the use-case at the end of this message.
> 
> On Tue, 30 Sep 2025 09:20:07 -0000 (UTC)
> Guenter Milde via Docutils-users
> <doc...@li...> wrote:
> 
> > Dear Schimon,
> > 
> > thank you for sharing your suggestions.
> > 
> > On 2025-09-28, Schimon Jehudah via Docutils-users wrote:
> > 
> > > This message is concerning to a feature which is not yet
> > > implemented.  
> > 
> > > https://docutils.sourceforge.io/docs/ref/rst/directives.html#references
> > >  
> > 
> > Mind, that the two unimplemented directives will only collect
> > <footnote> or <citation> elements at one place.
> > https://docutils.sourceforge.io/docs/dev/todo.html#footnote-citation-gathering
> > 
> > The reStructuredText syntax for `citation references`_ and
> > `citations`_ can be used to write documents including a
> > bibilography/references section or topic without need for a
> > "citations" directive, e.g. ::
> > 
> >     For details on brontosauruses, see [Elk:70]_.
> >   
> >     References
> >     ----------
> >   
> >     .. [Elk:70] `My Theory on Brontosauruses`,
> >                  Anne Elk, London, 1972.
> > 
> > ...
> > 
> > > XLink might be helpful for both, Atom and (X)HTML, in order to set
> > > accurate links to references.  
> > 
> > The <citation> <citation_reference> and <footnote>
> > <footnote_reference> Doctree elements already provide for a
> > bi-directional cross-link via the refname, refid, and backrefs
> > attributes. See
> > https://docutils.sourceforge.io/docs/ref/doctree.html#refname and
> > https://docutils.sourceforge.io/docs/ref/doctree.html#backrefs
> > 
> > The Docutils-XML output of the above example is::
> > 
> >     <!DOCTYPE document PUBLIC "+//IDN docutils.sourceforge.net//DTD
> > Docutils Generic//EN//XML"
> > "http://docutils.sourceforge.net/docs/ref/docutils.dtd"> <!--
> > Generated by Docutils 0.22.3b1.dev --> <document
> > source="/tmp/foo.rst"> <paragraph>For details on brontosauruses, see
> > <citation_reference ids="citation-reference-1"
> > refid="elk-70">Elk:70</citation_reference>.</paragraph> <section
> > ids="references" names="references"> <title>References</title>
> > <citation backrefs="citation-reference-1" ids="elk-70"
> > names="elk:70"> <label>Elk:70</label> <paragraph><title_reference>My
> > Theory on Brontosauruses</title_reference>, Anne Elk, London,
> > 1972.</paragraph> </citation> </section>
> >     </document>
> > 
> > 
> > > That publishing system (Rivista Voyager) is purely made of XML and
> > > XSLT, and it has no HTML nor XHTML files whatsoever; therefore I
> > > deem it important to consider and utilize XLink as a practical
> > > solution to XML, and (X)HTML.  
> > 
> > I am not sure what could be improved for the native Docutils-XML (or
> > XHTML) output by using XLink syntax.
> 
> I am unsure also. I am currently contemplating the idea.
> 
> > Can you provide a **minimal** working example of what you want to
> > achieve?
> > 
> 
> Yes. I can.
> 
> I am working on a publication platform of which all produced documents
> are XML (Atom Syndication Format), and these documents are transformed
> to XHTML with XSLT stylesheets.
> 
> As this platform utilizes The Atom Syndication Format, there is
> element "atom:link" which is almost identical to element "link" of
> HTML.
> 
> The element "atom:link" is utilized to list related resources (i.e.
> references) and attachments (i.e. enclosures).
> 
> I am interested to link to those links in a local fashion (i..e
> utilizing the sign hash/number/pound (#), utilizing XSLT directives.
> 
> I have attached a reStructuredText file, a produced Atom file, and a
> transformed HTML file, incliding an image of the section below the
> content of an article.
> 
> If you are interested at the XSLT stylesheets, this is the link.
> 
> https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/data/themes/vivista/xslt
> 
> > Thanks,
> > 
> > Günter
> > 
> 
> Best,
> 
> Schimon

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

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

Guenter. Good afternoon.

Thank you for this information.

I have wrote the use-case at the end of this message.

On Tue, 30 Sep 2025 09:20:07 -0000 (UTC)
Guenter Milde via Docutils-users <doc...@li...>
wrote:

> Dear Schimon,
> 
> thank you for sharing your suggestions.
> 
> On 2025-09-28, Schimon Jehudah via Docutils-users wrote:
> 
> > This message is concerning to a feature which is not yet
> > implemented.  
> 
> > https://docutils.sourceforge.io/docs/ref/rst/directives.html#references
> >  
> 
> Mind, that the two unimplemented directives will only collect
> <footnote> or <citation> elements at one place.
> https://docutils.sourceforge.io/docs/dev/todo.html#footnote-citation-gathering
> 
> The reStructuredText syntax for `citation references`_ and
> `citations`_ can be used to write documents including a
> bibilography/references section or topic without need for a
> "citations" directive, e.g. ::
> 
>     For details on brontosauruses, see [Elk:70]_.
>   
>     References
>     ----------
>   
>     .. [Elk:70] `My Theory on Brontosauruses`,
>                  Anne Elk, London, 1972.
> 
> ...
> 
> > XLink might be helpful for both, Atom and (X)HTML, in order to set
> > accurate links to references.  
> 
> The <citation> <citation_reference> and <footnote>
> <footnote_reference> Doctree elements already provide for a
> bi-directional cross-link via the refname, refid, and backrefs
> attributes. See
> https://docutils.sourceforge.io/docs/ref/doctree.html#refname and
> https://docutils.sourceforge.io/docs/ref/doctree.html#backrefs
> 
> The Docutils-XML output of the above example is::
> 
>     <!DOCTYPE document PUBLIC "+//IDN docutils.sourceforge.net//DTD
> Docutils Generic//EN//XML"
> "http://docutils.sourceforge.net/docs/ref/docutils.dtd"> <!--
> Generated by Docutils 0.22.3b1.dev --> <document
> source="/tmp/foo.rst"> <paragraph>For details on brontosauruses, see
> <citation_reference ids="citation-reference-1"
> refid="elk-70">Elk:70</citation_reference>.</paragraph> <section
> ids="references" names="references"> <title>References</title>
> <citation backrefs="citation-reference-1" ids="elk-70"
> names="elk:70"> <label>Elk:70</label> <paragraph><title_reference>My
> Theory on Brontosauruses</title_reference>, Anne Elk, London,
> 1972.</paragraph> </citation> </section>
>     </document>
> 
> 
> > That publishing system (Rivista Voyager) is purely made of XML and
> > XSLT, and it has no HTML nor XHTML files whatsoever; therefore I
> > deem it important to consider and utilize XLink as a practical
> > solution to XML, and (X)HTML.  
> 
> I am not sure what could be improved for the native Docutils-XML (or
> XHTML) output by using XLink syntax.

I am unsure also. I am currently contemplating the idea.

> Can you provide a **minimal** working example of what you want to
> achieve?
> 

Yes. I can.

I am working on a publication platform of which all produced documents
are XML (Atom Syndication Format), and these documents are transformed
to XHTML with XSLT stylesheets.

As this platform utilizes The Atom Syndication Format, there is element
"atom:link" which is almost identical to element "link" of HTML.

The element "atom:link" is utilized to list related resources (i.e.
references) and attachments (i.e. enclosures).

I am interested to link to those links in a local fashion (i..e
utilizing the sign hash/number/pound (#), utilizing XSLT directives.

I have attached a reStructuredText file, a produced Atom file, and a
transformed HTML file, incliding an image of the section below the
content of an article.

If you are interested at the XSLT stylesheets, this is the link.

https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/data/themes/vivista/xslt

> Thanks,
> 
> Günter
> 

Best,

Schimon

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

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

Dear Schimon,

thank you for sharing your suggestions.

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

> This message is concerning to a feature which is not yet implemented.

> https://docutils.sourceforge.io/docs/ref/rst/directives.html#references

Mind, that the two unimplemented directives will only collect <footnote>
or <citation> elements at one place.
https://docutils.sourceforge.io/docs/dev/todo.html#footnote-citation-gathering

The reStructuredText syntax for `citation references`_ and `citations`_
can be used to write documents including a bibilography/references
section or topic without need for a "citations" directive, e.g. ::

    For details on brontosauruses, see [Elk:70]_.
  
    References
    ----------
  
    .. [Elk:70] `My Theory on Brontosauruses`,
                 Anne Elk, London, 1972.

...

> XLink might be helpful for both, Atom and (X)HTML, in order to set
> accurate links to references.

The <citation> <citation_reference> and <footnote> <footnote_reference>
Doctree elements already provide for a bi-directional cross-link via the
refname, refid, and backrefs attributes.
See https://docutils.sourceforge.io/docs/ref/doctree.html#refname
and https://docutils.sourceforge.io/docs/ref/doctree.html#backrefs

The Docutils-XML output of the above example is::

    <!DOCTYPE document PUBLIC "+//IDN docutils.sourceforge.net//DTD Docutils Generic//EN//XML" "http://docutils.sourceforge.net/docs/ref/docutils.dtd">
    <!-- Generated by Docutils 0.22.3b1.dev -->
    <document source="/tmp/foo.rst">
        <paragraph>For details on brontosauruses, see <citation_reference ids="citation-reference-1" refid="elk-70">Elk:70</citation_reference>.</paragraph>
        <section ids="references" names="references">
            <title>References</title>
            <citation backrefs="citation-reference-1" ids="elk-70" names="elk:70">
                <label>Elk:70</label>
                <paragraph><title_reference>My Theory on Brontosauruses</title_reference>,
                    Anne Elk, London, 1972.</paragraph>
            </citation>
        </section>
    </document>


> That publishing system (Rivista Voyager) is purely made of XML and
> XSLT, and it has no HTML nor XHTML files whatsoever; therefore I deem
> it important to consider and utilize XLink as a practical solution to
> XML, and (X)HTML.

I am not sure what could be improved for the native Docutils-XML (or XHTML)
output by using XLink syntax.
Can you provide a **minimal** working example of what you want to achieve?

Thanks,

Günter

[Docutils-users] XLink as a solution for references

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

Good afternoon.

This message is concerning to a feature which is not yet implemented.

https://docutils.sourceforge.io/docs/ref/rst/directives.html#references

I am working on a publishing system which utilizes reStructuredText and
docutils.

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

https://journal.woodpeckersnest.eu/

The publishing system generates Atom Syndication Format documents, and
metadata elements "enclosures" and "related" are realized into
"atom:link" elements.

I have attached to this message a sample reStructuredText file, and an
Atom Syndication Format document.

XLink might be helpful for both, Atom and (X)HTML, in order to set
accurate links to references.

https://w3.org/TR/xlink/

https://manusimidt.dev/2021-05/what-is-xlink

That publishing system (Rivista Voyager) is purely made of XML and
XSLT, and it has no HTML nor XHTML files whatsoever; therefore I deem
it important to consider and utilize XLink as a practical solution to
XML, and (X)HTML.

Kind regards,
Schimon

[Docutils-users] release docutils 0.22.2

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

sorry for the high frequency

0.22.2 is a fix release for 0.22.1
minus one editor swap file that somehow broke a MacOS homebrew installation

otherwise nothing changed

sorry for any inconvenience
 e

[Docutils-users] docutils 0.22.1 is released

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

Good evening,

after a short test the 0.22.1 is released containing

* docutils/parsers/rst/states.py

 - Relax "section title" system messages from SEVERE to ERROR.
 - Fix behaviour with nested parsing into a detached node
   (cf. bugs #508 and #509).
 - New attribute `NestedStateMachine.parent_state_machine`.
   Use case: update the "current node" of parent state machine(s)
   after nested parsing.
 - Better error messages for grid table markup errors (bug #504),
   based on patch #214 by Jynn Nelson.

* docutils/transforms/references.py

 - Better error reports for hyperlinks with embedded URI or alias.

* docutils/writers/latex2e/__init__.py

 - Add cross-reference anchors (``\phantomsection\label{...}``)
   for elements with IDs (fixes bug #503).
 - Fix cross-reference anchor placement in figures, images,
   literal-blocks, tables, and (sub)titles.

all the best
 e

Re: [Docutils-users] query about literal inclusion with :literal: and :code:

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

Dear Alan,

On 2025-09-09, Alan wrote:

> I am happy that if I include code specifying :literal: as well as using
>:code: to specify the language that this suppresses the parsing for syntax
> highlighting, which I definitely do not want in this case. But it seems to
> me that I should still get the `code` and programming language classes set
> on the pre element and also to have the inclusion wrapped in a `code`
> element. Currently, the fact that I set :code: is apparently ignored (by
> the rst2html5 writer).

I am a bit lost regarding the details of your problem: is it about roles or
about directive arguments? Are you using ``:code:`` without specifying a
formal language? 

Please provide a working minimal example and clearly tell what you get and
what you want to get instead.

Günter

[Docutils-users] release candidate 0.22.1rc1 is out

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

Hei everyone,

0.22.1rc1 contains

* docutils/parsers/rst/states.py

 - Relax "section title" system messages from SEVERE to ERROR.
 - Fix behaviour with nested parsing into a detached node
   (cf. bugs #508 and #509).
 - New attribute `NestedStateMachine.parent_state_machine`.
   Use case: update the "current node" of parent state machine(s)
   after nested parsing.
 - Better error messages for grid table markup errors (bug #504),
   based on patch #214 by Jynn Nelson.

* docutils/writers/latex2e/__init__.py

 - Add cross-reference anchors (``\phantomsection\label{...}``)
   for elements with IDs (fixes bug #503).
 - Fix cross-reference anchor placement in figures, images,
   literal-blocks, tables, and (sub)titles.

and improvements (see https://docutils.sourceforge.io/HISTORY.html)

0.22.1 is planned for wednesday september 17
please test

cheers e

[Docutils-users] docutils release 0.22.1 release plan TWO

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

by popular demand a quicker release

friday sept 12 - 0.22.1rc1
wednesday 17 - 0.22.1

sorry for any inconvenience

[Docutils-users] docutils releas 0.22.1 release plan

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

Hei everyone,

the plan
-----------
0.22.1rc1 on tuesday  september 16
0.22.1      on tuesday september 23

if it works out fine


big thanks to Günter.for the work

the main changes/fixes are (from HISTORY.rst)

* docutils/parsers/rst/states.py

  - Relax "section title" system messages from SEVERE to ERROR.
  - Fix behaviour with nested parsing into a detached node
    (cf. bugs #508 and #509).
  - New attribute `NestedStateMachine.parent_state_machine`.
    Use case: update the "current node" of parent state machine(s)
    after nested parsing.
  - Better error messages for grid table markup errors (bug #504),
    based on patch #214 by Jynn Nelson.

* docutils/transforms/references.py

  - Better error reports for hyperlinks with embedded URI or alias.

* docutils/writers/latex2e/__init__.py

  - Add cross-reference anchors (``\phantomsection\label{...}``)
    for elements with IDs (fixes bug #503).
  - Fix cross-reference anchor placement in figures, images,
    literal-blocks, tables, and (sub)titles.

all the best
 e

[Docutils-users] query about literal inclusion with :literal: and :code:

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

I am happy that if I include code specifying :literal: as well as using
:code: to specify the language that this suppresses the parsing for syntax
highlighting, which I definitely do not want in this case. But it seems to
me that I should still get the `code` and programming language classes set
on the pre element and also to have the inclusion wrapped in a `code`
element. Currently, the fact that I set :code: is apparently ignored (by
the rst2html5 writer).

Thanks for considering this viewpoint,
Alan Isaac

Re: [Docutils-users] [SPAM] Re: [SPAM] Gemini and rst2gemtext

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

Dear Schimon,

On 2025-08-08, Schimon Jehudah via Docutils-users wrote:
> Of course, there is already  a discussion at SF.net.

> https://sourceforge.net/p/docutils/patches/200/

Mind, that this patch is about adding the "gemini:" scheme to the schemes
that are recognized in "standalone hyperlinks", i.e. not the addition of
another export format but a change to the reStructuredText specification
(a releated, but distinct topic).


Günter

Re: [Docutils-users] [SPAM] Gemini and rst2gemtext

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

Dear Schimon,

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

> Are there intentions to merge rst2gemtext into docutils?
...
> https://github.com/flozz/rst2gemtext/issues/9

Currently not.  I agree, that "gemtext" export is a useful addition to
Docutils, especially as both formats are "text centered" and try to stay
distraction free.  However, I am less sure merging is the best way forward
at the current stage.  

Instead, I propose to develop the project as an "independent
sister-project", using Docutils' plug-in architecture. 

This means generating a "gemtext" writer that can be used as

   docutils --writer=gemtext  mydoc.rst > mydoc.gemtext
   
as well as in the `Publisher Interface`__ provided by `docutils.core`
(https://docutils.sourceforge.io/docs/api/publisher.html).

In Docutils, we can provide cross-links in the Documentation similar to what
we already do for "markdown" parsers.
Not only in the "Docutils Link List", but also in, e.g., 
https://docutils.sourceforge.io/docs/user/config.html#docutils-application

Regards,  
Günter

[Docutils-users] [SPAM] Re: [SPAM] Gemini and rst2gemtext

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

Of course, there is already  a discussion at SF.net.

https://sourceforge.net/p/docutils/patches/200/

Schimon

On Fri, 8 Aug 2025 09:17:43 +0300
Schimon Jehudah via Docutils-users
<doc...@li...> wrote:

> Good day.
> 
> Are there intentions to merge rst2gemtext into docutils?
> 
> I think that it would be of at most useful to many people.
> 
> https://github.com/flozz/rst2gemtext/issues/9
> 
> Kind regards,
> Schimon
> 
> 
> _______________________________________________
> 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] Gemini and rst2gemtext

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

Good day.

Are there intentions to merge rst2gemtext into docutils?

I think that it would be of at most useful to many people.

https://github.com/flozz/rst2gemtext/issues/9

Kind regards,
Schimon

[Docutils-users] Release 0.22 (2026-07-29)

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

Good evening.

I suppose, that 2026 should be replaced by 2025.

https://docutils.sourceforge.io/HISTORY.html#toc-entry-2

Regards,
Schimon

Re: [Docutils-users] release 0.22

[Jeff M. <jmc...@ga...>]

minor change: the 0.22 release notes is tagged with the incorrect date: 
2026-07-29. ( 
https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-22-2026-07-29 )


-jeff



On 2025-07-29 1:22 p.m., engelbert gruber wrote:
> Hei everyone,
> 
> after one month of rc5
> 
> the final 0.22 is in the open
> sorry for the long wait
> 
> the Release consists of ... maybe see online https:// 
> docutils.sourceforge.io/0.22/RELEASE-NOTES.html <https:// 
> docutils.sourceforge.io/0.22/RELEASE-NOTES.html>
> 
> all the best and onto next
>   e
> 
> Release 0.22rc5 (2025-06-24)
> ============================
> 
> Targets generated from hyperlink references with embedded URI or alias
> are no longer "explicit" but "implicit" (i.e. with the same priority as
> auto-generated section targets, see `implicit hyperlink targets`__).
> 
> __ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html 
> <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html>
>     #implicit-hyperlink-targets
> 
> Don't report an error for duplicate targets with identical refname.
> 
> Release 0.22rc4 (2025-06-17)
> ============================
> 
> Drop the "name" option of the "target-notes" directive.
> (Report an error instead of silently ignoring the value.)
> 
> New alias "rst-class" for the `"class"`_ directive to improve the
> compatibility with Sphinx.
> 
> 
> Release 0.22rc3 (2025-06-10)
> ============================
> 
> New objects
>    `transforms.references.CitationReferences`
>       Mark citation_references as resolved if the backend
>       uses a BibTeX database.
> 
> Output changes
> 
>    manpage:
>       Do not drop text of internal targets.
> 
> 
> Release 0.22rc2 (2025-05-22)
> ============================
> 
> Fix backwards-compatibility problem:
>    reStructuredText section parsing no longer requires
>    `parsers.rst.states.RSTStateMachine.memo.section_parents`
>    (a cache introduced in Docutils 0.22rc1).
> 
> Deprecate `parsers.rst.states.Struct` (obsoleted by 
> `types.SimpleNamespace`).
> 
> 
> Release 0.22rc1 (2025-05-06)
> ============================
> 
> reStructuredText:
>    - Support `CSS3 units`_. This adds "ch", "rem", "vw", "vh", "vmin",
>      "vmax", and "Q" to the `supported length units`__. Note that some
>      output formats don't support all units.
>    - New option "figname" for the `"figure"`_ directive.
> 
>    .. _CSS3 units: https://www.w3.org/TR/css-values-3/#lengths <https:// 
> www.w3.org/TR/css-values-3/#lengths>
>    __ docs/ref/rst/restructuredtext.html#length-units
> 
> Document Tree / Docutils DTD
>    - Allow multiple <term> elements in a `\<definition_list_item>`__
>      (third-party writers may need adaption).
>    - The first element in a <figure> may also be a <reference>
>      (with nested "clickable" <image>).
> 
>    __ docs/ref/doctree.html#definition-list-item
> 
> Configuration changes
>    - Make MathML the default math_output_ for the "html5" writer.
>    - Change the default input_encoding_ from ``None`` (auto-detect) to 
> "utf-8".
>    - Drop short options ``-i`` and ``-o``.
>      Use the long equivalents ``--input-encoding`` and ``--output- 
> encoding``.
>      (See `command line interface`_ for the rationale.)
>    - Rename configuration setting "output" to "output_path_".
>    - New setting "validate_".
>    - The manpage writer now recognizes the sections [writers] and
>      [manpage writer] with the new setting `text_references`_.
> 
> Output changes
>    LaTeX:
>       Don't wrap references with custom reference_label_ in a ``\hyperref``
>       command. The "hyperref" package generates hyperlinks for labels by
>       default, so there is no change in the PDF
>       (except for the starred forms like ``reference_label = \ref*``).
> 
>       Stop requiring "ifthen.sty". Add "ifthen" to the stylesheet__ setting
>       or replace use of ``\ifthenelse{\isundefined...`` with the eTeX
>       primitive ``\ifdefined``.
> 
>       __ docs/user/config.html#stylesheet-2
> 
>    HTML5:
>       Unitless image_ size measures__ are written as <img> "width" and
>       "hight" values instead of "style" rules.  The current behaviour
>       is kept for values with units, so users may specify, e.g. ``:width:
>       50px`` instead of ``:width: 50`` to override CSS stylesheet rules.
> 
>       __ docs/ref/doctree.html#measure
> 
>    manpage:
>       Don't UPPERCASE section headings.
> 
>       Handle hyperlink references (see the text_references_ setting).
> 
>    null:
>       The "null" writer output changed from None to the empty string.
> 
>       `publish_string()` now returns a `bytes` or `str` instance
>       for all writers (as documented).
> 
> New objects
>    `parsers.docutils_xml`
>       parser for `Docutils XML`_ (e.g., the output of the "xml" writer).
>       Provisional.
> 
>       Try ``docutils --parser=xml test/data/multiple-term-definitions.xml``
>       or use the :parser: option of the `"include"`_ directive to include
>       an XML file in a rST document.
> 
>    `nodes.Element.validate()`
>       Raise `nodes.ValidationError` if the element does not comply with
>       the `Docutils Document Model`_.
>       Provisional.
> 
>    `writers.DoctreeTranslator`
>       Generic Docutils document tree translator base class with
>       `uri2path()` auxiliary method.
>       Provisional.
> 
> Removed objects
>    `core.Publisher.setup_option_parser()`
>       internal, obsolete,
>    `frontend.ConfigParser.get_section()`
>       obsoleted by the configparser's "Mapping Protocol Access",
>    `frontend.OptionParser.set_defaults_from_dict()`
>       obsolete,
>    `nodes.Element.set_class()`
>       obsolete, append to Element['classes'] directly,
>    `parsers.rst.directives.tables.CSVTable.decode_from_csv()`
>       not required with Python 3,
>    `parsers.rst.directives.tables.CSVTable.encode_from_csv()`
>       not required with Python 3,
>    `transforms.writer_aux.Compound`
>       not used since Dec 2010,
>    `utils.error_reporting`
>       obsolete in Python 3,
>    `utils.Reporter.set_conditions()`
>       obsolete, set attributes via configuration settings or directly.
> 
> Removed localisations
>    Mistranslations of the "admonition" directive name:
>       Use "advies" (af), "varsel" (da), "warnhinweis" (de), "aviso" (es),
>       "sciigo" (eo), "annonce" (fr), "avviso" (it), "advies" (nl),
>       "zauważenie" (pl) (introduced in Docutils 0.21)
>       or the English name "admonition".
> 
> New files
>    ``docutils/parsers/rst/include/html-roles.txt``
>       `Standard definition file`_ for additional roles matching HTML tags.
> 
> Removed files
>    ``tools/rst2odt_prepstyles.py``
>       Obsoleted by `writers.odf_odt.prepstyles`.
>    ``docutils/utils/roman.py``
>       Obsoleted by ``docutils/utils/_roman_numerals.py``
> 
> Bugfixes and improvements (see https://docutils.sourceforge.io/0.22/ 
> HISTORY.html <https://docutils.sourceforge.io/0.22/HISTORY.html>).
> 
> 
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
> 
> Please use "Reply All" to reply to the list.


-- 
Jeff McKenna
GatewayGeo: Developers of MS4W, & offering MapServer Consulting/Dev
co-founder of FOSS4G
http://gatewaygeo.com/

[Docutils-users] release 0.22

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

Hei everyone,

after one month of rc5

the final 0.22 is in the open
sorry for the long wait

the Release consists of ... maybe see online
https://docutils.sourceforge.io/0.22/RELEASE-NOTES.html

all the best and onto next
 e

Release 0.22rc5 (2025-06-24)
============================

Targets generated from hyperlink references with embedded URI or alias
are no longer "explicit" but "implicit" (i.e. with the same priority as
auto-generated section targets, see `implicit hyperlink targets`__).

__ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
   #implicit-hyperlink-targets

Don't report an error for duplicate targets with identical refname.

Release 0.22rc4 (2025-06-17)
============================

Drop the "name" option of the "target-notes" directive.
(Report an error instead of silently ignoring the value.)

New alias "rst-class" for the `"class"`_ directive to improve the
compatibility with Sphinx.


Release 0.22rc3 (2025-06-10)
============================

New objects
  `transforms.references.CitationReferences`
     Mark citation_references as resolved if the backend
     uses a BibTeX database.

Output changes

  manpage:
     Do not drop text of internal targets.


Release 0.22rc2 (2025-05-22)
============================

Fix backwards-compatibility problem:
  reStructuredText section parsing no longer requires
  `parsers.rst.states.RSTStateMachine.memo.section_parents`
  (a cache introduced in Docutils 0.22rc1).

Deprecate `parsers.rst.states.Struct` (obsoleted by
`types.SimpleNamespace`).


Release 0.22rc1 (2025-05-06)
============================

reStructuredText:
  - Support `CSS3 units`_. This adds "ch", "rem", "vw", "vh", "vmin",
    "vmax", and "Q" to the `supported length units`__. Note that some
    output formats don't support all units.
  - New option "figname" for the `"figure"`_ directive.

  .. _CSS3 units: https://www.w3.org/TR/css-values-3/#lengths
  __ docs/ref/rst/restructuredtext.html#length-units

Document Tree / Docutils DTD
  - Allow multiple <term> elements in a `\<definition_list_item>`__
    (third-party writers may need adaption).
  - The first element in a <figure> may also be a <reference>
    (with nested "clickable" <image>).

  __ docs/ref/doctree.html#definition-list-item

Configuration changes
  - Make MathML the default math_output_ for the "html5" writer.
  - Change the default input_encoding_ from ``None`` (auto-detect) to
"utf-8".
  - Drop short options ``-i`` and ``-o``.
    Use the long equivalents ``--input-encoding`` and ``--output-encoding``.
    (See `command line interface`_ for the rationale.)
  - Rename configuration setting "output" to "output_path_".
  - New setting "validate_".
  - The manpage writer now recognizes the sections [writers] and
    [manpage writer] with the new setting `text_references`_.

Output changes
  LaTeX:
     Don't wrap references with custom reference_label_ in a ``\hyperref``
     command. The "hyperref" package generates hyperlinks for labels by
     default, so there is no change in the PDF
     (except for the starred forms like ``reference_label = \ref*``).

     Stop requiring "ifthen.sty". Add "ifthen" to the stylesheet__ setting
     or replace use of ``\ifthenelse{\isundefined...`` with the eTeX
     primitive ``\ifdefined``.

     __ docs/user/config.html#stylesheet-2

  HTML5:
     Unitless image_ size measures__ are written as <img> "width" and
     "hight" values instead of "style" rules.  The current behaviour
     is kept for values with units, so users may specify, e.g. ``:width:
     50px`` instead of ``:width: 50`` to override CSS stylesheet rules.

     __ docs/ref/doctree.html#measure

  manpage:
     Don't UPPERCASE section headings.

     Handle hyperlink references (see the text_references_ setting).

  null:
     The "null" writer output changed from None to the empty string.

     `publish_string()` now returns a `bytes` or `str` instance
     for all writers (as documented).

New objects
  `parsers.docutils_xml`
     parser for `Docutils XML`_ (e.g., the output of the "xml" writer).
     Provisional.

     Try ``docutils --parser=xml test/data/multiple-term-definitions.xml``
     or use the :parser: option of the `"include"`_ directive to include
     an XML file in a rST document.

  `nodes.Element.validate()`
     Raise `nodes.ValidationError` if the element does not comply with
     the `Docutils Document Model`_.
     Provisional.

  `writers.DoctreeTranslator`
     Generic Docutils document tree translator base class with
     `uri2path()` auxiliary method.
     Provisional.

Removed objects
  `core.Publisher.setup_option_parser()`
     internal, obsolete,
  `frontend.ConfigParser.get_section()`
     obsoleted by the configparser's "Mapping Protocol Access",
  `frontend.OptionParser.set_defaults_from_dict()`
     obsolete,
  `nodes.Element.set_class()`
     obsolete, append to Element['classes'] directly,
  `parsers.rst.directives.tables.CSVTable.decode_from_csv()`
     not required with Python 3,
  `parsers.rst.directives.tables.CSVTable.encode_from_csv()`
     not required with Python 3,
  `transforms.writer_aux.Compound`
     not used since Dec 2010,
  `utils.error_reporting`
     obsolete in Python 3,
  `utils.Reporter.set_conditions()`
     obsolete, set attributes via configuration settings or directly.

Removed localisations
  Mistranslations of the "admonition" directive name:
     Use "advies" (af), "varsel" (da), "warnhinweis" (de), "aviso" (es),
     "sciigo" (eo), "annonce" (fr), "avviso" (it), "advies" (nl),
     "zauważenie" (pl) (introduced in Docutils 0.21)
     or the English name "admonition".

New files
  ``docutils/parsers/rst/include/html-roles.txt``
     `Standard definition file`_ for additional roles matching HTML tags.

Removed files
  ``tools/rst2odt_prepstyles.py``
     Obsoleted by `writers.odf_odt.prepstyles`.
  ``docutils/utils/roman.py``
     Obsoleted by ``docutils/utils/_roman_numerals.py``

Bugfixes and improvements (see
https://docutils.sourceforge.io/0.22/HISTORY.html).

[Docutils-users] [SPAM] Re: Setting element "span" instead of element "p"

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

Günter. Good afternoon.

On Mon, 28 Jul 2025 09:45:57 -0000 (UTC)
Guenter Milde via Docutils-users <doc...@li...>
wrote:

> On 2025-07-28, Schimon Jehudah wrote:
> > On Sun, 27 Jul 2025 Guenter Milde wrote:  
> >> On 2025-07-26, Schimon Jehudah wrote:  
> >> > On Sat, 26 Jul 2025 Guenter Milde wrote:    
> >> >> On 2025-07-25, Schimon Jehudah wrote:    
> 
> >> >> > Is it feasible to set the routine (i.e. default) element to
> >> >> > "span", or any other element, instead of element "p"?      
> 
> ...
> 
> >> This is something you may do in a custom HTML writer or as a
> >> post-processing with an XSLT stylesheet rule but it seems wrong for
> >> standard HTML output.  
> 
> > Yes. I can so that. I can process it again afterwards.  
> 
> 
> >> What is your problem with paragraphs? Is it about <p> in table
> >> cells, list items etc.?  
> 
> > Yes. I suppose, because I attach the output to an XSLT stylesheet,
> > as a part of customizing XSLT stylesheets and make them as usuable
> > as so called "template engines" (e.g. Jinja2).  
> 
> > This is the raw code of the XSLT stylesheet.  
> 
> ><nav id="xslt-navigation-bottom"/>  
> 
> > This is the processed code of the XSLT stylesheet.  
> 
> ><nav id="xslt-navigation-bottom">
> >  <p>
> >     <a class="reference external" href="/about" rel="noopener
> > noreferrer">About</a> <a class="reference external"
> > href="/about/rss" rel="noopener noreferrer">Atom</a> <a
> > class="reference external" href="/v" rel="noopener
> > noreferrer">V</a> <a class="reference external" href="/about/xmpp"
> > rel="noopener noreferrer">XMPP</a> <a class="reference external"
> > href="/help" rel="noopener noreferrer">Help</a> </p>
> ></nav>  
> 
> > The element "p" is not intended to be included.  
> 
> > https://journal.woodpeckersnest.eu/  
> 
> > So, I resorted to create a CSS rule.  
> 
> > nav p {
> >   all: unset;
> > }  
> 
> > https://journal.woodpeckersnest.eu/css/stylesheet.css  
> 
> > As you suggested, post-processing would be a good solution.  
> 
> This could be merged with the post processing to wrap text spans.
> After all, the output of Docutils HTML writers is valid XML but no
> XSLT ;)
> 

Of course. I only add that code as static code for XSLT, as a part of
its role as a templating engine.

> ...
> 
> >> Mind, that "xhtml" and "html5" are both aliases for the
> >> "html5_polyglot" writer. It produces HTML5 that is also valid XML.
> >> https://docutils.sourceforge.io/docs/user/html.html#html5  
> 
> >> For clarity and brevity, I prefer to call this writer "html5" and
> >> its output "HTML" or "HTML5".  
> 
> >> The term "XHTML" is a bit ambiguous, because the legacy
> >> `"html4css1" writer`__ (with aliases "html", "html4" and
> >> "xhtml10") produces `XHTML 1 Transitional`__.  
> 
> >> __ https://docutils.sourceforge.io/docs/user/html.html#html4css1
> >> __ https://www.w3.org/TR/xhtml1/  
> 
> 
> > Until recently, I have utilized "html".  
> 
> > I will try "xhtml10" also.  
> 
> Using the Docutils writer name "html" or "xhtml10" will make no
> difference, both refer to the legacy "html4css1" writer.
> 
> > I only need a valid XML output.  
> 
> Using the writer names "html5" or "xhtml" will also result in valid
> XML output. The difference is a more semantic output (more CSS styling
> instead of hard-coded layout) and better support for advanced features
> like SVG images, math formulas, and video images.
> 

I only need the HTML code, which are then embedded into XSLT
stylesheets.

https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/utility/rst.py

from docutils.core import publish_parts
html_content_str = publish_parts(source=rst_content_str,
                                 writer_name="xhtml")
html_content_str["fragment"]

> 
> Regards,
> 
> Günter
> 

Best,
Schimon

Re: [Docutils-users] Setting element "span" instead of element "p"

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

On 2025-07-28, Schimon Jehudah wrote:
> On Sun, 27 Jul 2025 Guenter Milde wrote:
>> On 2025-07-26, Schimon Jehudah wrote:
>> > On Sat, 26 Jul 2025 Guenter Milde wrote:  
>> >> On 2025-07-25, Schimon Jehudah wrote:  

>> >> > Is it feasible to set the routine (i.e. default) element to
>> >> > "span", or any other element, instead of element "p"?    

...

>> This is something you may do in a custom HTML writer or as a
>> post-processing with an XSLT stylesheet rule but it seems wrong for
>> standard HTML output.

> Yes. I can so that. I can process it again afterwards.


>> What is your problem with paragraphs? Is it about <p> in table cells,
>> list items etc.?

> Yes. I suppose, because I attach the output to an XSLT stylesheet, as
> a part of customizing XSLT stylesheets and make them as usuable as so
> called "template engines" (e.g. Jinja2).

> This is the raw code of the XSLT stylesheet.

><nav id="xslt-navigation-bottom"/>

> This is the processed code of the XSLT stylesheet.

><nav id="xslt-navigation-bottom">
>  <p>
>     <a class="reference external" href="/about" rel="noopener noreferrer">About</a>
>     <a class="reference external" href="/about/rss" rel="noopener noreferrer">Atom</a>
>     <a class="reference external" href="/v" rel="noopener noreferrer">V</a>
>     <a class="reference external" href="/about/xmpp" rel="noopener noreferrer">XMPP</a>
>     <a class="reference external" href="/help" rel="noopener noreferrer">Help</a>
>  </p>
></nav>

> The element "p" is not intended to be included.

> https://journal.woodpeckersnest.eu/

> So, I resorted to create a CSS rule.

> nav p {
>   all: unset;
> }

> https://journal.woodpeckersnest.eu/css/stylesheet.css

> As you suggested, post-processing would be a good solution.

This could be merged with the post processing to wrap text spans.
After all, the output of Docutils HTML writers is valid XML but no XSLT ;)

...

>> Mind, that "xhtml" and "html5" are both aliases for the
>> "html5_polyglot" writer. It produces HTML5 that is also valid XML.
>> https://docutils.sourceforge.io/docs/user/html.html#html5

>> For clarity and brevity, I prefer to call this writer "html5" and its
>> output "HTML" or "HTML5".

>> The term "XHTML" is a bit ambiguous, because the legacy `"html4css1"
>> writer`__ (with aliases "html", "html4" and "xhtml10") produces 
>> `XHTML 1 Transitional`__.

>> __ https://docutils.sourceforge.io/docs/user/html.html#html4css1
>> __ https://www.w3.org/TR/xhtml1/


> Until recently, I have utilized "html".

> I will try "xhtml10" also.

Using the Docutils writer name "html" or "xhtml10" will make no difference,
both refer to the legacy "html4css1" writer.

> I only need a valid XML output.

Using the writer names "html5" or "xhtml" will also result in valid XML
output. The difference is a more semantic output (more CSS styling
instead of hard-coded layout) and better support for advanced features
like SVG images, math formulas, and video images.


Regards,

Günter

[Docutils-users] [SPAM] Re: Setting element "span" instead of element "p"

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

Günter. Good day.

Thank you for your elaboration on this concern.

I have responded further.

On Sun, 27 Jul 2025 18:57:56 -0000 (UTC)
Guenter Milde via Docutils-users <doc...@li...>
wrote:

> Dear Schimon,
> 
> On 2025-07-26, Schimon Jehudah via Docutils-users wrote:
> > On Sat, 26 Jul 2025 08:06:50 -0000 (UTC)
> > Guenter Milde > wrote:  
> >> On 2025-07-25, Schimon Jehudah via Docutils-users wrote:  
> 
> >> > Is it feasible to set the routine (i.e. default) element to
> >> > "span", or any other element, instead of element "p"?    
> 
> >> Isn't this what XSLT is made for?  
> 
> > I meant, that the produced output of docutils utilizes the tag "p".
> >  
> 
> The Docutils HTML writers use the HTML tag <p> for native
> <pararagraph> elements, because both are the basic block-level
> elements.
> https://docutils.sourceforge.io/docs/ref/doctree.html#paragraph
> 
> Using a HTML <span> instead would mean using a HTML inline element
> for a native block element and prevent paragraph separation.
> This is something you may do in a custom HTML writer or as a
> post-processing with an XSLT stylesheet rule but it seems wrong for
> standard HTML output.
> 

Yes. I can so that. I can process it again afterwards.

> What is your problem with paragraphs? Is it about <p> in table cells,
> list items etc.?
> 

Yes. I suppose, because I attach the output to an XSLT stylesheet, ass
a part of customizing XSLT stylesheets and make them as usuable as so
called "template engines" (e.g. Jinja2).

This is the raw code of the XSLT stylesheet.

<nav id="xslt-navigation-bottom"/>

This is the processed code of the XSLT stylesheet.

<nav id="xslt-navigation-bottom">
  <p>
    <a class="reference external" href="/about" rel="noopener noreferrer">About</a>
    <a class="reference external" href="/about/rss" rel="noopener noreferrer">Atom</a>
    <a class="reference external" href="/v" rel="noopener noreferrer">V</a>
    <a class="reference external" href="/about/xmpp" rel="noopener noreferrer">XMPP</a>
    <a class="reference external" href="/help" rel="noopener noreferrer">Help</a>
  </p>
</nav>

The element "p" is not intended to be included.

https://journal.woodpeckersnest.eu/

So, I resorted to create a CSS rule.

nav p {
  all: unset;
}

https://journal.woodpeckersnest.eu/css/stylesheet.css

As you suggested, post-processing would be a good solution.

> 
> >> When processing Docutils output with XSLT, you may consider using
> >> Docutils native XML format as starting point. HTML is missing
> >> several features of Docutils documents (e.g. footnotes) that must
> >> be emulated. Starting from Docutils XML saves you from reverse
> >> engineering.  
> 
> >> See https://docutils.sourceforge.io/docs/ref/docutils.dtd
> >> and https://docutils.sourceforge.io/docs/ref/doctree.html.  
> 
> >> ::  
> 
> >>   from docutils.core import publish_string
> >>   publish_string(source="Text with link: https://example.org", 
> >>   		 writer_name="xml",
> >> 		 settings_overrides={"indents": True, 
> >> 		 		     "output_encoding":
> >> "unicode"})  
> 
> >> With the upcoming Docutils 0.22, you will be able to re-read the
> >> processed Docutils XML with the "xml" parser and export to all
> >> supported formats.  
> 
> 
> > This is done separately.  
> 
> > Docutils is utilized to convert reStructuredText to XHTML, and then
> > LXML is utilized to incorporate that output to XSLT.  
> 
> Does this mean you don't transform docutils output *with* some XSLT
> stylesheet but transform it *into* an XSLT template?
> 

Yes. Precisely, as I have detailed.

> 
> >> If you want HTML output from Docutils, you may consider the more
> >> modern "html5" writer.  Both, the "xhtml" writer and the "html5"
> >> writer emit HTML that is also valid XML. However the "xhtml" writer
> >> (an alias for "html4css1") is less semantic in its output. 
> >> (On the other hand, the "xhtml" writer is more stable, because it
> >> is mainly kept for backwards compatibility.)  
> 
> > I will try the option of XHTML.  
> 
> Mind, that "xhtml" and "html5" are both aliases for the
> "html5_polyglot" writer. It produces HTML5 that is also valid XML.
> https://docutils.sourceforge.io/docs/user/html.html#html5
> 
> For clarity and brevity, I prefer to call this writer "html5" and its
> output "HTML" or "HTML5".
> 
> The term "XHTML" is a bit ambiguous, because the legacy `"html4css1"
> writer`__ (with aliases "html", "html4" and "xhtml10") produces 
> `XHTML 1 Transitional`__.
> 
> __ https://docutils.sourceforge.io/docs/user/html.html#html4css1
> __ https://www.w3.org/TR/xhtml1/
> 

Until recently, I have utilized "html".

I will try "xhtml10" also.

I only need a valid XML output.

> 
> Regards,
> 
> Günter
> 
> 

Thank you,
Schimon