bug#47128: 28.0.50; Be more helpful regarding message-syntax-checks

bug#47128: 28.0.50; Be more helpful regarding message-syntax-checks

[Eric Abrahamsen]

[-- Attachment #1: Type: text/plain, Size: 878 bytes --]


The `message-syntax-checks' option doesn't have a very useful
customization :type, and the manual section explaining what it does
isn't in the most obvious spot. This patch moves the manual explanation
from "News Headers" to the more general "Message Headers" section, as
the option governs both mail and news. It also expands the :type
definition to explicitly list all the possible options.

The defcustom originally had two comments on it, one saying "Guess this
one shouldn't be easy to customize...", and another on the :type line
saying "improve this". That seems a bit contradictory.

Anyway, I don't see the point of actually obfuscating the use of this
option; this patch should make it a little more discoverable.

What would be even better is to obsolete this in favor of a new
`message-disabled-syntax-checks' option that was simply a plain list of
symbols.

Eric


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Improvements-to-message-syntax-checks-docs-and-optio.patch --]
[-- Type: text/x-patch, Size: 8424 bytes --]

From e9c6ce1195200916f1ce4ee428ca1379de4d4f44 Mon Sep 17 00:00:00 2001
From: Eric Abrahamsen <eric@ericabrahamsen.net>
Date: Sat, 13 Mar 2021 14:25:47 -0800
Subject: [PATCH] Improvements to message-syntax-checks docs and options

* doc/misc/message.texi: Move the manual entry from the "News Headers"
section to the "Message Headers" section, as it is generally
applicable, not just to News.
* lisp/gnus/message.el (message-syntax-checks): Add an explicit alist
type specifying the valid options; point to the manual for more
information.
---
 doc/misc/message.texi | 163 +++++++++++++++++++++---------------------
 lisp/gnus/message.el  |  22 +++---
 2 files changed, 94 insertions(+), 91 deletions(-)

diff --git a/doc/misc/message.texi b/doc/misc/message.texi
index 1497c710e4..d2353e6cec 100644
--- a/doc/misc/message.texi
+++ b/doc/misc/message.texi
@@ -1792,8 +1792,89 @@ Message Headers
 @code{message-carefully-insert-headers} will not insert a @code{To}
 header when the message is already @code{CC}ed to the recipient.
 
+@item message-syntax-checks
+@vindex message-syntax-checks
+Controls what syntax checks should not be performed on outgoing posts.
+To disable checking of long signatures, for instance, add
+
+@lisp
+(signature . disabled)
+@end lisp
+
+to this list.
+
+Valid checks are:
+
+@table @code
+@item approved
+@cindex approved
+Check whether the article has an @code{Approved} header, which is
+something only moderators should include.
+@item continuation-headers
+Check whether there are continuation header lines that don't begin with
+whitespace.
+@item control-chars
+Check for invalid characters.
+@item empty
+Check whether the article is empty.
+@item existing-newsgroups
+Check whether the newsgroups mentioned in the @code{Newsgroups} and
+@code{Followup-To} headers exist.
+@item from
+Check whether the @code{From} header seems nice.
+@item illegible-text
+Check whether there is any non-printable character in the body.
+@item invisible-text
+Check whether there is any invisible text in the buffer.
+@item long-header-lines
+Check for too long header lines.
+@item long-lines
+@cindex long lines
+Check for too long lines in the body.
+@item message-id
+Check whether the @code{Message-ID} looks syntactically ok.
+@item multiple-headers
+Check for the existence of multiple equal headers.
+@item new-text
+Check whether there is any new text in the messages.
+@item newsgroups
+Check whether the @code{Newsgroups} header exists and is not empty.
+@item quoting-style
+Check whether text follows last quoted portion.
+@item repeated-newsgroups
+Check whether the @code{Newsgroups} and @code{Followup-To} headers
+contains repeated group names.
+@item reply-to
+Check whether the @code{Reply-To} header looks ok.
+@item sender
+@cindex Sender
+Insert a new @code{Sender} header if the @code{From} header looks odd.
+@item sendsys
+@cindex sendsys
+Check for the existence of version and sendsys commands.
+@item shoot
+Check whether the domain part of the @code{Message-ID} header looks ok.
+@item shorten-followup-to
+Check whether to add a @code{Followup-To} header to shorten the number
+of groups to post to.
+@item signature
+Check the length of the signature.
+@item size
+Check for excessive size.
+@item subject
+Check whether the @code{Subject} header exists and is not empty.
+@item subject-cmsg
+Check the subject for commands.
+@item valid-newsgroups
+Check whether the @code{Newsgroups} and @code{Followup-To} headers
+are valid syntactically.
 @end table
 
