Arch Linux

Reported upstream https://gitlab.archlinux.org/archlinux/archmanweb/-/issues/31

MediaWiki's limitations do not make these URLs invalid. The links work perfectly fine when you click the heading on man.archlinux.org.

Technically, archmanweb uses the same encoding function [1] for the URL fragments as MediaWiki. See also the comparison table in [2].

[1] https://gitlab.archlinux.org/archlinux/archmanweb/-/blob/master/archmanweb/utils/encodings.py
[2] https://www.mediawiki.org/wiki/Manual:PAGENAMEE_encoding#Encodings_compared

Also note that links to manual pages from the wiki should be formatted using the man template [3]. To deal with square brackets, see how the link to "systemd.network(5) § [ROUTE] SECTION OPTIONS" is formatted in [4].

[3] https://wiki.archlinux.org/index.php/Template:Man
[4] https://wiki.archlinux.org/index.php/Systemd-networkd#Speeding_up_TCP_slow-start

Am I looking in the wrong place then?

If I look at RFC3986 at https://www.ietf.org/rfc/rfc3986.txt and how it defines URLs, it says:

sub-delims = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "="

pchar = unreserved / pct-encoded / sub-delims / ":" / "@"

fragment = *( pchar / "/" / "?" )

URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

Which I read as normal brackets don't need to be percent-encoded, but square-brackets do. Am I misunderstanding this?

That RFC deals only with ASCII so if everybody followed it to the letter, all Unicode non-ASCII symbols would have to be encoded, which would lead to very ugly URLs. MediaWiki has the "html5" encoding style for fragments specifically to avoid useless encoding of Unicode symbols. When it comes to brackets, it should be reported to MediaWiki, since our algorithm just matches their encoding. I don't know which RFC or whatever covers this, but notice that when you manually encode the brackets, it leads to the same resource: https://man.archlinux.org/man/systemd.network.5#%5BMATCH%5D_SECTION_OPTIONS

> I don't know which RFC or whatever covers this,

https://url.spec.whatwg.org/ is the relevant specification. [] aren't valid in the https://url.spec.whatwg.org/#url-fragment-string, but the parser doesn't care: https://url.spec.whatwg.org/#fragment-state.

According to https://url.spec.whatwg.org/#url-fragment-string, even spaces are not allowed in URL fragments, but they can be seen very often.

From the RFC3986, section 2.4. When to Encode or Decode:

> Under normal circumstances, the only time when octets within a URI
> are percent-encoded is during the process of producing the URI from
> its component parts. This is when an implementation determines which
> of the reserved characters are to be used as subcomponent delimiters
> and which can be safely used as data. Once produced, a URI is always
> in its percent-encoded form.

The encoding happens inside the browser when it takes the (un-encoded) URL and contacts the server. Specifically, it is not required of HTML documents to contain percent-encoded URLs (see e.g. the example in https://url.spec.whatwg.org/#query-encoding-example where the href contains even HTML entities). It depends on the browser if its "copy link URL" button gives you an encoded or unmodified URL, if it shows an encoded or decoded URL in the address bar, etc.

The reported issue seems to be only a MediaWiki limitation, so I'm inclined to close this as "not a bug".

It's a fair argument, if the spec allows it then it seems archmanweb is doing nothing wrong.

I suppose the question then becomes, should archmanweb be stubborn and make it difficult for people to link back to it just to make a point that other systems aren't following the spec properly, or should it encode the URLs even though it doesn't have to, to make it easier for people to share links to it?

I guess it depends on whether you want to promote the site and make it easy for people to reference, or whether you don't especially want people to post links to it.

FWIW it's not just the Arch Linux MediaWiki instance that won't accept these links, the Arch Linux forums won't accept them either. So I would argue that at least temporarily archmanweb should escape the links, at least until the rest of the Arch ecosystem correctly accepts the un-escaped URLs.

[Sorry for this noise, my browser just double-posted a comment...]

I've actually changed it differently [5]. The id attributes are left readable (unencoded), but the href attributes have the characters "[]|" percent-encoded, so the URLs that users will copy will be "compatible". Also the existing links with unencoded brackets should still work.

But as I said, man pages should be linked via a template [3] on the wiki. We've just improved it so that brackets do not have to be encoded manually [6].

[5] https://gitlab.archlinux.org/archlinux/archmanweb/-/commit/2e325ac6ba4300c608ca1af46f1fbaec9a440cda
[6] https://wiki.archlinux.org/index.php?title=Template:Man&diff=693490&oldid=648692