From ce375dbf92cd89780138cff01deae6fbefb71cf6 Mon Sep 17 00:00:00 2001 From: Tom Feist Date: Mon, 18 Apr 2011 15:42:10 +0100 Subject: updated a whole bunch of README files. --- .gitignore | 2 + ido-mode/README.pod | 204 ++++++++++++++ prompt_info/README.pod | 0 tinyurl-tabcomplete/README.pod | 56 ++++ tinyurl-tabcomplete/complete-tiny-url.pl | 44 ++- vim-mode/README.pod | 444 +++++++++++++++++++++++++++++++ 6 files changed, 746 insertions(+), 4 deletions(-) create mode 100644 ido-mode/README.pod create mode 100644 prompt_info/README.pod create mode 100644 tinyurl-tabcomplete/README.pod create mode 100644 vim-mode/README.pod diff --git a/.gitignore b/.gitignore index 80ea4ea..91f484a 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,5 @@ /modules/*/*.so /modules/*/*.o /vim-mode/TAGS +/testing/irssi-test.log +/vim-mode/irssi/scripts/autorun/README.pod diff --git a/ido-mode/README.pod b/ido-mode/README.pod new file mode 100644 index 0000000..9c49c0f --- /dev/null +++ b/ido-mode/README.pod @@ -0,0 +1,204 @@ +=pod + +=head1 NAME + +ido_switcher.pl + +=head1 DESCRIPTION + +Search and select windows similar to ido-mode for emacs + +=head1 INSTALLATION + +This script requires that you have first installed and loaded F + +Uberprompt can be downloaded from: + +L + +and follow the instructions at the top of that file or its README for installation. + +If uberprompt.pl is available, but not loaded, this script will make one +attempt to load it before giving up. This eliminates the need to precisely +arrange the startup order of your scripts. + +=head2 SETUP + +C + +Where C<^G> is a key of your choice. + +=head2 USAGE + +C (or whatever you've set the above bind to), enters IDO window switching mode. +You can then type either a search string, or use one of the additional key-bindings +to change the behaviour of the search. C provides online help regarding +the possible interactive options. + +=head3 EXTENDED USAGE: + +It is possible to pass arguments to the /ido_switch_start command, which +correspond to some of the interactively settable parameters listed below. + +The following options are available: + +=over 4 + +=item C<-channels> -- search through only channels. + +=item C<-queries> -- search through only queries. + +=item C<-all> -- search both queries and channels (Default). + +=item C<-active> -- limit search to only window items with activity. + +=item C<-exact> -- enable exact-substring matching + +=item C<-flex> -- enable flex-string matching + +=back + +I or C<-flex> are given, the default is the value of +C> + +=head4 EXAMPLE + +=over 2 + +=item C + +=item C + +=back + +B When entering window switching mode, the contents of your input line will +be saved and cleared, to avoid visual clutter whilst using the switching +interface. It will be restored once you exit the mode using either C, C, +or C. + +=head3 INTERACTIVE COMMANDS + +The following key-bindings are available only once the mode has been +activated: + +=over 4 + +=item C - Exit the mode without changing windows. + +=item C - Exit, as above. + +=item C - Rotate the list of window candidates forward by 1 + +=item C - Rotate the list of window candidates backward by 1 + +=item C - Toggle 'Active windows only' filter + +=item C - Switch between 'Flex' and 'Exact' matching. + +=item C - Select a network or server to filter candidates by + +=item C - Clear the current search string + +=item C - Cycle between showing only queries, channels, or all. + +=item C - Filter candidates by current search string, and then reset + the search string + +=item C - Select the current head of the candidate list (the green one) + +=item C - Select the current head of the list, without exiting the + switching mode. The head is then moved one place to the right, + allowing one to cycle through channels by repeatedly pressing space. + +=item C - B<[currently in development]> displays all possible completions + at the bottom of the current window. + +=item I (C, etc) - Add that character to the current search + string. + +=back + +=head3 USAGE NOTES + +=over 4 + +=item Using C-e (show actives), followed by repeatedly pressing space will cycle + through all your currently active windows. + +=item If you enter a search string fragment, and realise that more than one candidate + is still presented, rather than delete the whole string and modify it, you can + use C-SPC to 'lock' the current matching candidates, but allow you to search + through those matches alone. + +=back + +=head1 AUTHORS + +Based originally on L script Copyright 2007 Wouter Coekaerts +Ccoekie@irssi.orgE>. + +Primary functionality Copyright 2010-2011 Tom Feist +Cshabble+irssi@metavore.orgE>. + +=head1 LICENCE + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + +=head1 BUGS: + +=over 4 + +=item B Sometimes selecting a channel with the same name on a different + network will take you to the wrong channel. + +=back + +=head1 TODO + +=over 4 + +=item B C-g - cancel + +=item B C-spc - narrow + +=item B flex matching (on by default, but optional) + +=item TODO server/network narrowing + +=item B colourised output (via uberprompt) + +=item B C-r / C-s rotate matches + +=item B toggle queries/channels + +=item B remove inputline content, restore it afterwards. + +=item TODO tab - display all possibilities in window (clean up afterwards) +how exactly will this work? + +=item B sort by recent activity/recently used windows (separate commands?) + +=item B need to be able to switch ordering of active ones (numerical, or most +recently active, priority to PMs/hilights, etc?) + +=item B should space auto-move forward to next window for easy stepping + through sequential/active windows? + +=back + + + +=cut + diff --git a/prompt_info/README.pod b/prompt_info/README.pod new file mode 100644 index 0000000..e69de29 diff --git a/tinyurl-tabcomplete/README.pod b/tinyurl-tabcomplete/README.pod new file mode 100644 index 0000000..f29ace0 --- /dev/null +++ b/tinyurl-tabcomplete/README.pod @@ -0,0 +1,56 @@ +=pod + +=head1 NAME + +complete-tiny-url.pl + +=head1 DESCRIPTION + +Shortens web links from your Irssi input field by pressing tab directly after +them. + +=head1 INSTALLATION + +Copy into your F<~/.irssi/scripts/> directory and load with +C. You may wish to have it autoload in one of the +L. + +=head1 USAGE + +Type or paste a URL into your input field, then immediately following the last +character of it, press the CTABE> key. After a few seconds, the +URL will be replaced with an appropriate L address. + +=head1 AUTHORS + +Copyright E 2010-2011 Tom Feist Cshabble+irssi@metavore.orgE> and + +=head1 LICENCE + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. + +=head1 BUGS + +None Known. Please report any at +L + + + +=cut + diff --git a/tinyurl-tabcomplete/complete-tiny-url.pl b/tinyurl-tabcomplete/complete-tiny-url.pl index 3f268e7..b2d448f 100644 --- a/tinyurl-tabcomplete/complete-tiny-url.pl +++ b/tinyurl-tabcomplete/complete-tiny-url.pl @@ -2,35 +2,71 @@ =head1 NAME +complete-tiny-url.pl + =head1 DESCRIPTION +Shortens web links from your Irssi input field by pressing tab directly after +them. + =head1 INSTALLATION +Copy into your F<~/.irssi/scripts/> directory and load with +C. You may wish to have it autoload in one of the +L. + =head1 USAGE +Type or paste a URL into your input field, then immediately following the last +character of it, press the CTABE> key. After a few seconds, the +URL will be replaced with an appropriate L address. + =head1 AUTHORS +Copyright E 2010-2011 Tom Feist Cshabble+irssi@metavore.orgE> and + =head1 LICENCE +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. + =head1 BUGS +None Known. Please report any at +L + =cut use strict; -use vars qw($VERSION %IRSSI); +use warnings; use Irssi; use WWW::Shorten::TinyURL; -$VERSION = '1.0'; -%IRSSI = ( +our $VERSION = '1.0'; +our %IRSSI = ( authors => 'Shabble', contact => 'shabble+irssi /at/ metavore /dot/ org', name => 'Shorten URLs using Tab', description => 'Hitting Tab after typing/pasting a long URL will replace it with' . ' its tinyURL.com equivalent', - license => 'WTFPL', + license => 'MIT', ); sub do_complete { diff --git a/vim-mode/README.pod b/vim-mode/README.pod new file mode 100644 index 0000000..fc52701 --- /dev/null +++ b/vim-mode/README.pod @@ -0,0 +1,444 @@ +=pod + +=head1 NAME + +vim_mode.pl + +=head1 DESCRIPTION + +An Irssi script to emulate some of the vi(m) features for the Irssi inputline. + +=head1 INSTALLATION + +Copy into your F<~/.irssi/scripts/> directory and load with +C. You may wish to have it autoload in one of the +L. + +=head2 DEPENDENCIES + +For proper :ex mode support, vim-mode requires the installation of F +Uberprompt can be downloaded from: + +L + +and follow the instructions at the top of that file for installation. + +If you don't need Ex-mode, you can run vim_mode.pl without the +uberprompt.pl script, but it is strongly recommended that you use it. + +=head3 Irssi requirements + +0.8.12 and above should work fine. However the following features are +disabled in irssi < 0.8.13: + +=over 4 + +=item C C (only with count, they work fine without count in older versions) + +=item C, C + +=back + +It is intended to work with at Irssi 0.8.12 and later versions. However some +features are disabled in older versions (see below for details). + +Perl >= 5.8.1 is recommended for UTF-8 support (which can be disabled if +necessary). Please report bugs in older versions as well, we'll try to fix +them. Later versions of Perl are also faster, which is probably beneficial +to a script of this size and complexity. + +=head2 SETUP + +Run the following command to add a statusbar item that shows which mode +you're in. + +C + +And the following to let C<:b [str]> display a list of channels matching your +search string. + +C + +B Remember to C after adding these statusbar items to make them +permanent. + + +=head3 FILE-BASED CONFIGURATION + +Additionally to the irssi settings described in L, vim_mode +can be configured through an external configuration file named "vim_moderc" +located in F<~/.irssi/vim_moderc>. If available it's loaded on startup and every +supported ex-command is run. Its syntax is similar to "vimrc". To (re)load it +while vim_mode is running use C<:so[urce]>. + +Currently Supported ex-commands: + +=over 4 + +=item C<:map> + +=back + +=head1 USAGE + +The following section is divided into the different modes as supported by Vim itself: + +=head2 COMMAND MODE + +It supports most commonly used command mode features: + +=over 2 + +=item Insert/Command mode. C and C enter command mode. C allows to use C as Escape (any other character can be used as well). + +=item Cursor motion: CSpaceE EBSE f t F T> + +=item History motion: C C moves to the oldest (first) history +line. C without a count moves to the current input line, with a count it goes to the I history line (1 is the oldest). + +=item Cursor word motion: C + +=item Word objects (only the following work yet): C + +=item Yank and paste: C + +=item Change and delete: C + +=item Delete at cursor: C + +=item Replace at cursor: C + +=item Insert mode: C + +=item Switch case: C<~> + +=item Repeat change: C<.> + +=item Repeat C + +=item Registers: C<"a-"z "" "0 "* "+ "_> (black hole) + +=item Line-wise shortcuts: C
+ +=item Shortcuts: C + +=item Scroll the scrollback buffer: C + +=item Switch to last active window: C + +=item Switch split windows: + +=item Undo/Redo: C + +=back + +Counts and combinations work as well, e.g. C or C<3iabcEescE>. Counts also work with mapped ex-commands (see below), e.g. if you map C to do C<:bn>, then C<2gb> will switch to the second next buffer. Repeat also supports counts. + +=head3 REGISTERS + +=over 4 + +=item Appending to register with C<"A-"Z> + +=item C<""> is the default yank/delete register. + +=item C<"0> contains the last yank (if no register was specified). + +=item The special registers C<"* "+> both contain irssi's internal cut-buffer. + +=back + +=head2 INSERT MODE + +The following insert mode mappings are supported: + +=over 4 + +=item Insert register content: Ctrl-R x (where x is the register to insert) + +=back + +=head2 EX-MODE + +Ex-mode (activated by C<:> in command mode) supports the following commands: + +=over 4 + +=item Command History: + +CuparrowE> - cycle backwards through history + +CdownarrowE> - cycle forwards through history + +C<:eh> - show ex history + +=item Switching buffers: + +C<:[N]b [N]> - switch to channel number + +C<:b#> - switch to last channel + +C<:b> Epartial-channel-nameE + +C<:b> / + +C<:buffer {args}> (same as C<:b>) + +C<:[N]bn[ext] [N]> - switch to next window + +C<:[N]bp[rev] [N]> - switch to previous window + +=item Close window: + +C<:[N]bd[elete] [N]> + +=item Display windows: + +C<:ls>, C<:buffers> + +=item Display registers: + +<:reg[isters] {args}>, C<:di[splay] {args}> + +=item Display undolist: + +C<:undol[ist]> (mostly used for debugging) + +=item Source files: + +C<:so[urce]> - only sources vim_moderc at the moment, + F<{file}> not supported + +=item Mappings: + +C<:map> - display custom mappings + +=item Save mappings: + +C<:mkv[imrc][!]> - like in Vim, but [file] not supported + +=item Substitute: + +C<:s///> - I and I are supported as flags, only /// can be used as + separator, uses Perl regex instead of Vim regex + +=item Settings: + +C<:se[t]> - display all options + +C<:se[t] {option}> - display all matching options + +C<:se[t] {option} {value}> - change option to value + +=back + +=head3 MAPPINGS + +=head4 Commands + +=over 4 + +=item C<:map {lhs}> - display mappings starting with {lhs} + +=item C<:map {lhs} {rhs}> - add mapping + +=item C<:unm[ap] {lhs}> - remove custom mapping + +=back + +=head4 Parameters + +I<{lhs}> is the key combination to be mapped, I<{rhs}> the target. The +CE> notation is used + +(e.g. CC-FE> is I), case is ignored. + Supported CE> keys are: + +=over 4 + +=item CC-AE> - CC-ZE>, + +=item CC-^E>, CC-6E> + +=item CSpaceE> + +=item CCRE> - Enter + +=item CBSE> - Backspace + +=item CNopE> - No-op (Do Nothing). + +=back + +Mapping ex-mode and irssi commands is supported. When mapping ex-mode commands +the trailing CCrE> is not necessary. Only default mappings can be used +in I<{rhs}>. + +Examples: + +=over 4 + +=item C<:map w W> - to remap w to work like W + +=item C<:map gb :bnext> - to map gb to call :bnext + +=item C<:map gB :bprev> + +=item C<:map g1 :b 1> - to map g1 to switch to buffer 1 + +=item C<:map gb :b> - to map gb to :b, 1gb switches to buffer 1, 5gb to 5 + +=item C<:map EC-LE /clear> - map Ctrl-L to irssi command /clear + +=item C<:map EC-GE /window goto 1> + +=item C<:map EC-EE > - disable , it does nothing now + +=item C<:unmap EC-EE> - restore default behavior of CC-EE> +after disabling it + +=back + +Note that you must use C for irssi commands (like C), the current value +of Irssi's cmdchars does B work! This is necessary do differentiate between +ex-commands and irssi commands. + +=head2 SETTINGS + +The settings are stored as irssi settings and can be set using C as usual +(prepend C to setting name) or using the C<:set> ex-command. The +following settings are available: + +=over 4 + +=item utf8: support UTF-8 characters, boolean, default on + +=item debug: enable debug output, boolean, default off + +=item cmd_seq: char that when double-pressed simulates CEscE>, string, default '' (disabled) + +=item start_cmd: start every line in command mode, boolean, default off + +=item max_undo_lines: size of the undo buffer. Integer, default 50 items. + +=item ex_history_size: number of items stored in the ex-mode history. Integer, default 100. + +=item prompt_leading_space: determines whether ex mode prepends a space to the displayed input. Boolean, default on + +=back + +In contrast to irssi's settings, C<:set> accepts 0 and 1 as values for boolean +settings, but only vim_mode's settings can be set/displayed. + +Examples: + + :set cmd_seq=j # set cmd_seq to j + :set cmd_seq= # disable cmd_seq + :set debug=on # enable debug + :set debug=off # disable debug + +=head1 SUPPORT + +Any behavior different from Vim (unless explicitly documented) should be +considered a bug and reported. + +B This script is still under heavy development, and there may be bugs. +Please submit reproducible sequences to the bug-tracker at: +L + +or contact rudi_s or shabble on irc.freenode.net (#irssi and #irssi_vim) + +=head1 AUTHORS + +Copyright E 2010-2011 Tom Feist Cshabble+irssi@metavore.orgE> and +Copyright E 2010-2011 Simon Ruderich Csimon@ruderich.orgE> + +=head1 THANKS + +Particular thanks go to + +=over 4 + +=item estragib: a lot of testing and many bug reports and feature requests + +=item iaj: testing + +=item tmr: explaining how various bits of vim work + +=back + +as well as the rest of C<#irssi> and C<#irssi_vim> on Freenode IRC. + +=head1 LICENCE + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. + +=head1 BUGS + +=over 4 + +=item count before register doesn't work: e.g. 3"ap doesn't work, but "a3p does + +=item mapping an incomplete ex-command doesn't open the ex-mode with the partial + command (e.g. C<:map gb :b> causes an error instead of opening the ex-mode and + displaying C<:bEcursorE>) + +=item undo/redo cursor positions are mostly wrong + +=back + +=head1 TODO + +=over 4 + +=item History: + +=over 4 + +=item C< * /,?,n,N> to search through history (like rl_history_search.pl) + +=back + +=item Window switching (C<:b>) + +=over 4 + +=item Tab completion of window(-item) names + +=item non-sequential matches(?) + +=back + +=back + +See also the TODO file at +L for +many many more things. + +=head2 WONTFIX + +Things we're not ever likely to do: + +=over 4 + +=item Macros + +=back + -- cgit v1.2.3