Syntax documentation rewrite for C-commands

Rewrote the syntax documentation for all the commands starting with the
letter C.

8 files changed, 160 insertions, 75 deletions

diff --git a/docs/help/in/cat.in b/docs/help/in/cat.in
index ea324aa3..981771b7 100644
--- a/docs/help/in/cat.in
+++ b/docs/help/in/cat.in
@@ -1,8 +1,21 @@
 
+Syntax:
+
 @SYNTAX:cat@
 
-Outputs the contents of the specified file. Equivalent to
-UNIX 'cat' command.
+Parameters:
+
+    The file to display.
+
+Description:
+
+    Displays the contents of the specified file into the active window.
+
+Examples:
+
+    /CAT /etc/network/interfaces
+    /CAT /home/mike/unicorns.txt
+    /CAT kitties.txt
 
-See also: CD
+See also: CD,  EXEC
 
diff --git a/docs/help/in/cd.in b/docs/help/in/cd.in
index dd62f710..fad74c3f 100644
--- a/docs/help/in/cd.in
+++ b/docs/help/in/cd.in
@@ -1,8 +1,21 @@
 
+Syntax:
+
 @SYNTAX:cd@
 
-Changes the current working directory. Equivalent to UNIX
-'cd' command.
+Parameters:
+
+    The directory to change into.
+
+Description:
+
+    Changes the current active directory.
+
+Examples:
+
+    /CD /home/public_ftp
+    /CD /home/mike
+    /CD /var/log
 
-See also: DCC GET
+See also: CAT
 
diff --git a/docs/help/in/channel.in b/docs/help/in/channel.in
index eb4154b4..32ac6620 100644
--- a/docs/help/in/channel.in
+++ b/docs/help/in/channel.in
@@ -1,35 +1,39 @@
 
+Syntax:
+
 @SYNTAX:channel@
 
-Irssi can automatically join to specified channels in specified
-IRC networks. It can also automatically send the password when
-manually joining to channel without specifying the password.
+Parameters:
 
-/CHANNEL ADD [-auto | -noauto] [-bots <masks>] [-botcmd <command>]
-             <channel> <network> [<password>]
+    LIST:       Displays the list of configured channels.
+    ADD:        Adds a channel to your configuration.
+    REMOVE:     Removes a channel from your configuration.
 
-With -bots and -botcmd arguments you can automatically send
-commands to someone in channel. This is useful for automatically
-getting ops for channels, for example
+    -auto:      Automatically join the channel.
+    -noauto:    Don't join the channel automatically.
+    -bots:      The list of hostnames send automated commands to.
+    -botcmd:    The automated commands to perform.
 
-/CHANNEL ADD -auto -bots "*!bot@bothost.org bot*!*@host2.org"
-             -botcmd "msg $0 op mypass" #channel ircnet
+    The channel and network to add to the configuration; you can optionally
+    specify the password of a channel.
 
-You can also use the -botcmd without -bots argument. The command is
-then sent whenever you join the channel.
+    If no parameters are given, the list of channels you have joined will be
+    displayed.
+    
+Description:
 
-If you want to remove some settings from existing channel record,
-for example bots, just give the -bots "" parameters to it. Password
-can be removed by setting it to - (or actually, "" works too).
+    Adds, removes or displays the configuration of channels; this method is
+    used to automate and simplify your workflow.
 
-You can remove the channels with
-/CHANNEL REMOVE <channel> <network>
+Examples:
 
-/CHANNEL LIST displays list of channels with settings.
+    /CHANNEL ADD -auto #irssi Freenode
+    /CHANNEL ADD -auto -bots "*!@*.meow.net *!basement@cat.org" -botcmd "msg $0 op myPassword" #hideout Freenode
+    /CHANNEL ADD -auto -bots "Q!TheQBot@CServe.quakenet.org" -botcmd "^MSG Q op #irssi" #irssi Quakenet
 
-/CHANNEL without any arguments displays list of channels you have
-joined. You can also use /CHANNEL to join to channels just as with
-/JOIN, like /CHANNEL #a.
+    /CHANNEL
+    /CHANNEL LIST
+    /CHANNEL REMOVE #hideout Freenode
 
-See also: TS, JOIN
+See also: JOIN, TS
 
diff --git a/docs/help/in/clear.in b/docs/help/in/clear.in
index b3db54ef..fb4172c8 100644
--- a/docs/help/in/clear.in
+++ b/docs/help/in/clear.in
@@ -1,9 +1,19 @@
 
+Syntax:
+
 @SYNTAX:clear@
 
