summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2020-04-27 21:17:13 +0000
committerKarl Berry <karl@freefriends.org>2020-04-27 21:17:13 +0000
commitbf42995081d83e87bcfc31900f072921e3a95c41 (patch)
treee1b2b145be35174a19364111a99ba1b45c2f2dd6 /Master/texmf-dist/doc
parent597d59d1a34bc68a7d2b3e43012c15350df129be (diff)
context-vim (27apr20)
git-svn-id: svn://tug.org/texlive/trunk@54913 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r--Master/texmf-dist/doc/context/third/vim/VERSION2
-rw-r--r--Master/texmf-dist/doc/context/third/vim/vim.txt108
2 files changed, 98 insertions, 12 deletions
diff --git a/Master/texmf-dist/doc/context/third/vim/VERSION b/Master/texmf-dist/doc/context/third/vim/VERSION
index 95c275e4038..9e6f07d186e 100644
--- a/Master/texmf-dist/doc/context/third/vim/VERSION
+++ b/Master/texmf-dist/doc/context/third/vim/VERSION
@@ -1 +1 @@
-2018.08.10
+2020.04.25
diff --git a/Master/texmf-dist/doc/context/third/vim/vim.txt b/Master/texmf-dist/doc/context/third/vim/vim.txt
index 801d1fb34c7..11c17cf59e6 100644
--- a/Master/texmf-dist/doc/context/third/vim/vim.txt
+++ b/Master/texmf-dist/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
--------------------