Re: The netsec thread

[Eli Zaretskii <eliz@gnu.org>]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: rpluim@gmail.com,  emacs-devel@gnu.org
> Date: Fri, 23 Aug 2019 11:58:37 +0200
> 
> @item @acronym{RC4} stream cipher
> The @acronym{RC4} stream cipher is believed to be of low quality and
> may allow eavesdropping by third parties.  (This is the @code{rc4}
> check in @code{network-security-protocol-checks}).
> 
> I think this is of interest of absolutely zero reading the Emacs manual,
> and is basically security showoffery.  (That's a word.)  The user just
> needs to know that we're doing a best-effort er effort to adhere to best
> practices, and if they're really really interested, they can read the
> doc string to, say, `nsm-protocol-check--dhe-prime-kx', or any of the
> other `nsm-protocol-check--*' functions, each of which has an essay in
> the doc string now.
> 
> So I'd like to propose to remove most of the text about the specific
> tests in the "Network Security" node in the Emacs manual (saving
> precious pages) and just refer the user to the doc strings.

I'm firmly against removing existing documentation.  I simply don't
believe it could ever do any harm.

Specifically, regarding these issues, I don't like the paternalistic
attitude "believe us we're doing the best-effort job to adhere to best
practices".  Nothing and no one can assure we know best in every
particular situation, so leaving the knobs for users to DTRT when we
don't cannot be wrong.

I might agree to making the manual descriptions shorter, like
mentioning the variables and pointing to the doc strings for their
detailed descriptions.  But this is only acceptable if the text in the
manual is little more than a copy of the doc string; otherwise we
should enhance the doc strings to tell more.

Thanks.