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

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Guenter. Good day.

On Tue, 7 Oct 2025 20:13:23 -0000 (UTC)
Guenter Milde via Docutils-users <doc...@li...>
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  
> 
> ...
> 
> There are actually 2 ways to specify meta-data in rST, so you don't
> need to resort to comments:
> 
> a) bibliographic fields (for "visible" metadata)
>    https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bibliographic-fields
> 
>    A "visible" document start could look like::
> 
>      a short animated video about computers and trust
>      ------------------------------------------------
>      
>      :author: LAFKON Publishing <ha...@la...>
>      :author: `LAFKON Publishing <mailto:ha...@la...>`__
>      :abstract:
>         This is a short animated video (3:30 minutes) about computers
> and trust. “Trusted Computing” - ever heard of it?
>         This motion graphic style documentary explains what the term
> “trust” has in common with “Trusted Computing” and where you will
> meet this so-called technology in the near future.
>         Computers and Internet gave you freedom. TCPA is designed
> against freedom! It is crucial that you listen to it.
>      
>      :date: 2004-09-09 0:00:00 UTC
>      :slug: 2004-09-09-trusted-computing-2004
>      :tags: control, computing, iot, lafkon, lagrande, 
>      :type: text
> 

This is interesting, and it might be helpful to me. Thank you.

> b) the "meta" directive (for "invisible" metadata)
>    https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata
> 
>    Example::
>    
>      .. meta::
>         :authors: LAFKON Publishing <mailto:ha...@la...>
>         :category: journal
>         :comments: true
>         :date: 2004-09-09 0:00:00 UTC
>         :description:
>         :slug: 2004-09-09-trusted-computing-2004
>         :tags: control, computing, iot, lafkon, lagrande, 
>         :type: text
> 
> Both can be combined.
> 

I did not know of it; yet, that is probably not useful for project
Rivista Voyager, because it stores metadata references in Atom
Syndication Format elements, and XSLT is the only mean to transform
Atom Syndication Format to XHTML.

Tags are placed inside element "atom:category", and XSLT stylesheet
extracts values of "atom"categories" to (X)HTML metadata.

<xsl:if test="atom:category">
  <xsl:element name="meta">
    <xsl:attribute name="name">
      <xsl:text>keywords</xsl:text>
    </xsl:attribute>
    <xsl:attribute name="content">
      <xsl:for-each select="atom:category">
        <xsl:value-of select="@term"/>
        <xsl:text>, </xsl:text>
      </xsl:for-each>
    </xsl:attribute>
  </xsl:element>
</xsl:if>

View the source code of these documents (XML and HTML).

This is Atom (XSLT: client-side)
https://journal.woodpeckersnest.eu/posts/2004-09-09-trusted-computing-2004/index.atom

This is HTML (XSLT: server-side)
https://journal.woodpeckersnest.eu/posts/2004-09-09-trusted-computing-2004/index.html

Additionally, as element "atom:category" provides attribute "label",
the reStructuredText tags field will be designed as.

.. tags:
   BitTorrent ; bittorrent
   eDonkey2000 ; ed2k
   Gnutella ; gnutella
   IPFS ; ipfs
   Linux ; linux
   MUTE; mute
   ReactOS ; reactos

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

.. authors: LAFKON Publishing ; mailto:ha...@la...

> ...
> 
> > .. title: Trusted Computing (2004)  
> 
> Besides the "visible" title (via first section)
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#document-title
> there is also the "invisible" title via directive:
> https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata-document-title
> 

I did not know of it. I will explore this concern.

> ...
> 
> > .. image:: https://lafkon.net/work/trustedcomputing.jpg
> >    :alt: Trusted Computing
> >    :loading: lazy
> >    :target: https://lafkon.net/work/trustedcomputing.jpg
> >    :width: 100%  
> 
> The "target" option is intended for cases where you want to use an
> image as link like::
> 
>    .. image:: restructuredtext.svg
>       :alt: reStructuredText
>       :target: https://docutils.sourceforge.io/rst.html
>       

Yes. I did so for G2DN https://g2.doxu.org

https://journal.woodpeckersnest.eu/posts/2026-01-01-gnutella2-and-internet-publications/

https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/data/pages/posts/2026-01-01-gnutella2-and-internet-publications.rst

> You may also use it to get a standalone image or an image from a
> thumbnail In most cases, there is no need to repeat the image URI as
> "target".
> 

Thank you. I intend to do this.

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

For most links, I resort to element "atom:link" which is handled by the
software which handles Atom Syndication Format documents; in this case,
the XSLT stylesheet is a software which handles those links for me.

I did so with Hypercore and IPFS URIs.

https://journal.woodpeckersnest.eu/help/gemini/

https://git.xmpp-it.net/sch/Rivista/src/branch/main/rivista/data/pages/help/gemini.rst

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.

> 
> Günter
> 
> 

Regards,

Schimon