*TagmaTips.txt*	Plugin to display Tool Tips.
			     For Vim version 7.x.
		  Last Changed: Fri Nov 22 05:33 AM 2013 EST
		https://github.com/JessicaKMcIntosh/TagmaTips
	     http://www.vim.org/scripts/script.php?script_id=3738
		    By Jessica K McIntosh AT gmail DOT com

Contents:					*TagmaTips*
	Description				|TagmaTips-description|
	Installation				|TagmaTips-installation|
	Supported Types				|TagmaTips-types|
	Commands				|TagmaTips-commands|
	Settings				|TagmaTips-settings|
	Adding File Types			|TagmaTips-adding-types|
	Plugin API				|TagmaTips-api|


==============================================================================
DESCRIPTION					*TagmaTips-description*

This plugin uses the Tool Tip / Balloon functionality of Vim to display Tool
Tips for code. Currently only Awl, Tcl and Vim are supported.

Tool Tips are displayed for commands, variables and user defined procedures /
functions. The current buffer is checked for user defined procedures /
functions when it is written to disk.

See the GitHub URL above for more information and screenshots (in the wiki)

Note: TagmaTips can consume a large quantity of memory. To limit the memory
used either disable auto enable or limit the file types that are enabled.

==============================================================================
INSTALLATION					*TagmaTips-installation*

Copy the files to your ~/.vim or ~/vimfiles directory.
If using a package manager like pathogen place the whole directory in the
bundle directory.

==============================================================================
SUPPORTED TYPES					*TagmaTips-types*

AwK	Locates user defined functions.
	Supports Awk variables and most primitives.

Perl	Locates user defined functions.
	Supports most Perl primitives.

Tcl	Locates user defined functions.
	Supports most Tcl variables and primitives.

Vim	Locates user defined functions.
	Loads builtin functions, internal variables and features from the
	eval.txt help file. Loads options from the options.txt help file.
	Loads AutoCmd Events from the autocmd.txt help file.
	If enabled the data loaded from the help files is cached.

==============================================================================
COMMANDS					*TagmaTips-commands*

:EnableTips					*EnableTips*
	Enables tool tips for the current buffer if the file type is
	supported. Reports an error if the file type is not supported or if
	tool tips are already enabled for the current buffer.

==============================================================================
SETTINGS					*TagmaTips-settings*

*g:TagmaTipsAutoEnable*
	Automatically enables tool tips for supported file types.
	If disabled tool tips must be manually enabled for each buffer using
	the command |EnableTips|.
	Defaults to true. Set to 0 to disable. >
	let g:TagmaTipsAutoEnable = 1
<

*g:TagmaTipsDebugMode*
	Enables debugging output.
	This is only useful if developing changes or experiencing issues.
	Currently this only enables errors when attempting to load a file type
	specific autoload file. This will have more uses in the future.
	Disabled by default. Set to 1 to enable. >
	let g:TagmaTipsDebugMode = 0
<

*g:TagmaTipsCachePath*
	The path to save Cache files.
	Defaults to the directory 'cache/' where the plugin is installed.
	If the directory does not exist an attempt is made to create it. >
		let g:TagmaTipsCachePath = '~/.vim/tips_cache/'
<

*g:TagmaTipsEnableCache*
	Enables caching of Tool Tips data if the file type supports it.
	If disabled also disables creathing the cache path.
	Enabled by default. Set to 0 to disable. >
	let g:TagmaTipsEnableCache = 1
<

*g:TagmaTipsLineLimit*
	Limits the number of lines in the Tool Tips body.
	If a tool tip body exceeds this number of lines it is truncated and
	the last line is "...". Does not affect existinc cache files.
	Defaults to 30 lines. >
		let g:TagmaTipsLineLimit = 30
<

*g:TagmaTipsTypes*
	Set the file types that will be enabled. This must be a list.
	If not specified all supported file types are enabled. >
		let g:TagmaTipsTypes = ['awk']
<

*g:TagmaTipsVimDisable*
	Disables the extended Vim support.
	Reading the data from the help files can take a while.
	This will stop the related slow-down.
	If caching is enabled this slow-down will only be experienced once.
	Enabled by default. Set to 0 to disable. >
		let g:TagmaTipsVimDisable = 1
<

==============================================================================
ADDING FILE TYPES 				*TagmaTips-adding-types*

To add new file types the file "plugin/TagmaTips.vim" needs to be modified.
The file type needs to be added to the Dictionary "g:TagmaTips#Settings. See
the the |TagmaTips-api| section for details.

In order for primitives and variables to exist for tool tips they must be
defined in an file type specific autoload file. The name of the file is
"autoload/TagmaTips#.vim" where "#" is the file type identifier. For example
the Tcl specific file is "autoload/TagmaTipstcl.vim".  When a file type is
setup the function "LoadSettings" is called from the file type specific
autoload file. The function must include the autoload file in the name. The
Tcl example would be "TagmaTipstcl#LoadSettings()". See |autolaod| for more
information.

File types can have a custom function to lookup tool tips. If the setting
"expr" exists for a file type then that function is called if the tool tip can
not be found in the normal lists. See the |TagmaTips-api| section for details.

