From 822db3090f8c144833459cb7d3ed9e0422749f5e Mon Sep 17 00:00:00 2001
From: Geert Hauwaerts <geert@hauwaerts.be>
Date: Wed, 30 Jul 2014 14:29:06 +0200
Subject: [PATCH] Syntax rewrite for S-commands

Rewrote the syntax documentation for all commands starting with S.
---
 docs/help/in/save.in       | 22 ++++++++++++---
 docs/help/in/sconnect.in   | 23 +++++++++++++--
 docs/help/in/script.in     | 29 +++++++++++++------
 docs/help/in/scrollback.in | 45 ++++++++++++++++++++---------
 docs/help/in/set.in        | 38 ++++++++++++++++---------
 docs/help/in/silence.in    | 41 +++++++++++++++------------
 docs/help/in/squit.in      | 18 ++++++++++--
 docs/help/in/stats.in      | 58 +++++++++++++++++++++++++-------------
 docs/help/in/statusbar.in  | 36 +++++++++++++++++++----
 9 files changed, 222 insertions(+), 88 deletions(-)

diff --git a/docs/help/in/save.in b/docs/help/in/save.in
index 8ab25f29..14e29172 100644
--- a/docs/help/in/save.in
+++ b/docs/help/in/save.in
@@ -1,10 +1,24 @@
 
+%9Syntax:%9
+
 @SYNTAX:save@
 
-     -formats: Save all /FORMATs into theme file
+%9Parameters:%9
 
-Saves the current Irssi configuration into the configuration
-file.
+    -formats:    Saves all the formats into the theme file.
 
-See also: RELOAD
+    The file to save the configuration or theme into; if no parameter is given,
+    the active configuration or theme file will be used.
+
+%9Description:%9
+
+    Saves the configuration file.
+
+%9Examples:%9
+
+    /SAVE
+    /SAVE -formats
+    /SAVE ~/.irssi/config-new
+
+%9See also:%9 SET, RELOAD
 
diff --git a/docs/help/in/sconnect.in b/docs/help/in/sconnect.in
index ed07f4f9..47da885f 100644
--- a/docs/help/in/sconnect.in
+++ b/docs/help/in/sconnect.in
@@ -1,8 +1,25 @@
 
+%9Syntax:%9
+
 @SYNTAX:sconnect@
 
-IRC Operator command. Makes an IRC server connect
-to another server. This is CONNECT on the protocol level.
+%9Parameters:%9
 
-See also: OPER, SQUIT, RESTART
+    The server to connect to, the connection port and the remote server that
+    initiates the connection attempt.
+
+    If no remote server is given, the server you are currently connected to will
+    be used.
+
+%9Description:%9
+
+    Connect a server to the IRC network; this command is restricted to IRC
+    operators.
+
+%9Examples:%9
+
+    /SCONNECT ircsource.irssi.org
+    /SCONNECT ircsource.irssi.org 6667 be.hub
+
+%9See also:%9 DIE, KILL, OPER, RESTART, SQUIT
 
diff --git a/docs/help/in/script.in b/docs/help/in/script.in
index 0354512b..e99dd9ba 100644
--- a/docs/help/in/script.in
+++ b/docs/help/in/script.in
@@ -1,19 +1,32 @@
 
+%9Syntax:%9
+
 @SYNTAX:script@
 
-Irssi has very powerful support for scripts written in Perl - they can extend functionality of Irssi in almost unlimited way, and they still keep the client's core unbloated, light and fast. You can control loading and execution of such scripts by this command.
+%9Parameters:%9
 
-Without any parameters, /SCRIPT acts in same way as if you would call /SCRIPT LIST.
+    LIST:          Displays the list of loaded scripts.
+    EXEC:          Executes the given code.
+    LOAD:          Loads the given script into the memory and executes it.
+    UNLOAD:        Unloads the given script from the memory.
+    RESET:         Unloads all the scripts.
+    -permanent:    In combination with EXEC, the code will be loaded into the
+                   memory.
 
