1 *textformat.txt* Vim Text Formatter (version 0.9) 2008-08-01
4 Description This plugin provides commands and key mappings to quickly
5 align and format text. Text can be aligned to either left or
6 right margin or justified to both margins or centered. The
7 text formatting commands in this plugin are a bit different
8 from those integrated to Vim.
10 Author Teemu Likonen <tlikonen@iki.fi>
17 1. Quick start |textformat-start|
18 2. Commands |textformat-commands|
19 3. Default key mappings |textformat-keymap-default|
20 4. User key mappings |textformat-keymap-user|
22 ==============================================================================
23 1. Quick start *textformat-start*
25 The impatient ones are always with us so here is the list of (probably) the
26 most commonly used key mappings for formatting text:
28 <Leader>al Reformat current paragraph and align lines to the
30 <Leader>ar Align lines of current paragraph to the right.
31 <Leader>aj Reformat current paragraph and justify it to both
32 margins. The last line in the paragraph is aligned to
34 <Leader>ac Center lines of current paragraph.
36 By default, <Leader> is the backslash key (\) so by default the mappings are
37 actually \al, \ar, \aj and \ac. If you have changed the g:mapleader variable
38 in your .vimrc file <Leader> may be something else.
40 ==============================================================================
41 2. Commands *textformat-commands*
43 Let's start with the basic components of this plugin. These are the ex
44 commands. You probably don't need these very often but they can be handy if
45 you want to have text formatting and aligning as a part of a macro or function
46 or something. The "daily tools" are explained later.
48 :[range]AlignLeft [indent] *:AlignLeft*
49 Align to left all the lines in [range] (default is
50 current line) and truncate all extra whitespace
51 characters. That is, if there are more than one space
52 between words they are reduced to just one. If
53 'joinspaces' is set then two spaces are inserted after
54 every sentence ending with character ".", "?" or "!".
56 If optional numeric argument [indent] is given then
57 that is used as the left margin. If [indent] is not
58 given the indent of the first line in the [range] is
59 used to define indent for the rest of the lines. There
60 is one exception: if 'formatoptions' contains "2" then
61 the second line in the [range] defines the indent for
62 the rest of the lines.
64 Note: This is very similar to |:left| command except
65 that this also truncates whitespaces and that without
66 [indent] the first line's indent is used.
68 Note: There is a possible unexpected behaviour: If
69 command is run without [range] (i.e., it's just the
70 current line) and [indent] is not given then this
71 command just "aligns" to the current indent position
72 and truncates whitespaces. You might see nothing
73 happening if there weren't any extra whitespaces. Use
74 [indent] (or |:left| command) to align to desired
77 :[range]AlignRight [width] *:AlignRight*
78 Align to right all the lines in [range] (default is
79 current line) and truncate all extra whitespace
80 characters (honor 'joinspaces', as in :AlignLeft).
81 [width] is used as the right margin. If [width] is not
82 given 'textwidth' option is used instead. If
83 'textwidth' is zero then the value of 80 is used.
85 Note: This is very similar to |:right| command except
86 that this also truncates whitespaces.
88 :[range]AlignJustify [width] *:AlignJustify*
89 Left-right justify lines in [range] (default is
90 current line). This means adjusting spaces between
91 words so that the lines fit. Unlike the previous
92 commands this does not use 'joinspaces' option.
93 Instead, extra spaces are always first added after
94 sentences ending with ".", "?" or "!". Then to other
97 The first line in the [range] defines the indent for
98 the rest of the lines, except if 'formatoptions'
99 contains "2" then it's the second line.
101 Numeric argument [width] is used as the right margin.
102 If [width] is not given 'textwidth' is used instead.
103 If 'textwidth' is zero then the value of 80 is used.
105 Also see the Discussion below.
107 :[range]AlignCenter [width] *:AlignCenter*
108 Center lines in [range] (default is current line)
109 horizontally between the first column and [width]. All
110 extra whitespace characters are truncated but honor
111 'joinspaces', just like in :AlignLeft. If [width] is
112 not given 'textwidth' option is used instead. If
113 'textwidth' is zero the value of 80 is used.
115 Note: This is very similar to |:center| except that
116 this also truncates whitespaces.
120 All previous commands operate on single lines only. They do not wrap lines nor
121 do other kind of formatting. If [width] (or 'textwidth') is too narrow for the
122 line then some characters will go beyond the right margin. This is similar to
123 Vim's own |:left|, |:right| and |:center| commands. You might first want to
124 adjust line lengths with other editing commands and then run one of the
125 previous text-formatting commands.
127 Usually when paragraphs are justified the last line of paragraph is aligned to
128 left. However, :AlignJustify command (see above) does not do this. The purpose
129 of this command is to do exactly what was asked for: left-right justify
130 a range of lines. The general-purpose justification tools is <Leader>aj which
131 reformats the paragraph (like |gw|), justifies lines and aligns the last line
134 Why do these commands truncate whitespaces? Well, this is a text-formatting
135 tool and in plain text paragraphs any extra spaces are considered
136 a "typographical flaw." These formatting commands can be used to fix
137 whitespace errors in plain text. Another reason is that left-right justify
138 commands need to add extra spaces to make lines fit. If you later want to
139 reformat such previously justified paragraph and align it to left, for
140 example, it's convenient that the tool automatically handles this and removes
141 extra spaces. If you want to align text without truncating whitespaces use
142 Vim's own align commands: |:left|, |:right| and |:center|.
144 ==============================================================================
145 3. Default key mappings *textformat-keymap-default*
147 By default this plugin provides a couple of key mappings for convenient text
148 formatting. If some of the mappings have already been defined by user (or are
149 taken by some other plugin) then some of the following mappings may not be
150 automatically available. See the next section of this manual for information
151 on how to change the default mappings.
153 There are key mappings available for normal mode and visual mode. As usual,
154 <Leader> is the backslash key by default but it can be changed with
155 g:mapleader variable. Consult the Vim manual for more information on <Leader>.
157 Normal mode (current paragraph) ~
159 <Leader>al Left-align current paragraph, truncate all whitespace
160 characters (but honor 'joinspaces', as in :AlignLeft)
161 and reformat the paragraph so that it fits to
162 'textwidth'. The first line in the paragraph defines
163 the indent for the rest of the lines, except if
164 'formatoptions' contains "2" then it's the second
167 <Leader>ar Right-align current paragraph (use 'textwidth') and
168 truncate all whitespace characters (but honor
169 'joinspaces', as in :AlignLeft). This does not
170 reformat lines because with right-aligned text user
171 usually wants to decide exactly what goes to what
174 <Leader>aj Left-right justify. Truncate all whitespace characters
175 (but honor 'joinspaces', as in :AlignLeft), reformat
176 the paragraph so that it fits to 'textwidth' and
177 finally left-right justify lines. Extra spaces may be
178 added between words so that lines fill the text area.
179 Paragraph's last line is aligned to left. The first
180 line in the paragraph defines the indent for the rest
181 of the lines, except if 'formatoptions' contains "2"
182 then it's the second line.
184 <Leader>ac Center lines of current paragraph horizontally between
185 the first column and 'textwidth'. All whitespace
186 characters are truncated, except if 'joinspaces' is
187 set then an extra space is added after full sentences
188 (see :AlignLeft). This does not reformat the
189 paragraph. With centered text user usually wants to
190 decide exactly what goes to what line. Reformatting
193 Visual mode (range of lines) ~
195 {Visual}<Leader>al Left-align {Visual} lines.
196 {Visual}<Leader>ar Right-align {Visual} lines.
197 {Visual}<Leader>aj Left-right justify {Visual} lines.
198 {Visual}<Leader>ac Center {Visual} lines.
200 Visual mode mappings do not wrap lines nor otherwise reformat text. They work
201 line-by-line, just like their command line equivalents: :AlignLeft,
202 :AlignRight, :AlignJustify and :AlignCenter.
204 ==============================================================================
205 4. User key mappings *textformat-keymap-user*
207 The key mappings can be configured freely by user. This plugin uses the
208 default ones only if they are free and not mapped to some other things. We try
209 to be non-intrusive because this is a general-purpose tool which is likely
210 loaded automatically when Vim starts.
212 Here's an example of lines you could put in your .vimrc file: >
214 nmap <F5> <Plug>Quick_Align_Paragraph_Left
215 nmap <F6> <Plug>Quick_Align_Paragraph_Right
216 nmap <F7> <Plug>Quick_Align_Paragraph_Justify
217 nmap <F8> <Plug>Quick_Align_Paragraph_Center
219 vmap <F5> <Plug>Align_Range_Left
220 vmap <F6> <Plug>Align_Range_Right
221 vmap <F7> <Plug>Align_Range_Justify
222 vmap <F8> <Plug>Align_Range_Center
224 That is, |:nmap| command defines mappings for normal mode and |:vmap| for
225 visual mode. Function keys from <F5> to <F8> are used in this example. The
226 rest of the line is a code word for this plugin; they tell Vim what to do.
227 I think the code words are pretty much self-descriptive.
229 Don't use |:nnoremap| and |:vnoremap| commands here; they don't work because
230 the right-hand side (<Plug>...) must be remappable. See Vim's manual for more
231 information about mapping commands.
235 ==============================================================================
236 vim: ft=help tw=78 ts=8 norl