301 lines
15 KiB
Text
301 lines
15 KiB
Text
*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
|