summaryrefslogtreecommitdiff log msg author committer range
blob: 12c5d10a07614d4b98b4e55795087b2d3169d866 (plain)
 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082  The vim module ============== This module highlights code snippets using vim as a syntax highlighter. Such a task may appear pointless at first glance. After all, ConTeXt provides excellent syntax highlighting features for TeX, Metapost, XML, and a few other languages. And in MkIV, you can specify the grammar to parse a language, and get syntax highlighting for a new language. But writing such grammars is difficult. More importantly, why reinvent the wheel? Most 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) * [XML export](#xml-export) * [A bit of a history](#a-bit-of-a-history) Compatibility ------------ This module works with both MkII and MkIV. To get colors with MkII, use \setupcolors[state=start] If avoid -- and --- to turn into – and — in MkII, use \usetypescript [modern] [texnansi] \setupbodyfont [modern] Both colors and no ligatures work out of the box in MkIV. Installation ------------ This module depends on the t-filter module. If you are using ConTeXt standalone, you can install the module using first-setup.sh --modules="t-filter,t-vim" Depending on your TeX distribution, you may already have the module. To verify, check if 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 [http://github.com/adityam/filter/downloads](http://github.com/adityam/filter/downloads) and unzip them either $TEXMFHOME or $TEXMFLOCAL. Run mtxrun --generate and mktexlsr to refresh the TeX file database (for MkIV and MkII, respectively). If everything went well 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 in MkII, you must set shell_escape=t in your texmf.cnf file. See this page [http://wiki.contextgarden.net/write18](http://wiki.contextgarden.net/write18) on the ConTeXt wiki for detailed instructions. Usage ----- Include the module \usemodule[vim] Suppose you want to syntax highlight Ruby. In particular, you want \startRUBY # Wow, my first ruby program print("Hello World") \stopRUBY to be printed with Ruby syntax highlighting. To get that, define \definevimtyping [RUBY] [syntax=ruby] Yes, its that easy. To get syntax highlighting for a particular language, all you need to know what is its filetype in vim. If you don't know that, start vim and type :help syntax.txt and go through the list of supported languages to find the name of the language that you are interested in. (Oh, and in case you don't know how to quit vim, type :qa!.) Vim supports syntax highlighting for more than 500 programming languages; the t-vim module enables you to use any of them with just one \definevimtyping. The command \definevimtyping [RUBY] [syntax=ruby] defines three things: 1. An environment \startRUBY ... \stopRUBY The contents of this environment are processed by a vim script (2context.vim) and the result is read back in ConTeXt. 2. A macro \inlineRUBY{...} The contents of this macro are processed by a vim script (2context.vim) and the result is read back in ConTeXt. 3. A macro \typeRUBYfile{...} The argument of this macro must a file name or a url (urls work in MkIV only). That file is processed by 2context.vim and the result is read back in ConTeXt. For controling how frequently a remote file is downloaded when processing a url, see the _Processing remote files_ section of the t-filter manual. 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. Start and stop lines -------------------- The \start ... \stop environment and the \typefile macro take an optional argument that is used to set options. For example, to typeset lines 15 through 25 of a ruby file rails_install.rb, use: \typeRUBYfile[start=15,stop=25]{rails_install.rb} To exclude 10 lines from the end, set stop=-10. Changing tab skip ----------------- By default, a literal tab (0x09 or ^I) character has a width of 8 spaces. For most cases, this is too excessive. To reduce the shift of a tab, use the tab key. For example: \definevimtyping [...] [... tab=4, ...] changes the tab width to four spaces. Avoid clutter ------------- Running an external file through vim is slow. So, t-vim reprocesses a snippet or a file only if its contents have changed. To check if the contents have changed, it writes each snippet to a different file and stores the md5 sum of that snippet. As a result, the working directory gets cluttered with lot of temporary files. To avoid this clutter, write the temporary files to a different directory using the directory key. For example, \definevimtyping[...] [directory=output/] ensures that all the temporary files are written to the output directory. See the section on _Output Directory_ in the documentation of t-filter module for more details. Before and after --------------- Like most ConTeXt environments, \definevimtyping also accepts the before and after options. These can be used, for example, to enclose the output in a frame, etc. Changing the color scheme ------------------------- This module provides two colorschemes - pscolor based on ps_color colorscheme for vim by Shi Zhu Pan. - blackandwhite based on print_bw colorscheme for vim by Mike Williams. A particular color scheme may be chosen using the options: \definevimtyping [...] [... alternative=pscolor, ...] The default color scheme is pscolor. See below for instructions on how to define a new colorscheme. Line numbering --------------- **Note**: Currently only works in MkIV. In principle, it should also work in MkII, but for some reasons it does not. To enable line numbering for a particular snippet, use: \start[numbering=yes] ... \stop To enable line numbering for all code snippets, use: \definevimtyping [...] [... numbering=yes, ...] If you want a particular snippet not to have line numbering, use \start[numbering=no] ... \stop By default, numbering starts from one, all lines are numbered, numbering is reset at each snippet, and numbers are displayed on the left. All these defaults can be changed. Number of the first line ------------------------ By default, the numbering starts from one (that is, the first line is numbered 1). If you want the first line to be numbered something else, say 15, you need to set \start[numberstart=15] If you want the numbering to continue from where the previous snippet ended, use \start[numbercontinue=yes] By default, consecutive lines are numbered. If you want alternate lines to be numbered, use \start[numbertstep=2] If you want every fifth line to be numbered, use \start[numbertstep=5] Standard options for line numbering ----------------------------------- **Note**: Linenumbering options can only be set using \definevimtyping[...][...] or \setupvimtyping[...][...]. They do not work when used with \start. 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 numberstyle is set to \ttx. - To change the alignment of numbers, use the numberalign=... option. Default value is flushright. - To change the width of the box in which the numbers are typeset, use numberwidth=... option. Default value is 2em. - To change the distance between the numbers and the rest of the code, use numberdistance=... option. Default value is 0.5em. - To change the conversion of numbers, use numberconversion=... option. Default value is numbers. - Use numberleft=... and numberright=... options to typeset something on the left and right of the number. By default, these options are not set. - numbercommand=... is used to set a command for typesetting the number. - numberlocation=... is used to set the location of the numbers. Default value is left. Change this to right if you want the numbers on the right. Spaces ------ By default, the space is invisible. If you want to make the space visible, set \definevimtyping [...] [... space=on, ...] The default value is space=off. Removing leading spaces ----------------------- If you are listing a code snippet inside another environment, it is common to indent the TeX code. For example: \definevimtyping[C][syntax=C] \definevimtyping[ruby][syntax=ruby] \startitemize \item A hello world example in C \startC #include int main() { printf("Hello World") } \stopC \item A hello world example in ruby \startruby puts "Hello World" \stopruby \stopitemize By default, the leading whitespace is stripped so that the output is the same as \startitemize \item A hello world example in C \startC #include int main() { printf("Hello World") } \stopC \item A hello world example in ruby \startruby puts "Hello World" \stopruby \stopitemize If you want to disable this, set \definevimtyping [...] [... strip=no, ...] The default value of strip is ψyes. Adding left margin ------------------ By default, a  environment resets the left skip to 0pt, so each line is aligned to the left edge. Use the margin key to change the left skip of each line: \definevimtyping [...] [... margin=, ...] where  is a valid TeX dimension. Wrapping lines --------------- By default, long lines are not wrapped. If your source code has long lines, there are two alternatives. First, you can allow the lines to break at spaces by setting \definevimtyping [...] [... lines=split, ...] The default value is lines=fixed. Second, you can allow lines to break between _compound_ words, such as long/path, long-path, long+path, etc by setting \definevimtyping [...] [... option={packed,hyphenated}, ...] The default value of option is packed. Note that with both these alternatives do not hyphenate a word, merely break lines at spaces or at the boundary of compound words. If you really need to hyphenate words, use \definevimtyping [...] [... option={packed,hyphenated}, align=hyphenated, ...] Note that you have to add **both** option=hyphenated and align=hyphenated. The default value of align is nothypenated. Highlighting lines ------------------ Sometimes you want to draw attention to a particular line (or set of lines). One way to do so it to highlight the lines by a background color. This can be done using: \start[highlight={}] ... \stop where  is a comma separated list. For example, if you want to highlight lines 1 and 5, you may use: \start[highlight={1,5}] ... \stop This will highlight lines 1 and 5 with gray background color. To change the highlight color use \definevimtyping [...] [... highlightcolor=, ...] where  is any valid ConTeXt color. When you pass a comma list to highlight, the 2context.vim script wraps **each** of those line around \HGL{....} macro. The \HGL is, in turn, set to the value of highlightcommand key. So, if you want to change the way highlighting works, change the highlightcommand: \definevimtyping [...] [... highlightcommand=, ...] where  is any valid ConTeXt command. The default value is highlightcommand is \syntaxhighlightline; in MkIV, \syntaxhighlightline is defined as a bar; in MkII, \syntaxhighlightline is defined as a text background. The bar mechanism is more efficient but both mechanisms behave differently. The text background starts from the left edge of the line, while the bar starts from the first non-blank character. Using TeX code in Comments -------------------------- 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=comment, ] For backward compatibility, this feature can also be enabled using 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} * using the determinant \m{\Delta=\frac{-b\pm\sqrt{b^2-2ac}}{2a}} */ double root (double a, double b, double c) {....} \stopC **Note** that only \ { } have their usual meaning inside the Comment 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 or the output typeset by ConTeXt has to be manually tested for correctness prior to the release of your document. 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 -------------------- Some vim syntax files have optional features that are turned on or off using variables. To enable these optional features, you need to first create a vimrc file and then use it. To create a vimrc file, use \startvimrc[name=...] ... \stopvimrc The name=... is necessary. To enable the settings in this vimrc file, use: \definevimtyping [...] [... vimrc=..., ...] The value of vimrc key needs to be the same as the value of the name key in \startvimrc. You may set the vimrc file for a particular code snippet by \start[vimrc=....] .. \stop To disable loading of vimrc file, use \definevimtyping [...] [... vimrc=, ...] The default is not to use any vimrc file. A vimrc file gets loaded before syntax highlighting is enabled. If you want to override the default syntax highlighting scheme, add the appropriate syn ... commands to a vimrc file, and source that using \definevimtyping [...] [... extras=, ...] For example, suppose you are using a C++ library that defines uDouble as a keyword, so you want to highlight it in your code. Use \startvimrc[name=cpp_extras] syn keyword Type uDouble \stopvimrc \definevimtyping [cpp] [ syntax=cpp, extras=cpp_extras, ] Messages and Tracing -------------------- The vim module uses the filter module in the background. The filter module outputs some diagnostic information on the console output to indicate what is happening. For example, for each code snippet, you will see messages like t-filter > command : vim -u NONE -e -s -C -n -c "set tabstop=4" -c "syntax on" -c "set syntax=scala" -c "let contextstartline=1" -c "let contextstopline=0" -c "source kpse:2context.vim" -c "qa" scala-temp-SCALA-0.tmp scala-temp-SCALA-0.vimout If, for some reason, the output file is not generated, or not found, a message similar to t-filter > file matlab-temp-MATLAB-0.vimout cannot be found t-filter > current filter : MATLAB t-filter > base file : matlab-temp-MATLAB-0 t-filter > input file : matlab-temp-MATLAB-0.tmp t-filter > output file : matlab-temp-MATLAB-0.vimout is displayed in the console. At the same time, the string [[output file missing]] is displayed in the PDF output. This data, along with the filter command, is useful for debugging what whet wrong. Yes, on, whatever ----------------- ConTeXt has two ways of indicating binary options: - option=yes and option=no - option=on and option=off The core commands freely switch between the two. In some cases, option=yes has a different meaning than option=on. To avoid confusion, I have made these synonyms. Thus, whenever the documentation says option=yes, you may use option=on. And vice-versa. One less thing to worry about! Name (and location) of the VIM executable ----------------------------------------- By default, the t-vim module calls the program vim to do syntax highlighting. If the vim program is not in the $PATH, the vimcommand option may be used to specify the compete path of vim: \setupvimtyping[vimcommand=/path/to/vim] This option may also be used to call [Neovim] instead of vim to do syntax highlighting, by either using \setupvimtyping[vimcommand=nvim] or, if nvim is not in the $PATH, using \setupvimtyping[vimcommand=/path/to/nvim] [Neovim]: https://neovim.io/ 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  XML Export ---------- The vim module provides a basic support for XML export. If the user-document contains \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 # Python program listing def foobar print("Hello World") The name of the exported envionment is vimtyping. Inline environments such as \definevimtyping[PYTHON][syntax=python] \inlinePYTHON{print("Hello World")} is exported as print("Hello World") 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 . 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 ------------------ Mojca Miklavec germinated the idea of using vim to get syntax highlighting. Below is her message to the ConTeXt mailing list (circa Sep 2005): > I am thinking of piping the code to vim, letting vim process it, and return > something like highlight[Conditional]{if} \highlight[Delimiter]{(} > \highlight[Identifier]{!}. > > One could modify the 2html.vim file. Vim can already transform the highlighted > code to HTML, so ConTeXt should not be so difficult. Vim already has over 400 > syntax file definitions, probably equivalent to some hundred thousand lines of > syntax definition in ConTexT. Well, I don't know (yet) how to do it, but if > someone on the last has more experience with vim, please feel free to > contribute. A few months later (circa Dec 2005), Nikolai Webull provided such a modification of 2html.vim and called it 2context.vim. That file was the foundation of t-vim module. About two years later (circa June 2008), Mojca and I (Aditya Mahajan) pickup up on this idea and released t-vim. Over the next few years, nothing much changed in the module, except a few minor bug fixes. Around June 2010, I decided to completely rewrite the module from scratch. The new version of t-vim relies on t-filter for all the bookkeeping. As a result, the module is smaller and more robust.