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