*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 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. al Left-align and reformat ar Right-align aj Left-right justify and reformat ac Center lines In normal mode the commands operate on current paragraph; in visual mode they operate on the selected lines. By default, 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 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 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, is the backslash key by default but it can be changed with g:mapleader variable. Consult the Vim manual for more information on . Normal mode (current paragraph) ~ al Left-align the current "inner paragraph" (see |ip|) and reformat it according to 'textwidth'. 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. 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. 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}al Left-align and reformat {Visual} lines so that they fill 'textwidth'. {Visual}ar Right-align {Visual} lines. {Visual}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}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 al and 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 (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 Quick_Align_Paragraph_Left nmap Quick_Align_Paragraph_Right nmap Quick_Align_Paragraph_Justify nmap Quick_Align_Paragraph_Center vmap Align_Range_Left vmap Align_Range_Right vmap Align_Range_Justify vmap Align_Range_Center That is, |:nmap| command defines mappings for normal mode and |:vmap| for visual mode. Function keys from to 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 (...) 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