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.

1 files changed, 12 insertions, 0 deletions

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