From 5a5c6461b163f00b9d4e2c8265b0ebb10c2be2e1 Mon Sep 17 00:00:00 2001 From: Tom Feist Date: Wed, 21 Jul 2010 20:58:21 +0100 Subject: added formats, and some copypasta from default.theme comments into theme --- docs/Formats.pod | 37 ++++++++++ docs/Guide.pod | 5 +- docs/Irssi.pod | 186 ++++++++++++++++++++++++++++-------------------- docs/Irssi/Channel.pod | 67 +++++++++-------- docs/Irssi/Irc/Dcc.pod | 8 +-- docs/Irssi/Log.pod | 36 +++++----- docs/Irssi/Logitem.pod | 4 +- docs/Irssi/Nick.pod | 3 +- docs/Irssi/Rawlog.pod | 42 ++++++----- docs/Irssi/UI/Theme.pod | 56 +++++++++++++++ docs/Signals.pod | 24 ++++++- 11 files changed, 316 insertions(+), 152 deletions(-) create mode 100644 docs/Formats.pod diff --git a/docs/Formats.pod b/docs/Formats.pod new file mode 100644 index 0000000..0902d78 --- /dev/null +++ b/docs/Formats.pod @@ -0,0 +1,37 @@ +__END__ + +=head1 NAME + +Formats + +=head1 DESCRIPTION + +Irssi's colors that you can use in text formats, hilights, etc: + + text text background + --------------------------------------------------------------------- + %k %K %0 black dark grey black + %r %R %1 red bold red red + %g %G %2 green bold green green + %y %Y %3 yellow bold yellow yellow + %b %B %4 blue bold blue blue + %m %M %5 magenta bold magenta magenta + %p %P magenta (think: purple) + %c %C %6 cyan bold cyan cyan + %w %W %7 white bold white white + %n %N Changes the color to "default color", removing + all other coloring and formatting. %N is always + the terminal's default color. %n is usually too, + except in themes it changes to "previous color", + ie. hello = "%Rhello%n" and "%G{hello} world" + would print hello in red, and %n would turn back + into %G making world green. + %F Blinking on/off (think: flash) + %U Underline on/off + %8 Reverse on/off + %9 %_ Bold on/off + %: Insert newline + %| Marks the indentation position + %# Monospace font on/off (useful with lists and GUI) + %% A single % + diff --git a/docs/Guide.pod b/docs/Guide.pod index eba0912..b540e75 100644 --- a/docs/Guide.pod +++ b/docs/Guide.pod @@ -87,7 +87,8 @@ The C defines two global variables, which are then set below to the appropriate values. C tells the script to make the various L support functions available. - +Additional parameters passed here with C can be used to import functions into +the current script namespace. =head1 COMMONLY SCRIPTED TASKS @@ -197,6 +198,8 @@ B B +B + =head3 Use Subcommands to Group Script Functionality A common theme in Irssi scripts is to define commands with a prefix, such as diff --git a/docs/Irssi.pod b/docs/Irssi.pod index d67b9aa..c02f852 100644 --- a/docs/Irssi.pod +++ b/docs/Irssi.pod @@ -18,8 +18,8 @@ support is available. If not, refer to the F file for how to recompile irssi. The C package is the basis of Perl scripting in Irssi. It does not export any -functions, and requires that all function-calls be fully qualified with the -C> prefix. +functions by default, and requires that all function-calls be fully qualified with the +C> prefix. See L for alternatives. =head1 CLASSES @@ -31,19 +31,19 @@ B =over 4 -=item L - =item L -=item L +=item L -=item L +=item L -=item L +=item L -=item L +=item L -=item L +=item L + +=item L =item L @@ -51,8 +51,6 @@ B =item L -=item L - =item L =item L @@ -462,104 +460,124 @@ B =head3 Modifying Settings +=head4 C + +=head4 C + +=head4 C + +=head4 C + +=head4 C + +=head4 C + +Changes the value of the setting with key C<$key> to C<$value>. + B signal afterwards.> -=head4 C +This can be done with: -=head4 C + Irssi::signal_emit("setup changed"); -=head4 C +=head4 C -=head4 C +Remove a setting specified with C<$key>. -=head4 C -=head4 C +=head2 IO and Process Management -=head4 C +=head3 C -Remove a setting. + 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. +=head3 C -=head2 IO and Process Management +Call `func' once after `msecs' milliseconds (1000 = 1 second) +with parameter `data'. Returns tag which can be used to stop the timeout. + +=head3 C + +Remove timeout specified with tag C<$tag>. -timeout_add(msecs, func, data) - Call `func' every `msecs' milliseconds (1000 = 1 second) with - parameter `data'. Returns tag which can be used to stop the timeout. +=head3 C -timeout_add_once(msecs, func, data); - Call `func' once after `msecs' milliseconds (1000 = 1 second) - with parameter `data'. Returns tag which can be used to stop the timeout. +Call `func' with parameter `data' when specified IO happens. +`source' is the file handle that is being listened. `condition' can +be INPUT_READ, INPUT_WRITE or both. Returns tag which can be used to +remove the listener. -timeout_remove(tag) - Remove timeout with tag. +=head3 C -input_add(source, condition, func, data) - Call `func' with parameter `data' when specified IO happens. - `source' is the file handle that is being listened. `condition' can - be INPUT_READ, INPUT_WRITE or both. Returns tag which can be used to - remove the listener. +Remove listener with tag. -input_remove(tag) - Remove listener with tag. +=head3 C -pidwait_add(pid) - Adds `pid' to the list of processes to wait for. The pid must identify - a child process of the irssi process. When the process terminates, a - "pidwait" signal will be sent with the pid and the status from - waitpid(). This is useful to avoid zombies if your script forks. +Adds `pid' to the list of processes to wait for. The pid must identify +a child process of the irssi process. When the process terminates, a +"pidwait" signal will be sent with the pid and the status from +waitpid(). This is useful to avoid zombies if your script forks. -pidwait_remove(pid) - Removes `pid' from the list of processes to wait for. Terminated - processes are removed automatically, so it is usually not necessary - to call this function. +=head3 C +Removes `pid' from the list of processes to wait for. Terminated +processes are removed automatically, so it is usually not necessary +to call this function. =head2 Message Levels -level2bits(level) +=head3 C + Level string -> number -bits2level(bits) +=head3 C + Level number -> string -combine_level(level, str) +=head3 C + Combine level number to level string ("+level -level"). Return new level number. =head2 Themes -See also L +See also L You can have user configurable texts in scripts that work just like irssi's internal texts that can be changed in themes. First you'll have to register the formats: - -Irssi::theme_register([ - 'format_name', '{hilight my perl format!}', - 'format2', 'testing.. nick = $0, channel = $1' -]); + Irssi::theme_register([ + 'format_name', '{hilight my perl format!}', + 'format2', 'testing.. nick = $0, channel = $1' + ]); Printing happens with one of the functions: -printformat(level, format, ...) -Window::printformat(level, format, ...) -Server::printformat(target, level, format, ...) -Windowitem::printformat(level, format, ...) + printformat $level, $format, ... + + Window::printformat $level, $format, ... + + Server::printformat $target, $level, $format, ... + + Windowitem::printformat $level, $format, ... For example: - $channel->printformat(MSGLEVEL_CRAP, 'format2', - 'nick', $channel->{name}); + $channel->printformat(MSGLEVEL_CRAP, 'format2', + 'nick', $channel->{name}); =head2 DCC +B + See also L Dcc @@ -573,48 +591,58 @@ dcc_find_by_port(nick, port) =head2 Channels -Channel -channel_find(channel) - Find channel from any server. +=head3 C + +Find channel from any server. Returns an L object. + =head2 Ignores +=head3 C -ignore_add_rec(ignore) - Add ignore record. +Add ignore record. + +=head3 C + +Update ignore record in configuration + +=head3 C + +B -ignore_update_rec(ignore) - Update ignore record in configuration -ignore_check(nick, host, channel, text, level) =head2 Logging +=head3 C + +Create log file. Returns L -Log -log_create_rec(fname, level) - Create log file. +=head3 C + +Find log with file name. Returns L -Log -log_find(fname) - Find log with file name. =head2 Raw Logging -Rawlog rawlog_create() - Create a new rawlog. +=head3 C + +Create a new rawlog. Returns an L object. -rawlog_set_size(lines) - Set the default rawlog size for new rawlogs. +=head3 C + +Set the default rawlog size for new rawlogs. =head2 Chat-Nets -chatnet_find(name) - Find chat network with name. +=head3 C + +Find chat network with name. =head2 Status Bars +See also L B =head1 COPYRIGHT diff --git a/docs/Irssi/Channel.pod b/docs/Irssi/Channel.pod index bb6789d..baeff6c 100644 --- a/docs/Irssi/Channel.pod +++ b/docs/Irssi/Channel.pod @@ -6,7 +6,8 @@ Irssi::Channel =head1 FIELDS -Channel->{} +C{}> + type - "CHANNEL" text chat_type - String ID of chat protocol, for example "IRC" @@ -35,45 +36,51 @@ Channel->{} -Server::channels_join(channels, automatic) - Join to channels in server. `channels' may also contain keys for - channels just like with /JOIN command. `automatic' specifies if this - channel was joined "automatically" or if it was joined because join - was requested by user. If channel join is "automatic", irssi doesn't - jump to the window where the channel was joined. +=head2 C + +Join to channels in server. `channels' may also contain keys for +channels just like with /JOIN command. `automatic' specifies if this +channel was joined "automatically" or if it was joined because join +was requested by user. If channel join is "automatic", irssi doesn't +jump to the window where the channel was joined. + +=head2 C + +Destroy channel. + +=head2 C + +Return a list of bans in channel. + +=head2 C + +Get ban mask for `nick'. + +=head2 C + +Add a new ban to channel. +=head2 C -Channel::destroy() - Destroy channel. +Remove a ban from channel. -Channel::bans() - Return a list of bans in channel. +=head2 C -Channel::ban_get_mask(nick) - Get ban mask for `nick'. +Add nick to nicklist. Returns a L. -Channel::banlist_add(ban, nick, time) - Add a new ban to channel. +=head2 C -Channel::banlist_remove(ban) - Remove a ban from channel. +Remove nick from nicklist. +=head2 C -Nick -Channel::nick_insert(nick, op, voice, send_massjoin) - Add nick to nicklist. +Find nick from nicklist. Returns L. -Channel::nick_remove(nick) - Remove nick from nicklist. +=head2 C -Nick -Channel::nick_find(nick) - Find nick from nicklist. +Find nick mask from nicklist, wildcards allowed. Returns L. -Nick -Channel::nick_find_mask(mask) - Find nick mask from nicklist, wildcards allowed. +=head2 C -Channel::nicks() - Return a list of all nicks in channel. +Return a list of all nicks in channel. diff --git a/docs/Irssi/Irc/Dcc.pod b/docs/Irssi/Irc/Dcc.pod index 5950a92..5ba52b9 100644 --- a/docs/Irssi/Irc/Dcc.pod +++ b/docs/Irssi/Irc/Dcc.pod @@ -6,7 +6,7 @@ Irssi::Irc::Dcc =head1 FIELDS -=head2 C{}> +=head2 C{}> type - Type of the DCC: chat, send, get orig_type - Original DCC type that was sent to us - same as type except @@ -29,13 +29,13 @@ Irssi::Irc::Dcc starttime - Unix time stamp when the DCC transfer was started transfd - Bytes transferred -=head2 C{}> +=head2 C{}> id - Unique identifier - usually same as nick mirc_ctcp - Send CTCPs without the CTCP_MESSAGE prefix connection_lost - Other side closed connection -=head2 C{}> +=head2 C{}> (..contains all the same data as core Dcc object..) size - File size @@ -47,7 +47,7 @@ Irssi::Irc::Dcc file - The real file name which we use. file_quoted - 1 if file name was received quoted ("file name") -=head2 C{}> +=head2 C{}> (..contains all the same data as core Dcc object..) size - File size diff --git a/docs/Irssi/Log.pod b/docs/Irssi/Log.pod index 673a183..68163a2 100644 --- a/docs/Irssi/Log.pod +++ b/docs/Irssi/Log.pod @@ -6,7 +6,8 @@ Irssi::Log =head1 FIELDS -Log->{} +C{}> + fname - Log file name real_fname - The actual opened log file (after %d.%m.Y etc. are expanded) opened - Log file is open @@ -20,27 +21,30 @@ Log->{} =head1 METHODS +=head2 C + +Add log to list of logs / save changes to config file. + +=head2 C + +Destroy log file. + +=head2 C -Log::update() - Add log to list of logs / save changes to config file. +Open log file and start logging. +=head2 C -Log::close() - Destroy log file. +Close log file. -Log::start_logging() - Open log file and start logging. +=head2 C -Log::stop_logging() - Close log file. +Add log item to log. -Log::item_add(type, name, server) - Add log item to log. +=head2 C -Log::item_destroy(item) - Remove log item from log. +Remove log item from log. +=head2 C -Logitem -Log::item_find(type, item, server) - Find item from log. +Find item from log. Returns L diff --git a/docs/Irssi/Logitem.pod b/docs/Irssi/Logitem.pod index 6db0c7b..f30d4b8 100644 --- a/docs/Irssi/Logitem.pod +++ b/docs/Irssi/Logitem.pod @@ -6,11 +6,11 @@ Irssi::Logitem =head1 FIELDS -Logitem->{} +C{}> + type - 0=target, 1=window refnum name - Name servertag - Server tag - =head1 METHODS diff --git a/docs/Irssi/Nick.pod b/docs/Irssi/Nick.pod index b20d43a..3e85256 100644 --- a/docs/Irssi/Nick.pod +++ b/docs/Irssi/Nick.pod @@ -6,7 +6,8 @@ Irssi::Nick =head1 FIELDS -Nick->{} +C{}> + type - "NICK" text chat_type - String ID of chat protocol, for example "IRC" diff --git a/docs/Irssi/Rawlog.pod b/docs/Irssi/Rawlog.pod index 7f89c64..a5428bf 100644 --- a/docs/Irssi/Rawlog.pod +++ b/docs/Irssi/Rawlog.pod @@ -7,34 +7,42 @@ Irssi::Rawlog =head1 FIELDS -Rawlog->{} +C{}> + logging - The rawlog is being written to file currently nlines - Number of lines in rawlog =head1 METHODS +=head2 C + +Destroy the rawlog. + +=head2 C + +Returns all lines in rawlog. + +=head2 C + +Start logging new messages in rawlog to specified file. + +=head2 C + +Stop logging to file. -Rawlog::destroy() - Destroy the rawlog. +=head2 C -Rawlog::get_lines() - Returns all lines in rawlog. +Save the current rawlog history to specified file. -Rawlog::open(filename) - Start logging new messages in rawlog to specified file. +=head2 C -Rawlog::close() - Stop logging to file. +Send `str' to raw log as input text. -Rawlog::save(filename) - Save the current rawlog history to specified file. +=head2 C -Rawlog::input(str) - Send `str' to raw log as input text. +Send `str' to raw log as output text. -Rawlog::output(str) - Send `str' to raw log as output text. +=head2 C -Rawlog::redirect(str) - Send `str' to raw log as redirection text. +Send `str' to raw log as redirection text. diff --git a/docs/Irssi/UI/Theme.pod b/docs/Irssi/UI/Theme.pod index 56e3a3f..4fff169 100644 --- a/docs/Irssi/UI/Theme.pod +++ b/docs/Irssi/UI/Theme.pod @@ -1,3 +1,5 @@ +__END__ + =head1 NAME Irssi::UI::Theme @@ -6,3 +8,57 @@ Irssi::UI::Theme =head1 METHODS +=head1 THEME DOCUMENTATION + +When testing changes, the easiest way to reload the theme is with /RELOAD. +This reloads the configuration file too, so if you did any changes remember +to /SAVE it first. Remember also that /SAVE overwrites the theme file with +old data so keep backups :) + +=head2 TEMPLATES + +The real text formats that irssi uses are the ones you can find with +/FORMAT command. Back in the old days all the colors and texts were mixed +up in those formats, and it was really hard to change the colors since you +might have had to change them in tens of different places. So, then came +this templating system. + +Now the Cs don't have any colors in them, and they also have very +little other styling. Most of the stuff you need to change is in this +theme file. If you can't change something here, you can always go back +to change the /FORMATs directly, they're also saved in these .theme files. + +So .. the templates. They're those C<{blahblah}> parts you see all over the +/FORMATs and here. Their usage is simply C<{name parameter1 parameter2}>. + +When irssi sees this kind of text, it goes to find "name" from abstracts block +below and sets C into C<$0> and C into C<$1> (you can +have more parameters of course). Templates can have subtemplates. Here's a +small example: + + /FORMAT format hello {colorify {underline world}} + + abstracts = { colorify = "%G$0-%n"; underline = "%U$0-%U"; } + +When irssi expands the templates in "format", the final string would be: + + hello %G%Uworld%U%n + +ie. underlined bright green "world" text. +and why C<$0->, why not C<$0>? C<$0> would only mean the first parameter, +$0- means all the parameters. With {underline hello world} you'd really +want to underline both of the words, not just the hello (and world would +actually be removed entirely). + +=head2 COLORS + +You can find definitions for the color format codes in L + +There's one difference here though. %n format. Normally it means the +default color of the terminal (white mostly), but here it means the +"reset color back to the one it was in higher template". For example +if there was /FORMAT test %g{foo}bar, and foo = "%Y$0%n", irssi would +print yellow "foo" (as set with %Y) but "bar" would be green, which was +set at the beginning before the {foo} template. If there wasn't the %g +at start, the normal behaviour of %n would occur. If you _really_ want +to use the terminal's default color, use %N. diff --git a/docs/Signals.pod b/docs/Signals.pod index 7c1f6db..2fcf913 100644 --- a/docs/Signals.pod +++ b/docs/Signals.pod @@ -1606,10 +1606,18 @@ B =back +=item C<"gui print text finished"> + +=over + +=item L C<$window> + =back (Can be used to determine when all "gui print text"s are sent (not required)) - "gui print text finished", WINDOW_REC + +=back + B @@ -1619,7 +1627,19 @@ B =item C<"complete word"> -, GList * of char*, WINDOW_REC, char *word, char *linestart, int *want_space +=over + +=item arrayref of string C<$WHAT> B + +=item L C<$window> + +=item string C<$word> + +=item string C<$linestart> + +=item int C<$want_space> + +=back =back -- cgit v1.2.3