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/598, Downloaded by 6289    Comments, bugs, improvements  Vim wiki

created by
Brett Stahlman
script type
USER FEEDBACK NEEDED: I would greatly appreciate feedback email:
brettstahlman AT gmail DOT com

The Txtfmt help file is large; for a quick (and gentle) introduction, please see the "QUICK-START TUTORIAL" further down on this page...

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


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:
    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.

Suppose you wish to enter some green text...
You execute one of Txtfmt's "insert-token" mappings and enter the following at the prompt:
(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 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 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:
(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-separated list, thereby reducing the number of times you have to execute the mapping.

=== 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!

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)
    -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
    -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.

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:


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:

    :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:

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>:

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:

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:

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:

At the resulting prompt, enter the following:

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:
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:

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:

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:

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:

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:

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:

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):

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:

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.

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

The Txtfmt distribution comprises the following 4 files:

    Txtfmt help file
    Txtfmt filetype plugin (contains mappings for working with Txtfmt tokens)
    Txtfmt syntax file (defines the Txtfmt syntax highlighting)
    Txtfmt common configuration code (contains configuration script needed by
    both the filetype and syntax plugins)
    (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 %

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


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.

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.

    " 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_v24.vba 2.4 2010-09-28 7.0 Brett Stahlman Version 2.4 repackaged in Vimball format
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:

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