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

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

On 2025-10-08, Schimon Jehudah via Docutils-users wrote:
> On Tue, 7 Oct 2025 20:13:23 -0000 (UTC)
> Guenter Milde via Docutils-users wrote:
>> On 2025-10-06, Schimon Jehudah via Docutils-users wrote:

>> > I forgot to attach the reStructuredText file.  
>> ...

>> > .. authors: LAFKON Publishing ; mailto:ha...@la...
>> > .. category: journal
>> > .. comments: true
>> > .. date: 2004-09-09 0:00:00 UTC  
...

> Rivista Voyager [...] stores metadata references in Atom
> Syndication Format elements, and XSLT is the only mean to transform
> Atom Syndication Format to XHTML.

You should decide, whether the preamble/metadata block should be parsed
as reStructuredText (rST) at all or be a different format (I strongly
recommend using an existing standard format). Then document this for
users.

If you decide to use rST for the metadata, you can split off the preamble
and parse it to Docutils-XML which then can be converted to Atom
Syndication Format with XSLT.

An alternative idea would be using "yaml", "toml", or some other human
readable data format as container, with only the content using rST.
(Then, the system might even support various content formats 
(rST, markdown, XHTML, ...).


...

> Concerning to field "authors"; I have deliberately added semicolon as
> it it easier to "split" title from address.

I strongly recommend using an existing standard format.


>> ...

>> > Mail `ha...@la... <mailto:ha...@la...>`_  

>> This could be simplified, as Docutils recognizes e-mail addresses as
>> standalone hyperlinks (the telephone may also be simplified if you
>> accept a slightly different link text).
>> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#standalone-hyperlinks


> I am not sure why you wrote it, so I hope that I answer to the correct
> context.

This is about the credit in the *content* (to be converted to HTML by
Docutils). Here, you can simply write

   Mail ha...@la...

and Docutils will turn this into an active "mailto" link. Similar for

   Phone tel:+48-816-555-1212

but not for gemini: (cf. https://sourceforge.net/p/docutils/patches/200/).

...

> I further utilize that syntax in the content of a document, yet I am
> lesser fond of that linking syntax, and I would be glad to have an
> additional directive for links.

> And considering XLink, I would be glad to have something of this sort,
> even if XLink was not a concern.

> .. link:: ed2k://|file|TrustedComputing_LAFKON_HIGH.mov|50834053|68D9B8032FCF0CA5A0515B65998F8376|/
>:text: TrustedComputing_LAFKON_HIGH.mov
>    :id: trusted-computing-link
>    :class: ed2k-link
>    :xlink: ed2k-trusted-computing

You are free to define and register a "link" directive in your project.
There is some documentation in
https://docutils.sourceforge.io/docs/howto/rst-directives.html
to get you started.
It helps to read the user reference of the standard directives
https://docutils.sourceforge.io/docs/ref/rst/directives.html especially
about "common options" and "common option value types" as to not
re-invent the wheel. (I'd recommend using the established directive options
:name: instead of :id: and :alt: instead of :text:).

Alternatively, use (in the rST content) some convention for rST, e.g. 

  .. class: ed2k-link
  .. trusted-computing-link:
  
  TrustedComputing_LAFKON_HIGH.mov (ed2k__, gnutella__, ...)
  
  __ ed2k://|file|TrustedComputing_LAFKON_HIGH.mov|50834053|68D9B8032FCF0CA5A0515B65998F8376|/
  __ gnutella://wherever
     

or define the targets outside of the (rST) content and use a URI reference
in the document like, e.g.

  Trusted Computing (ed2k__, gnutella__, ...)
  
  __ #ed2k-trusted-computing
  __ #gnutella-trusted-computing>`__

(this assumes that the final HTML document contains the targets
with the matching IDs).


Regards,

Günter