* [PROPOSED-PATCH] Fix doc string quoting problems with '
@ 2022-07-24 17:07 Paul Eggert
2022-07-25 8:50 ` Ihor Radchenko
0 siblings, 1 reply; 3+ messages in thread
From: Paul Eggert @ 2022-07-24 17:07 UTC (permalink / raw)
To: emacs-orgmode; +Cc: Paul Eggert
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)".
---
lisp/ob-core.el | 6 +++---
lisp/ob-julia.el | 8 ++++----
lisp/ob-table.el | 4 ++--
lisp/org-agenda.el | 16 ++++++++--------
lisp/org-attach-git.el | 2 +-
lisp/org-capture.el | 4 ++--
lisp/org-faces.el | 2 +-
lisp/org-fold-core.el | 6 +++---
lisp/org-macs.el | 2 +-
lisp/org-plot.el | 2 +-
lisp/org-src.el | 2 +-
lisp/org-table.el | 2 +-
lisp/org.el | 2 +-
lisp/ox.el | 12 ++++++------
14 files changed, 35 insertions(+), 35 deletions(-)
diff --git a/lisp/ob-core.el b/lisp/ob-core.el
index ac9af5d24..945adf3a4 100644
--- a/lisp/ob-core.el
+++ b/lisp/ob-core.el
@@ -487,7 +487,7 @@ evaluates to a string.
A closure is evaluated when the source block is being
evaluated (e.g. during execution or export), with point at the
source block. It is not possible to use an arbitrary function
-symbol (e.g. \\='some-func), since org uses lexical binding. To
+symbol (e.g. `some-func'), since org uses lexical binding. To
achieve the same functionality, call the function within a
closure (e.g. (lambda () (some-func))).
@@ -514,7 +514,7 @@ functionality is also supported for default header arguments by
providing the header argument multiple times in the alist. For
example:
-\\='((:var . \"foo=\\\"bar\\\"\")
+ ((:var . \"foo=\\\"bar\\\"\")
(:var . \"bar=\\\"foo\\\"\"))")
(put 'org-babel-default-header-args 'safe-local-variable
@@ -2627,7 +2627,7 @@ in the buffer."
If the `default-directory' is different from the containing
file's directory then expand relative links.
-If the optional TYPE is passed as \\='attachment and the path is a
+If the optional TYPE is passed as `attachment' and the path is a
descendant of the DEFAULT-DIRECTORY, the generated link will be
specified as an an \"attachment:\" style link."
(when (stringp result)
diff --git a/lisp/ob-julia.el b/lisp/ob-julia.el
index cb65b0310..7f25fafad 100644
--- a/lisp/ob-julia.el
+++ b/lisp/ob-julia.el
@@ -250,8 +250,8 @@ end")
(defun org-babel-julia-evaluate-external-process
(body result-type result-params column-names-p)
"Evaluate BODY in external julia process.
-If RESULT-TYPE equals \\='output then return standard output as a
-string. If RESULT-TYPE equals \\='value then return the value of the
+If RESULT-TYPE equals `output' then return standard output as a
+string. If RESULT-TYPE equals `value' then return the value of the
last statement in BODY, as elisp."
(cl-case result-type
(value
@@ -274,8 +274,8 @@ last statement in BODY, as elisp."
(defun org-babel-julia-evaluate-session
(session body result-type result-params column-names-p)
"Evaluate BODY in SESSION.
-If RESULT-TYPE equals \\='output then return standard output as a
-string. If RESULT-TYPE equals \\='value then return the value of the
+If RESULT-TYPE equals `output' then return standard output as a
+string. If RESULT-TYPE equals `value' then return the value of the
last statement in BODY, as elisp."
(cl-case result-type
(value
diff --git a/lisp/ob-table.el b/lisp/ob-table.el
index bafc81a1a..1c17db4cc 100644
--- a/lisp/ob-table.el
+++ b/lisp/ob-table.el
@@ -83,8 +83,8 @@ is the equivalent of the following source code block:
results
#+end_src
-NOTE: The quotation marks around the function name,
-\\='source-block\\=', are optional.
+NOTE: The quotation marks around the function name
+`source-block' are optional.
NOTE: By default, string variable names are interpreted as
references to source-code blocks, to force interpretation of a
diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el
index ace76729f..8e5f229e5 100644
--- a/lisp/org-agenda.el
+++ b/lisp/org-agenda.el
@@ -1646,7 +1646,7 @@ alpha-down Sort headlines alphabetically, reversed.
The different possibilities will be tried in sequence, and testing stops
if one comparison returns a \"not-equal\". For example, the default
- \\='(time-up category-keep priority-down)
+ (time-up category-keep priority-down)
means: Pull out all entries having a specified time of day and sort them,
in order to make a time schedule for the current day the first thing in the
agenda listing for the day. Of the entries without a time indication, keep
@@ -2111,7 +2111,7 @@ the lower-case version of all tags."
"Alist of characters and custom functions for bulk actions.
For example, this value makes those two functions available:
- \\='((?R set-category)
+ ((?R set-category)
(?C bulk-cut))
With selected entries in an agenda buffer, `B R' will call
@@ -2123,7 +2123,7 @@ used for each call to your bulk custom function. The argument
collecting function will be run once and should return a list of
arguments to pass to the bulk function. For example:
- \\='((?R set-category get-category))
+ ((?R set-category get-category))
Now, `B R' will call the custom `get-category' which would prompt
the user once for a category. That category is then passed as an
@@ -2732,7 +2732,7 @@ For example, if you have a custom agenda command \"p\" and you
want this command to be accessible only from plain text files,
use this:
- \\='((\"p\" ((in-file . \"\\\\.txt\\\\'\"))))
+ ((\"p\" ((in-file . \"\\\\.txt\\\\'\"))))
Here are the available contexts definitions:
@@ -2750,7 +2750,7 @@ accessible if there is at least one valid check.
You can also bind a key to another agenda custom command
depending on contextual rules.
- \\='((\"p\" \"q\" ((in-file . \"\\\\.txt\\\\'\"))))
+ ((\"p\" \"q\" ((in-file . \"\\\\.txt\\\\'\"))))
Here it means: in .txt files, use \"p\" as the key for the
agenda command otherwise associated with \"q\". (The command
@@ -4156,7 +4156,7 @@ dimming them." ;FIXME: The arg isn't used, actually!
If the header at `org-hd-marker' is blocked according to
`org-entry-blocked-p', then if `org-agenda-dim-blocked-tasks' is
-\\='invisible and the header is not blocked by checkboxes, set the
+`invisible' and the header is not blocked by checkboxes, set the
text property `org-todo-blocked' to `invisible', otherwise set it
to t."
(when (get-text-property 0 'todo-state entry)
@@ -7877,7 +7877,7 @@ Argument ARG is the prefix argument."
When in a restricted subtree, remove it.
The restriction will span over the entire file if TYPE is `file',
-or if type is \\='(4), or if the cursor is before the first headline
+or if type is (4), or if the cursor is before the first headline
in the file. Otherwise, only apply the restriction to the current
subtree."
(interactive "P")
@@ -11304,7 +11304,7 @@ argument: an entry from `org-agenda-get-day-entries'.
FILTER can also be an alist with the car of each cell being
either `headline' or `category'. For example:
- \\='((headline \"IMPORTANT\")
+ ((headline \"IMPORTANT\")
(category \"Work\"))
will only add headlines containing IMPORTANT or headlines
diff --git a/lisp/org-attach-git.el b/lisp/org-attach-git.el
index ddb2ee97a..c838686b3 100644
--- a/lisp/org-attach-git.el
+++ b/lisp/org-attach-git.el
@@ -43,7 +43,7 @@
(defcustom org-attach-git-annex-auto-get 'ask
"Confirmation preference for automatically getting annex files.
-If \\='ask, prompt using `y-or-n-p'. If t, always get. If nil, never get."
+If `ask', prompt using `y-or-n-p'. If t, always get. If nil, never get."
:group 'org-attach
:package-version '(Org . "9.0")
:version "26.1"
diff --git a/lisp/org-capture.el b/lisp/org-capture.el
index 8748b7f84..f0a07b269 100644
--- a/lisp/org-capture.el
+++ b/lisp/org-capture.el
@@ -560,7 +560,7 @@ For example, if you have a capture template \"c\" and you want
this template to be accessible only from `message-mode' buffers,
use this:
- \\='((\"c\" ((in-mode . \"message-mode\"))))
+ ((\"c\" ((in-mode . \"message-mode\"))))
Here are the available contexts definitions:
@@ -578,7 +578,7 @@ accessible if there is at least one valid check.
You can also bind a key to another capture template depending on
contextual rules.
- \\='((\"c\" \"d\" ((in-mode . \"message-mode\"))))
+ ((\"c\" \"d\" ((in-mode . \"message-mode\"))))
Here it means: in `message-mode buffers', use \"c\" as the
key for the capture template otherwise associated with \"d\".
diff --git a/lisp/org-faces.el b/lisp/org-faces.el
index 3095dd5a4..a3db35f12 100644
--- a/lisp/org-faces.el
+++ b/lisp/org-faces.el
@@ -597,7 +597,7 @@ See also `org-agenda-deadline-faces'.")
(0.0 . org-upcoming-distant-deadline))
"Faces for showing deadlines in the agenda.
This is a list of cons cells. The cdr of each cell is a face to be used,
-and it can also just be like \\='(:foreground \"yellow\").
+and it can also just be like (:foreground \"yellow\").
Each car is a fraction of the head-warning time that must have passed for
this the face in the cdr to be used for display. The numbers must be
given in descending order. The head-warning time is normally taken
diff --git a/lisp/org-fold-core.el b/lisp/org-fold-core.el
index 3fcacb975..322840ed0 100644
--- a/lisp/org-fold-core.el
+++ b/lisp/org-fold-core.el
@@ -382,7 +382,7 @@ The following properties are known:
using isearch.
- :isearch-open :: non-nil means that isearch can reveal text hidden
using this spec. This property does nothing
- when \\='isearch-ignore property is non-nil.
+ when `isearch-ignore' property is non-nil.
- :front-sticky :: non-nil means that text prepended to the folded text
is automatically folded.
- :rear-sticky :: non-nil means that text appended to the folded text
@@ -709,7 +709,7 @@ The folding spec properties will be set to PROPERTIES (see
SPEC must be a symbol.
BUFFER can be a buffer to remove SPEC in, nil to remove SPEC in current
-buffer, or \\='all to remove SPEC in all open `org-mode' buffers and all
+buffer, or `all' to remove SPEC in all open `org-mode' buffers and all
future org buffers."
(org-fold-core--check-spec spec)
(when (eq buffer 'all)
@@ -778,7 +778,7 @@ If SPEC-OR-ALIAS is a folding spec, only check the given folding spec."
Return nil if there is no folding at point or POM.
If SPEC-OR-ALIAS is nil, return a folding spec with highest priority
among present at `point' or POM.
-If SPEC-OR-ALIAS is \\='all, return the list of all present folding
+If SPEC-OR-ALIAS is `all', return the list of all present folding
specs.
If SPEC-OR-ALIAS is a valid folding spec or a spec alias, return the
corresponding folding spec (if the text is folded using that spec)."
diff --git a/lisp/org-macs.el b/lisp/org-macs.el
index 5931dd260..1dc0b7080 100644
--- a/lisp/org-macs.el
+++ b/lisp/org-macs.el
@@ -522,7 +522,7 @@ is selected, only the bare key is returned."
For example, in this alist:
\(org-uniquify-alist \\='((a 1) (b 2) (a 3)))
- => \\='((a 1 3) (b 2))
+ => ((a 1 3) (b 2))
merge (a 1) and (a 3) into (a 1 3).
diff --git a/lisp/org-plot.el b/lisp/org-plot.el
index 3928da7d8..0fcedbc99 100644
--- a/lisp/org-plot.el
+++ b/lisp/org-plot.el
@@ -280,7 +280,7 @@ When NORMALISE is non-nil, the count is divided by the number of values."
collect (cons n (/ (length m) normaliser)))))
(defun org--plot/prime-factors (value)
- "Return the prime decomposition of VALUE, e.g. for 12, \\='(3 2 2)."
+ "Return the prime decomposition of VALUE, e.g. for 12, (3 2 2)."
(let ((factors '(1)) (i 1))
(while (/= 1 value)
(setq i (1+ i))
diff --git a/lisp/org-src.el b/lisp/org-src.el
index b691817a7..767a8485c 100644
--- a/lisp/org-src.el
+++ b/lisp/org-src.el
@@ -234,7 +234,7 @@ For instance, the following value would color the background of
emacs-lisp source blocks and python source blocks in purple and
green, respectability.
- \\='((\"emacs-lisp\" (:background \"#EEE2FF\"))
+ ((\"emacs-lisp\" (:background \"#EEE2FF\"))
(\"python\" (:background \"#e5ffb8\")))"
:group 'org-edit-structure
:type '(repeat (list (string :tag "language")
diff --git a/lisp/org-table.el b/lisp/org-table.el
index e9d6c5a9f..a5a550812 100644
--- a/lisp/org-table.el
+++ b/lisp/org-table.el
@@ -5462,7 +5462,7 @@ The table is taken from the parameter TXT, or from the buffer at point."
(nreverse table)))))
(defun org-table-collapse-header (table &optional separator max-header-lines)
- "Collapse the lines before \\='hline into a single header.
+ "Collapse the lines before `hline' into a single header.
The given TABLE is a list of lists as returned by `org-table-to-lisp'.
The leading lines before the first `hline' symbol are considered
diff --git a/lisp/org.el b/lisp/org.el
index 61a21115f..8454f776c 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -3457,7 +3457,7 @@ lines to the buffer:
(defcustom org-hidden-keywords nil
"List of symbols corresponding to keywords to be hidden in the Org buffer.
-For example, a value \\='(title) for this list makes the document's title
+For example, a value (title) for this list makes the document's title
appear in the buffer without the initial \"#+TITLE:\" part."
:group 'org-appearance
:package-version '(Org . "9.5")
diff --git a/lisp/ox.el b/lisp/ox.el
index 8223940fb..5ba436743 100644
--- a/lisp/ox.el
+++ b/lisp/ox.el
@@ -872,7 +872,7 @@ This option can also be set with the OPTIONS keyword, e.g.,
This variable allows providing shortcuts for export snippets.
-For example, with a value of \\='((\"h\" . \"html\")), the
+For example, with a value of ((\"h\" . \"html\")), the
HTML back-end will recognize the contents of \"@@h:<b>@@\" as
HTML code while every other back-end will ignore it."
:group 'org-export-general
@@ -1182,7 +1182,7 @@ keywords are understood:
Menu entry for the export dispatcher. It should be a list
like:
- \\='(KEY DESCRIPTION-OR-ORDINAL ACTION-OR-MENU)
+ (KEY DESCRIPTION-OR-ORDINAL ACTION-OR-MENU)
where :
@@ -1206,17 +1206,17 @@ keywords are understood:
If it is an alist, associations should follow the
pattern:
- \\='(KEY DESCRIPTION ACTION)
+ (KEY DESCRIPTION ACTION)
where KEY, DESCRIPTION and ACTION are described above.
Valid values include:
- \\='(?m \"My Special Back-end\" my-special-export-function)
+ (?m \"My Special Back-end\" my-special-export-function)
or
- \\='(?l \"Export to LaTeX\"
+ (?l \"Export to LaTeX\"
((?p \"As PDF file\" org-latex-export-to-pdf)
(?o \"As PDF file and open\"
(lambda (a s v b)
@@ -1227,7 +1227,7 @@ keywords are understood:
or the following, which will be added to the previous
sub-menu,
- \\='(?l 1
+ (?l 1
((?B \"As TEX buffer (Beamer)\" org-beamer-export-as-latex)
(?P \"As PDF file (Beamer)\" org-beamer-export-to-pdf)))
--
2.37.1
^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: [PROPOSED-PATCH] Fix doc string quoting problems with '
2022-07-24 17:07 [PROPOSED-PATCH] Fix doc string quoting problems with ' Paul Eggert
@ 2022-07-25 8:50 ` Ihor Radchenko
2022-07-25 20:14 ` Paul Eggert
0 siblings, 1 reply; 3+ messages in thread
From: Ihor Radchenko @ 2022-07-25 8:50 UTC (permalink / raw)
To: Paul Eggert; +Cc: emacs-orgmode
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
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [PROPOSED-PATCH] Fix doc string quoting problems with '
2022-07-25 8:50 ` Ihor Radchenko
@ 2022-07-25 20:14 ` Paul Eggert
0 siblings, 0 replies; 3+ messages in thread
From: Paul Eggert @ 2022-07-25 20:14 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: emacs-orgmode
On 7/25/22 01:50, Ihor Radchenko wrote:
> 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.
Thanks, I added the following to the Elisp manual to try to fix that:
https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=d04701c0c4959d3c42587a4e1277bb517a2ea04b
> 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.
OK, I went with a more conservative route there, e.g., replacing this:
\\='((?R set-category get-category))
with this:
(setq org-agenda-bulk-custom-functions
\\='((?R set-category get-category)))
Although wordier, this follows the doc string guidelines and should make
it clear why the apostrophe is present.
> Also, note that references in the babel documentation are _not_ Elisp
> symbols - they are defined in #+name: name lines at the relevant src
> blocks.
Yes, I left those alone. Here's what I installed:
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=6013cb161d6f186829f6bfcfc5dd927c6cb89b49
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2022-07-25 20:15 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-07-24 17:07 [PROPOSED-PATCH] Fix doc string quoting problems with ' Paul Eggert
2022-07-25 8:50 ` Ihor Radchenko
2022-07-25 20:14 ` Paul Eggert
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).