.vim/doc/textformat.txt

   1 *textformat.txt*        Vim Text Formatter  (version 0.9)           2008-08-01
   2
   3
   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.
   9
  10 Author          Teemu Likonen <tlikonen@iki.fi>
  11
  12
  13
  14
  15 Contents
  16
  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|
  21
  22 ==============================================================================
  23 1. Quick start                                              *textformat-start*
  24
  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:
  27
  28         <Leader>al      Reformat current paragraph and align lines to the
  29                         left.
  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
  33                         the left.
  34         <Leader>ac      Center lines of current paragraph.
  35
  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.
  39
  40 ==============================================================================
  41 2. Commands                                              *textformat-commands*
  42
  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.
  47
  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 "!".
  55
  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.
  63
  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.
  67
  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
  75                         column.
  76
  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.
  84
  85                         Note: This is very similar to |:right| command except
  86                         that this also truncates whitespaces.
  87
  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
  95                         available positions.
  96
  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.
 100
 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.
 104
 105                         Also see the Discussion below.
 106
 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.
 114
 115                         Note: This is very similar to |:center| except that
 116                         this also truncates whitespaces.
 117
 118 Discussion ~
 119
 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.
 126
 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
 132 to left.
 133
 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|.
 143
 144 ==============================================================================
 145 3. Default key mappings                            *textformat-keymap-default*
 146
 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.
 152
 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>.
 156
 157 Normal mode (current paragraph) ~
 158
 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
 165                         line.
 166
 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
 172                         line.
 173
 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.
 183
 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
 191                         would destroy it.
 192
 193 Visual mode (range of lines) ~
 194
 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.
 199
 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.
 203
 204 ==============================================================================
 205 4. User key mappings                                  *textformat-keymap-user*
 206
 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.
 211
 212 Here's an example of lines you could put in your .vimrc file: >
 213
 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
 218
 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
 223
 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.
 228
 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.
 232
 233 Happy formatting!
 234
 235 ==============================================================================
 236 vim: ft=help tw=78 ts=8 norl