From d04701c0c4959d3c42587a4e1277bb517a2ea04b Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Mon, 25 Jul 2022 12:59:26 -0700 Subject: [PATCH] Note guideline for doc string expressions * doc/lispref/tips.texi (Documentation Tips): Mention \\=' and \\=` and say that expressions like (NAME TYPE RANGE) should not be quoted. --- doc/lispref/tips.texi | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index 30146a89ebf..d03698d354f 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -689,6 +689,18 @@ line. This looks nice in the source code, but looks bizarre when users view the documentation. Remember that the indentation before the starting double-quote is not part of the string! +@item +When documentation should display an ASCII apostrophe or grave accent, +use @samp{\\='} or @samp{\\=`} in the documentation string literal so +that the character is displayed as-is. + +@item +In documentation strings, do not quote expressions that are not Lisp symbols, +as these expressions can stand for themselves. For example, write +@samp{Return the list (NAME TYPE RANGE) ...}@: instead of +@samp{Return the list `(NAME TYPE RANGE)' ...}@: or +@samp{Return the list \\='(NAME TYPE RANGE) ...}. + @anchor{Docstring hyperlinks} @item @cindex curly quotes -- 2.39.2