added messagelevel docs to irssi.pod, more stuff in guide, and a little script to dump .xs func definitions

1 files changed, 136 insertions, 26 deletions

diff --git a/docs/Formats.pod b/docs/Formats.pod
index 0902d78..0aaca37 100644
--- a/docs/Formats.pod
+++ b/docs/Formats.pod
@@ -6,32 +6,142 @@ Formats
 
 =head1 DESCRIPTION
 
+I<Stuff>
+
+=head1 COLOURS
+
 Irssi's colors that you can use in text formats, hilights, etc:
 
-                           text            text            background
-   ---------------------------------------------------------------------
-   %k      %K      %0      black           dark grey       black
-   %r      %R      %1      red             bold red        red
-   %g      %G      %2      green           bold green      green
-   %y      %Y      %3      yellow          bold yellow     yellow
-   %b      %B      %4      blue            bold blue       blue
-   %m      %M      %5      magenta         bold magenta    magenta
-   %p      %P              magenta (think: purple)
-   %c      %C      %6      cyan            bold cyan       cyan
-   %w      %W      %7      white           bold white      white
-   %n      %N              Changes the color to "default color", removing
-                           all other coloring and formatting. %N is always
-			   the terminal's default color. %n is usually too,
-			   except in themes it changes to "previous color",
-			   ie. hello = "%Rhello%n" and "%G{hello} world"
-			   would print hello in red, and %n would turn back
-			   into %G making world green.
-   %F                      Blinking on/off (think: flash)
-   %U                      Underline on/off
-   %8                      Reverse on/off
-   %9      %_              Bold on/off
-   %:                      Insert newline
-   %|                      Marks the indentation position
-   %#                      Monospace font on/off (useful with lists and GUI)
-   %%                      A single %
+   C1      C2      C3       Text Colour (C1) Text Colour (C2) Background (C3)
+   --------------------------------------------------------------------------
+   %k      %K       %0      black            dark grey        black
+   %r      %R       %1      red              bold red         red
+   %g      %G       %2      green            bold green       green
+   %y      %Y       %3      yellow           bold yellow      yellow
+   %b      %B       %4      blue             bold blue        blue
+   %m      %M       %5      magenta          bold magenta     magenta
+   %p      %P               magenta (think: purple)
+   %c      %C       %6      cyan             bold cyan        cyan
+   %w      %W       %7      white            bold white       white
+
+   %n      %N               Changes the color to "default color", removing
+                            all other coloring and formatting. %N is always
+                            the terminal's default color. %n is usually too,
+                            except in themes it changes to "previous color",
+                            ie. hello = "%Rhello%n" and "%G{hello} world"
+                            would print hello in red, and %n would turn back
+                            into %G making world green.
+
+   %F                       Blinking on/off (think: flash)
+   %U                       Underline on/off
+   %8                       Reverse on/off
+   %9      %_               Bold on/off
+   %:                       Insert newline
+   %|                       Marks the indentation position
+   %#                       Monospace font on/off (useful with lists and GUI)
+   %%                       A single %
+
+
+=head1 VARIABLE SYNTAX
+
+Irssi supports a number of reserved, dynamic variables, sometimes
+referred to as I<expandos>.  They are special in that the client is
+constantly updating their values automatically.  There are also
+numerous variable modifiers available.
+
+   Modifier          Description
+   ------------------------------------------------------------------------
+   $variable         A normal variable, expanding to the first match of:
+                     |  1) an internal SET variable
+                     |  2) an environment variable
+   $[num]variable    Expands to the variables value, with 'num' width.  If
+                     | the number is negative, the value is right-aligned.
+                     | The value is padded to meet the width with the
+                     | character given after number (default is space).
+                     | The value is truncated to specified width unless
+                     | '!' character precedes the number. If '.' character
+                     | precedes the number the value isn't padded, just
+                     | truncated.
+   $#variable        Expands to the number of words in $variable. If $variable
+                     | is omitted, it assumes $*
+   $@variable        Expands to the number of characters in $variable. if
+                     | $variable is omitted, it assumes $*
+   $($subvariable)   This is somewhat similar to a pointer, in that the
+                     | value of $subvar is taken as the name of the
+                     | variable to expand to.  Nesting is allowed.
+   ${expression}     Permits the value to be embedded in another string
+                     | unambiguously.
+   $!history!        Expands to a matching entry in the client's command
+                     | history, wildcards allowed.
+
+B<TODO: provide some examples of the various forms of truncation/padding, etc>
+
+=head1 ALIAS AND FORMAT TEMPLATE ARGUMENTS
+
+Whenever an alias is called, these expandos are set to the arguments passed
+to it.  If none of these expandos are used in the alias, or the C<$()> form
+shown above, any arguments passed will automatically be appended to the last
+command in the alias.
+
+   Expando   Description
+   ------------------------------------------------------------------------
+   $*        expands to all arguments passed to an alias
+   $n        expands to argument 'n' passed to an alias (counting from zero)
+   $n-m      expands to arguments 'n' through 'm' passed to an alias
+   $n-       expands to all arguments from 'n' on passed to an alias
+   $-m       expands to all arguments up to 'm' passed to an alias
+   $~        expands to the last argument passed to an alias
+
+=head1 EXPANDOS (SPECIAL VARIABLES)
+
+These variables are set and updated dynamically by the client.  The case of
+C<$A .. $Z> is important.
+
+   Variable   Description
+   ------------------------------------------------------------------------
+   $,         last person who sent you a MSG
+   $.         last person to whom you sent a MSG
+   $:         last person to join a channel you are on
+   $;         last person to send a public message to a channel you are on
+   $A         text of your AWAY message, if any
+   $B         body of last MSG you sent
+   $C         current channel
+   $D         last person that NOTIFY detected a signon for
+   $E         idle time
+   $F         time client was started, $time() format
+   $H         current server numeric being processed
+   $I         channel you were last INVITEd to
+   $J         client version text string
+   $K         current value of CMDCHARS
+   $k         first character in CMDCHARS
+   $L         current contents of the input line
+   $M         modes of current channel, if any
+   $N         current nickname
+   $O         value of STATUS_OPER if you are an irc operator
+   $P         if you are a channel operator in $C, expands to a '@'
+   $Q         nickname of whomever you are QUERYing
+   $R         version of current server
+   $S         current server name
+   $T         target of current input (channel or nick of query)
+   $U         value of cutbuffer
+   $V         client release date (format YYYYMMDD)
+   $W         current working directory
+   $X         your /userhost $N address (user@host)
+   $Y         value of REALNAME
+   $Z         time of day (hh:mm, can be changed with /SET timestamp_format)
+   $$         a literal '$'
 
+   $versiontime         prints time of the irssi version in HHMM format
+   $sysname             system name (eg. Linux)
+   $sysrelease          system release (eg. 2.2.18)
+   $sysarch             system architecture (eg. i686)
+   $topic               channel topic
+   $usermode            user mode
+   $cumode              own channel user mode
+   $cumode_space        like $cumode, but gives space if there's no mode.
+   $tag                 server tag
+   $chatnet             chat network of server
+   $winref              window reference number
+   $winname             window name
+   $itemname            like $T, but use item's visible_name which may be
+                        different (eg. $T = !12345chan, $itemname = !chan)