From 440f9d752fa43726ac73e4482994e73417ec8de9 Mon Sep 17 00:00:00 2001 From: Tom Feist Date: Wed, 21 Jul 2010 18:07:50 +0100 Subject: stubbed out empty files, mroe content in Guide --- docs/Guide.pod | 52 ++++++++++++++++++++++++++++++++---- docs/Irssi.pod | 42 +++++++++++++++++++++++++++++ docs/Irssi/TextUI/Line.pod | 3 +++ docs/Irssi/TextUI/LineCache.pod | 3 +++ docs/Irssi/TextUI/LineInfo.pod | 3 +++ docs/Irssi/TextUI/MainWindow.pod | 3 +++ docs/Irssi/TextUI/StatusbarItem.pod | 3 +++ docs/Irssi/TextUI/TextBufferView.pod | 3 +++ docs/Irssi/TextUI/Textbuffer.pod | 3 +++ 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, +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 + =head2 Loading Scripts are loaded via C>. A default Irssi @@ -22,7 +33,6 @@ Loaded scripts will exist in the Irssi namespace as: CnameE>>, where I is the filename stripped of its F<.pl> extension. - =head2 Unloading A script can be unloaded via the C> 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 This section has considerable overlap with L, which you may also +wish to read. + +B + =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, or generate them for +others to handle with L + +For example: + +B + =head3 Using Functions +B + =head2 If In Doubt, Dump! C 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 command. -B - +B =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 +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 their +settings for subsequent invocations. B 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 functions. =head4 C +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 + +The following list summarises the data types available: + +=over + +=item C + +A generic string type, which can contain arbitrary text. It is also commonly +used to build space-separated lists of entries. + +=item C + +An integer type. Integers must be whole numbers, but may also be negative or zero. + +=item C + +A boolean type. In Perl terms, values are C<0> for false, and anything else for +true. When acting on them externally, C and C are the usual terms used. + +=item C