added formats, and some copypasta from default.theme comments into theme

11 files changed, 316 insertions, 152 deletions

diff --git a/docs/Formats.pod b/docs/Formats.pod
new file mode 100644
index 0000000..0902d78
--- /dev/null
+++ b/docs/Formats.pod
@@ -0,0 +1,37 @@
+__END__
+
+=head1 NAME
+
+Formats
+
+=head1 DESCRIPTION
+
+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 %
+
diff --git a/docs/Guide.pod b/docs/Guide.pod
index eba0912..b540e75 100644
--- a/docs/Guide.pod
+++ b/docs/Guide.pod
@@ -87,7 +87,8 @@ The C<use vars qw($VERSION %IRSSI)> defines two global variables, which are then
 set below to the appropriate values.
 
 C<use Irssi> tells the script to make the various L<Irssi> support functions available.
-
+Additional parameters passed here with C<qw/.../> can be used to import functions into
+the current script namespace.
 
 
 =head1 COMMONLY SCRIPTED TASKS
@@ -197,6 +198,8 @@ B<TODO: different types of settings>
 
 B<TODO: register/set/get>
 
+B<TODO: Listening for changes and acting accordingly>
+
 =head3 Use Subcommands to Group Script Functionality
 
 A common theme in Irssi scripts is to define commands with a prefix, such as
diff --git a/docs/Irssi.pod b/docs/Irssi.pod
index d67b9aa..c02f852 100644
--- a/docs/Irssi.pod
+++ b/docs/Irssi.pod
@@ -18,8 +18,8 @@ support is available. If not, refer to the F<INSTALL> file for how to recompile
 irssi.
 
 The C<Irssi> package is the basis of Perl scripting in Irssi. It does not export any
-functions, and requires that all function-calls be fully qualified with the
-C<Irssi::I<cmd>> prefix.
+functions by default, and requires that all function-calls be fully qualified with the
+C<Irssi::I<cmd>> prefix. See L</EXPORTS> for alternatives.
 
 =head1 CLASSES
 
@@ -31,19 +31,19 @@ B<TODO: fix this list with proper package names>
 
 =over 4
 
-=item L<Irssi::Ban>
-
 =item L<Irssi::Chatnet>
 
-=item L<Irssi::Chatnet>
+=item L<Irssi::Command>
 
-=item L<Irssi::Client>
+=item L<Irssi::Ignore>
 
-=item L<Irssi::Command>
+=item L<Irssi::Irc::Ban>
 
-=item L<Irssi::Dcc>
+=item L<Irssi::Irc::Client>
 
-=item L<Irssi::Ignore>
+=item L<Irssi::Irc::Dcc>
+
+=item L<Irssi::Irc::Notifylist>
 
 =item L<Irssi::Log>
 
@@ -51,8 +51,6 @@ B<TODO: fix this list with proper package names>
 
 =item L<Irssi::Nick>
 
-=item L<Irssi::Notifylist>
-
 =item L<Irssi::Process>
 
 =item L<Irssi::Query>
@@ -462,104 +460,124 @@ B<TODO: What is this for?>
 
 =head3 Modifying Settings
 
+=head4 C<settings_set_str $key, $value>
+
+=head4 C<settings_set_int $key, $value>
+
+=head4 C<settings_set_bool $key, $value>
+
+=head4 C<settings_set_time $key, $value>
+
+=head4 C<settings_set_level $key, $value>
+
+=head4 C<settings_set_size $key, $value>
+
+Changes the value of the setting with key C<$key> to C<$value>.
+
 B<If you change the settings of another module/script with one of these, you
 must emit a C<"setup changed"> signal afterwards.>
 
-=head4 C<settings_set_str(key, value)>
+This can be done with:
 
-=head4 C<settings_set_int(key, value)>
+   Irssi::signal_emit("setup changed");
 
-=head4 C<settings_set_bool(key, value)>
+=head4 C<settings_remove $key>
 
-=head4 C<settings_set_time(key, value)>
+Remove a setting specified with C<$key>.
 
-=head4 C<settings_set_level(key, value)>
 
