lots of doc updates

7 files changed, 389 insertions, 126 deletions

diff --git a/docs/General/Guide.pod b/docs/General/Guide.pod
index 3a9f43f..20f48af 100644
--- a/docs/General/Guide.pod
+++ b/docs/General/Guide.pod
@@ -6,6 +6,10 @@ Guide To Irssi Scripting.
 
 =head1 DESCRIPTION
 
+This page presents a bunch of additional information about scripting for Irssi
+that doesn't fit well anywhere else. It contains useful tips, common pitfalls,
+and a bunch of other handy things.  At least, I hope so.
+
 =head1 LOADING AND UNLOADING SCRIPTS
 
 =head2 File Locations
@@ -19,12 +23,33 @@ F<~/.irssi/scripts/>.
 If you require a script be run when Irssi starts, you can place the file (or
 better, create a symlink to it) into F<~/.irssi/scripts/autorun/>.
 
+Alternatively, if you want more control over the order in which scripts are
+autoloaded, you can place
+
+   SCRIPT LOAD script1
+   SCRIPT LOAD script2
+   SCRIPT LOAD script3
+
+into your F<~/.irssi/startup> file.
+
+I<This tip was provided by C<Rhonda> on Freenode/#irssi>.
+
 =head2 Testing
 
 =for comment B<TODO: Forgotten what was going to go here>
 
 =head3 C</SCRIPT EXEC>
 
+The C<SCRIPT EZEC> command allows you to test various simple ideas straight from
+the Irssi interface.  It can also be used to register signal handlers and
+commands if run with the C<-permanent> option.
+
+B<NB: C<-permanent> only means that the script should not terminate
+immediately. It is still not persistent between restarts of the Irssi client.
+Truly permanent scripts should be placed in autorun scripts or added to
+F<~/.irssi/startup>>
+
+
 B<TODO: Using it for testing stuff out>
 
 B<TODO: Also for very short scripts (with -permanent?)>
diff --git a/docs/Irssi.pod b/docs/Irssi.pod
index 5984116..f5d72b7 100644
--- a/docs/Irssi.pod
+++ b/docs/Irssi.pod
@@ -181,7 +181,7 @@ using the C<--home=> commandline option, or defaults to F<~/.irssi/>.
 
 =head2 Signals
 
-See also L<Signals>
+See also L<General::Signals>
 
 Irssi is pretty much based on sending and handling different signals.
 Like when you receive a message from server, say:
@@ -225,7 +225,8 @@ could use /IGNORE instead for both of these C<:)>
 You can also use L<Irssi::signal_add_last|/signal_add_last> if you wish to let the
 Irssi's internal functions be run before yours.
 
-A list of signals that irssi sends can be found in the L<Signals> documentation.
+A list of signals that irssi sends can be found in the L<General::Signals>
+documentation.
 
 
 
@@ -246,7 +247,7 @@ For example:
     Irssi::signal_add("default command", \&my_function);
 
 In all cases, the specified function will be passed arguments in C<@_> as specified
-in L<Signals>.
+in L<General::Signals>.
 
 =head4 C<signal_add_first $sig_name, $func>
 
@@ -365,8 +366,8 @@ with:
 
     command_bind("$cmd $subcmd", subcmdfunc[, category]);
 
-See the L<example|Guide/Use Subcommands to Group Script Functionality> for
-further details.
+See the L<example|General::Guide/Use Subcommands to Group Script Functionality>
+for further details.
 
 =head4 C<command_unbind $cmd, $func>
 
@@ -695,38 +696,160 @@ See also L<Irssi::UI::Theme>
 
 Reloads the current theme (set with C</SET THEME>) from file.
 
-=head3 Miscellaneous
+See also L<Irssi::UI::Theme/Loading and Testing>.
+
+=head3 C<current_theme>
+
+Returns the current L<theme|Irssi::UI::Theme> object.
+
+=head3 C<theme_register $format_list_ref>
 
 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:
