txtfmt 1.0a

txtfmt is a syntax/filetype Vim plugin for adding format and color attributes to plain text.

  Add it to your Download Basket!

 Add it to your Watch List!


Rate it!
send us
an update
GPL (GNU General Public License) 
3.3/5 16
Brett Stahlman
ROOT \ Text Editing&Processing \ Others
txtfmt is a syntax/filetype Vim plugin for adding format and color attributes to plain text. txtfmt's formatting is accomplished through the use of single-character "tokens" (chosen from ranges not normally used in text files), which are used to define highlight attributes for subsequent text. The tokens themselves are concealed by Txtfmt's syntax file, so that each appears as a single space. txtfmt requires 9 such tokens for color regions. The number of tokens required for format regions varies according to the txtfmt-specific 'tokrange' option setting.

:help txtfmt-'tokrange'

If, for example, the "short" qualifier was used, then the only formatting attributes in use are bold, underline and italic. All possible permutations of these attributes may be represented with only 8 tokens. If, on the other hand, the "long" qualifier was used in the setting of 'tokrange', the set of available format attributes expands to include standout, reverse and (for Vim versions >= 7.0) undercurl. In this case, Txtfmt will require either 32 or 64 format tokens, depending upon whether the version of Vim supports undercurl.

There are 2 types of Txtfmt marker token: format markers and color markers. The 2 types of regions begun by these 2 types of tokens are "orthogonal", meaning that a format token has no effect upon coloration, and a color token has no effect upon formatting. For example, suppose you have begun a green color region by inserting the appropriate token (with one of txtfmt's mappings, to be discussed later). You now wish to emphasize a word or phrase by formatting it in italics, but you do not wish to change the color. In this case, you would simply insert the format token denoting "italic", and subsequently typed text would be green italic. If you later wished to switch back to un-italicized (normal) green text, you would simply insert the format token corresponding to "no format". Note that format and color tokens may be freely interspersed with one another in any order.

The tokens described above are simply characters belonging to the character set in use (e.g. latin1, utf-8, etc...), so it would be theoretically possible to accomplish the highlighting with a syntax file alone, by simply inserting themarker characters with CTRL-V or something similar. However, this would require you to memorize the character codes corresponding to 8 colors and all combinations of underline, bold, italic, etc... Thus, in addition to a syntax file, txtfmt provides a filetype plugin (ftplugin), which provides mappings and functions to facilitate working with the format/color tokens. Inserting tokens, finding (jumping to) tokens, and querying token type, are just a few of the operations that can be performed with mappings and/or functions defined in the ftplugin.




The txtfmt distribution comprises the following files:

doc/txtfmt.vim Txtfmt help file (this 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)
mb_patch.txt Yukihiro Nakadaira's patch to fix handling of multibyte chararacter offsets (necessary for versions of Vim prior to 7.2 if multibyte characters are used as txtfmt tokens)
indent_patch.txt Bram Moolenaar's patch to fix indent.vim's handling of dot-separated lists in 'filetype' option values (required only if you plan to use txtfmt in conjunction with C files)

All of the txtfmt.vim files should be placed in their respective parent directories, somewhere in your 'runtimepath'. If you need the patch files, you
may place them wherever you like.
Important Note: To make txtfmt help topics visible to Vim's :help command, youmust run :helptags, passing the path to the doc folder where you unpacked txtfmt.txt as an argument. e.g.,

:helptags $VIM/vimfiles/doc


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

Last updated on April 9th, 2008

#text formatter #syntax highlighter #vim script #text #syntax #highlighter #formatter

Add your review!