CustDoc

Provides a function to create custom help-like commands.

Overview

The "Custom Documentation" plugin allows users to add custom documentation commands (akin to :help) without adding to the editors documentation namespace. For example, one might connect a command DocC to look up documentation about the code used in the project. Functions that have the same name as vim would only return the project documentation for the DocC command and only the VIM documentation for the :help command.

The following are the goals of this plugin:

Documentation should be in a singleton window like the help command uses (but not sharing the help window itself)
Allow more than one documentation command to be defined (keeps things flexible, so projects needing more than one separate namespace don't need to recreate the plugin)
Not force users/projects to use a particular format for the documentation (This plugin does not manage the generation of help indices, it just allows searching and opening the documents)

Requirements

This plugin has been tested on Vim 7.3. It will probably work on others as well. The following features are required for any operation:

+eval
+user_commands

The following features are suggested for best operation:

+cmdline_compl
+windows
+statusline

Installing

If you use Pathogen:

bzr branch http://linsam.homelinux.com/projs/vim-custdoc ~/.vim/bundle/vim-custdoc

Otherwise, branch or checkout the code and then copy the files into your ~/.vim directory.

Usage

Before this plugin can search and open documentation files, a tags file for the documentation must exist. Any tags generator will work. For example, for VIM formatted documentation, the :helptags command will generate the appropriate tags file. Once the tags file exists, call the CustDoc_makeCmd() function, providing it the name of the command to make, and the location of the tags file. For example

:call CustDoc_makeCmd("DocC", "projdoc/tags")

Note: If provided a relative path, that path will always be relative to the current working directory of Vim. If you want to change directories and still have working documentation, provide an absolute path! This will create a command called "DocC" and a sister function for commandline completion. It will fail if DocC already exists, or if CustDoc_completeDocC already exists. This function call can be made by hand every time you open Vim, or it can be be placed in your .vimrc so that it is always available. There are (probably) other plugins available which allow per-project vimrc files where this call could be placed for project-specific documents. For global definitions in .vimrc, the author recommends naming the commands based on project.

Function Documentation

CustDoc_makeCmd({name},{tagspath}): Creates a command by the name of the string {name}, a completion function by the name of CustDoc_complete{name}, and binds them to the index file {tagspath}, which should be a normal Vim tags file. {name} must start with a capital letter, or the command will fail (Vim only allows user commands to begin with uppercase letters).
CustDoc_searchDoc({tagspath},{query}): Opens the (or finds previously open) documentation window, and loads a buffer based on {query} into it. {tagspath} specifies the index file to use. Intended for use by the commands generated by CustDoc_makeCmd() function, but may be called directly if desired.