-This command clears the current window of all text. It is useful 
-for wiping a screen that has rendered improperly (such as due 
-to a bad termcap entry) or that contains sensitive information 
-(such as one's OPER password). 
+Parameters:
+
+    -all:    Clear all the windows
+
+    The window number to clear; if no argument is given, the active window
+    is used.
+
+Description:
+
+    Clears the window of all text; you may use this to clear a windows that
+    contains sensitive information or has rendered improperly.
 
+See also: REDRAW
 
diff --git a/docs/help/in/completion.in b/docs/help/in/completion.in
index 1509bf33..68da328b 100644
--- a/docs/help/in/completion.in
+++ b/docs/help/in/completion.in
@@ -1,31 +1,31 @@
 
+Syntax:
+
 @SYNTAX:completion@
 
-Irssi can "complete" some words for you - you can write just first few letters
-of the word and press TAB (or any other key with action word_completion
-assigned). Then, irssi will choose the most probable matching word and inserts
-it to the command line. You can press TAB repetitively and irssi will replace
-the chosen word with another possible words matching to the letters you wrote.
+Parameters:
+
+    -auto:      Insert the completion without pressing a word completion character.
+    -delete:    Removes the completion from the list.
+    
+    A key and the value to use as a replacement. If no argument is given, the
+    list of completions will be displayed.
 
-The words chosen usually depend on their context - they can be filenames or
-command names, but most frequently they are nicks of people on same channels as
-you are. However, you can have global list of own completions, which apply to
-all contexts. This command is dedicated to maintaining of such a list.
+Description:
 
-Without any parameters, /COMPLETION displays list of all user completions.
+    Replaces or completed words or letters; you can write just the first few
+    letters of the word and press TAB to insert a replacement.
 
-/COMPLETION [-auto] <prefix> <string> adds completion which gets triggered when
-you press TAB (or any other key with action word_completion assigned) after
-writing <prefix> specified and which expands to <string>. When -auto is
-specified, the completion gets triggered even when you press SPACE or ENTER (or
-any other key with action check_replaces assigned) after the <prefix>. If
-there's already some <prefix> completion in the list, it will get replaced.
+    When a replacement has been found, Irssi will choose the most probable
+    matching word and replaces it; you may press TAB repeatedly to swap between
+    matches.
 
-/COMPLETION -delete <prefix> removes completion of <prefix> from the user
-completion list.
+Examples:
 
-Note: When -auto is specified for the <prefix> you want to remove you have to 
-quote it like /COMPLETION -delete '<prefix>'. Works with doublequotes aswell.
+    /COMPLETION w/h without
+    /COMPLETION -auto compr compromised
+    /COMPLETION -delete 'compr'
+    /COMPLETION -delete without
 
 See also: BIND
 
diff --git a/docs/help/in/connect.in b/docs/help/in/connect.in
index c06ce999..69ed91b9 100644
--- a/docs/help/in/connect.in
+++ b/docs/help/in/connect.in
@@ -1,23 +1,38 @@
 
+Syntax:
+
 @SYNTAX:connect@
 
-     -4, -6: specify explicitly whether to use IPv4 or IPv6 address
-     -ssl: use SSL when connecting
-     -ssl_cert: The SSL client certificate file (implies -ssl)
-     -ssl_pkey: The SSL client private key (if not included in the certificate file)
-     -ssl_pass: The password for the SSL client private key or certificate.
-     -ssl_verify: Verify servers SSL certificate
-     -ssl_cafile: File with list of CA certificates (implies -ssl_verify)
-     -ssl_capath: Directory with CA certificates (implies -ssl_verify)
-     -network: the network this connection belongs to
-     -ircnet: Same as -network. Deprecated. Do not use.
-     -host: the host
-     -!: don't autojoin channels
-     -noautosendcmd: don't execute autosendcmd
-     -rawlog: immediately open rawlog after connected
-
-This command makes irssi to connect to specified server.
-Current connections are kept and a new one is created.
-
-See also: SERVER, DISCONNECT, RMRECONNS, SCONNECT
+Parameters:
+
+    -4:             Connect using IPv4.
+    -6:             Connect using IPv6.
+    -ssl:           Connect using SSL encryption.
+    -ssl_cert:      The SSL client certificate file.
+    -ssl_pkey:      The SSL client private key, if not included in the certificate file.
+    -ssl_verify:    Verify the SSL certificate of the server.
+    -ssl_cafile:    The file with the list of CA certificates.
+    -ssl_capath:    The directory which contains the CA certificates.
+    -noproxy:       Ignore the global proxy configuration.
+    -network:       The network this connection belongs to
+    -host:          The hostname you would like to connect from.
+    -rawlog:        Immediately open rawlog after connecting.
+    -!:             Don't autojoin channels.
+    -noautosendcmd: Don't execute autosendcmd.
+
+    A network or server to connect to. You can optionally specify a custom port,
+    password and nickname.
+
+Description:
+
+    Opens a new connection to the specified network or server.
+
+Examples:
+
+    /CONNECT Freenode
+    /CONNECT -6 Freenode
+    /CONNECT -4 -! -host my.cute.hostname.tld -network Freenode orwell.freenode.net
+    /CONNECT kitties.example.com 6667 myPassword BasementCat
+
+See also: DISCONNECT, RMRECONNS, SERVER
 
diff --git a/docs/help/in/ctcp.in b/docs/help/in/ctcp.in
index ce553649..44d03064 100644
--- a/docs/help/in/ctcp.in
+++ b/docs/help/in/ctcp.in
@@ -1,7 +1,23 @@
 
+Syntax:
+
 @SYNTAX:ctcp@
 
-Sends a CTCP message. For example CTCP ACTION, or CTCP VERSION.
+Parameters:
+
+    A target nickname or channel and a command.
+
+Description:
+
+    Sends a CTCP request towards the given target nickname or channel.
+
+Examples:
+
+    /CTCP mike PING
+    /CTCP #irssi VERSION
+    /CTCP bob USERINFO
+    /CTCP sarah CLIENTINFO
+    /CTCP john TIME
 
-See also: ME, ACTION
+See also: ACTION, ME
 
diff --git a/docs/help/in/cycle.in b/docs/help/in/cycle.in
index 3d1ed0c2..3cb28ee4 100644
--- a/docs/help/in/cycle.in
+++ b/docs/help/in/cycle.in
@@ -1,8 +1,22 @@
 
+Syntax:
+
 @SYNTAX:cycle@
 
-Cycles (leaves and joins) the current channel or the specified 
-channel.
+Parameters:
+
+    A channel and the message. If no argument is given, the active channel
+    will be used.
+
+Description:
+
+    Leaves and rejoins a channel.
+
+Examples:
+
+    /CYCLE
+    /CYCLE #irssi
+    /CYCLE #irssi BRB :)
 
 See also: JOIN, PART