master a08bb27517: ; Fix documentation of recent ERC changes

[Eli Zaretskii]

branch: master
commit a08bb27517e840e14c8bb83dc96307a8771ab990
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; Fix documentation of recent ERC changes
    
    * lisp/erc/erc.el (erc-inhibit-multiline-input)
    (erc-ask-about-multiline-input): Doc fixes.
    
    * doc/misc/erc.texi (Connecting): Fix typos, grammar, wording,
    punctuation, markup, and indexing.
---
 doc/misc/erc.texi | 69 ++++++++++++++++++++++++++++++++-----------------------
 lisp/erc/erc.el   |  7 +++---
 2 files changed, 44 insertions(+), 32 deletions(-)

diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi
index 6daa54d956..cf19f1e32a 100644
--- a/doc/misc/erc.texi
+++ b/doc/misc/erc.texi
@@ -557,6 +557,7 @@ For example, calling the command like so
 (erc :server "irc.libera.chat" :full-name "J. Random Hacker")
 @end example
 
+@noindent
 sets @var{server} and @var{full-name} directly while leaving the rest
 up to functions like @code{erc-compute-port}.  Note that some
 arguments can't be specified interactively.  @var{id}, in particular,
@@ -589,6 +590,7 @@ That is, if called in the following manner
 (erc-tls :server "irc.libera.chat" :full-name "J. Random Hacker")
 @end example
 
+@noindent
 the command will set @var{server} and @var{full-name} accordingly,
 while helpers, like @code{erc-compute-nick}, will determine other
 parameters, and some, like @code{client-certificate}, will just be
@@ -730,14 +732,17 @@ You can manually set another nickname with the /NICK 
command.
 
 @subheading User
 @defun erc-compute-user &optional user
-Determine a suitable value to send for the first argument to the
+Determine a suitable value to send as the first argument of the
 opening @samp{USER} IRC command by consulting the following sources:
 
 @itemize
-@item @var{user}, the argument passed to this function
-@item The option @code{erc-email-userid}, assuming @code{erc-anonymous-login}
+@item
+@var{user}, the argument passed to this function
+@item
+The option @code{erc-email-userid}, assuming @code{erc-anonymous-login}
 is non-@code{nil}
-@item The result of calling the function @code{user-login-name}
+@item
+The result of calling the function @code{user-login-name}
 @end itemize
 
 @end defun
@@ -751,9 +756,9 @@ a string abiding by the rules of the network.
 @cindex password
 
 @defopt erc-prompt-for-password
-If non-@code{nil} (the default), @kbd{M-x erc} prompts for a server
-password.  This only affects interactive invocations of @code{erc} and
-@code{erc-tls}.
+If non-@code{nil} (the default), @kbd{M-x erc} and @kbd{M-x erc-tls}
+prompt for a server password.  This only affects interactive
+invocations of @code{erc} and @code{erc-tls}.
 @end defopt
 
 @noindent
@@ -768,32 +773,33 @@ machine irc.example.net login mynick password sEcReT
 
 @noindent
 For server passwords, that is, passwords sent for the IRC @samp{PASS}
-command, the @samp{host} field, here @code{machine irc.example.net},
+command, the @samp{host} field (@w{@code{machine irc.example.net}} in
+the above example)
 corresponds to the @var{server} parameter used by @code{erc} and
 @code{erc-tls}.  Unfortunately, specifying a network, like
 @samp{Libera.Chat}, or a specific network server, like
-@samp{platinum.libera.chat}, won't work OOTB for looking up a server
+@samp{platinum.libera.chat}, won't normally work for looking up a server
 password because such information isn't available during opening
-introductions.  Actually, ERC @emph{can} find entries with arbitrary
+introductions.  (Actually, ERC @emph{can} find entries with arbitrary
 @samp{host} values for any context, including server passwords, but
-that requires messing with the more advanced options below.
+that requires customizing the more advanced options below.)
 
-If ERC can't find a suitable server password, it'll just skip the IRC
+If ERC can't find a suitable server password, it will just skip the IRC
 @samp{PASS} command altogether, something users may want when using
-CertFP or engaging NickServ via ERC's ``services'' module.  If that
-sounds like you, you can also set the option
+CertFP or engaging NickServ via ERC's ``services'' module.  If that is
+what you'd like to do, you can also customize the option
 @code{erc-auth-source-server-function} to @code{nil} to skip
 server-passwork lookup for all servers.  Note that some networks and
 IRCds may accept account-services authentication via server password
-using the nonstandard ``mynick:sEcReT'' convention.
+using the nonstandard @samp{mynick:sEcReT} convention.
 
 As just mentioned, you can also use @code{auth-source} to authenticate
 to account services the traditional way, through a bot called
