context-vim (7feb11)

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

1 files changed, 140 insertions, 36 deletions

diff --git a/Master/texmf-dist/doc/context/third/vim/vim.txt b/Master/texmf-dist/doc/context/third/vim/vim.txt
index 251565547fc..349c9b39da8 100644
--- a/Master/texmf-dist/doc/context/third/vim/vim.txt
+++ b/Master/texmf-dist/doc/context/third/vim/vim.txt
@@ -1,23 +1,142 @@
 The vim module
 ==============
 
-ConTeXt has excellent code highlighting capabilities for some languages: TeX,
-metapost, XML, amongst others. In MkII, syntax highlighting was done by parsing
-the source code in TeX---a task not for the faint of heart. In MkIV, the
-situation is much better: syntax highlighting is done by parsing the source code
-in Lua using LPEG. Nonetheless, writing a grammar to parse the source code of
-languages is a tricky task. This module takes the onus of defining such a
-grammar away from the user and uses Vim editor to create syntax highlighting. A
-helper script, `2context.vim` does the actual work.
-
-The idea of the module was germinated  by Mojca Miklavec. She said (crica Sep
-2005):
+This module highlights code snippets using vim as a syntax
+highlighter. Such a task may appear pointless at first glance. After all,
+ConTeXt provides excellent syntax highlighting features for TeX, Metapost, XML,
+and a few other langauges. And in MkIV, you can specify the grammer to parse a
+language, and get syntax highlighting for a new language. But writing such
+grammers is difficult. More importantly, why reinvent the wheel? Most
+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.
+
+Installation
+------------
+
+TODO:
+
+Usage
+-----
+
+Suppose you want to syntax highlight Ruby. In particular, you want
+
+    \startRUBY
+      # Wow, my first ruby program
+      print("Hello World")
+    \stopRUBY
+
+to be printed with Ruby syntax highlighting. To get that, define
+
+    \definevimtyping [RUBY]  [syntax=ruby]
+
+Yes, its that easy. To get syntax highlighting for a particular language, all
+you need to know what is its `filetype` in vim. If you don't know that, start
+vim and type `:help syntax.txt` and go through the list of supported languages to
+find the name of the language that you are interested in. (Oh, and in case you
+don't know how to quit vim, type `:qa!`.)  Vim supports syntax
+highlighting for more than 500 programming languages; the `t-vim` module enables
+you to use any of them with just one `\definevimtyping`.
+
+The command 
+
+    \definevimtyping [RUBY]  [syntax=ruby]
+
+defines three things:
+
+1. An environment
+
+        \startRUBY
+          ...
+        \stopRUBY
+
+    The contents of this environment are processed by a vim script
+    (`2context.vim`) and the result is read back in ConTeXt.
+
+2. A macro
+
+        \inlineRUBY{...}
+
+    The contents of this environment are processed by a vim script
+    (`2context.vim`) and the result is read back in ConTeXt.
+
+3. A macro
+
+        \typeRUBYfile{...}
+
+    The argument of this macro must a file name. That file is processed by
+    `2context.vim` and the result is read back in ConTeXt.
+
+In all the three cases, the `t-filter` module takes care of writing to external
+file, processing by `2context.vim`, and reading the contents back to ConTeXt.
+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`
+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:
+
+    \typeRUBYfile[start=15,stop=25]{rails_install.rb}
+
+To exclude 10 lines from the end, set `stop=-10`.
+
+Avoid clutter
+-------------
+
+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.,
+
+    \definevimtyping[...]
+                    [directory=output/]
+
+ensures that all the temporary files are written to the `output` directory. See
+the section on _Output Directory_ in the documentation of `t-filter` module for
+more details.
+
+Before and after
+---------------
+
+Like most ConTeXt environments, `\definevimtyping` also accepts the `before` and
+`after` options. These can be used, for example, to enclose the output in a
+frame, etc.
+
+Changing the color scheme
+-------------------------
+
+This module provides two colorschemes
+
+- `pscolor` based on `ps_color` colorscheme for vim by Shi Zhu Pan.
+- `blackandwhite` based on `print_bw` colorscheme for vim by Mike Williams.
+
+A particular color scheme may be chosen using the options:
+
+    \definevimtyping
+      [...]
+      [...
+       alternative=pscolor,
+       ...]
+
+The default color scheme is `pscolor`.
+
+A bit of a history
+------------------
+
+Mojca Miklavec germinated the idea of using vim to get syntax highlighting.
+Below is her message to the ConTeXt mailing list (circa Sep 2005):
 
 > I am thinking of piping the code to vim, letting vim process it, and return
 > something like `highlight[Conditional]{if} \highlight[Delimiter]{(}
 > \highlight[Identifier]{!}`.
-
-
+>
 > One could modify the `2html.vim` file. Vim can already transform the highlighted
 > code to HTML, so ConTeXt should not be so difficult. Vim already has over 400
 > syntax file definitions, probably equivalent to some hundred thousand lines of
@@ -33,28 +152,13 @@ About two years later (circa June 2008), Mojca and I (Aditya Mahajan) pickup up
 on this idea and released `t-vim`. Over the next few years, nothing much changed
 in the module, except a few minor bug fixes. 
 
-Around June 2010, I decided to completely rewrite the module from scratch. It
-now uses the `t-filter` module behind the scenes for all the book-keeping of
-creating and maintaining external files.
-
-Installation
-------------
-
-You also need to install `t-filter` module.
+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.
 
-Basic Usage
------------
-
-The main macro of this module is `\definevimtyping`. Suppose you want to do
-syntax highlighting of ruby code in ConTeXt. For that you may use:
-
-    \definevimtyping [RUBY]  [syntax=ruby]
-
-This defines an environment
-
-    \startRUBY
-      ...
-    \stopRUBY
+TODO
+----
 
-The contents of this environment are written to an external file, which is then
-parsed using vim, and the output is read back by ConTeXt.
+- Line numbering
+- continue line numbering from previous environment
+- modify tabs and spaces