Vim Editor

This page is for those using vim, an excellent vi clone with many added features such as infinite undo, filename completion, windowing, syntax highlighting, file recovery (great if machine crashes or connection drops), etc. Comparable in power to the EmacsEditor, vim is available from vim.org, and is included in CygWin and most Linux distributions. It does help if you like vi, but vim is quite a bit more user friendly than vi.

NOTE: This should really have a TopicClassification of DeveloperTip, like PerlTips and some other pages.

See also Google:vim.

Getting started with vim

This $HOME/.vimrc file works with 'tags' for easier navigation and sets some other useful options for editing TWiki code:

set ignorecase
set shiftwidth=3 " recommended: twiki needs an indent of exactly 3 for lists
set autoindent
" Use ^D to move cursor back one indent level

" Turn on syntax highlighting - adjust background command
" to your window background
if &t_Co > 1
   syntax enable
   set background=dark
endif

" Point to global tags file - set the 'twiki' environment
" variable to point to the 'twiki' directory above bin, lib, etc.
set tags=$twiki/tags

" Make tab-completion work more like bash
set wildmode=longest,list

" Flip cursor to matching parenthesis when you type closing paren
set showmatch

" Record search patterns and command history between invocations of vi
set viminfo=%,'50,\"100,:100,n~/.viminfo

Using spaces for indentation -

To edit TWiki code, you are recommended to use only spaces for indentation, and use 3-character indents (see ReadmeFirst). This can be configured easily with the following ~/.vimrc settings:

" Always expand tabs to spaces
set expandtab
set softtabstop=3
set tabstop=8