+See also the L<template|Irssi::UI::Theme/TEMPLATES> and L<format
+arguments|General::Formats/ALIAS AND FORMAT TEMPLATE ARGUMENTS> docs for
+details on the structure of these templates.
 
     Irssi::theme_register([
       'format_name', '{hilight my perl format!}',
       'format2', 'testing.. nick = $0, channel = $1'
     ]);
 
-Printing happens with one of the functions:
+B<NB: Format variable placeholders should be single-quoted or escaped to prevent
+Perl from trying to expand the C<$> variables prematurely.>
+
+=head3 Printing
+
+Printing happens with one of the following functions:
+
+=over
 
-    printformat $level, $format, ...
+=item C<printformat $level, $format, ...>
 
-    Window::printformat $level, $format, ...
+=item C<Irssi::UI::Window::printformat $window, $level, $format, ...>
 
-    Server::printformat $target, $level, $format, ...
+=item C<Irssi::Server::printformat $server, $target, $level, $format, ...>
 
-    Windowitem::printformat $level, $format, ...
+=item C<Irssi::Windowitem::printformat $win_item, $level, $format, ...>
+
+=back
+
+The remaining args passed after C<$format> are passed to the format template as
+arguments, starting at C<$0>.
+
+Note that the latter 3 functions are intended to be called as methods on a
+Window, Server, or Windowitem object, and will print to their respective
+destinations.
+
+B<TODO: What does plain old printformat use as a destination?>
 
 For example:
 
     $channel->printformat(MSGLEVEL_CRAP, 'format2',
                           'nick', $channel->{name});
 
+or
 
-=head3 C<current_theme>
+    $window->printformat(MSGLEVEL_CRAP, 'format_blah', @format_data);
 
-Returns the current L<theme|Irssi::UI::Theme> object.
+=head3 C<parse_special $str, $data, $flags>
+
+This function takes a string in C<$str> containing L<colour
+codes|General::Formats/COLOURS> and L<expandos|General::Formats/EXPANDOS
+(SPECIAL VARIABLES)> and ordinary text, returns a string with all variables,
+formats and expandos expanded to their appropriate values.
+
+B<TODO: What is data?>
+
+B<TODO: What are flags?>
+
+
+=head2 Expandos
+
+Expandos are special variables which can be used in format and abstract
+L<templates|Irssi::UI::Theme/TEMPLATES>.
+
+They behave similarly to Perl "Magic" variables, and their value is set behind
+the scenes depending on calling context.
+
+See also L<Formats/Expandos|General::Formats/EXPANDOS (SPECIAL VARIABLES)> for
+a list of builtin expandos.
+
+Scripts can fetch the value of expandos using the L<parse_special|/parse_special
+$cmd, $data, $flags> function, and can also register and handle rendering of
+additional ones.
+
+=head3 C<expando_create $name, $func, $update_flags>
+
+This function creates a new expando with name C<$name>.  The expando is
+accessible from templates via C<I<$expando_name>>.
+
+C<$func> is a CODEREF which is called by Irssi internally when the expando
+should be updated.
+
+A simple handler function would look something like:
+
+    sub handle_my_expando {
+        my ($server, $win_item, $arg) = @_;
+        return "some string";
+    }
+
+B<TODO: What is passed in $arg?>
+
+C<$update_flags> is a hashref containing one or more C<SIGNAL =E<gt> BEHAVIOUR> pairs.
 
