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

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

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.
Can you provide a **minimal** working example of what you want to achieve?

Thanks,

Günter