-=head4 C<settings_set_size(key, value)>
+=head2 IO and Process Management
 
-=head4 C<settings_remove(key)>
+=head3 C<timeout_add $msecs, $func, $data>
 
-Remove a setting.
+  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>
 
-=head2 IO and Process Management
+Call `func' once after `msecs' milliseconds (1000 = 1 second)
+with parameter `data'. Returns tag which can be used to stop the timeout.
+
+=head3 C<timeout_remove $tag>
+
+Remove timeout specified with tag C<$tag>.
 
-timeout_add(msecs, func, data)
-  Call `func' every `msecs' milliseconds (1000 = 1 second) with
-  parameter `data'. Returns tag which can be used to stop the timeout.
+=head3 C<input_add $source, $condition, $func, $data>
 
-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 `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.
 
-timeout_remove(tag)
-  Remove timeout with tag.
+=head3 C<input_remove $tag>
 
-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.
+Remove listener with tag.
 
-input_remove(tag)
-  Remove listener with tag.
+=head3 C<pidwait_add $pid>
 
-pidwait_add(pid)
-  Adds `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.
+Adds `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.
 
-pidwait_remove(pid)
-  Removes `pid' from the list of processes to wait for. Terminated
-  processes are removed automatically, so it is usually not necessary
-  to call this function.
+=head3 C<pidwait_remove $pid>
 
+Removes `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
 
-level2bits(level)
+=head3 C<level2bits $level>
+
   Level string -> number
 
-bits2level(bits)
+=head3 C<bits2level $bits>
+
   Level number -> string
 
-combine_level(level, str)
+=head3 C<combine_level $level, $str>
+
   Combine level number to level string ("+level -level").
   Return new level number.
 
 
 =head2 Themes
 
-See also L<Irssi::Theme>
+See also L<Irssi::UI::Theme>
 
 You can have user configurable texts in scripts that work just like
 irssi's internal texts that can be changed in themes.
 
 First you'll have to register the formats:
 
-
-Irssi::theme_register([
-  'format_name', '{hilight my perl format!}',
-  'format2', 'testing.. nick = $0, channel = $1'
-]);
+    Irssi::theme_register([
+      'format_name', '{hilight my perl format!}',
+      'format2', 'testing.. nick = $0, channel = $1'
+    ]);
 
 Printing happens with one of the functions:
 
-printformat(level, format, ...)
-Window::printformat(level, format, ...)
-Server::printformat(target, level, format, ...)
-Windowitem::printformat(level, format, ...)
+    printformat $level, $format, ...
+
+    Window::printformat $level, $format, ...
+
+    Server::printformat $target, $level, $format, ...
+
+    Windowitem::printformat $level, $format, ...
 
 For example:
 
-  $channel->printformat(MSGLEVEL_CRAP, 'format2',
-		        'nick', $channel->{name});
+    $channel->printformat(MSGLEVEL_CRAP, 'format2',
+                          'nick', $channel->{name});
 
 
 =head2 DCC
 
+B<TODO: This should probably move to L<Irssi::Irc>
+
 See also L<Irssi::Dcc>
 
 Dcc
@@ -573,48 +591,58 @@ dcc_find_by_port(nick, port)
 
 =head2 Channels
 
-Channel
-channel_find(channel)
-  Find channel from any server.
+=head3 C<channel_find $channel>
+
+Find channel from any server. Returns an L<Irssi::Channel> object.
+
 
 =head2 Ignores
 
+=head3 C<ignore_add_rec $ignore>
 
-ignore_add_rec(ignore)
-  Add ignore record.
+Add ignore record.
+
+=head3 C<ignore_update_rec $ignore>
+
+Update ignore record in configuration
+
+=head3 C<ignore_check $nick, $host, $channel, $text, $level>
+
+B<TODO: Document what this does>
 
-ignore_update_rec(ignore)
-  Update ignore record in configuration
 
-ignore_check(nick, host, channel, text, level)
 
 =head2 Logging
 
+=head3 C<log_create_rec $fname, $level>
+
+Create log file. Returns L<Irssi::Log>
 
