added some stuff to the guide, and cleaned up some irssi.pod function descs

12 files changed, 201 insertions, 71 deletions

diff --git a/docs/Guide.pod b/docs/Guide.pod
index 4f78fc0..239aac7 100644
--- a/docs/Guide.pod
+++ b/docs/Guide.pod
@@ -18,6 +18,10 @@ Scripts are loaded via C</SCRIPT LOAD I<filename>>.  A default Irssi
 configuration also provides the C</RUN> alias as an alternative to C</SCRIPT
 LOAD>.
 
+Loaded scripts will exist in the Irssi namespace as:
+C<Irssi::Script::I<E<lt>nameE<gt>>>, where I<name> is the filename stripped of its
+F<.pl> extension.
+
 
 =head2 Unloading
 
@@ -42,16 +46,64 @@ necessary code.
 
 =head2 Preamble
 
+All scripts should contain a header as follows:
+
+    use strict;
+    use warnings;
+
+    use vars qw($VERSION %IRSSI);
+    use Irssi;
+
+    $VERSION = '1.00';
+    %IRSSI = (
+        authors     => 'Author Name(s)',
+        contact     => 'author_email@example.com',
+        name        => 'Script Title',
+        description => 'Longer script description ',
+        license     => 'Public Domain',
+    );
+
+The first two lines should be used in B<all> perl scripts, not just Irssi. They
+provide far greater error checking and diagnostics should you make a mistake in your
+code.
+
+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.
+
+
+
 =head1 COMMONLY SCRIPTED TASKS
 
 =head2 Modifying an input line before sending
 
+B<TODO: catch "send text", modify it if necessary, signal_emit it>
+
 =head2 Responding to a public message
 
+B<TODO: catch "messsage public", check params, generate response>
+
 =head2 Responding to a private message
 
+B<TODO: catch "messsage private", check params, generate response>
+
 =head1 USEFUL THINGS
 
+
+=head2 Getting the Response Value of a Remote Command
+
+B<TODO: use server redirections?>
+
+=head2 Getting the Response Value of a Local Command
+
+B<TODO: How?!??>
+
+Maybe, look up the format, intercept gui print text, try to match it against
+what you're expecting?
+
+Can this be generalised at all?
+
 =head2 Sharing Code Between Scripts
 
 There are 2 main ways for scripts to communicate, either via emitting and
@@ -121,7 +173,7 @@ The following example demonstrates how to use subcommands from within a script:
 
     sub subcmd_handler {
         my ($data, $server, $item) = @_;
-        $data =~ s/\s+$//g;
+        $data =~ s/\s+$//g; # strip trailing whitespace.
         Irssi::command_runsub('foo', $data, $server, $item);
     }
 
diff --git a/docs/Irssi.pod b/docs/Irssi.pod
index fc7e81f..97e4799 100644
--- a/docs/Irssi.pod
+++ b/docs/Irssi.pod
@@ -27,6 +27,8 @@ This documentation has been split into a number of pages, each documenting a
 particular class or pseudo-class.  The following list contains all of these
 additional pages.
 
+B<TODO: fix this list with proper package names>
+
 =over 4
 
 =item L<Irssi::Ban>
@@ -131,6 +133,7 @@ returns a list of all L<ignores|Irssi::Ignore>.
 
 =head3 C<dccs>
 
+B<TODO: this shouldn't be here>
 returns a list of all L<DCC connections|Irssi::Irc::Dcc>
 
 =head2 Signals
@@ -282,6 +285,20 @@ Bind a command string C<$cmd> to call function C<$func>. C<$func> can be
 either a string or coderef. C<$category> is an optional string specifying
 the category to display the command in when C</HELP> is used.
 
+When a command is invoked, either by the user typing C</command args>, the
+handler function will be called.
+
+It will receive the following parameters, passed in C<@_>:
+
+    my ($argument_string, $server_obj, $window_item_obj) = @_;
+
+The argument string must be processed by the handler to split it into
+individual words if necessary.
+
+The L<command_parse_options|/command_parse_options $cmd, $data> function can be
+used to process options (beginning with a single dash), and will also return the
+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
@@ -291,7 +308,8 @@ L<Irssi::Windowitem> `item'.
 Call command_runsub in handler function for `cmd' and bind
 with command_bind("`cmd' `subcmd'", subcmdfunc[, category]);
 
