A short guide for getting the single quotes rendered as expected
(straight or curved) in Emacs Lisp function and variable documentation
This post is related to the curved quotes feature from Emacs 25
(September 2016), but I got inspired to write this as I was reading
the NEWS file of the recently released Emacs 28.1 ✨ .. this
specific part related to the
shortdoc library. Turns out that I had
If you also haven’t used this library before, it’s basically a “cheat
sheet generator” or an aggregator of related functions grouped
together with code examples and their outputs – for example,
functions related to string manipulation, buffer operations, etc. It
is like https://tldr.sh/ but for Emacs Lisp functions.
. So as I was reading through the help for various user-facing
C-h f shortdoc-add-function led me to
We don’t have curved quotes in Emacs Lisp syntax 🧐
.. So I look up the source of
The documentation looks correct at first glance, but there’s a minor problem. This post talks about how to fix that documentation and then a bit more on how to deal with auto-conversion to curved quotes.
Emacs 25 – Curved quotes rendering feature #
Emacs 25 had landed with one of my favorite new features — the
auto-rendering of grave accents (
`) and straight quotes (
curved (or curly) quotes (
’). From its
New variable ’text-quoting-style’ to control how Emacs translates quotes. Set it to ‘curve’ for curved single quotes, to ‘straight’ for straight apostrophes, and to ‘grave’ for grave accent and apostrophe. The default value nil acts like ‘curve’ if curved single quotes are displayable, and like ‘grave’ otherwise. The new variable affects display of diagnostics and help, but not of info. As the variable is not intended for casual use, it is not a user option.
I like the rendering to curved quotes because it improves the
readability of documentation strings in the ∗Help∗ buffers (
C-h f, etc.), and they look great in ∗Messages∗ buffer. It helps
differentiate between typographical use of quotes like in ‘Hello’
versus the straight quotes used in Emacs Lisp syntax like
(setq foo 'some-symbol) or the usage of
grave accents like
(setq foo `(,(+ 1 1))).
This feature renders grave accents (
‘ and straight quotes
’ by default. But there would be times when you would want
to literally print grave accents or straight quotes in ∗Help∗ and
Preventing curved quotes in documentation strings #
In documentation strings, some times you would want to show literal straight quotes or grave accents, for instance, when showing some example Emacs Lisp code snippets in there. Above image shows one of such examples.
More than the visual inaccuracy of seeing curved quoted where straight quotes should be, if someone copies that code to try it out, it will not work !
This should be fixed by escaping the
Emacs Lisp uses a special escaping sequence in documentation strings:
Below we see Code Snippet 1 after this fix:
.. and now the straight quotes get rendered as straight quotes:
Preventing curved quotes in messages #
The same auto-rendering of curved quotes happens in the messages that get printed to the ∗Messages∗ buffer and Echo Area as well. So the below behavior where ‘Hi’ gets printed is expected and nice:
(message "`Hi'") ;=> "‘Hi’"
But if someone does below, the rendered ’Hi’ looks pretty odd:
(message "'Hi'") ;=> "’Hi’"
I had come across this surprise rendering in Emacs 25 and had raised
this issue then. From Paul Eggert’s reply, I learned that to prevent
this curved quote conversion, we should make the
print the string processed by the
format function and not the string
directly. You could do this ..
(message "%s" (format "%s" "'Hi'")) ;=>"'Hi'"
But below will do the same thing and is much easier to type:
(message "%s" "'Hi'") ;=> "'Hi'" (message "%s" "`Hi'") ;=> "`Hi'"
|Render ||doc string snippet: |
|Render ||doc string snippet: |
By the way, I submitted a patch for fixing the escaping of straight
shortdoc-add-function documentation string
I planned to fix just this straight quote escaping issue, but then I
also ended up slightly improving the documentation of the
(FUNC :eval EVAL) and other forms used for adding a function’s documentation to
in debbugs # 54782 and now it’s in the emacs master branch! 🎉