+The signals are strings containing ordinary Irssi L<signals|General::Signals>.
+The behaviour flag can take one of the following (string) values:
+
+=over
+
+=item C<"none">
+
+Unconditionally update the expando when this signal is received.
+
+=item C<"server">
+
+Only update this expando if the signal received passes an L<Irssi::Server>
+argument that matches the Server in which the expando is used in.
+
+=item C<"window">
+
+Only update this expando if the signal received passes an L<Irssi::UI::Window>
+argument that matches the Window in which the expando is used in.
+
+=item C<"windowitem">
+
+Only update this expando if the signal received passes an L<Irssi::Windowitem>
+argument that matches the Windowitem in which the expando is used in.
+
+=item C<"never">
+
+Never update the value of this expando. It is calculated once and never altered.
+
+=back
+
+For example:
+
+    Irssi::expando_create 'my_expando', \&handle_my_expando, { 'message part' => 'none' };
+
+This expando will be refreshed (via a call to C<handle_my_expando()>) every time
+a C<message part> signal is emitted.
+
+B<NB: Only expandos used in statusbars will be updated dynamically to reflect
+their new value.  Those used in a template to print text will remain static as
+determined by their value when they were firstrendered.>
+
+Expandos used in statusbars can be forced to refresh using
+L<statusbar_items_redraw|/statusbar_items_redraw $name>, even if they have no
+autorefresh signals set.
+
+=head3 C<expando_destroy $name>
+
+This function removes the expando specified by C<$name>. Its handler function
+will no longer be called, and all update signal listeners are also removed.
+
+B<TODO: What is the value of a destroyed expando if used in a template/sbar?>
 
 =head2 Text GUI
 
@@ -746,7 +869,7 @@ Sets the position of the cursor in the input field.
 
 There is no equivalent function for accessing this directly as there
 are for the others above, but it can be determined using the C<$L> expando
-documented in L<Formats>.
+documented in L<General::Formats>.
 
 For example:
 
@@ -754,6 +877,17 @@ For example:
 
 See L<parse_special|/parse_special $cmd, $data, $flags> for more detail.
 
+=head3 C<gui_printtext $x, $y, $str>
+
+Prints C<$str> starting at the C<$x, $y> position on the current screen.
+
+The coordinates treat the top-left corner of the screen as the origin (0, 0).
+
+B<NB: The contents of the string will overwrite whatever is currently located at
+that screen position, but is transient, and will be replaced by the original
+content if the screen is redrawn (C</REDRAW> or C<Ctrl-L>).>
+
+
 =head2 Channels
 
 =head3 C<channel_find $channel>
@@ -808,7 +942,13 @@ Find chat network with name.
 
 See also L<Irssi::TextUI::Statusbaritem>
 
-B<TODO>
+=head3 C<statusbar_item_register $name, $value, $func>
+
+=head3 C<statusbar_item_unregister $name>
+
+=head3 C<statusbar_items_redraw $name>
+
+=head3 C<statusbars_recreate_items>
 
 =head1 COPYRIGHT
 
@@ -820,9 +960,12 @@ Formatting to POD, and some additional comments by Tom Feist
 
 =head1 Complete List of Functions
 
-    Irssi::abstracts_register
-    Irssi::active_server
-    Irssi::active_win
+C<*> indicates functions currently documented, C<+> for those which aren't
+useful for scripting, and won't be dealt with here. Go read the source C<:)>
+
+    *Irssi::abstracts_register
+    *Irssi::active_server
+    *Irssi::active_win
 
     Irssi::bits2level
 
@@ -834,107 +977,107 @@ Formatting to POD, and some additional comments by Tom Feist
 
     Irssi::combine_level
 
-    Irssi::command
-    Irssi::command_bind
-    Irssi::command_bind_first
-    Irssi::command_bind_last
-    Irssi::command_parse_options
-    Irssi::command_runsub
-    Irssi::command_set_options
-    Irssi::command_unbind
-    Irssi::commands
+    *Irssi::command
+    *Irssi::command_bind
+    *Irssi::command_bind_first
+    *Irssi::command_bind_last
+    *Irssi::command_parse_options
+    *Irssi::command_runsub
+    *Irssi::command_set_options
+    *Irssi::command_unbind
+    *Irssi::commands
 
     Irssi::ctcp_register
     Irssi::ctcp_unregister
 
-    Irssi::current_theme
+    *Irssi::current_theme
 
-    Irssi::deinit
+    +Irssi::deinit
 
-    Irssi::expando_create
-    Irssi::expando_destroy
+    *Irssi::expando_create
+    *Irssi::expando_destroy
 
     Irssi::format_create_dest
     Irssi::format_get_length
     Irssi::format_real_length
 
