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

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

Greetings. Guenter.

On Thu, 9 Oct 2025 09:54:59 -0000 (UTC)
Guenter Milde via Docutils-users <doc...@li...>
wrote:

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

Is there example code?

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

No. I am interested in utilizing only rST. It appears to be a perfect
format for documents, presentations, and internet pages.

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

The purpose of Rivista Voyager is to only utilize standards.

I would appreciate example code for hte extraction of "title" and
"address".

Please see fields of the new version of that document.

Fields: "authors", "enclosures", "tags" (title and address),
"metalink", "related", and in file "xmpp.rst", see field
"microsummaries" and "tags" (some only have address).

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

If this is abount the preamble/metadata, then it is not a concern to
me, as I utilize element "atom:link" which data is automatically
realize to a hyperlink, even if it is eDonkey2000, Hypercore, et cetera.

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

I will explore it.

> 
> Regards,
> 
> Günter
> 

Thank you,

Schimon