-B<TODO: example here>
+See the L<example|Guide/Use Subcommands to Group Script Functionality> for
+further details.
 
 =head4 C<command_unbind $cmd, $func>
 
@@ -365,40 +383,43 @@ For example:
 
 =head2 Settings
 
+Settings are a way to permanently store values that your script may wish to use.
+They are also easily manipulable by the user through the C</SET> command, making
+them a good way to allow configuration of your script.
 
 =head3 Creating New Settings
 
-=head4 C<settings_add_str(section, key, def)>
+If a setting does not currently exist, it must first be registered with Irssi
+using one of the C<settings_add> functions.
 
-=head4 C<settings_add_int(section, key, def)>
+=head4 C<settings_add_str $section, $key, $def>
 
-=head4 C<settings_add_bool(section, key, def)>
+=head4 C<settings_add_int $section, $key, $def>
 
-=head4 C<settings_add_time(section, key, def)>
+=head4 C<settings_add_bool $section, $key, $def>
 
-=head4 C<settings_add_level(section, key, def)>
+=head4 C<settings_add_time $section, $key, $def>
 
-=head4 C<settings_add_size(section, key, def)>
+=head4 C<settings_add_level $section, $key, $def>
 
+=head4 C<settings_add_size $section, $key, $def>
 
 =head3 Retrieving Settings
 
-=head4 C<settings_get_str($key)>
+=head4 C<settings_get_str $key>
 
-=head4 C<settings_get_int($key)>
+=head4 C<settings_get_int $key>
 
-=head4 C<settings_get_bool($key)>
+=head4 C<settings_get_bool $key>
 
-=head4 C<settings_get_time($key)>
+=head4 C<settings_get_time $key>
 
-=head4 C<settings_get_level($key)>
+=head4 C<settings_get_level $key>
 
-=head4 C<settings_get_size($key)>
+=head4 C<settings_get_size $key>
 
 =head3 Modifying Settings
 
-Set value for setting.
-
 B<If you change the settings of another module/script with one of these, you
 must emit a C<"setup changed"> signal afterwards.>
 
diff --git a/docs/Irssi/Ignore.pod b/docs/Irssi/Ignore.pod
index 108c0ba..f93cbe3 100644
--- a/docs/Irssi/Ignore.pod
+++ b/docs/Irssi/Ignore.pod
@@ -7,6 +7,7 @@ Irssi::Ignore
 =head1 FIELDS
 
 Ignore->{}
+
   mask - Ignore mask
   servertag - Ignore only in server
   channels - Ignore only in channels (list of names)
diff --git a/docs/Irssi/Irc.pod b/docs/Irssi/Irc.pod
new file mode 100644
index 0000000..e51b190
--- /dev/null
+++ b/docs/Irssi/Irc.pod
@@ -0,0 +1,27 @@
+__END__
+
+=head1 NAME
+
+Irssi::Irc
+
+=head1 DESCRIPTION
+
+=head1 CLASSES
+
+=head1 EXPORTS
+
+=head1 METHODS
+
+=head2 Accessors
+
+=head3 C<dccs>
+
+returns a list of all L<DCC connections|Irssi::Irc::Dcc>
+
+=head1 COPYRIGHT
+
+All the content of this site is copyright E<copy> 2000-2010 L<The Irssi
+project|http://irssi.org>.
+
+Formatting to POD and linking by Tom Feist
+ L<shabble+irssi@metavore.org|mailto:shabble+irssi@metavore.org>
diff --git a/docs/Irssi/Irc/Ban.pod b/docs/Irssi/Irc/Ban.pod
index ba8381f..7026ca1 100644
--- a/docs/Irssi/Irc/Ban.pod
+++ b/docs/Irssi/Irc/Ban.pod
@@ -2,14 +2,14 @@ __END__
 
 =head1 NAME
 
-Irssi::Ban
+Irssi::Irc::Ban
 
 =head1 FIELDS
 
 Ban->{}
+
   ban - The ban
   setby - Nick of who set the ban
   time - Timestamp when ban was set
 
-
 =head1 METHODS
diff --git a/docs/Irssi/Irc/Client.pod b/docs/Irssi/Irc/Client.pod
index e07bed7..e0a27f4 100644
--- a/docs/Irssi/Irc/Client.pod
+++ b/docs/Irssi/Irc/Client.pod
@@ -2,10 +2,12 @@ __END__
 
 =head1 NAME
 
