summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/context
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2011-02-07 00:17:28 +0000
committerKarl Berry <karl@freefriends.org>2011-02-07 00:17:28 +0000
commit6ed45e99f37edb7c8a4a7e03adf20f60b93b0319 (patch)
tree2a7b90b09d7128ff369dac17232ac52970f7ddcf /Master/texmf-dist/doc/context
parent9771992141589e82ce1d540e026726b59004f44e (diff)
context-vim (7feb11)
git-svn-id: svn://tug.org/texlive/trunk@21319 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/context')
-rw-r--r--Master/texmf-dist/doc/context/third/vim/vim.txt176
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