From: Paul Eggert <eggert@cs.ucla.edu>
To: 20385@debbugs.gnu.org
Cc: Paul Eggert <eggert@cs.ucla.edu>
Subject: bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings
Date: Mon, 20 Apr 2015 11:39:15 -0700 [thread overview]
Message-ID: <1429555155-4695-1-git-send-email-eggert@cs.ucla.edu> (raw)
Emacs's traditional doc string style has been to quote symbols
`like this'. This worked well on older terminals where ` and '
were symmetric quotes, but nowadays this quoting looks odd and
it's better to use apostrophe for single-quoted ASCII text.
Add support for quoting either way, suggesting the newer style.
* doc/lispref/tips.texi (Documentation Tips): Quote symbols
'like-this' as well as `like-this'. Recommend the former style.
* etc/NEWS: Mention this.
* lisp/cedet/srecode/texi.el (srecode-texi-texify-docstring):
* lisp/emacs-lisp/checkdoc.el (checkdoc-this-string-valid-engine):
* lisp/emacs-lisp/lisp-mode.el (lisp-el-font-lock-keywords-2)
(lisp-cl-font-lock-keywords-2):
* lisp/finder.el (finder-font-lock-keywords):
* lisp/gnus/gnus-art.el (gnus-button-alist):
* lisp/help-mode.el (help-xref-symbol-regexp)
(help-xref-info-regexp, help-xref-url-regexp):
* lisp/international/mule-cmds.el (help-xref-mule-regexp-template):
* lisp/wid-edit.el (widget-documentation-link-regexp):
Parse symbols quoted 'like-this' as well as `like-this'.
---
doc/lispref/tips.texi | 27 ++++++++++++++++-----------
etc/NEWS | 4 ++++
lisp/cedet/srecode/texi.el | 2 +-
lisp/emacs-lisp/checkdoc.el | 4 ++--
lisp/emacs-lisp/lisp-mode.el | 8 ++++----
lisp/finder.el | 2 +-
lisp/gnus/gnus-art.el | 8 ++++----
lisp/help-mode.el | 6 +++---
lisp/international/mule-cmds.el | 2 +-
lisp/wid-edit.el | 2 +-
10 files changed, 37 insertions(+), 28 deletions(-)
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index cc1f0e4..8997249 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -658,17 +658,22 @@ starting double-quote is not part of the string!
@anchor{Docstring hyperlinks}
@item
When a documentation string refers to a Lisp symbol, write it as it
-would be printed (which usually means in lower case), with a grave
-accent @samp{`} before and apostrophe @samp{'} after it. There are
+would be printed (which usually means in lower case), with a
+apostrophe @samp{'} before and after it. There are
two exceptions: write @code{t} and @code{nil} without surrounding
-punctuation. For example: @samp{CODE can be `lambda', nil, or t.}
+punctuation. For example: @samp{CODE can be 'lambda', nil, or t.}
(In this manual, we use a different convention, with single-quotes
around symbols.)
+Documentation strings can also use an older single-quoting convention,
+which quotes symbols with grave accent @samp{`} and apostrophe, rather
+than with two apostrophes: @samp{`like-this'} rather than
+@samp{'like-this'}. This older single-quoting convention is not
+recommended for new documentation.
+
@cindex hyperlinks in documentation strings
Help mode automatically creates a hyperlink when a documentation string
-uses a symbol name between grave accent and apostrophe, if the symbol
-has either a
+uses a single-quoted symbol name, if the symbol has either a
function or a variable definition. You do not need to do anything
special to make use of this feature. However, when a symbol has both a
function definition and a variable definition, and you want to refer to
@@ -710,21 +715,21 @@ followed by the word @samp{face}. In that case, only the face
documentation will be shown, even if the symbol is also defined as a
variable or as a function.
-To make a hyperlink to Info documentation, write the name of the Info
-node (or anchor) between grave accent and apostrophe, preceded by
+To make a hyperlink to Info documentation, write the single-quoted
+name of the Info node (or anchor), preceded by
@samp{info node}, @samp{Info node}, @samp{info anchor} or @samp{Info
anchor}. The Info file name defaults to @samp{emacs}. For example,
@smallexample
-See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'.
+See Info node 'Font Lock' and Info node '(elisp)Font Lock Basics'.
@end smallexample
-Finally, to create a hyperlink to URLs, write the URL between grave
-accent and apostrophe, preceded by @samp{URL}. For example,
+Finally, to create a hyperlink to URLs, write the single-quoted URL,
+preceded by @samp{URL}. For example,
@smallexample
The home page for the GNU project has more information (see URL
-`http://www.gnu.org/').
+'http://www.gnu.org/').
@end smallexample
@item
diff --git a/etc/NEWS b/etc/NEWS
index a9c0d2e..278754e 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -791,6 +791,10 @@ name. The variable `system-name' is now obsolete.
*** New macros `thread-first' and `thread-last' allow threading a form
as the first or last argument of subsequent forms.
+** Documentation strings now support single-quoting 'like-this'
+in addition to the older style `like-this'. The newer style looks
+better on most modern displays, and is recommended for new code.
+
+++
** Time-related changes:
diff --git a/lisp/cedet/srecode/texi.el b/lisp/cedet/srecode/texi.el
index 5c3f21c..d03203d 100644
--- a/lisp/cedet/srecode/texi.el
+++ b/lisp/cedet/srecode/texi.el
@@ -253,7 +253,7 @@ that class.
[ stuff ] => @code{[ stuff ]}
Key => @kbd{Key} (key is C\\-h, M\\-h, SPC, RET, TAB and the like)
... => @dots{}"
- (while (string-match "`\\([-a-zA-Z0-9<>.]+\\)'" string)
+ (while (string-match "['`]\\([-a-zA-Z0-9<>.]+\\)'" string)
(let* ((vs (substring string (match-beginning 1) (match-end 1)))
(v (intern-soft vs)))
(setq string
diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
index 777fed0..d861da9 100644
--- a/lisp/emacs-lisp/checkdoc.el
+++ b/lisp/emacs-lisp/checkdoc.el
@@ -1554,7 +1554,7 @@ mouse-[0-3]\\)\\)\\>"))
(save-excursion
(let ((case-fold-search t)
(ret nil) mb me)
- (while (and (re-search-forward "`\\(\\sw\\(\\sw\\|\\s_\\)+\\)'" e t)
+ (while (and (re-search-forward "['`]\\(\\sw\\(\\sw\\|\\s_\\)+\\)'" e t)
(not ret))
(let* ((ms1 (match-string 1))
(sym (intern-soft ms1)))
@@ -1824,7 +1824,7 @@ Replace with \"%s\"? " original replace)
nil)))
;; t and nil case
(save-excursion
- (if (re-search-forward "\\(`\\(t\\|nil\\)'\\)" e t)
+ (if (re-search-forward "\\(['`]\\(t\\|nil\\)'\\)" e t)
(if (checkdoc-autofix-ask-replace
(match-beginning 1) (match-end 1)
(format "%s should not appear in quotes. Remove? "
diff --git a/lisp/emacs-lisp/lisp-mode.el b/lisp/emacs-lisp/lisp-mode.el
index 26a21d5..bfdd41e 100644
--- a/lisp/emacs-lisp/lisp-mode.el
+++ b/lisp/emacs-lisp/lisp-mode.el
@@ -405,8 +405,8 @@
;; Words inside \\[] tend to be for `substitute-command-keys'.
("\\\\\\\\\\[\\(\\(?:\\sw\\|\\s_\\)+\\)\\]"
(1 font-lock-constant-face prepend))
- ;; Words inside `' tend to be symbol names.
- ("`\\(\\(?:\\sw\\|\\s_\\)\\(?:\\sw\\|\\s_\\)+\\)'"
+ ;; Words inside '' and `' tend to be symbol names.
+ ("['`]\\(\\(?:\\sw\\|\\s_\\)\\(?:\\sw\\|\\s_\\)+\\)'"
(1 font-lock-constant-face prepend))
;; Constant values.
("\\_<:\\(?:\\sw\\|\\s_\\)+\\_>" 0 font-lock-builtin-face)
@@ -454,8 +454,8 @@
;; Erroneous structures.
(,(concat "(" cl-errs-re "\\_>")
(1 font-lock-warning-face))
- ;; Words inside `' tend to be symbol names.
- ("`\\(\\(?:\\sw\\|\\s_\\)\\(?:\\sw\\|\\s_\\)+\\)'"
+ ;; Words inside '' and `' tend to be symbol names.
+ ("['`]\\(\\(?:\\sw\\|\\s_\\)\\(?:\\sw\\|\\s_\\)+\\)'"
(1 font-lock-constant-face prepend))
;; Constant values.
("\\_<:\\(?:\\sw\\|\\s_\\)+\\_>" 0 font-lock-builtin-face)
diff --git a/lisp/finder.el b/lisp/finder.el
index 47fab3c..847dccc 100644
--- a/lisp/finder.el
+++ b/lisp/finder.el
@@ -115,7 +115,7 @@ Each element has the form (KEYWORD . DESCRIPTION).")
"Syntax table used while in `finder-mode'.")
(defvar finder-font-lock-keywords
- '(("`\\([^'`]+\\)'" 1 font-lock-constant-face prepend))
+ '(("['`]\\([^'`]+\\)'" 1 font-lock-constant-face prepend))
"Font-lock keywords for Finder mode.")
(defvar finder-headmark nil
diff --git a/lisp/gnus/gnus-art.el b/lisp/gnus/gnus-art.el
index 14f9adc..4560a0e 100644
--- a/lisp/gnus/gnus-art.el
+++ b/lisp/gnus/gnus-art.el
@@ -7828,11 +7828,11 @@ positives are possible."
("/\\([a-z][-a-z0-9]+\\.el\\)\\>[^.?]"
;; Exclude [.?] for URLs in gmane.emacs.cvs
1 (>= gnus-button-emacs-level 8) gnus-button-handle-library 1)
- ("`\\([a-z][-a-z0-9]+\\.el\\)'"
+ ("['`]\\([a-z][-a-z0-9]+\\.el\\)'"
1 (>= gnus-button-emacs-level 8) gnus-button-handle-library 1)
- ("`\\([a-z][a-z0-9]+-[a-z0-9]+-[-a-z0-9]*[a-z]\\|\\(gnus\\|message\\)-[-a-z]+\\)'"
+ ("['`]\\([a-z][a-z0-9]+-[a-z0-9]+-[-a-z0-9]*[a-z]\\|\\(gnus\\|message\\)-[-a-z]+\\)'"
0 (>= gnus-button-emacs-level 8) gnus-button-handle-symbol 1)
- ("`\\([a-z][a-z0-9]+-[a-z]+\\)'"
+ ("['`]\\([a-z][a-z0-9]+-[a-z]+\\)'"
0 (>= gnus-button-emacs-level 9) gnus-button-handle-symbol 1)
("(setq[ \t\n]+\\([a-z][a-z0-9]+-[-a-z0-9]+\\)[ \t\n]+.+)"
1 (>= gnus-button-emacs-level 7) gnus-button-handle-describe-variable 1)
@@ -7842,7 +7842,7 @@ positives are possible."
0 (>= gnus-button-emacs-level 1) gnus-button-handle-describe-function 2)
("\\b\\(C-h\\|<?[Ff]1>?\\)[ \t\n]+v[ \t\n]+\\([^ \t\n]+\\)[ \t\n]+RET\\>"
0 (>= gnus-button-emacs-level 1) gnus-button-handle-describe-variable 2)
- ("`\\(\\(C-h\\|<?[Ff]1>?\\)[ \t\n]+k[ \t\n]+\\([^']+\\)\\)'"
+ ("['`]\\(\\(C-h\\|<?[Ff]1>?\\)[ \t\n]+k[ \t\n]+\\([^']+\\)\\)'"
;; Unlike the other regexps we really have to require quoting
;; here to determine where it ends.
1 (>= gnus-button-emacs-level 1) gnus-button-handle-describe-key 3)
diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index d6679e9..13e5ed4 100644
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -322,7 +322,7 @@ Commands:
"\\(source \\(?:code \\)?\\(?:of\\|for\\)\\)\\)"
"[ \t\n]+\\)?"
;; Note starting with word-syntax character:
- "`\\(\\sw\\(\\sw\\|\\s_\\)+\\)'"))
+ "['`]\\(\\sw\\(\\sw\\|\\s_\\)+\\)'"))
"Regexp matching doc string references to symbols.
The words preceding the quoted symbol can be used in doc strings to
@@ -337,11 +337,11 @@ when help commands related to multilingual environment (e.g.,
(defconst help-xref-info-regexp
- (purecopy "\\<[Ii]nfo[ \t\n]+\\(node\\|anchor\\)[ \t\n]+`\\([^']+\\)'")
+ (purecopy "\\<[Ii]nfo[ \t\n]+\\(node\\|anchor\\)[ \t\n]+['`]\\([^']+\\)'")
"Regexp matching doc string references to an Info node.")
(defconst help-xref-url-regexp
- (purecopy "\\<[Uu][Rr][Ll][ \t\n]+`\\([^']+\\)'")
+ (purecopy "\\<[Uu][Rr][Ll][ \t\n]+['`]\\([^']+\\)'")
"Regexp matching doc string references to a URL.")
;;;###autoload
diff --git a/lisp/international/mule-cmds.el b/lisp/international/mule-cmds.el
index cca659f..0856995 100644
--- a/lisp/international/mule-cmds.el
+++ b/lisp/international/mule-cmds.el
@@ -177,7 +177,7 @@
"\\(charset\\)"
"\\)\\s-+\\)?"
;; Note starting with word-syntax character:
- "`\\(\\sw\\(\\sw\\|\\s_\\)+\\)'")))
+ "['`]\\(\\sw\\(\\sw\\|\\s_\\)+\\)'")))
(defun coding-system-change-eol-conversion (coding-system eol-type)
"Return a coding system which differs from CODING-SYSTEM in EOL conversion.
diff --git a/lisp/wid-edit.el b/lisp/wid-edit.el
index 04a900f..9e1c895 100644
--- a/lisp/wid-edit.el
+++ b/lisp/wid-edit.el
@@ -2855,7 +2855,7 @@ The following properties have special meanings for this widget:
:type 'boolean
:group 'widget-documentation)
-(defcustom widget-documentation-link-regexp "`\\([^\n`' ]+\\)'"
+(defcustom widget-documentation-link-regexp "['`]\\([^\n`' ]+\\)'"
"Regexp for matching potential links in documentation strings.
The first group should be the link itself."
:type 'regexp
--
2.1.0
next reply other threads:[~2015-04-20 18:39 UTC|newest]
Thread overview: 102+ messages / expand[flat|nested] mbox.gz Atom feed top
2015-04-20 18:39 Paul Eggert [this message]
2015-04-20 19:37 ` bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings Stefan Monnier
2015-04-21 0:18 ` Paul Eggert
2015-04-21 0:53 ` Drew Adams
2015-04-21 1:14 ` Stefan Monnier
2015-04-21 1:30 ` Drew Adams
2015-04-21 1:58 ` Stefan Monnier
2015-04-21 3:45 ` Paul Eggert
2015-04-21 14:52 ` Eli Zaretskii
2015-04-21 18:04 ` Stefan Monnier
2015-04-21 18:25 ` Eli Zaretskii
2015-04-21 19:34 ` Stefan Monnier
2015-04-21 19:50 ` Eli Zaretskii
2015-04-21 20:01 ` Dmitry Gutov
2015-04-22 7:00 ` Eli Zaretskii
2015-04-22 13:52 ` Drew Adams
2015-04-22 13:59 ` Nicolas Petton
2015-04-22 14:52 ` Drew Adams
2015-04-22 23:36 ` Paul Eggert
2015-04-23 0:23 ` Nicolas Petton
2015-04-23 6:45 ` Paul Eggert
2015-04-23 9:14 ` Nicolas Petton
2015-04-23 10:22 ` Paul Eggert
2015-04-23 11:15 ` Nicolas Petton
2015-04-23 17:32 ` Paul Eggert
2015-04-23 18:23 ` Drew Adams
2015-04-23 19:38 ` Paul Eggert
2015-04-23 20:07 ` Drew Adams
2015-04-23 20:12 ` Eli Zaretskii
2015-04-23 23:24 ` Paul Eggert
2015-04-24 0:24 ` Drew Adams
2015-04-24 4:47 ` Paul Eggert
2015-04-23 19:47 ` Nicolas Petton
2015-04-23 19:57 ` Dmitry Gutov
2015-04-23 2:19 ` Drew Adams
2015-04-23 6:45 ` Paul Eggert
2015-04-23 14:51 ` Drew Adams
2015-04-23 15:32 ` Drew Adams
2015-04-23 17:11 ` Paul Eggert
2015-04-23 19:55 ` Dmitry Gutov
2015-04-23 20:03 ` Eli Zaretskii
2015-04-23 20:13 ` Drew Adams
2015-04-24 6:11 ` Eli Zaretskii
2015-04-24 3:04 ` Dmitry Gutov
2015-04-24 6:46 ` Eli Zaretskii
2015-04-24 13:43 ` Artur Malabarba
2015-04-21 18:44 ` Nicolas Petton
2015-04-21 20:30 ` Stefan Monnier
2015-04-22 0:49 ` Paul Eggert
2015-04-22 23:37 ` Paul Eggert
2015-04-23 6:30 ` Eli Zaretskii
2015-04-21 18:35 ` Ivan Shmakov
2015-04-21 18:42 ` Eli Zaretskii
2015-04-21 19:37 ` Ivan Shmakov
2015-04-21 19:52 ` Eli Zaretskii
[not found] ` <mailman.1406.1429745828.904.bug-gnu-emacs@gnu.org>
2015-04-23 12:11 ` Alan Mackenzie
2015-04-23 12:35 ` Eli Zaretskii
2015-04-23 12:45 ` Alan Mackenzie
2015-04-23 13:06 ` Eli Zaretskii
[not found] ` <mailman.1407.1429745888.904.bug-gnu-emacs@gnu.org>
2015-04-23 12:27 ` Alan Mackenzie
2015-04-23 19:42 ` Paul Eggert
2015-05-13 7:30 ` bug#20385: [PATCH] Support curved quotes " Paul Eggert
2015-05-13 12:16 ` Dmitry Gutov
2015-05-13 15:13 ` Paul Eggert
2015-05-13 22:33 ` Dmitry Gutov
2015-05-14 3:24 ` Paul Eggert
2015-05-14 10:49 ` Dmitry Gutov
2015-05-15 7:49 ` Paul Eggert
2015-05-15 17:24 ` Dmitry Gutov
2015-05-15 18:54 ` Paul Eggert
2015-05-15 19:09 ` Dmitry Gutov
2015-05-15 21:13 ` Paul Eggert
2015-05-15 21:48 ` Dmitry Gutov
2015-05-15 23:52 ` Paul Eggert
2015-05-16 0:08 ` Dmitry Gutov
2015-05-16 0:11 ` Dmitry Gutov
2015-05-16 1:48 ` Paul Eggert
2015-05-16 8:27 ` Dmitry Gutov
2015-05-19 23:27 ` Paul Eggert
2015-05-20 2:22 ` Dmitry Gutov
2015-05-21 7:21 ` Paul Eggert
2015-05-21 10:01 ` Dmitry Gutov
2015-05-21 14:58 ` Paul Eggert
2015-05-22 3:41 ` Dmitry Gutov
2015-05-16 9:51 ` Andreas Schwab
2015-05-16 1:23 ` Drew Adams
2015-05-16 6:20 ` Paul Eggert
2015-05-16 7:36 ` Eli Zaretskii
2015-05-14 7:10 ` missing charset for non-ASCII text/x-patch MIME parts in Thunderbird Ivan Shmakov
2015-05-14 8:28 ` Stephen J. Turnbull
2015-05-14 8:28 ` bug#20385: " Stephen J. Turnbull
2015-05-14 7:10 ` Ivan Shmakov
2015-05-14 7:20 ` bug#20385: Support curved quotes in doc strings Ivan Shmakov
2015-05-14 14:55 ` Eli Zaretskii
2015-05-14 20:05 ` Ivan Shmakov
2015-05-14 20:12 ` Eli Zaretskii
2015-05-14 20:30 ` Ivan Shmakov
[not found] <<1429555155-4695-1-git-send-email-eggert@cs.ucla.edu>
2015-04-20 20:16 ` bug#20385: [PROPOSED PATCH] Support quoting 'like this' " Drew Adams
[not found] ` <<jwvtwwabnhp.fsf-monnier+emacsbugs@gnu.org>
[not found] ` <<5535974D.9050207@cs.ucla.edu>
[not found] ` <<jwvvbgqs2ud.fsf-monnier+emacsbugs@gnu.org>
[not found] ` <<5535C7F3.7020107@cs.ucla.edu>
[not found] ` <<83618p5y9w.fsf@gnu.org>
[not found] ` <<jwvk2x59x4g.fsf-monnier+emacsbugs@gnu.org>
[not found] ` <<83vbgp49ve.fsf@gnu.org>
[not found] ` <<jwv8udl9syp.fsf-monnier+emacsbugs@gnu.org>
[not found] ` <<83pp6x45x5.fsf@gnu.org>
[not found] ` <<5536ACB3.9040707@yandex.ru>
[not found] ` <<83lhhk4phe.fsf@gnu.org>
[not found] ` <<fe3d90cd-056a-49a6-a049-6df07e710663@default>
[not found] ` <<87a8y0jmba.fsf@petton.fr>
[not found] ` <<6837d058-ba18-461b-8af6-2c4e6d767348@default>
[not found] ` <<55383081.4010106@cs.ucla.edu>
[not found] ` <<87a8xzae0o.fsf@petton.fr>
[not found] ` <<55389500.8000404@cs.ucla.edu>
[not found] ` <<878udj9pfq.fsf@petton.fr>
[not found] ` <<5538C7EC.9010105@cs.ucla.edu>
[not found] ` <<877ft39juq.fsf@petton.fr>
[not found] ` <<55392C91.1010300@cs.ucla.edu>
[not found] ` <<84f4aea9-c3ef-44c5-ac06-0df72d223e8c@default>
[not found] ` <<55394A2E.8020002@cs.ucla.edu>
[not found] ` <<f978526c-c5e3-405d-ae75-63b9ed5d4537@default>
[not found] ` <<83lhhizjqw.fsf@gnu.org>
2015-04-23 20:15 ` Drew Adams
2015-04-24 6:12 ` Eli Zaretskii
[not found] ` <<55394E30.8040307@yandex.ru>
[not found] ` <<83oamezk77.fsf@gnu.org>
[not found] ` <<4b159230-cd7e-4cb9-a778-3ad7ed2ae301@default>
[not found] ` <<83k2x2ys1b.fsf@gnu.org>
2015-04-24 14:11 ` Drew Adams
2015-04-24 14:40 ` Eli Zaretskii
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=1429555155-4695-1-git-send-email-eggert@cs.ucla.edu \
--to=eggert@cs.ucla.edu \
--cc=20385@debbugs.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.