*mu-template.txt*	Utility for loading and expanding template-files
*mu-template.vim*	For Vim version 6.0.+	Last change: 28th Jul 2003
*Template*

		    Template MANUAL	by Luc Hermitte (LH)
		    Version ~0.31


==============================================================================
CONTENTS                                    *MuT-contents*     {{{1
|MuT-presentation|	Presentation
|MuT-features|		Features
|MuT-syntax|		Template-files syntax
|MuT-config|		Configuration
|MuT-design|		Design considerations
|MuT-files|		Files
|MuT-trojan-horse|	Security concerns
|MuT-credits|		Credits
|add-local-help|	Instructions on installing this file

}}}1
==============================================================================
PRESENTATION                                *MuT-presentation* {{{1

Template is a template-files loader for Vim. Once loaded, templates are
interpreted and expanded according to a flexible syntax (|MuT-syntax|).

Note: Every time you read "I", "me" or "my", consider that I, Luc Hermitte, have
written this documentation.

------------------------------------------------------------------------------
					*MuT-paths*        {{{2
Template-files paths~

The template-files are searched within a list of directories specified by
|{runtimepath}/template/| and by |$VIMTEMPLATES|. 

*{runtimepath}/template/* refers to 'template/' subdirectories, built from the
list of directories specified in the 'runtimepath' vim-option. 

*$VIMTEMPLATES* is a comma (or semicolon) separated list of directories. When
set, it has precedence over paths of the form |{runtimepath}/template/|.


Precedence~
By default, the template-files should be installed into your
$HOME/.vim/after/template/ directory. ($HOME/vimfiles under windows systems ...
cf. 'runtimepath' for other acceptable directories ; prefer the after/
sub-hierarchy).

Hence, you can easily override a default template-file by yours. Put your file
into your $HOME/.vim/template/ directory.


Sharing template-files~
As template-files are searched within a list of directories, sharing them
between several people or teams becomes really easy. They are several ways to
proceed:
- put all the template-files into $VIM/vimfiles/after/template/
  At this point, VIM administrators (often known as system administrators) on
  your environment should not let anybody add new template-files to the common
  repository. Cf. |MuT-trojan-horse|.
- Import the configuration from another VIM user by adding '~hislogin/.vim' to
  your 'runtimepath'. By doing so, you will use the plugin and ftplugins he is
  using, but also the template-file he uses. 
- More interresting, on a project you work on with other VIM users, you can
  share a directory with everybody and set |$VIMTEMPLATES| point to this
  directory.
  If you are working on several projects, you can use for instance Aric Blumer's
  |project| plugin and set |$VIMRUNTIME| to a specific value with every
  different project. It is not very handing yet, but I'm opened to any
  suggestion.

Note: Every time you share template-files with other people, be sure that these
template-files are not |MuT-trojan-horse|s. Actually, it is the same issue as
using someone else's plugins.

------------------------------------------------------------------------------
					*MuT-load*         {{{2
Loading template-files~

There are several ways to load template-files:

					*MuT-autoload*                  {{{3
Automatic expansion of templates when opening new files~
    When opening a new file, if |g:mt_IDontWantTemplatesAutomaticallyInserted|
    is false, then the first template-file found whose name matches:
	{path}/template.{filetype}
    is loaded and interpreted.

    {path} refers to directories listed within |{runtimepath}/template/| or
    |$VIMTEMPLATES|.
    {filetype} refers to the |filetype| of the new file.


- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
					*:MuTemplate*                   {{{3
Explicit expansion of template-files~
    We can explicitely load and interpret the template-file whose name matches:
	{path}/template.{extension}
    thanks to the command:
	:MuTemplate {extension}
	
    Note: {path} still refers to directories listed within |$VIMTEMPLATES| or
    |{runtimepath}/template/|.


    The code snippets associated to a particular filetype can be accessed thanks
    to the call:
	:MuTemplate {ft}/{code}
    which loads and interprets the template-file whose name matches:
	{path}/{ft}/template.{code}

    Note: The filetype of the current file does not need to be the same as {ft}.
					
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
					*i_CTRL-R_SPACE* *i_CTRL-R_TAB* {{{3
Insert-mode expansion of template-files~
    This plugin defines two default insert-mode mappings:
    (*) i_CTRL-R_SPACE 
	uses as a {pattern}: the keyword (check 'iskeyword') before the cursor.
    (*) i_{WORD}_CTRL-R_TAB
	uses as a {pattern}: the |WORD| before the cursor.

    ]Contrary to |expand()|, "before" means "whose first character is placed on
    ]a column prior to the column where is cursor is".

    The work of the mappings consists in:
    - listing all the template-files whose names match:
	 {path}/template.{filetype}-{pattern} 
      or {path}/{filetype}/template.{pattern}
    - If there are several matches, the user will have to choose one template-
      file.
    - The template-file thus selected is inserted in place of the (key)word
      before the cursor.

      If there were characters before and after the word, the line is not split.
      For instance, let's suppose the xslt line: >
	blah xsl:val foo
<     with the cursor just after "val". 
      Hitting CTRL-R_TAB expands the line into: >
        blah <xsl:value-of select=XPath/> foo


- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
Through the menu                {{{3~
    See |MuT-menu|.


==============================================================================
FEATURES                                    *MuT-features*     {{{1

{{{2 Markers -- a.k.a `placeholders'   ~
				 				*MuT-markers*

    {{{3 Inserting markers                           ~
							    *MuT-Marker_Txt()|*
    This plugin supports |markers| -- also known as |placeholders| in Srinath
    Avadhanula's imaps.vim plugin. 
    
    To benefit (of?) the power of advanced markers sytstems, use the function
    |Marker_Txt()| within your template-files -- or even |Marker_Open()| or
    |Marker_Close()|. The text will be expanded into "{parameter}",
    "<+{parameter}+>" or whatever according to your configuration and your
    environment.

    Several template-files are already relying on these functions.
    
    They are defined into |bracketing.base.vim|, which is shipped with the
    tarball archive mu-template.tar.gz. 
    Right now, they are compatible with my |markers| system and Srinath
    Avadhanula's |placeholders| system. However, to use his configuration
    variables instead of mine, don't forget to set |g:use_place_holders| to 1.

    If you want to develop or support another n-th markers system, then you will
    have to define these three functions in a plugin that MUST be placed into
    one of your {runtimepath}/after/plugin/ directories (not just
    {rtp}/plugin/), and to define as well the mappings to |!jump!| -- see
    |MuT-!jump!|. 

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
    {{{3 Jumping to markers                          ~
							  |!jump!| *MuT-!jump!*
    |bracketing.base.vim| also proposes some default mappings that jump to the
    next marker. These mappings are required by Template.

    Note: This means that by default, the jumping-forward function from my
    |markers| system will be used. The jumping functions defined are quite
    accurate (they handle multi-characters markers, multi-byte characters, don't
    mess when jumping to markers hidden within folds, etc), very flexible
    (through options), and can jump forward and backward.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
    {{{3 Automatic jump to the first marker              ~
		    *b:mt_jump_to_first_markers* *g:mt_jump_to_first_markers*
    After a template-file has been loaded and expanded, the cursor is moved to
    the first |marker| encountered. If the marker is within a fold, then the
    fold will be opened and the marker selected.

    Sometimes, we define scripts that generate code. Usually, these scripts 
    will not expect neither the cursor to move on its own, nor to be in
    |Select-mode|. 
    In order to not mess things up this plugin defines the option
    |g:mt_jump_to_first_markers|, which must be set to 0.

    So, when a new buffer is created, we can prevent Template from jumping to
    the first marker. For instance, my |lh-cpp-ftplugins| detects Template
    presence on the system, and sets off this options while generating code. If
    you are using such a tool unable to work with Template, patch it
    (contacting the author is even better) to integrate something like: >
      if exists('g:mu_template') && 
	    \ (   !exists('g:mt_jump_to_first_markers') 
	    \  || g:mt_jump_to_first_markers)
	" NB: g:mt_jump_to_first_markers is true by default
	let mt_jump = 1
	let g:mt_jump_to_first_markers = 0
      endif
      
      ... where a new buffer is opened and filled ...

      if exists('mt_jump')
        let g:mt_jump_to_first_markers = mt_jump
        unlet mt_jump
      endif

------------------------------------------------------------------------------
{{{2 Other features of interrest       ~

    {{{3 Syntax easy to enhance                      ~

    The syntax is only limited by VimL's syntax. See |MuT-syntax|.
    Thus, you can add |plugins| of our own that define new |functions| or
    |:command|s that you can use within your own template-files.

    Right now, you can use all the builtin-|functions| that Vim proposes plus
    some wrappers I propose with Template (see |MuT-Marker_Txt()|,
    |s:Include()|) and |ui-functions.vim|.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
    {{{3 Other things provided if not yet defined ...~
    *g:author*	([$USER/$USERNAME]/"")
	    Used by some templates.

    *DateStamp()*
	    Used by some templates.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
    {{{3 Menus                                       ~
					    *MuT-menu*

    Template will propose a |menu| on systems that support them.
    The placement of the menu can be ajusted thanks to the two options:
    |g:mt_menu_priority| and |g:mt_menu_name|.

    The menu-items are based on the template-files detected on your system ;
    see |MuT-paths|:
    - First, it lists all the skeletons that can be used when a new buffer is
      created
    - Then, it lists the differents filetypes for which there are code snippets
    - Finally, the last menu item permit to rebuild the menu when some
      template-files are added or deleted from the system.
    

==============================================================================
TEMPLATE FILES SYNTAX                       *MuT-syntax*       {{{1

{{{2 Syntax                            ~
    |expression|
	is expanded into the result of the VimL {expression}.
	If the {expression} results into an empty line, this empty line is
	trimmed.
    
    VimL: {VimL-instruction}
	{VimL-instruction} is an Ex command that is executed.
	This statement is expanded into an empty string, 

------------------------------------------------------------------------------
{{{2 How-To                            ~
					    *MuT-howto*
(*) Automate the insertion |markers|/placeholders matching your current
    configuration -> my bracketing.base.vim, or Srinath Avadhanula's imaps.vim: >
    Marker_Txt('comment text')
<   Examples available within every default template-file shipped with
    Template.
    See |MuT-Marker_Txt()|.

(*) Insert the current date: >
    strftime({format})
<   check |strftime()|

(*) Insert the name of the current file: >
    expand('%:t')
<   check |expand()|

(*) Insert your name: >
    g:author
<   See |g:author|.

(*) To store the result of a expression into a variable, use the VimL
    instruction |:let|, and make the scope of the variable to be either |s:var|,
    |b:var|, |w:var| or |g:var|. 
    |local-variable|s can not be used. 
    Ex.: >
        VimL: let s:my_variable = 1 + 2
<   However, note that some script-symbol are reserved and must not be used. See
    |MuT-reserved-symbols|.

(*) Interactively insert things  >
    VimL: let s:choice = CONFIRM('prompt', "&Yes\n&No", 2)
    IF(s:choice, 'I agree', 'I disagree')

    VimL: let s:name = INPUT('what name ?')
    The name chosen is s:name
<
    Examples: check template.vim and cpp/template.class
    See also |ui-functions.vim|.

(*) Reindent the lines inserted: 		*s:reindent*
>
    VimL: let s:reindent = 1
<
    Examples: check */template.*.

(*) Load the appropriate skeleton:		*s:Include()*
>
    VimL: call s:Include( (expand("%:e") =~ '^hh\=$') ?'c-header' : 'c-imp')
<
    Examples: check template.c

Insert here

------------------------------------------------------------------------------
{{{2 Reserved symbols                  ~
						    *MuT-reserved-symbols*

Several symbols are reserved and you must NOT use them in your template-files.
The correct execution of the plugin can not be garranty otherwise.

The exhaustive list of the reserved symbols is:
- s:last, s:crt, s:r, s:files,
- s:template_dirs,
- s:menu_prio, s:menu_name, s:AddMenu(), s:BuildMenu(),
- s:Interpret(), s:InterpretValue(), s:InterpretCommand(), s:InterpretLines(),
- s:Template(), s:TemplateDirs(), s:SearchTemplates(),
- s:CheckDeps(), s:Option().


==============================================================================
CONFIGURATION                               *MuT-config*       {{{1

{{{2 Options                           ~
    *b:mt_how_to_join* *g:mt_how_to_join*
	Used only with |i_CTRL-R_TAB|.
	== 0 : "{pattern}^r\t foo" -> "{the template}\nfoo"
	== 1 : "{pattern}^r\t foo" -> "{the template} foo"
	== 2 : "{pattern}^r\t foo" -> "{the template} foo"

    |b:mt_jump_to_first_markers| |g:mt_jump_to_first_markers| (bool; default 1)
	Specifies whether we want to automatically jump to the first |marker|
	inserted. Mainly aimed at |ftplugin| writers who wish to be compatible
	with Template.

    *g:mt_IDontWantTemplatesAutomaticallyInserted*  (boolean; default: 0)
	Forbids template from automatically inserting template-files when
	opening new files.

    *g:mt_menu_priority* (number/string; default: 59)
    *g:mt_menu_name* (string; default: "&Templates")
	These two options enable Template's menu to be placed wherever we wish
	it to be. For instance: >
            let g:mt_menu_priority = '40.700'
            let g:mt_menu_name     = '&Tools.Templates'
<       Must be set once before mu-template.vim is sourced -> .vimrc

------------------------------------------------------------------------------
{{{2 Mappings                          ~
    *<Plug>MuT_ckword* 
    *<Plug>MuT_cWORD*

CTRL-R and CTRL-X
insert something stored somewhere vs expand something
accessibility.


==============================================================================
DESIGN CONSIDERATIONS                       *MuT-design*       {{{1

Out there, there are several other template-expander plugins that use a
predefined set of "expandable" tags. 
Template, on the contrary, does not use any predefine set of tags. Instead, it
expands VimL |expression|s and interpret VimL commands. Thus it gives us an
almost unlimited rewrite this!!!


mu-Template.vim is best placed in a {rtp}/after/ directory. This way, several
things (like the bracketing and marker systems) can be overriden before this
plugin is initialized.

The default template-files, shipped with the tarball archive, are also best
placed into a {rtp}/after/ directory. Thus, it leaves us the possibility to
override them. See |MuT-paths|.

       
Template uses some other plugins. I (LH)'d rather use one (even complex) plugin
that defines a feature I need in several places, instead of copying an
over-simplified and limited version of the functions defined in that plugin in
every other (ft)plugin that need this specific feature. 
In other words, I prefer modularity over redundancy. That's why Template is
shipped with other plugins.


==============================================================================
FILES                                       *MuT-files*        {{{1

{runtimepath}/  ($HOME/.vim/ or $HOME/vimfiles/ ; cf. 'runtimepath')
+-> doc/                                         {{{2
|   |  Don't forget to execute ':helptags $HOME/.vim/doc'
|   +-> |mu-template.txt|  : this file
|   +-> |lh-map-tools.txt| : more precise help regarding the |bracketing| system
|   +-> |searchInRuntime.txt| : documentation for |searchInRuntime.vim|
|
+-> plugin/                                      {{{2
|   +-> |bracketing.base.vim|				supported
|   |   | defines markers to insert after brackets
|   +---+-> |common_brackets.vim|			supported
|   |        defines brackets mappings
|   |
|   +-> |searchInRuntime.vim|				needed
|   |    extends |:runtime| to other commands
|   |    used to correctly search in 'runtimepath'
|   +-> *word_tools.vim*				needed
|   |    defines more accurate alternatives to |expand()| applied on "<cword>"
|   +-> *ui-functions.vim*				supported
|        defines functions that will ease the definition of template-files.
|        Required by the template-files: template.vim, cpp/template.class
|
+-> after/plugin/                                {{{2
|   +-> |mu-template.vim|
|        The main file of this plugin
| 
+-> after/template/                              {{{2
|   +-> template.*	\ template-files for |mu-template|
|   +-> *		/ 
| 
+-> syntax/                                      {{{2
    +-> 2html.vim : override $VIMRUNTIME/syntax/2html.vim in order that
         mu-Template does not mess up with ":runtime syntax/2html.vim"


==============================================================================
SECURITY CONCERNS                           *MuT-trojan-horse* {{{1

Out there, there are several template expanders that strictly limit the set of
expressions they can understand and expand. With this plugin, the opposite
approach has been chosen: any VimL |expression| or statement correctly
introduced will be interpreted and expanded.

As a consequence, any one can write a template |trojan-horse| that this plugin
will execute automatically. You can argue that is a backdoor. Yes indeed. It is
a backdoor as well as |plugin|s and |ftplugin|s are. As you won't install and
activate plugins or ftplugins from untrusted sources, DO NOT install or share
template-files from untrusted sources.

This beeing said, the usual recommendations apply: do not fly a plane, pilot an
atomic plant or conduct any other important activity while this plugin is
running.


This plugin is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  


==============================================================================
CREDITS                                     *MuT-credits*      {{{1

Gergely Kontra:		Author of the first version of Template
Luc Hermitte (LH):	Author of this enhanced version and this documentation
Robert Kelly IV:	For his insight and the ideas he gave me (LH)

	* Robert Kelly IV's |fte.txt| proposes a nice way to post process the
	  skeleton inserted. ie. mu-template.vim can be used for immediate gui
	  interactions, and |:FTE| to treat delayed expansions that need more
	  attention from the developper.

                                                                           }}}1
==============================================================================
  Luc Hermitte, 2001-2003, <http://hermitte.free.fr/vim/>		{{{1
 VIM: let b:VS_language = 'american' 
 vim:ts=8:sw=4:tw=80:fo=tcq2:isk=!-~,^*,^\|,^\":ft=help:
 vim600:fdm=marker:
