andre/zsh
1
0
Fork 0
mirror of https://github.com/akelge/zsh synced 2025-07-04 05:29:06 +00:00
Code Issues Releases Wiki Activity

Changes to mapping

Browse Source
This commit is contained in:
Andrea Mistrali
2010-11-10 17:35:53 +00:00
parent fe392d0509
commit 1f1f60bb74
5 changed files with 928 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

301
vim/doc/textformat.txt Normal file
View File

@ -0,0 +1,301 @@
*textformat.txt* Vim Text Formatter (version 2.1) 2008-09-13
Description This plugin provides commands and key mappings to quickly
align and format text. Text can be easily reformatted and
aligned to either left or right margin or justified to both
margins or centered. The text formatting commands provided by
this plugin are a bit more automatic and more intelligent than
those integrated to Vim. Together they make more powerful
command set for formatting text.
Author Teemu Likonen <tlikonen@iki.fi>
Contents
1. Quick start |textformat-start|
2. Commands |textformat-commands|
3. Default key mappings |textformat-keymap|
4. Configuration |textformat-config|
5. Version history |textformat-history|
==============================================================================
1. Quick start *textformat-start*
The impatient are always with us so below is a short info on (probably) the
most important tools provided by this plugin. See the following sections of
this manual for more detailed instructions.
<Leader>al Left-align and reformat
<Leader>ar Right-align
<Leader>aj Left-right justify and reformat
<Leader>ac Center lines
In normal mode the commands operate on current paragraph; in visual mode they
operate on the selected lines. By default, <Leader> is the backslash key, so
the mappings are actually \al, \ar, \aj and \ac, by default. If you have
changed the g:mapleader variable in your .vimrc file <Leader> may be something
else.
==============================================================================
2. Commands *textformat-commands*
Let's start with the basic components of this plugin. These are the ex
commands. You probably don't need these very often but they can be handy if
you want to have text formatting and aligning as a part of a macro or function
or something. The "daily tools" are explained later.
:[range]AlignLeft [indent] *:AlignLeft*
Align to left all the lines in [range] (default is
current line) and truncate all extra whitespace
characters. That is, if there are more than one space
between words they are reduced to just one. If
'joinspaces' is set then two spaces are added after
every sentence ending with character ".", "?" or "!".
If optional numeric argument [indent] is given then
that is used as the left margin. If [indent] is not
given the indent of the first line in the [range] (and
the first line of each paragraph within the [range])
is used to define indent for the rest of the lines in
the paragraph. There is one exception: if
'formatoptions' contains "2" then the second line
defines the indent for the rest of the lines in the
paragraph.
Note: This is very similar to |:left| command except
that this also truncates whitespaces and that without
[indent] each paragraph's indent is detected and used.
Note: There is a possible unexpected behaviour: If
command is run without [range] (i.e., it's just the
current line) and [indent] is not given then this
command just "aligns" to the current indent position
and truncates whitespaces. You might see nothing
happening if there weren't any extra whitespaces. Use
[indent] (or |:left| command) to align to desired
column.
:[range]AlignRight [width] *:AlignRight*
Align to right all the lines in [range] (default is
current line) and truncate all extra whitespace
characters (honor 'joinspaces', as in :AlignLeft).
[width] is used as the right margin. If [width] is not
given the value of 'textwidth' option is used instead.
If 'textwidth' is zero then the value of 80 is used.
Note: This is very similar to |:right| command except
that this also truncates whitespaces.
:[range]AlignJustify [width] *:AlignJustify*
Left-right justify lines in [range] (default is
current line). This means adjusting spaces between
words so that the lines fit. If 'joinspaces' is set
then at least two spaces are printed after every
sentence ending with a ".", "?" or "!". The first line
in [range] (and the first line in each paragraph
within the [range]) defines the indent for the rest of
the lines in the paragraph, except if 'formatoptions'
contains "2" then it's the second line.
Numeric argument [width] is used as the right margin.
If [width] is not given the value of 'textwidth' is
used instead. If 'textwidth' is zero then the value of
80 is used.
Also see the Discussion below.
:[range]AlignCenter [width] *:AlignCenter*
Center lines in [range] (default is current line)
between the first column and [width]. All extra
whitespace characters are truncated (but honor
'joinspaces', just like in :AlignLeft). If [width] is
not given the value of 'textwidth' option is used
instead. If 'textwidth' is zero the value of 80 is
used.
Note: This is very similar to |:center| except that
this also truncates whitespaces.
Discussion ~
All the previous ex commands are rather "stupid" and operate on single lines
only. They do not wrap lines nor do other kind of formatting. If [width] (or
'textwidth') is too narrow for the line then some characters will go beyond
the right margin. This is similar to Vim's own |:left|, |:right| and |:center|
commands. More sophisticated formatting tools are provided as key mappings
(see below).
Usually when paragraphs are justified the last line of each paragraph is
aligned to left. However, :AlignJustify command does not do this. The purpose
of this command is to do exactly what was asked for: left-right justify
a range of lines. More sophisticated justify tools is <Leader>aj which
reformats the paragraph (like |gw|), justifies lines and aligns each
paragraph's last line to left.
All the commands truncate extra whitespaces which makes them work well
together. This is particularly because the left-right justify needs to add
extra spaces to make lines fill the text area. If you later want to reformat
such previously justified paragraph and align it to left, for example, it's
convenient that the tool automatically handles this and removes extra spaces.
If you want to align text without truncating whitespaces use Vim's own align
commands: |:left|, |:right| and |:center|.
==============================================================================
3. Default key mappings *textformat-keymap*
By default this plugin provides a couple of key mappings for convenient text
formatting. If the mappings have already been defined by user (or are taken by
other plugins) then some of the following mappings may not be automatically
available. See the next section of this manual for information on how to
change the default mappings.
There are key mappings available for normal mode and visual mode. As usual,
<Leader> is the backslash key by default but it can be changed with
g:mapleader variable. Consult the Vim manual for more information on <Leader>.
Normal mode (current paragraph) ~
<Leader>al Left-align the current "inner paragraph" (see |ip|)
and reformat it according to 'textwidth'.
<Leader>ar Right-align the current "inner paragraph" (see |ip|)
to margin at 'textwidth'. This does not reformat the
paragraph because with right-aligned text user usually
wants to decide exactly what goes to what line.
<Leader>aj Left-right justify the current "inner paragraph" (see
|ip|). Technically each line's whitespaces are first
truncated, then the text is reformatted according to
'textwidth' and finally lines are justified. The last
line (of each text paragraph) is aligned to left.
<Leader>ac Center lines of current "inner paragraph" (see |ip|)
between the first column and 'textwidth'. This does
not reformat the paragraph because with centered text
user usually wants to decide exactly what goes to what
line.
Visual mode (range of lines) ~
{Visual}<Leader>al Left-align and reformat {Visual} lines so that they
fill 'textwidth'.
{Visual}<Leader>ar Right-align {Visual} lines.
{Visual}<Leader>aj Left-right justify {Visual} lines. First truncate all
extra whitespace characters, then reformat lines so
that they fill 'textwidth' and finally left-right
justify. The last line of each paragraph as well as
the last line in {Visual} range is aligned to left.
{Visual}<Leader>ac Center {Visual} lines.
Both normal mode and visual mode commands truncate extra whitespace
characters. If 'joinspaces' is set then an extra space is added after every
sentence ending with a ".", "?" or "!". The first line in each paragraph
inside the range defines the indent for the rest of the lines in the
paragraph, except if 'formatoptions' contains "2" then it's the second line.
Paragraph definitions ~
The normal mode commands operate on the concept of "inner paragraph" (see
|ip|). The effect is almost the same as selecting current paragraph with Vim's
"vip" command and then executing the equivalent visual mode command. Such
inner paragraph may contain several text paragraphs if 'formatoptions'
contains "w". Each of them is reformatted separately with <Leader>al and
<Leader>aj commands.
New paragraph always begins after a blank line. If 'formatoptions' contains
"w" then new paragraph also begins after a line which ends with
a non-whitespace character. That is, with "w" in 'formatoptions' every line
which ends with a non-whitespace also ends a paragraph. In left-right justify
(<Leader>aj) such line is aligned to left. You need to ensure that there is
a trailing whitespace in every consecutive line which belongs to same
paragraph (the whitespace is preserved after formatting). If 'formatoptions'
does not contain "w" then all consecutive non-blank lines belong to same
paragraph.
==============================================================================
4. Configuration *textformat-config*
The key mappings can be configured freely by user. This plugin uses the
default ones only if they are free and not used for other purposes. Here's an
example of lines you could put to your .vimrc file:
>
nmap <F5> <Plug>Quick_Align_Paragraph_Left
nmap <F6> <Plug>Quick_Align_Paragraph_Right
nmap <F7> <Plug>Quick_Align_Paragraph_Justify
nmap <F8> <Plug>Quick_Align_Paragraph_Center
vmap <F5> <Plug>Align_Range_Left
vmap <F6> <Plug>Align_Range_Right
vmap <F7> <Plug>Align_Range_Justify
vmap <F8> <Plug>Align_Range_Center
That is, |:nmap| command defines mappings for normal mode and |:vmap| for
visual mode. Function keys from <F5> to <F8> are used in this example. The
rest of the line is a code word for Vim and this plugin. They must be written
exactly as shown in the example. I think the code words are pretty much
self-descriptive.
Don't use |:nnoremap| and |:vnoremap| commands here; they don't work because
the right-hand side (<Plug>...) must be remappable. See Vim's manual for more
information about the key map commands.
Most part of this plugin is loaded into memory when the text-formatting
commands or key maps are used for the first time. Only the very minimum is
automatically loaded when Vim is started. If you want to completely avoid
loading this plugin put the following line to your .vimrc file:
>
let g:loaded_textformat = 1
Happy formatting!
==============================================================================
5. Version history *textformat-history*
v2.1 2008-09-13
- Minor internal cleanup.
v2.0 2008-08-10
- \al and \aj now reformat text also in visual mode.
- \al and \aj honor "w" in 'formatoptions' and detect paragraph
boundaries accordingly.
- :AlignLeft, :AlignJustify, \al and \aj recognize several
paragraphs within the range and detect indent for each
paragraph separately.
- Add logic to load the plugin script only once.
v1.1 2008-08-04
- Keep cursor position more accurately when formatting
a paragraph with \al and \aj.
- When 'joinspaces' is set insert two spaces after .?!
punctuation with left-right justify. This is now similar to
other commands.
v1.0 2008-08-03
- All the commands now follow user's 'expandtab' setting and
print leading whitespaces accordingly. Now this works just
like :left, :right and :center commands.
- The left-aligned last line in justified paragraph did not
honor 'joinspaces'. Fixed.
v0.9 2008-08-01
- Initial upload to http://www.vim.org .
==============================================================================
vim: ft=help tw=78 ts=8 et norl fo+=2aw