Use hyphens in URLs for accessibility and readability

[hugovk]

Summary of changes

I strongly recommend using hyphens in URLs rather than spaces:

• https://setuptools.readthedocs.io/en/latest/python-2-sunset.html
• https://setuptools.readthedocs.io/en/latest/python%202%20sunset.html

They make things harder for people using screen readers:

• https://accessiblewebsiteservices.com/accessible-file-naming-conventions/

Attached is the Android screen reader reading out each of these two URLs when selecting the address bar in Chrome.

screen-reader-urls.zip

• For the one with hyphens, it reads out the words and doesn't say "hyphen".

• For the one with spaces, it says "python percent 200 2 percent 20 sunset".

---

From #2134 (comment):

Acknowledged, but I prefer the spaces, especially as it appears nicely for users:

Too many systems avoid spaces in filenames, even though they're well supported in almost all environments. I plan to continue to break the convention of replacing spaces with some other character, as spaces have their purpose.

It doesn't actually appear nicer in my browser (Chrome 81, macOS Mojave and similar in Chrome on Android):

Nor Opera 68:

Firefox 76 is okay and shows the spaces:

Irrelevant for Safari, which only shows the domain:

---

This not only affects how the URL looks and sounds in the address bar, but also when pasted elsewhere, for example:

• https://setuptools.readthedocs.io/en/latest/python%202%20sunset.html

It can also cause difficulty for some when copying and pasting, and RFC 1738 on URLs declares spaces unsafe:

Unsafe:

Characters can be unsafe for a number of reasons. The space
character is unsafe because significant spaces may disappear and
insignificant spaces may be introduced when URLs are transcribed or
typeset or subjected to the treatment of word-processing programs.
The characters "<" and ">" are unsafe because they are used as the
delimiters around URLs in free text; the quote mark (""") is used to
delimit URLs in some systems. The character "#" is unsafe and should
always be encoded because it is used in World Wide Web and in other
systems to delimit a URL from a fragment/anchor identifier that might
follow it. The character "%" is unsafe because it is used for
encodings of other characters. Other characters are unsafe because
gateways and other transport agents are known to sometimes modify
such characters. These characters are "{", "}", "|", "", "^", "~",
"[", "]", and "`".

All unsafe characters must always be encoded within a URL. For
example, the character "#" must be encoded within URLs even in
systems that do not normally deal with fragment or anchor
identifiers, so that if the URL is copied into another system that
does use them, it will not be necessary to change the URL encoding.

Pull Request Checklist

• [n/a] Changes have tests
• [n/a] News fragment added in changelog.d. See documentation for details

[jaraco]

I was unaware of the accessibility issue. That does update my thinking on the matter.

Unfortunately, I've already set the URL in the bit.ly link, so changing this URL would also require changing the bit.ly link, which I don't think is worth the effort.

[pganssle]

@jaraco I think we can set it up in Sphinx to redirect python%202%20sunset.html to python-2-sunset.txt; here's a blog post on how to do it that I found on Google.

[jaraco]

I took a look at Edge. It also renders the URL-encoded form:

set it up in Sphinx to redirect

Thanks for the lead, Paul. I had searched for something similar, but come up empty-handed. I may even have read the reference you shared, but hadn't fully grokked what was involved. With these latest two commits, the file with spaces now redirects to the file with hyphens. You can see it in action.

I'm still a little reluctant to adopt this change. It feels like an awful lot of work to accommodate visually-impaired users of Python 2 who have Setuptools 47 or later. Surely, that's a use-case that can afford a bit of clumsiness.

All unsafe characters must always be encoded within a URL.

I don't think the RFC applies here. The characters are encoded, as specified by the RFC. They're just not honored by the Chrome and Reader UIs.

In my opinion, it's a shortcoming of Google Chrome and Android Screen Reader to improperly interpret the URL. By speaking the percent-encoded characters, it's exposing implementation details in a user-unfriendly way. I find it surprising it translates '-' to a space, but speaks a properly-encoded space as its url-encoded form. By accepting this PR, I'm endorsing or at least capitulating to the Chrome's space-hostile UI. I've fought against this hostility that comes dominantly from the Unix community.

Indeed, the more I think about it, I don't want to be complicit in this hostility, especially at the added maintenance burden it adds to the project.

I do appreciate the additional information and will be less capricious about spaces in filenames in the future, given the accessibility concerns.

[hugovk]

It's not just the Android Screen Reader, also Apple's VoiceOver on Mac, and I expect others too.

Actually, VoiceOver is worse, for some reason reads the second % as /:

• with hyphens: "python two sunset"
• with spaces: "python percent two hundred and two divided by twenty sunset"

---

And it's not only Chrome and Opera's address bars. The text above shows percents in Chrome and Firefox:

And Safari:

So screen readers will have difficulty reading such URLs pasted elsewhere too.

---

Anyway, thank you for considering it for future filenames!