progit2
progit2 copied to clipboard
progit
Use clear link descriptions
There's no existing/similar bug report.
- [X] I have searched the existing issues
This report is about a single actionable bug.
- [X] I'm reporting a single actionable bug
This report is about the ProGit book, version 2, English language.
- [X] This bug is not about a translation or old version
Bug covers book website/pdf
- [X] I confirm the bug is about the book as found on the website/pdf
Problem is present in the Pro Git book on the website?
- [X] This bug also affects the Pro Git book as published on the website.
Which version of the book is affected?
Source files
Describe the bug:
I reviewed PR #1708 where there was a link that was styled like this (it's fixed now 😉 ):
It can be found at https://github.com/Microsoft/Git-Credential-Manager-for-Windows[].
This will cause screenreaders to read out the link like this:
https colon slash slash github dot com slash gitcredentialmanager slash git hypen credential hyphen manager hypen for hypen windows
Nobody is going to understand what a link like that points to. 😉
So we should use the [] part of the AsciiDoctor link to give a name to the link.
This way humans can understand where they'll end up if they click on the link.
To be more accessible we should use link names instead of leaving them empty.
Steps to reproduce:
Do a grep search on the link pattern to find all hits.
Expected behavior:
Links should have human readable names.
Screenshots:
No response
Additional context:
I recommend you also read the MDN Web Docs, use clear link wording, as they have more helpful advice on how links should be named.
Device
No response
Operating system
No response
Browser/application + version
No response
@vtbassmatt can you maybe provide the grep search that you did to find other links that follow this "bad pattern"? That would help us fix this problem easier. 😉
Sure, though it's far from perfect 😅 I use VS Code as my editor. With the repo open as my workspace, I used the Search icon on the left bar, in regex mode, with the following patterns:
http[^ ]*\[.+\]– finds instances of links which already have friendly nameshttp[^ ]*\[\]– finds instances of nameless links (but there are false positives too, as it makes no attempt to filter outinclude:s and so on)
