Syntax documentation rewrite for H-I-commands

10 files changed, 165 insertions, 96 deletions

diff --git a/docs/help/in/connect.in b/docs/help/in/connect.in
index 1dff0538..6eae59a2 100644
--- a/docs/help/in/connect.in
+++ b/docs/help/in/connect.in
@@ -25,7 +25,8 @@
 
 %9Description:%9
 
-    Opens a new connection to the specified network or server. Existing connections are kept.
+    Opens a new connection to the specified network or server; existing
+    connections are kept.
 
 %9Examples:%9
 
diff --git a/docs/help/in/hash.in b/docs/help/in/hash.in
index 62a889f8..32dfc9c7 100644
--- a/docs/help/in/hash.in
+++ b/docs/help/in/hash.in
@@ -1,5 +1,22 @@
 
+%9Syntax:%9
+
 @SYNTAX:hash@
 
-Not available.
+%9Description:%9
+
+    This is an ancient command that is no longer used; if you on an IRC server
+    that supports this command, please contact us to we can update the
+    documentation.
+
+%9Examples:%9
+
+    /HASH
+
+%9References:%9
+
+    http://www.irssi.org
+    https://github.com/irssi
+
+%9See also:%9 DIE, KILL, OPER
 
diff --git a/docs/help/in/help.in b/docs/help/in/help.in
index 318b8204..555e20e1 100644
--- a/docs/help/in/help.in
+++ b/docs/help/in/help.in
@@ -1,13 +1,27 @@
 
+%9Syntax:%9
+
 @SYNTAX:help@
 
-Shows help on commands. Try:
-  /HELP command
+%9Parameters:%9
+
+    The command to display the documentation for; if no argument is given, the
+    list of commands will be displayed.
+
+%9Description:%9
+
+    Displays the documentation for the given command.
+
+%9Examples:%9
+
+    /HELP
+    /HELP AWAY
+    /HELP CONNECT
+
+%9References:%9
 
-Also try, for example:
-  /SET beep
-or
-  /SET auto
+    http://www.irssi.org
+    https://github.com/irssi
 
-See also: 
+%9See also:%9 CONNECT, MSG, NETWORK, SERVER
 
diff --git a/docs/help/in/hilight.in b/docs/help/in/hilight.in
index 89842933..94660a21 100644
--- a/docs/help/in/hilight.in
+++ b/docs/help/in/hilight.in
@@ -1,32 +1,41 @@
 
+%9Syntax:%9
+
 @SYNTAX:hilight@
 
-   -mask: Match only for nick, <text> is a nick mask
-   -regexp: <text> is a regular expression
-   -full: <text> must match to full words
-   -nick: Hilight only the nick, not the whole line (default)
-   -word: Hilight only the word (default with non-public messages)
-   -line: Hilight the whole line with the hilight color.
-   -color: Print the message with <color>. color is in %%code format
-           (see docs/formats.txt)
-   -actcolor: Color to show in statusbar activity, or don't change if %%n.
-   -level: Match only for <level> messages, default is
-           publics,msgs,notices,actions
-   -channels: Match only in <channels> (comma separated list)
-   -priority: Priority to use when multiple hilights match. Default is 0.
+%9Parameters:%9
+
+    -nick:        Highlights only the nickname and not the whole line.
+    -word:        Highlights only the word and not the whole line.
+    -line:        Highlights the whole line.
+    -mask:        Highlights all messages from users matching the mask.
+    -full:        The text must match the full word.
+    -regexp:      The text is a regular expression.
+    -color:       The color the display the highlight in.
+    -actcolor:    The color to mark the highlight activity in the statusbar.
+    -level:       Matches only on the given message level.
+    -channels:    Matches only on the given channels.
+    -priority:    The priority to use when multiple highlights match.
+
+    The text to highlight on; if no argument is given, the list of highlights
+    will be displayed.
+
+%9Description:%9
 
-Examples:
+    Highlights the keyword or pattern to make sure that you don't miss any
+    important messages.
 
-Hilight lines that have "mynick" word:
-  /HILIGHT mynick
+%9Examples:%9
 
