From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Paul Eggert Newsgroups: gmane.emacs.bugs Subject: bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings Date: Mon, 20 Apr 2015 11:39:15 -0700 Message-ID: <1429555155-4695-1-git-send-email-eggert@cs.ucla.edu> NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1429555232 31904 80.91.229.3 (20 Apr 2015 18:40:32 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 20 Apr 2015 18:40:32 +0000 (UTC) Cc: Paul Eggert To: 20385@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Apr 20 20:40:20 2015 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1YkGcE-00016v-Qn for geb-bug-gnu-emacs@m.gmane.org; Mon, 20 Apr 2015 20:40:19 +0200 Original-Received: from localhost ([::1]:54961 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YkGcE-0000Jc-0l for geb-bug-gnu-emacs@m.gmane.org; Mon, 20 Apr 2015 14:40:18 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:39365) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YkGc6-0000JX-Vm for bug-gnu-emacs@gnu.org; Mon, 20 Apr 2015 14:40:16 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YkGc1-0003BA-PJ for bug-gnu-emacs@gnu.org; Mon, 20 Apr 2015 14:40:10 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:44051) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YkGc1-0003Ah-Lc for bug-gnu-emacs@gnu.org; Mon, 20 Apr 2015 14:40:05 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1YkGc0-0005AB-M8 for bug-gnu-emacs@gnu.org; Mon, 20 Apr 2015 14:40:05 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Paul Eggert Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 20 Apr 2015 18:40:04 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 20385 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.142955520019828 (code B ref -1); Mon, 20 Apr 2015 18:40:04 +0000 Original-Received: (at submit) by debbugs.gnu.org; 20 Apr 2015 18:40:00 +0000 Original-Received: from localhost ([127.0.0.1]:33827 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YkGbu-00059i-IP for submit@debbugs.gnu.org; Mon, 20 Apr 2015 14:39:59 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:54046) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YkGbr-00059V-PE for submit@debbugs.gnu.org; Mon, 20 Apr 2015 14:39:57 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YkGbh-0002rZ-CP for submit@debbugs.gnu.org; Mon, 20 Apr 2015 14:39:50 -0400 Original-Received: from lists.gnu.org ([2001:4830:134:3::11]:53351) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YkGbh-0002rU-9S for submit@debbugs.gnu.org; Mon, 20 Apr 2015 14:39:45 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:39281) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YkGbf-00007Q-5t for bug-gnu-emacs@gnu.org; Mon, 20 Apr 2015 14:39:45 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YkGbY-0002q6-UZ for bug-gnu-emacs@gnu.org; Mon, 20 Apr 2015 14:39:43 -0400 Original-Received: from smtp.cs.ucla.edu ([131.179.128.62]:33902) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YkGbY-0002p9-Hl for bug-gnu-emacs@gnu.org; Mon, 20 Apr 2015 14:39:36 -0400 Original-Received: from localhost (localhost.localdomain [127.0.0.1]) by smtp.cs.ucla.edu (Postfix) with ESMTP id A4E0FA60003 for ; Mon, 20 Apr 2015 11:39:28 -0700 (PDT) X-Virus-Scanned: amavisd-new at smtp.cs.ucla.edu Original-Received: from smtp.cs.ucla.edu ([127.0.0.1]) by localhost (smtp.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 3lJHgtR86fUi; Mon, 20 Apr 2015 11:39:27 -0700 (PDT) Original-Received: from Penguin.CS.UCLA.EDU (Penguin.CS.UCLA.EDU [131.179.64.200]) by smtp.cs.ucla.edu (Postfix) with ESMTPSA id 3155939E8013; Mon, 20 Apr 2015 11:39:27 -0700 (PDT) X-Mailer: git-send-email 2.1.0 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:101769 Archived-At: 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\\|?\\)[ \t\n]+v[ \t\n]+\\([^ \t\n]+\\)[ \t\n]+RET\\>" 0 (>= gnus-button-emacs-level 1) gnus-button-handle-describe-variable 2) - ("`\\(\\(C-h\\|?\\)[ \t\n]+k[ \t\n]+\\([^']+\\)\\)'" + ("['`]\\(\\(C-h\\|?\\)[ \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