context-vim update per author

git-svn-id: svn://tug.org/texlive/trunk@23166 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 180 insertions, 13 deletions

diff --git a/Master/texmf-dist/doc/context/third/vim/vim.txt b/Master/texmf-dist/doc/context/third/vim/vim.txt
index 349c9b39da8..153398011ce 100644
--- a/Master/texmf-dist/doc/context/third/vim/vim.txt
+++ b/Master/texmf-dist/doc/context/third/vim/vim.txt
@@ -11,10 +11,65 @@ editors, and many other syntax highlighting programs, already syntax highlight
 many programming languages. Why not just leverage these external programs to
 generate syntax highlighting? This module does exactly that.
 
+Compatibility
+------------
+
+This module works with both MkII and MkIV. 
+
+To get colors with MkII, use
+
+    \setupcolors[state=start]
+
+If avoid `--` and `---` to turn into `–` and `—` in MkII, use
+
+    \usetypescript [modern] [texnansi]
+    \setupbodyfont [modern]
+
+Both colors and no ligatures work out of the box in MkIV.
+   
+
 Installation
 ------------
 
-TODO:
+This module depends on the `t-filter` module. If you are using ConTeXt minimals,
+you can install the module using 
+
+    first-setup.sh --extras="t-filter,t-vim"
+
+Depending on your TeX distribution, you may already have the module.
+To verify, check if
+
+    kpsewhich t-vim.tex
+
+returns a meaningful path. If not, you have to manually install the module.
+Download the latest version of the `filter` and `vim` modules from
+[http://github.com/adityam/filter/downloads](http://github.com/adityam/filter/downloads)
+and unzip them either `$TEXMFHOME` or `$TEXMFLOCAL`. Run
+
+    mktexlsr
+
+and
+
+    mtxrun --generate
+
+to refresh the TeX file database (for MkII and MkIV, respectively). If
+everything went well
+
+    kpsewhich t-vim
+
+will return the path where you stored the file.
+
+Unfortunately, that is not enough. For the module to work, TeX must be able to
+call an external program. This feature is a potential security risk and is
+disabled by default on most TeX distributions. To enable this feature, you must
+set
+
+    shell_escape=t
+
+in your `texmf.cnf` file. See this page
+[http://wiki.contextgarden.net/write18](http://wiki.contextgarden.net/write18)
+on the ConTeXt wiki for detailed instructions.
+
 
 Usage
 -----
@@ -75,16 +130,31 @@ The `t-vim` module simply defines the macros that are used by `2context.vim`.
 Start and stop lines
 --------------------
 
-The `\start<typing>` ... `\stop<typing>` environment and the `\type<typing>file`
+The `\start<vimtyping>` ... `\stop<vimtyping>` environment and the `\type<vimtyping>file`
 macro take an optional argument that is used to set options.
 
-For example, if we only want to typeset lines 15 through 25 of a ruby file
-`rails_install.rb`, we can use:
+For example, to typeset lines 15 through 25 of a ruby file
+`rails_install.rb`, use:
 
     \typeRUBYfile[start=15,stop=25]{rails_install.rb}
 
 To exclude 10 lines from the end, set `stop=-10`.
 
+Changing tab skip
+-----------------
+
+By default, a literal tab (`0x09` or `^I`) character has a width of 8 spaces. For most
+cases, this is too excessive. To reduce the shift of a tab, use the `tab` key.
+For example:
+
+    \definevimtyping
+      [...]
+      [...
+       tab=4,
+       ...]
+
+changes the tab width to four spaces. 
+
 Avoid clutter
 -------------
 
@@ -92,8 +162,8 @@ Running an external file through vim is slow. So, `t-vim` reprocesses a snippet
 or a file only if its contents have changed. To check if the contents have
 changed, it writes each snippet to a different file and stores the md5 sum of
 that snippet. As a result, the working directory gets cluttered with lot of
-temporary files. To avoid the clutter, these temporary files can be written to a
-different directory, e.g.,
+temporary files. To avoid this clutter, write the temporary files to an a
+different directory using the `directory` key. For example,
 
     \definevimtyping[...]
                     [directory=output/]
@@ -127,6 +197,110 @@ A particular color scheme may be chosen using the options:
 
 The default color scheme is `pscolor`.
 
+Line numbering
+---------------
+
+To eanble line numbering for a particular snippet, use:
+
+    \start<vimtyping>[numbering=yes]
+      ...
+    \stop<vimtyping>
+
+To enable line numbering for all code snippets, use:
+
+    \definevimtyping
+      [...]
+      [...
+       numbering=yes,
+       ...]
+
+If you want a particular snippet not to have line numbering, use
+
+    \start<vimtyping>[numbering=no]
+      ...
+    \stop<vimtyping>
+
+By default, numbering starts from one, all lines are numbered, numbering is
+reset at each snippet, and numbers are displayed on the left. All these defaults
+can be changed. 
+
+Number of the first line
+------------------------
+
+By default, the numbering starts from one (that is, the first line is numbered
+`1`). If you want the first line to be numbered something else, say `15`, you
+need to set
+
+      \start<vimtyping>[numberstart=15]
+
+If you want the numbering to continue from where the previous snippet ended, use
+
+      \start<vimtyping>[numbercontinue=yes]
+
+By default, consecutive lines are numbered. If you want alternate lines to be
+numbered, use
+
+      \start<vimtyping>[numbertstep=2]
+
+If you want every fifth line to be numbered, use
+
+      \start<vimtyping>[numbertstep=5]
+
+Standard options for line numbering
+-----------------------------------
+
+- To change the color or style of the numbers, use the `numbercolor=...` and
+  `numberstyle=...` options. By default `numbercolor` is not set, while
+  `numberstyle` is set to `\ttx`.
+
+- To change the alignment of numbers, use the `numberalign=...` option. Default
+  value is `flushright`.
+
+- To change the width of the box in which the numbers are typeset, use
+  `numberwidth=...` option. Default value is `2em`.
+
+- To change the distance between the numbers and the rest of the code, use
+  `numberdistance=...` option. Default value is `0.5em`.
+
+- To change the conversion of numbers, use `numberconversion=...` option.
+  Default value is `numbers`.
+
+- Use `numberleft=...` and `numberright=...` options to typeset
+  something on the left and right of the number. By default, these options are
+  not set.
+
+- `numbercommand=...` is used to set a command for typesetting the number.
+
+- `numberlocation=...` is used to set the location of the numbers. Default value
+  is `left`. Change this to `right` if you want the numbers on the right.
+
+Spaces
+------
+
+By default, the space is invisible. If you want to make the space visible, set
+
+    \definevimtyping
+        [...]
+        [...
+         space=on,
+         ...]
+
+The default value is `space=off`.
+
+Splitting lines
+---------------
+
+By default, long lines are not split. If you want to split long lines, set
+
+    \definevimtyping
+        [...]
+        [...
+         lines=split,
+         ...]
+
+The default value is `lines=fixed`.
+
+
 A bit of a history
 ------------------
 
@@ -155,10 +329,3 @@ in the module, except a few minor bug fixes.
 Around June 2010, I decided to completely rewrite the module from scratch. The
 new version of `t-vim` relies on `t-filter` for all the bookkeeping. As a
 result, the module is smaller and more robust.
-
-TODO
-----
-
-- Line numbering
-- continue line numbering from previous environment
-- modify tabs and spaces