Re: [Docutils-users] XLink as a solution for references

[Schimon J. <sc...@fe...>]

Good afternoon.

On Thu, 9 Oct 2025 08:53:15 -0000 (UTC)
Guenter Milde via Docutils-users <doc...@li...>
wrote:

> On 2025-10-07, Schimon Jehudah via Docutils-users wrote:
> 
> > > >> Can you provide a **minimal** working example of what you want
> > > >> to achieve?    
> > >   
> > > > Yes. I can.    
> > >   
> > > > I am working on a publication platform of which all produced
> > > > documents are XML (Atom Syndication Format), and these documents
> > > > are transformed to XHTML with XSLT stylesheets.    
> > > 
> > > How do you produce the XML (Atom) documents? 
> > > With a custom Docutils writer or with XSLT from a standard output
> > > format?  
> 
> > The system produces and Atom Syndication Format document, which
> > receives the XHTML data from Docutils; Docutils converts *only the
> > content* to XHTML.  
> 
> Then it may be cleaner to strip the preamble and feed Docutils only
> the content. Currently, the preamble turns up as redundant comment in
> the output bloating both, generated atom and HTML files.
> 

Yes. So I noticed. I will explore a solution.

> 
> > The process can be observed at.
> > https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/publish/xhtml.py
> >  
> 
> > Docutils conversion.
> > https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/utility/document.py
> >  
> 
> > Atom formation.
> > https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/parser/atom.py
> >  
> 
> What I am missing, is a user documentation.
> 

There is no documentation yet. This software is subjected to further
development.

> 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?

Do you mean that the use of multiple lines in which each semicolon
segregates "title" and "address" is not to be considered as standard?

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


> The easy way to get XHTML is using the "html4css1" or the "html5"
> writer. Both generate HTML complying to the respective standards that
> is also valid XML (polyglot HTML).
> 

Thank you.

> Regards,
> Günter
> 

Best,
Schimon