[Vim-latex-cvs] vimfiles/doc imaps.txt,NONE,1.1

[<sri...@us...>]

Update of /cvsroot/vim-latex/vimfiles/doc
In directory sc8-pr-cvs1:/tmp/cvs-serv8143

Added Files:
	imaps.txt 
Log Message:
Starting the doc file for the imaps.vim plugin. This is just a quick hack
job for now. Its not in the releaseable state yet. But I will keep working
at it in the next few days when I get the time... This doc file should
describe the various imaps options for placeholders and also how to
override the mappings for jumping back and forth...



--- NEW FILE: imaps.txt ---
*imaps.txt*        A Fluid Replacement for the imap command
                        For Vim version 6.0 and above
                  Last Change: Tue Dec 31 02:00 AM 2002 PST

                 By Srinath Avadhanula <sr...@fa...>,
                     Benji Fisher <be...@me...>


===========================================================================
MOTIVATION                             *imap-plugin-motivation* {{{

This plugin provides a function IMAP() which emulates vims |:imap| function.
The motivation for providing this plugin is that |:imap| sufffers from
problems which get increasingly annoying with a large number of mappings.

Consider an example. If you do

imap lhs something

then a mapping is set up. However, there will be the following problems:
1. the 'ttimeout' option will generally limit how easily you can type the
   lhs. if you type the left hand side too slowly, then the mapping will not
   be activated.
2. if you mistype one of the letters of the lhs, then the mapping is
   deactivated as soon as you backspace to correct the mistake.
3. The characters in lhs are shown on top of each other. This is fairly
   distracting. This becomes a real annoyance when a lot of characters
   initiate mappings.

This script provides a function IMAP() which does not suffer from these
problems.

}}}
===========================================================================
USAGE                                    *imap-plugin-usage* {{{

Each call to IMAP is made using the sytax:
>
    call IMAP (lhs, rhs, ft [, phs, phe])

This is equivalent to having <lhs> map to <rhs> for all files of type <ft>.

Some characters in the <rhs> have special meaning which help in cursor
placement as described in |imaps-placeholders|. The optional arguments define
these special characters.

Example One:
>
	call IMAP ("bit`", "\\begin{itemize}\<cr>\\item <++>\<cr>\\end{itemize}<++>", "tex")

This effectively sets up the map for "bit`" whenever you edit a latex file.
When you type in this sequence of letters, the following text is inserted:
>
    \begin{itemize}
    \item *
    \end{itemize}<++>

where * shows the cursor position. The cursor position after inserting the
text is decided by the position of the first "place-holder". Place holders
are special characters which decide cursor placement and movement. In the
example above, the place holder characters are <+ and +>. After you have typed
in the item, press <C-j> and you will be taken to the next set of <++>'s.
Therefore by placing the <++> characters appropriately, you can minimize the
use of movement keys.

NOTE: Set g:Imap_UsePlaceHolders to 0 to disable placeholders altogether.
Set 
	g:Imap_PlaceHolderStart and g:Imap_PlaceHolderEnd
to something else if you want different place holder characters.
Also, b:Imap_PlaceHolderStart and b:Imap_PlaceHolderEnd override the values
of g:Imap_PlaceHolderStart and g:Imap_PlaceHolderEnd respectively. This is
useful for setting buffer specific place hoders.

Example Two:
You can use the <C-r> command to insert dynamic elements such as dates.
  call IMAP ('date`', "\<c-r>=strftime('%b %d %Y')\<cr>", '')

sets up the map for date` to insert the current date.

vim:tw=78:et:ts=4:ft=help:norl:fo+=2:fdm=marker