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

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

Guenter. Good afternoon.

Thank you for this information.

I have wrote the use-case at the end of this message.

On Tue, 30 Sep 2025 09:20:07 -0000 (UTC)
Guenter Milde via Docutils-users <doc...@li...>
wrote:

> Dear Schimon,
> 
> thank you for sharing your suggestions.
> 
> On 2025-09-28, Schimon Jehudah via Docutils-users wrote:
> 
> > This message is concerning to a feature which is not yet
> > implemented.  
> 
> > https://docutils.sourceforge.io/docs/ref/rst/directives.html#references
> >  
> 
> Mind, that the two unimplemented directives will only collect
> <footnote> or <citation> elements at one place.
> https://docutils.sourceforge.io/docs/dev/todo.html#footnote-citation-gathering
> 
> The reStructuredText syntax for `citation references`_ and
> `citations`_ can be used to write documents including a
> bibilography/references section or topic without need for a
> "citations" directive, e.g. ::
> 
>     For details on brontosauruses, see [Elk:70]_.
>   
>     References
>     ----------
>   
>     .. [Elk:70] `My Theory on Brontosauruses`,
>                  Anne Elk, London, 1972.
> 
> ...
> 
> > XLink might be helpful for both, Atom and (X)HTML, in order to set
> > accurate links to references.  
> 
> The <citation> <citation_reference> and <footnote>
> <footnote_reference> Doctree elements already provide for a
> bi-directional cross-link via the refname, refid, and backrefs
> attributes. See
> https://docutils.sourceforge.io/docs/ref/doctree.html#refname and
> https://docutils.sourceforge.io/docs/ref/doctree.html#backrefs
> 
> The Docutils-XML output of the above example is::
> 
>     <!DOCTYPE document PUBLIC "+//IDN docutils.sourceforge.net//DTD
> Docutils Generic//EN//XML"
> "http://docutils.sourceforge.net/docs/ref/docutils.dtd"> <!--
> Generated by Docutils 0.22.3b1.dev --> <document
> source="/tmp/foo.rst"> <paragraph>For details on brontosauruses, see
> <citation_reference ids="citation-reference-1"
> refid="elk-70">Elk:70</citation_reference>.</paragraph> <section
> ids="references" names="references"> <title>References</title>
> <citation backrefs="citation-reference-1" ids="elk-70"
> names="elk:70"> <label>Elk:70</label> <paragraph><title_reference>My
> Theory on Brontosauruses</title_reference>, Anne Elk, London,
> 1972.</paragraph> </citation> </section>
>     </document>
> 
> 
> > That publishing system (Rivista Voyager) is purely made of XML and
> > XSLT, and it has no HTML nor XHTML files whatsoever; therefore I
> > deem it important to consider and utilize XLink as a practical
> > solution to XML, and (X)HTML.  
> 
> I am not sure what could be improved for the native Docutils-XML (or
> XHTML) output by using XLink syntax.

I am unsure also. I am currently contemplating the idea.

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

As this platform utilizes The Atom Syndication Format, there is element
"atom:link" which is almost identical to element "link" of HTML.

The element "atom:link" is utilized to list related resources (i.e.
references) and attachments (i.e. enclosures).

I am interested to link to those links in a local fashion (i..e
utilizing the sign hash/number/pound (#), utilizing XSLT directives.

I have attached a reStructuredText file, a produced Atom file, and a
transformed HTML file, incliding an image of the section below the
content of an article.

If you are interested at the XSLT stylesheets, this is the link.

https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/data/themes/vivista/xslt

> Thanks,
> 
> Günter
> 

Best,

Schimon