-Log
-log_create_rec(fname, level)
-  Create log file.
 
+=head3 C<log_find $fname>
+
+Find log with file name. Returns L<Irssi::Log>
 
-Log
-log_find(fname)
-  Find log with file name.
 
 =head2 Raw Logging
 
-Rawlog rawlog_create()
-  Create a new rawlog.
+=head3 C<rawlog_create>
+
+Create a new rawlog. Returns an L<Irssi::Rawlog> object.
 
-rawlog_set_size(lines)
-  Set the default rawlog size for new rawlogs.
+=head3 C<rawlog_set_size $lines>
+
+Set the default rawlog size for new rawlogs.
 
 =head2 Chat-Nets
 
-chatnet_find(name)
-  Find chat network with name.
+=head3 C<chatnet_find $name>
+
+Find chat network with name.
 
 =head2 Status Bars
 
+See also L<Irssi::TextUI::Statusbaritem>
 B<TODO>
 
 =head1 COPYRIGHT
diff --git a/docs/Irssi/Channel.pod b/docs/Irssi/Channel.pod
index bb6789d..baeff6c 100644
--- a/docs/Irssi/Channel.pod
+++ b/docs/Irssi/Channel.pod
@@ -6,7 +6,8 @@ Irssi::Channel
 
 =head1 FIELDS
 
-Channel->{}
+C<Channel-E<gt>{}>
+
   type - "CHANNEL" text
   chat_type - String ID of chat protocol, for example "IRC"
 
@@ -35,45 +36,51 @@ Channel->{}
 
 
 
-Server::channels_join(channels, automatic)
-  Join to channels in server. `channels' may also contain keys for
-  channels just like with /JOIN command. `automatic' specifies if this
-  channel was joined "automatically" or if it was joined because join
-  was requested by user. If channel join is "automatic", irssi doesn't
-  jump to the window where the channel was joined.
+=head2 C<channels_join(channels, automatic)>
+
+Join to channels in server. `channels' may also contain keys for
+channels just like with /JOIN command. `automatic' specifies if this
+channel was joined "automatically" or if it was joined because join
+was requested by user. If channel join is "automatic", irssi doesn't
+jump to the window where the channel was joined.
+
+=head2 C<destroy>
+
+Destroy channel.
+
+=head2 C<bans>
+
+Return a list of bans in channel.
+
+=head2 C<ban_get_mask $nick>
+
+Get ban mask for `nick'.
+
+=head2 C<banlist_add $ban, $nick, $time>
+
+Add a new ban to channel.
 
+=head2 C<banlist_remove $ban>
 
-Channel::destroy()
-  Destroy channel.
+Remove a ban from channel.
 
 
-Channel::bans()
-  Return a list of bans in channel.
+=head2 C<nick_insert $nick, $op, $voice, $send_massjoin>
 
-Channel::ban_get_mask(nick)
-  Get ban mask for `nick'.
+Add nick to nicklist. Returns a L<Irssi::Nick>.
 
-Channel::banlist_add(ban, nick, time)
-   Add a new ban to channel.
+=head2 C<nick_remove $nick>
 
-Channel::banlist_remove(ban)
-   Remove a ban from channel.
+Remove nick from nicklist.
 
+=head2 C<nick_find $nick>
 
-Nick
-Channel::nick_insert(nick, op, voice, send_massjoin)
-  Add nick to nicklist.
+Find nick from nicklist. Returns L<Irssi::Nick>.
 
-Channel::nick_remove(nick)
-  Remove nick from nicklist.
+=head2 C<nick_find_mask $mask>
 
-Nick
-Channel::nick_find(nick)
-  Find nick from nicklist.
+Find nick mask from nicklist, wildcards allowed. Returns L<Irssi::Nick>.
 
-Nick
-Channel::nick_find_mask(mask)
-  Find nick mask from nicklist, wildcards allowed.
+=head2 C<nicks>
 
