Syntax documentation rewrite for J-K commands

Rewrote the syntax documentation for all commands starting with the
letters J and K.

6 files changed, 111 insertions, 45 deletions

diff --git a/docs/help/in/join.in b/docs/help/in/join.in
index c4e21f6e..d27597a8 100644
--- a/docs/help/in/join.in
+++ b/docs/help/in/join.in
@@ -1,15 +1,26 @@
 
+%9Syntax:%9
+
 @SYNTAX:join@
 
-   -window: Join channel, placing channel window item in currently active window
-   -invite: Join last invited channel
-   -<server tag>: Join channel on server with specified tag
+%9Parameters:%9
+
+    -window          Joins a channel in the active window.
+    -invite          Joins the channel you were last invited to.
+    -<server tag>    The server tag on which you want to join the channel.
+
+    The channel names, separated by a commma, to join and the channel key.
+
+%9Description:%9
+
+    Joins the given channels.
 
-Joins a specified channel. Channel names usually begin with #-sign,
-which may be omitted here.
+%9Examples:%9
 
-JOIN is aliased to J by default. Example: /j irssi
-(This joins to the channel #irssi)
+    /JOIN #irssi
+    /JOIN #google secret_lair
+    /JOIN -invite
+    /JOIN -freenode #github,#freenode,#irssi
 
-See also: PART, WINDOW CLOSE
+%9See also:%9 KICK, PART
 
diff --git a/docs/help/in/kick.in b/docs/help/in/kick.in
index 48f58e68..00586059 100644
--- a/docs/help/in/kick.in
+++ b/docs/help/in/kick.in
@@ -1,16 +1,24 @@
 
+%9Syntax:%9
+
 @SYNTAX:kick@
 
-This command "kicks" the specified user off of the specified 
-channel. It is typically used to remove troublemakers, flooders, 
-or people otherwise making a nuisance of themselves on the channel. 
-The reason for the kick is recommended, but not required by the IRC 
-servers.
+%9Parameters%9
+
+    The channel and the nicknames, separated by a comma, to kick from the
+    channel and the reason thereof; if no channel is given, the active channel
+    will be used.
+
+%9Description:%9
+
+    Removes the given nicknames from the specified channel; this command is
+    typically used to remove troublemakers, flooders or people otherwise making
+    a nuisance of themselves.
 
-If the <channel> is omitted, removes the nick from the current
-channel.
+%9Examples:%9
 
-The default alias for /KICK is /K.
+    /KICK mike Please... chill down!
+    /KICK #irssi bob,sarah Stop flooding!
 
-See also: KNOCKOUT
+%9See also:%9 BAN, KICKBAN, KNOCKOUT
 
diff --git a/docs/help/in/kickban.in b/docs/help/in/kickban.in
index aff0cfb2..3aef99cf 100644
--- a/docs/help/in/kickban.in
+++ b/docs/help/in/kickban.in
@@ -1,10 +1,22 @@
 
+%9Syntax:%9
+
 @SYNTAX:kickban@
 
-Kicks off and bans a nick from the current channel.
-A reason for the kick can be supplied.
+%9Parameters:%9
+
+    The channel and the nicknames, separated by a comma, to kickban from the
+    channel and the reason thereof; if no channel is given, the active channel
+    will be used.
+
+%9Description:%9
+
+    Removes and then bans the given nicknames from the specified channel.
+
+%9Examples:%9
 
-Default alias for /KICKBAN is /KB.
+    /KICKBAN mike Please... chill down!
+    /KICKBAN #irssi bob,sarah You guys broke the rules for the last time.
 
-See also: KNOCKOUT, BANTYPE
+%9See also:%9 BAN, KICK, KNOCKOUT
 
diff --git a/docs/help/in/kill.in b/docs/help/in/kill.in
index 338871d9..37bfc584 100644
--- a/docs/help/in/kill.in
+++ b/docs/help/in/kill.in
@@ -1,18 +1,24 @@
 
+%9Syntax:%9
+
 @SYNTAX:kill@
 
-IRC operator command.
+%9Parameters:%9
+
+    The nickname to remove from the network and the reason thereof.
+
+%9Description:%9
+
+    Terminates a nickname's connection from the network; this command is
+    reserved for IRC operators.
+
+    You should not use this command for personal vendettas or for trolling;
+    these practices are generally frowned upon.
 
-KILL is used to forcibly remote a client from the irc network. 
-It works similarly to KICK, except that a reason must be 
-given (even if it is meaningless or flat-out wrong). 
+%9Examples:%9
 
-In general, KILL is useful only as a warning tool for abusive 
-users. Modern irc clients (this one included) have automated 
-means for reconnecting to a server after a disconnection (whether 
-due to a KILL or something else), so KILL is by no means a 
-permanent solution. It is not intended as a means for personal 
-vendettas; this practice is generally frowned upon. 
+    /KILL mike Get off my lawn
+    /KILL bob Stop breaking the network rules!
 
-See also: OPER
+%9See also:%9 DIE, OPER, WALLOPS
 
diff --git a/docs/help/in/knock.in b/docs/help/in/knock.in
index c7b23c56..f5c2cf53 100644
--- a/docs/help/in/knock.in
+++ b/docs/help/in/knock.in
@@ -1,16 +1,30 @@
 
+%9Syntax:%9
+
 @SYNTAX:knock@
 
-Works only in some IRC networks (hybrid-like ircds).
+%9Parameters:%9
+
+    The channel you wish to get invited to.
+
+%9Description:%9
+
+    Sends an invitation request to the channel operators of the target channel;
+    this command may not work on all IRC servers.
+    
+    The following conditions must be met:
 
-KNOCK is a feature that lets you request access to a channel they cannot join without an invite, a key or a raised limit.
+        * You are not banned from the channel.
+        * The channel is not private.
+        * You may not be already in the channel.
+        * The channel must be invite only, have a key or has exceeded its user
+          limit.
 
-The following conditions must be met for KNOCK to work:
+%9Examples:%9
 
- - You are not banned from the channel
- - Channel is not private (+p)
- - You are not already on the channel
- - Channel is invite only (+i), has a key (+k) or limit is full
+    /KNOCK #irssi
+    /KNOCK #freenode
+    /KNOCK #github
 
-When successful KNOCK is issued, it sends a notice to channel operators. Use of KNOCK is rate limited by the server.
+%9See also:%9 INVITE, JOIN
 
diff --git a/docs/help/in/knockout.in b/docs/help/in/knockout.in
index 1d18b533..cbaa8dd7 100644
--- a/docs/help/in/knockout.in
+++ b/docs/help/in/knockout.in
@@ -1,11 +1,26 @@
 
+%9Syntax:%9
+
 @SYNTAX:knockout@
 
-Kicks user off the channel and bans him/her. Ban
-lasts the given number of seconds or 5 minutes
-by default.
+%9Parameters:%9
+
+    The time, expressed in seconds, the nicknames, separated by a comma, and the
+    reason thereof; if no time is provided, the ban will be lifted after 5
+    minutes.
+
+%9Description:%9
+
+    Removes and then bans the given nicknames from the active channel; the ban
+    will be automatically lifted after the specified time.
+
+    The ban will not be lifted if you leave the channel or disconnect from the
+    network.
+
+%9Examples:%9
 
-Default alias for /KNOCKOUT is /KN.
+    /KNOCKOUT 3600 mike Your connection is unstable.
+    /KNOCKOUT bob,sarah Chill down a bit.
 
-See also: BAN, KICK
+%9See also:%9 BAN, KICK, KICKBAN