summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/context/third/vim/vim.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/context/third/vim/vim.txt')
-rw-r--r--Master/texmf-dist/doc/context/third/vim/vim.txt193
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