-Channel::nicks()
-  Return a list of all nicks in channel.
+Return a list of all nicks in channel.
diff --git a/docs/Irssi/Irc/Dcc.pod b/docs/Irssi/Irc/Dcc.pod
index 5950a92..5ba52b9 100644
--- a/docs/Irssi/Irc/Dcc.pod
+++ b/docs/Irssi/Irc/Dcc.pod
@@ -6,7 +6,7 @@ Irssi::Irc::Dcc
 
 =head1 FIELDS
 
-=head2 C<Dcc->{}>
+=head2 C<Dcc-E<gt>{}>
 
   type - Type of the DCC: chat, send, get
   orig_type - Original DCC type that was sent to us - same as type except
@@ -29,13 +29,13 @@ Irssi::Irc::Dcc
   starttime - Unix time stamp when the DCC transfer was started
   transfd - Bytes transferred
 
-=head2 C<Dcc::Chat->{}>
+=head2 C<Dcc::Chat-E<gt>{}>
 
   id - Unique identifier - usually same as nick
   mirc_ctcp - Send CTCPs without the CTCP_MESSAGE prefix
   connection_lost - Other side closed connection
 
-=head2 C<Dcc::Get->{}>
+=head2 C<Dcc::Get-E<gt>{}>
 
   (..contains all the same data as core Dcc object..)
   size - File size
@@ -47,7 +47,7 @@ Irssi::Irc::Dcc
   file - The real file name which we use.
   file_quoted - 1 if file name was received quoted ("file name")
 
-=head2 C<Dcc::Send->{}>
+=head2 C<Dcc::Send-E<gt>{}>
 
   (..contains all the same data as core Dcc object..)
   size - File size
diff --git a/docs/Irssi/Log.pod b/docs/Irssi/Log.pod
index 673a183..68163a2 100644
--- a/docs/Irssi/Log.pod
+++ b/docs/Irssi/Log.pod
@@ -6,7 +6,8 @@ Irssi::Log
 
 =head1 FIELDS
 
-Log->{}
+C<Log-E<gt>{}>
+
   fname - Log file name
   real_fname - The actual opened log file (after %d.%m.Y etc. are expanded)
   opened - Log file is open
@@ -20,27 +21,30 @@ Log->{}
 
 =head1 METHODS
 
+=head2 C<update>
+
+Add log to list of logs / save changes to config file.
+
+=head2 C<close>
+
+Destroy log file.
+
+=head2 C<start_logging>
 
-Log::update()
-  Add log to list of logs / save changes to config file.
+Open log file and start logging.
 
+=head2 C<stop_logging>
 
-Log::close()
-  Destroy log file.
+Close log file.
 
-Log::start_logging()
-  Open log file and start logging.
+=head2 C<item_add $type, $name, $server>
 
-Log::stop_logging()
-  Close log file.
+Add log item to log.
 
-Log::item_add(type, name, server)
-  Add log item to log.
+=head2 C<item_destroy $item>
 
-Log::item_destroy(item)
-  Remove log item from log.
+Remove log item from log.
 
+=head2 C<item_find $type, $item, $server>
 
-Logitem
-Log::item_find(type, item, server)
-  Find item from log.
+Find item from log. Returns L<Irssi::Logitem>
diff --git a/docs/Irssi/Logitem.pod b/docs/Irssi/Logitem.pod
index 6db0c7b..f30d4b8 100644
--- a/docs/Irssi/Logitem.pod
+++ b/docs/Irssi/Logitem.pod
@@ -6,11 +6,11 @@ Irssi::Logitem
 
 =head1 FIELDS
 
-Logitem->{}
+C<Logitem-E<gt>{}>
+
   type - 0=target, 1=window refnum
   name - Name
   servertag - Server tag
 
-
 =head1 METHODS
 
diff --git a/docs/Irssi/Nick.pod b/docs/Irssi/Nick.pod
index b20d43a..3e85256 100644
--- a/docs/Irssi/Nick.pod
+++ b/docs/Irssi/Nick.pod
@@ -6,7 +6,8 @@ Irssi::Nick
 
 =head1 FIELDS
 
-Nick->{}
+C<Nick-E<gt>{}>
+
   type - "NICK" text
   chat_type - String ID of chat protocol, for example "IRC"
 
