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

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

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

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.

...

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

...

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

...

> 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


Günter