-Irssi::Client
+Irssi::Irc::Client
 
 =head1 FIELDS
+
 Client->{}
+
   nick - nick of the client
   host - host of the client
   proxy_address - address of the proxy server
@@ -16,5 +18,4 @@ Client->{}
   want_ctcp - whether the client wants to receive CTCPs
   ircnet - network tag of the network we proxy
 
-
 =head1 METHODS
diff --git a/docs/Irssi/Irc/Dcc.pod b/docs/Irssi/Irc/Dcc.pod
index d7ab4a3..5950a92 100644
--- a/docs/Irssi/Irc/Dcc.pod
+++ b/docs/Irssi/Irc/Dcc.pod
@@ -2,7 +2,7 @@ __END__
 
 =head1 NAME
 
-Irssi::Dcc
+Irssi::Irc::Dcc
 
 =head1 FIELDS
 
diff --git a/docs/Irssi/Irc/Notifylist.pod b/docs/Irssi/Irc/Notifylist.pod
index 5b2628a..fd933ef 100644
--- a/docs/Irssi/Irc/Notifylist.pod
+++ b/docs/Irssi/Irc/Notifylist.pod
@@ -2,11 +2,12 @@ __END__
 
 =head1 NAME
 
-Irssi::Notifylist
+Irssi::Irc::Notifylist
 
 =head1 FIELDS
 
 Notifylist->{}
+
   mask - Notify nick mask
   away_check - Notify away status changes
   idle_check_time - Notify when idle time is reset and idle was bigger
@@ -16,6 +17,7 @@ Notifylist->{}
 
 =head1 METHODS
 
-Notifylist::ircnets_match(ircnet)
-  Returns 1 if notify is checked in `ircnet'.
+=head2 C<ircnets_match $ircnet>
+
+Returns 1 if notify is checked in `ircnet'.
 
diff --git a/docs/Irssi/UI/Window.pod b/docs/Irssi/UI/Window.pod
index a00827e..aa601a8 100644
--- a/docs/Irssi/UI/Window.pod
+++ b/docs/Irssi/UI/Window.pod
@@ -6,7 +6,8 @@ Irssi::UI::Window
 
 =head1 FIELDS
 
-UI::Window->{}
+C<UI::Window-E<gt>{}>
+
   refnum - Reference number
   name - Name
 
@@ -33,7 +34,8 @@ UI::Window->{}
 
   theme_name - Active theme in window, undef = default
 
-UI::TextDest->{}
+C<UI::TextDest-E<gt>{}>
+
   window - Window where the text will be written
   server - Target server
   target - Target channel/query/etc name
@@ -45,72 +47,92 @@ UI::TextDest->{}
 
 =head1 METHODS
 
-Window::command(cmd)
-Window::print(str[, level])
+=head2 C<command $cmd>
 
+=head2 C<print $str, [$level]>
 
-Window::items()
-  Return a list of items in window.
+=head2 C<items>
+
+Return a list of items in window.
 
-Window
-window_create(automatic)
-Windowitem::window_create(automatic)
-  Create a new window.
 
-Window::destroy()
-  Destroy the window.
+=head2 C<window_create $automatic>
+
+=head2 C<destroy>
+
+Destroy the window.
 
 Irssi::Window
 Windowitem::window()
   Returns parent window for window item.
 
-Window
-window_find_name(name)
-  Find window with name.
+=head2 C<window_find_name $name>
 
-Window
-window_find_refnum(refnum)
-  Find window with reference number.
+Find window with name.L<Irssi::UI::Window>
+
+=head2 C<window_find_refnum $refnum>
+
+Find window with reference number.
 
 Window
 window_find_level(level)
+
 Server::window_find_level(level)
   Find window with level.
 
 Window
 window_find_closest(name, level)
