From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Phil Sainty Newsgroups: gmane.emacs.bugs Subject: bug#28863: 26.0.90; [PATCH] Don't clobber docstrings of explicitly-defined mode hook variables Date: Tue, 17 Oct 2017 01:35:43 +1300 Message-ID: <0e9fedfc-ee21-3c9b-2455-17ae5f128d7f@orcon.net.nz> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="------------C3F2D9755DD76F679A6C9C3E" X-Trace: blaine.gmane.org 1508157435 2723 195.159.176.226 (16 Oct 2017 12:37:15 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 16 Oct 2017 12:37:15 +0000 (UTC) User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.4.0 To: 28863@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Oct 16 14:37:09 2017 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1e44dl-00081s-BN for geb-bug-gnu-emacs@m.gmane.org; Mon, 16 Oct 2017 14:37:05 +0200 Original-Received: from localhost ([::1]:32802 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1e44ds-0003La-OL for geb-bug-gnu-emacs@m.gmane.org; Mon, 16 Oct 2017 08:37:12 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:47792) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1e44dl-0003LI-Ui for bug-gnu-emacs@gnu.org; Mon, 16 Oct 2017 08:37:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1e44di-0006pg-Ph for bug-gnu-emacs@gnu.org; Mon, 16 Oct 2017 08:37:05 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:33923) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1e44di-0006pc-LH for bug-gnu-emacs@gnu.org; Mon, 16 Oct 2017 08:37:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1e44di-00046Q-CI for bug-gnu-emacs@gnu.org; Mon, 16 Oct 2017 08:37:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Phil Sainty Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 16 Oct 2017 12:37:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 28863 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.150815737415705 (code B ref -1); Mon, 16 Oct 2017 12:37:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 16 Oct 2017 12:36:14 +0000 Original-Received: from localhost ([127.0.0.1]:42604 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1e44cv-00045D-NL for submit@debbugs.gnu.org; Mon, 16 Oct 2017 08:36:14 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:56630) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1e44cu-00044w-4U for submit@debbugs.gnu.org; Mon, 16 Oct 2017 08:36:12 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1e44cn-0006Tz-BU for submit@debbugs.gnu.org; Mon, 16 Oct 2017 08:36:06 -0400 Original-Received: from lists.gnu.org ([2001:4830:134:3::11]:51183) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1e44cn-0006Tu-6v for submit@debbugs.gnu.org; Mon, 16 Oct 2017 08:36:05 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:47580) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1e44cl-0002mW-Ew for bug-gnu-emacs@gnu.org; Mon, 16 Oct 2017 08:36:04 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1e44ci-0006RI-8K for bug-gnu-emacs@gnu.org; Mon, 16 Oct 2017 08:36:03 -0400 Original-Received: from smtp-3.orcon.net.nz ([60.234.4.44]:38261) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1e44ch-0006Op-LN for bug-gnu-emacs@gnu.org; Mon, 16 Oct 2017 08:36:00 -0400 Original-Received: from [150.107.172.48] (port=9802 helo=[192.168.20.102]) by smtp-3.orcon.net.nz with esmtpa (Exim 4.86_2) (envelope-from ) id 1e44cR-0000l4-Og for bug-gnu-emacs@gnu.org; Tue, 17 Oct 2017 01:35:54 +1300 Content-Language: en-GB X-GeoIP: NZ X-Spam_score: -2.9 X-Spam_score_int: -28 X-Spam_bar: -- X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.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" Xref: news.gmane.org gmane.emacs.bugs:138517 Archived-At: This is a multi-part message in MIME format. --------------C3F2D9755DD76F679A6C9C3E Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 7bit `define-derived-mode' and `define-minor-mode' each define their mode hook variable, including a standard docstring, using: (defvar ,hook nil ".....") In the uncommon (but not unheard of) scenario whereby a library defines a mode and also explicitly defines that mode's hook variable with defvar or defcustom, the library author will encounter problems no matter which way around they define them. 1. If the mode is defined first: (define-derived-mode foo-mode ...) (defcustom foo-mode-hook '(default value) "docstring") Then `foo-mode-hook' has already been defvar'd with a value of nil, and so the defcustom default value never gets set, so that sequence is no good. 2. If the variable is defined first: (defcustom foo-mode-hook '(default value) "docstring") (define-derived-mode foo-mode ...) Then `foo-mode-hook' gets its default value, but its original docstring is clobbered by the one provided by `define-derived-mode' -- because while the value of a bound variable is not affected by evaling its definition again, the docstring does get updated. 3. We can work around that with a sequence such as: (defcustom foo-mode-hook '(default value) "" ...) (define-derived-mode foo-mode ...) (put 'foo-mode-hook 'variable-documentation "docstring") which works, but is cumbersome, as the hook variable's docstring is now separated from the hook variable definition by the entirety of the mode definition. My suggestion is that `define-derived-mode' and `define-minor-mode' should only add the standard docstring to the mode hook variable conditional on that variable not *already* having a docstring. That would then allow approach (2) to have the same effect as (3) but in a much tidier manner. Patch attached for consideration. -Phil In GNU Emacs 26.0.90 (build 1, x86_64-pc-linux-gnu, X toolkit, Xaw3d scroll bars) of 2017-10-17 built on shodan Repository revision: ead257cbfc2c7e9196210b899f6d4e6496c0a42b Windowing system distributor 'The X.Org Foundation', version 11.0.11804000 System Description: Ubuntu 16.04.3 LTS Recent messages: For information about GNU Emacs and the GNU system, type C-h C-a. Configured using: 'configure --prefix=/home/phil/emacs/trunk/usr/local --with-x-toolkit=lucid --without-sound' Configured features: XAW3D XPM JPEG TIFF GIF PNG RSVG IMAGEMAGICK DBUS GSETTINGS NOTIFY GNUTLS LIBXML2 FREETYPE XFT ZLIB TOOLKIT_SCROLL_BARS LUCID X11 LCMS2 Important settings: value of $LANG: en_NZ.UTF-8 value of $XMODIFIERS: locale-coding-system: utf-8-unix Major mode: Lisp Interaction Minor modes in effect: tooltip-mode: t global-eldoc-mode: t eldoc-mode: t electric-indent-mode: t mouse-wheel-mode: t tool-bar-mode: t menu-bar-mode: t file-name-shadow-mode: t global-font-lock-mode: t font-lock-mode: t blink-cursor-mode: t auto-composition-mode: t auto-encryption-mode: t auto-compression-mode: t line-number-mode: t transient-mark-mode: t Load-path shadows: None found. Features: (shadow sort mail-extr emacsbug message rmc puny seq byte-opt gv bytecomp byte-compile cconv cl-loaddefs cl-lib dired dired-loaddefs format-spec rfc822 mml easymenu mml-sec password-cache epa derived epg epg-config gnus-util rmail rmail-loaddefs mm-decode mm-bodies mm-encode mail-parse rfc2231 mailabbrev gmm-utils mailheader sendmail rfc2047 rfc2045 ietf-drums mm-util mail-prsvr mail-utils elec-pair time-date mule-util tooltip eldoc electric uniquify ediff-hook vc-hooks lisp-float-type mwheel term/x-win x-win term/common-win x-dnd tool-bar dnd fontset image regexp-opt fringe tabulated-list replace newcomment text-mode elisp-mode lisp-mode prog-mode register page menu-bar rfn-eshadow isearch timer select scroll-bar mouse jit-lock font-lock syntax facemenu font-core term/tty-colors frame cl-generic cham georgian utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao korean japanese eucjp-ms cp51932 hebrew greek romanian slovak czech european ethiopic indian cyrillic chinese composite charscript charprop case-table epa-hook jka-cmpr-hook help simple abbrev obarray minibuffer cl-preloaded nadvice loaddefs button faces cus-face macroexp files text-properties overlay sha1 md5 base64 format env code-pages mule custom widget hashtable-print-readable backquote dbusbind inotify lcms2 dynamic-setting system-font-setting font-render-setting x-toolkit x multi-tty make-network-process emacs) Memory information: ((conses 16 96192 5551) (symbols 48 20686 1) (miscs 40 41 93) (strings 32 30399 1252) (string-bytes 1 771583) (vectors 16 13978) (vector-slots 8 492632 7908) (floats 8 51 66) (intervals 56 232 0) (buffers 992 11) (heap 1024 32112 1181)) --------------C3F2D9755DD76F679A6C9C3E Content-Type: text/x-patch; name="0001-Don-t-clobber-docstrings-of-explicitly-defined-mode-.patch" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename*0="0001-Don-t-clobber-docstrings-of-explicitly-defined-mode-.pa"; filename*1="tch" >From ead257cbfc2c7e9196210b899f6d4e6496c0a42b Mon Sep 17 00:00:00 2001 From: Phil Sainty Date: Mon, 16 Oct 2017 23:38:42 +1300 Subject: [PATCH] Don't clobber docstrings of explicitly-defined mode hook variables * lisp/emacs-lisp/derived.el (define-derived-mode): * lisp/emacs-lisp/easy-mmode.el (define-minor-mode): When defining the mode hook variable, do not clobber pre-existing docstrings. --- lisp/emacs-lisp/derived.el | 8 +++++--- lisp/emacs-lisp/easy-mmode.el | 8 +++++--- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/lisp/emacs-lisp/derived.el b/lisp/emacs-lisp/derived.el index 3fa3818..e8910d1 100644 --- a/lisp/emacs-lisp/derived.el +++ b/lisp/emacs-lisp/derived.el @@ -203,11 +203,13 @@ define-derived-mode parent child docstring syntax abbrev)) `(progn - (defvar ,hook nil - ,(format "Hook run after entering %s mode. + (defvar ,hook nil) + (unless (get ',hook 'variable-documentation) + (put ',hook 'variable-documentation + ,(format "Hook run after entering %s mode. No problems result if this variable is not bound. `add-hook' automatically binds it. (This is true for all hook variables.)" - name)) + name))) (unless (boundp ',map) (put ',map 'definition-name ',child)) (with-no-warnings (defvar ,map (make-sparse-keymap))) diff --git a/lisp/emacs-lisp/easy-mmode.el b/lisp/emacs-lisp/easy-mmode.el index bf087fc..220691c 100644 --- a/lisp/emacs-lisp/easy-mmode.el +++ b/lisp/emacs-lisp/easy-mmode.el @@ -309,11 +309,13 @@ define-minor-mode ;; up-to-here. :autoload-end - (defvar ,hook nil - ,(format "Hook run after entering or leaving `%s'. + (defvar ,hook nil) + (unless (get ',hook 'variable-documentation) + (put ',hook 'variable-documentation + ,(format "Hook run after entering or leaving `%s'. No problems result if this variable is not bound. `add-hook' automatically binds it. (This is true for all hook variables.)" - modefun)) + modefun))) ;; Define the minor-mode keymap. ,(unless (symbolp keymap) ;nil is also a symbol. -- 2.8.3 --------------C3F2D9755DD76F679A6C9C3E--