+All these conditions are checked by default, except for @code{sender}
+for which the check is disabled by default if
+@code{message-insert-canlock} is non-@code{nil} (@pxref{Canceling News}).
+
+@end table
 
 @node Mail Headers
 @section Mail Headers
@@ -2072,88 +2153,6 @@ News Headers
 
 @table @code
 
-@item message-syntax-checks
-@vindex message-syntax-checks
-Controls what syntax checks should not be performed on outgoing posts.
-To disable checking of long signatures, for instance, add
-
-@lisp
-(signature . disabled)
-@end lisp
-
-to this list.
-
-Valid checks are:
-
-@table @code
-@item approved
-@cindex approved
-Check whether the article has an @code{Approved} header, which is
-something only moderators should include.
-@item continuation-headers
-Check whether there are continuation header lines that don't begin with
-whitespace.
-@item control-chars
-Check for invalid characters.
-@item empty
-Check whether the article is empty.
-@item existing-newsgroups
-Check whether the newsgroups mentioned in the @code{Newsgroups} and
-@code{Followup-To} headers exist.
-@item from
-Check whether the @code{From} header seems nice.
-@item illegible-text
-Check whether there is any non-printable character in the body.
-@item invisible-text
-Check whether there is any invisible text in the buffer.
-@item long-header-lines
-Check for too long header lines.
-@item long-lines
-@cindex long lines
-Check for too long lines in the body.
-@item message-id
-Check whether the @code{Message-ID} looks syntactically ok.
-@item multiple-headers
-Check for the existence of multiple equal headers.
-@item new-text
-Check whether there is any new text in the messages.
-@item newsgroups
-Check whether the @code{Newsgroups} header exists and is not empty.
-@item quoting-style
-Check whether text follows last quoted portion.
-@item repeated-newsgroups
-Check whether the @code{Newsgroups} and @code{Followup-To} headers
-contains repeated group names.
-@item reply-to
-Check whether the @code{Reply-To} header looks ok.
-@item sender
-@cindex Sender
-Insert a new @code{Sender} header if the @code{From} header looks odd.
-@item sendsys
-@cindex sendsys
-Check for the existence of version and sendsys commands.
-@item shoot
-Check whether the domain part of the @code{Message-ID} header looks ok.
-@item shorten-followup-to
-Check whether to add a @code{Followup-To} header to shorten the number
-of groups to post to.
-@item signature
-Check the length of the signature.
-@item size
-Check for excessive size.
-@item subject
-Check whether the @code{Subject} header exists and is not empty.
-@item subject-cmsg
-Check the subject for commands.
-@item valid-newsgroups
-Check whether the @code{Newsgroups} and @code{Followup-To} headers
-are valid syntactically.
-@end table
-
-All these conditions are checked by default, except for @code{sender}
-for which the check is disabled by default if
-@code{message-insert-canlock} is non-@code{nil} (@pxref{Canceling News}).
-
 @item message-ignored-news-headers
 @vindex message-ignored-news-headers
 Regexp of headers to be removed before posting.  The default is@*