-Hilight all messages from "mynick":
-  /HILIGHT -mask mynick!*@*
+    /HILIGHT
+    /HILIGHT mike
+    /HILIGHT -regexp mi+ke+
+    /HILIGHT -mask bob!*@*.google.com -color %%G
+    /HILIGHT -full -color %%G -actcolor %%Y redbull
 
-Hilight lines that were written by nicks from *.fi with bold green
-  /HILIGHT -color %%G -mask *!*@*.fi
+%9References:%9
 
-For regular expressions, see `man 7 regex`.
+    https://github.com/irssi/irssi/blob/master/docs/formats.txt
 
-See also: DEHILIGHT, SET HILIGHT
+%9See also:%9 DEHILIGHT, LEVELS
 
diff --git a/docs/help/in/ignore.in b/docs/help/in/ignore.in
index fbb23fe4..bb7af901 100644
--- a/docs/help/in/ignore.in
+++ b/docs/help/in/ignore.in
@@ -1,59 +1,41 @@
 
+%9Syntax:%9
+
 @SYNTAX:ignore@
 
-    -regexp: <pattern> is a regular expression
-    -full: <pattern> must match to full words
-    -pattern: <pattern> must match to the message's text
-    -except: *DON'T* ignore - overrides an existing ignore.
-    -replies: Ignore replies to nick in channels. For example
-              "/IGNORE -replies *!*@*.fi PUBLIC" ignores everyone
-              from Finland, but also anyone sending message
-              "tofinnishnick: blahblah".
-    -network: Ignore only on this network.
-    -ircnet: Same as -network. Deprecated. Do not use.
-    -channels: Ignore only in channels (comma separated list)
-    -time: <secs> seconds after the ignore is removed
-    <mask>: Either a nick mask or list of channels
-    <levels>: List of levels to ignore. You can use -<level> to remove levels
-              from ignore (/help levels for details).
-    <^levels>: List of levels to NOT ignore
-               (/ignore -except nick notices = /ignore nick ^notices)
-
-
-/IGNORE without any arguments displays list of ignores. If you want to remove
-some levels of the ignore, use /IGNORE <mask> -<level> -<level2> etc
-
-The best match always wins, so you can have:
-    /IGNORE * CTCPS
-    /IGNORE -except *!*@host.org CTCPS
+%9Parameters:%9
+
+    -regexp:      Indicates that the pattern is a regular expression.
+    -full:        Indicates that the pattern must match a full word.
+    -pattern:     The text pattern to ignore.
+    -except:      Negates the ignore.
+    -replies:     Also ignore nicknames who are talking to anyone who matches the ignore.
+    -network:     Ignores only on a specific network.
+    -channels:    Ignores only on specific channels.
+    -time:        The timeout to automatically remove the ignore.
+
+    The mask, channels and levels to ignore; if no argument is provided, the
+    list of ignores will be displayed.
+
+%9Description:%9
 
-Examples:
+    Ignores nicknames or text that matches a pattern.
 
-    /IGNORE * JOINS                         - ignore joins in all channels
-    /IGNORE #channel ALL -PUBLIC -ACTIONS   - ignore all but public/actions
-    /IGNORE #channel -JOINS                 - don't ignore joins anymore
-    /IGNORE -replies *!user@*.host.org ALL  - ignore user and all replies
+%9Examples:%9
 
-Some suggestions for ignoring annoying public aways:
+    /IGNORE
+    /IGNORE * JOINS
+    /IGNORE * CTCPS
+    /IGNORE -except *!*@*.google.com CTCPS
+    /IGNORE #irssi ALL -PUBLIC -ACTIONS
+    /IGNORE -replies *!*@*.google.com ALL
     /IGNORE -regexp -pattern "is (away|gone|back)" * ACTIONS
     /IGNORE *zzz* NICKS
     /IGNORE *afk* NICKS
     /IGNORE *away* NICKS
+    /IGNORE #irssi NO_ACT JOINS PARTS QUITS
+    /IGNORE mike NO_ACT -MSGS
+    /IGNORE -regexp -pattern
 
