Merge pull request #2125 from sopel-irc/more-owner-doc-clarification

docs: clarify relationship between `owner` and `owner_account` (again)

[skip ci] because why not, it doesn't touch code.

docs/source/configuration.rst

@@ -131,17 +131,10 @@ on the IRC server the bot connects to.
 Owner & Admins
 --------------
 
-A Sopel instance must have exactly one owner. This is configured either by
-:attr:`~CoreSection.owner_account` if the IRC server supports IRCv3 accounts,
-or by :attr:`~CoreSection.owner`. If ``owner_account`` is set, ``owner`` will
-be ignored.
-
-.. important::
-
-    Even if ``owner_account`` is set, ``owner`` **must** still have a value.
-
-    This is silly, we know. The plan for Sopel 8 is to require only one value
-    or the other.
+A Sopel instance must have exactly one owner. This is configured by the
+:attr:`~CoreSection.owner` setting. If the IRC server supports IRCv3 accounts,
+Sopel can use :attr:`~CoreSection.owner_account` to increase the security of
+ownership verification.
 
 The same instance can have multiple admins. Similarly, it can be configured
 by :attr:`~CoreSection.admin_accounts` or by :attr:`~CoreSection.admins`. If
@@ -151,25 +144,33 @@ Example owner & admin configurations::
 
     # Using nickname matching
     [core]
+    # Will be used for alerts and ownership verification
     owner = dgw
     admins =
             Exirel
             HumorBaby
 
     # Using account matching
     [core]
-    owner_account = dgw
+    # Will be used for alerts only
+    owner = dgw
+    # Will be used for ownership verification
+    owner_account = dgws_account
     admin_accounts =
             Exirel
             HumorBaby
-    # ignored when owner_account is set,
-    # but MUST NOT be empty
-    owner = dgw
 
 Both ``owner_account`` and ``admin_accounts`` are safer to use than
 nick-based matching, but the IRC server must support accounts.
 (Most, sadly, do not as of late 2019.)
 
+.. important::
+
+    The :attr:`~CoreSection.owner` setting should **always** contain the bot
+    owner's nickname, even when using :attr:`~CoreSection.owner_account`. Both
+    Sopel and plugins may send important messages or notices to the owner
+    using ``bot.config.core.owner`` as the recipient.
+
 
 IRC Server
 ==========
@@ -428,23 +429,30 @@ details:
 Example of nick-based authentication with NickServ service::
 
     [core]
-    auth_method = nickserv         # select nick-based auth
+    # select nick-based authentication
+    auth_method = nickserv
     # auth_username is not required for nickserv
-    auth_password = SopelIsGreat!  # your bot's password
-    auth_target = NickServ         # default value
+    # your bot's login password
+    auth_password = SopelIsGreat!
+    # default value
+    auth_target = NickServ
 
 And here is an example of server-based authentication using SASL::
 
     [core]
-    auth_method = sasl             # select server-based auth
-    auth_username = BotAccount     # your bot's username
-    auth_password = SopelIsGreat!  # your bot's password
-    auth_target = PLAIN            # default sasl mechanism
+    # select SASL authentication
+    auth_method = sasl
+    # your bot's login username and password
+    auth_username = BotAccount
+    auth_password = SopelIsGreat!
+    # default SASL mechanism
+    auth_target = PLAIN
 
 Example of authentication to a ZNC bouncer::
 
     [core]
-    auth_method = server           # select server-based auth
+    # select server-based authentication
+    auth_method = server
     # auth_username is not used with server authentication, so instead
     # we combine the ZNC username, network name, and password here:
     auth_password = Sopel/libera:SopelIsGreat!
@@ -484,17 +492,21 @@ When :attr:`~CoreSection.server_auth_method` is defined the settings used are:
 For example, this will use NickServ ``IDENTIFY`` command and SASL mechanism::
 
     [core]
-    # nick-based auth
-    auth_method = nickserv         # select nick-based auth
+    # select nick-based authentication
+    auth_method = nickserv
     # auth_username is not required for nickserv
-    auth_password = SopelIsGreat!  # your bot's password
-    auth_target = NickServ         # default value
-
-    # server-based auth
-    server_auth_method = sasl             # select server-based auth
-    server_auth_username = BotAccount     # your bot's username
-    server_auth_password = SopelIsGreat!  # your bot's password
-    server_auth_target = PLAIN            # default sasl mechanism
+    # your bot's login password
+    auth_password = SopelIsGreat!
+    # default value
+    auth_target = NickServ
+
+    # select SASL authentication
+    server_auth_method = sasl
+    # your bot's login username and password
+    server_auth_username = BotAccount
+    server_auth_password = SopelIsGreat!
+    # default SASL mechanism
+    server_auth_target = PLAIN
 
 .. important::
 
@@ -518,17 +530,21 @@ used are:
 For example, this will use NickServ ``IDENTIFY`` command and SASL mechanism::
 
     [core]
-    # nick-based auth
-    nick_auth_method = nickserv         # select nick-based auth
+    # select nick-based authentication
+    nick_auth_method = nickserv
     # nick_auth_username is not required for nickserv
-    nick_auth_password = SopelIsGreat!  # your bot's password
-    nick_auth_target = NickServ         # default value
-
-    # server-based auth
-    server_auth_method = sasl             # select server-based auth
-    server_auth_username = BotAccount     # your bot's username
-    server_auth_password = SopelIsGreat!  # your bot's password
-    server_auth_target = PLAIN            # default sasl mechanism
+    # your bot's login password
+    nick_auth_password = SopelIsGreat!
+    # default value
+    nick_auth_target = NickServ
+
+    # select SASL auth
+    server_auth_method = sasl
+    # your bot's login username and password
+    server_auth_username = BotAccount
+    server_auth_password = SopelIsGreat!
+    # default SASL mechanism
+    server_auth_target = PLAIN
 
 .. important::
 

docs/source/plugin/anatomy.rst

@@ -136,7 +136,7 @@ manipulation. There are two cases to consider:
 * A :term:`Named rule` is already named (by definition), so it uses its name
   directly as rule label. This can't be overridden by a decorator.
 
-This label is particulary useful for bot owners who want to disable a rule in
+This label is particularly useful for bot owners who want to disable a rule in
 a specific channel. In the following example, the ``say_hello`` rule from the
 ``hello`` plugin is disabled in the ``#rude`` channel: