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

2 files changed, 104 insertions, 40 deletions

diff --git a/docs/Irssi.pod b/docs/Irssi.pod
index c02f852..85b36dd 100644
--- a/docs/Irssi.pod
+++ b/docs/Irssi.pod
@@ -83,6 +83,7 @@ For example:
 
 =head1 METHODS
 
+
 =head2 Accessors
 
 =head3 C<active_win>
@@ -299,12 +300,14 @@ remainder of the string to be processed as desired.
 
 =head4 C<command_runsub $cmd, $data, $server, $item>
 
-Run subcommands for `cmd'. First word in `data' is parsed as
-subcommand. `server' is L<Irssi::Server> record for current
-L<Irssi::Windowitem> `item'.
+Run subcommands for C<$cmd>. First word in C<$data> is parsed as
+subcommand. C<$server> is L<Irssi::Server> record for current
+L<Irssi::Windowitem> C<$item>.
+
+Call command_runsub in handler function for C<$cmd> and bind
+with:
 
-Call command_runsub in handler function for `cmd' and bind
-with command_bind("`cmd' `subcmd'", subcmdfunc[, category]);
+    command_bind("$cmd $subcmd", subcmdfunc[, category]);
 
 See the L<example|Guide/Use Subcommands to Group Script Functionality> for
 further details.
@@ -436,7 +439,8 @@ A time type. B<TODO: what values can it take?>
 
 =item C<level>
 
-An irssi Messagelevel. See C</HELP LEVELS> for a full list and description.
+An irssi Messagelevel. See C</HELP LEVELS> for a full list and description, or
+L</Message Levels> for a description of the Perl equivalents.
 
 =item C<size>
 
@@ -490,14 +494,15 @@ Remove a setting specified with C<$key>.
 
 =head3 C<timeout_add $msecs, $func, $data>
 
-  Call C<$func> every C<$msecs> milliseconds (1/1000th of a second) with
-  parameter C<$data>. Returns a tag which can be used to stop the timeout via
-  L</timeout_remove $tag>.
+Call C<$func> every C<$msecs> milliseconds (1/1000th of a second) with
+parameter C<$data>. Returns a tag which can be used to stop the timeout via
+L</timeout_remove $tag>.
 
 =head3 C<timeout_add_once $msecs, $func, $data>
 
-Call `func' once after `msecs' milliseconds (1000 = 1 second)
-with parameter `data'. Returns tag which can be used to stop the timeout.
+Call C<$func> once after C<$msecs> milliseconds (1000 = 1 second) with parameter
+C<$data>. Returns tag which can be used to stop the timeout via
+L</timeout_remove $tag>.
 
 =head3 C<timeout_remove $tag>
 
@@ -505,43 +510,104 @@ Remove timeout specified with tag C<$tag>.
 
 =head3 C<input_add $source, $condition, $func, $data>
 
-Call `func' with parameter `data' when specified IO happens.
-`source' is the file handle that is being listened. `condition' can
-be INPUT_READ, INPUT_WRITE or both. Returns tag which can be used to
-remove the listener.
+Call C<$func> with parameter C<$data> when specified IO happens.  C<$source> is
+the file handle that is being listened. C<$condition> can be
+C<Irssi::INPUT_READ>, C<Irssi::INPUT_WRITE> or both.  Returns tag which can be
+used to remove the listener with L</input_remove $tag>.
 
 =head3 C<input_remove $tag>
 
-Remove listener with tag.
+Remove listener with C<$tag>.
 
 =head3 C<pidwait_add $pid>
 
-Adds `pid' to the list of processes to wait for. The pid must identify
+Adds C<$pid> to the list of processes to wait for. The pid must identify
 a child process of the irssi process. When the process terminates, a
 "pidwait" signal will be sent with the pid and the status from
 waitpid(). This is useful to avoid zombies if your script forks.
 
 =head3 C<pidwait_remove $pid>
 
-Removes `pid' from the list of processes to wait for. Terminated
+Removes C<$pid> from the list of processes to wait for. Terminated
 processes are removed automatically, so it is usually not necessary
 to call this function.
 
 
 =head2 Message Levels
 
+The standard Irssi levels (as specified in C</HELP LEVELS>) are accessible from
+within scripts with the following zero-arguments functions:
+
+=over
+
+=item C<MSGLEVEL_CRAP>
+
+=item C<MSGLEVEL_MSGS>
+
+=item C<MSGLEVEL_PUBLIC>
+
+=item C<MSGLEVEL_NOTICES>
+
+=item C<MSGLEVEL_SNOTES>
+
+=item C<MSGLEVEL_CTCPS>
+
+=item C<MSGLEVEL_ACTIONS>
+
+=item C<MSGLEVEL_JOINS>
+
+=item C<MSGLEVEL_PARTS>
+
+=item C<MSGLEVEL_QUITS>
+
+=item C<MSGLEVEL_KICKS>
+
+=item C<MSGLEVEL_MODES>
+
+=item C<MSGLEVEL_TOPICS>
+
+=item C<MSGLEVEL_WALLOPS>
+
+=item C<MSGLEVEL_INVITES>
+
+=item C<MSGLEVEL_NICKS>
+
+=item C<MSGLEVEL_DCC>
+
+=item C<MSGLEVEL_DCCMSGS>
+
+=item C<MSGLEVEL_CLIENTNOTICE>
+
+=item C<MSGLEVEL_CLIENTCRAP>
+
+=item C<MSGLEVEL_CLIENTERROR>
+
+=item C<MSGLEVEL_HILIGHT>
+
+=item C<MSGLEVEL_ALL>
+
+=item C<MSGLEVEL_NOHILIGHT>
+
+=item C<MSGLEVEL_NO_ACT>
+
+=item C<MSGLEVEL_NEVER>
+
+=item C<MSGLEVEL_LASTLOG>
+
+=back
+
 =head3 C<level2bits $level>
 
-  Level string -> number
+Level string -> number
 
 =head3 C<bits2level $bits>
 
-  Level number -> string
+Level number -> string
 
 =head3 C<combine_level $level, $str>
 
-  Combine level number to level string ("+level -level").
-  Return new level number.
+Combine level number to level string (C<"+level -level">).
+Return new level number.
 
 
 =head2 Themes
@@ -611,7 +677,6 @@ Update ignore record in configuration
 B<TODO: Document what this does>
 
 
-
 =head2 Logging
 
 =head3 C<log_create_rec $fname, $level>
diff --git a/docs/Irssi/UI/Theme.pod b/docs/Irssi/UI/Theme.pod
index 4fff169..2e69186 100644
--- a/docs/Irssi/UI/Theme.pod
+++ b/docs/Irssi/UI/Theme.pod
@@ -13,7 +13,7 @@ Irssi::UI::Theme
 When testing changes, the easiest way to reload the theme is with /RELOAD.
 This reloads the configuration file too, so if you did any changes remember
 to /SAVE it first. Remember also that /SAVE overwrites the theme file with
-old data so keep backups :)
+old data so keep backups C<:)>
 
 =head2 TEMPLATES
 
@@ -26,9 +26,9 @@ this templating system.
 Now the C</FORMAT>s don't have any colors in them, and they also have very
 little other styling. Most of the stuff you need to change is in this
 theme file. If you can't change something here, you can always go back
-to change the /FORMATs directly, they're also saved in these .theme files.
+to change the /FORMATs directly, they're also saved in the  F<*.theme> files.
 
-So .. the templates. They're those C<{blahblah}> parts you see all over the
+So, the templates. They're those C<{blahblah}> parts you see all over the
 /FORMATs and here. Their usage is simply C<{name parameter1 parameter2}>.
 
 When irssi sees this kind of text, it goes to find "name" from abstracts block
@@ -44,21 +44,20 @@ When irssi expands the templates in "format", the final string would be:
 
   hello %G%Uworld%U%n
 
-ie. underlined bright green "world" text.
-and why C<$0->, why not C<$0>? C<$0> would only mean the first parameter,
-$0- means all the parameters. With {underline hello world} you'd really
-want to underline both of the words, not just the hello (and world would
-actually be removed entirely).
+ie. underlined bright green "world" text.  and why C<$0->, why not C<$0>? C<$0>
+would only mean the first parameter, $0- means all the parameters. With
+{underline hello world} you'd really want to underline both of the words, not
+just the hello (and world would actually be removed entirely).
 
-=head2 COLORS
+=head2 COLOURS
 
 You can find definitions for the color format codes in L<Formats>
 
-There's one difference here though. %n format. Normally it means the
-default color of the terminal (white mostly), but here it means the
-"reset color back to the one it was in higher template". For example
-if there was /FORMAT test %g{foo}bar, and foo = "%Y$0%n", irssi would
-print yellow "foo" (as set with %Y) but "bar" would be green, which was
-set at the beginning before the {foo} template. If there wasn't the %g
-at start, the normal behaviour of %n would occur. If you _really_ want
-to use the terminal's default color, use %N.
+There's one difference here though. C<%n> format. Normally it means the default
+color of the terminal (white mostly), but here it means the "reset color back to
+the one it was in higher template". For example if there was C</FORMAT test
+%g{foo}bar>, and C<foo = "%Y$0%n">, irssi would print yellow C<"foo"> (as set
+with C<%Y>) but C<"bar"> would be green, which was set at the beginning before
+the C<{foo}> template. If there wasn't the C<%g> at start, the normal behaviour
+of C<%n> would occur. If you I<really> want to use the terminal's default color,
+use C<%N>.