diff options
Diffstat (limited to 'doc/lispref/tips.texi')
| -rw-r--r-- | doc/lispref/tips.texi | 25 |
1 files changed, 24 insertions, 1 deletions
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index eddbbfe8b90..3a1f6de12b2 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -252,6 +252,13 @@ themselves; Lisp programmers find this disconcerting. Please put a copyright notice and copying permission notice on the file if you distribute copies. @xref{Library Headers}. +@item +For variables holding (or functions returning) a file or directory name, +avoid using @code{path} in its name, preferring @code{file}, +@code{file-name}, or @code{directory} instead, since Emacs follows the +GNU convention to use the term @emph{path} only for search paths, +which are lists of directory names. + @end itemize @node Key Binding Conventions @@ -682,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 @@ -700,7 +719,11 @@ Note that when Emacs displays these doc strings, Emacs will usually display @samp{`} (grave accent) as @samp{‘} (left single quotation mark) and @samp{'} (apostrophe) as @samp{’} (right single quotation mark), if the display supports displaying these characters. -@xref{Keys in Documentation}. +@xref{Keys in Documentation}. (Some previous versions of this section +recommended using the non-@acronym{ASCII} single quotation marks +directly in doc strings, but this is now discouraged, since that leads +to broken help string displays on terminals that don't support +displaying those characters.) @cindex hyperlinks in documentation strings Help mode automatically creates a hyperlink when a documentation string |