GitHub-rendered readme is "Style dispatchers" section is misleading/hard to read
axelson opened this issue · comments
The "Style dispatchers" shows a formatting error:
This is how I would expect that section to be rendered (I've entered it in markdown since that's what GitHub issues supports):
!
makes the rest of the component match using
orderless-without-literal
, that is, both!bad
andbad!
will match
strings that do /not/ contain the substringbad
.,
usesorderless-initialism
.=
usesorderless-literal
.~
usesorderless-flex
.%
makes the string match ignoring diacritics and similar
inflections on characters (it uses the functionchar-fold-to-regexp
to do this).
When I first read this I thought it meant that you type ===
as the prefix to use orderless-literal
which was incorrect.
I'm not sure if this is an issue with the org-mode rendering or with GitHub's interpretation of it.
GitHub's org mode parser doesn't seem to correctly support either =verbatim=
or ~code~
syntax. For all but one of those characters one of the two syntaxes does work (but both should work!), and for comma, neither syntax works. These render correctly in Emacs org mode buffers, of course, and it also renders correctly in the primary documentation: the Orderless info manual. Maybe for the sake of GitHub users I can just not use markup for these characters. (Although it feels a little wrong that I should use semantically incorrect markup to work around a bug in a closed-source commercial product, when Org and Info work just fine.)
I decided to just remove the markup to work around the GitHub bug.
That works. Thanks!