context-vim (24jun20)

git-svn-id: svn://tug.org/texlive/trunk@55652 c570f23f-e606-0410-a88d-b1316a301751

4 files changed, 308 insertions, 37 deletions

diff --git a/Master/texmf-dist/doc/context/third/vim/VERSION b/Master/texmf-dist/doc/context/third/vim/VERSION
index 8d240647ada..421d2f5235d 100644
--- a/Master/texmf-dist/doc/context/third/vim/VERSION
+++ b/Master/texmf-dist/doc/context/third/vim/VERSION
@@ -1 +1 @@
-2020.05.17
+2020.06.23
diff --git a/Master/texmf-dist/doc/context/third/vim/vim.txt b/Master/texmf-dist/doc/context/third/vim/vim.txt
index ea2d4749470..88bc2b9dc62 100644
--- a/Master/texmf-dist/doc/context/third/vim/vim.txt
+++ b/Master/texmf-dist/doc/context/third/vim/vim.txt
@@ -11,6 +11,36 @@ 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.
 
+Table of Contents
+=================
+
+* [Compatibility](#compatibility)
+* [Installation](#installation)
+* [Usage](#usage)
+* [Start and stop lines](#start-and-stop-lines)
+* [Changing tab skip](#changing-tab-skip)
+* [Avoid clutter](#avoid-clutter)
+* [Before and after](#before-and-after)
+* [Changing the color scheme](#changing-the-color-scheme)
+* [Line numbering](#line-numbering)
+* [Number of the first line](#number-of-the-first-line)
+* [Standard options for line numbering](#standard-options-for-line-numbering)
+* [Spaces](#spaces)
+* [Removing leading spaces](#removing-leading-spaces)
+* [Adding left margin](#adding-left-margin)
+* [Wrapping lines](#wrapping-lines)
+* [Highlighting lines](#highlighting-lines)
+* [Using TeX code in Comments](#using-tex-code-in-comments)
+* [Tuning color schemes](#tuning-color-schemes)
+* [Messages and Tracing](#messages-and-tracing)
+* [Yes, on, whatever](#yes-on-whatever)
+* [Name (and location) of the VIM executable](#name-and-location-of-the-vim-executable)
+* [Defining a new colorscheme](#defining-a-new-colorscheme)
+* [Modifying an existing color scheme](#modifying-an-existing-color-scheme)
+* [A bit of a history](#a-bit-of-a-history)
+
+
+
 Compatibility
 ------------
 
@@ -209,7 +239,8 @@ A particular color scheme may be chosen using the options:
        alternative=pscolor,
        ...]
 
-The default color scheme is `pscolor`.
+The default color scheme is `pscolor`. See below for instructions on how to
+define a new colorscheme. 
 
 Line numbering
 ---------------
@@ -701,6 +732,246 @@ or, if `nvim` is not in the `$PATH`, using
 
 As of 2020.04.29, `nvim` is about 10% faster than `vim`.
 
+Defining a new colorscheme
+--------------------------
+
+Vim recommends the following names for syntax highlighting groups (information
+copied from `:help group-name`):
+
+> ```
+> 	*Comment	any comment
+> 
+> 	*Constant	any constant
+> 	 String		a string constant: "this is a string"
+> 	 Character	a character constant: 'c', '\n'
+> 	 Number		a number constant: 234, 0xff
+> 	 Boolean	a boolean constant: TRUE, false
+> 	 Float		a floating point constant: 2.3e10
+> 
+> 	*Identifier	any variable name
+> 	 Function	function name (also: methods for classes)
+> 
+> 	*Statement	any statement
+> 	 Conditional	if, then, else, endif, switch, etc.
+> 	 Repeat		for, do, while, etc.
+> 	 Label		case, default, etc.
+> 	 Operator	"sizeof", "+", "*", etc.
+> 	 Keyword	any other keyword
+> 	 Exception	try, catch, throw
+> 
+> 	*PreProc	generic Preprocessor
+> 	 Include	preprocessor #include
+> 	 Define		preprocessor #define
+> 	 Macro		same as Define
+> 	 PreCondit	preprocessor #if, #else, #endif, etc.
+> 
+> 	*Type		int, long, char, etc.
+> 	 StorageClass	static, register, volatile, etc.
+> 	 Structure	struct, union, enum, etc.
+> 	 Typedef	A typedef
+> 
+> 	*Special	any special symbol
+> 	 SpecialChar	special character in a constant
+> 	 Tag		you can use CTRL-] on this
+> 	 Delimiter	character that needs attention
+> 	 SpecialComment	special things inside a comment
+> 	 Debug		debugging statements
+> 
+> 	*Underlined	text that stands out, HTML links
+> 
+> 	*Ignore		left blank, hidden  |hl-Ignore|
+> 
+> 	*Error		any erroneous construct
+> 
+> 	*Todo		anything that needs extra attention; mostly the
+> 			keywords TODO FIXME and XXX
+>``` 
+>
+> The names marked with * are the preferred groups; the others are minor groups.
+> For the preferred groups, the "syntax.vim" file contains default highlighting.
+> The minor groups are linked to the preferred groups, so they get the same
+> highlighting.  You can override these defaults by using ":highlight" commands
+> after sourcing the "syntax.vim" file.
+
+The syntax highlighting files for almost all languages define other highlight
+groups most of which get mapped to these basic groups. To define a new
+colorscheme, we need to define color mappings for each of these groups. 
+
+The basic syntax for defining a new color scheme is:
+
+```
+\startcolorscheme[name-of-scheme]
+...
+\stopcolorscheme
+```
+
+where the `name-of-scheme` is whatever name you want to call your colorscheme.
+This name has to be used as the value for `alternative` key in
+`\definevimtyping` or `setupvimtyping`. 
+
+The bare-minimum setup needed to define a new colorscheme is as follows:
+
+```
+\startcolorscheme[name-of-scheme]
+    % Vim Preferred groups
+    \definesyntaxgroup
+        [Constant]
+        [...]
+
+    \definesyntaxgroup
+        [Identifier]
+        [...]
+
+    \definesyntaxgroup
+        [Statement]
+        [...]
+
+    \definesyntaxgroup
+        [PreProc]
+        [...]
+
+    \definesyntaxgroup
+        [Type]
+        [...]
+
+    \definesyntaxgroup
+        [Special]
+        [...]
+
+    \definesyntaxgroup
+        [Comment]
+        [...]
+
+    \definesyntaxgroup
+         [Ignore]
+         [...]
+
+    \definesyntaxgroup
+        [Todo]
+        [...]
+
+
+    \definesyntaxgroup
+        [Error]
+        [...]
+
+    \definesyntaxgroup
+        [Underlined]
+        [...]
+
+    \definesyntaxgroup
+        [Todo]
+        [...]
+
+    \setups{vim-minor-groups}
+
+\stopcolorscheme
+```
+
+The detailed syntax of `\definesyntaxgroup` will be explained in a bit. 
+The `\setups{vim-minor-groups}` line at the end maps the minor color groups to
+the preferred color groups, as per the default mappings in vim. Suppose you
+want to override the default mappings for `Number` and `Function`, then you
+define those mappings after `\setups{vim-minor-groups}`.
+
+```
+\startcolorscheme[name-of-scheme]
+    % Vim Preferred groups
+    \definesyntaxgroup
+        [Constant]
+        [...]
+
+    ....
+
+    \setups{vim-minor-groups}
+
+    \definesyntaxgroup
+        [Number]
+        [...]
+
+    \definesyntaxgroup
+        [Function]
+        [...]
+
+\stopcolorscheme
+```
+
+A full setup for defining a new color scheme will be add `\definesyntaxgroup`
+for all the basic vim syntax highlighting groups listed from the vim help
+above. If you define the mappings for *all* groups, then you can omit the
+`\setups{vim-minor-groups}` line above. 
+
+The `\definesyntaxgroup` command has the following syntax:
+
+```
+\definesyntaxgroup
+    [name-of-group]
+    [
+      color=...,
+      style=...,
+      command=...,
+    ]
+```
+where `color` is the name of any predefined color in ConTeXt, `style` can be
+any predefined [style alternative][style] (such as `bold`, `italic`, etc.) or
+an explicit style formatting command (such as `\bf`, `\it`, etc.), and
+`command` can be any ConTeXt macro which takes one argument. 
+
+[style]: https://wiki.contextgarden.net/Style_Alternatives
+
+For example, if you want to highlight `Todo` with a frame, use can use:
+
+```
+\definesyntaxgroup
+    [Todo]
+    [command=\inframed]
+```
+
+_A convinience interface for `color`:_ A colorscheme uses a lot of colors and
+defining all of them just for the purpose of defining a new colorscheme can be
+cumbersome. So, the `\definesyntaxgroup` macro provides a shorthand:
+
+```
+\definesyntaxgroup
+    [...]
+    [
+      color={r=..., g=..., b=...},
+    ]
+```
+
+where `r`, `g`, `b`, values are the red, green, and blue values (between 0 and
+1) of the color, or
+
+```
+\definesyntaxgroup
+    [...]
+    [
+      color={h=...},
+    ]
+```
+
+where the `h` value is the hex value of the color.
+
+Modifying an existing color scheme
+----------------------------------
+
+It is possible to modify an existing color scheme by simply redefining
+some of the syntax highlighting groups. For example, if we want to update
+`pscolor` so that `Identifier` group is typeset in red color and `Function` is
+typeset in bold red, we can use:
+
+```
+\startcolorscheme[pscolor]
+  \definesyntaxgroup
+      [Identifier]
+      [color=red]
+
+  \definesyntaxgroup
+      [Function]
+      [color=red, style=bold]
+\stopcolorscheme
+```
+
 A bit of a history
 ------------------
 
diff --git a/Master/texmf-dist/tex/context/third/vim/t-syntax-groups.tex b/Master/texmf-dist/tex/context/third/vim/t-syntax-groups.tex
index db526bf77e9..40189fe331c 100644
--- a/Master/texmf-dist/tex/context/third/vim/t-syntax-groups.tex
+++ b/Master/texmf-dist/tex/context/third/vim/t-syntax-groups.tex
@@ -1,6 +1,6 @@
 %D \module
 %D   [     file=t-syntax-groups,
-%D      version=2012.05.06,
+%D      version=2020.06.23,
 %D        title=\CONTEXT\ User Module,
 %D     subtitle=Syntax highlighting support,
 %D       author=Aditya Mahajan,
@@ -9,7 +9,7 @@
 %D        email=adityam <at> ieee <dot> org,
 %D      license=Simplified BSD License]
 
-\writestatus{loading}{Syntax highlighting groups (ver: 2012.05.06)}
+\writestatus{loading}{Syntax highlighting groups (ver: 2020.06.23)}
 
 \startmodule [syntax-group]
 \usemodule   [module-catcodes]
@@ -52,9 +52,9 @@
                           [\s!parent=\syntaxgroup@namespace,\c!color=,\c!style=,\c!command=,#2]
          \doifsomething{\syntaxgroupparameter\c!color}
           {
-             \expanded{\definecolor[\syntaxgroup@namespace-##1-color]
+             \expanded{\definecolor[\syntaxgroup@namespace-\syntaxgroup@name-color]
                                    [\syntaxgroupparameter\c!color]}
-             \setupsyntaxgroup[\syntaxgroup@name][\s!parent=\syntaxgroup@namespace,\c!color=\syntaxgroup@namespace-##1-color]
+             \setupsyntaxgroup[\syntaxgroup@name][\s!parent=\syntaxgroup@namespace,\c!color=\syntaxgroup@namespace-\syntaxgroup@name-color]
           }
     }
   }{
diff --git a/Master/texmf-dist/tex/context/third/vim/t-syntax-highlight.mkiv b/Master/texmf-dist/tex/context/third/vim/t-syntax-highlight.mkiv
index 7c31c8f6a38..a0567301749 100644
--- a/Master/texmf-dist/tex/context/third/vim/t-syntax-highlight.mkiv
+++ b/Master/texmf-dist/tex/context/third/vim/t-syntax-highlight.mkiv
@@ -97,10 +97,10 @@
       {\language\minusone}%
 
   \def\obeyedline{\strut\par}
+  \activatespacehandler{\????syntaxhighlighting\externalfilterparameter\c!space:\externalfilterparameter\c!lines}
   \setcatcodetable\externalfilter@minimal_catcodes%
   \letcharcode\endoflineasciicode\obeyedline
   \letcharcode\spaceasciicode\obeyedspace
-  \activatespacehandler{\????syntaxhighlighting\externalfilterparameter\c!space}
   \raggedright
 \stopsetups
 
@@ -120,7 +120,7 @@
               \c!method=\v!type,
                \c!start=\externalfilterparameter{\c!number\c!start},
                 \c!step=\externalfilterparameter{\c!number\c!step},
-             \c!continue=\externalfilterparameter{\c!number\c!continue},
+            \c!continue=\externalfilterparameter{\c!number\c!continue},
           ]}
    \dostarttagged\t!syntaxhighlighting\colorscheme@name
 \stoptexdefinition
@@ -191,40 +191,40 @@
   ]
 
 % Space handler
-%
-% The space handing code for MkII and MkIV is not consistent. So, we provide our
-% own versions.
 
-\setvalue{\????syntaxhighlighting::\c!lines::\v!split}{\hskip}
-\setvalue{\????syntaxhighlighting::\c!lines::\v!fixed}{\dontleavehmode\kern}
+% Invisible space, don't split
+\installspacemethod {\????syntaxhighlighting\v!off:\v!fixed}
+  {\def\obeyedspace{\mathortext\normalspace\explicitfixedspace}}
 
-% default
-\setvalue{\????syntaxhighlighting::\c!lines::}{\dontleavehmode\kern}
+% Invisible space, allow split
+\installspacemethod {\????syntaxhighlighting\v!off:\v!split}
+  {\def\obeyedspace{\mathortext\normalspace\explicitobeyedspace}}
 
-\def\syntaxhighlighting@split%
-    {\getvalue{\????syntaxhighlighting::\c!lines::\externalfilterparameter\c!lines}}
+% Visible space, don't split
+\installspacemethod {\????syntaxhighlighting\v!on:\v!fixed}
+  {\def\obeyedspace{\mathortext\normalspace\optionalcontrolspace}}
+
+% Visible space, allow split
+\installspacemethod {\????syntaxhighlighting\v!on:\v!split}
+  {\def\obeyedspace{\mathortext\normalspace\explicitcontrolspace}}
+
+% Default: line=empty
+\installspacemethod {\????syntaxhighlighting\v!off:}
+  {\activatespacehandler {\????syntaxhighlighting\v!off:\v!fixed}}
 
-% Visible space
 \installspacemethod {\????syntaxhighlighting\v!on}
-  {\unexpanded\def\obeyedspace
-      {\mathortext\normalspace
-        {\syntaxhighlighting@split\zeropoint\relax
-         \hbox{\normalcontrolspace}%
-         \syntaxhighlighting@split\zeropoint\relax}}%
-  \letcharcode\spaceasciicode\obeyedspace}
-
-% Invisible space
-\installspacemethod {\????syntaxhighlighting\v!off}
-  {\unexpanded\def\obeyedspace
-      {\mathortext\normalspace
-          {\syntaxhighlighting@split\interwordspace\relax}}%
-   \letcharcode\spaceasciicode\obeyedspace}
-
-% Default
-\installspacemethod {\????syntaxhighlighting}
-  {\activatespacehandler {\????syntaxhighlighting\v!off}}
-
-% Line highlighting
+  {\activatespacehandler {\????syntaxhighlighting\v!on:\v!fixed}}
+
+% space=empty, line=something
+\installspacemethod {\????syntaxhighlighting:\v!fixed}
+  {\activatespacehandler {\????syntaxhighlighting\v!off:\v!fixed}}
+
+\installspacemethod {\????syntaxhighlighting:\v!split}
+  {\activatespacehandler {\????syntaxhighlighting\v!off:\v!split}}
+
+% Both empty
+\installspacemethod {\????syntaxhighlighting:}
+  {\activatespacehandler {\????syntaxhighlighting\v!off:\v!fixed}}
 
 \definebar[syntaxhighlightline]
           [\c!order=\v!background,