HGcommand.vim : doc integration

contrib/vim/hgcommand.vim

@@ -1,1265 +1,1984 b''
 " vim600: set foldmethod=marker:
 "
 " Vim plugin to assist in working with HG-controlled files.
 "
 " Last Change:   2006/02/22
 " Version:       1.76
 " Maintainer:    Mathieu Clabaut <[e-mail]>
 " License:       This file is placed in the public domain.
 " Credits: {{{1
 "                Bob Hiestand <[e-mail]> for the fabulous
 "                cvscommand.vim from which this script was directly created by
 "                means of sed commands and minor tweaks.
 
-" Section: Documentation {{{1
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+"
+" Section: Documentation 
+"----------------------------
+"
+" Documentation should be available by ":help hgcommand" command, once the
+" script has been copied in you .vim/plugin directory.
+"
+" You still can read the documentation at the end of this file. Locate it by
+" searching the "hgcommand-contents" string (and set ft=help to have
+" appropriate syntaxic coloration). 
+" 
+" Section: Documentation : detail {{{1
 "
 " Provides functions to invoke various HG commands on the current file
 " (either the current buffer, or, in the case of an directory buffer, the file
 " on the current line).  The output of the commands is captured in a new
 " scratch window.  For convenience, if the functions are invoked on a HG
 " output window, the original file is used for the hg operation instead after
 " the window is split.  This is primarily useful when running HGCommit and
 " you need to see the changes made, so that HGDiff is usable and shows up in
 " another window.
 "
 " Command documentation {{{2
 "
 " HGAdd           Performs "hg add" on the current file.
 "
 " HGAnnotate      Performs "hg annotate" on the current file.  If an
 "                  argument is given, the argument is used as a revision
 "                  number to display.  If not given an argument, it uses the
 "                  most recent version of the file on the current branch.
 "                  Additionally, if the current buffer is a HGAnnotate buffer
 "                  already, the version number on the current line is used.
 "
 "                  If the 'HGCommandAnnotateParent' variable is set to a
 "                  non-zero value, the version previous to the one on the
 "                  current line is used instead.  This allows one to navigate
 "                  back to examine the previous version of a line.
 "
 " HGCommit[!]     If called with arguments, this performs "hg commit" using
 "                  the arguments as the log message.
 "
 "                  If '!' is used, an empty log message is committed.
 "
 "                  If called with no arguments, this is a two-step command.
 "                  The first step opens a buffer to accept a log message.
 "                  When that buffer is written, it is automatically closed and
 "                  the file is committed using the information from that log
 "                  message.  The commit can be abandoned if the log message
 "                  buffer is deleted or wiped before being written.
 "
 " HGDiff          With no arguments, this performs "hg diff" on the current
 "                  file.  With one argument, "hg diff" is performed on the
 "                  current file against the specified revision.  With two
 "                  arguments, hg diff is performed between the specified
 "                  revisions of the current file.  This command uses the
 "                  'HGCommandDiffOpt' variable to specify diff options.  If
 "                  that variable does not exist, then 'wbBc' is assumed.  If
 "                  you wish to have no options, then set it to the empty
 "                  string.
 "
 " HGGotoOriginal  Returns the current window to the source buffer if the
 "                  current buffer is a HG output buffer.
 "
 " HGLog           Performs "hg log" on the current file.
 "
 " HGRevert        Replaces the modified version of the current file with the
 "                  most recent version from the repository.
 "
 " HGReview        Retrieves a particular version of the current file.  If no
 "                  argument is given, the most recent version of the file on
 "                  the current branch is retrieved.  The specified revision is
 "                  retrieved into a new buffer.
 "
 " HGStatus        Performs "hg status" on the current file.
 "
 " HGUpdate        Performs "hg update" on the current file.
 "
 " HGVimDiff       With no arguments, this prompts the user for a revision and
 "                  then uses vimdiff to display the differences between the
 "                  current file and the specified revision.  If no revision is
 "                  specified, the most recent version of the file on the
 "                  current branch is used.  With one argument, that argument
 "                  is used as the revision as above.  With two arguments, the
 "                  differences between the two revisions is displayed using
 "                  vimdiff.
 "
 "                  With either zero or one argument, the original buffer is used
 "                  to perform the vimdiff.  When the other buffer is closed, the
 "                  original buffer will be returned to normal mode.
 "
 "                  Once vimdiff mode is started using the above methods,
 "                  additional vimdiff buffers may be added by passing a single
 "                  version argument to the command.  There may be up to 4
 "                  vimdiff buffers total.
 "
 "                  Using the 2-argument form of the command resets the vimdiff
 "                  to only those 2 versions.  Additionally, invoking the
 "                  command on a different file will close the previous vimdiff
 "                  buffers.
 "
 "
 " Mapping documentation: {{{2
 "
 " By default, a mapping is defined for each command.  User-provided mappings
 " can be used instead by mapping to <Plug>CommandName, for instance:
 "
 " nnoremap ,ca <Plug>HGAdd
 "
 " The default mappings are as follow:
 "
 "   <Leader>hga HGAdd
 "   <Leader>hgn HGAnnotate
 "   <Leader>hgc HGCommit
 "   <Leader>hgd HGDiff
 "   <Leader>hgg HGGotoOriginal
 "   <Leader>hgG HGGotoOriginal!
 "   <Leader>hgl HGLog
 "   <Leader>hgr HGReview
 "   <Leader>hgs HGStatus
 "   <Leader>hgu HGUpdate
 "   <Leader>hgv HGVimDiff
 "
 " Options documentation: {{{2
 "
 " Several variables are checked by the script to determine behavior as follow:
 "
 " HGCommandAnnotateParent
 "   This variable, if set to a non-zero value, causes the zero-argument form
 "   of HGAnnotate when invoked on a HGAnnotate buffer to go to the version
 "   previous to that displayed on the current line.  If not set, it defaults
 "   to 0.
 "
 " HGCommandCommitOnWrite
 "   This variable, if set to a non-zero value, causes the pending hg commit
 "   to take place immediately as soon as the log message buffer is written.
 "   If set to zero, only the HGCommit mapping will cause the pending commit
 "   to occur.  If not set, it defaults to 1.
 "
 " HGCommandDeleteOnHide
 "   This variable, if set to a non-zero value, causes the temporary HG result
 "   buffers to automatically delete themselves when hidden.
 "
 " HGCommandDiffOpt
 "   This variable, if set, determines the options passed to the diff command
 "   of HG.  If not set, it defaults to 'wbBc'.
 "
 " HGCommandDiffSplit
 "   This variable overrides the HGCommandSplit variable, but only for buffers
 "   created with HGVimDiff.
 "
 " HGCommandEdit
 "   This variable controls whether the original buffer is replaced ('edit') or
 "   split ('split').  If not set, it defaults to 'edit'.
 "
 " HGCommandEnableBufferSetup
 "   This variable, if set to a non-zero value, activates HG buffer management
 "   mode.  This mode means that two buffer variables, 'HGRevision' and
 "   'HGBranch', are set if the file is HG-controlled.  This is useful for
 "   displaying version information in the status bar.
 "
 " HGCommandInteractive
 "   This variable, if set to a non-zero value, causes appropriate functions (for
 "   the moment, only HGReview) to query the user for a revision to use
 "   instead of the current revision if none is specified.
 "
 " HGCommandNameMarker
 "   This variable, if set, configures the special attention-getting characters
 "   that appear on either side of the hg buffer type in the buffer name.
 "   This has no effect unless 'HGCommandNameResultBuffers' is set to a true
 "   value.  If not set, it defaults to '_'.  
 "
 " HGCommandNameResultBuffers
 "   This variable, if set to a true value, causes the hg result buffers to be
 "   named in the old way ('<source file name> _<hg command>_').  If not set
 "   or set to a false value, the result buffer is nameless.
 "
 " HGCommandSplit
 "   This variable controls the orientation of the various window splits that
 "   may occur (such as with HGVimDiff, when using a HG command on a HG
 "   command buffer, or when the 'HGCommandEdit' variable is set to 'split'.
 "   If set to 'horizontal', the resulting windows will be on stacked on top of
 "   one another.  If set to 'vertical', the resulting windows will be
 "   side-by-side.  If not set, it defaults to 'horizontal' for all but
 "   HGVimDiff windows.
 "
 " Event documentation {{{2
 "   For additional customization, hgcommand.vim uses User event autocommand
 "   hooks.  Each event is in the HGCommand group, and different patterns
 "   match the various hooks.
 "
 "   For instance, the following could be added to the vimrc to provide a 'q'
 "   mapping to quit a HG buffer:
 "
 "   augroup HGCommand
 "     au HGCommand User HGBufferCreated silent! nmap <unique> <buffer> q :bwipeout<cr> 
 "   augroup END
 "
 "   The following hooks are available:
 "
 "   HGBufferCreated           This event is fired just after a hg command
 "                              result buffer is created and filled with the
 "                              result of a hg command.  It is executed within
 "                              the context of the new buffer.
 "
 "   HGBufferSetup             This event is fired just after HG buffer setup
 "                              occurs, if enabled.
 "
 "   HGPluginInit              This event is fired when the HGCommand plugin
 "                              first loads.
 "
 "   HGPluginFinish            This event is fired just after the HGCommand
 "                              plugin loads.
 "
 "   HGVimDiffFinish           This event is fired just after the HGVimDiff
 "                              command executes to allow customization of,
 "                              for instance, window placement and focus.
 "
 " Section: Plugin header {{{1
 
 " loaded_hgcommand is set to 1 when the initialization begins, and 2 when it
 " completes.  This allows various actions to only be taken by functions after
 " system initialization.
 
 if exists("loaded_hgcommand")
    finish
 endif
 let loaded_hgcommand = 1
 
 if v:version < 602
   echohl WarningMsg|echomsg "HGCommand 1.69 or later requires VIM 6.2 or later"|echohl None
   finish
 endif
 
 " Section: Event group setup {{{1
 
 augroup HGCommand
 augroup END
 
 " Section: Plugin initialization {{{1
 silent do HGCommand User HGPluginInit
 
 " Section: Script variable initialization {{{1
 
 let s:HGCommandEditFileRunning = 0
 unlet! s:vimDiffRestoreCmd
 unlet! s:vimDiffSourceBuffer
 unlet! s:vimDiffBufferCount
 unlet! s:vimDiffScratchList
 
 " Section: Utility functions {{{1
 
 " Function: s:HGResolveLink() {{{2
 " Fully resolve the given file name to remove shortcuts or symbolic links.
 
 function! s:HGResolveLink(fileName)
   let resolved = resolve(a:fileName)
   if resolved != a:fileName
     let resolved = s:HGResolveLink(resolved)
   endif
   return resolved
 endfunction
 
 " Function: s:HGChangeToCurrentFileDir() {{{2
 " Go to the directory in which the current HG-controlled file is located.
 " If this is a HG command buffer, first switch to the original file.
 
 function! s:HGChangeToCurrentFileDir(fileName)
   let oldCwd=getcwd()
   let fileName=s:HGResolveLink(a:fileName)
   let newCwd=fnamemodify(fileName, ':h')
   if strlen(newCwd) > 0
     execute 'cd' escape(newCwd, ' ')
   endif
   return oldCwd
 endfunction
 
 " Function: s:HGGetOption(name, default) {{{2
 " Grab a user-specified option to override the default provided.  Options are
 " searched in the window, buffer, then global spaces.
 
 function! s:HGGetOption(name, default)
   if exists("s:" . a:name . "Override")
     execute "return s:".a:name."Override"
   elseif exists("w:" . a:name)
     execute "return w:".a:name
   elseif exists("b:" . a:name)
     execute "return b:".a:name
   elseif exists("g:" . a:name)
     execute "return g:".a:name
   else
     return a:default
   endif
 endfunction
 
 " Function: s:HGEditFile(name, origBuffNR) {{{2
 " Wrapper around the 'edit' command to provide some helpful error text if the
 " current buffer can't be abandoned.  If name is provided, it is used;
 " otherwise, a nameless scratch buffer is used.
 " Returns: 0 if successful, -1 if an error occurs.
 
 function! s:HGEditFile(name, origBuffNR)
   "Name parameter will be pasted into expression.
   let name = escape(a:name, ' *?\')
 
   let editCommand = s:HGGetOption('HGCommandEdit', 'edit')
   if editCommand != 'edit'
     if s:HGGetOption('HGCommandSplit', 'horizontal') == 'horizontal'
       if name == ""
         let editCommand = 'rightbelow new'
       else
         let editCommand = 'rightbelow split ' . name
       endif
     else
       if name == ""
         let editCommand = 'vert rightbelow new'
       else
         let editCommand = 'vert rightbelow split ' . name
       endif
     endif
   else
     if name == ""
       let editCommand = 'enew'
     else
       let editCommand = 'edit ' . name
     endif
   endif
 
   " Protect against useless buffer set-up
   let s:HGCommandEditFileRunning = s:HGCommandEditFileRunning + 1
   try
     execute editCommand
   finally
     let s:HGCommandEditFileRunning = s:HGCommandEditFileRunning - 1
   endtry
 
   let b:HGOrigBuffNR=a:origBuffNR
   let b:HGCommandEdit='split'
 endfunction
 
 " Function: s:HGCreateCommandBuffer(cmd, cmdName, statusText, filename) {{{2
 " Creates a new scratch buffer and captures the output from execution of the
 " given command.  The name of the scratch buffer is returned.
 
 function! s:HGCreateCommandBuffer(cmd, cmdName, statusText, origBuffNR)
   let fileName=bufname(a:origBuffNR)
 
   let resultBufferName=''
 
   if s:HGGetOption("HGCommandNameResultBuffers", 0)
     let nameMarker = s:HGGetOption("HGCommandNameMarker", '_')
     if strlen(a:statusText) > 0
       let bufName=a:cmdName . ' -- ' . a:statusText
     else
       let bufName=a:cmdName
     endif
     let bufName=fileName . ' ' . nameMarker . bufName . nameMarker
     let counter=0
     let resultBufferName = bufName
     while buflisted(resultBufferName)
       let counter=counter + 1
       let resultBufferName=bufName . ' (' . counter . ')'
     endwhile
   endif
 
   let hgCommand = s:HGGetOption("HGCommandHGExec", "hg") . " " . a:cmd
   echomsg "DBG :".hgCommand
   let hgOut = system(hgCommand)
   " HACK:  diff command does not return proper error codes
   if v:shell_error && a:cmdName != 'hgdiff'
     if strlen(hgOut) == 0
       echoerr "HG command failed"
     else
       echoerr "HG command failed:  " . hgOut
     endif
     return -1
   endif
   if strlen(hgOut) == 0
     " Handle case of no output.  In this case, it is important to check the
     " file status, especially since hg edit/unedit may change the attributes
     " of the file with no visible output.
 
     echomsg "No output from HG command"
     checktime
     return -1
   endif
 
   if s:HGEditFile(resultBufferName, a:origBuffNR) == -1
     return -1
   endif
 
   set buftype=nofile
   set noswapfile
   set filetype=
 
   if s:HGGetOption("HGCommandDeleteOnHide", 0)
     set bufhidden=delete
   endif
 
   silent 0put=hgOut
 
   " The last command left a blank line at the end of the buffer.  If the
   " last line is folded (a side effect of the 'put') then the attempt to
   " remove the blank line will kill the last fold.
   "
   " This could be fixed by explicitly detecting whether the last line is
   " within a fold, but I prefer to simply unfold the result buffer altogether.
 
   if has('folding')
     normal zR
   endif
 
   $d
   1
 
   " Define the environment and execute user-defined hooks.
 
   let b:HGSourceFile=fileName
   let b:HGCommand=a:cmdName
   if a:statusText != ""
     let b:HGStatusText=a:statusText
   endif
 
   silent do HGCommand User HGBufferCreated
   return bufnr("%")
 endfunction
 
 " Function: s:HGBufferCheck(hgBuffer) {{{2
 " Attempts to locate the original file to which HG operations were applied
 " for a given buffer.
 
 function! s:HGBufferCheck(hgBuffer)
   let origBuffer = getbufvar(a:hgBuffer, "HGOrigBuffNR")
   if origBuffer
     if bufexists(origBuffer)
       return origBuffer
     else
       " Original buffer no longer exists.
       return -1 
     endif
   else
     " No original buffer
     return a:hgBuffer
   endif
 endfunction
 
 " Function: s:HGCurrentBufferCheck() {{{2
 " Attempts to locate the original file to which HG operations were applied
 " for the current buffer.
 
 function! s:HGCurrentBufferCheck()
   return s:HGBufferCheck(bufnr("%"))
 endfunction
 
 " Function: s:HGToggleDeleteOnHide() {{{2
 " Toggles on and off the delete-on-hide behavior of HG buffers
 
 function! s:HGToggleDeleteOnHide()
   if exists("g:HGCommandDeleteOnHide")
     unlet g:HGCommandDeleteOnHide
   else
     let g:HGCommandDeleteOnHide=1
   endif
 endfunction
 
 " Function: s:HGDoCommand(hgcmd, cmdName, statusText) {{{2
 " General skeleton for HG function execution.
 " Returns: name of the new command buffer containing the command results
 
 function! s:HGDoCommand(cmd, cmdName, statusText)
   let hgBufferCheck=s:HGCurrentBufferCheck()
   if hgBufferCheck == -1 
     echo "Original buffer no longer exists, aborting."
     return -1
   endif
 
   let fileName=bufname(hgBufferCheck)
   if isdirectory(fileName)
     let fileName=fileName . "/" . getline(".")
   endif
   let realFileName = fnamemodify(s:HGResolveLink(fileName), ':t')
   let oldCwd=s:HGChangeToCurrentFileDir(fileName)
   try
      " TODO
     "if !filereadable('HG/Root')
       "throw fileName . ' is not a HG-controlled file.'
     "endif
     let fullCmd = a:cmd . ' "' . realFileName . '"'
     "echomsg "DEBUG".fullCmd
     let resultBuffer=s:HGCreateCommandBuffer(fullCmd, a:cmdName, a:statusText, hgBufferCheck)
     return resultBuffer
   catch
     echoerr v:exception
     return -1
   finally
     execute 'cd' escape(oldCwd, ' ')
   endtry
 endfunction
 
 
 " Function: s:HGGetStatusVars(revision, branch, repository) {{{2
 "
 " Obtains a HG revision number and branch name.  The 'revisionVar',
 " 'branchVar'and 'repositoryVar' arguments, if non-empty, contain the names of variables to hold
 " the corresponding results.
 "
 " Returns: string to be exec'd that sets the multiple return values.
 
 function! s:HGGetStatusVars(revisionVar, branchVar, repositoryVar)
   let hgBufferCheck=s:HGCurrentBufferCheck()
   if hgBufferCheck == -1 
     return ""
   endif
   let fileName=bufname(hgBufferCheck)
   let realFileName = fnamemodify(s:HGResolveLink(fileName), ':t')
   let oldCwd=s:HGChangeToCurrentFileDir(fileName)
   try
      ""TODO
     "if !filereadable('HG/Root')
       "return ""
     "endif
     let hgCommand = s:HGGetOption("HGCommandHGExec", "hg") . " status -mardui " . fileName
     let statustext=system(hgCommand)
     if(v:shell_error)
       return ""
     endif
     if match(statustext, '^[?I]') >= 0 
       let revision="NEW"
     elseif match(statustext, '^[R]') >= 0 
       let revision="REMOVED"
     elseif match(statustext, '^[D]') >= 0 
       let revision="DELETED"
     elseif match(statustext, '^[A]') >= 0 
       let revision="ADDED"
     endif
 
     let hgCommand = s:HGGetOption("HGCommandHGExec", "hg") . " parents -b  " 
     let statustext=system(hgCommand)
     if(v:shell_error)
         return ""
     endif
     if exists('revision')
       let returnExpression = "let " . a:revisionVar . "='" . revision . "'"
     else
       let revision=substitute(statustext, '^changeset:\s*\(\d\+\):.*\_$\_.*$', '\1', "")
       let returnExpression = "let " . a:revisionVar . "='" . revision . "'"
     endif
 
     if a:branchVar != "" && match(statustext, '^\_.*\_^branch:') >= 0
       let branch=substitute(statustext, '^\_.*\_^branch:\s*\(\S\+\)\n\_.*$', '\1', "")
       let returnExpression=returnExpression . " | let " . a:branchVar . "='" . branch . "'"
     endif
     if a:repositoryVar != ""
       let hgCommand = s:HGGetOption("HGCommandHGExec", "hg") . " root  " 
       let roottext=system(hgCommand)
       let repository=substitute(roottext,'^.*/\([^/\n\r]*\)\n\_.*$','\1','')
       let returnExpression=returnExpression . " | let " . a:repositoryVar . "='" . repository . "'"
     endif
 
 
 
     return returnExpression
   finally
     execute 'cd' escape(oldCwd, ' ')
   endtry
 endfunction
 
 " Function: s:HGSetupBuffer() {{{2
 " Attempts to set the b:HGBranch, b:HGRevision and b:HGRepository variables.
 
 function! s:HGSetupBuffer()
   if (exists("b:HGBufferSetup") && b:HGBufferSetup)
     " This buffer is already set up.
     return
   endif
 
   if !s:HGGetOption("HGCommandEnableBufferSetup", 0)
         \ || @% == ""
         \ || s:HGCommandEditFileRunning > 0
         \ || exists("b:HGOrigBuffNR")
     unlet! b:HGRevision
     unlet! b:HGBranch
     unlet! b:HGRepository
     return
   endif
 
   if !filereadable(expand("%"))
     return -1
   endif
 
   let revision=""
   let branch=""
   let repository=""
 
   exec s:HGGetStatusVars('revision', 'branch', 'repository')
   "echomsg "DBG ".revision."#".branch."#".repository
   if revision != ""
     let b:HGRevision=revision
   else
     unlet! b:HGRevision
   endif
   if branch != ""
     let b:HGBranch=branch
   else
     unlet! b:HGBranch
   endif
   if repository != ""
      let b:HGRepository=repository
   else
      unlet! b:HGRepository
   endif
   silent do HGCommand User HGBufferSetup
   let b:HGBufferSetup=1
 endfunction
 
 " Function: s:HGMarkOrigBufferForSetup(hgbuffer) {{{2
 " Resets the buffer setup state of the original buffer for a given HG buffer.
 " Returns:  The HG buffer number in a passthrough mode.
 
 function! s:HGMarkOrigBufferForSetup(hgBuffer)
   checktime
   if a:hgBuffer != -1
     let origBuffer = s:HGBufferCheck(a:hgBuffer)
     "This should never not work, but I'm paranoid
     if origBuffer != a:hgBuffer
       call setbufvar(origBuffer, "HGBufferSetup", 0)
     endif
   endif
   return a:hgBuffer
 endfunction
 
 " Function: s:HGOverrideOption(option, [value]) {{{2
 " Provides a temporary override for the given HG option.  If no value is
 " passed, the override is disabled.
 
 function! s:HGOverrideOption(option, ...)
   if a:0 == 0
     unlet! s:{a:option}Override
   else
     let s:{a:option}Override = a:1
   endif
 endfunction
 
 " Function: s:HGWipeoutCommandBuffers() {{{2
 " Clears all current HG buffers of the specified type for a given source.
 
 function! s:HGWipeoutCommandBuffers(originalBuffer, hgCommand)
   let buffer = 1
   while buffer <= bufnr('$')
     if getbufvar(buffer, 'HGOrigBuffNR') == a:originalBuffer
       if getbufvar(buffer, 'HGCommand') == a:hgCommand
         execute 'bw' buffer
       endif
     endif
     let buffer = buffer + 1
   endwhile
 endfunction
 
+" Function: s:HGInstallDocumentation(full_name, revision)              {{{2
+"   Install help documentation.
+" Arguments:
+"   full_name: Full name of this vim plugin script, including path name.
+"   revision:  Revision of the vim script. #version# mark in the document file
+"              will be replaced with this string with 'v' prefix.
+" Return:
+"   1 if new document installed, 0 otherwise.
+" Note: Cleaned and generalized by guo-peng Wen
+"'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+function! s:HGInstallDocumentation(full_name, revision)
+    " Name of the document path based on the system we use:
+    if (has("unix"))
+        " On UNIX like system, using forward slash:
+        let l:slash_char = '/'
+        let l:mkdir_cmd  = ':silent !mkdir -p '
+    else
+        " On M$ system, use backslash. Also mkdir syntax is different.
+        " This should only work on W2K and up.
+        let l:slash_char = '\'
+        let l:mkdir_cmd  = ':silent !mkdir '
+    endif
+
+    let l:doc_path = l:slash_char . 'doc'
+    let l:doc_home = l:slash_char . '.vim' . l:slash_char . 'doc'
+
+    " Figure out document path based on full name of this script:
+    let l:vim_plugin_path = fnamemodify(a:full_name, ':h')
+    let l:vim_doc_path    = fnamemodify(a:full_name, ':h:h') . l:doc_path
+    if (!(filewritable(l:vim_doc_path) == 2))
+        echomsg "Doc path: " . l:vim_doc_path
+        execute l:mkdir_cmd . '"' . l:vim_doc_path . '"'
+        if (!(filewritable(l:vim_doc_path) == 2))
+            " Try a default configuration in user home:
+            let l:vim_doc_path = expand("~") . l:doc_home
+            if (!(filewritable(l:vim_doc_path) == 2))
+                execute l:mkdir_cmd . '"' . l:vim_doc_path . '"'
+                if (!(filewritable(l:vim_doc_path) == 2))
+                    " Put a warning:
+                    echomsg "Unable to open documentation directory"
+                    echomsg " type :help add-local-help for more informations."
+                    return 0
+                endif
+            endif
+        endif
+    endif
+
+    " Exit if we have problem to access the document directory:
+    if (!isdirectory(l:vim_plugin_path)
+        \ || !isdirectory(l:vim_doc_path)
+        \ || filewritable(l:vim_doc_path) != 2)
+        return 0
+    endif
+
+    " Full name of script and documentation file:
+    let l:script_name = fnamemodify(a:full_name, ':t')
+    let l:doc_name    = fnamemodify(a:full_name, ':t:r') . '.txt'
+    let l:plugin_file = l:vim_plugin_path . l:slash_char . l:script_name
+    let l:doc_file    = l:vim_doc_path    . l:slash_char . l:doc_name
+
+    " Bail out if document file is still up to date:
+    if (filereadable(l:doc_file)  &&
+        \ getftime(l:plugin_file) < getftime(l:doc_file))
+        return 0
+    endif
+
+    " Prepare window position restoring command:
+    if (strlen(@%))
+        let l:go_back = 'b ' . bufnr("%")
+    else
+        let l:go_back = 'enew!'
+    endif
+
+    " Create a new buffer & read in the plugin file (me):
+    setl nomodeline
+    exe 'enew!'
+    exe 'r ' . l:plugin_file
+
+    setl modeline
+    let l:buf = bufnr("%")
+    setl noswapfile modifiable
+
+    norm zR
+    norm gg
+
+    " Delete from first line to a line starts with
+    " === START_DOC
+    1,/^=\{3,}\s\+START_DOC\C/ d
+
+    " Delete from a line starts with
+    " === END_DOC
+    " to the end of the documents:
+    /^=\{3,}\s\+END_DOC\C/,$ d
+
+    " Remove fold marks:
+    %s/{\{3}[1-9]/    /
+
+    " Add modeline for help doc: the modeline string is mangled intentionally
+    " to avoid it be recognized by VIM:
+    call append(line('$'), '')
+    call append(line('$'), ' v' . 'im:tw=78:ts=8:ft=help:norl:')
+
+    " Replace revision:
+    exe "normal :1s/#version#/ v" . a:revision . "/\<CR>"
+
+    " Save the help document:
+    exe 'w! ' . l:doc_file
+    exe l:go_back
+    exe 'bw ' . l:buf
+
+    " Build help tags:
+    exe 'helptags ' . l:vim_doc_path
+
+    return 1
+endfunction
+
 " Section: Public functions {{{1
 
 " Function: HGGetRevision() {{{2
 " Global function for retrieving the current buffer's HG revision number.
 " Returns: Revision number or an empty string if an error occurs.
 
 function! HGGetRevision()
   let revision=""
   exec s:HGGetStatusVars('revision', '', '')
   return revision
 endfunction
 
 " Function: HGDisableBufferSetup() {{{2
 " Global function for deactivating the buffer autovariables.
 
 function! HGDisableBufferSetup()
   let g:HGCommandEnableBufferSetup=0
   silent! augroup! HGCommandPlugin
 endfunction
 
 " Function: HGEnableBufferSetup() {{{2
 " Global function for activating the buffer autovariables.
 
 function! HGEnableBufferSetup()
   let g:HGCommandEnableBufferSetup=1
   augroup HGCommandPlugin
     au!
     au BufEnter * call s:HGSetupBuffer()
   augroup END
 
   " Only auto-load if the plugin is fully loaded.  This gives other plugins a
   " chance to run.
   if g:loaded_hgcommand == 2
     call s:HGSetupBuffer()
   endif
 endfunction
 
 " Function: HGGetStatusLine() {{{2
 " Default (sample) status line entry for HG files.  This is only useful if
 " HG-managed buffer mode is on (see the HGCommandEnableBufferSetup variable
 " for how to do this).
 
 function! HGGetStatusLine()
   if exists('b:HGSourceFile')
     " This is a result buffer
     let value='[' . b:HGCommand . ' ' . b:HGSourceFile
     if exists('b:HGStatusText')
       let value=value . ' ' . b:HGStatusText
     endif
     let value = value . ']'
     return value
   endif
 
   if exists('b:HGRevision')
         \ && b:HGRevision != ''
         \ && exists('b:HGBranch')
         \ && b:HGBranch != ''
         \ && exists('b:HGRepository')
         \ && b:HGRepository != ''
         \ && exists('g:HGCommandEnableBufferSetup')
         \ && g:HGCommandEnableBufferSetup
    return '[HG ' . b:HGRepository . '/' . b:HGBranch .'/' . b:HGRevision . ']'
   else
     return ''
   endif
 endfunction
 
 " Section: HG command functions {{{1
 
 " Function: s:HGAdd() {{{2
 function! s:HGAdd()
   return s:HGMarkOrigBufferForSetup(s:HGDoCommand('add', 'hgadd', ''))
 endfunction
 
 " Function: s:HGAnnotate(...) {{{2
 function! s:HGAnnotate(...)
   if a:0 == 0
     if &filetype == "HGAnnotate"
       " This is a HGAnnotate buffer.  Perform annotation of the version
       " indicated by the current line.
       let revision = substitute(getline("."),'\(^[0-9]*\):.*','\1','')
       if s:HGGetOption('HGCommandAnnotateParent', 0) != 0 && revision > 0
         let revision = revision - 1
       endif
     else
       let revision=HGGetRevision()
       if revision == ""
         echoerr "Unable to obtain HG version information."
         return -1
       endif
     endif
   else
     let revision=a:1
   endif
 
   if revision == "NEW"
     echo "No annotatation available for new file."
     return -1
   endif
 
   let resultBuffer=s:HGDoCommand('annotate -ndu -r ' . revision, 'hgannotate', revision) 
   echomsg "DBG: ".resultBuffer
   if resultBuffer !=  -1
     set filetype=HGAnnotate
   endif
 
   return resultBuffer
 endfunction
 
 " Function: s:HGCommit() {{{2
 function! s:HGCommit(...)
   " Handle the commit message being specified.  If a message is supplied, it
   " is used; if bang is supplied, an empty message is used; otherwise, the
   " user is provided a buffer from which to edit the commit message.
   if a:2 != "" || a:1 == "!"
     return s:HGMarkOrigBufferForSetup(s:HGDoCommand('commit -m "' . a:2 . '"', 'hgcommit', ''))
   endif
 
   let hgBufferCheck=s:HGCurrentBufferCheck()
   if hgBufferCheck ==  -1
     echo "Original buffer no longer exists, aborting."
     return -1
   endif
 
   " Protect against windows' backslashes in paths.  They confuse exec'd
   " commands.
 
   let shellSlashBak = &shellslash
   try
     set shellslash
 
     let messageFileName = tempname()
 
     let fileName=bufname(hgBufferCheck)
     let realFilePath=s:HGResolveLink(fileName)
     let newCwd=fnamemodify(realFilePath, ':h')
     if strlen(newCwd) == 0
       " Account for autochdir being in effect, which will make this blank, but
       " we know we'll be in the current directory for the original file.
       let newCwd = getcwd()
     endif
 
     let realFileName=fnamemodify(realFilePath, ':t')
 
     if s:HGEditFile(messageFileName, hgBufferCheck) == -1
       return
     endif
 
     " Protect against case and backslash issues in Windows.
     let autoPattern = '\c' . messageFileName
 
     " Ensure existance of group
     augroup HGCommit
     augroup END
 
     execute 'au HGCommit BufDelete' autoPattern 'call delete("' . messageFileName . '")'
     execute 'au HGCommit BufDelete' autoPattern 'au! HGCommit * ' autoPattern
 
     " Create a commit mapping.  The mapping must clear all autocommands in case
     " it is invoked when HGCommandCommitOnWrite is active, as well as to not
     " invoke the buffer deletion autocommand.
 
     execute 'nnoremap <silent> <buffer> <Plug>HGCommit '.
           \ ':au! HGCommit * ' . autoPattern . '<CR>'.
           \ ':g/^HG:/d<CR>'.
           \ ':update<CR>'.
           \ ':call <SID>HGFinishCommit("' . messageFileName . '",' .
           \                             '"' . newCwd . '",' .
           \                             '"' . realFileName . '",' .
           \                             hgBufferCheck . ')<CR>'
 
     silent 0put ='HG: ----------------------------------------------------------------------'
     silent put =\"HG: Enter Log.  Lines beginning with `HG:' are removed automatically\"
     silent put ='HG: Type <leader>cc (or your own <Plug>HGCommit mapping)'
 
     if s:HGGetOption('HGCommandCommitOnWrite', 1) == 1
       execute 'au HGCommit BufWritePre' autoPattern 'g/^HG:/d'
       execute 'au HGCommit BufWritePost' autoPattern 'call s:HGFinishCommit("' . messageFileName . '", "' . newCwd . '", "' . realFileName . '", ' . hgBufferCheck . ') | au! * ' autoPattern
       silent put ='HG: or write this buffer'
     endif
 
     silent put ='HG: to finish this commit operation'
     silent put ='HG: ----------------------------------------------------------------------'
     $
     let b:HGSourceFile=fileName
     let b:HGCommand='HGCommit'
     set filetype=hg
   finally
     let &shellslash = shellSlashBak
   endtry
 
 endfunction
 
 " Function: s:HGDiff(...) {{{2
 function! s:HGDiff(...)
   if a:0 == 1
     let revOptions = '-r' . a:1
     let caption = a:1 . ' -> current'
   elseif a:0 == 2
     let revOptions = '-r' . a:1 . ' -r' . a:2
     let caption = a:1 . ' -> ' . a:2
   else
     let revOptions = ''
     let caption = ''
   endif
 
   let hgdiffopt=s:HGGetOption('HGCommandDiffOpt', 'w')
 
   if hgdiffopt == ""
     let diffoptionstring=""
   else
     let diffoptionstring=" -" . hgdiffopt . " "
   endif
 
   let resultBuffer = s:HGDoCommand('diff ' . diffoptionstring . revOptions , 'hgdiff', caption)
   if resultBuffer != -1 
     set filetype=diff
   endif
   return resultBuffer
 endfunction
 
 
 " Function: s:HGGotoOriginal(["!]) {{{2
 function! s:HGGotoOriginal(...)
   let origBuffNR = s:HGCurrentBufferCheck()
   if origBuffNR > 0
     let origWinNR = bufwinnr(origBuffNR)
     if origWinNR == -1
       execute 'buffer' origBuffNR
     else
       execute origWinNR . 'wincmd w'
     endif
     if a:0 == 1
       if a:1 == "!"
         let buffnr = 1
         let buffmaxnr = bufnr("$")
         while buffnr <= buffmaxnr
           if getbufvar(buffnr, "HGOrigBuffNR") == origBuffNR
             execute "bw" buffnr
           endif
           let buffnr = buffnr + 1
         endwhile
       endif
     endif
   endif
 endfunction
 
 " Function: s:HGFinishCommit(messageFile, targetDir, targetFile) {{{2
 function! s:HGFinishCommit(messageFile, targetDir, targetFile, origBuffNR)
   if filereadable(a:messageFile)
     let oldCwd=getcwd()
     if strlen(a:targetDir) > 0
       execute 'cd' escape(a:targetDir, ' ')
     endif
     let resultBuffer=s:HGCreateCommandBuffer('commit -F "' . a:messageFile . '" "'. a:targetFile . '"', 'hgcommit', '', a:origBuffNR)
     execute 'cd' escape(oldCwd, ' ')
     execute 'bw' escape(a:messageFile, ' *?\')
     silent execute 'call delete("' . a:messageFile . '")'
     return s:HGMarkOrigBufferForSetup(resultBuffer)
   else
     echoerr "Can't read message file; no commit is possible."
     return -1
   endif
 endfunction
 
 " Function: s:HGLog() {{{2
 function! s:HGLog(...)
   if a:0 == 0
     let versionOption = ""
     let caption = ''
   else
     let versionOption=" -r" . a:1
     let caption = a:1
   endif
 
   let resultBuffer=s:HGDoCommand('log' . versionOption, 'hglog', caption)
   if resultBuffer != ""
     set filetype=rcslog
   endif
   return resultBuffer
 endfunction
 
 " Function: s:HGRevert() {{{2
 function! s:HGRevert()
   return s:HGMarkOrigBufferForSetup(s:HGDoCommand('revert', 'hgrevert', ''))
 endfunction
 
 " Function: s:HGReview(...) {{{2
 function! s:HGReview(...)
   if a:0 == 0
     let versiontag=""
     if s:HGGetOption('HGCommandInteractive', 0)
       let versiontag=input('Revision:  ')
     endif
     if versiontag == ""
       let versiontag="(current)"
       let versionOption=""
     else
       let versionOption=" -r " . versiontag . " "
     endif
   else
     let versiontag=a:1
     let versionOption=" -r " . versiontag . " "
   endif
 
   let resultBuffer = s:HGDoCommand('cat' . versionOption, 'hgreview', versiontag)
   if resultBuffer > 0
     let &filetype=getbufvar(b:HGOrigBuffNR, '&filetype')
   endif
 
   return resultBuffer
 endfunction
 
 " Function: s:HGStatus() {{{2
 function! s:HGStatus()
   return s:HGDoCommand('status', 'hgstatus', '')
 endfunction
 
 
 " Function: s:HGUpdate() {{{2
 function! s:HGUpdate()
   return s:HGMarkOrigBufferForSetup(s:HGDoCommand('update', 'update', ''))
 endfunction
 
 " Function: s:HGVimDiff(...) {{{2
 function! s:HGVimDiff(...)
   let originalBuffer = s:HGCurrentBufferCheck()
   let s:HGCommandEditFileRunning = s:HGCommandEditFileRunning + 1
   try
     " If there's already a VimDiff'ed window, restore it.
     " There may only be one HGVimDiff original window at a time.
 
     if exists("s:vimDiffSourceBuffer") && s:vimDiffSourceBuffer != originalBuffer
       " Clear the existing vimdiff setup by removing the result buffers.
       call s:HGWipeoutCommandBuffers(s:vimDiffSourceBuffer, 'vimdiff')
     endif
 
     " Split and diff
     if(a:0 == 2)
       " Reset the vimdiff system, as 2 explicit versions were provided.
       if exists('s:vimDiffSourceBuffer')
         call s:HGWipeoutCommandBuffers(s:vimDiffSourceBuffer, 'vimdiff')
       endif
       let resultBuffer = s:HGReview(a:1)
       if resultBuffer < 0
         echomsg "Can't open HG revision " . a:1
         return resultBuffer
       endif
       let b:HGCommand = 'vimdiff'
       diffthis
       let s:vimDiffBufferCount = 1
       let s:vimDiffScratchList = '{'. resultBuffer . '}'
       " If no split method is defined, cheat, and set it to vertical.
       try
         call s:HGOverrideOption('HGCommandSplit', s:HGGetOption('HGCommandDiffSplit', s:HGGetOption('HGCommandSplit', 'vertical')))
         let resultBuffer=s:HGReview(a:2)
       finally
         call s:HGOverrideOption('HGCommandSplit')
       endtry
       if resultBuffer < 0
         echomsg "Can't open HG revision " . a:1
         return resultBuffer
       endif
       let b:HGCommand = 'vimdiff'
       diffthis
       let s:vimDiffBufferCount = 2
       let s:vimDiffScratchList = s:vimDiffScratchList . '{'. resultBuffer . '}'
     else
       " Add new buffer
       try
         " Force splitting behavior, otherwise why use vimdiff?
         call s:HGOverrideOption("HGCommandEdit", "split")
         call s:HGOverrideOption("HGCommandSplit", s:HGGetOption('HGCommandDiffSplit', s:HGGetOption('HGCommandSplit', 'vertical')))
         if(a:0 == 0)
           let resultBuffer=s:HGReview()
         else
           let resultBuffer=s:HGReview(a:1)
         endif
       finally
         call s:HGOverrideOption("HGCommandEdit")
         call s:HGOverrideOption("HGCommandSplit")
       endtry
       if resultBuffer < 0
         echomsg "Can't open current HG revision"
         return resultBuffer
       endif
       let b:HGCommand = 'vimdiff'
       diffthis
 
       if !exists('s:vimDiffBufferCount')
         " New instance of vimdiff.
         let s:vimDiffBufferCount = 2
         let s:vimDiffScratchList = '{' . resultBuffer . '}'
 
         " This could have been invoked on a HG result buffer, not the
         " original buffer.
         wincmd W
         execute 'buffer' originalBuffer
         " Store info for later original buffer restore
         let s:vimDiffRestoreCmd = 
               \    "call setbufvar(".originalBuffer.", \"&diff\", ".getbufvar(originalBuffer, '&diff').")"
               \ . "|call setbufvar(".originalBuffer.", \"&foldcolumn\", ".getbufvar(originalBuffer, '&foldcolumn').")"
               \ . "|call setbufvar(".originalBuffer.", \"&foldenable\", ".getbufvar(originalBuffer, '&foldenable').")"
               \ . "|call setbufvar(".originalBuffer.", \"&foldmethod\", '".getbufvar(originalBuffer, '&foldmethod')."')"
               \ . "|call setbufvar(".originalBuffer.", \"&scrollbind\", ".getbufvar(originalBuffer, '&scrollbind').")"
               \ . "|call setbufvar(".originalBuffer.", \"&wrap\", ".getbufvar(originalBuffer, '&wrap').")"
               \ . "|if &foldmethod=='manual'|execute 'normal zE'|endif"
         diffthis
         wincmd w
       else
         " Adding a window to an existing vimdiff
         let s:vimDiffBufferCount = s:vimDiffBufferCount + 1
         let s:vimDiffScratchList = s:vimDiffScratchList . '{' . resultBuffer . '}'
       endif
     endif
 
     let s:vimDiffSourceBuffer = originalBuffer
 
     " Avoid executing the modeline in the current buffer after the autocommand.
 
     let currentBuffer = bufnr('%')
     let saveModeline = getbufvar(currentBuffer, '&modeline')
     try
       call setbufvar(currentBuffer, '&modeline', 0)
       silent do HGCommand User HGVimDiffFinish
     finally
       call setbufvar(currentBuffer, '&modeline', saveModeline)
     endtry
     return resultBuffer
   finally
     let s:HGCommandEditFileRunning = s:HGCommandEditFileRunning - 1
   endtry
 endfunction
 
 " Section: Command definitions {{{1
 " Section: Primary commands {{{2
 com! HGAdd call s:HGAdd()
 com! -nargs=? HGAnnotate call s:HGAnnotate(<f-args>)
 com! -bang -nargs=? HGCommit call s:HGCommit(<q-bang>, <q-args>)
 com! -nargs=* HGDiff call s:HGDiff(<f-args>)
 com! -bang HGGotoOriginal call s:HGGotoOriginal(<q-bang>)
 com! -nargs=? HGLog call s:HGLog(<f-args>)
 com! HGRevert call s:HGRevert()
 com! -nargs=? HGReview call s:HGReview(<f-args>)
 com! HGStatus call s:HGStatus()
 com! HGUpdate call s:HGUpdate()
 com! -nargs=* HGVimDiff call s:HGVimDiff(<f-args>)
 
 " Section: HG buffer management commands {{{2
 com! HGDisableBufferSetup call HGDisableBufferSetup()
 com! HGEnableBufferSetup call HGEnableBufferSetup()
 
 " Allow reloading hgcommand.vim
 com! HGReload unlet! loaded_hgcommand | runtime plugin/hgcommand.vim
 
 " Section: Plugin command mappings {{{1
 nnoremap <silent> <Plug>HGAdd :HGAdd<CR>
 nnoremap <silent> <Plug>HGAnnotate :HGAnnotate<CR>
 nnoremap <silent> <Plug>HGCommit :HGCommit<CR>
 nnoremap <silent> <Plug>HGDiff :HGDiff<CR>
 nnoremap <silent> <Plug>HGGotoOriginal :HGGotoOriginal<CR>
 nnoremap <silent> <Plug>HGClearAndGotoOriginal :HGGotoOriginal!<CR>
 nnoremap <silent> <Plug>HGLog :HGLog<CR>
 nnoremap <silent> <Plug>HGRevert :HGRevert<CR>
 nnoremap <silent> <Plug>HGReview :HGReview<CR>
 nnoremap <silent> <Plug>HGStatus :HGStatus<CR>
 nnoremap <silent> <Plug>HGUpdate :HGUpdate<CR>
 nnoremap <silent> <Plug>HGVimDiff :HGVimDiff<CR>
 nnoremap <silent> <Plug>HGWatchers :HGWatchers<CR>
 nnoremap <silent> <Plug>HGWatchAdd :HGWatchAdd<CR>
 nnoremap <silent> <Plug>HGWatchOn :HGWatchOn<CR>
 nnoremap <silent> <Plug>HGWatchOff :HGWatchOff<CR>
 nnoremap <silent> <Plug>HGWatchRemove :HGWatchRemove<CR>
 
 " Section: Default mappings {{{1
 if !hasmapto('<Plug>HGAdd')
   nmap <unique> <Leader>hga <Plug>HGAdd
 endif
 if !hasmapto('<Plug>HGAnnotate')
   nmap <unique> <Leader>hgn <Plug>HGAnnotate
 endif
 if !hasmapto('<Plug>HGClearAndGotoOriginal')
   nmap <unique> <Leader>hgG <Plug>HGClearAndGotoOriginal
 endif
 if !hasmapto('<Plug>HGCommit')
   nmap <unique> <Leader>hgc <Plug>HGCommit
 endif
 if !hasmapto('<Plug>HGDiff')
   nmap <unique> <Leader>hgd <Plug>HGDiff
 endif
 if !hasmapto('<Plug>HGGotoOriginal')
   nmap <unique> <Leader>hgg <Plug>HGGotoOriginal
 endif
 if !hasmapto('<Plug>HGLog')
   nmap <unique> <Leader>hgl <Plug>HGLog
 endif
 if !hasmapto('<Plug>HGRevert')
   nmap <unique> <Leader>hgq <Plug>HGRevert
 endif
 if !hasmapto('<Plug>HGReview')
   nmap <unique> <Leader>hgr <Plug>HGReview
 endif
 if !hasmapto('<Plug>HGStatus')
   nmap <unique> <Leader>hgs <Plug>HGStatus
 endif
 if !hasmapto('<Plug>HGUpdate')
   nmap <unique> <Leader>hgu <Plug>HGUpdate
 endif
 if !hasmapto('<Plug>HGVimDiff')
   nmap <unique> <Leader>hgv <Plug>HGVimDiff
 endif
 
 " Section: Menu items {{{1
 silent! aunmenu Plugin.HG
 amenu <silent> &Plugin.HG.&Add        <Plug>HGAdd
 amenu <silent> &Plugin.HG.A&nnotate   <Plug>HGAnnotate
 amenu <silent> &Plugin.HG.&Commit     <Plug>HGCommit
 amenu <silent> &Plugin.HG.&Diff       <Plug>HGDiff
 amenu <silent> &Plugin.HG.&Log        <Plug>HGLog
 amenu <silent> &Plugin.HG.Revert      <Plug>HGRevert
 amenu <silent> &Plugin.HG.&Review     <Plug>HGReview
 amenu <silent> &Plugin.HG.&Status     <Plug>HGStatus
 amenu <silent> &Plugin.HG.&Update     <Plug>HGUpdate
 amenu <silent> &Plugin.HG.&VimDiff    <Plug>HGVimDiff
 amenu <silent> &Plugin.HG.&Watchers   <Plug>HGWatchers
 amenu <silent> &Plugin.HG.WatchAdd    <Plug>HGWatchAdd
 amenu <silent> &Plugin.HG.WatchOn     <Plug>HGWatchOn
 amenu <silent> &Plugin.HG.WatchOff    <Plug>HGWatchOff
 amenu <silent> &Plugin.HG.WatchRemove <Plug>HGWatchRemove
 
 " Section: Autocommands to restore vimdiff state {{{1
 function! s:HGVimDiffRestore(vimDiffBuff)
   let s:HGCommandEditFileRunning = s:HGCommandEditFileRunning + 1
   try
     if exists("s:vimDiffSourceBuffer")
       if a:vimDiffBuff == s:vimDiffSourceBuffer
         " Original file is being removed.
         unlet! s:vimDiffSourceBuffer
         unlet! s:vimDiffBufferCount
         unlet! s:vimDiffRestoreCmd
         unlet! s:vimDiffScratchList
       elseif match(s:vimDiffScratchList, '{' . a:vimDiffBuff . '}') >= 0
         let s:vimDiffScratchList = substitute(s:vimDiffScratchList, '{' . a:vimDiffBuff . '}', '', '')
         let s:vimDiffBufferCount = s:vimDiffBufferCount - 1
         if s:vimDiffBufferCount == 1 && exists('s:vimDiffRestoreCmd')
           " All scratch buffers are gone, reset the original.
           " Only restore if the source buffer is still in Diff mode
 
           let sourceWinNR=bufwinnr(s:vimDiffSourceBuffer)
           if sourceWinNR != -1
             " The buffer is visible in at least one window
             let currentWinNR = winnr()
             while winbufnr(sourceWinNR) != -1
               if winbufnr(sourceWinNR) == s:vimDiffSourceBuffer
                 execute sourceWinNR . 'wincmd w'
                 if getwinvar('', "&diff")
                   execute s:vimDiffRestoreCmd
                 endif
               endif
               let sourceWinNR = sourceWinNR + 1
             endwhile
             execute currentWinNR . 'wincmd w'
           else
             " The buffer is hidden.  It must be visible in order to set the
             " diff option.
             let currentBufNR = bufnr('')
             execute "hide buffer" s:vimDiffSourceBuffer
             if getwinvar('', "&diff")
               execute s:vimDiffRestoreCmd
             endif
             execute "hide buffer" currentBufNR
           endif
 
           unlet s:vimDiffRestoreCmd
           unlet s:vimDiffSourceBuffer
           unlet s:vimDiffBufferCount
           unlet s:vimDiffScratchList
         elseif s:vimDiffBufferCount == 0
           " All buffers are gone.
           unlet s:vimDiffSourceBuffer
           unlet s:vimDiffBufferCount
           unlet s:vimDiffScratchList
         endif
       endif
     endif
   finally
     let s:HGCommandEditFileRunning = s:HGCommandEditFileRunning - 1
   endtry
 endfunction
 
 augroup HGVimDiffRestore
   au!
   au BufUnload * call s:HGVimDiffRestore(expand("<abuf>"))
 augroup END
 
 " Section: Optional activation of buffer management {{{1
 
 if s:HGGetOption('HGCommandEnableBufferSetup', 0)
   call HGEnableBufferSetup()
 endif
 
+" Section: Doc installation {{{1
+"
+  let s:revision="0.1"
+  silent! let s:install_status =
+      \ s:HGInstallDocumentation(expand('<sfile>:p'), s:revision)
+  if (s:install_status == 1)
+      echom expand("<sfile>:t:r") . ' v' . s:revision .
+		\ ': Help-documentation installed.'
+  endif
+
+
 " Section: Plugin completion {{{1
 
 let loaded_hgcommand=2
 silent do HGCommand User HGPluginFinish
 " vim:se expandtab sts=2 sw=2:
+finish
+
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+" Section: Documentation content                                          {{{1
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+=== START_DOC
+*hgcommand.txt*	  Mercurial vim integration		             #version#
+
+
+			 HGCOMMAND REFERENCE MANUAL~
+
+
+Author:  Mathieu Clabaut <[e-mail]>
+Credits:  Bob Hiestand <[e-mail]>
+Mercurial: http://www.selenic.com/mercurial
+   Mercurial (noted Hg) is a fast, lightweight Source Control Management
+   system designed for efficient handling of very large distributed projects.
+
+==============================================================================
+1. Contents						*hgcommand-contents*
+
+	Installation		: |hgcommand-install|
+        HGCommand Intro	        : |hgcommand|
+	HGCommand Manual	: |hgcommand-manual|
+	Customization		: |hgcommand-customize|
+	SSH "integration"	: |hgcommand-ssh|
+	Bugs			: |hgcommand-bugs|
+
+==============================================================================
+                                                           *hgcommand-install*
+2. HGCommand Installation				
+
+   In order to install the plugin, place the hgcommand.vim file into a plugin' 
+   directory in your runtime path (please see |add-global-plugin| and 
+   |'runtimepath'|.
+
+   HGCommand may be customized by setting variables, creating maps, and 
+   specifying event handlers.  Please see |hgcommand-customize| for more
+   details.
+
+                                                         *hgcommand-auto-help*
+   The help file is automagically generated when the |vimspell| script is 
+   loaded for the first time.
+
+==============================================================================
+
+3. HGCommand Intro					*hgcommand*
+							*hgcommand-intro*
+
+The HGCommand plugin provides global ex commands for manipulating
+HG-controlled source files.  In general, each command operates on the current
+buffer and accomplishes a separate hg function, such as update, commit, log,
+and others (please see |hgcommand-commands| for a list of all available
+commands).  The results of each operation are displayed in a scratch buffer.
+Several buffer variables are defined for those scratch buffers (please see
+|hgcommand-buffer-variables|).
+
+The notion of "current file" means either the current buffer, or, in the case
+of a directory buffer, the file on the current line within the buffer.
+
+For convenience, any HGCommand invoked on a HGCommand scratch buffer acts as
+though it was invoked on the original file and splits the screen so that the
+output appears in a new window.
+
+Many of the commands accept revisions as arguments.  By default, most operate
+on the most recent revision on the current branch if no revision is specified
+(though see |HGCommandInteractive| to prompt instead).
+
+Each HGCommand is mapped to a key sequence starting with the <Leader>
+keystroke.  The default mappings may be overridden by supplying different
+mappings before the plugin is loaded, such as in the vimrc, in the standard
+fashion for plugin mappings.  For examples, please see
+|hgcommand-mappings-override|.
+
+The HGCommand plugin may be configured in several ways.  For more details,
+please see |hgcommand-customize|.
+
+==============================================================================
+
+4. HGCommand Manual					*hgcommand-manual*
+
+4.1 HGCommand commands					*hgcommand-commands*
+
+HGCommand defines the following commands:
+
+|:HGAdd|
+|:HGAnnotate|
+|:HGCommit|
+|:HGDiff|
+|:HGGotoOriginal|
+|:HGLog|
+|:HGRevert|
+|:HGReview|
+|:HGStatus|
+|:HGUnedit|
+|:HGUpdate|
+|:HGVimDiff|
+
+:HGAdd							*:HGAdd*
+
+This command performs "hg add" on the current file.  Please note, this does
+not commit the newly-added file.
+
+:HGAnnotate						*:HGAnnotate*
+
+This command performs "hg annotate" on the current file.  If an argument is
+given, the argument is used as a revision number to display.  If not given an
+argument, it uses the most recent version of the file on the current branch.
+Additionally, if the current buffer is a HGAnnotate buffer already, the
+version number on the current line is used.
+
+If the |HGCommandAnnotateParent| variable is set to a non-zero value, the
+version previous to the one on the current line is used instead.  This allows
+one to navigate back to examine the previous version of a line.
+
+The filetype of the HGCommand scratch buffer is set to 'HGAnnotate', to take
+advantage of the bundled syntax file.
+
+
+:HGCommit[!]						*:HGCommit*
+
+If called with arguments, this performs "hg commit" using the arguments as
+the log message.
+
+If '!' is used with no arguments, an empty log message is committed.
+
+If called with no arguments, this is a two-step command.  The first step opens
+a buffer to accept a log message.  When that buffer is written, it is
+automatically closed and the file is committed using the information from that
+log message.  The commit can be abandoned if the log message buffer is deleted
+or wiped before being written.
+
+Alternatively, the mapping that is used to invoke :HGCommit (by default
+<Leader>hgc) can be used in the log message buffer to immediately commit.  
+This
+is useful if the |HGCommandCommitOnWrite| variable is set to 0 to disable the
+normal commit-on-write behavior.
+
+:HGDiff						*:HGDiff*
+
+With no arguments, this performs "hg diff" on the current file against the
+current repository version.
+
+With one argument, "hg diff" is performed on the current file against the
+specified revision.
+
+With two arguments, hg diff is performed between the specified
+revisions of the current file.
+
+This command uses the 'HGCommandDiffOpt' variable to specify diff options.
+If that variable does not exist, then 'wbBc' is assumed.  If you wish to have
+no options, then set it to the empty string.
+
+
+This command performs "hg edit" on the current file.
+
+:HGGotoOriginal					*:HGGotoOriginal*
+
+This command returns the current window to the source buffer, if the current
+buffer is a HG command output buffer.
+
+:HGGotoOriginal!
+
+Like ":HGGotoOriginal" but also executes :bufwipeout on all HG command
+output buffers for the source buffer.
+
+:HGLog							*:HGLog*
+
+Performs "hg log" on the current file.
+
+If an argument is given, it is passed as an argument to the "-r" option of
+"hg log".
+
+:HGRevert						*:HGRevert*
+
+Replaces the current file with the most recent version from the repository in
+order to wipe out any undesired changes.
+
+:HGReview						*:HGReview*
+
+Retrieves a particular version of the current file.  If no argument is given,
+the most recent version of the file on the current branch is retrieved.
+Otherwise, the specified version is retrieved.
+
+:HGStatus						*:HGStatus*
+
+Performs "hg status" on the current file.
+
+:HGUnedit						*:HGUnedit*
+
+Performs "hg unedit" on the current file.  Again, yes, the output buffer here
+is basically useless.
+
+:HGUpdate						*:HGUpdate*
+
+Performs "hg update" on the current file.  This intentionally does not
+automatically reload the current buffer, though vim should prompt the user to
+do so if the underlying file is altered by this command.
+
+:HGVimDiff						*:HGVimDiff*
+
+With no arguments, this prompts the user for a revision and then uses vimdiff
+to display the differences between the current file and the specified
+revision.  If no revision is specified, the most recent version of the file on
+the current branch is used.
+
+With one argument, that argument is used as the revision as above.  With two
+arguments, the differences between the two revisions is displayed using
+vimdiff.
+
+With either zero or one argument, the original buffer is used to perform the
+vimdiff.  When the other buffer is closed, the original buffer will be
+returned to normal mode.
+
+Once vimdiff mode is started using the above methods, additional vimdiff
+buffers may be added by passing a single version argument to the command.
+There may be up to 4 vimdiff buffers total.
+
+Using the 2-argument form of the command resets the vimdiff to only those 2
+versions.  Additionally, invoking the command on a different file will close
+the previous vimdiff buffers.
+
+
+4.2 Mappings						*hgcommand-mappings*
+
+By default, a mapping is defined for each command.  These mappings execute the
+default (no-argument) form of each command.
+
+<Leader>hga HGAdd
+<Leader>hgn HGAnnotate
+<Leader>hgc HGCommit
+<Leader>hgd HGDiff
+<Leader>hgg HGGotoOriginal
+<Leader>hgG HGGotoOriginal!
+<Leader>hgl HGLog
+<Leader>hgr HGReview
+<Leader>hgs HGStatus
+<Leader>hgt HGUnedit
+<Leader>hgu HGUpdate
+<Leader>hgv HGVimDiff
+
+						*hgcommand-mappings-override*
+
+The default mappings can be overriden by user-provided instead by mapping to
+<Plug>CommandName.  This is especially useful when these mappings collide with
+other existing mappings (vim will warn of this during plugin initialization,
+but will not clobber the existing mappings).
+
+For instance, to override the default mapping for :HGAdd to set it to '\add',
+add the following to the vimrc:
+
+nmap \add <Plug>HGAdd
+
+4.3 Automatic buffer variables			*hgcommand-buffer-variables*
+
+Several buffer variables are defined in each HGCommand result buffer.	These
+may be useful for additional customization in callbacks defined in the event
+handlers (please see |hgcommand-events|).
+
+The following variables are automatically defined:
+
+b:hgOrigBuffNR						*b:hgOrigBuffNR*
+
+This variable is set to the buffer number of the source file.
+
+b:hgcmd						*b:hgcmd*
+
+This variable is set to the name of the hg command that created the result
+buffer.
+==============================================================================
+
+5. Configuration and customization			*hgcommand-customize*
+							*hgcommand-config*
+
+The HGCommand plugin can be configured in two ways:  by setting configuration
+variables (see |hgcommand-options|) or by defining HGCommand event handlers
+(see |hgcommand-events|).  Additionally, the HGCommand plugin provides
+several option for naming the HG result buffers (see |hgcommand-naming|) and
+supported a customized status line (see |hgcommand-statusline| and
+|hgcommand-buffer-management|).
+
+5.1 HGCommand configuration variables			*hgcommand-options*
+
+Several variables affect the plugin's behavior.  These variables are checked
+at time of execution, and may be defined at the window, buffer, or global
+level and are checked in that order of precedence.
+
+
+The following variables are available:
+
+|HGCommandAnnotateParent|
+|HGCommandCommitOnWrite|
+|HGCommandHGExec|
+|HGCommandDeleteOnHide|
+|HGCommandDiffOpt|
+|HGCommandDiffSplit|
+|HGCommandEdit|
+|HGCommandEnableBufferSetup|
+|HGCommandInteractive|
+|HGCommandNameMarker|
+|HGCommandNameResultBuffers|
+|HGCommandSplit|
+
+HGCommandAnnotateParent			*HGCommandAnnotateParent*
+
+This variable, if set to a non-zero value, causes the zero-argument form of
+HGAnnotate when invoked on a HGAnnotate buffer to go to the version previous
+to that displayed on the current line.  If not set, it defaults to 0.
+
+HGCommandCommitOnWrite				*HGCommandCommitOnWrite*
+
+This variable, if set to a non-zero value, causes the pending hg commit
+to take place immediately as soon as the log message buffer is written.
+If set to zero, only the HGCommit mapping will cause the pending commit to
+occur.	If not set, it defaults to 1.
+
+HGCommandHGExec				*HGCommandHGExec*
+
+This variable controls the executable used for all HG commands  If not set,
+it defaults to "hg".
+
+HGCommandDeleteOnHide				*HGCommandDeleteOnHide*
+
+This variable, if set to a non-zero value, causes the temporary HG result
+buffers to automatically delete themselves when hidden.
+
+HGCommandDiffOpt				*HGCommandDiffOpt*
+
+This variable, if set, determines the options passed to the diff command of
+HG.  If not set, it defaults to 'wbBc'.
+
+HGCommandDiffSplit				*HGCommandDiffSplit*
+
+This variable overrides the |HGCommandSplit| variable, but only for buffers
+created with |:HGVimDiff|.
+
+HGCommandEdit					*HGCommandEdit*
+
+This variable controls whether the original buffer is replaced ('edit') or
+split ('split').  If not set, it defaults to 'edit'.
+
+HGCommandEnableBufferSetup			*HGCommandEnableBufferSetup*
+
+This variable, if set to a non-zero value, activates HG buffer management
+mode see (|hgcommand-buffer-management|).  This mode means that two buffer
+variables, 'HGRevision' and 'HGBranch', are set if the file is
+HG-controlled.  This is useful for displaying version information in the
+status bar.
+
+HGCommandInteractive				*HGCommandInteractive*
+
+This variable, if set to a non-zero value, causes appropriate commands (for
+the moment, only |:HGReview|) to query the user for a revision to use instead
+of the current revision if none is specified.
+
+HGCommandNameMarker				*HGCommandNameMarker*
+
+This variable, if set, configures the special attention-getting characters
+that appear on either side of the hg buffer type in the buffer name.  This
+has no effect unless |HGCommandNameResultBuffers| is set to a true value.  If
+not set, it defaults to '_'.  
+
+HGCommandNameResultBuffers			*HGCommandNameResultBuffers*
+
+This variable, if set to a true value, causes the hg result buffers to be
+named in the old way ('<source file name> _<hg command>_').  If not set
+or set to a false value, the result buffer is nameless.
+
+HGCommandSplit					*HGCommandSplit*
+
+This variable controls the orientation of the various window splits that
+may occur (such as with HGVimDiff, when using a HG command on a HG
+command buffer, or when the |HGCommandEdit| variable is set to 'split'.
+If set to 'horizontal', the resulting windows will be on stacked on top of
+one another.  If set to 'vertical', the resulting windows will be
+side-by-side.  If not set, it defaults to 'horizontal' for all but
+HGVimDiff windows.
+
+5.2 HGCommand events				*hgcommand-events*
+
+For additional customization, HGCommand can trigger user-defined events.
+Event handlers are provided by defining User event autocommands (see
+|autocommand|, |User|) in the HGCommand group with patterns matching the
+event name.
+
+For instance, the following could be added to the vimrc to provide a 'q'
+mapping to quit a HGCommand scratch buffer:
+
+augroup HGCommand
+  au HGCommand User HGBufferCreated silent! nmap <unique> <buffer> q: bwipeout<cr>
+augroup END
+
+The following hooks are available:
+
+HGBufferCreated		This event is fired just after a hg command
+				result buffer is created and filled with the
+				result of a hg command.  It is executed within
+				the context of the HG command buffer.  The
+				HGCommand buffer variables may be useful for
+				handlers of this event (please see
+				|hgcommand-buffer-variables|).
+
+HGBufferSetup			This event is fired just after HG buffer setup
+				occurs, if enabled.
+
+HGPluginInit			This event is fired when the HGCommand plugin
+				first loads.
+
+HGPluginFinish			This event is fired just after the HGCommand
+				plugin loads.
+
+HGVimDiffFinish		This event is fired just after the HGVimDiff
+				command executes to allow customization of,
+				for instance, window placement and focus.
+
+5.3 HGCommand buffer naming				*hgcommand-naming*
+
+By default, the buffers containing the result of HG commands are nameless
+scratch buffers.  It is intended that buffer variables of those buffers be
+used to customize the statusline option so that the user may fully control the
+display of result buffers.
+
+If the old-style naming is desired, please enable the
+|HGCommandNameResultBuffers| variable.  Then, each result buffer will receive
+a unique name that includes the source file name, the HG command, and any
+extra data (such as revision numbers) that were part of the command.
+
+5.4 HGCommand status line support			*hgcommand-statusline*
+
+It is intended that the user will customize the |'statusline'| option to
+include HG result buffer attributes.  A sample function that may be used in
+the |'statusline'| option is provided by the plugin, HGGetStatusLine().  In
+order to use that function in the status line, do something like the
+following:
+
+set statusline=%<%f\ %{HGGetStatusLine()}\ %h%m%r%=%l,%c%V\ %P
+
+of which %{HGGetStatusLine()} is the relevant portion.
+
+The sample HGGetStatusLine() function handles both HG result buffers and
+HG-managed files if HGCommand buffer management is enabled (please see
+|hgcommand-buffer-management|).
+
+5.5 HGCommand buffer management		*hgcommand-buffer-management*
+
+The HGCommand plugin can operate in buffer management mode, which means that
+it attempts to set two buffer variables ('HGRevision' and 'HGBranch') upon
+entry into a buffer.  This is rather slow because it means that 'hg status'
+will be invoked at each entry into a buffer (during the |BufEnter|
+autocommand).
+
+This mode is disabled by default.  In order to enable it, set the
+|HGCommandEnableBufferSetup| variable to a true (non-zero) value.  Enabling
+this mode simply provides the buffer variables mentioned above.  The user must
+explicitly include those in the |'statusline'| option if they are to appear in
+the status line (but see |hgcommand-statusline| for a simple way to do that).
+
+==============================================================================
+
+6. SSH "integration"					*hgcommand-ssh*
+
+The following instructions are intended for use in integrating the
+hgcommand.vim plugin with an SSH-based HG environment.
+
+Familiarity with SSH and HG are assumed.
+
+These instructions assume that the intent is to have a message box pop up in
+order to allow the user to enter a passphrase.  If, instead, the user is
+comfortable using certificate-based authentication, then only instructions
+6.1.1 and 6.1.2 (and optionally 6.1.4) need to be followed; ssh should then
+work transparently.
+
+6.1 Environment settings				*hgcommand-ssh-env*
+
+6.1.1 HGROOT should be set to something like:
+
+	:ext:user@host:/path_to_repository
+
+6.1.2 HG_RSH should be set to:
+
+	ssh
+
+	Together, those settings tell HG to use ssh as the transport when
+	performing HG calls.
+
+6.1.3 SSH_ASKPASS should be set to the password-dialog program.  In my case,
+	running gnome, it's set to:
+
+	/usr/libexec/openssh/gnome-ssh-askpass
+
+	This tells SSH how to get passwords if no input is available.
+
+6.1.4 OPTIONAL.  You may need to set SSH_SERVER to the location of the hg
+	executable on the remote (server) machine.
+
+6.2 HG wrapper program				*hgcommand-ssh-wrapper*
+
+Now you need to convince SSH to use the password-dialog program.  This means
+you need to execute SSH (and therefore HG) without standard input.  The
+following script is a simple perl wrapper that dissasociates the HG command
+from the current terminal.  Specific steps to do this may vary from system to
+system; the following example works for me on linux.
+
+#!/usr/bin/perl -w
+use strict;
+use POSIX qw(setsid);
+open STDIN, '/dev/null';
+fork and do {wait; exit;};
+setsid;
+exec('hg', @ARGV);
+
+6.3 Configuring hgcommand.vim			*hgcommand-ssh-config*
+
+At this point, you should be able to use your wrapper script to invoke HG with
+various commands, and get the password dialog.  All that's left is to make HG
+use your newly-created wrapper script.
+
+6.3.1 Tell hgcommand.vim what HG executable to use.  The easiest way to do this
+	is globally, by putting the following in your .vimrc:
+
+	let HGCommandHGExec=/path/to/hg/wrapper/script
+
+6.4 Where to go from here			*hgcommand-ssh-other*
+
+The script given above works even when non-SSH HG connections are used,
+except possibly when interactively entering the message for HG commit log
+(depending on the editor you use... VIM works fine).  Since the hgcommand.vim
+plugin handles that message without a terminal, the wrapper script can be used
+all the time.
+
+This allows mixed-mode operation, where some work is done with SSH-based HG
+repositories, and others with pserver or local access.
+
+It is possible, though beyond the scope of the plugin, to dynamically set the
+HG executable based on the HGROOT for the file being edited.  The user
+events provided (such as HGBufferCreated and HGBufferSetup) can be used to
+set a buffer-local value (b:HGCommandHGExec) to override the HG executable
+on a file-by-file basis.  Alternatively, much the same can be done (less
+automatically) by the various project-oriented plugins out there.
+
+It is highly recommended for ease-of-use that certificates with no passphrase
+or ssh-agent are employed so that the user is not given the password prompt
+too often.
+
+==============================================================================
+9. Tips							*hgcommand-tips*
+
+9.1 Split window annotation, by Michael Anderson
+
+:nmap <Leader>hgN :vs<CR><C-w>h<Leader>hgn:vertical res 40<CR>
+                 \ggdddd:set scb<CR>:set nowrap<CR><C-w>lgg:set scb<CR>
+                 \:set nowrap<CR>
+
+This splits the buffer vertically, puts an annotation on the left (minus the
+header) with the width set to 40. An editable/normal copy is placed on the
+right.  The two versions are scroll locked so they  move as one. and wrapping
+is turned off so that the lines line up correctly. The advantages are...
+
+1) You get a versioning on the right.
+2) You can still edit your own code.
+3) Your own code still has syntax highlighting.
+
+==============================================================================
+
+8. Known bugs						*hgcommand-bugs*
+
+Please let me know if you run across any.
+
+HGVimDiff, when using the original (real) source buffer as one of the diff
+buffers, uses some hacks to try to restore the state of the original buffer
+when the scratch buffer containing the other version is destroyed.  There may
+still be bugs in here, depending on many configuration details.
+
+==============================================================================
+=== END_DOC
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+" v im:tw=78:ts=8:ft=help:norl:
+" vim600: set foldmethod=marker  tabstop=8 shiftwidth=2 softtabstop=2 smartindent smarttab  :
+"fileencoding=iso-8859-15