From 5616936940e4bd5a987edda4f029ffa6265aaf48 Mon Sep 17 00:00:00 2001
From: Tom Feist <shabble@cowu.be>
Date: Fri, 23 Jul 2010 01:19:03 +0100
Subject: additional docs about some Irssi:: core funcs

---
 docs/Guide.pod                     | 29 +++++++++++++++++-
 docs/Irssi.pod                     | 63 +++++++++++++++++++-------------------
 docs/Signals.pod                   | 18 +++++++++--
 history-search/irssi/config        |  4 ++-
 history-search/irssi/default.theme |  2 +-
 5 files changed, 79 insertions(+), 37 deletions(-)

diff --git a/docs/Guide.pod b/docs/Guide.pod
index 8f27823..9d52ed1 100644
--- a/docs/Guide.pod
+++ b/docs/Guide.pod
@@ -176,7 +176,7 @@ that the package and function exist, and generate an error otherwise. Other
 error handling is possible, including executing a C</SCRIPT LOAD> to load the
 necessary script and retry, but is not shown here.
 
-I<This snippet was provided by C<Bazerka> on Freenode/#irssi.>
+I<This snippet was provided by C<Bazerka> on Freenode/#irssi>.
 
 =head2 If In Doubt, Dump!
 
@@ -219,6 +219,9 @@ This example demonstrates overriding the C</HELP> command, and if the argument
 matches our command, print some custom help and prevent the internal Irssi help
 function from being called.  Otherwise, it falls back to the default help.
 
+
+I<This snippet was provided by C<nightfrog> on Freenode/#irssi>.
+
 =head3 Use Tab Completion
 
 One of the great features of Irssi is the ability to complete commands,
@@ -226,6 +229,30 @@ subcommands and even certain arguments.  Using the subcommands processing featur
 described below automatically allows those subcommands to be tab-completed, but
 for more complex tasks, you can hook into the autocompletion system itself.
 
+In order to create your own completions, you must intercept the C<"complete
+word"> signal and return a list of completion candidates.
+
+    sub do_complete {
+        my ($strings, $window, $word, $linestart, $want_space) = @_;
+
+        # only provide these completions if the input line is otherwise empty.
+        return unless ($linestart eq '' && $word eq '');
+
+        # add the completion candidates
+        push @$strings, qw/foo bar baz bacon/;
+
+        # indicate that we want to include a space after the completion
+        $$want_space = 1;
+
+        # prevent internal Irssi completion from responding
+        Irssi::signal_stop;
+    }
+
+    Irssi::signal_add_first('complete word',  \&do_complete);
+
+I<This snippet taken from
+L<F<complete_lastspoke.pl>|http://scripts.irssi.org/scripts/complete_lastspoke.pl>
+by Daenyth>
 
 =head3 Use Settings for Customisation
 
diff --git a/docs/Irssi.pod b/docs/Irssi.pod
index 3187763..49e83fa 100644
--- a/docs/Irssi.pod
+++ b/docs/Irssi.pod
@@ -65,7 +65,7 @@ B<TODO: fix this list with proper package names>
 
 =item L<Irssi::Theme>
 
-=item L<Irssi::Window>
+=item L<Irssi::UI::Window>
 
 =item L<Irssi::Windowitem>
 
@@ -90,7 +90,7 @@ For example:
 
 C<my $win = Irssi::active_win();>
 
-returns the currently active L<Irssi::Window>
+returns the currently active L<Irssi::UI::Window>
 
 =head3 C<active_server>
 
@@ -100,7 +100,7 @@ returns the currently active L<Irssi::Server> in active window.
 
 =head3 C<windows>
 
-returns a list of all L<windows|Irssi::Window>.
+returns a list of all L<windows|Irssi::UI::Window>.
 
 =head3 C<servers>
 
@@ -130,11 +130,6 @@ returns a list of all L<log files|Irssi::Log>.
 
 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
 
 See also L<Signals>
@@ -428,6 +423,8 @@ used to build space-separated lists of entries.
 
 An integer type.  Integers must be whole numbers, but may also be negative or zero.
 
+It is stored internally as a C<signed int>, and has a range of +/- 2^31.
+
 =item C<bool>
 
 A boolean type.  In Perl terms, values are C<0> for false, and anything else for
@@ -435,16 +432,32 @@ true.  When acting on them externally, C<ON> and C<OFF> are the usual terms used
 
 =item C<time>
 
-A time type. B<TODO: what values can it take?>
+A time type. An integer with optional unit specifier.  Valid specifiers are:
+
+    days
+    hours
+    minutes / mins
+    seconds / secs
+    milliseconds / millisecs / mseconds / msecs
+
+B<TODO: can different specifiers be combined?>
+
+The value is stored internally as a number of milliseconds.  Since it is stored
+as an C<signed int>, it will overflow at 2^31 ms, or approximately 24 days.
+
+Times longer than this are considered invalid.
 
 =item C<level>
 
 An irssi Messagelevel. See C</HELP LEVELS> for a full list and description, or
-L</Message Levels> for a description of the Perl equivalents.
+L</Message Levels> for a list of the Perl equivalents.
 
 =item C<size>
 
-B<TODO: What is this for?>
+A size type. This is an non-negative integer, and the default suffix is I<kbytes>.
+An optional suffix of C<bytes>, C<kbytes>, C<mbytes>, or C<gbytes> can be used
+to set the size accordingly. Note that sizes are given using the exponent of 2
+scheme, rather than the decimal C<$x * 1000> system.
 
 =back
 
@@ -489,20 +502,21 @@ This can be done with:
 
 Remove a setting specified with C<$key>.
 
-
 =head2 IO and Process Management
 
 =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>. C<$msecs> must be at least 10 or an error is signaled via C<croak>.
+
+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 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>.
+C<$data>. C<$msecs> must be at least 10 or an error is signaled via C<croak>.
+
+Returns tag which can be used to stop the timeout via L</timeout_remove $tag>.
 
 =head3 C<timeout_remove $tag>
 
@@ -644,21 +658,6 @@ For example:
 
 Returns the current L<theme|Irssi::UI::Theme> object.
 
-=head2 DCC
-
-B<TODO: This should probably move to L<Irssi::Irc>
-
-See also L<Irssi::Dcc>
-
-Dcc
-dcc_find_item(type, nick, arg)
-  Find DCC connection.
-
-Dcc
-dcc_find_by_port(nick, port)
-  Find DCC connection by port.
-
-
 =head2 Channels
 
 =head3 C<channel_find $channel>
diff --git a/docs/Signals.pod b/docs/Signals.pod
index 2fcf913..93c79db 100644
--- a/docs/Signals.pod
+++ b/docs/Signals.pod
@@ -1614,7 +1614,7 @@ B<Requires to work properly:>
 
 =back
 
-(Can be used to determine when all "gui print text"s are sent (not required))
+(Can be used to determine when all C<"gui print text">s are sent (not required))
 
 =back
 
@@ -1629,16 +1629,30 @@ B<Provides signals:>
 
 =over
 
-=item arrayref of string C<$WHAT> B<TODO: ???>
+=item arrayref of strings C<$strings_ref>
+
+An arrayref which can be modified to add additional completion candidates.
+
+For example:
+
+    push @$strings_ref, "another_candidate";
 
 =item L<Irssi::Window> C<$window>
 
 =item string C<$word>
 
+The prefix of the word currently being typed.
+
 =item string C<$linestart>
 
+The contents of the input line up to (but not including) the current
+word prefix C<$word>.
+
 =item int C<$want_space>
 
+A scalar reference which can be set to indicate if tab completion of these
+candidates should be appended with a space.
+
 =back
 
 =back
diff --git a/history-search/irssi/config b/history-search/irssi/config
index 693c426..6b7db48 100644
--- a/history-search/irssi/config
+++ b/history-search/irssi/config
@@ -251,10 +251,12 @@ statusbar = {
     };
     prompt = {
       items = {
-        custom_prompt = { priority = "-5"; };
+        prompt = { };
+        prompt_empty = { };
         input = { priority = "10"; };
       };
     };
+    promptadd = { disabled = "yes"; };
   };
 };
 settings = {
diff --git a/history-search/irssi/default.theme b/history-search/irssi/default.theme
index 98af18b..5e2a735 100644
--- a/history-search/irssi/default.theme
+++ b/history-search/irssi/default.theme
@@ -271,7 +271,7 @@ abstracts = {
   topicsbstart = "{sbstart $*}";
   topicsbend = "{sbend $*}";
 
-  prompt = "[$*] ";
+  prompt = "[$* $expando_test] ";
 
   sb = " %c[%n$*%c]%n";
   sbmode = "(%c+%n$*)";
-- 
cgit v1.2.3