-The special level "NO_ACT" can be used to ignore activity ("Act:") but not
-actually ignore the message entirely. It is somewhat special because it is
-allowed in addition to another ignore for the same target.
-
-Examples:
-
-  /IGNORE #channel NO_ACT JOINS PARTS QUITS - hide joins, etc from activity
-  /IGNORE nick NO_ACT -MSGS - ignore activity from nick, except for /MSG
-  /IGNORE -regexp -pattern . -except nick NO_ACT HILIGHT
-    - combined with the ignore above show hilights from this nick (needs to be
-      an except as "PUBLIC HILIGHT" still matches public, the regexp is used to
-      have more than one ignore for "nick").
-
-For regular expressions, see `man 7 regex`.
-
-See also: UNIGNORE, SILENCE, ACCEPT
+%9See also:%9 ACCEPT, SILENCE, UNIGNORE
 
diff --git a/docs/help/in/info.in b/docs/help/in/info.in
index 864fe69e..275f349d 100644
--- a/docs/help/in/info.in
+++ b/docs/help/in/info.in
@@ -1,6 +1,21 @@
 
+%9Syntax:%9
+
 @SYNTAX:info@
 
-Shows information about the IRC server software and the current
-server instance.
+%9Parameters:%9
+
+    The server to display the information for; if no argument is given, the
+    active server will be used.
+
+%9Description:%9
+
+    Displays information about the IRC server software.
+
+%9Examples:%9
+
+    /INFO
+    /INFO orwell.freenode.net
+
+%9See also:%9 ADMIN
 
diff --git a/docs/help/in/invite.in b/docs/help/in/invite.in
index 1e7f69b1..7c0babb3 100644
--- a/docs/help/in/invite.in
+++ b/docs/help/in/invite.in
@@ -1,10 +1,21 @@
- 
+
+%9Syntax:%9
+
 @SYNTAX:invite@
 
-Invites the specified nick to the current or specified channel.
+%9Parameters:%9
+
+    The nickname to invite and the channel to invite him or her to; if no
+    channel is given, the active channel will be used.
+
+%9Description:%9
+
+    Invites the specified nick to a channel.
+
+%9Examples:%9
 
-Example:
-   /INVITE buddy #mychannel
+    /INVITE mike
+    /INVITE bob #irssi
 
-See also: MODE
+%9See also:%9 MODE, WHOIS
 
diff --git a/docs/help/in/invitelist.in b/docs/help/in/invitelist.in
index d544754b..e516b31a 100644
--- a/docs/help/in/invitelist.in
+++ b/docs/help/in/invitelist.in
@@ -1,9 +1,20 @@
 
-@SYNTAX:invitelist@
+%9Syntax:%9
 
-Shows the +I modes of the current channel. +I mode
-allows free joins of clients with certain userhost masks
-even if the channel is invite only.
+INVITELIST
 
-See also: INVITE, MODE
+%9Description:%9
+
+    Displays the invitelist for the active channel; nicknames who match the
+    masks will be able to join the channel if its invite only.
+
+    This is not a command, but a default alias.
+
+%9Examples:%9
+
+    /INVITELIST
+
+%9References:%9
+
+    /ALIAS INVITELIST MODE $C +I
 
diff --git a/docs/help/in/ircnet.in b/docs/help/in/ircnet.in
deleted file mode 100644
index 88f28156..00000000
--- a/docs/help/in/ircnet.in
+++ /dev/null
@@ -1,4 +0,0 @@
-IRCNET
-
-Deprecated. Use NETWORK instead.
-
diff --git a/docs/help/in/ison.in b/docs/help/in/ison.in
index 0287a60e..c77e4c59 100644
--- a/docs/help/in/ison.in
+++ b/docs/help/in/ison.in
@@ -1,7 +1,20 @@
 
+%9Syntax:%9
+
 @SYNTAX:ison@
 
-Tells whether specified nicks (space-separated) are online.
+%9Parameters:%9
+
+    The nicknames, separated by space, to check.
+
+%9Description:%9
+
+    Displays whether the specified nicknames are online.
+
+%9Examples:%9
+
+    /ISON mike
+    /ISON sarah bob
 
-See also: WHOIS, WHOWAS, NOTIFY
+%9See also:%9 NOTIFY, WHOAS, WHOIS