-    Irssi::get_gui
-    Irssi::get_irssi_binary
-    Irssi::get_irssi_config
-    Irssi::get_irssi_dir
+    *Irssi::get_gui
+    *Irssi::get_irssi_binary
+    *Irssi::get_irssi_config
+    *Irssi::get_irssi_dir
 
-    Irssi::gui_input_get_pos
-    Irssi::gui_input_set
-    Irssi::gui_input_set_pos
-    Irssi::gui_printtext
+    *Irssi::gui_input_get_pos
+    *Irssi::gui_input_set
+    *Irssi::gui_input_set_pos
+    *Irssi::gui_printtext
 
     Irssi::ignore_check
-    Irssi::ignores
-    Irssi::init
-    Irssi::input_add
-    Irssi::input_remove
+    *Irssi::ignores
+    +Irssi::init
+    *Irssi::input_add
+    *Irssi::input_remove
     Irssi::level2bits
 
-    Irssi::log_create_rec
+    +Irssi::log_create_rec
     Irssi::log_find
-    Irssi::logs
+    *Irssi::logs
 
     Irssi::mask_match
     Irssi::mask_match_address
     Irssi::masks_match
 
-    Irssi::parse_special
+    *Irssi::parse_special
 
-    Irssi::pidwait_add
-    Irssi::pidwait_remove
+    *Irssi::pidwait_add
+    *Irssi::pidwait_remove
 
     Irssi::print
-    Irssi::printformat
+    *Irssi::printformat
 
-    Irssi::queries
+    *Irssi::queries
     Irssi::query_find
 
-    Irssi::rawlog_create
-    Irssi::rawlog_set_size
+    *Irssi::rawlog_create
+    *Irssi::rawlog_set_size
 
-    Irssi::reconnects
+    *Irssi::reconnects
 
     Irssi::server_create_conn
     Irssi::server_find_chatnet
     Irssi::server_find_tag
-    Irssi::servers
-
-    Irssi::settings_add_bool
-    Irssi::settings_add_int
-    Irssi::settings_add_level
-    Irssi::settings_add_size
-    Irssi::settings_add_str
-    Irssi::settings_add_time
-    Irssi::settings_get_bool
-    Irssi::settings_get_int
-    Irssi::settings_get_level
-    Irssi::settings_get_size
-    Irssi::settings_get_str
-    Irssi::settings_get_time
-    Irssi::settings_remove
-    Irssi::settings_set_bool
-    Irssi::settings_set_int
-    Irssi::settings_set_level
-    Irssi::settings_set_size
-    Irssi::settings_set_str
-    Irssi::settings_set_time
-
-    Irssi::signal_add
-    Irssi::signal_add_first
-    Irssi::signal_add_last
+    *Irssi::servers
+
+    *Irssi::settings_add_bool
+    *Irssi::settings_add_int
+    *Irssi::settings_add_level
+    *Irssi::settings_add_size
+    *Irssi::settings_add_str
+    *Irssi::settings_add_time
+    *Irssi::settings_get_bool
+    *Irssi::settings_get_int
+    *Irssi::settings_get_level
+    *Irssi::settings_get_size
+    *Irssi::settings_get_str
+    *Irssi::settings_get_time
+    *Irssi::settings_remove
+    *Irssi::settings_set_bool
+    *Irssi::settings_set_int
+    *Irssi::settings_set_level
+    *Irssi::settings_set_size
+    *Irssi::settings_set_str
+    *Irssi::settings_set_time
+
+    *Irssi::signal_add
+    *Irssi::signal_add_first
+    *Irssi::signal_add_last
     Irssi::signal_add_priority
-    Irssi::signal_continue
-    Irssi::signal_emit
+    *Irssi::signal_continue
+    *Irssi::signal_emit
     Irssi::signal_get_emitted
     Irssi::signal_get_emitted_id
-    Irssi::signal_register
+    *Irssi::signal_register
     Irssi::signal_remove
-    Irssi::signal_stop
+    *Irssi::signal_stop
     Irssi::signal_stop_by_name
 
     Irssi::statusbar_item_register
@@ -947,9 +1090,9 @@ Formatting to POD, and some additional comments by Tom Feist
     Irssi::theme_register
     *Irssi::themes_reload
 