diff --git a/lisp/gnus/message.el b/lisp/gnus/message.el
index 1e0362a3bf..3eaf8ed162 100644
--- a/lisp/gnus/message.el
+++ b/lisp/gnus/message.el
@@ -186,22 +186,26 @@ message-insert-canlock
 
 (defcustom message-syntax-checks
   (if message-insert-canlock '((sender . disabled)) nil)
-  ;; Guess this one shouldn't be easy to customize...
   "Controls what syntax checks should not be performed on outgoing posts.
 To disable checking of long signatures, for instance, add
  `(signature . disabled)' to this list.
 
 Don't touch this variable unless you really know what you're doing.
 
-Checks include `approved', `bogus-recipient', `continuation-headers',
-`control-chars', `empty', `existing-newsgroups', `from', `illegible-text',
-`invisible-text', `long-header-lines', `long-lines', `message-id',
-`multiple-headers', `new-text', `newsgroups', `quoting-style',
-`repeated-newsgroups', `reply-to', `sender', `sendsys', `shoot',
-`shorten-followup-to', `signature', `size', `subject', `subject-cmsg'
-and `valid-newsgroups'."
+See the Message manual for the meanings of the valid syntax check
+types."
   :group 'message-news
-  :type '(repeat sexp))			; Fixme: improve this
+  :link '(custom-manual "(message)Message Headers")
+  :type '(alist
+	  :key-type symbol
+	  :value-type (const disabled)
+	  :options (approved bogus-recipient continuation-headers
+		    control-chars empty existing-newsgroups from illegible-text
+		    invisible-text long-header-lines long-lines message-id
+		    multiple-headers new-text newgroups quoting-style
+		    repeated-newsgroups reply-to sender sendsys shoot
+		    shorten-followup-to signature size subject subject-cmsg
+		    valid-newsgroups)))
 
 (defcustom message-required-headers '((optional . References)
 				      From)
-- 
2.30.1

bug#47128: 28.0.50; Be more helpful regarding message-syntax-checks

[Eric Abrahamsen]

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> The `message-syntax-checks' option doesn't have a very useful
> customization :type, and the manual section explaining what it does
> isn't in the most obvious spot. This patch moves the manual explanation
> from "News Headers" to the more general "Message Headers" section, as
> the option governs both mail and news. It also expands the :type
> definition to explicitly list all the possible options.
>
> The defcustom originally had two comments on it, one saying "Guess this
> one shouldn't be easy to customize...", and another on the :type line
> saying "improve this". That seems a bit contradictory.
>
> Anyway, I don't see the point of actually obfuscating the use of this
> option; this patch should make it a little more discoverable.
>
> What would be even better is to obsolete this in favor of a new
> `message-disabled-syntax-checks' option that was simply a plain list of
> symbols.

I feel like this is fairly uncontroversial -- does anyone have any
objections? I may just go ahead and push, otherwise. (I've since tweaked
the patch so that `message-syntax-checks' belongs to the
'message-headers group, in line with the other changes.)

bug#47128: 28.0.50; Be more helpful regarding message-syntax-checks

[Lars Ingebrigtsen]

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

>> What would be even better is to obsolete this in favor of a new
>> `message-disabled-syntax-checks' option that was simply a plain list of
>> symbols.
>
> I feel like this is fairly uncontroversial -- does anyone have any
> objections? I may just go ahead and push, otherwise. (I've since tweaked
> the patch so that `message-syntax-checks' belongs to the
> 'message-headers group, in line with the other changes.)

The patch looks fine to me -- obsoleting the variable in favour of an
opposite variable doesn't seem to be optimal, though.

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

bug#47128: 28.0.50; Be more helpful regarding message-syntax-checks

[Eric Abrahamsen]

On 04/13/21 09:47 AM, Lars Ingebrigtsen wrote:
> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>>> What would be even better is to obsolete this in favor of a new
>>> `message-disabled-syntax-checks' option that was simply a plain list of
>>> symbols.
>>
>> I feel like this is fairly uncontroversial -- does anyone have any
>> objections? I may just go ahead and push, otherwise. (I've since tweaked
>> the patch so that `message-syntax-checks' belongs to the
>> 'message-headers group, in line with the other changes.)
>
> The patch looks fine to me -- obsoleting the variable in favour of an
> opposite variable doesn't seem to be optimal, though.

That's fine, it wasn't a big deal -- it just seemed oddly verbose to
require the 'disabled symbol, when 'disabled the only viable option. But
no actual harm in it, of course.

Closing this now...