summaryrefslogtreecommitdiff
path: root/macros/context/contrib/context-vim/doc/context/third/vim/vim.txt
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2020-04-27 03:03:41 +0000
committerNorbert Preining <norbert@preining.info>2020-04-27 03:03:41 +0000
commitae496a1c963576dfe63885afa818b2af745ed44a (patch)
tree62604706ca603c17f5f56fe646072d8d2cfab60c /macros/context/contrib/context-vim/doc/context/third/vim/vim.txt
parent7d9d2e08fcab92adcc759e3f1e4bb0a15a63f220 (diff)
CTAN sync 202004270303
Diffstat (limited to 'macros/context/contrib/context-vim/doc/context/third/vim/vim.txt')
-rw-r--r--macros/context/contrib/context-vim/doc/context/third/vim/vim.txt108
1 files changed, 97 insertions, 11 deletions
diff --git a/macros/context/contrib/context-vim/doc/context/third/vim/vim.txt b/macros/context/contrib/context-vim/doc/context/third/vim/vim.txt
index 801d1fb34c..11c17cf59e 100644
--- a/macros/context/contrib/context-vim/doc/context/third/vim/vim.txt
+++ b/macros/context/contrib/context-vim/doc/context/third/vim/vim.txt
@@ -73,6 +73,9 @@ on the ConTeXt wiki for detailed instructions.
Usage
-----
+Include the module
+
+ \usemodule[vim]
Suppose you want to syntax highlight Ruby. In particular, you want
@@ -112,7 +115,7 @@ defines three things:
\inlineRUBY{...}
- The contents of this environment are processed by a vim script
+ The contents of this macro are processed by a vim script
(`2context.vim`) and the result is read back in ConTeXt.
3. A macro
@@ -125,7 +128,15 @@ defines three things:
processing a url, see the _Processing remote files_ section of the
`t-filter` manual.
-In all the three cases, the `t-filter` module takes care of writing to external
+4. A macro
+
+ \processRUBYbuffer[...]
+
+ The argument to the macro is the name of a buffer, which is written to an
+ external file, processesd by `2context.vim` and the result is read back in
+ ConTeXt.
+
+In all the four 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`.
@@ -460,21 +471,27 @@ the bar starts from the first non-blank character.
Using TeX code in Comments
--------------------------
-Sometimes one wants to use TeX code in comments, especially for math. To
-enable this use
+Sometimes one wants to use TeX command in code. There are two different
+methods to do so.
+
+The first method is primarily aimed towards writing math in comments. To
+enable this, use
\definevimtyping
[...]
[...
- escape=on,
+ escape=comment,
]
-When `escape=on`, the `2context.vim` script passes the `Comment` syntax
-region (as identified by `vim`) verbatim to TeX. So, we may use TeX
-commands inside the comment region and they will be interpreted by TeX.
-For example
+For backward compatibility, this feature can also be enabled using
+`escape=on`.
- \definevimtyping[C][syntax=c, escape=on]
+When `escape=comment` is enabled, the `2context.vim` script passes the
+`Comment` syntax region (as identified by `vim`) verbatim to TeX. So, we may
+use TeX commands inside the comment region and they will be interpreted by
+TeX. For example
+
+ \definevimtyping[C][syntax=c, escape=comment]
\startC
/* The following function computes the roots of \m{ax^2+bx+c=0}
@@ -484,10 +501,79 @@ For example
\stopC
**Note** that only `\ { }` have their usual meaning inside the `Comment`
-region when `escape=on` is set. Thus, to enter a math expression, use
+region when `escape=comment` is set. Thus, to enter a math expression, use
`\m{...}` instead of `$...$`. Moreover, spaces are active inside the
math mode, so, as in the above example, avoid spaces in the math expressions.
+The second method is to imitate the behavior of `\starttyping` environment,
+where one can write arbitrary TeX commands in code inside `/BTEX ... /ETEX`
+delimiters. To enable this, use
+
+ \definevimtyping
+ [...]
+ [...
+ escape=command,
+ ]
+
+When `escape=command` is enabled, the `2context.vim` script defines a new
+syntax region using
+
+ syntax region ... start="/BTEX" end="/ETEX" transparent oneline containedin=ALL contains=NONE
+
+and passes content of this region verbatim to TeX. So, any TeX commands used
+inside this region are interpreted by TeX. For example,
+
+ \definevimtyping[C][syntax=c, escape=command]
+
+ \startC
+ /* Here is a comment describing a complicated function */
+ /BTEX\startframedtext[width=\textwidth,corner=round]/ETEX
+ double complicated (...)
+ {
+ ....
+ }
+ /BTEX\stopframedtext/ETEX
+ \stopC
+
+**Note** that as in the case for `escape=comment`, only `\ { }` have their
+usual meaning inside `/BTEX ... /ETEX`. Moreover, spaces are active
+characters. So, using a space between `\startframedtext` and `[` or between
+after the comma in the options to `\startframedtext` will result in an error.
+
+Clearly, `/BTEX ... /ETEX` is not a valid syntax in any language, so if these
+tags are used outside of a comment region (as is the case in the above
+example), the code will not compile. So, if the code also needs to run, then
+these annotations have to be restricted to the comment region of the code.
+
+Although, in practice, the use of both escape mechanisms is restricted to
+comments, the two mechanism have subtle differences. When using
+`escape=comment`, the `2context.vim` script simply passes the content of the
+comment region to TeX. This content is still typeset inside a
+`\SYN[Comment]{...}` group. While when using `escape=command`, the
+`2context.vim` script identifies the content of `/BTEX .. /ETEX` and passes it
+to TeX _without wrapping it insider any `\SYN[..]{...}` group_. This has an
+advantage when we want to use commands that cannot be used inside a group
+(e.g., `\inmargin`). For example, if we want to define a `\callout` macro that
+displays a note in the margin which we can refer to later, we can use:
+
+
+ \define[1]\callout{\inmargin{\rm #1}}
+ \definevimtyping[C][syntax=c, escape=command]
+
+ \startC
+ /* Here is a comment describing a complicated function */
+ double complicated (...)
+ {
+ ... // /BTEX\callout{Fancy trick!}/ETEX
+ }
+ \stopC
+
+Finally, note that the value of `escape` set using `\definevimtyping` is not
+used to `\inline<vim>typing`. If for some reason, you do need the escape
+mechanism for inline code, use
+
+ \inline<vim>typing[escape=command]{...}
+
Tuning color schemes
--------------------