-    Irssi::timeout_add
-    Irssi::timeout_add_once
-    Irssi::timeout_remove
+    *Irssi::timeout_add
+    *Irssi::timeout_add_once
+    *Irssi::timeout_remove
 
     Irssi::version
 
@@ -961,6 +1104,6 @@ Formatting to POD, and some additional comments by Tom Feist
     Irssi::window_item_find
     Irssi::window_refnum_next
     Irssi::window_refnum_prev
-    Irssi::windows
+    *Irssi::windows
     Irssi::windows_refnum_last
 
diff --git a/docs/Irssi/Ignore.pod b/docs/Irssi/Ignore.pod
index 6b0270a..47f5225 100644
--- a/docs/Irssi/Ignore.pod
+++ b/docs/Irssi/Ignore.pod
@@ -21,8 +21,6 @@ C<Ignore-E<gt>{}>
 
 =head1 METHODS
 
-B<TODO>
-
 =head2 C<add_rec>
 
 =head2 C<update_rec>
diff --git a/docs/Irssi/UI/Theme.pod b/docs/Irssi/UI/Theme.pod
index 323e6b3..344b5ae 100644
--- a/docs/Irssi/UI/Theme.pod
+++ b/docs/Irssi/UI/Theme.pod
@@ -10,11 +10,59 @@ Irssi::UI::Theme
 
 =head2 C<format_expand $theme, $format, $flags>
 
-I<undocumented>
+C<$flags> is an optional bitmask of any of the following flags:
+
+=over
+
+=item C<EXPAND_FLAG_IGNORE_REPLACES>
+
+Any replacements specified in the theme are not applied to this expansion.
+
+=item C<EXPAND_FLAG_RECURSIVE_MASK>
+
+B<TODO: dunno>
+
+=item C<EXPAND_FLAG_IGNORE_EMPTY>
+
+If the format contains variables and no values are specified, an empty string is
+returned instead of a partially filled template.
+
+=back
+
+B<TODO: What?>
+
+Example:
+
+    my $formatted_str = Irssi::current_theme()->format_expand('{hilight Hello}');
+
+B<NOTE: it seems that this only operates on abstract templates, not those
+accessible with C</FORMAT>. Weird>
 
 =head2 C<get_format $theme, $module, $tag>
 
-I<undocumented>
+Returns the unexpanded format template for the format name supplied in C<$tag>.
+
+Valid values for C<$module> are:
+
+=over
+
+=item C<fe-common/perl>
+
+=item C<fe-common/irc/dcc>
+
+=item C<fe-common/irc>
+
+=item C<fe-common/core>
+
+=item C<fe-common/irc/notifylist>
+
+=item C<fe-text>
+
+=back
+
+Example:
+
+    my $pubmsg_format = Irssi::current_theme()->get_format('fe-common/core', 'pubmsg');
 
 =head1 THEME DETAILS
 
@@ -49,7 +97,19 @@ The actual mechanism used by Irssi to print text into the client involves a
 certain amount of indirection, which allows themes to reformat messages in
 various ways before they are displayed.
 
-The overall structure of these 
+The overall structure of these templates is based around 3 basic ideas:
+
+=over
+
+=item Nested Templates
+
+=item Colour Codes
+
+=item Variable Expansion
+
+=item Special Variables
+
+=back
 
 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
