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