From 31cacb05643d9156eecbf08c3f958089e391d139 Mon Sep 17 00:00:00 2001
From: Jeremy Stanley <fungi@yuggoth.org>
Date: Wed, 2 Nov 2016 16:52:38 +0000
Subject: [PATCH] Refactor IRC user banning documentation

To make it easier to find in a pinch, the IRC channel banning
documentation is given its own subsection and rearranged to make the
fastest and easiest solution appear as the first documented example.

Change-Id: If4d00927c3ac55a74b6ed1059269dbe872f18079
---
 doc/source/irc.rst | 48 ++++++++++++++++++++++++++++------------------
 1 file changed, 29 insertions(+), 19 deletions(-)

diff --git a/doc/source/irc.rst b/doc/source/irc.rst
index 278dfb7053..60218985d6 100644
--- a/doc/source/irc.rst
+++ b/doc/source/irc.rst
@@ -257,28 +257,13 @@ This is not a comprehensive overview of commands available to individuals
 running IRC channels on Freenode, but a basic overview of some of the common
 commands which may be required for channel operators.
 
-Operator status is required to perform certain commands in your channel like
-inviting users, changing the topic through your client and removing disruptive
-users. To give yourself operator status in a channel, use the following
-command:
+Operator status is sometimes required to perform certain commands in your
+channel (though most everything can be done through `/msg chanserv` commands
+instead if permission flags are set correctly). To give yourself operator
+status in a channel, use the following command:
 
   /msg chanserv op #channel
 
-On some networks, the preferred mechanism for removing a user from a channel is
-a kick. Freenode also supports the "remove" command which is a gentler way to
-simply send a part-like command to the user's client. In most cases, this will
-signal the client not to try to rejoin. Syntax for the removal command is as
-follows (you must be an operator):
-
-  /quote remove #channel nickname :Reason goes here
-
-Note the colon in the syntax, if this is omitted only the first word will
-accompany the removal message.
-
-Banning of disruptive users is also available with the `/ban` command, see your
-client documentation for syntax. You can also add users to Chanserv's auto-kick
-list like so: `/msg chanserv akick <channel_name> add <nick> [optional reason]`
-
 You don't need to become an operator to change the topic, this can be done
 via Chanserv:
 
@@ -293,6 +278,31 @@ Visit the `Freenode Channel Guidelines <https://freenode.net/changuide>`_
 for more information about recommended strategies for running channels on
 Freenode.
 
+Banning Disruptive Users
+========================
+
+The easiest and fastest solution to indefinitely ban an abusive user from a
+channel is to add them to Chanserv's auto-kick list like so::
+
+  /msg chanserv akick <channel_name> add <nick> [optional reason]
+
+This will immediately and anonymously kick them from the channel, and prevent
+them from rejoining until explicitly removed from the akick list again.
+
+On some networks, the preferred mechanism for removing a user from a channel is
+a kick. Freenode also supports the "remove" command which is a gentler way to
+simply send a part-like command to the user's client. In most cases, this will
+signal the client not to try to rejoin. Syntax for the removal command is as
+follows (you must be an operator)::
+
+  /quote remove #channel nickname :Reason goes here
+
+Note the colon in the syntax, if this is omitted only the first word will
+accompany the removal message.
+
+Banning of disruptive users is also available with the `/ban` command, see your
+client documentation for syntax.
+
 Renaming an IRC Channel
 =======================