bug#32680: 27.0.50; Improve docstring and customization for 'message-signature'

bug#32680: 27.0.50; Improve docstring and customization for 'message-signature'

[Philipp Stephani]

The manual states

   If you change ‘message-signature’ to ‘nil’, Emacs will not insert
your mail signature automatically.  You can insert your mail signature
by typing ‘C-c C-w’ (‘message-insert-signature’) in the mail buffer.
Emacs will look for your signature in the signature file.

However, the docstring for message-signature doesn't state that nil is a
possible value, and the customization choices also don't suggest nil.


In GNU Emacs 27.0.50 (build 45, x86_64-pc-linux-gnu, GTK+ Version 3.22.24)
 of 2018-09-10 built on localhost
Repository revision: a65fe6fbf6f05789bb69c50de7b0946adf8773ac
Windowing system distributor 'The X.Org Foundation', version 11.0.11906000
System Description: Debian GNU/Linux buster/sid

Recent messages:
For information about GNU Emacs and the GNU system, type C-h C-a.

Configured using:
 'configure --without-threads --enable-gcc-warnings=warn-only
 --enable-gtk-deprecation-warnings --without-pop --with-mailutils
 --enable-checking --enable-check-lisp-object-type --with-modules
 'CFLAGS=-O0 -ggdb3''

Configured features:
XPM JPEG TIFF GIF PNG SOUND DBUS GSETTINGS GLIB NOTIFY GNUTLS FREETYPE
XFT ZLIB TOOLKIT_SCROLL_BARS GTK3 X11 XDBE XIM MODULES JSON GMP

Important settings:
  value of $LANG: en_US.UTF-8
  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 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 cl-loaddefs cl-lib 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
dynamic-setting system-font-setting font-render-setting move-toolbar gtk
x-toolkit x multi-tty make-network-process emacs)

Memory information:
((conses 16 95085 7371)
 (symbols 48 20185 1)
 (strings 32 28364 1644)
 (string-bytes 1 762351)
 (vectors 16 14358)
 (vector-slots 8 509630 11310)
 (floats 8 48 69)
 (intervals 56 223 0)
 (buffers 992 12))

-- 
Google Germany GmbH
Erika-Mann-Straße 33
80636 München

Registergericht und -nummer: Hamburg, HRB 86891
Sitz der Gesellschaft: Hamburg
Geschäftsführer: Paul Manicle, Halimah DeLaine Prado

If you received this communication by mistake, please don’t forward it to
anyone else (it may contain confidential or privileged information), please
erase all copies of it, including all attachments, and please let the sender
know it went to the wrong person.  Thanks.

bug#32680: 27.0.50; Improve docstring and customization for 'message-signature'

[Robert Pluim]

Philipp Stephani <p.stephani2@gmail.com> writes:

> The manual states
>
>    If you change ‘message-signature’ to ‘nil’, Emacs will not insert
> your mail signature automatically.  You can insert your mail signature
> by typing ‘C-c C-w’ (‘message-insert-signature’) in the mail buffer.
> Emacs will look for your signature in the signature file.
>
> However, the docstring for message-signature doesn't state that nil is a
> possible value, and the customization choices also don't suggest nil.

We could even put this in emacs-26.

2018-09-10  Robert Pluim  <rpluim@gmail.com>

	* lisp/gnus/message.el (message-signature): Allow nil as a
	customizable value, and describe its effect. (Bug #32680)

diff --git i/lisp/gnus/message.el w/lisp/gnus/message.el
index 66356b6fda..ec2286b06d 100644
--- i/lisp/gnus/message.el
+++ w/lisp/gnus/message.el
@@ -1079,12 +1079,15 @@ message-indent-citation-function
 (defcustom message-signature mail-signature
   "String to be inserted at the end of the message buffer.
 If t, the `message-signature-file' file will be inserted instead.
+If nil, no signature is inserted.
 If a function, the result from the function will be used instead.
-If a form, the result from the form will be used instead."
-  :version "23.2"
+If a form, the result from the form will be used instead.
+See `mail-signature' for the recommended format of a signature."
+  :version "27.1"
   :type '(choice string (const :tag "Contents of signature file" t)
 		 function
-		 sexp)
+		 sexp
+                 (const :tag "None" nil))
   :risky t
   :link '(custom-manual "(message)Insertion Variables")
   :group 'message-insertion)

bug#32680: 27.0.50; Improve docstring and customization for 'message-signature'

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Date: Mon, 10 Sep 2018 16:25:21 +0200
> Cc: 32680@debbugs.gnu.org
> 
> Philipp Stephani <p.stephani2@gmail.com> writes:
> 
> > The manual states
> >
> >    If you change ‘message-signature’ to ‘nil’, Emacs will not insert
> > your mail signature automatically.  You can insert your mail signature
> > by typing ‘C-c C-w’ (‘message-insert-signature’) in the mail buffer.
> > Emacs will look for your signature in the signature file.
> >
> > However, the docstring for message-signature doesn't state that nil is a
> > possible value, and the customization choices also don't suggest nil.
> 
> We could even put this in emacs-26.

