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

Re: [Docutils-users] comments vs. directives

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

Günter. Good afternoon.

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

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

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

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

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

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

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

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

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

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

Nevertheless, incorporating CSV is significantly better.

> Günter
> 

Schimon

Re: [Docutils-users] comments vs. directives

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

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

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

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

I would have chosen a different syntax.

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

Günter

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

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

Dear Schimon,

thanks for the new example.

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

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

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

...

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

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

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

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

Günter


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

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

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

...

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

Re: [Docutils-users] comments vs. directives

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

Günter. Good afternoon.

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

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

Now, I realize this.

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

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

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

Thank you.

> Günter

Schimon

Re: [Docutils-users] comments vs. directives

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

Guenter. Good day.

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

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

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

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


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

.. author:: My Lin

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


Schimon

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

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

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

> 
> Günter
> 
> 
> 
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
> 
> Please use "Reply All" to reply to the list.

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

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

Guenter. Good day.

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

Kindly,

Schimon

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

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

[Docutils-users] comments vs. directives

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

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


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

>> > How so?  

...

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

* create a file containing

    .. title: My simple example

    .. title:: My simple example

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

    .. author: My Lin

    .. author:: My Lin

* Optionally repeat with

    .. date: 2025-10-09

    .. date: 2025-10-09


Günter

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

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

Guenter. Good evening.

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

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

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

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

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

Yes. Indeed.

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

I will explore this.

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

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

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

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

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

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

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

> 
> Regards, 
> Günter
> 

Thank you very much!

Best,

Schimon.

[Docutils-users] Atom Syndication Format minimal example.

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

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

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

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

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

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

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

Günter

Re: [Docutils-users] Docutils standards

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

Dear Schimon,

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

> I want to conclude these realizations.

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

Docutils has no formal standards (RFCs or similar).

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

a) The `reStructuredText Markup Specification`__

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

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

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

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

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

is parsed into the XML elements::

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

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



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

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

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

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


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

This is my understanding of the power of XSLT:

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

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


Regards, 
Günter

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

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

Sorry, I forgot to add XSLT.

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

Schimon

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

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

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

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

Guenter. Good evening.

Please see a newly proposed diagram.

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

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

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

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

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

Schimon

[Docutils-users] Docutils standards

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

Guenter. Good evening.

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

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

I want to conclude these realizations.

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

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

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

Are these correct conclusions?

Kindly,
Schimon

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

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

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

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

Thank you for this comment. I will do so.

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

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

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

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

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

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

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

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

Nevertheless, I think that I realize your answer.

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

Thank you for this additional information.

I will act upon this in a few hours.

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

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

Is this fine to write this? (comma)

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

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

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


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

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

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

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

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

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

Atom-dict > Atom-XML

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

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

> * Atom > (XSLT) > HTML  
> 

This procedure is already done.

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

> 
> Günter
> 

Schimon

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

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

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

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

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

[Docutils-users] Converting reStructuredText to Atom Syndication Format

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

Good day.

As I am currently discussing with Mr. Guenter Milde about XLink and the
system of the publishing platform "Rivista Voyager" (CMS and SSG), I do
want to advise for Docutils to support The Atom Syndication Format.

The Atom Syndication Format is standard, and has the capabilities to
transfer the whole internet into an API oriented internet, by having
XML for publications instead of (broken) HTML.

This means, that documents that are conveyed as Atom Syndication Format
can be interacted with any device, as small as an OGG/MP3 Player which
has a software for parsing XML and HTML, and without the need for a
visual display screen monitor.

> It is important to state that because Rivista Voyager, as an
> ACE-compliant publication platform, is a machine-readable site, due
> to the predicted and structured form of The Atom Syndication Format,
> it is possible to interact and communicate with Rivitsa Voyager by
> audible directives and without a display screen monitor, utilizing
> portable devices with software such as eSpeak and Numen Voice Control.
> 
> -- A new hope for further internet federation via HTTP

Please read these resources.

https://journal.woodpeckersnest.eu/about/rivista/

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

gemini://woodpeckersnest.space/~schapps/journal/2025-07-29-announcing-ace.gmi

gemini://woodpeckersnest.space/~schapps/journal/2025-08-10-an-analyses-of-the-benefits-of-ace.gmi

gemini://woodpeckersnest.space/~schapps/journal/2025-10-08-a-hope-for-further-internet-federation-via-http.gmi

I have been experimenting with The Atom Syndication Format for a couple
of months or so, and I have managed to create a whole CMS site with
just Atom Syndication Format files, including forms and pages of
contact, comments, and search.

I urge you to examine the resulted documents of command "rivista-build"
(be sure to start "rivista-adjust" before that), and be inspired to
consider and add The Atom Syndication Format as an option of Docutils.

For Atom Syndication Format documents with navigation links, please
refer to these documents.

https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/data/pages/posts/1270-01-01-an-introduction-to-havamal.rst

https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/data/pages/posts/2024-08-01-establish-your-i2p-site-in-five-minutes.rst

The element "atom:link" is also utilized to realize resources of
reStructuredText bibliography and metadata.

Kind regards,
Schimon

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