vim-mode/vim_mode: podified help

1 files changed, 412 insertions, 244 deletions

diff --git a/vim-mode/vim_mode.pl b/vim-mode/vim_mode.pl
index b279790..3e844e5 100644
--- a/vim-mode/vim_mode.pl
+++ b/vim-mode/vim_mode.pl
@@ -1,247 +1,415 @@
-# A script to emulate some of the vi(m) features for the Irssi inputline.
-#
-# It should work fine with at least 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.
-#
-# Any behavior different from Vim (unless explicitly documented) should be
-# considered a bug and reported.
-#
-# NOTE: This script is still under heavy development, and there may be bugs.
-# Please submit reproducible sequences to the bug-tracker at:
-# http://github.com/shabble/irssi-scripts/issues
-#
-# or contact rudi_s or shabble on irc.freenode.net (#irssi and #irssi_vim)
-#
-#
-# Features:
-#
-# It supports most commonly used command mode features:
-#
-# * Insert/Command mode. Escape and Ctrl-C enter command mode.
-#   /set vim_mode_cmd_seq j allows to use jj as Escape (any other character
-#   can be used as well).
-# * Cursor motion: h l 0 ^ $ <Space> <BS> f t F T
-# * History motion: j k gg G
-#   gg moves to the oldest (first) history line.
-#   G without a count moves to the current input line, with a count it goes to
-#   the count-th history line (1 is the oldest).
-# * Cursor word motion: w b ge e W gE B E
-# * Word objects (only the following work yet): aw aW
-# * Yank and paste: y p P
-# * Change and delete: c d
-# * Delete at cursor: x X
-# * Replace at cursor: r
-# * Insert mode: i a I A
-# * Switch case: ~
-# * Repeat change: .
-# * Repeat ftFT: ; ,
-# * Registers: "a-"z "" "0 "* "+ "_ (black hole)
-#   Appending to register with "A-"Z
-#   "" is the default yank/delete register.
-#   "0 contains the last yank (if no register was specified).
-#   The special registers "* "+ contain both irssi's cut-buffer.
-# * Line-wise shortcuts: dd cc yy
-# * Shortcuts: s S C D
-# * Scroll the scrollback buffer: Ctrl-E Ctrl-D Ctrl-Y Ctrl-U Ctrl-F Ctrl-B
-# * Switch to last active window: Ctrl-6/Ctrl-^
-# * Switch split windows: Ctrl-W j Ctrl-W k
-# * Undo/Redo: u Ctrl-R
-#
-# Counts and combinations work as well, e.g. d5fx or 3iabc<esc>. Counts also
-# work with mapped ex-commands (see below), e.g. if you map gb to do :bn, then
-# 2gb will switch to the second next buffer.
-# Repeat also supports counts.
-#
-# The following insert mode mappings are supported:
-#
-# * Insert register content: Ctrl-R x (where x is the register to insert)
-#
-# Ex-mode supports (activated by : in command mode) the following commands:
-#
-# * Command History:   <uparrow>, <downarrow>
-#                      :eh       - show ex history
-# * Switching buffers: :[N]b [N] - switch to channel number
-#                      :b#       - switch to last channel
-#                      :b <partial-channel-name>
-#                      :b <partial-server>/<partial-channel>
-#                      :buffer {args} (same as :b)
-#                      :[N]bn[ext] [N] - switch to next window
-#                      :[N]bp[rev] [N] - switch to previous window
-# * Close window:      :[N]bd[elete] [N]
-# * Display windows:   :ls :buffers
-# * Display registers: :reg[isters] {args} :di[splay] {args}
-# * Display undolist:  :undol[ist] (mostly used for debugging)
-# * Source files       :so[urce] - only sources vim_moderc at the moment,
-#                                  {file} not supported
-# * Mappings:          :map             - display custom mappings
-#                      :map {lhs}       - display mappings starting with {lhs}
-#                      :map {lhs} {rhs} - add mapping
-#                      :unm[ap] {lhs}   - remove custom mapping
-# * Save mappings:     :mkv[imrc][!] - like in Vim, but [file] not supported
-# * Substitute:        :s/// - i and g are supported as flags, only /// can be
-#                              used as separator, uses Perl regex instead of
-#                              Vim regex
-# * Settings:          :se[t]                  - display all options
-#                      :se[t] {option}         - display all matching options
-#                      :se[t] {option} {value} - change option to value
-#
-#
-# Mappings:
-#
-# {lhs} is the key combination to be mapped, {rhs} the target. The <> notation
-# is used (e.g. <C-F> is Ctrl-F), case is ignored. Supported <> keys:
-# <C-A>-<C-Z>, <C-^>, <C-6>, <Space>, <CR>, <BS>, <Nop>. Mapping ex-mode and
-# irssi commands is supported. When mapping ex-mode commands the trailing <Cr>
-# is not necessary. Only default mappings can be used in {rhs}.
-# Examples:
-#     :map w  W      - to remap w to work like W
-#     :map gb :bnext - to map gb to call :bnext
-#     :map gB :bprev
-#     :map g1 :b 1   - to map g1 to switch to buffer 1
-#     :map gb :b     - to map gb to :b, 1gb switches to buffer 1, 5gb to 5
-#     :map <C-L> /clear - map Ctrl-L to irssi command /clear
-#     :map <C-G> /window goto 1
-#     :map <C-E> <Nop> - disable <C-E>, it does nothing now
-#     :unmap <C-E>     - restore default behavior of <C-E> after disabling it
-#
-# Note that you must use / for irssi commands (like /clear), the current value
-# of cmdchars does _not_ work! This is necessary do differentiate between
-# ex-commands and irssi commands.
-#
-#
-# Settings:
-#
-# The settings are stored as irssi settings and can be set using /set as usual
-# (prepend vim_mode_ to setting name) or using the :set ex-command. The
-# following settings are available:
-#
-# * utf8:                 support UTF-8 characters, boolean, default on
-# * debug:                enable debug output, boolean, default off
-# * cmd_seq:              char that when double-pressed simulates <esc>,
-#                         string, default ''
-# * start_cmd:            start every line in command mode, boolean, default off
-# * max_undo_lines:       size of the undo buffer. Integer, default 50 items.
-# * ex_history_size:      number of items stored in the ex-mode history.
-#                         Integer, default 100.
-# * prompt_leading_space: determines whether ex mode prepends a space to the
-#                         displayed input. Boolean, default on
-#
-# In contrast to irssi's settings, :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
-#
-#
-# The following statusbar items are available:
-#
-# * vim_mode: displays current mode
-# * vim_windows: displays windows selected with :b
-#
-#
-# Configuration
-#
-# Additionally to the irssi settings described above vim_mode can be
-# configured through an external configuration file named "vim_moderc" located
-# in ~/.irssi/vim_moderc. If available it's loaded on startup and every
-# supported ex-command is run. It's syntax is similar to "vimrc". To (re)load
-# it while vim_mode is running use :so[urce].
-#
-# Supported ex-commands:
-#
-# * :map
-#
-#
-# Installation:
-#
-# As always, copy the script into .irssi/scripts and load it with
-#     /script load vim_mode.pl
-#
-# Use the following command to get a statusbar item that shows which mode
-# you're in.
-#
-#     /statusbar window add vim_mode
-#
-# And the following to let :b name display a list of matching channels
-#
-#     /statusbar window add vim_windows
-#
-#
-# Dependencies:
-#
-# For proper :ex mode support, vim-mode requires the installation of uberprompt.pl
-# Uberprompt can be downloaded from:
-#
-# http://github.com/shabble/irssi-scripts/raw/master/prompt_info/uberprompt.pl
-#
-# 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 recommended.
-#
-#
-# Irssi requirements:
-#
-# 0.8.12 and above should work fine. However the following features are
-# disabled in irssi < 0.8.13:
-#
-# * j k (only with count, they work fine without count in older versions)
-# * gg G
-#
-#
-# Known bugs:
-#
-# * count before register doesn't work: e.g. 3"ap doesn't work, but "a3p does
-# * mapping an incomplete ex-command doesn't open the ex-mode with the partial
-#   command (e.g. :map gb :b causes an error instead of opening the ex-mode
-#   and displaying :b<cursor>)
-# * undo/redo positions are mostly wrong
-#
-#
-# TODO:
-# * History:
-#   * /,?,n,N to search through history (like history_search.pl)
-# * Window switching (:b)
-#  * Tab completion of window(-item) names
-#  * non-sequential matches(?)
-#
-# WONTFIX - things we're not ever likely to do
-# * Macros
-#
-# THANKS:
-#
-# * estragib: a lot of testing and many bug reports and feature requests
-# * iaj: testing
-# * tmr: explaining how various bits of vim work
-#
-# LICENCE:
-#
-# Copyright (c) 2010 Tom Feist & Simon Ruderich
-#
-# 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.
-#
-#
-# Have fun!
+=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</SCRIPT LOAD vim_mode.pl>. You may wish to have it autoload in one of the
+L<usual ways|https://github.com/shabble/irssi-docs/wiki/Guide#Autorunning_Scripts>.
+
+=head2 DEPENDENCIES
+
+For proper :ex mode support, vim-mode requires the installation of F<uberprompt.pl>
+Uberprompt can be downloaded from:
+
+L<https://github.com/shabble/irssi-scripts/raw/master/prompt_info/uberprompt.pl>
+
+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 recommended.
+
+=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<j> C<k> (only with count, they work fine without count in older versions)
+
+=item C<gg>, C<G>
+
+=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
+
+Use the following command to get a statusbar item that shows which mode
+you're in.
+
+C</statusbar window add vim_mode>
+
+And the following to let C<:b I<name>> display a list of matching channels
+
+C</statusbar window add vim_windows>
+
+B<Note:> Remember to C</save> after adding these statusbar items to make them
+permanent.
+
+
+=head3 FILE-BASED CONFIGURATION
+
+Additionally to the irssi settings described in L<settings|/SETTINGS>, 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
+
+=head2 COMMAND MODE
+
+It supports most commonly used command mode features:
+
+=over 4
+
+=item Insert/Command mode. Escape and Ctrl-C enter command mode.
+  /set vim_mode_cmd_seq j allows to use jj as Escape (any other character
+  can be used as well).
+
+=item Cursor motion: h l 0 ^ $ <Space> <BS> f t F T
+
+=item History motion: j k gg G
+  gg moves to the oldest (first) history line.
+  G without a count moves to the current input line, with a count it goes to
+  the count-th history line (1 is the oldest).
+
+=item Cursor word motion: C<w b ge e W gE B E>
+
+=item Word objects (only the following work yet): C<aw aW>
+
+=item Yank and paste: C<y p P>
+
+=item Change and delete: C<c d>
+
+=item Delete at cursor: C<x X>
+
+=item Replace at cursor: C<r>
+
+=item Insert mode: C<i a I A>
+
+=item Switch case: C<~>
+
+=item Repeat change: C<.>
+
+=item Repeat C<ftFT: ; ,>
+
+=item Registers: C<"a-"z "" "0 "* "+ "_> (black hole)
+
+=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 
+
+=item Line-wise shortcuts: C<dd cc yy>
+
+=item Shortcuts: C<s S C D>
+
+=item Scroll the scrollback buffer: C<Ctrl-E Ctrl-D Ctrl-Y Ctrl-U Ctrl-F Ctrl-B>
+
+=item Switch to last active window: C<Ctrl-6/Ctrl-^>
+
+=item Switch split windows: <Ctrl-W j Ctrl-W k>
+
+=item Undo/Redo: C<u Ctrl-R>
+
+=back
+
+Counts and combinations work as well, e.g. C<d5fx> or C<3iabcE<lt>escE<gt>>.
+Counts also work with mapped ex-commands (see below), e.g. if you map C<gb> to do
+C<:bn>, then C<2gb> will switch to the second next buffer.  Repeat also supports
+counts.
+
+=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: C<E<lt>uparrowE<gt>>, C<E<lt><downarrowE<gt>>
+                       C<:eh>       - show ex history
+
+=item Switching buffers: C<:[N]b [N]> - switch to channel number
+                     C<:b#>       - switch to last channel
+                     C<:b> E<lt>partial-channel-nameE<gt>
+                     C<:b> <partial-server>/<partial-channel>
+                     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: C<: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
+
+=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
+
+=item Save mappings:     C<:mkv[imrc][!]> - like in Vim, but [file] not supported
+
+=item Substitute: C<:s///> - I<i> and I<g> 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
+
+C<{lhs}> is the key combination to be mapped, C<{rhs}> the target. The
+C<E<lt>E<gt>>> notation is used
+
+(e.g. C<E<lt>C-FE<gt>> is Ctrl-F), case is ignored. Supported C<E<lt>E<gt>> keys:
+
+=over 4
+
+=item C<E<lt>C-AE<gt>> - C<E<lt>C-ZE<gt>>,
+
+=item C<E<lt>C-^E<gt>>
+
+=item C<E<lt>C-6E<gt>>
+
+=item C<E<lt>SpaceE<gt>>
+
+=item C<E<LT>CRE<GT>>
+
+=item C<E<LT>BSE<GT>>
+
+=item C<E<lt>NopE<gt>>
+
+=back
+
+Mapping ex-mode and irssi commands is supported. When mapping ex-mode commands
+the trailing C<E<lt>CrE<gt>> is not necessary. Only default mappings can be used
+in {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 <C-L> /clear> - map Ctrl-L to irssi command /clear
+
+=item C<:map <C-G> /window goto 1>
+
+=item C<:map <C-E> <Nop>> - disable <C-E>, it does nothing now
+
+=item C<:unmap <C-E>>     - restore default behavior of <C-E> after disabling it
+
+=back
+
+Note that you must use C</> for irssi commands (like C</clear>), the current value
+of Irssi's cmdchars does B<not> 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</set> as usual
+(prepend C<vim_mode_> 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 <esc>,
+                        string, default ''
+=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<NOTE:> This script is still under heavy development, and there may be bugs.
+Please submit reproducible sequences to the bug-tracker at:
+L<http://github.com/shabble/irssi-scripts/issues>
+
+or contact rudi_s or shabble on irc.freenode.net (#irssi and #irssi_vim)
+
+=head1 AUTHORS
+
+Copyright E<copy> 2010-2011 Tom Feist C<E<lt>shabble+irssi@metavore.orgE<gt>> and
+Copyright E<copy> 2010-2011 Simon Ruderich C<E<lt>simon@ruderich.org<gt>>
+
+=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<:bE<lt>cursorE<gt>>)
+
+=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<github|https://github.com/shabble/irssi-scripts/blob/master/vim-mode/TODO> for
+many many more things.
+
+=head2 WONTFIX
+
+Things we're not ever likely to do:
+
+=over 4
+
+=item Macros
+
+=back
+
+=cut
 
 use strict;
 use warnings;