install_details.txt

=== DISTRIBUTED FILES ===
The Txtfmt distribution comprises the following 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.

=== INSTALLATION ===
Txtfmt can be installed using any of the standard Vim plugin mechanisms: e.g., Pathogen, Vundle, etc. If you're not using a plugin manager, simply uncompress the Txtfmt distribution somewhere in your 'runtimepath' (e.g., ~/.vim/) and run the following command to prepare the Txtfmt help:

    :helptags ALL

=== PLUGIN LOADING ===
Caveat: Like most plugins, Txtfmt requires both filetype detection and syntax highlighting to be enabled, yet neither is enabled in Vim's default configuration; thus, 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

At this point, if the plugin has been properly installed, you can load the plugin manually by executing the following from the Vim command line:

    :set ft=txtfmt

A better approach, however, is to ensure that Txtfmt is loaded automatically whenever you open certain files. Several approaches are outlined below...

Method 1: Custom filetype.vim
-----------------------------

If it doesn't already exist, create your own filetype.vim in the first directory of 'runtimepath' (e.g., ~/.vim) and add an autocommand that associates txtfmt with the desired file extensions.

Example:
    " -- filetype.vim --
    augroup filetypedetect
      " Treat files with the following extensions as Txtfmt files: .txt, .tf, .jnl
      au! BufRead,BufNewFile *.txt,*.tf,*.jnl    setfiletype txtfmt
    augroup END

Method 2: Plugin-specific file in ftdetect
------------------------------------------

If it doesn't already exist, create your own "ftdetect" folder in the first directory of 'runtimepath' (e.g., ~/.vim). In ftdetect, create a file called "txtfmt.vim" containing an autocommand that associates txtfmt with the desired file extensions.

Example:
    " -- ftdetect/txtfmt.vim --
    " Treat files with the following extensions as Txtfmt files: .txt, .tf, .jnl
    au! BufRead,BufNewFile *.txt,*.tf,*.jnl    set filetype=txtfmt

Note: When ftdetect is used, there's no need to wrap your autocommands in an `augroup` block, as your script is sourced from within an autocommand group.

    :help new-filetype

Method 3: Modeline
------------------

Modelines can be used to set filetype=txtfmt when the files you wish to highlight do not share a common extension. Simply add a line like the following to the beginning or end of a file you wish to highlight:

    vim:ft=txtfmt

Note: You'll need to close and reopen the file to cause the line to be processed.

=== COMBINING TXTFMT WITH OTHER FILETYPES ===
It is quite possible to use Txtfmt highlighting in a file associated with another filetype plugin. For instance, if you're using a plugin that facilitates note-taking or journaling, you may wish to use Txtfmt to highlight the entries. It is even possible to "nest" Txtfmt highlighting regions within syntax regions defined by other plugins, but nesting must be enabled explicitly by setting the `txtfmt-'nested'` option.

    :help txtfmt-combining
    :help txtfmt-nesting