aboutsummaryrefslogtreecommitdiffstats
path: root/docs/Guide.pod
diff options
context:
space:
mode:
authorTom Feist <shabble@cowu.be>2010-07-21 17:07:50 +0000
committerTom Feist <shabble@cowu.be>2010-07-21 17:07:50 +0000
commit440f9d752fa43726ac73e4482994e73417ec8de9 (patch)
treefe123238d1268c5dcf6a4b5858cb40f818dd770d /docs/Guide.pod
parentadded some stuff to the guide, and cleaned up some irssi.pod function descs (diff)
downloadirssi-scripts-440f9d752fa43726ac73e4482994e73417ec8de9.tar.gz
irssi-scripts-440f9d752fa43726ac73e4482994e73417ec8de9.zip
stubbed out empty files, mroe content in Guide
Diffstat (limited to 'docs/Guide.pod')
-rw-r--r--docs/Guide.pod52
1 files changed, 47 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>