These have the effect of always inserting spaces instead of TABs when you hit the tab key (expandtab), inserting 3 spaces for each tab (softtabstop=3), and interpreting embedded TAB characters as 8 tabstops (for compatibility with some existing code that doesn't follow the current guidelines.

To convert code with '8-space' TABs already inserted, you can do the following interactively within vim:

:retab 8

Syntax highlighting

Since vim's syntax highlighting is excellent, here's a tweak to make it show TWiki *.tmpl files like HTML files. Using vim 6.0 or higher, edit $VIMRUNTIME/filetype.vim, adding this near end:

" -------------------- Local changes
" TMPL (TWiki HTML templates)
au BufNewFile,BufRead *.tmpl    setf html

To find out the value of $VIMRUNTIME, launch vim and type :echo $VIMRUNTIME, or just do :n $VIMRUNTIME/filetype.vim.

Using tags

ExuberantCtags is a great tool to generate a ctags file, which acts as an index of all functions in all TWiki files - this lets you hit a key to follow a function call to its definition (even if it's in another file).

This Makefile generates a new tags file, should be placed in 'twiki' directory. The last 2 commands are for CygWin only, to use forward slashes:

tags:
        ctags --recurse --excmd=pattern --exclude=CVS --totals
        perl -pi.bak -e 's!\\!/!g' tags
        rm tags.bak

-- RichardDonkin - 31 Mar 2002

Syntax File

Here's a first pass at a syntax file for TWiki on Vim. Enjoy. Usual disclaimers apply.

If you want to loose even more of my kludgeware on your system, you might enjoy EditDaemonWithGVimIntegration, which lets you automatically load and save TWiki based pages from Vim. If you have the misfortune to use another editor, the edit daemon component may well still be quite useful.

-- SimonClift - 12 Nov 2002

Online resources

See http://vim.org/ for a lot of resources, including tutorials and tips - and of course Google:vim has even more information.

The Vi IMproved book, from New Riders, is available free online, as well as on paper. Well worth a look, but note that the table of contents frame only seems to work with InternetExplorer, not Opera or Mozilla... I've uploaded the pdf version here. MartyBacke

-- RichardDonkin - 12 Jan 2003

I have started using MozEX to edit text area in Vim. Promblem is that attached wiki syntax file for Vim doesnt seem to work very well. It does not handle underscore in the middle of a word (e.g. one_word ) correctly. It gets confused and starts highlighting everything after that underscore as italic. It has same problem while highlighting say x=3. I wish I could fix it but I am no wizard at writing Vim syntax files. Does anyone has fixed this problem or have better syntax file? Thanks.

-- HaritNanavati - 07 Oct 2003

You might also look at Cream for Vim, a package of vim scripts designed to make gVim behave more like standard editors. It redoes the menus to fit familiar paradigms, tries to make as much as possible doable from insertmode, etc.

Also, if you're editing some of the more involved TWiki code, it might be smart to download an updated Perl syntax file. I've also found it helpful to add 'let perl_extended_vars=1' in my .vimrc, which tells the Perl syntax highlighter to deal properly with stuff like @{$ref->[5]} variable accesses.

-- WalterMundt - 10 Mar 2004

I don't have a fixed syntax file, but the problem is that the regexes in the syntax file are over-simple, having looked at them quickly. Try writing regexes that are similar to the ones in CVSget:lib/TWiki.pm, specifically the ones in getRenderedVersion at the end of the file. These check for various items before and after the regex (e.g. non-alpha characters before the '_' used to start italic markup, for example). You would need to learn a bit more about Vim's regex capabilities but it shouldn't be too hard as long as it has positive lookahead/lookbehind type regexes.

-- RichardDonkin - 07 Oct 2003

I have attached twikiSyntax.vim which handles syntax for emphasis a little bit better then the previous syntax file. Its still not perfect but this will work for now.

-- HaritNanavati - 07 Oct 2003

According to this Vim tip, http://www.vim.org/tips/tip.php?tip_id=581 , there is a plugin for Mozilla which allows text areas to be editted with Vim.

-- JonathanCline - 14 Oct 2003

Since 1999 I have been attempting to learn enough of Vim to make it my favourite text editor. While I've managed to learn a fair bit about it, even to the point of building a script to search and replace thousands of text files on multiple users machines unattended, I just haven't been able to get get comfortable with it. Text Pad is still my text editor of choice at work we pay for these things. Today though, I may have found the program to turn this around: enter "Cream, an easy-to-use configuration of the powerful, free, and famous Vim text editor for both Microsoft Windows and GNU/Linux."

-- MattWilkie - 24 Oct 2003

There's another TWiki syntax file for vim at the vim site.

-- RichardDonkin - 25 Oct 2004

A new version of TWiki syntax file for vim has been released that includes support for folding.

-- IanTegebo - 06 Mar 2006

I modified the vim syntax file from HaritNanavati to include highlighting for any TWiki variable, not just the predefined ones, as well as including the highlighting for HTML.

-- RobertWhelton - 24 May 2006

The TWiki syntaxfile for vim is now also hostet at sourceforge: http://sf.net/projects/vim-twiki

-- RainerThierfelder - 01 Jun 2006

Way cool, this. Does anyone have a tip for what I might be able to do in my .vimrc so I don't have to do :se syntax=twiki everytime I edit a file? Or maybe a fancy shell alias/function to handle this?

Hmmm... answering my own question:

alias viki='vim -c ":se syntax=twiki" $*'

Alternatively, the vim -u option could be used

-u {vimrc}  Use the commands in the file {vimrc}  for  initializations.
                  All  the  other  initializations  are skipped.  Use this to edit special kind of files.  

So, a vim alias for editing twiki files that uses a separate but not quite equal ~.vimrc_tw file.

-- VickiBrown - 07 Jul 2006

• I'm using mozex with firefox. One can configure mozex to use an external editor for editboxes in webpages. And that's what the edit field in twiki is. To start vim from mozex I use a script like that:

  #!/bin/sh
  /usr/bin/vim -geometry 120x60+10+20 -g -c 'set ft=twiki' -f $*
     

-- RainerThierfelder - 11 Jul 2006

Hi Rainer,

I've made some changes to the twiki.vim syntax file for my personal use: What the patch (twiki.vim.patch.20060811, attached) mainly does is:

• add the HTML syntax so HTML code in TWiki gets highlighted (usefull for TWikiApplications development
• highlight diferent parts of variables, and other variables inside arguments
• add a <pre> that looks like <verbatim> but accepts TWikiVariables
• add support for WebName.WikiWord WikiWords

Maybe you'll want to apply these changes to the distributed file.

-- AntonioTerceiro - 11 Aug 2006

Hi Antonio,

Thanks for the patch. I included most of it and updated the files on sourceforge (http://sourceforge.net/projects/vim-twiki).

• the HTML syntax could now be includes by setting of g:Twiki_SourceHTMLSyntax in your ~/.vimrc
• I think that WikiWords were already working. The problem with your patch was, that for example asdf.WikiWord would be recognized as WikiWord, too.

-- RainerThierfelder - 18 Sep 2006

<advertisement>
I just uploadet a new version (0.7) with some bugfixes to http://www.vim.org/scripts/script.php?script_id=1113 and made that package available on sourceforge: http://sourceforge.net/projects/vim-twiki.
Let me know, if you find errors or bugs.
</advertisement>

-- RainerThierfelder - 23 Nov 2006

Rainer, I made some functions to add autocompletion, it works well on VIm 7.0 or greater. As I saw the development of the project is being hosted on sourcefoge, can we do this here on this twiki topic ? I would like to add lots of new functionalities to it. I don't know how to let you know my improvements (since I don't want to override the twiki.vim attached to this topic), can you give me a callback on this ? thks.

-- MarcoSilva - 07 Oct 2007

I would recommend to use a shiftwidth and softtabstob of 3 as long as TWiki demands an indenting of exactly 3 spaces for lists.

-- OlafSchulz - 13 Apr 2008