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