From ae496a1c963576dfe63885afa818b2af745ed44a Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 27 Apr 2020 03:03:41 +0000 Subject: CTAN sync 202004270303 --- .../context-vim/doc/context/third/vim/vim.txt | 108 ++++++++++++++++++--- 1 file changed, 97 insertions(+), 11 deletions(-) (limited to 'macros/context/contrib/context-vim/doc/context') 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 `\inlinetyping`. If for some reason, you do need the escape +mechanism for inline code, use + + \inlinetyping[escape=command]{...} + Tuning color schemes -------------------- -- cgit v1.2.3