+
 Server::window_find_closest(name, level)
   Find window that matches best to given arguments. `name' can be either
   window name or name of one of the window items.
 
 Window
 window_find_item(name)
+
 Server::window_find_item(name)
   Find window which contains window item with specified name/server.
 
 
-Window::item_add(item, automatic)
-Window::item_remove(item)
-Window::item_destroy(item)
-  Add/remove/destroy window item
+=head2 C<item_add $item, $automatic>
+
+Add specified windowitem
+
+=head2 C<item_remove $item>
+
+remove specified windowitem
+
+=head2 C<item_destroy $item>
+
+destroy specified windowitem
+
+=head2 C<set_active>
+
+Set window active.
+
+=head2 C<change_server $server>
+
+=head2 C<set_refnum $refnum>
+
+=head2 C<set_name $name>
+
+=head2 C<set_history $name>
+
+=head2 C<set_level $level>
+
+Change server/refnum/name/history/level in window.
+
+=head2 C<item_prev>
+
+=head2 C<item_next>
 
-Window::set_active()
-  Set window active.
+Change to previous/next window item.
 
-Window::change_server(server)
-Window::set_refnum(refnum)
-Window::set_name(name)
-Window::set_history(name)
-Window::set_level(level)
-  Change server/refnum/name/history/level in window.
 
-Window::item_prev()
-Window::item_next()
-  Change to previous/next window item.
+=head2 C<get_active_name>
 
+Return active item's name, or if none is active, window's name
 
-Window::get_active_name()
-  Return active item's name, or if none is active, window's name
+=head2 C<item_find $server, $name>
 
-Window::item_find(server, name)
-  Find window item that matches best to given arguments.
+Find window item that matches best to given arguments.
diff --git a/docs/Irssi/Windowitem.pod b/docs/Irssi/Windowitem.pod
index f91183c..45cde9c 100644
--- a/docs/Irssi/Windowitem.pod
+++ b/docs/Irssi/Windowitem.pod
@@ -57,3 +57,6 @@ Returns 1 if window item is the active item in parent window.
 
 If `item' is a query of a =nick, return DCC chat record of nick.
 returns L<Irssi::Dcc> object.
+
+Windowitem::window_create(automatic)
+  Create a new window.
diff --git a/docs/Signals.pod b/docs/Signals.pod
index 4940671..7c1f6db 100644
--- a/docs/Signals.pod
+++ b/docs/Signals.pod
@@ -251,7 +251,7 @@ B<TODO: What are CHAT_PROTOCOL_REC types?>
 
 =back
 
-=item C<"send command"> 
+=item C<"send command">
 
 =over
 
@@ -263,7 +263,7 @@ B<TODO: What are CHAT_PROTOCOL_REC types?>
 
 =back
 
-=item C<"send text"> 
+=item C<"send text">
 
 =over
 
@@ -275,9 +275,9 @@ B<TODO: What are CHAT_PROTOCOL_REC types?>
 
 =back
 
-=item C<"command "<cmd>> 
+=item C<"command "<cmd>>
 
-=over 
+=over
 
 =item string C<$args>
 
@@ -337,7 +337,7 @@ B<TODO: check this "cmd" out?>
 
 =over 4
 
-=item C<"log new"> 
+=item C<"log new">
 
 =over
 
@@ -413,7 +413,7 @@ B<TODO: what are these types?>
 
 =item C<"module loaded">
 
-=over 
+=over
 
 =item MODULE_REC C<$module>
 
@@ -423,7 +423,7 @@ B<TODO: what are these types?>
 
 =item C<"module unloaded">
 
-=over 
+=over
 
 =item MODULE_REC C<$module>
 
@@ -535,7 +535,7 @@ B<TODO: what are these types?>
 
 =over 4
 
-=item C<"query created"> 
+=item C<"query created">
 
 =over
 
@@ -545,7 +545,7 @@ B<TODO: what are these types?>
 
 =back
 
-=item C<"query destroyed"> 
+=item C<"query destroyed">
 
 =over
 
@@ -553,7 +553,7 @@ B<TODO: what are these types?>
 
 =back
 
-=item C<"query nick changed"> 
+=item C<"query nick changed">
 
 =over
 
diff --git a/history-search/irssi/config b/history-search/irssi/config
index 052c67c..17cd55e 100644
--- a/history-search/irssi/config
+++ b/history-search/irssi/config
@@ -263,4 +263,5 @@ settings = {
   };
   "fe-text" = { actlist_sort = "refnum"; };
   "perl/core/scripts" = { autoinstall_custom_prompt = "yes"; };
+  "fe-common/core" = { bell_beeps = "yes"; };
 };