It is suggested to copy the settings and autoload files for an exist file type
and modify them to match the new file type. For a simple example see the Tcl
settings and file, for a complex example see the Vim settings and file.

==============================================================================
PLUGIN API	 				*TagmaTips-api*

User Procedures ~

User procedures are searched in the current buffer using the function
TagmaTips#ProcScan(). This function is invoked when the buffer is written via
an |autocmd|. The procedures are stored in the dictionary
b:TagmaToolTipsProcs.

Cache Files ~

Cache files are stored in the directory cache/ in the directory the plugin
files are located. This can be changed via the |g:TagmaTipsCachePath| setting.
If the directory does not exist an attempt is made to create it. Cache files
are named after the file type with the extension .txt appended, eg vim.txt.
Cache data is saved and loaded using the functions TagmaTips#CacheSave() and
TagmaTips#CacheLoad()

Cache files contain four lines. The first two are comments, the plugin version
and the cache data. The comments identify the purpose of the file and warn
against changing the contents. The version is saved to prevent compatability
issues in future versions. The version is incremented when any change would
impact existing cache files, eliminating user intervention in such cases.

Functions ~

TagmaTips#CacheLoad({type})			*TagmaTips#CacheLoad()*
		Source File:	autoload/TagmaTips.vim
	Load cache data for a file {type}. The cache data is added to the
	g:TagmaTipsSettings dictionary for the specified file type.

TagmaTips#CacheSave({type}, {keys})		*TagmaTips#CacheSave()*
		Source File:	autoload/TagmaTips.vim
	Saves the specified {keys} from the g:TagmaTipsSettings dictionary for
	the specified file {type} to a cache file.

						*TagmaTips#StoreTip()*
TagmaTips#StoreTip({type}, {key}, {name}, {body})
		Source File:	autoload/TagmaTips.vim
	Stores a tool tip in the g:TagmaTipsSettings dictionary. The tool tip
	is stored by {name} for the file {type} under the specific {key}. The
	{body} should be a list and will be converted if it is not. If the
	{body} has more than |g:TagmaTipsLineLimit| elements it is truncated
	and "..." is used for the last item. If {name} is empty no action is
	performed. This is intended behavior to allow calling as data is
	parsed without adding extra checks. If {type} is empty the tool tip is
	stored instead in b:TagmaToolTipsProcs.

TagmaTips#ProcScan()				*TagmaTips#ProcScan()*
		Source File:	autoload/TagmaTips.vim
	This is the function that scans a file for user defined procedures. It
	is run via an autocmd when the file is written to disk. This function
	should not be changed as it will affect all file types. The settings
	_blank and _proc define what is considered a user procedure and which
	lines are included in the tool tip body.

TagmaTips#SetupBuffer()				*TagmaTips#SetupBuffer()*
		Source File:	autoload/TagmaTips.vim
	Creates settings in the current buffer for tool tips. All settings are
	based on the file type. An autocmd is created to scan for user
	procedures when the buffer is written. If the file type specific
	settings, see _loaded, have not been loaded they are loaded at this
	point. Some settings are cached in buffer variables for cleaner code
	and faster access.

File Type Settings ~

Each file type has an entry in the g:TagmaTipsSettings dictionary. The
dictionary is keyed by file type. These settings determin how the plugin
behaves for each file type. At a minimum the settings "_blank" and "_proc"
must be set. All other settings are optional, with the exception of "_loaded".

File type specific settings can be freely added. Settings that start with an
underscore, "_", are reserved for internal use only.

_loaded	Boolean to indicate if file type specific settings are loaded.
	Only present when the file type settings have been loaded. To disable
	checking for file type specific settings set this to 1. Normally this
	should only be set internally.

_blank	Regexp that matches a blank line.
	This is used to locate the start of the description for a user
	procedure.

_proc	Regexp that matches a procedure definition.
	Each line of the current file is checked for this regexp when the file
	is written. Combined with the setting blank defines how the function
	TagmaTips#ProcScan() locates user defined procedures.

	The regexp must contain two groupings:
	#1  The procedure definition for the tooltip body.
	#2  The name of the procedure for the dictionary of user procedures.
	    This is used as they key in the dictionary and is what would be
	    passed from Vim to indicate the cursor is over a word.

_prim	Dictionary of language primitives.

_vars	Dictionary of language variables.

_expr	If present this function is called if no matches are found for the
	word under the cursor. Normally tool tips are checked for in the user
	procedure dictionary then the settings _prim, _vars, _palias and
	_valias.  If no entries are found the function name stored in this
	setting is called. This function MUST return a list, even if it is
	empty.  See the file autoload/TagmaTipsvim.vim for an example.

_palias	Dictionary of primitive aliases.
_valias	Dictionary of variable aliases.
	The alias settings are used when a primitive or variable can have
	several names. If an alias matches then that word is looked up in the
	respective setting. For example the Perl documentation for the "-X"
	operator is would have aliases keys for "-r", "-w" and so on.
 
The settings "_vars", "_prim", "_palias" and "_valias" are populated from an
autoload plugin for the file type. See autoload/TagmaTipstcl.vim for a simple
example.
 
 vim:ts=8 sw=8 noexpandtab tw=78 ft=help: