aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--docs/Guide.pod52
-rw-r--r--docs/Irssi.pod42
-rw-r--r--docs/Irssi/TextUI/Line.pod3
-rw-r--r--docs/Irssi/TextUI/LineCache.pod3
-rw-r--r--docs/Irssi/TextUI/LineInfo.pod3
-rw-r--r--docs/Irssi/TextUI/MainWindow.pod3
-rw-r--r--docs/Irssi/TextUI/StatusbarItem.pod3
-rw-r--r--docs/Irssi/TextUI/TextBufferView.pod3
-rw-r--r--docs/Irssi/TextUI/Textbuffer.pod3
9 files changed, 110 insertions, 5 deletions
diff --git a/docs/Guide.pod b/docs/Guide.pod
index 239aac7..eba0912 100644
--- a/docs/Guide.pod
+++ b/docs/Guide.pod
@@ -10,8 +10,19 @@ Guide To Irssi Scripting.
=head2 File Locations
+Packaged Irssi script files are usually placed in F</usr/share/irssi/scripts/>,
+but custom scripts or those required by a single user can be placed in
+F<~/.irssi/scripts/>.
+
+=head3 Autorunning 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/>.
+
=head2 Testing
+B<TODO: Forgotten what was going to go here>
+
=head2 Loading
Scripts are loaded via C</SCRIPT LOAD I<filename>>. A default Irssi
@@ -22,7 +33,6 @@ 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
A script can be unloaded via the C</SCRIPT UNLOAD I<name>> command. The name is
@@ -44,6 +54,12 @@ network connections or processes, and restore any Irssi modifications made.
In this section, we develop a very simplistic script and look at the
necessary code.
+B<Note:> This section has considerable overlap with L<Juerd's Scripting
+Tutorial|http://juerd.nl/site.plp/irssiscripttut>, which you may also
+wish to read.
+
+B<TODO: Figure out a basic script to use as an example>
+
=head2 Preamble
All scripts should contain a header as follows:
@@ -111,8 +127,22 @@ handling Irssi signals, or by calling functions from one another directly.
=head3 Using Signals
+In order to use custom signals, they must first be registered with Irssi.
+During registration, a list of the parameters must also be specified. Once specified,
+it cannot be changed without restarting Irssi, so be warned.
+
+After registration, your script can simply listen for signals with
+L<Irssi::signal_add|Irssi/signal_add $sig_name, $func>, or generate them for
+others to handle with L<Irssi::signal_emit|Irssi/signal_emit $sig_name, @params>
+
+For example:
+
+B<TODO: Example here>
+
=head3 Using Functions
+B<TODO: Find the example code that demonstrates this>
+
=head2 If In Doubt, Dump!
C<Data::Dumper> is an extremely good way to inspect Irssi internals if you're
@@ -139,17 +169,29 @@ of their file. Whilst better than no documentation at all, a preferable approac
is to allow that help to be accessed from within Irssi itself, using the C</HELP>
command.
-B<TODO: how>
-
+B<TODO: example - catch or rebind /HELP, then check args and either print and
+sig_stop or continue>
=head3 Use Tab Completion
One of the great features of Irssi is the ability to complete commands,
-subcommands and even certain arguments.
+subcommands and even certain arguments. Using the subcommands processing feature
+described below automatically allows those subcommands to be tab-completed, but
+for more complex tasks, you can hook into the autocompletion system itself.
+
+
=head3 Use Settings for Customisation
-B<TODO: why?>
+Many scripts require the setting of various parameters to affect how they behave.
+One approach is to require the user to directly edit the script file, but this
+is less than ideal for a number of reasons. Firstly, it is easy to introduce
+errors into a script by accidentally deleting closing quotes or semicolons.
+Secondly, it has no effect until the script is reloaded, leading to confusion.
+
+A much better alternative is to use Irssi's inbuilt settings mechanism to allow
+users to set these parameters from within Irssi, as well as to C</SAVE> their
+settings for subsequent invocations.
B<TODO: different types of settings>
diff --git a/docs/Irssi.pod b/docs/Irssi.pod
index 97e4799..d67b9aa 100644
--- a/docs/Irssi.pod
+++ b/docs/Irssi.pod
@@ -404,6 +404,48 @@ using one of the C<settings_add> functions.
=head4 C<settings_add_size $section, $key, $def>
+Each of the above functions operates in the same way, but creates a different
+data type. For each function, C<$section> is a string describing the
+group the entry falls into, C<$key> is the name of the setting. The key must
+be a single string, and typically multiple words are separated by underscores.
+
+The final parameter, C<$def>, is the default value of this setting. It should
+correspond to the type of the setting being created.
+
+B<TODO: move this list to another section?>
+
+The following list summarises the data types available:
+
+=over
+
+=item C<str>
+
+A generic string type, which can contain arbitrary text. It is also commonly
+used to build space-separated lists of entries.
+
+=item C<int>
+
+An integer type. Integers must be whole numbers, but may also be negative or zero.
+
+=item C<bool>
+
+A boolean type. In Perl terms, values are C<0> for false, and anything else for
+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?>
+
+=item C<level>
+
+An irssi Messagelevel. See C</HELP LEVELS> for a full list and description.
+
+=item C<size>
+
+B<TODO: What is this for?>
+
+=back
+
=head3 Retrieving Settings
=head4 C<settings_get_str $key>
diff --git a/docs/Irssi/TextUI/Line.pod b/docs/Irssi/TextUI/Line.pod
index e69de29..08bdae1 100644
--- a/docs/Irssi/TextUI/Line.pod
+++ b/docs/Irssi/TextUI/Line.pod
@@ -0,0 +1,3 @@
+__END__
+
+=head1 Empty
diff --git a/docs/Irssi/TextUI/LineCache.pod b/docs/Irssi/TextUI/LineCache.pod
index e69de29..08bdae1 100644
--- a/docs/Irssi/TextUI/LineCache.pod
+++ b/docs/Irssi/TextUI/LineCache.pod
@@ -0,0 +1,3 @@
+__END__
+
+=head1 Empty
diff --git a/docs/Irssi/TextUI/LineInfo.pod b/docs/Irssi/TextUI/LineInfo.pod
index e69de29..08bdae1 100644
--- a/docs/Irssi/TextUI/LineInfo.pod
+++ b/docs/Irssi/TextUI/LineInfo.pod
@@ -0,0 +1,3 @@
+__END__
+
+=head1 Empty
diff --git a/docs/Irssi/TextUI/MainWindow.pod b/docs/Irssi/TextUI/MainWindow.pod
index e69de29..08bdae1 100644
--- a/docs/Irssi/TextUI/MainWindow.pod
+++ b/docs/Irssi/TextUI/MainWindow.pod
@@ -0,0 +1,3 @@
+__END__
+
+=head1 Empty
diff --git a/docs/Irssi/TextUI/StatusbarItem.pod b/docs/Irssi/TextUI/StatusbarItem.pod
index e69de29..08bdae1 100644
--- a/docs/Irssi/TextUI/StatusbarItem.pod
+++ b/docs/Irssi/TextUI/StatusbarItem.pod
@@ -0,0 +1,3 @@
+__END__
+
+=head1 Empty
diff --git a/docs/Irssi/TextUI/TextBufferView.pod b/docs/Irssi/TextUI/TextBufferView.pod
index e69de29..08bdae1 100644
--- a/docs/Irssi/TextUI/TextBufferView.pod
+++ b/docs/Irssi/TextUI/TextBufferView.pod
@@ -0,0 +1,3 @@
+__END__
+
+=head1 Empty
diff --git a/docs/Irssi/TextUI/Textbuffer.pod b/docs/Irssi/TextUI/Textbuffer.pod
index e69de29..08bdae1 100644
--- a/docs/Irssi/TextUI/Textbuffer.pod
+++ b/docs/Irssi/TextUI/Textbuffer.pod
@@ -0,0 +1,3 @@
+__END__
+
+=head1 Empty