sponsor Vim development Vim logo Vim Book Ad

Txtfmt (The Vim Highlighter) : "Rich text" highlighting in Vim! (colors, underline, bold, italic, etc...)

 script karma  Rating 1073/600, Downloaded by 6433    Comments, bugs, improvements  Vim wiki

created by
Brett Stahlman
 
script type
utility
 
description
USER FEEDBACK NEEDED: I would greatly appreciate feedback email, especially on the new "auto map" feature (currently in "Alpha" testing):
brettstahlman AT gmail DOT com

=== !!! IMPORTANT NOTE TO NEW USERS !!! ===
The Txtfmt help file is large; for a quick (and gentle) introduction, please see the "USAGE EXAMPLE" sections and the "QUICK-START TUTORIAL" further down the page...

=== SCREENSHOTS ===
Check out the following link for screenshots showing Txtfmt used...
    -as a standalone filetype for journal entries, notes, documents, etc...
    -in conjunction with the .otl filetype used by Ned Konz' TVO (The Vim
     Outliner) plugin
    -to spruce up a circuit diagram created with the aid of Dr. Charles
     Campbell's drawit plugin
    -to spruce up comments in various programming languages

    http://www.txtfmt.webs.com

=== !!! AUTO MAPS - ALPHA RELEASE !!! ===
Since the initial release of Txtfmt, a significant number of users have requested the ability to highlight visually-selected regions. Accordingly, I have added several new types of mappings for highlighting and deleting existing regions of text. These mappings are collectively known as "auto maps" (with the original mappings now known as "manual maps"). Although the feature is not quite complete, I wanted to make an "alpha release" at this point for 2 reasons:
1. The auto-maps feature is already quite usable, and will be preferred over manual maps by many users.
2. I wanted users to have the opportunity to provide feedback on the UI before it's frozen.

Note: Auto maps have not yet been documented in the Txtfmt help file, but their usage is quite simple (simpler than manual maps), so the USAGE EXAMPLE and QUICK-START TUTORIAL sections in this document should be more than sufficient for most users to get started. However, users who prefer to work with the latest stable release, and don't require the convenience of auto maps, may download version 2.4.

=== MOTIVATION ===
Vim's syntax highlighting is very useful for editing files in a particular programming language such as C or Perl. But what if you are simply using Vim to edit text that doesn't fall into any particular language category: e.g., personal journal entries, miscellaneous notes or generic documents? In such cases, Vim's statically defined syntax regions are not very useful. What is really needed is a word processor's ability to apply highlighting to an arbitrary selection of text.

=== OVERVIEW ===
Txtfmt (The Vim Highlighter) is a combination syntax/filetype plugin that allows you to highlight plain text in Vim. The highlighting mechanism uses invisible tokens that are inserted into a Txtfmt buffer with the aid of easy to use mappings provided by the filetype plugin. Each token affects either the color or formatting of subsequent text. The plugin supports up to 8 configurable foreground colors, up to 8 configurable background colors, and all combinations of the following formatting attributes: bold, underline, italic, standout, reverse and undercurl.

Nearly everything in this plugin is configurable, with defaults that should work for most users "right out of the box". The following is a *partial* list of things that can be configured:
    mappings
    colors
    range of character codes used as highlighting tokens

Everything is documented in an extensive Vim help file. Additionally, there is a "Quick-Start Tutorial" at the bottom of this page, designed to help you get up and running quickly with Txtfmt.

=== MANUAL VS AUTO MAPS ===
Prior to version 3, Txtfmt provided only what are now known as "manual maps". Manual maps operate at the level of individual tokens: e.g., insert a new token or replace an existing one at or near the cursor location. Although there is no highlighting task that cannot be accomplished with manual maps, manual mode forced many users to think too much about the details of how to accomplish a particular highlighting task, especially when regions with pre-existing highlighting were involved. Manual maps are still the best choice when you know before entering a piece of text how you want it to be highlighted, but to simplify the use-case of highlighting existing text, Txtfmt version 3.0 introduces several new types of maps, known collectively as "auto maps". Curently, auto maps fall into 2 basic categories:
1. Visual maps: operate on the visually selected text
2. Operator-pending maps: operate on the text moved over (or the text included in a "text object")
Note: I'm also planning to add linewise normal mode maps, which would operate on a range of lines, but the same basic functionality can be achieved today with operator-pending maps.

The following 3 sections give usage examples of visual auto maps, operator-pending auto maps, and manual maps, respectively...