-/SCRIPT LIST displays list of all currently loaded scripts, together with full path to their source files.
+    If no argument is given, the list of active scripts will be displayed.
 
-/SCRIPT EXEC executes the <commands> as a little perl script. It doesn't preserve it loaded in memory, unless -permanent is specified.
+%9Description:%9
 
-/SCRIPT LOAD loads the <script> in memory and executes it.
+    Interact with the Perl engine to execute scripts.
 
-/SCRIPT UNLOAD unloads the <script> from memory.
+%9Examples:%9
 
-/SCRIPT RESET unloads all loaded scripts and resets the perl interpreter.
+    /SCRIPT
+    /SCRIPT LIST
+    /SCRIPT LOAD ~/.irssi/scripts/nickserv.pl
+    /SCRIPT UNLOAD nickserv
+    /SCRIPT RESET
+    /SCRIPT EXEC foreach my $channel (Irssi::channels()) { Irssi::print($channel->{name} . " @ " . $channel->{server}->{tag}); }
 
-See also: LOAD, UNLOAD
+%9See also:%9 LOAD, SAVE, UNLOAD
 
diff --git a/docs/help/in/scrollback.in b/docs/help/in/scrollback.in
index 4124cf6f..9f303491 100644
--- a/docs/help/in/scrollback.in
+++ b/docs/help/in/scrollback.in
@@ -1,20 +1,37 @@
 
+%9Syntax:%9
+
 @SYNTAX:scrollback@
 
-/SCROLLBACK, or the default alias /SB:
+%9Parameters:%9
 
