emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed

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

  List information: https://www.orgmode.org/

* 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

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).