-``NickServ''.  To tell ERC to do that, set
+@samp{NickServ}.  To tell ERC to do that, set
 @code{erc-use-auth-source-for-nickserv-password} to @code{t}.  For
 these and most other queries, entries featuring custom identifiers and
 networks are matched first, followed by network-specific servers and
-dialed endpoints (typically, the @var{SERVER} passed to
+dialed endpoints (typically, the @var{server} argument passed to
 @code{erc}). The following netrc-style entries appear in order of
 precedence:
 
@@ -812,7 +818,7 @@ syntax of your chosen backend medium.  For example, always 
quote
 channel names in a netrc file.
 
 If this all seems overly nuanced or just plain doesn't appeal to you,
-see options @code{erc-auth-source-services-function} and friends just
+see options @code{erc-auth-source-services-function} and friends, described
 below.  These let you query auth-source your way.  Most users can
 simply ignore the passed-in arguments and get by with something like
 the following:
@@ -830,7 +836,7 @@ Lastly, ERC also consults @code{auth-source} to find 
``keys'' that may
 be required by certain channels you join.  When modifying a
 traditional @code{auth-source} entry for this purpose, put the channel
 name in the @samp{user} field (for example, @samp{login "#fsf"}, in
-netrc's case). The actual key goes in the @samp{password} (or
+netrc's case).  The actual key goes in the @samp{password} (or
 @samp{secret}) field.
 
 @noindent
@@ -850,9 +856,10 @@ Generalized names, like @code{:user} and @code{:host}, are 
always used
 over back-end specific ones, like @code{:login} or @code{:machine}.
 ERC expects a string to use as the secret or nil, if the search fails.
 
+@findex erc-auth-source-search
 The default value for all three options is the function
 @code{erc-auth-source-search}.  It tries to merge relevant contextual
-params with those provided or discovered from the logical connection
+parameters with those provided or discovered from the logical connection
 or the underlying transport.  Some auth-source back ends may not be
 compatible; netrc, plstore, json, and secrets are currently supported.
 @end defopt
@@ -866,10 +873,14 @@ This tries a number of increasingly more default methods 
until a
 non-@code{nil} value is found.
 
 @itemize @bullet
-@item @var{full-name} (the argument passed to this function)
-@item The @code{erc-user-full-name} option
-@item The value of the IRCNAME environment variable
-@item The result from the @code{user-full-name} function
+@item
+@var{full-name} (the argument passed to this function)
+@item
+The @code{erc-user-full-name} option
+@item
+The value of the IRCNAME environment variable
+@item
+The result from the @code{user-full-name} function
 @end itemize
 
 @end defun
@@ -884,20 +895,20 @@ This can be either a string or a function to call.
 @subheading ID
 @anchor{Network Identifier}
 
-ERC uses an abstract designation called a @dfn{network context
-identifier} for referring to a connection internally.  While normally
+ERC uses an abstract designation, called @dfn{network context
+identifier}, for referring to a connection internally.  While normally
 derived from a combination of logical and physical connection
 parameters, an ID can also be explicitly provided via an entry-point
-command (like @code{erc-tls}). Use this in rare situations where ERC
+command (like @code{erc-tls}).  Use this in rare situations where ERC
 would otherwise have trouble discerning between connections.
 
 One such situation might arise when using multiple connections to the
-same network with the same nick but different (nonstandard) "device"
+same network with the same nick but different (nonstandard) @samp{device}
 identifiers, which some bouncers may support.  Another might be when
 mimicking the experience offered by popular standalone clients, which
 normally offer ``named'' persistent configurations with server buffers
 reflecting those names.  Yet another use case might involve
-third-party code needing to identify a connection unequivocally but in
+third-party code needing to identify a connection unequivocally, but in
 a human-friendly way suitable for UI components.
 
 When providing an ID as an entry-point argument, strings and symbols
diff --git a/lisp/erc/erc.el b/lisp/erc/erc.el
index 6f17e4ee7b..239d8ebdcb 100644
--- a/lisp/erc/erc.el
+++ b/lisp/erc/erc.el
@@ -261,15 +261,16 @@ node `(auth) Top' and info node `(erc) Connecting'.")
   :type 'boolean)
 
 (defcustom erc-inhibit-multiline-input nil
-  "Conditionally disallow input consisting of multiple lines.
+  "When non-nil, conditionally disallow input consisting of multiple lines.
 Issue an error when the number of input lines submitted for
-sending exceeds this value."
+sending exceeds this value.  The value t means disallow more
+than 1 line of input."
   :package-version '(ERC . "5.4.1") ; FIXME match to next release
   :group 'erc
   :type '(choice integer boolean))
 
 (defcustom erc-ask-about-multiline-input nil
-  "Ask to ignore `erc-inhibit-multiline-input' when tripped."
+  "Whether to ask to ignore `erc-inhibit-multiline-input' when tripped."
   :package-version '(ERC . "5.4.1") ; FIXME match to next release
   :group 'erc
   :type 'boolean)