From 328e7cc475e3cd08fd72b71f985fcee6895e4c7e Mon Sep 17 00:00:00 2001 From: Lars Ingebrigtsen Date: Sat, 6 Mar 2021 13:27:34 +0100 Subject: Remove mention of using defun- and defvar- as prefixes * doc/lispref/tips.texi (Coding Conventions): Remove mention of using defun- and defvar- as prefixes, as this is something that we rarely do in Emacs (bug#46899). --- doc/lispref/tips.texi | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/lispref/tips.texi') diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index 4a7793a976d..36c68ee5ced 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -75,8 +75,8 @@ example, it is our convention to have commands that list objects named as @samp{list-@var{something}}, e.g., a package called @samp{frob} could have a command @samp{list-frobs}, when its other global symbols begin with @samp{frob-}. Also, constructs that define functions, -variables, etc., work better if they start with @samp{defun} or -@samp{defvar}, so put the name prefix later on in the name. +variables, etc., work better if they start with @samp{define-}, so put +the name prefix later on in the name. This recommendation applies even to names for traditional Lisp primitives that are not primitives in Emacs Lisp---such as -- cgit v1.2.3 From 3cfc5532021357ef2e1284323e6936fafce484e5 Mon Sep 17 00:00:00 2001 From: Jonas Bernoulli Date: Mon, 3 May 2021 23:22:47 +0200 Subject: Add new function lm-maintainers (bug#48592) * doc/lispref/tips.texi (Library Headers): Improve wording. * lisp/emacs-lisp/lisp-mnt.el (lm-maintainers): New function. (lm-maintainer): Make obsolete in favor of lm-maintainer. (lm-verify): Use lm-maintainers. (lm-report-bug): Use lm-maintainers. --- doc/lispref/tips.texi | 6 +++--- lisp/emacs-lisp/lisp-mnt.el | 22 +++++++++++++++------- 2 files changed, 18 insertions(+), 10 deletions(-) (limited to 'doc/lispref/tips.texi') diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index 36c68ee5ced..54cafffab38 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -1034,7 +1034,7 @@ the conventional possibilities for @var{header-name}: @table @samp @item Author -This line states the name and email address of at least the principal +This header states the name and email address of at least the principal author of the library. If there are multiple authors, list them on continuation lines led by @code{;;} and a tab or at least two spaces. We recommend including a contact email address, of the form @@ -1053,8 +1053,8 @@ This header has the same format as the Author header. It lists the person(s) who currently maintain(s) the file (respond to bug reports, etc.). -If there is no maintainer line, the person(s) in the Author field -is/are presumed to be the maintainers. Some files in Emacs use +If there is no Maintainer header, the person(s) in the Author header +is/are presumed to be the maintainer(s). Some files in Emacs use @samp{emacs-devel@@gnu.org} for the maintainer, which means the author is no longer responsible for the file, and that it is maintained as part of Emacs. diff --git a/lisp/emacs-lisp/lisp-mnt.el b/lisp/emacs-lisp/lisp-mnt.el index 11a04400877..83da495edf0 100644 --- a/lisp/emacs-lisp/lisp-mnt.el +++ b/lisp/emacs-lisp/lisp-mnt.el @@ -378,14 +378,22 @@ the cdr is an email address." (let ((authorlist (lm-header-multiline "author"))) (mapcar #'lm-crack-address authorlist)))) +(defun lm-maintainers (&optional file) + "Return the maintainer list of file FILE, or current buffer if FILE is nil. +If the maintainers are unspecified, then return the authors. +Each element of the list is a cons; the car is the full name, +the cdr is an email address." + (lm-with-file file + (mapcar #'lm-crack-address + (or (lm-header-multiline "maintainer") + (lm-header-multiline "author"))))) + (defun lm-maintainer (&optional file) "Return the maintainer of file FILE, or current buffer if FILE is nil. +If the maintainer is unspecified, then return the author. The return value has the form (NAME . ADDRESS)." - (lm-with-file file - (let ((maint (lm-header "maintainer"))) - (if maint - (lm-crack-address maint) - (car (lm-authors)))))) + (declare (obsolete lm-maintainers "28.1")) + (car (lm-maintainers file))) (defun lm-creation-date (&optional file) "Return the created date given in file FILE, or current buffer if FILE is nil." @@ -545,7 +553,7 @@ copyright notice is allowed." "Can't find package name") ((not (lm-authors)) "`Author:' tag missing") - ((not (lm-maintainer)) + ((not (lm-maintainers)) "`Maintainer:' tag missing") ((not (lm-summary)) "Can't find the one-line summary description") @@ -613,7 +621,7 @@ Prompts for bug subject TOPIC. Leaves you in a mail buffer." (interactive "sBug Subject: ") (require 'emacsbug) (let ((package (lm-get-package-name)) - (addr (lm-maintainer)) + (addr (car (lm-maintainers))) (version (lm-version))) (compose-mail (if addr (concat (car addr) " <" (cdr addr) ">") -- cgit v1.2.3 From dc85ffffc88c08742072573539f8bfae9dcbbccb Mon Sep 17 00:00:00 2001 From: Lars Ingebrigtsen Date: Fri, 16 Jul 2021 10:56:21 +0200 Subject: Clarify -unload-feature in Coding Conventions * doc/lispref/tips.texi (Coding Conventions): Clarify when an unload function is useful (bug#21440). --- doc/lispref/tips.texi | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'doc/lispref/tips.texi') diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index 54cafffab38..a35847a74db 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -168,11 +168,12 @@ follow the naming conventions for hooks. @xref{Hooks}. @item @cindex unloading packages, preparing for -If loading the file adds functions to hooks, define a function -@code{@var{feature}-unload-function}, where @var{feature} is the name -of the feature the package provides, and make it undo any such -changes. Using @code{unload-feature} to unload the file will run this -function. @xref{Unloading}. +@code{unload-feature} will normally undo normal changes done by +loading a feature (like adding adds functions to hooks). However, if +loading @var{feature} does something more complex, define a function +@code{@var{feature}-unload-function}, and make it undo any such +changes. @code{unload-feature} will run this function. +@xref{Unloading}. @item It is a bad idea to define aliases for the Emacs primitives. Normally -- cgit v1.2.3 From 7176407c0127426fcaf28fe3c151156379a59209 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Fri, 16 Jul 2021 14:30:12 +0300 Subject: Fix wording in a recent ELisp manual change * doc/lispref/tips.texi (Coding Conventions): Fix wording in a recent change. (Bug#21440) --- doc/lispref/tips.texi | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'doc/lispref/tips.texi') diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index a35847a74db..8aa225a00c3 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -168,12 +168,12 @@ follow the naming conventions for hooks. @xref{Hooks}. @item @cindex unloading packages, preparing for -@code{unload-feature} will normally undo normal changes done by -loading a feature (like adding adds functions to hooks). However, if -loading @var{feature} does something more complex, define a function -@code{@var{feature}-unload-function}, and make it undo any such -changes. @code{unload-feature} will run this function. -@xref{Unloading}. +Using @code{unload-feature} will undo the changes usually done by +loading a feature (like adding functions to hooks). However, if +loading @var{feature} does something unusual and more complex, you can +define a function named @code{@var{feature}-unload-function}, and make +it undo any such special changes. @code{unload-feature} will then +automatically run this function if it exists. @xref{Unloading}. @item It is a bad idea to define aliases for the Emacs primitives. Normally -- cgit v1.2.3