=== USAGE EXAMPLE (VISUAL AUTO MAPS) ===
Suppose you wish to make a block of text blue, bold-italic.
Select the text to be highlighted using either mouse or visual mode (e.g., v, V or CTRL-V). Then type...
\h
At the resulting Txtfmt prompt, enter the following and hit Enter:
f=bi,cb
Note: You could also have typed "fbi,cb" (without the `='), which would have added bold-italic on top of any existing format attributes: i.e., the `=' causes any existing format attributes to be overwritten. More on this later...

=== USAGE EXAMPLE (OPERATOR-PENDING AUTO MAPS) ===
Suppose you wish to make the word under the cursor red, bold-underline.
In normal mode, with cursor positioned on the word to be highlighted, type...
\h
Vim is now waiting for a motion (or text object). Enter the 'inner word' text object specification:
iw
At the resulting Txtfmt prompt, type the following and hit Enter:
f=bu,cr

Now, let's italicize and underline the current and subsequent 2 lines. In normal mode, with cursor still on the word we just highlighted, type...
\h
Once again, Vim awaits a motion. Enter the normal mode command to move down 2 lines:
2j
At the resulting Txtfmt prompt, type the following and hit Enter:
fui
Note: Because we used "f" instead of "f=", the word you highlighted in the first step has retained the bold attribute.

=== USAGE EXAMPLE (MANUAL MAPS) ===
Suppose you wish to enter some green text...
You execute one of Txtfmt's "insert-token" mappings (e.g., \i in normal mode), and enter the following at the prompt:
    cg
(mnemonic: color green)
Now, the text you type is green.

While typing green text, you wish to emphasize a phrase by making it bold-italic. You execute another mapping (e.g., CTRL-\ CTRL-\ in insert mode) and enter "fbi" or "fib" at the prompt.
(mnemonic: format bold italic)
Now, the text you type is green bold-italic.
Note: Inserting the bold-italic token did not affect the text color, because the color and format regions are completely "orthogonal".

Now you wish to switch to a blue background. Execute another mapping (e.g., CTRL-\ CTRL-\ in insert mode) and enter "kb" at the prompt.
(mnemonic: bac_k_ground blue)
Now, the text you type is green bold-italic on a blue background. Notice that, as before, the preceding highight regions are unaffected by the start of the new one.

At some point, you may wish to return to default (unhighlighted) text. You can terminate the 3 active regions by executing the insert-token mapping one last time and entering the following at the prompt:
    c-,f-,k-
(mnemonic: remove color, remove format, remove bac_k_ground color)
Now, the text you type should be plain, unhighlighted text. Notice how multiple format/color specifiers can be concatenated in a comma (or dot) separated list, thereby reducing the number of times you have to execute the mapping. You can use this feature to insert both the start and end tokens of a region at once: e.g.,
fbi.f-
This specifier would enter a bold-italic token, followed immediately by the "no format" token, leaving the cursor between the two. (Note that Txtfmt lets you replace one of the commas with a dot to indicate where the cursor should be positioned after the token insertion.)

=== FEEDBACK ===
I would greatly appreciate your feedback on this plugin. Contact me either at...

brettstahlman AT comcast DOT net

...or by posting to the Vim list with Txtfmt somewhere in the subject or body.
Also, please rate this plugin!

=== SUGGESTED USES ===
The following applications represent a few of the many possible uses of the Txtfmt plugin:
    -For taking notes
     (e.g., notes taken while reviewing large programming projects)
    -As part of a personal journaling system
    -For highlighting .otl files created with Ned Konz' TVO (The Vim Outliner)
     plugin
    -For highlighting files created with 'Notes' (Hari Krishna Dara's
     lightweight note management plugin)
    -For highlighting text files created with Yongping Guo's TxtBrowser plugin
    -For beautifying block diagrams created with Dr. Charles Campbell's drawit
     plugin
    -For sprucing up programming language comments
     Don't laugh! You can embed Txtfmt formatting regions within other syntax
     regions (e.g., C comments)
     :help txtfmt-'nested'
    -etc. etc...
Note: If you wish to make your formatted documents available to non-Vim users, simply use the :TOhtml command distributed with Vim to output an HTML version of the Txtfmt buffer.


====================
QUICK-START TUTORIAL
====================
After you have installed the plugin, you may wish to generate a "test page", both to ensure that you have installed the plugin properly, and as a quick and easy way to create a Txtfmt buffer containing actual formatting regions that you can view and play around with. You may create a "test page" with default options by executing the MakeTestPage command at the command line:

    :MakeTestPage<Enter>

Be sure to scroll down and/or enlarge the window to view all sections. Although the primary purpose of the test page is to allow you to visualize the effects of a particular set of option values, the text of the page has been carefully chosen to give the new user an overview of some of the more important Txtfmt options. For information on how to use MakeTestPage to visualize different sets of options,

    :help txtfmt-:MakeTestPage

After you have viewed formatting regions in a test page, you will probably want to try creating your own formatting regions. The simplest way to begin is as follows:

    :new<Enter>
    :set ft=txtfmt<Enter>

Assuming you have installed the plugin properly, you now have access to all the Txtfmt mappings for working with the special Txtfmt tokens discussed earlier. There are a large number of mappings provided for inserting and jumping to Txtfmt tokens. Note that while intuitive key-sequences are used by default, Txtfmt provides a way for you to customize the {lhs} of any or all mappings.

For a detailed description of mapping customization,
    :help txtfmt-map-config

For a detailed description of the token insertion mappings,
    :help txtfmt-ins-tok-maps

For a detailed description of the jump-to-token mappings,
    :help txtfmt-jump-to-tok

To keep this "quick-start tutorial" quick, I'll demonstrate the use of only a few of the available mappings...

In your newly-created Txtfmt buffer, execute the following normal mode command:
    \i

Note: The remainder of the tutorial assumes that your <LocalLeader> is at the default value (i.e., backslash). If you have set <LocalLeader> to something other than the default, replace the backslash in the examples with the appropriate character.
    :help <LocalLeader>

At this point, you will be presented with the following prompt:
    Enter a fmt / clr string. (Enter to cancel):

At the prompt, type the following string and hit <Enter>:
    fbui

Now, begin typing some text. The text should be highlighted with the bold, underline, and italic attributes. Note that the results would have been the same if you had typed fbiu, fibu, fubi, etc... As you have probably surmised, the letters 'b', 'u', and 'i' are flags indicating bold, underline, and italic, respectively. The leading 'f' indicates that the subsequent flags comprise a "format specification".
    :help txtfmt-fmt-spec

To terminate the underline, bold, italic region, execute the following keystroke sequence while still in insert mode:
    <CTRL-\><CTRL-\>

Hint: Hold the Control key down while hitting backslash twice in quick succession.

Once again, you should be presented with the prompt asking for a fmt / clr string. This time, enter the following:
    f-

The dash character indicates "no format"; i.e., a return to the normal (unhighlighted) text. If you continue typing text, you will see that it no longer has any format attributes.

Now let's see what happens when we bring color into the mix... If you're still in insert mode, hit <Esc> to return to normal mode. Now execute the following normal mode command to insert a token on the line below:
    \o

At the resulting prompt, enter the following:
    cblue

The 'c' is analogous to the 'f' in the preceding "format specifications"; it
indicates that the following text is a "color specification".
    :help txtfmt-clr-spec

Since in this case the color specified is "blue", the text you type after hitting <Enter> will be blue. Although I specified the color as "blue", I could just as well have abbreviated it to "b". As discussed in the Txtfmt help, color names are actually defined as regular expression patterns. The default patterns permit you to abbreviate color names to uniqueness. In practice, this means that for all colors but black, you needn't specify more than the first letter of the color name. (The single letter abbreviation for black is 'k', which permits it to be disambiguated with blue.) Txtfmt provides you with 8 distinct colors, each with its own default color name pattern and RGB value. You can view these definitions with the :ShowTokenMap command. Go ahead and try it now... After hitting <Esc> to return to normal mode, execute the following at the command line:
    :ShowTokenMap<Enter>
    
You may have to page down to see all of the output. The first section shows foreground color definitions, and the last section shows similar definitions for background colors. If you are not happy with either the color name or the RGB value of any of the 8 default colors, Txtfmt provides a very flexible mechanism for overriding the defaults with your own color preferences. The details may be found in the help, but if you're short on time, here's a quick example that shows how easy it is...
Note: You don't need to try this now.

Suppose the GUI's default red color (RGB: #FF0000) is too bright for your eyes. You wish to replace this color with a dark brown (RGB: #804000). You see from the output of :ShowTokenMap that red corresponds to index 5 in the default color array. Thus, you could make the desired change by overriding txtfmtColor{5} with the following line in your .vimrc:
    :let txtfmtColor5='^br\\%[own]$,c:DarkRed,g:#804000'

With this definition, you could specify the new color with the abbreviation "br". Of course, you would no longer be able to use the color red in the GUI, and any red highlighting in your existing file(s) would change to dark brown when viewed in the GUI. (Since the "c:DarkRed" is unchanged, color #5 will still be red in a color terminal.)
    :help txtfmt-color-config
    :help txtfmt-:ShowTokenMap

Now suppose you wish to continue typing blue text, but would like the text you are about to type to have the bold and italic attributes as well. Assuming you are in normal mode, hit \a to bring up the familiar prompt. (Note that \a differs from \i in that the former will insert the Txtfmt token(s) *after* the cursor location instead of before it.) Now enter the following at the prompt:
    fbi

The text you type after hitting <Enter> will be blue, bold-italic. Notice that it wasn't necessary to do anything special to ensure that the bold-italic text would also be blue. It is blue because the effects of the "blue" foreground color token you entered earlier are not affected in any way by the introduction of a format token. This behavior is a direct consequence of the orthogonality of Txtfmt's various token types. A format token supercedes the preceding format token, but has no effect upon any preceding color regions. Similarly, a foreground color token supercedes the preceding foreground color token, but has no effect upon any preceding format or background color regions.

Important Note: The fact that format/color tokens "supercede" preceding tokens of the same type means that the "no format"/"no color" tokens are required only when you wish to turn off format or colors completely for subsequent text. To change from one format to another format, or from one color to another color, simply insert the token for the new region.

To verify that we can supercede the blue foreground color token entered earlier, let's enter a red foreground color token by hitting <CTRL-\><CTRL-\> once more (still in insert mode) and entering the following at the prompt:
    cr

Observe that the text you type after hitting <Enter> still possesses the bold-italic attribute, though its color is red.
Note: You may have noticed that I used the convenient single letter abbreviation for "red". I will use such abbreviations exclusively for the remainder of the tutorial.

Up until now, you have been applying colors only to text; i.e., you have been working exclusively with foreground colors. Txtfmt 2.0 introduced support for background colors as well. For performance reasons, the default configuration enables only 4 background colors: red, green, blue and yellow. It is quite easy, however, to tailor the set of colors enabled via independent foreground and background color mask options.
    :help txtfmt-'fgcolormask'
    :help txtfmt-'bgcolormask'

You insert a background color token just as you would a foreground color token, except that the character introducing the color spec is 'k' instead of 'c' (since 'c' was already taken, and the word "background" contains a 'k'). You can try it out by hitting <CTRL-\><CTRL-\> (still in insert mode) and entering the following at the prompt:
    kb

Hit <Enter> and type some text. As you might expect, the text you type now is red bold-italic on a blue background.

To revert to default format and color, hit <CTRL-\><CTRL-\> and enter the following at the prompt:
    f-,c-,k-

You may recognize the "f-" as the special "no format" token we inserted earlier to end the first format region we created. Similarly, the "c-" and "k-" are the special "no fg color" and "no bg color" tokens, respectively . Note that it was not necessary to enter these three tokens with separate mappings and separate prompts. We simply concatenated the token specs together, separating them with a comma. This is an example of a format/color specification list.
    :help txtfmt-fmt-clr-spec-list

Note that such lists may contain any number of format/color specifications. Ordinarily, the cursor will be left at the end of the sequence of tokens inserted via such a list. You can, however, specify a different cursor position by replacing one of the commas in the list with a single dot ('.'). This is actually a very useful feature. Recall that in our previous example, we inserted the "no format" and "no color" tokens used to terminate our format/color regions only after we had finished typing all the text within them. In the common case, however, you know when you begin a region that you will eventually want to end it. Thus, you can save yourself a mapping invocation by entering both the start and end tokens at the same prompt.

To see how it works, hit <Esc> to return to normal mode, then hit \o and enter the following at the prompt:
    cr,fi.c-,f-

This format/color specification list comprises both the start and end tokens for a red, italic region. The advantage of using a dot to separate the "italic" format spec from the "no color" spec is that it allows you to begin typing red, italic text immediately after hitting <Enter>. (Go ahead and type a bit of text...) If a comma had been used instead, the cursor would have ended up after the "no format" token, which means you would have had to move the cursor back 2 character positions to get it inside the region before beginning to type the formatted text.

Now suppose after typing some red, italic text, you decide that green, underline would have been a better choice. The change is accomplished fairly easily, and will give us an opportunity to introduce the "jump-to-token" mappings...

After hitting <Esc> to return to normal mode, Execute the following "jump-to-token" command:
    [c

This command positions the cursor on the previous color token (i.e., the red color token beginning the region). Note that there are many variations of the jump-to-token commands: the one to use depends upon desired search direction, the type of token sought, whether you wish to land "on" or "next to" the sought token, etc...
    :help txtfmt-jump-to-tok

IMPORTANT NOTE: As of Vim 7.3, the default configuration causes tokens to disappear completely as soon as they are inserted. The "jump-to-token" maps provide the best way to locate hidden tokens (for example, when you wish to remove one). If you prefer that tokens remain visible as long as the cursor is in their line, you can add the `i' and `n' flags to the txtfmt-'concealcursor' option.
    :help txtfmt-'concealcursor'

Now type the following (still in normal mode):
    2\s

This is the "substitute" variant of the insert-token command. The numeric argument indicates that we wish to replace 2 characters at the cursor (i.e., the red color and italic format tokens) with the tokens we are about to specify at the prompt:
    fu,cg

Upon hitting <Enter>, you should observe that the red, italic text has changed to green, underline.

You may have noticed a similarity between several of the normal mode insert-token mappings used above and the native Vim normal mode commands for entering insert mode. This similarity was not by chance, but by design. In addition to the \i, \a, \o, and \s commands that were demonstrated above, Txtfmt also provides the following:
    \I, \O, \A

Although all these commands are described in the help, a regular Vim user can easily intuit where they will insert the Txtfmt tokens relative to the cursor, by analogy with the corresponding enter insert mode commands.

Also note that if you insert a 'v' between the backslash and the subsequent character (e.g., \vI), Txtfmt will exit insert mode after inserting the Txtfmt tokens. This is useful when you are simply highlighting existing text.

-- AUTO MAPS (version 3.0 alpha) --

Now that you know how to manipulate Txtfmt highlighting tokens directly, it's time to try working with "auto maps", which permit a more declarative workflow.

Select a block of text (either using mouse or visual mode) and type the following:
\h
At the prompt, enter the following and hit <Enter>:
fbi
Notice that the selected text is now highlighted bold-italic.

Now suppose you wish to change the highlighting of just one word within the block just highlighted. In particular, you want to do the following:
-Remove italic
-Add underline
-Change color to blue
Of course, you could accomplish this with manual mappings by inserting a bold-italic format token and a blue fg color token at the start of the word, and a bold-italic format token and default fg color token at the end of the word. But this is a bit tedious. Note, for instance, that you would have to think about the current highlighting *after* the region to know what sort of tokens should be inserted at the end of the word. Also, there is no way with manual maps to say "remove italic" and "add underline". You have to think about the existing highlighting to know what sort of token to insert. This is exactly the sort of use-case for which Txtfmt's auto maps were designed...

To accomplish the desired highlighting with an operator-pending map, simply position yourself at the start of the word to be changed and type the following:
\h
Vim is now waiting for you to execute a motion to define the region you wish to operate on. Hit e to jump to the end of the current word and bring up the Txtfmt prompt. At the prompt, enter the following:
fu-i,cb
Notice that the word at cursor is now blue bold-underline, and the containing region is unchanged.

The fmt/clr spec you just entered used "additive mode" to add underline and subtract italic. Note that there's a subtle difference between the use of `-' in manual and auto maps: in manual maps, `-' is used to turn off formats altogether (i.e., to return to the "default" format or color); with auto maps, it is used to "subtract", or remove, specific attributes. Although an explicit `+' can be used to "add" fmt attributes, it is generally unnecessary, since attributes are added by default. The following examples should give the idea:
fbi       (add bold and italic)
f+bi      (same as above: leading `+' is optional)
fbi-us    (add bold and italic / remove underline and standout)
f+bi-us   (same as above)
fb-u+i-s  (same as above)
f-bi      (remove bold and italic)

*** Note to Alpha testers ***
I have considered (and have not completely ruled out) the following, stricter format...
f<ADD>-<SUB>
...which would not permit add/sub components to be interspersed in any order as they were in the examples. With this more limited format, an explicit `+' would never be needed (and would probably not even be allowed). Feedback is welcome on this UI choice, as the design is not yet frozen.

Tip: Additive mode is particularly useful when you want to add certain attributes to an entire region, without affecting any existing attributes. Imagine you had a paragraph with lots of words highlighted differently, and you wished to italicize the entire paragraph (without otherwise changing the individual word highlighting). With manual maps, you would have to visit each of the highlighted words and replace the token before it with a new token containing the original attribute(s) *and* italic. In most cases, you'd also need to replace a token *after* the word as well. This would be rather tedious. But with additive mode, you can simply select the entire paragraph (or move over it with an operator-pending map) and specify...
fi
...and Txtfmt will do everything necessary to italicize the paragraph without affecting existing highlighting.

But what if you know exactly how you want an entire region formatted? I.e., instead of adding to any existing sub-regions, you want to wipe out the existing highlighting and replace it with something new. In that case, you should use "prescriptive" or "equals" mode, which is specified by prepending an equals sign to the format spec: E.g.,
f=i       (set region to italic)
    f=ubi     (set region to underline-bold-italic)
f=        (set to "no formats" - i.e., remove all fmt attributes)
Caveat: You cannot mix additive and equals mode within a single format spec: i.e., the following is an error (and wouldn't really make much sense):
f=i-b     (ERROR)
Note: Additive and equals modes are for formats only. Since colors support *only* equals mode, no special characters are required for disambiguation: thus, `=' and `+' are not permitted in fg/bg color specs.

** Note to Alpha testers **
My original thought was to use `f-' (rather than, or in addition to, `f='), to remove all format attributes, as this seemed the most natural extension of `f-' from manual to auto maps. From a purely logical standpoint, however, `f=' makes more sense than `f-'. Consider that `f-' is simply a degenerate additive mode spec that removes nothing (i.e., leaves formatting as-is); `f=', on the other hand, is a degenerate prescriptive mode spec that sets formatting to nothing (i.e., clears formatting). Finally, `f' by itself would be a degenerate additive mode spec that adds nothing (i.e., leaves formatting as-is). For these reasons, I have opted for the following interpretations:
f-    no change
f     no change
f=    clear all format attributes
As already mentioned, the `-' is not special in color specs: thus, you can use either a `-' or an empty color name to remove fg/bg colors: E.g.,
c-    remove fg color
c     same
k-    remove bg color
k     same
Note: Previous versions of Txtfmt required explicit `-' to remove colors.
Also Note: It has occurred to me that users accustomed only to manual maps might expect `f-' to clear all format attributes. I welcome feedback on this point, as I haven't completely ruled out making `f-' a special case that violates consistency in order to avoid surprising some users...

*** Smart Text Deletion Maps ***
Although Txtfmt tokens are invisible, they are characters in your buffer like any other: deleting text can delete tokens, which in turn, can affect the highlighting of text beyond the deletion. To see how this could be problematic, consider the following line of bold text (Txtfmt tokens shown as <fb> and <f->):

<fb>This is some bold text.<f->

You hit 0 in normal mode to go to the start of the line, then hit d2w in normal mode to delete the first two words. But note that this also deletes the <fb> token, with the result that the remaining portion of the line is no longer bold! In other words, the deletion had a visible effect on the text beyond the deletion. This is probably not what you wanted. To solve this problem, Txtfmt also provides a smart delete command, which is aware of Txtfmt highlighting. Like the auto maps highlighting commands, it can be used in both visual and operator-pending modes. Its default mapping is \d. To use it with the previous example, you could simply have hit \d2w instead of d2w. Alternatively, you could have highlighted the first two words, then hit \d. The difference between Vim's and Txtfmt's delete commands is that, whereas Vim makes no distinction between text and Txtfmt tokens, Txtfmt's delete assumes your objective is to delete text only, and will do whatever is necessary (possibly inserting new tokens), to preserve the highlighting of text beyond the deletion.

This concludes the tutorial. No attempt was made to discuss all of the many Txtfmt options. Detailed information on all options may be found in the Txtfmt help file.
    :help txtfmt

 
install details
=== DISTRIBUTED FILES ===

The Txtfmt distribution comprises the following 4 files:

doc/txtfmt.txt
    Txtfmt help file
ftplugin/txtfmt.vim
    Txtfmt filetype plugin (contains mappings for working with Txtfmt tokens)
syntax/txtfmt.vim
    Txtfmt syntax file (defines the Txtfmt syntax highlighting)
plugin/txtfmt.vim
    Txtfmt common configuration code (contains configuration script needed by
    both the filetype and syntax plugins)
indent_patch.txt
    (Not needed by most users)
    Bram Moolenaar's patch to fix indent.vim's handling of dot-separated lists
    in 'filetype' option values (required only if your version of Vim is older
    than 7.2 and you plan to "nest" Txtfmt within other filetypes) For details,
        :help txtfmt-combining.

All of the txtfmt files should be placed in their respective parent directories, somewhere in your 'runtimepath'. If you need the patch file, you may place it wherever you like (but if you're using a recent version of Vim, you won't need it).

The instructions for extracting the Txtfmt files vary, depending upon the package file format you have chosen to download. Follow the instructions that apply...

--- Vimball (.vba) ---

Extracting a Vimball is easy. Simply edit the file with Vim and execute the following at the Vim command line:
    :so %
    :q

That's it! If you haven't overridden any of the Vimball defaults, this will extract the plugin files under the first directory in your 'runtimepath'. Additionally, it will run :helptags to make the Txtfmt help topics searchable with Vim's help command. Note that it is necessary to restart Vim after installing the files before using the plugin.

Note: If you wish to extract the files somewhere other than the first directory in your 'runtimepath', you can override the default location by setting the g:vimball_home option.
    :help g:vimball_home

--- Gzipped tarfile (.tar.gz) ---

Choose the location where you wish to install the plugin. If you are unsure what location to choose, consider using the first directory in your 'runtimepath' option. You can see what this is by executing `:set rtp'.

Typical values are...
    ~/.vim (Unix)
    $HOME/vimfiles or $VIM/vimfiles (Windows)

Go to the selected installation directory and extract the gzipped tarfile with a command similar to the following (replacing <path_to_tar_gz> with the actual path to the downloaded file).
    tar -xzvf <path_to_tar_gz>

To make Txtfmt help topics visible to Vim's :help command, you must now run :helptags, passing as argument the path to the doc folder where you unpacked txtfmt.txt: e.g.,
    :helptags ~/.vim/doc

=== DETECTING OR SETTING TXTFMT FILETYPE ===

!!! IMPORTANT CAVEAT !!!
Txtfmt requires both filetype detection and syntax highlighting to be enabled. Though nearly everyone nowadays wants both, they are not enabled by default: unless you copied the commands from the example vimrc (or source the example file from your own .vimrc), you will probably need to add something like the following to your .vimrc...

    :syntax on
    :filetype plugin on

help :syntax-on
help :filetype-plugin-on

Once you have copied the Txtfmt files to the appropriate directories in 'runtimepath', you can always use the Txtfmt syntax and mappings by manually setting the 'filetype' option. (I am assuming, of course, that you have enabled syntax at some point, most likely in your .vimrc. If you are not sure about this, :help syntax-enable.) The 'filetype' option may be set on the command line: e.g.,
    :set ft=txtfmt

A better approach for a file designed to be viewed with Txtfmt highlighting would be to set the filetype in a Vim modeline: e.g.
    vim:ft=txtfmt

While the manual approach may be appropriate for some uses, if you find yourself always using Txtfmt with certain types of files, it probably makes sense to set up automatic detection via one of the methods discussed in the section "new-filetype" in the Vim help. The simplest approach is to create your own filetype.vim (assuming you haven't done so already) in a directory that comes before $VIMRUNTIME in 'runtimepath'. Within this script, you should define an autocommand that will :setfiletype to Txtfmt for any file with an appropriate extension.

Example:
    " Set up detection for Txtfmt files
    au! filetypedetect BufRead,BufNewFile *.txt    setfiletype txtfmt

IMPORTANT NOTE: More information on this topic, such as how to use Txtfmt in combination with other filetypes (e.g. to format C comments), may be found in the Txtfmt help file.
 

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
txtfmt_v3.0alpha.tar.gz 3.0 alpha 2016-01-30 7.0 Brett Stahlman Alpha release of "auto maps" feature: includes both visual and operator-pending maps for highlighting existing regions. UI not yet frozen. User feedback desired.
txtfmt_v24.vba 2.4 2010-09-28 7.0 Brett Stahlman Version 2.4 repackaged in Vimball format
*** TOKENS NOW COMPLETELY CONCEALED (with Vim 7.3) ***
See original version 2.4 release notes for additional details
txtfmt_v2.4.tar.gz 2.4 2010-09-18 6.0 Brett Stahlman *** TOKENS NOW COMPLETELY CONCEALED (with Vim 7.3) ***
-Makes using the "conceal" feature the default for Vim versions >= 7.3.
Important Note: If you have legacy files for which you do not wish to use "conceal", read the following:
:help txtfmt-conceal-history
:help txtfmt-viewing-old-files-without-conceal
-Provides more accurate definition of "turquoise" color in default color map: LightGreen changed to DarkCyan.
-Fixed handling of bad modeline options.
txtfmt_v2.3.tar.gz 2.3 2010-06-08 6.0 Brett Stahlman Prevents E21 in several scenarios: e.g.,
-Txtfmt used within a Vim help buffer (e.g., ft=help.txtfmt)
-Txtfmt loaded when 'nomodifiable' is set globally.
txtfmt_v2.2.tar.gz 2.2 2010-02-16 6.0 Brett Stahlman -Loading Txtfmt no longer makes all windows the same size when 'equalalways' is set
-Fixed several anomalies caused by Txtfmt load when 'winfixheight' is set:
-"test page" displayed in 2 windows
-chain of errors when initial window contains changes
-Txtfmt buffer loaded in 2 windows
-Added logic that attempts to make "test page" at least 20 lines high
txtfmt_v2.1.tar.gz 2.1 2009-11-26 6.0 Brett Stahlman Minor fix in Define_syntax to ensure that 'containedin' clause does not refer to nonexistent "inner escape" region when there are no active foreground colors.
txtfmt_v2.0.tar.gz 2.0 2009-09-29 6.0 Brett Stahlman !!!!! Formal Release of Version 2.0 (bg color and 'conceal' patch support) !!!!!
Incorporated perl script used to generate large portion of Define_syntax into syntax/txtfmt.vim, and provided Vim command line used to update the auto-generated script block.
txtfmt_v2.0b.tar.gz 2.0b 2009-09-16 6.0 Brett Stahlman !!!!! Version 2.0 beta release (background colors and 'conceal' patch) !!!!!
Code cleanup (removed unused functions, streamlined color name lookup)
txtfmt_v2.0a.tar.gz 2.0a 2009-08-25 6.0 Brett Stahlman !!!!! MAJOR RELEASE !!!!!
-Added support for background colors!!!
-Added support for Vince Negri's 'conceal' patch, which can make Txtfmt tokens consume zero screen width
txtfmt_v1.5.tar.gz 1.5 2009-03-05 6.0 Brett Stahlman -Removed (obsolete) multibyte syntax patch from distribution
-Updated help to reflect fact that several issues affecting Txtfmt have been eliminated in Vim 7.2
txtfmt_v1.4.tar.gz 1.4 2009-02-23 6.0 Brett Stahlman -Fixed several of the operator-pending "jump to token" maps
-Added more robust mechanism for hiding tokens, eliminating dependence upon "Ignore" group whenever possible
-Added help section "Color terminal pitfalls" containing...
    -Description of "Ignore" group issue and recommended workarounds
    -Description of gnome-terminal issue and recommended workarounds
-Fixed broken link in helpfile
-Minor cosmetic fix on test page
txtfmt_v1.3.tar.gz 1.3 2008-12-16 6.0 Brett Stahlman Fixed "bold" attribute display in color terminals. Prior to this fix, the default Txtfmt colors were unaffected by the bold attribute. With this fix, the bold attribute will cause dark colors to appear brighter (lighter) in a color terminal.
txtfmt_v1.2.tar.gz 1.2 2008-08-17 6.0 Brett Stahlman Added missing help tags for a number of options.
txtfmt_v1.1.tar.gz 1.1 2008-06-04 6.0 Brett Stahlman NOW WORKS WITH MULTIBYTE ENCODINGS!!! (no patch required)
-Added logic to determine whether the running Vim treats syntax match offsets as byte or character offsets. (This logic renders the multi-byte syntax patch obsolete.)
-Help file additions: added instructions for using Txtfmt with TVO (:help txtfmt-nesting-tvo-example), and outlined a strategy for achieving "colorscheme independence" by defining colors according to default highlighting groups (:help txtfmt-colorschemes)
txtfmt_v1.0e.tar.gz 1.0e 2008-05-11 6.0 Brett Stahlman -Fixed bug that prevented buf-local color definitions from being used.
-Added to the help file a description of a possible strategy for making txtfmt
color definitions dependent upon current colorscheme.
-Fixed bug that sometimes prevented txtfmt option changes from taking effect
when a txtfmt buffer was re-edited.
-Fixed bug that prevented insert-token mappings from working in Replace mode.
txtfmt_v1.0d.tar.gz 1.0d 2008-04-28 6.0 Brett Stahlman Applied the <silent> attribute to prevent the jump-to-token
mappings from echoing to the command line
txtfmt_v1.0c.tar.gz 1.0c 2008-04-19 6.0 Brett Stahlman -Added buffer-local mapping (\ga) and command (:GetTokInfo) for obtaining
information about a specific character/token in a txtfmt buffer.
(Functionality is analogous to that of Vim's ga normal mode command.)
-Fixed documentation and reporting bug that caused a 0-based color index to be
displayed instead of the 1-based index specified in the help file. (Affected
:MakeTestPage, \ga, :GetTokInfo and documentation)
txtfmt_v1.0b.tar.gz 1.0b 2008-04-10 6.0 Brett Stahlman Fixed bug in ftplugin that caused sample "user-maps" (defined for testing) to override any user-defined ones.
txtfmt_v1.0a.tar.gz 1.0a 2008-04-06 6.0 Brett Stahlman Initial upload
ip used for rating: 54.226.133.245

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.
   
SourceForge.net Logo