Some reStructuredText (rST) links broken in moin2.

[gmilde]

It seems like "simple" links to different Wiki pages fail in text parts written in rST:

Working examples: links with targed specified in rST (cf. https://moin-20.readthedocs.io/en/latest/user/rest.html#hyperlinks).

Links that work
=============

This is a `hyperlink with included target <WikiLink>`_.

This is a `hyperlink to an explicit target`_.

.. _hyperlink to an explicit target: WikiLink

This is an `anonymous hyperlink to an explicit target`_.

__ WikiLink

This is a link to an implicit target: `links that work`_.

All these links work in standard rST

Now the failing example: A link to a different WikiPage without explicit or embedded target. This works in the "old" MoinMoin but fails in Moin2:

Here is a link to a MoinMoin page named SecondPage_.

Details:

The reference would typically cause an unknown target error from the docutils parser. This is because there isn't a target in the document named "SecondPage". However, with the MoinMoin parser, the "SecondPage_" reference instead creates a link to a MoinMoin page named "SecondPage". — https://moinmo.in/HelpOnParsers/ReStructuredText section "Unknown Targets"

It seems that a part of the underlying code was transferred to moin2: see the visit_reference() function

However, this code is never reached, as Docutils checks for references without targets earlier (in a "transform") and creates a "system message" describing the problem (With Docutils and Sphinx, the system message is inserted into the output, in moin2 it seems to be shown in the log only.)

If continued support for simple WikiLinks_ is planned, moin2 would need to

• define a "resolver" function and register it in the "unknown_references_resolvers" hook,
• adapt the abovelinked visit_reference() function to the upcoming changes in Docutils DTD.

[gmilde]

The patch to future-proof the rst_in.py reStructured Text input converter:

--- /tmp/rst_in.py.bak	2025-05-07 21:43:33.229924365 +0200
+++ /tmp/rst_in.py	2025-05-07 21:47:23.746945103 +0200
@@ -582,7 +582,8 @@
             return
         if refuri == "":
             # build a link to a heading or an explicitly defined anchor
-            refuri = Iri(scheme="wiki.local", fragment=node.attributes["name"].replace(" ", "_"))
+            refname = nodes.whitespace_normalize_name(node.astext())
+            refuri = Iri(scheme="wiki.local", fragment=refname.replace(" ", "_"))
         if isinstance(refuri, str) and refuri.startswith("http"):
             if "://" not in refuri:
                 refuri = refuri.split(":")[1]

Rationale:

• The "name" attribute of the Docutils <reference> element will be removed.
• The "refname" attribute is case-normalized (downcased) but we need to preserve the case.

Therefore we re-create a "refname" without case normalization.

[UlrichB22]

@gmilde, do you want to create a PR with your solution? Does this fix the issue?

[gmilde]

I don't want to create a PR.

Does this fix the issue?

The suggested change is expected to solve point 2 of the issue:

• adapt the visit_reference() function to the upcoming changes in the Docutils DTD.

(I don't know how to test whether it works or how to road test reStructuredText markup constructs with the Moin wiki).

moin2 would still need to

• define a "resolver" function and register it in the "unknown_references_resolvers" hook,

[gmilde]

@UlrichB22 I managed to set up a "Test Wiki" and prepared a patch that solves both points of the issue. This is now PR #1921.

The following code was used in a sample page in interactive testing:

rST test page
=============

.. _first Paragraph:

This is my first pure *rST* page. [#]_

.. _second Section:

§ With % strange & siLLY <title>
--------------------------------

.. [#] with the MoinMoin wiki.

External Links
--------------

Here is a link to a `Wiki & 
page`_ (the URI is determined from its text by the :code:`wiki_reference_resolver()`)
and a link to the title_ (with explicit target refering to a URI reference).

Internal Links
--------------

Implicit targets
''''''''''''''''

A link to the `§ With % strange & siLLY \<title>`_

This link to the `§ with % 
strange & silly \<title>`_ contains a newline and no uppercase.

An `indirect link to the page title`__.


Explicit targets
''''''''''''''''

An indirect link to the `text Start`_, the `first paragraph`_ 
and a link to the explicit target representing the `second section`_.

`First paragraph`_ -- a capitalized link works, too.

__ `rST test page`_

.. _title: #rST_test_page
.. _text start: `First Paragraph`_

.. sectnum:

[UlrichB22]

@gmilde, can we close this issue? Are there any important points still open?

Thanks for your support.

[gmilde]

Patch #1935 only fixed the "Wiki links". The fix for internal cross-links to section headings is still missing (cf. the example in https://github.com/moinwiki/moin/issues/1680#issuecomment-2895130846). I'll prepare a new PR.

[gmilde]

Still missing

• inline internal targets
• IDs of elements specified via the "names" directive option

Paragraph with _`inline target`.

.. note::
   :name: my note

   Admonitions can be targets if they use the :name: option.

.. image:: help-common/logo.svg
   :alt: the MoinMoin logo
   :name: moin logo

Links to the `inline target`_ and `my note`_ and the `moin logo`_.

Requires change to the handling of <target> elements.

Suggestion: handle IDs and targets similar to the Docutils HTML writer:

• Convert "inline targets" to generic inline elements with "id" attribute.
• Ignore "body" targets (already handled by Docutils transforms, but kept for reference).
• For all elements, convert the first ID (from the list in the "ids" attribute) to an ID.
• generate empty <spans> or similar for additional IDs (aliases).

This is a considerable change, so I would appreciate feedback from the main developers before starting to code.

[UlrichB22]

Since this only affects rST documents, I don't see any difficulties. Thanks for your assistance.