Vim HowTo - Maintaining vim pages, binaries, and syntax files

Some hints on maintainng a syntax file for Vim.

Getting Started

Get and install the "runtime archive" with the helpfiles and syntax files.

Have a look at the syntax file distributed with Vim These should be available in the directory "$VIM/syntax". For example, you should be able to take a look at the main syntax file with ":view $VIM/syntax/syntax.vim".

Fool around with some of the colors in syntax.vim. Then make a copy of some syntax file and change it. Work it in to the syntax vim by adding the autocommands necessary to load them for your special files. Invent a new filename extension if necessary. "Be inventive!" :-)

Header:
The start of your systax file MUST contain a "header" with info about the syntax file. All lines MUST be comment lines, ie start with '"'. The comment of the first line should read "Vim syntax file". All further lines have a "field name", followed by a colon, and followed by one or more TABs to align the values nicely (tabstop=8). The line with "Language" should mention the name of the language, or possibly explain the abbreviation chosen for the filename. The line "Version" is optional; if it exists then it should give a hint on some kind of version number, indicating how severe the changes have been. "Last Change" MUST contain the output of a local "date" command, so it is easily parsable. "Maintainer" MUST contains the *full* name of the maintainer and also a working email address. "URL" MUST contain the correct address to the online version of the syntax file. And "Info" MUST point to a webpage that contains more info about the syntax file (purpose, installation, configuration etc). I highly recommend that make your syntax file available and also create an info page for it, too! "Literature" and "Contributors" are completely optional and SHOULD be added as separate paragraphs. But this would be nice.

$ head mylang.vim " Vim syntax file " Language: MyLang " Version: 1.2.3 " Last Change: Sun Jan 14 03:33:33 MET 2001 " Last Change: 010114 " Maintainer: NAME <address> " URL: http://www.math.fu-berlin.de/~guckes/Vim/syntax/mylang.vim " Info http://www.math.fu-berlin.de/~guckes/Vim/syntax/ " SEE ALSO: " Contributors: NAME <address> " Literature: <book>

VIM Users Page - Hints

If you can spare a little time for putting up a page for your syntax file then I'd appreciate if you could create it with the follwing structure:

  Home Page         http://www.domain/~user/
  Vim  Page         http://www.domain/~user/vim/index.html
  Vim  Binary page  http://www.domain/~user/vim/bin/index.html
  Vim  Binaries     http://www.domain/~user/vim/bin/vim-bin-OS-version/.tar.gz
  Vim  Syntax Page  http://www.domain/~user/vim/syntax/index.html
  Vim  Syntax Files http://www.domain/~user/vim/syntax/language.vim

This structure helps in finding vim pages and additional syntax files more easily on the Web.

Example: Altavista's "advanced search" allows to search for "url:vim/syntax/".

Contents of Pages

Now, what can you put onto your vim page?

Vim Page: Add some links to the vim data that you maintain, eg binaries, syntax files, your vimrc, or docs on vim. Let everyone know what you do with Vim, how you use it, and what your favourite features are. Descriptions of misfeatures and pet peeves are definitely welcome, too! Put any info on Vim onto your page. Then again, you might want to avoid redundancy by linking one of the Vim Pages, such as the page with the summary on mirror sites, binaries the History or the HowTos.

Put all outbound links (eg a link to the Vim HomePage) at the end of your page.

Syntax Page

Give a summary of all you syntax files first. Then describe what they do and how to use them. Give some examples by screenshots or by using "2html.vim" to create a webpage with colored text.

Binaries Page

Give a summary of all the binaries you maintain. Then list them all one by one, giving an output of each of their ":version", so you can see which feature have been compiled into the binary.

Please update all binaries to the latest user release. Yes, this takes some time, but those wo use your binary will be thankful that you did.

Example Pages

Here are some nice examples of well maintained vim pages:

Peppe's Vim Page: I think it is a great page because the info is shown very clearly. It is a frame version by default but can also be viewed as a "normal" page.
Thomas Köhler's vim page - vim binary for SunOS: This page has a link to the archive file and also shows its ":version" output, so you'll know which features are in that binary and also when it was compiled. [990206]

URL:         http://www.math.fu-berlin.de/~guckes/vim/howto/synmain.html
Created:     https://www.vim8.org/synmain.html (mirror)
Created:     Wed Mar 03 19:00:00 CET 1999

Send feedback on this page to

Sven Guckes [email protected]