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