Paul Eggert <[email protected]> writes: > The Emacs doc string convention is to document values as-is when that > is clear, and surrounded by `single quotes' otherwise. For example, a > doc string "(a b c)" stands for a list of symbols, and the doc string > "`a'" stands for a single symbol. The doc string "\\=`a" is typically > not correct for that single symbol, because that is equivalent to > "(quote a)" and the typical intent is to talk about the symbol, not > about the Lisp quoting construct. One needs "\\=`X" only when talking > about something intended to be equivalent to "(quote X)", as in the > doc string "(provide \\='org-xyz)".
Thanks for the patch! The conventions sound reasonable, though I do not think that they are documented in D.6 Tips for Documentation Strings section of the Elisp manual. The patch looks good in general, however I am not sure if it is a good idea to change explicit 'symbol or '(...) mentions in the documentation of the defcustoms. In particular, when 'symbol is intended to be set as (setq variable 'symbol), I feel that 'symbol should be preferred over `symbol' - it will make life easier for users who can then just copy-paste the text from docstring. Also, note that references in the babel documentation are _not_ Elisp symbols - they are defined in #+name: name lines at the relevant src blocks. Finally, note that your patch does not apply after Kyle backported similar changes from Emacs master. Best, Ihor