diff --git a/docs/Irssi/Rawlog.pod b/docs/Irssi/Rawlog.pod
index 7f89c64..a5428bf 100644
--- a/docs/Irssi/Rawlog.pod
+++ b/docs/Irssi/Rawlog.pod
@@ -7,34 +7,42 @@ Irssi::Rawlog
 =head1 FIELDS
 
 
-Rawlog->{}
+C<Rawlog-E<gt>{}>
+
   logging - The rawlog is being written to file currently
   nlines - Number of lines in rawlog
 
 =head1 METHODS
 
+=head2 C<destroy>
+
+Destroy the rawlog.
+
+=head2 C<get_lines>
+
+Returns all lines in rawlog.
+
+=head2 C<open $filename>
+
+Start logging new messages in rawlog to specified file.
+
+=head2 C<close>
+
+Stop logging to file.
 
-Rawlog::destroy()
-  Destroy the rawlog.
+=head2 C<save $filename>
 
-Rawlog::get_lines()
-  Returns all lines in rawlog.
+Save the current rawlog history to specified file.
 
-Rawlog::open(filename)
-  Start logging new messages in rawlog to specified file.
+=head2 C<input $str>
 
-Rawlog::close()
-  Stop logging to file.
+Send `str' to raw log as input text.
 
-Rawlog::save(filename)
-  Save the current rawlog history to specified file.
+=head2 C<output $str>
 
-Rawlog::input(str)
-  Send `str' to raw log as input text.
+Send `str' to raw log as output text.
 
-Rawlog::output(str)
-  Send `str' to raw log as output text.
+=head2 C<redirect $str>
 
-Rawlog::redirect(str)
-  Send `str' to raw log as redirection text.
+Send `str' to raw log as redirection text.
 
diff --git a/docs/Irssi/UI/Theme.pod b/docs/Irssi/UI/Theme.pod
index 56e3a3f..4fff169 100644
--- a/docs/Irssi/UI/Theme.pod
+++ b/docs/Irssi/UI/Theme.pod
@@ -1,3 +1,5 @@
+__END__
+
 =head1 NAME
 
 Irssi::UI::Theme
@@ -6,3 +8,57 @@ Irssi::UI::Theme
 
 =head1 METHODS
 
+=head1 THEME DOCUMENTATION
+
+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 :)
+
+=head2 TEMPLATES
+
+The real text formats that irssi uses are the ones you can find with
+/FORMAT command. Back in the old days all the colors and texts were mixed
+up in those formats, and it was really hard to change the colors since you
+might have had to change them in tens of different places. So, then came
+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.
+
+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
+below and sets C<parameter1> into C<$0> and C<parameter2> into C<$1> (you can
+have more parameters of course). Templates can have subtemplates.  Here's a
+small example:
+
+  /FORMAT format hello {colorify {underline world}}
+
+  abstracts = { colorify = "%G$0-%n"; underline = "%U$0-%U"; }
+
+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).
+
+=head2 COLORS
+
+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.
diff --git a/docs/Signals.pod b/docs/Signals.pod
index 7c1f6db..2fcf913 100644
--- a/docs/Signals.pod
+++ b/docs/Signals.pod
@@ -1606,10 +1606,18 @@ B<Requires to work properly:>
 
 =back
 
+=item C<"gui print text finished">
+
+=over
+
+=item L<Irssi::Window> C<$window>
+
 =back
 
 (Can be used to determine when all "gui print text"s are sent (not required))
- "gui print text finished", WINDOW_REC
+
+=back
+
 
 B<Provides signals:>
 
@@ -1619,7 +1627,19 @@ B<Provides signals:>
 
 =item C<"complete word">
 
-, GList * of char*, WINDOW_REC, char *word, char *linestart, int *want_space
+=over
+
+=item arrayref of string C<$WHAT> B<TODO: ???>
+
+=item L<Irssi::Window> C<$window>
+
+=item string C<$word>
+
+=item string C<$linestart>
+
+=item int C<$want_space>
+
+=back
 
 =back