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

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

Greetings.

I forgot to attach the reStructuredText file.

Kindly,

Schimon

On Mon, 6 Oct 2025 14:40:08 +0300
Schimon Jehudah via Docutils-users
<doc...@li...> wrote:

> 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