-/SB LEVELCLEAR
-   - Remove lines with level matching one of those
-     specified in the comma-separated list <level>.
-/SB CLEAR
-   - Clear screen, free all memory used by texts in window.
-/SB HOME
-   - Jump to start of the buffer.
-/SB END
-   - Jump to end of the buffer.
-/SB GOTO [[-|+]line#|time]
-   - Jump to specified line or timestamp.
-     time format is [dd[.mm] | -<days ago>] hh:mi[:ss].
+    CLEAR:         Clears the screen and the buffer of all text.
+    LEVELCLEAR:    Clears the screen and the buffer of text matching the given
+                   levels.
+    GOTO:          Go to the given position.
+    HOME:          Go to the start of the buffer.
+    END:           Go to the end of the buffer.
 
-See also: SET SCROLL
+    -all:          Applies to all windows instead of only the active one.
+    -level:        The levels, separated by a comman, to match.
+
+    The line number, timestamp to jump to or the window reference number to
+    clear.
+
+%9Description:%9
+
+    Manipulate the text in the window to go to a to the given line number, or
+    clear the buffers.
+
+    The timestamp format is format is "[dd[.mm] | -<days ago>] hh:mi[:ss]".
+
+%9Examples:%9
+
+    /SCROLLBACK CLEAR
+    /SCROLLBACK LEVELCLEAR -level NOTICES
+    /SCROLLBACK GOTO 100
+    /SCROLLBACK HOME
+    /SCROLLBACK END
+
+%9See also:%9 CLEAR, WINDOW
 
diff --git a/docs/help/in/set.in b/docs/help/in/set.in
index e355aaba..1639829a 100644
--- a/docs/help/in/set.in
+++ b/docs/help/in/set.in
@@ -1,23 +1,33 @@
 
+%9Syntax:%9
+
 @SYNTAX:set@
 
-You can view or change the settings with /SET command.
+%9Parameters:%9
 
-/SET without any arguments displays all the settings.
-/SET <key> displays settings whose key (partly) matches <key>
-/SET <key> <value> sets <key> to <value>
+    -clear:      Removes the setting's value from the configuration.
+    -default:    Restore the setting to its default value.
 
-Boolean settings accept only values ON, OFF and TOGGLE. You can
-also use /TOGGLE command to change them, so /TOGGLE <key> behaves
-like /SET <key> TOGGLE. /TOGGLE also accepts arguments ON and OFF
-when /TOGGLE behaves exactly like /SET.
+    The setting and the value; if no value is given, the list of settings that
+    matched will be returned. If no arguments are given, all the settings will
+    be displayed.
 
-Remember that changes are not saved until you use /SAVE!
+%9Description:%9
 
-Examples:
-   /SET autolog OFF    - Sets value for setting 'autolog'
-   /SET close          - Shows all settings whose variable name
-                         contains 'close'. Very practical.
+    Modifies the value of a setting; boolean settings accept only ON, OFF and
+    TOGGLE.
+    
+    Please remember that you need to use the SAVE command to store the changes
+    into your configuration.
 
-See also: TOGGLE
+%9Examples:%9
+
+    /SET
+    /SET nick mike
+    /SET -clear nick
+    /SET log_timestamp %H:%H:%S
+    /SET -default log_timestamp
+    /SET close
+
+%9See also:%9 SAVE, TOGGLE
 
diff --git a/docs/help/in/silence.in b/docs/help/in/silence.in
index d4562cf7..b998c717 100644
--- a/docs/help/in/silence.in
+++ b/docs/help/in/silence.in
@@ -1,24 +1,29 @@
 
+%9Syntax:%9
+
 @SYNTAX:silence@
 
-Works only in some IRC networks.
+%9Parameters:%9
 
-SILENCE is similar in many respects to IGNORE, except that it is 
-server-based. What this means is the server will never even send 
-you messages from anyone you have silenced, whereas it will with
-IGNORE, where your client is responsible for filtering the messages 
-out. This has the advantage of not bogging your client down with 
-excessive data as it tries to filter out messages. The silence list
-is lost when you disconnect. SILENCE only affects private messages
-and invites.
+    The nickname or hostname to silence; you must prepend it by the "+" or "-"
+    character to indicate whether the entry should be added or removed.
 
-The default behavior is to SILENCE a nick!user@host pattern, and 
-if such a pattern is not passed as the argument, it must be prepended 
-with a plus ('+') to be added to your silence list. If a pattern is 
-prepended with a minus ('-'), it will be removed from your silence list. 
-If you only specify a nickname, you can list the patterns in the 
-silence list owned by that nickname. If no arguments are given, your 
-own silence list is displayed. 
- 
-See also: IGNORE, ACCEPT
+    If no arguments are given, the list of silence entries will be displayed.
+
+%9Description:%9
+
+    Manages the server side ignore list; users or hostnames that match an entry
+    on the list are not able to send you any messages or invites.
+
+    This command does not work on all IRC networks.
+
+%9Examples:%9
+
+    /SILENCE
+    /SILENCE +mike
+    /SILENCE -mike
+    /SILENCE +*!*@*.irssi.org
+    /SILENCE -*!*@*.irssi.org
+
+%9See also:%9 ACCEPT, IGNORE
 
diff --git a/docs/help/in/squit.in b/docs/help/in/squit.in
index ab888781..b45a308f 100644
--- a/docs/help/in/squit.in
+++ b/docs/help/in/squit.in
@@ -1,8 +1,20 @@
 
+%9Syntax:%9
+
 @SYNTAX:squit@
 
-IRC Operator command. Splits the given server and all servers
-behind it from your side of the IRC network.
+%9Parameters:%9
 
-See also: SCONNECT, OPER, DIE, RESTART
+    The server and the disconnect reason.
+
+%9Description:%9
+
+    Disconnects a server from the IRC network; this command is restricted to
+    IRC operators.
+
+%9Examples:%9
+
+    /SQUIT ircsource.irssi.org I'm fixing a desync!
+
+%9See also:%9 DIE, OPER, SCONNECT
 
diff --git a/docs/help/in/stats.in b/docs/help/in/stats.in
index 5de453f5..80f16707 100644
--- a/docs/help/in/stats.in
+++ b/docs/help/in/stats.in
@@ -1,23 +1,43 @@
 
+%9Syntax:%9
+
 @SYNTAX:stats@
 
-Shows some irc server usage statistics. Available types vary slightly
-per server; some common ones are:
-  c - Shows C and N lines for a given server.  These are 
-      the names of the servers that are allowed to connect.
-  h - Shows H and L lines for a given server (Hubs and Leaves).
-  k - Show K lines for a server.  This shows who is not 
-      allowed to connect and possibly at what time they are
-      not allowed to connect.
-  i - Shows I lines. This is who CAN connect to a server.
-  l - Shows information about amount of information passed
-      to servers and users.
-  m - Shows a count for the number of times the various 
-      commands have been used since the server was booted.
-  o - Shows the list of authorized operators on the server.
-  p - Shows online operators and their idle times.
-  u - Shows the uptime for a server.
-  y - Shows Y lines, which lists the various connection 
-      classes for a given server.
-  ? - Shows information about servers connected to a server.
+%9Parameters:%9
+
+    The statistic identifier and the remote server; if no remote server is
+    given, the active server will be used.
+
+%9Description:%9
+
+    Displays statistics from the IRC server; some statistics require you to have
+    IRC operators privileges and might differ between IRC networks.
+
+    Common statistics:
+
+        C:    Displays the servers the server may connect to.
+        H:    Displays hub server the server may connect to.
+        K:    Displays the permanent blacklist of hostnames which are prohibited
+              from connecting to the server.
+        k:    Displays the temporary blacklist of hostname which are prohibited
+              from connecting to the server.
+        I:    Displays the list of hostnames which are allowed to connect to the
+              server.
+        L:    Displays the list of connected users and servers.
+        M:    Displays the list of commands and how many times they have been
+              issued.
+        O:    Displays the list of hostnames and users which are allowed to
+              become IRC operators.
+        P:    Displays the ports the server is listening on.
+        p:    Displays the IRC operators and their idle time.
+        u:    Displays the uptime of the server.
+        Y:    Displays the list of connection groups users are placed into.
+        ?:    Displays information about the utilized bandwidth.
+
+%9Examples:%9
+
+    /STATS p
+    /STATS I ircsource.irssi.org
+
+%9See also:%9 MOTD, OPER
 
diff --git a/docs/help/in/statusbar.in b/docs/help/in/statusbar.in
index e7b35349..ac475dd5 100644
--- a/docs/help/in/statusbar.in
+++ b/docs/help/in/statusbar.in
@@ -1,10 +1,36 @@
 
+%9Syntax:%9
+
 @SYNTAX:statusbar@
 
-Commands for modifying the statusbar.
+%9Parameters:%9
 
-/STATUSBAR
-   - Display all statusbars.
+    ENABLE:       Enables the statusbar.
+    DISABLE:      Disabled the statusbar.
+    RESET:        Restores the default statusbar configuration.
+    TYPE:         Identifies the type of statusbar.
+    PLACEMENT:    Identifies the placement of the statusbar.
+    POSITION:     Identifies the position of the statusbar.
+    VISIBLE:      Identifies the visibility of the statusbar.
+    ADD:          Adds a statusbar into the configuration.
+    REMOVE:       Removes a statusbar from the configuration.
+
+    The name of the statusbar; if no argument is given, the list of statusbars
+    will be displayed.
+
+%9Description:%9
+
+    Modified the attributes of the statusbar.
+
+%9Examples:%9
+
+    /STATUSBAR
+    /STATUSBAR window
+    /STATUSBAR window REMOVE time
+    /STATUSBAR window ADD time
+    /STATUSBAR window RESET
+    /STATUSBAR topic DISABLE
+    /STATUSBAR topic ENABLE
+
+%9See also:%9 WINDOW
 
-/STATUSBAR <name>
-   - display elements of statusbar <name>