diff options
author | Karl Berry <karl@freefriends.org> | 2020-04-27 21:17:13 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2020-04-27 21:17:13 +0000 |
commit | bf42995081d83e87bcfc31900f072921e3a95c41 (patch) | |
tree | e1b2b145be35174a19364111a99ba1b45c2f2dd6 /Master/texmf-dist/doc/context/third | |
parent | 597d59d1a34bc68a7d2b3e43012c15350df129be (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/context/third')
-rw-r--r-- | Master/texmf-dist/doc/context/third/vim/VERSION | 2 | ||||
-rw-r--r-- | Master/texmf-dist/doc/context/third/vim/vim.txt | 108 |
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 -------------------- |