Fine with me, but if it will go to emacs-26, then the :version tag
should say so.

Thanks.

bug#32680: 27.0.50; Improve docstring and customization for 'message-signature'

[Glenn Morris]

Robert Pluim wrote:

> --- i/lisp/gnus/message.el
> +++ w/lisp/gnus/message.el
> @@ -1079,12 +1079,15 @@ message-indent-citation-function
>  (defcustom message-signature mail-signature
>    "String to be inserted at the end of the message buffer.
>  If t, the `message-signature-file' file will be inserted instead.
> +If nil, no signature is inserted.
>  If a function, the result from the function will be used instead.
> -If a form, the result from the form will be used instead."
> -  :version "23.2"
> +If a form, the result from the form will be used instead.

May as well rewrite it all to use the active voice while you are there.

> +See `mail-signature' for the recommended format of a signature."
> +  :version "27.1"

It's not new, and the default hasn't changed, so a version bump is not
appropriate. It's just a doc fix.

bug#32680: 27.0.50; Improve docstring and customization for 'message-signature'

[Robert Pluim]

Glenn Morris <rgm@gnu.org> writes:

> Robert Pluim wrote:
>
>> --- i/lisp/gnus/message.el
>> +++ w/lisp/gnus/message.el
>> @@ -1079,12 +1079,15 @@ message-indent-citation-function
>>  (defcustom message-signature mail-signature
>>    "String to be inserted at the end of the message buffer.
>>  If t, the `message-signature-file' file will be inserted instead.
>> +If nil, no signature is inserted.
>>  If a function, the result from the function will be used instead.
>> -If a form, the result from the form will be used instead."
>> -  :version "23.2"
>> +If a form, the result from the form will be used instead.
>
> May as well rewrite it all to use the active voice while you are there.
>

OK. I modified 'mail-signature' as well, it didnʼt describe the nil
value.

>> +See `mail-signature' for the recommended format of a signature."
>> +  :version "27.1"
>
> It's not new, and the default hasn't changed, so a version bump is not
> appropriate. It's just a doc fix.

Fixed.

2018-09-10  Robert Pluim  <rpluim@gmail.com>

	* lisp/gnus/message.el (message-signature): Allow nil as a
	customizable value, and describe its effect.
	* lisp/mail/sendmail.el (mail-signature): Describe effect of nil value.

diff --git i/lisp/gnus/message.el w/lisp/gnus/message.el
index 66356b6fda..6ecf804e9e 100644
--- i/lisp/gnus/message.el
+++ w/lisp/gnus/message.el
@@ -1078,13 +1078,16 @@ message-indent-citation-function
 
 (defcustom message-signature mail-signature
   "String to be inserted at the end of the message buffer.
-If t, the `message-signature-file' file will be inserted instead.
-If a function, the result from the function will be used instead.
-If a form, the result from the form will be used instead."
+If nil, no signature is inserted.
+If t, the `message-signature-file' file is inserted instead.
+If a function, the result from the function is used.
+If a form, the result from the form is used.
+See `mail-signature' for the recommended format of a signature."
   :version "23.2"
   :type '(choice string (const :tag "Contents of signature file" t)
 		 function
-		 sexp)
+		 sexp
+                 (const :tag "None" nil))
   :risky t
   :link '(custom-manual "(message)Insertion Variables")
   :group 'message-insertion)
diff --git i/lisp/mail/sendmail.el w/lisp/mail/sendmail.el
index 50dd81039e..af5270fbd9 100644
--- i/lisp/mail/sendmail.el
+++ w/lisp/mail/sendmail.el
@@ -370,6 +370,7 @@ mail-mode-map
 ;;;###autoload
 (defcustom mail-signature t
   "Text inserted at end of mail buffer when a message is initialized.
+If nil, no signature is inserted.
 If t, it means to insert the contents of the file `mail-signature-file'.
 If a string, that string is inserted.
  (To make a proper signature, the string should begin with \\n\\n-- \\n,

bug#32680: 27.0.50; Improve docstring and customization for 'message-signature'

[Glenn Morris]

Robert Pluim wrote:

> -If t, the `message-signature-file' file will be inserted instead.
> -If a function, the result from the function will be used instead.
> -If a form, the result from the form will be used instead."
> +If nil, no signature is inserted.
> +If t, the `message-signature-file' file is inserted instead.
> +If a function, the result from the function is used.
> +If a form, the result from the form is used.
> +See `mail-signature' for the recommended format of a signature."

To me, "active" would be:

If nil, don't insert a signature.
If t, insert `message-signature-file'.
If a function or form, insert its result.

bug#32680: 27.0.50; Improve docstring and customization for 'message-signature'

[Lars Ingebrigtsen]

Robert Pluim <rpluim@gmail.com> writes:

> 2018-09-10  Robert Pluim  <rpluim@gmail.com>
>
> 	* lisp/gnus/message.el (message-signature): Allow nil as a
> 	customizable value, and describe its effect.
> 	* lisp/mail/sendmail.el (mail-signature): Describe effect of nil value.

Thanks; I've now applied this to Emacs 27.1 with Glenn's tweaks to the
text.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no