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

[Guenter M. <mi...@us...>]

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.


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

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.


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

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

Regards,
Günter