#154 Introduce support for application schemes with addition of first one (Slack)

[Nicholas Williams]

Currently, Docutils is strictly confined to IANA/W3-recognized URI schemes when parsing URIs in (for example) ReStructuredText. However, as technologies continues to progress, this is becoming a limiting decision. It's impossible to create a link to something that has a commonly-recognized URI scheme but that isn't recognized by IANA/W3 as official schemes. This patch proposes to change that.

Take, for example, internal RST-based documentation for a project that includes contact information for the responsible team. If that contact information were a mailing list or email address, you could use the mailto:// scheme to provide a link to the reader to open the user's favored email client to start composing an email to the team, and Docutils would make that link clickable in the rendered documentation.

However, many (maybe most?) development teams don't use email anymore. A common communication technology employed today is Slack. Slack has a URI scheme (slack://) that is recognized by every major browser and by (at least) macOS, iOS, and Android that instructs that browser or OS to open the Slack client. Different paths and arguments in the URI can open a specific team, channel, and/or direct message—much more versatile than email. We would like to employ this in our documentation, providing handy links for contacting the responsible team on Slack. However, beacuse it's not an IANA/W3-recognized scheme, Docutils currently suppresses the link completely and, instead, renders just unclickable link text.

I would like to change this Docutils policy to include permitting well-recognized application URI schemes. I'm not suggesting opening the flood gates to any scheme that anyone wants to use (though that is certainly a plausible alternative that I would support), but rather continuing to whitelist schemes while opening it up to more than just IANA/W3-recognized schemes.

To that end, I have attached a diff that adds support for the Slack client URI scheme, and I respectfully submit it for consideration and inclusion in the next version of Docutils.

[Günter Milde]

Thank you for the suggestion and contribution.

However, it is actually possible to create a link to any string. The restriction to IANA/W3 official schemes only holds for recognition of standalone URIs:

This is a link_, an `inline link <slack://example2>`_ with embedded target
and an embedded link without link text `<slack://example3>`_.

.. _link: slack://example1

All of these can be made anonymous:

This link2__, the `inline link2 <slack://example5>`__ with embedded target
and the embedded link without link text `<slack://example6>`__.

__ slack://example4

The named links must have unique names and can be reused later:

This is again a link_, an `inline link`_ and a link to the embedded target
`slack://example3`_.

That said, although I never heard of slack and it is not recognized by my firefox browser, I can envisage an extension mechanism for automatic recognized URI schemes -- hower this should preferabely be done in an open way via a configuration setting.

[Nicholas Williams]

Indeed you are right. I was trying all of the above ^^, but my problem wasn't with Docutils. My problem was with the incomplete GitHub rendering. My actual beef is not with Docutils, but with GitHub. I'll file an issue with them. My apologies for wasting your time.