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