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 1082/603, Downloaded by 6887    Comments, bugs, improvements  Vim wiki

created by
Brett Stahlman
 
script type
utility
 
description
USER FEEDBACK NEEDED: I would greatly appreciate comments and suggestions, especially on the new "auto-maps" feature and associated "selector patterns":
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 ===
http://www.txtfmt.webs.com

=== 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 using Vim to edit plain text: 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 intuitive mappings provided by the filetype plugin. 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.
Note: Standout, reverse and undercurl are supported only in certain configurations. For details...
    :help txtfmt-formats

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

Everything is documented in an extensive Vim help file. Additionally, this page contains usage examples and a "Quick-Start Tutorial", designed to help you get up and running quickly with Txtfmt.

=== MANUAL VS AUTO MAPS ===
!!!! NEW FEATURE (version 3.0) !!!!
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 highlighting 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. 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 maps: operate on the text moved over (or 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 maps.

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

The next few sections give usage examples of visual/operator auto maps and manual maps...
Note: If you wish to try the usage examples now, you will need to install and load the plugin. If you're in a hurry, and are familiar with plugin installation, just drop the bundle of files in the proper location and do...
    :set ft=txtfmt
The "INSTALL DETAILS" section (further down) discusses plugin load in greater detail...

=== 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 or 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.
Mnemonic: The `=' causes any existing format attributes to be overwritten; `+' (the default) adds to, and `-' subtracts from the existing attributes. More on this later...

=== USAGE EXAMPLE (OPERATOR 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, suppose you wish to italicize and underline the line containing the word just highlighted and the subsequent 2 lines. In normal mode, with cursor still on the previously-highlighted word, 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 you used "fui" instead of "f=ui", the word you highlighted in the first step has retained the bold attribute.

=== SELECTIVE HIGHLIGHTING ===
Txtfmt now allows you to target only specific sub-regions within the visually-selected or operated-on text. To apply highlighting selectively, simply append a `/' to the highlighting spec, followed by a "selector pattern expression": i.e.,
    <highlighting-spec> / <selector-pattern>
The simplest way to explain selector patterns is with examples...

    fu/cr
        Action: Add underline attribute
        Applies To: Red text

    cb/cr||f&bi
        Action: Make foreground color blue
        Applies To: Text that is red OR has *both* bold *and* italic attributes
        Note: `f&' should be read as "has *all* of the following attributes"

    fu,kg/cr&&f|bi
        Action: Add underline attribute AND make background color green
        Applies To: Text that is red AND has *either* bold *or* italic attributes
        Note: `f|' should be read as "has *any* of the following attributes"

    fi/cr||f=bu
        Action: Add italic attribute
        Applies To: Text that is red OR has bold-underline attributes and no others

    cb kr f-i / fbi & !(cr & k-)
        Action: Set fg color blue, bg color red, and remove italic attribute
        Applies To: Text that is bold-italic AND is NOT red with clear background

** Points to Note **
-Whitespace (ignored by Txtfmt) can be used to make the expressions (both highlighting and selector) easier to read.
Caveat: `f&<attrs>' and `f|<attrs>' are atomic constructs: don't put space between the `f' and the operator, or between the operator and the list of attributes.
-For logical AND and OR, you can double the operator if it looks nicer to you.
Rationale: | and & are equivalent to || and &&, respectively, but to avoid confusion with the special `f|' and `f&' primitives, some users may prefer the longer forms.
-You can drop the `=' from `f=<attrs>' in a selector expression.
Rationale: `=' is the default operator in selector expressions: i.e., f=ub is equivalent to fub.
Caveat: In the auto-map highlighting spec itself (i.e., the "action" portion of the spec), f=ub and fub mean different things: the former means set to *exactly* underline-bold, whereas fub is a synonym for f+ub, which means add underline-bold on top of existing format attributes.


=== USAGE EXAMPLE (MANUAL MAPS) ===
Suppose you wish to enter some green text...
You execute one of Txtfmt's "insert-token" mappings (e.g., \i, \I, \a, \A, \o, etc... 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.

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 (CTRL-\ CTRL-\) 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.
Explanation: 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: brettstahlman AT gmail DOT com
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...

=== EXPORTING HIGHLIGHTED DOCUMENTS ===
If you wish to make your highlighted 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 highlighting in a test page, you will probably want to try creating your own highlighting. 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. To keep this "quick-start tutorial" quick, I'll demonstrate only a few of the available mappings. After you've completed the tutorial, you may want to have a look at the following sections in the help...

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

Let's begin...
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...
Note: For the sake of subsequent examples, it would be best to type at least a few words whenever you're prompted to enter some text.

The text you just typed should be highlighted bold-underline-italic. 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 what follows constitutes 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. Type some more text, and notice 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 (mnemonic: like normal mode 'o' command in Vim):
    \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

Type a little blue text now... 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'.) Txtfmt provides 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'

    :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. Using \A instead of \a would insert the token at the end of the line.)
Enter the following at the prompt:
    fbi

Now type some blue, bold-italic text. 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 have not been canceled (either by the "no color" token (c-) or some other fg color token).

Tip: Txtfmt tokens "supersede" preceding tokens of the same type; thus, the "no format" / "no color" tokens are required only when you wish to return to default highlighting. 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 supersede the blue foreground color token entered earlier, let's enter a red foreground color token by hitting <CTRL-\><CTRL-\> once more (assuming you're still in insert mode) and entering the following at the prompt:
    cr

Now type some red bold-italic text.
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 3 background colors: red, green and blue. 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. (As of version 3.0, you can alternatively separate with whitespace.) 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 insert tokens. 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 been placed *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.
Important Note: This example was intended only to demonstrate the use of the \s manual map. Auto maps provide a less tedious way to accomplish this sort of highlighting change.

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 Vim 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 (new in version 3.0) --

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

Using either mouse or visual mode, select some text in the plain (unhighlighted) region created earlier, then 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 let's change the highlighting of just one word within the blue bold-italic block highlighted earlier. In particular, we want to do the following:
    -Remove italic
    -Add underline
    -Change color to green
    -Make background red

Aside: You could accomplish this with manual mappings by inserting "fbu", "cg" and "kr" tokens at the start of the word, and "fbi", "cb" and "k-" tokens at the end of the word. But this would be rather 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 map, simply position yourself at the start of any of the words in the aforementioned blue bold-italic region 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,cg,kr
Notice that the word at cursor is now green bold-underline with red background, and the containing region is unchanged.

The fmt spec you just entered used "additive mode" to add underline and subtract italic. An additive mode spec uses `-' to "subtract", or remove, specific attributes. Although an explicit `+' can be used to "add" fmt attributes, it is generally unnecessary, since format 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-u      add bold and italic / remove underline
    f+bi-u     same as above
    fb-u+i     same as above
    f-bi       remove bold and italic
    f-         clear all format attributes

Note: You might have been tempted to think of `f-' as a degenerate additive mode spec that removes nothing (i.e., as a NOOP); however, this would have been too confusing for legacy users accustomed to thinking of a `-' by itself as "clear all" formats/colors.

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 could be extremely tedious. But with additive mode, you can simply select the entire paragraph (or move over it with an operator map) and specify...
    fi
...and Txtfmt will do everything necessary to italicize the paragraph without affecting any existing highlighting.

But what if, instead of adding to existing sub-regions, you simply want to wipe out the existing highlighting and replace it with something new? In such cases, 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., same as f-)
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, `+' is not permitted in fg/bg color specs; `=' is permitted, but only because some users may like some separation between the 'c' or 'k' and the following color name (and whitespace is illegal there).
Examples:
    cb      fg color blue
    cblue   same as above
    k=b     bg color blue
    k-      clear bg color
    k=      same as above

Note: Earlier versions of Txtfmt required a `,' between the components of a fmt/clr spec. This release permits either comma or whitespace: e.g., both of the following forms should work:
    fbi,cb
    fbi cb
Rationale: Intended to help users with keyboards whose `,' key is not conveniently located.

*** Selective Highlighting (!!! new in version 3.0 !!!) ***
Now suppose you'd like to change the highlighting of some, but not all, of your bold-italic regions: specifically, text that is underlined and/or has background color should be left as-is, but all other text containing both bold and italic attributes should be un-italicized and colored green. Txtfmt's "selector patterns" make this task quite simple. From normal mode, hit the following key sequence to go to the first line and initiate Txtfmt operator mode highlighting (alternatively, you could visually select the entire buffer, and hit \h):
    gg\h

Txtfmt is awaiting a motion: hit G to operate on the entire buffer, and enter the following at the resulting Txtfmt prompt:
    f-i cg / k- && f&bi && !f|u

Note: To avoid confusion, I used whitespace liberally, and used the long form of the logical operator `&&' (which can also be written as `&'). The following spec is unambiguous, and equivalent to the one above:
    f-i,cg/k-&f&bi&!f|u

After you have executed this highlighting spec, notice how only the targeted bold-italic regions were affected. The red-bold-italic on blue background, for instance, was untouched because its background color prevented the `k-' in the selector pattern from matching. Similarly, the bold-italic-underline region was unaffected because of the `!f|u' in the selector pattern. The following 3 primitives can be used to match format attributes in a selector expression:
    f&<attrs>
        Contains ALL OF the listed attributes
    f|<attrs>
        Contains ANY OF the listed attributes
    f=<attrs>
        Contains EXACTLY the listed attributes (no more, no less)
    Note: The operator following `f' is optional, with `=' being the default, so f<attrs> and f=<attrs> are equivalent.

Note: You may have noticed that I made that selector pattern a bit more complicated than it needed to be. In particular, I used `f&bi' to select all regions containing bold and italic (including those containing additional attributes, such as underline), then used `!f|u' to exclude regions containing the underline attribute. If I really wanted to operate only on regions that were exactly bold-italic, I could have used the following, simpler selector:
    f-i cg / k- && f=bi
Note that in this case, I could alternatively have written the action spec as `f=b cg', since removing italic from a bold-italic region is the same as setting the region to bold.

Note that selector expressions are true boolean expressions, which can be as simple or as complex as you like: use `!', `(' and `)' to build complex expressions: e.g.,
    !(f&bi || cb) && (f|ui && k-)


*** 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, position your cursor at the start of the buffer by hitting gg0. At this point you should be sitting on an underline-bold-italic format token. If you wish to verify this, hit the following map in normal mode:
    \ga
    :help txtfmt-get-tok-info

Because you wish to delete the first two words, enter the following in normal mode:
    d2w
Notice how the underline-bold-italic highlighting has been lost! The problem is that the command that deletes the first two words has also deleted the Txtfmt format token. 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 modes. Its default mapping is \d. To use it with the previous example, you could simply have hit \d2w instead of d2w. Try it now (after hitting 'u' to undo the problematic delete, and '0' to be sure you're at the start of the line). 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 commands and options. More detailed information may be found in the Txtfmt help file.
    :help txtfmt

    vim:et:ts=4:sw=4:tw=0:linebreak
 
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...

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

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

=== 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.0.tar.gz 3.0 2016-05-14 7.0 Brett Stahlman "Auto Maps" Formal Release:
-Visual/operator maps simplify highlighting: visually select (or move over) region to be highlighted, specify desired change, and let Txtfmt "make it so". (No more fiddling with start/end tokens.)
-Selective highlighting via "selector pattern expressions": e.g., add italic, but only to text that is currently red-bold; change currently red text to yellow; etc...
-Various minor fixes/enhancements.
txtfmt_v3.0beta-2.tar.gz 3.0beta-2 2016-04-28 7.0 Brett Stahlman Added "True Color" support for color terminals in Neovim. (Prior to this, highlighting was invisible in Neovim color terminals when the $NVIM_TUI_ENABLE_TRUE_COLOR env var was used to enable 24-bit "true color".)
txtfmt_v3.0beta-1.tar.gz 3.0beta-1 2016-04-23 7.0 Brett Stahlman "Auto-maps" Beta release:
!!! New Feature !!! - "Selective Highlighting"
Modify highlighting spec with a "selector pattern" that targets only a subset of the selection: e.g.,
    f+u / cr && fbi
...to add underline attribute, but only to text that is red bold-italic already.
txtfmt_v3.0alpha-6.tar.gz 3.0alpha-6 2016-04-17 7.0 Brett Stahlman Bugfix: Automatic line breaking during token insertion breaks auto map highlighting. (Occurs only when 'textwidth' is nonzero, and the tokens inserted by an auto map cause 'textwidth' to be exceeded.)
txtfmt_v3.0alpha-5.tar.gz 3.0alpha-5 2016-04-10 7.0 Brett Stahlman "Auto-maps" alpha release:
Bugfix: Calls to s:Contains_hlable were causing cursor to move backwards spuriously (due to failure to restore cursor pos after temporary move), which broke highlighting in certain scenarios (and could conceivably have been preventing timely exit from Vmap_collect search loop).
Note: This release *may* provide a fix for the Annis Monadjem issue.
txtfmt_v3.0alpha-4.tar.gz 3.0alpha-4 2016-03-27 7.0 Brett Stahlman "Auto-maps" alpha release:
Minor change to logic pertaining to cleanup of unnecessary tokens near end of buffer.
txtfmt_v3.0alpha-3.tar.gz 3.0alpha-3 2016-03-27 7.0 Brett Stahlman "Auto-maps" alpha release:
Bugfix for issue affecting highlighting of regions near end of buffer.
txtfmt_v3.0alpha-2.tar.gz 3.0alpha-2 2016-03-17 7.0 Brett Stahlman Minor bugfixes and UI tweaks to alpha release of "auto maps" feature: e.g., `f-' and `c-' now mean "clear format" and "clear color", respectively.
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.166.191.112

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