path: root/macros/context/contrib/context-vim/doc/context/third/vim/vim.txt
diff options
Diffstat (limited to 'macros/context/contrib/context-vim/doc/context/third/vim/vim.txt')
1 files changed, 89 insertions, 10 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 88bc2b9dc6..12c5d10a07 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
@@ -37,6 +37,7 @@ Table of Contents
* [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)
+* [XML export](#xml-export)
* [A bit of a history](#a-bit-of-a-history)
@@ -69,30 +70,30 @@ standalone, you can install the module using
Depending on your TeX distribution, you may already have the module.
To verify, check if
- kpsewhich t-vim.tex
+ luatools t-vim.tex
returns a meaningful path. If not, you have to manually install the module.
Download the latest version of the `filter` and `vim` modules from
and unzip them either `$TEXMFHOME` or `$TEXMFLOCAL`. Run
- mktexlsr
+ mtxrun --generate
- mtxrun --generate
+ mktexlsr
-to refresh the TeX file database (for MkII and MkIV, respectively). If
+to refresh the TeX file database (for MkIV and MkII, respectively). If
everything went well
- kpsewhich t-vim
+ luatools t-vim
will return the path where you stored the file.
Unfortunately, that is not enough. For the module to work, TeX must be able to
call an external program. This feature is a potential security risk and is
-disabled by default on most TeX distributions. To enable this feature, you must
+disabled by default on most TeX distributions. To enable this feature in MkII,
+you must set
@@ -297,9 +298,12 @@ If you want every fifth line to be numbered, use
Standard options for line numbering
-**Note**: These options can only be set using `\definevimtyping[...][...]` or
-`\setupvimtyping[...][...]`. They do not work when used with
+**Note**: Linenumbering options can only be set using `\definevimtyping[...][...]`
+or `\setupvimtyping[...][...]`. They do not work when used with
+`\start<vimtyping>`. All the line numbers on a given page have the same
+properties. So, if you change these properties in the middle of the page, it
+will effect all the listings on that page, _even those defined earlier!_
- To change the color or style of the numbers, use the `numbercolor=...` and
`numberstyle=...` options. By default `numbercolor` is not set, while
@@ -971,6 +975,81 @@ typeset in bold red, we can use:
[color=red, style=bold]
+XML Export
+The vim module provides a basic support for XML export. If the user-document
+ \setupbackend[export=yes]
+or other valid options to `export` such as `export=xml`, then the vim typing
+environments are exported as well. For example,
+ \definevimtyping[PYTHON][syntax=python]
+ \startPYTHON
+ # Python program listing
+ def foobar
+ print("Hello World")
+ \stopPYTHON
+is exported as
+ <vimtyping detail="pscolor">
+ <verbatimline><syntaxgroup detail="vimComment"># Python program listing</syntaxgroup></verbatimline>
+ <verbatimline><syntaxgroup detail="vimStatement">def</syntaxgroup> <syntaxgroup detail="vimFunction">foobar</syntaxgroup></verbatimline>
+ <verbatimline> <syntaxgroup detail="vimFunction">print</syntaxgroup>(<syntaxgroup detail="vimString">"</syntaxgroup><syntaxgroup detail="vimString">Hello World</syntaxgroup><syntaxgroup detail="vimString">"</syntaxgroup>)</verbatimline>
+ </vimtyping>
+The name of the exported envionment is `vimtyping`.
+Inline environments such as
+ \definevimtyping[PYTHON][syntax=python]
+ \inlinePYTHON{print("Hello World")}
+is exported as
+ <inlinevimtyping detail="pscolor"><verbatimline><syntaxgroup detail="vimFunction">print</syntaxgroup>(<syntaxgroup detail="vimString">"</syntaxgroup><syntaxgroup detail="vimString">Hello World</syntaxgroup><syntaxgroup detail="vimString">"</syntaxgroup>)</verbatimline></inlinevimtyping>
+The name of the exported envionment is `inlinevimtyping`.
+In both the display and inline environments, the name of the programming
+language (value of the `syntax` key) is
+not exported since it is not needed to display the parse output.
+Instead the name of the colorscheme (value of the `alternative` key) is
+exported as the parameter `detail` of `vimtyping`. Each line is exported as a
+`verbatimline`. Each syntaxgroup is exported as `<syntaxgroup detail="...">`.
+The value of `defail` equals to the name of the syntax highlighting group
+_prepended with `vim`_. The name is prepended with `vim` to avoid name clashes
+with other elements in the exported XML. Strictly speaking this is not
+necessary, but it does make it easier to write CSS selectors.
+The module comes with a CSS file with default mappings for the two
+colorschemes that are provided with the module (`pscolor` and
+`blackandwhite`). This is meant as a simple solution which gives approximately
+the same output as the PDF file. To use this CSS file, add
+ \setupexport[cssfile=\vimtypingcssfile]
+If you already have other values for `cssfile`, then use:
+ \setupexport[cssfile={...,...,\vimtypingcssfile}]
+Note that the macro `\vimtypingcssfile` is defined in the vim module, so the
+above line has to come after the `vim` module has been loaded.
+If you make changes to the default colorschemes, define colorschemes of your
+own, or want to tweak the visual appearance of the output, you need to tweak
+the default CSS file to suit your needs. It is suggested that you copy the
+default css file and tweak it. You can find the location of the default CSS
+file using
+ luatools vimtyping-default.css
+Copy it under a different name and tweak it as desired.
A bit of a history