From: Ihor Radchenko <yantar92@gmail.com>
To: Paul Eggert <eggert@cs.ucla.edu>
Cc: emacs-orgmode@gnu.org
Subject: Re: [PROPOSED-PATCH] Fix doc string quoting problems with '
Date: Mon, 25 Jul 2022 16:50:51 +0800 [thread overview]
Message-ID: <87k081vams.fsf@localhost> (raw)
In-Reply-To: <20220724170720.46921-1-eggert@cs.ucla.edu>
Paul Eggert <eggert@cs.ucla.edu> 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
next prev parent reply other threads:[~2022-07-25 8:51 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-07-24 17:07 [PROPOSED-PATCH] Fix doc string quoting problems with ' Paul Eggert
2022-07-25 8:50 ` Ihor Radchenko [this message]
2022-07-25 20:14 ` Paul Eggert
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87k081vams.fsf@localhost \
--to=yantar92@gmail.com \
--cc=eggert@cs.ucla.edu \
--cc=emacs-orgmode@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.