diff --git a/docs/TODO b/docs/TODO
new file mode 100644
index 0000000..f4b986d
--- /dev/null
+++ b/docs/TODO
@@ -0,0 +1,63 @@
+* Documentation
+** Finish writing up function defs in Irssi:: namespace
+** Write up more stuff on Themes, including brief tutorial
+** Fill in more stuff in Guide
+** Write up what triggers signals, when/how, etc.
+** Rest of docs
+*** Window
+*** WindowItem
+*** Server
+*** Channel
+*** Query
+*** Theme/View/Accessing screen content
+* Doc Gen
+** Prettify snippets with perltidy HTML mode
+** Javascript(?) c&p generator for signals
+   eg:
+   sub handle_sig_<foo> {
+       my ($arg1, $arg2, $arg3) = @_;
+   }
+   Irssi::signal_add("<foo>", \&handle_sig_<foo>);
+
+** Make CSS suck less (steal from perldoc.perl.org?)
+** Sidebar/frameset with quick links menu? 
+
+** Write parser for module-formats files and incorporate into docs somewhere
+*** Some sort of javascript bacon for viewing default formats?
+    Or just a big list?
+
+** Have something to check link validity, since refs have changed a lot
+** Index page
+*** Make it more multi-level, split on namespaces
+
+* Misc Code
+** finish off build-signals script to parse POD and produce signals header file.
+
+* Patches
+** Bindings
+*** Figure out how memory management / ref-counting works, and check for leaks
+*** Add "binding added/changed/deleted" signals
+*** Talk to someone (Bazerka?) about merging into trunk
+*** Proof of concept (modify adv_windowlist to use bindings rather than parsing cmd)
+
+** Abstract raw access
+*** Where are they stored - why doesn't get_format work?
+** Statusbars
+*** Access to entries (as objects)
+*** Create
+*** Remove
+** StatusbarItems
+*** List (given sbar)
+*** Enable/Disable
+** Aliases
+*** Add / Modify
+*** Remove
+*** List
+*** Fetch Single
+*** Signals
+
+* Misc Stuff
+** Publicise it a bit more, try to get links from people
+** Host on metavore?
+** Talk to maintainers about inclusion in core
+*** Maybe as patches to .xs files + parsing scripts?
diff --git a/docs/buildpod.pl b/docs/buildpod.pl
index ce2b2aa..050ea8e 100755
--- a/docs/buildpod.pl
+++ b/docs/buildpod.pl
@@ -19,7 +19,6 @@ sub new {
     my $self = shift;
     my $obj = $self->SUPER::new(@_);
 
-    $obj->add_css('podstyle.css', 1);
     $obj->css_flurry(0);
     $obj->javascript_flurry(0);
 
@@ -83,8 +82,15 @@ sub _write_contents_middle {
 
 package main;
 
+use File::Copy;
+
 my $output_dir = "../../tmp/shab-irssi-scripts/docs/";
 my $batchconv = Pod::Simple::HTMLBatch::Custom->new;
+my $css = 'podstyle.css';
 
-$batchconv->batch_convert([qw/./], $output_dir);
+$batchconv->add_css('podstyle.css', 1);
 
+$batchconv->batch_convert([qw/./], $output_dir);
+print "Copying CSS...\n";
+copy($css, $output_dir . $css);
+print "Done\n";
diff --git a/docs/podstyle.css b/docs/podstyle.css
index 79dbc1d..1cecdfb 100644
--- a/docs/podstyle.css
+++ b/docs/podstyle.css
@@ -1,36 +1,7 @@
-/* This file is autogenerated.  Do not edit.  110n=black_with_blue_on_white */
-
 /* For accessibility reasons, never specify text sizes in px/pt/pc/in/cm/mm */
 
 @media all { .hide { display: none; } }
 
-@media print {
-  .noprint, div.indexgroup, .backlinktop, .backlinkbottom { display: none }
-
-  * {
-    border-color: black !important;
-    color: black !important;
-    background-color: transparent !important;
-    background-image: none !important;
-  }
-
-  dl.superindex > dd  {
-    word-spacing: .6em;
-  }
-}
-
-@media aural, braille, embossed {
-  div.indexgroup  { display: none; }  /* Too noisy, don't you think? */
-  dl.superindex > dt:before { content: "Group ";  }
-  dl.superindex > dt:after  { content: " contains:"; }
-  .backlinktop    a:before  { content: "Back to contents"; }
-  .backlinkbottom a:before  { content: "Back to contents"; }
-}
-
-@media aural {
-  dl.superindex > dt  { pause-before: 600ms; }
-}
-
 @media screen, tty, tv, projection {
   .noscreen { display: none; }
 
@@ -134,6 +105,3 @@
   }
   
 }
-
-/* The End */
-