docutils-users

[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

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

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

[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] 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] 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

[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

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

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

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 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-07, Schimon Jehudah via Docutils-users wrote:
> On Tue, 7 Oct 2025 18:41:51 -0000 (UTC)
> Guenter Milde via Docutils-users wrote:
>> 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.
...

> XLink is fine to them, for toying with SVG ...

Sorry for beeing ambiguous. My response was intended to mean:

  I don't think using XLink will give advantages to 
  *Docutils (X)HTML writers*, 
  as it XLink is not part of the various HTML standards 
  and browser support is missing.
  

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

As docutils.dtd is designed for extensibility, it should be easy
for interested parties to derive a custom document type with, e.g., 
a <link> element supporting XLink syntax.

  
Günter  

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

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

Thank you for your helpful respond.

Schimon

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

> On 2025-10-07, Schimon Jehudah via Docutils-users wrote:
> > On Tue, 7 Oct 2025 18:41:51 -0000 (UTC)
> > Guenter Milde via Docutils-users wrote:  
> >> 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.  
> ...
> 
> > XLink is fine to them, for toying with SVG ...  
> 
> Sorry for beeing ambiguous. My response was intended to mean:
> 
>   I don't think using XLink will give advantages to 
>   *Docutils (X)HTML writers*, 
>   as it XLink is not part of the various HTML standards 
>   and browser support is missing.
>   
> 
> > Also, XLink has no format of its own, and it is meant to be
> > incorporated into existing formats.  
> 
> As docutils.dtd is designed for extensibility, it should be easy
> for interested parties to derive a custom document type with, e.g., 
> a <link> element supporting XLink syntax.
> 
>   
> Günter  
> 

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

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

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

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

Then it may be cleaner to strip the preamble and feed Docutils only the
content. Currently, the preamble turns up as redundant comment in the output
bloating both, generated atom and HTML files.


> 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

What I am missing, is a user documentation.

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.


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

The easy way to get XHTML is using the "html4css1" or the "html5" writer.
Both generate HTML complying to the respective standards that is also
valid XML (polyglot HTML).

Regards,
Günter

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

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

Good afternoon.

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

> On 2025-10-07, Schimon Jehudah via Docutils-users wrote:
> 
> > > >> 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.  
> 
> Then it may be cleaner to strip the preamble and feed Docutils only
> the content. Currently, the preamble turns up as redundant comment in
> the output bloating both, generated atom and HTML files.
> 

Yes. So I noticed. I will explore a solution.

> 
> > 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
> >  
> 
> What I am missing, is a user documentation.
> 

There is no documentation yet. This software is subjected to further
development.

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

Do you mean that the use of multiple lines in which each semicolon
segregates "title" and "address" is not to be considered as standard?

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


> The easy way to get XHTML is using the "html4css1" or the "html5"
> writer. Both generate HTML complying to the respective standards that
> is also valid XML (polyglot HTML).
> 

Thank you.

> Regards,
> Günter
> 

Best,
Schimon

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

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

On 2025-10-08, Schimon Jehudah via Docutils-users wrote:
> On Tue, 7 Oct 2025 20:13:23 -0000 (UTC)
> Guenter Milde via Docutils-users 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  
...

> Rivista Voyager [...] stores metadata references in Atom
> Syndication Format elements, and XSLT is the only mean to transform
> Atom Syndication Format to XHTML.

You should decide, whether the preamble/metadata block should be parsed
as reStructuredText (rST) at all or be a different format (I strongly
recommend using an existing standard format). Then document this for
users.

If you decide to use rST for the metadata, you can split off the preamble
and parse it to Docutils-XML which then can be converted to Atom
Syndication Format with XSLT.

An alternative idea would be using "yaml", "toml", or some other human
readable data format as container, with only the content using rST.
(Then, the system might even support various content formats 
(rST, markdown, XHTML, ...).


...

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

I strongly recommend using an existing standard format.


>> ...

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

This is about the credit in the *content* (to be converted to HTML by
Docutils). Here, you can simply write

   Mail ha...@la...

and Docutils will turn this into an active "mailto" link. Similar for

   Phone tel:+48-816-555-1212

but not for gemini: (cf. https://sourceforge.net/p/docutils/patches/200/).

...

> 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

You are free to define and register a "link" directive in your project.
There is some documentation in
https://docutils.sourceforge.io/docs/howto/rst-directives.html
to get you started.
It helps to read the user reference of the standard directives
https://docutils.sourceforge.io/docs/ref/rst/directives.html especially
about "common options" and "common option value types" as to not
re-invent the wheel. (I'd recommend using the established directive options
:name: instead of :id: and :alt: instead of :text:).

Alternatively, use (in the rST content) some convention for rST, e.g. 

  .. class: ed2k-link
  .. trusted-computing-link:
  
  TrustedComputing_LAFKON_HIGH.mov (ed2k__, gnutella__, ...)
  
  __ ed2k://|file|TrustedComputing_LAFKON_HIGH.mov|50834053|68D9B8032FCF0CA5A0515B65998F8376|/
  __ gnutella://wherever
     

or define the targets outside of the (rST) content and use a URI reference
in the document like, e.g.

  Trusted Computing (ed2k__, gnutella__, ...)
  
  __ #ed2k-trusted-computing
  __ #gnutella-trusted-computing>`__

(this assumes that the final HTML document contains the targets
with the matching IDs).


Regards,

Günter

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

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

Greetings. Guenter.

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

> On 2025-10-08, Schimon Jehudah via Docutils-users wrote:
> > On Tue, 7 Oct 2025 20:13:23 -0000 (UTC)
> > Guenter Milde via Docutils-users 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    
> ...
> 
> > Rivista Voyager [...] stores metadata references in Atom
> > Syndication Format elements, and XSLT is the only mean to transform
> > Atom Syndication Format to XHTML.  
> 
> You should decide, whether the preamble/metadata block should be
> parsed as reStructuredText (rST) at all or be a different format (I
> strongly recommend using an existing standard format). Then document
> this for users.
> 
> If you decide to use rST for the metadata, you can split off the
> preamble and parse it to Docutils-XML which then can be converted to
> Atom Syndication Format with XSLT.
> 

Is there example code?

> An alternative idea would be using "yaml", "toml", or some other human
> readable data format as container, with only the content using rST.
> (Then, the system might even support various content formats 
> (rST, markdown, XHTML, ...).
> 

No. I am interested in utilizing only rST. It appears to be a perfect
format for documents, presentations, and internet pages.

> 
> ...
> 
> > Concerning to field "authors"; I have deliberately added semicolon
> > as it it easier to "split" title from address.  
> 
> I strongly recommend using an existing standard format.
> 

The purpose of Rivista Voyager is to only utilize standards.

I would appreciate example code for hte extraction of "title" and
"address".

Please see fields of the new version of that document.

Fields: "authors", "enclosures", "tags" (title and address),
"metalink", "related", and in file "xmpp.rst", see field
"microsummaries" and "tags" (some only have address).

> 
> >> ...  
> 
> >> > 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.  
> 
> This is about the credit in the *content* (to be converted to HTML by
> Docutils). Here, you can simply write
> 
>    Mail ha...@la...
> 
> and Docutils will turn this into an active "mailto" link. Similar for
> 
>    Phone tel:+48-816-555-1212
> 
> but not for gemini: (cf.
> https://sourceforge.net/p/docutils/patches/200/).
> 

If this is abount the preamble/metadata, then it is not a concern to
me, as I utilize element "atom:link" which data is automatically
realize to a hyperlink, even if it is eDonkey2000, Hypercore, et cetera.

> ...
> 
> > 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  
> 
> You are free to define and register a "link" directive in your
> project. There is some documentation in
> https://docutils.sourceforge.io/docs/howto/rst-directives.html
> to get you started.
> It helps to read the user reference of the standard directives
> https://docutils.sourceforge.io/docs/ref/rst/directives.html
> especially about "common options" and "common option value types" as
> to not re-invent the wheel. (I'd recommend using the established
> directive options :name: instead of :id: and :alt: instead of :text:).
> 
> Alternatively, use (in the rST content) some convention for rST, e.g. 
> 
>   .. class: ed2k-link
>   .. trusted-computing-link:
>   
>   TrustedComputing_LAFKON_HIGH.mov (ed2k__, gnutella__, ...)
>   
>   __
> ed2k://|file|TrustedComputing_LAFKON_HIGH.mov|50834053|68D9B8032FCF0CA5A0515B65998F8376|/
> __ gnutella://wherever 
> 
> or define the targets outside of the (rST) content and use a URI
> reference in the document like, e.g.
> 
>   Trusted Computing (ed2k__, gnutella__, ...)
>   
>   __ #ed2k-trusted-computing
>   __ #gnutella-trusted-computing>`__
> 
> (this assumes that the final HTML document contains the targets
> with the matching IDs).
> 

I will explore it.

> 
> Regards,
> 
> Günter
> 

Thank you,

Schimon

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

[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:
>> On 2025-10-08, Schimon Jehudah via Docutils-users wrote:
...

>> You should decide, whether the preamble/metadata block should be
>> parsed as reStructuredText (rST) at all or be a different format


>> If you decide to use rST for the metadata, you can split off the
>> preamble and parse it to Docutils-XML which then can be converted to
>> Atom Syndication Format with XSLT.

> Is there example code?

Not directly.

It also depends on how you would like to split the preamble from
the content

* with a pre-processor from the rST file
* after parsing, from the Python "doctree" object
* with XSLT from the Docutils-XML

>> An alternative idea would be using "yaml", [...]

> No. I am interested in utilizing only rST. It appears to be a perfect
> format for documents, presentations, and internet pages.


>> ...

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

>> I strongly recommend using an existing standard format.

> The purpose of Rivista Voyager is to only utilize standards.

...

> I would appreciate example code for hte extraction of "title" and
> "address".

> Please see fields of the new version of that document.

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)


...

> .. authors: Schimon Jehudah Zachary ; xmpp:sc...@pi...?message
> .. date: 2025-07-14 00:00:00 UTC
> .. description: Publishing client software for XMPP.
> .. link: xmpp
> .. microsummaries:
>    5 XMPP publishing client software ; projects
>    1 XMPP publishing client software ; desktop
>    4 XMPP publishing client software ; html
>    1 XMPP publishing client software ; mobile
...

If you convert the preamble to a rST bibliography::

  :authors: Schimon Jehudah Zachary ; xmpp:sc...@pi...?message
  :date: 2025-07-14 00:00:00 UTC
  :description: Publishing client software for XMPP.
  :link: ...

with a suitable rST construct instead of the non-standard ";",¹  
and run rst2xml on it, you see the XML representation.

How to extract/convert this to atom XML is left as exercise to the reader.

Regards,
Günter   


¹ In rST, the format for data entries is a "field list" or a description list.
  
  What to use depends on the context and may be discussed later on a
  *minimal* example with corresponding Atom element (one item at a time).
  

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

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

Guenter. Good evening.

On Thu, 9 Oct 2025 11:44:01 -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:  
> >> On 2025-10-08, Schimon Jehudah via Docutils-users wrote:  
> ...
> 
> >> You should decide, whether the preamble/metadata block should be
> >> parsed as reStructuredText (rST) at all or be a different format  
> 
> 
> >> If you decide to use rST for the metadata, you can split off the
> >> preamble and parse it to Docutils-XML which then can be converted
> >> to Atom Syndication Format with XSLT.  
> 
> > Is there example code?  
> 
> Not directly.
> 
> It also depends on how you would like to split the preamble from
> the content
> 
> * with a pre-processor from the rST file
> * after parsing, from the Python "doctree" object
> * with XSLT from the Docutils-XML
> 

Fine. So, I suppose, that it is for me to decide.

It is just that semicolons should not be utilized, but commas.

> >> An alternative idea would be using "yaml", [...]  
> 
> > No. I am interested in utilizing only rST. It appears to be a
> > perfect format for documents, presentations, and internet pages.  
> 
> 
> >> ...  
> 
> >> > Concerning to field "authors"; I have deliberately added
> >> > semicolon as it it easier to "split" title from address.  
> 
> >> I strongly recommend using an existing standard format.  
> 
> > The purpose of Rivista Voyager is to only utilize standards.  
> 
> ...
> 
> > I would appreciate example code for hte extraction of "title" and
> > "address".  
> 
> > Please see fields of the new version of that document.  
> 
> 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. Please read further at the end of this message.

Otherwise, I handle Atom Syndication Format by collecting rST
properties, and contents into a dictionary (i.e. "dict") which is then
delivered to function "ParserAtom.document" for further processing into
an Atom Syndication Format file.

> 
> ...
> 
> > .. authors: Schimon Jehudah Zachary ; xmpp:sc...@pi...?message
> > .. date: 2025-07-14 00:00:00 UTC
> > .. description: Publishing client software for XMPP.
> > .. link: xmpp
> > .. microsummaries:
> >    5 XMPP publishing client software ; projects
> >    1 XMPP publishing client software ; desktop
> >    4 XMPP publishing client software ; html
> >    1 XMPP publishing client software ; mobile  
> ...
> 
> If you convert the preamble to a rST bibliography::
> 
>   :authors: Schimon Jehudah Zachary ; xmpp:sc...@pi...?message
>   :date: 2025-07-14 00:00:00 UTC
>   :description: Publishing client software for XMPP.
>   :link: ...
> 
> with a suitable rST construct instead of the non-standard ";",¹  
> and run rst2xml on it, you see the XML representation.
> 

I think, that there is no difference to me, because it appears that the
output would be just the same with semicolon.

However, I will replace all instances of semicolon by comma, for the
sake of standards compliancy.

NOTE: It  means, that the system would have to reject attempts to
      incorporate commans into Microsummaries, Names and Titles.

This field.

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

Is realized to this code.

<comment xml:space="preserve">author:
BabylonObserver.com , https://babylonobserver.com
The Babylon Observer , mailto:in...@ba...</comment>

The same for field tags.

.. tags:
   Analyses, Currency, Economics, Finance, Fund, Garden, Industry,
   Metaphor, Mystery Paper, Power, World

<comment xml:space="preserve">tags:
Analyses, Currency, Economics, Finance, Fund, Garden, Industry,
Metaphor, Mystery Paper, Power, World</comment>

> How to extract/convert this to atom XML is left as exercise to the
> reader.
> 
> Regards,
> Günter   
> 
> 
> ¹ In rST, the format for data entries is a "field list" or a
> description list. 
>   What to use depends on the context and may be discussed later on a
>   *minimal* example with corresponding Atom element (one item at a
> time). 
> 

I think that I, now, realize what you mean.

If I correctly realize what you mean, by recommending to comply with
standards, then this is what I am intending to do.

I intend to remove fields that are not of The Atom Syndication Format,
such as "category", or rename other fields to comply with The Atom
Syndication Format, such as renaming "slug" to "id", "tags" to
"categories", "date" to "published", and add more fields such as
"updated".

However, fields "metalinks" and "microsummaries" are not part of The
Atom Syndication Format.

When you imply to correspond with standard, does it mean that you
advise to remove fields "metalinks" and "microsummaries" from rST and
utilize external files (e.g. TOML) to handle those custom fields?

Field "comments" is also not standard; it is a setting to enable
comments, so it would have to be removed also.

NOTE: The fields of "metalinks" and "microsummaries" are realized into
      element "atom:link", metalinks into rel="enclosure" and
      microsummaries into rel="microsummary".

Additionally, The Atom Syndication Format allows to be extended, but I
do not extend it. https://rfc-editor.org/rfc/rfc4287#section-6

Thinking of this further, I wonder whether I should replace fields
"enclosures" and "related" (both are realized as "atom:link") by field
"link", and add a new field for "rel".

.. links:
   Mystery Paper Documentary Series , https://babylonobserver.com/mystery-paper/, rel
   The Babylon Observer , https://babylonobserver.com, rel
   Mystery Paper – Episode 4 – The Decolonisation Show , /movies/Mystery.Paper.S01.E04.mkv, enclosure
   Recent episode: #4 – The Decolonisation Show , recent-episode , microsummary

As seen, this does not appear to allow me to selectively generate
Metalinks, so I would have to generate Metalinks to all local files,
I suppose. This is fine, yet this is when I would have to utilize a mean
which be external to rST (e.g. TOML).


Regards,

Schimon

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

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

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

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


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

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

¹ 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 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.
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
  
* XML-preamble + HTML-content (XSLT) > Atom-XML
  
* Atom > (XSLT) > HTML  


Günter

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

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

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

[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

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