Add VimHelp.sublime-syntax and its test

2 files changed, 523 insertions, 0 deletions

diff --git a/assets/syntaxes/02_Extra/VimHelp.sublime-syntax b/assets/syntaxes/02_Extra/VimHelp.sublime-syntax
new file mode 100644
index 00000000..727a3cac
--- /dev/null
+++ b/assets/syntaxes/02_Extra/VimHelp.sublime-syntax
@@ -0,0 +1,104 @@
+%YAML 1.2
+---
+# http://www.sublimetext.com/docs/syntax.html
+scope: source.vimhelp
+file_extensions:
+  # shortname
+  - vimhelp
+
+# $VIMRUNTIME/syntax/help.vim
+contexts:
+  main:
+    - match: '(?<=^\s*)(vim?|ex):\s*([a-z]+(=[^\s:]+)?(\s+|:))+'
+      scope: comment.line.modeline.vimhelp
+    - match: '^[-A-Z .][-A-Z0-9 .()_]*(?=\s+\*|$)'
+      scope: markup.heading.headline.vimhelp
+    - match: '^(===.*===)$'
+      captures:
+        1: punctuation.definition.heading.1.setext.vimhelp
+      push:
+        - meta_scope: markup.heading.1.setext.vimhelp
+        - match: '\t|  '
+          pop: true
+    - match: '^(---.*---)$'
+      captures:
+        1: punctuation.definition.heading.2.setext.vimhelp
+      push:
+        - meta_scope: markup.heading.2.setext.vimhelp
+        - match: '\t|  '
+          pop: true
+    - match: '(?:^| )(>)$'
+      captures:
+        1: punctuation.definition.blockquote.begin.vimhelp
+      push:
+        - meta_scope: markup.quote.vimhelp
+        - match: '^(<)'
+          captures:
+            1: punctuation.definition.blockquote.end.vimhelp
+          pop: true
+        - match: '^(?=\S)'
+          pop: true
+    - match: '(?<!\\)(\|)([#-)!+-~]+)(\|)'
+      captures:
+        1: punctuation.definition.link.begin.vimhelp
+        2: markup.underline.link.vimhelp
+        3: punctuation.definition.link.end.vimhelp
+    - match: '(\*)([#-)!+-~]+)(\*)(?:\s|$)'
+      captures:
+        1: punctuation.definition.constant.begin.vimhelp
+        2: entity.name.reference.link.vimhelp
+        3: punctuation.definition.constant.end.vimhelp
+    - match: '\bVim version [0-9][0-9.a-z]*'
+      scope: variable.language.vimhelp
+    - match: 'N?VIM REFERENCE.*'
+      scope: variable.language.vimhelp
+    - match: '('')([a-z]{2,}|t_..)('')'
+      captures:
+        1: punctuation.definition.link.option.begin.vimhelp
+        2: markup.underline.link.option.vimhelp
+        3: punctuation.definition.link.option.end.vimhelp
+    - match: '(`)([^` \t]+)(`)'
+      captures:
+        1: punctuation.definition.link.command.begin.vimhelp
+        2: markup.underline.link.command.vimhelp
+        3: punctuation.definition.link.command.end.vimhelp
+    - match: '(?<=^|[^a-z"\[])(`)([^`]+)(`)(?=[^a-z\t."'']|$)'
+      captures:
+        1: punctuation.definition.link.command.begin.vimhelp
+        2: markup.underline.link.command.vimhelp
+        3: punctuation.definition.link.command.end.vimhelp
+    - match: '(?<=\s*)(.*?)(?=\s?)(~)$'
+      captures:
+        1: markup.heading.header.vimhelp
+        2: punctuation.definition.keyword.vimhelp
+    - match: '(.*) (?=`$)'
+      captures:
+        1: variable.other.graphic.vimhelp
+        2: punctuation.definition.keyword.vimhelp
+    - match: '\b(note:?|Note:?|NOTE:?|Notes:?)\b'
+      scope: constant.other.note.vimhelp
+    - match: '\b(WARNING:?|Warning:)\b'
+      scope: constant.other.warning.vimhelp
+    - match: '\b(DEPRECATED:?|Deprecated:)\b'
+      scope: constant.other.deprecated.vimhelp
+    - match: '(\{)([-_a-zA-Z0-9''"*+/:%#=\[\]<>.,]+)(\})'
+      captures:
+        1: punctuation.definition.constant.begin.vimhelp
+        2: constant.numeric.vimhelp
+        3: punctuation.definition.constant.end.vimhelp
+    - match: '\[(range|line|count|offset|\+?cmd|(\+|-|)num|\+\+opt)\]'
+      scope: constant.numeric.vimhelp
+    - match: '\[(arg(uments)?|ident|addr|group)\]'
+      scope: constant.numeric.vimhelp
+    - match: '\[(readonly|fifo|socket|converted|crypted)\]'
+      scope: constant.numeric.vimhelp
+    - match: '<[-a-zA-Z0-9_]+>'
+      scope: markup.underline.link.key.vimhelp
+    - match: '<[SCM]-.>'
+      scope: markup.underline.link.key.vimhelp
+    - match: 'CTRL-((SHIFT-)?.|Break|PageUp|PageDown|Insert|Del|\{char\})'
+      scope: markup.underline.link.key.vimhelp
+    - match: '(META|ALT)-.'
+      scope: markup.underline.link.key.vimhelp
+    - match: '\b(((https?|ftp|gopher)://|(mailto|file|news):)[^'' 	<>"]+|(www|web|w3)[a-z0-9_-]*\.[a-z0-9._-]+\.[^'' 	<>"]+)[a-zA-Z0-9/]'
+      scope: markup.underline.link.url.vimhelp
diff --git a/assets/syntaxes/02_Extra/syntax_test_helphelp.txt b/assets/syntaxes/02_Extra/syntax_test_helphelp.txt
new file mode 100644
index 00000000..ea8d5cd7
--- /dev/null
+++ b/assets/syntaxes/02_Extra/syntax_test_helphelp.txt
@@ -0,0 +1,419 @@
+# SYNTAX TEST "VimHelp.sublime-syntax"
+*helphelp.txt*	Nvim
+# <- punctuation.definition.constant.begin
+#^^^^^^^^^^^^ entity.name.reference.link
+#            ^ punctuation.definition.constant.end
+
+
+		  VIM REFERENCE MANUAL    by Bram Moolenaar
+#   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ variable.language
+
+
+Help on help files					*helphelp*
+
+                                      Type |gO| to see the table of contents.
+#                                          ^ punctuation.definition.link.begin
+#                                           ^^ markup.underline.link
+#                                             ^ punctuation.definition.link.end
+
+==============================================================================
+#^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ punctuation.definition.heading.1.setext
+1. Help commands					*online-help*
+#^^^^^^^^^^^^^^^ markup.heading.1.setext
+
+			*help* *<Help>* *:h* *:help* *<F1>* *i_<F1>* *i_<Help>*
+<Help>		or
+#^^^^^ markup.underline.link.key
+:h[elp]			Open a window and display the help file in read-only
+			mode.  If there is a help window open already, use
+			that one.  Otherwise, if the current window uses the
+			full width of the screen or is at least 80 characters
+			wide, the help window will appear just above the
+			current window.  Otherwise the new window is put at
+			the very top.
+			The 'helplang' option is used to select a language, if
+#      ^ punctuation.definition.link.option.begin
+#       ^^^^^^^^ markup.underline.link.option
+#               ^ punctuation.definition.link.option.end
+			the main help file is available in several languages.
+
+			Type |gO| to see the table of contents.
+
+						*{subject}* *E149* *E661*
+:h[elp] {subject}	Like ":help", additionally jump to the tag {subject}.
+			For example:  >
+				:help options
+
+<			{subject} can include wildcards such as "*", "?" and
+#   ^ punctuation.definition.constant.begin
+#    ^^^^^^^ constant.numeric
+#           ^ punctuation.definition.constant.end
+			"[a-z]":
+			   :help z?	jump to help for any "z" command
+			   :help z.	jump to the help for "z."
+			But when a tag exists it is taken literally:
+			   :help :?	jump to help for ":?"
+
+			If there is no full match for the pattern, or there
+			are several matches, the "best" match will be used.
+			A sophisticated algorithm is used to decide which
+			match is better than another one.  These items are
+			considered in the computation:
+			- A match with same case is much better than a match
+			  with different case.
+			- A match that starts after a non-alphanumeric
+			  character is better than a match in the middle of a
+			  word.
+			- A match at or near the beginning of the tag is
+			  better than a match further on.
+			- The more alphanumeric characters match, the better.
+			- The shorter the length of the match, the better.
+
+			The 'helplang' option is used to select a language, if
+			the {subject} is available in several languages.
+			To find a tag in a specific language, append "@ab",
+			where "ab" is the two-letter language code.  See
+			|help-translated|.
+
+			Note that the longer the {subject} you give, the less
+			matches will be found.  You can get an idea how this
+			all works by using commandline completion (type CTRL-D
+#                                                  ^^^^^^ markup.underline.link.key
+			after ":help subject" |c_CTRL-D|).
+			If there are several matches, you can have them listed
+			by hitting CTRL-D.  Example: >
+				:help cont<Ctrl-D>
+
+<			Instead of typing ":help CTRL-V" to search for help
+			for CTRL-V you can type: >
+				:help ^V
+<			This also works together with other characters, for
+			example to find help for CTRL-V in Insert mode: >
+				:help i^V
+<
+			It is also possible to first do ":help" and then
+			use ":tag {pattern}" in the help window.  The
+			":tnext" command can then be used to jump to other
+			matches, "tselect" to list matches and choose one. >
+				:help index
+				:tselect /.*mode
+
+<			When there is no argument you will see matches for
+			"help", to avoid listing all possible matches (that
+			would be very slow).
+			The number of matches displayed is limited to 300.
+
+			The `:help` command can be followed by '|' and another
+			command, but you don't need to escape the '|' inside a
+			help command.  So these both work: >
+				:help |
+				:help k| only
+<			Note that a space before the '|' is seen as part of
+#   ^^^^ constant.other.note
+			the ":help" argument.
+			You can also use <NL> or <CR> to separate the help
+			command from a following command.  You need to type
+			CTRL-V first to insert the <NL> or <CR>.  Example: >
+				:help so<C-V><CR>only
+<
+
+:h[elp]! [subject]	Like ":help", but in non-English help files prefer to
+			find a tag in a file with the same language as the
+			current file.  See |help-translated|.
+
+							*:helpc* *:helpclose*
+:helpc[lose]		Close one help window, if there is one.
+			Vim will try to restore the window layout (including
+			cursor position) to the same layout it was before
+			opening the help window initially.  This might cause
+			triggering several autocommands.
+
+							*:helpg* *:helpgrep*
+:helpg[rep] {pattern}[@xx]
+			Search all help text files and make a list of lines
+			in which {pattern} matches.  Jumps to the first match.
+			The optional [@xx] specifies that only matches in the
+			"xx" language are to be found.
+			You can navigate through the matches with the
+			|quickfix| commands, e.g., |:cnext| to jump to the
+			next one.  Or use |:cwindow| to get the list of
+			matches in the quickfix window.
+			{pattern} is used as a Vim regexp |pattern|.
+			'ignorecase' is not used, add "\c" to ignore case.
+			Example for case sensitive search: >
+				:helpgrep Uganda
+<			Example for case ignoring search: >
+				:helpgrep uganda\c
+<			Example for searching in French help: >
+				:helpgrep backspace@fr
+<			The pattern does not support line breaks, it must
+			match within one line.  You can use |:grep| instead,
+			but then you need to get the list of help files in a
+			complicated way.
+			Cannot be followed by another command, everything is
+			used as part of the pattern.  But you can use
+			|:execute| when needed.
+			Compressed help files will not be searched (Fedora
+			compresses the help files).
+
+							*:lh* *:lhelpgrep*
+:lh[elpgrep] {pattern}[@xx]
+			Same as ":helpgrep", except the location list is used
+			instead of the quickfix list.  If the help window is
+			already opened, then the location list for that window
+			is used.  Otherwise, a new help window is opened and
+			the location list for that window is set.  The
+			location list for the current window is not changed
+			then.
+
+							*:exu* *:exusage*
+:exu[sage]		Show help on Ex commands.  Added to simulate the Nvi
+			command.
+
+							*:viu* *:viusage*
+:viu[sage]		Show help on Normal mode commands.  Added to simulate
+			the Nvi command.
+
+When no argument is given to |:help| the file given with the 'helpfile' option
+will be opened.  Otherwise the specified tag is searched for in all "doc/tags"
+files in the directories specified in the 'runtimepath' option.
+
+If you would like to open the help in the current window, see this tip:
+|help-curwin|.
+
+The initial height of the help window can be set with the 'helpheight' option
+(default 20).
+						*help-buffer-options*
+When the help buffer is created, several local options are set to make sure
+the help text is displayed as it was intended:
+    'iskeyword'		nearly all ASCII chars except ' ', '*', '"' and '|'
+    'foldmethod'	"manual"
+    'tabstop'		8
+    'arabic'		off
+    'binary'		off
+    'buflisted'		off
+    'cursorbind'	off
+    'diff'		off
+    'foldenable'	off
+    'list'		off
+    'modifiable'	off
+    'number'		off
+    'relativenumber'	off
+    'rightleft'		off
+    'scrollbind'	off
+    'spell'		off
+
+Jump to specific subjects by using tags.  This can be done in two ways:
+- Use the "CTRL-]" command while standing on the name of a command or option.
+  This only works when the tag is a keyword.  "<C-Leftmouse>" and
+  "g<LeftMouse>" work just like "CTRL-]".
+- use the ":ta {subject}" command.  This also works with non-keyword
+  characters.
+
+Use CTRL-T or CTRL-O to jump back.
+Use ":q" to close the help window.
+
+If there are several matches for an item you are looking for, this is how you
+can jump to each one of them:
+1. Open a help window
+2. Use the ":tag" command with a slash prepended to the tag.  E.g.: >
+	:tag /min
+3. Use ":tnext" to jump to the next matching tag.
+
+It is possible to add help files for plugins and other items.  You don't need
+to change the distributed help files for that.  See |add-local-help|.
+
+To write a local help file, see |write-local-help|.
+
+Note that the title lines from the local help files are automagically added to
+the "LOCAL ADDITIONS" section in the "help.txt" help file |local-additions|.
+This is done when viewing the file in Vim, the file itself is not changed.  It
+is done by going through all help files and obtaining the first line of each
+file.  The files in $VIMRUNTIME/doc are skipped.
+
+							*help-xterm-window*
+If you want to have the help in another xterm window, you could use this
+command: >
+	:!xterm -e vim +help &
+<
+
+					*:helpt* *:helptags*
+			*E150* *E151* *E152* *E153* *E154* *E670* *E856*
+:helpt[ags] [++t] {dir}
+			Generate the help tags file(s) for directory {dir}.
+			When {dir} is ALL then all "doc" directories in
+			'runtimepath' will be used.
+
+			All "*.txt" and "*.??x" files in the directory and
+			sub-directories are scanned for a help tag definition
+			in between stars.  The "*.??x" files are for
+			translated docs, they generate the "tags-??" file, see
+			|help-translated|.  The generated tags files are
+			sorted.
+			When there are duplicates an error message is given.
+			An existing tags file is silently overwritten.
+
+			The optional "++t" argument forces adding the
+			"help-tags" tag.  This is also done when the {dir} is
+			equal to $VIMRUNTIME/doc.
+
+			To rebuild the help tags in the runtime directory
+			(requires write permission there): >
+				:helptags $VIMRUNTIME/doc
+<
+
+
+==============================================================================
+2. Translated help files				*help-translated*
+
+It is possible to add translated help files, next to the original English help
+files.  Vim will search for all help in "doc" directories in 'runtimepath'.
+
+At this moment translations are available for:
+	Chinese  - multiple authors
+	French   - translated by David Blanchet
+	Italian  - translated by Antonio Colombo
+	Japanese - multiple authors
+	Polish   - translated by Mikolaj Machowski
+	Russian  - translated by Vassily Ragosin
+See the Vim website to find them: http://www.vim.org/translations.php
+
+A set of translated help files consists of these files:
+
+	help.abx
+	howto.abx
+	...
+	tags-ab
+
+"ab" is the two-letter language code.  Thus for Italian the names are:
+
+	help.itx
+	howto.itx
+	...
+	tags-it
+
+The 'helplang' option can be set to the preferred language(s).  The default is
+set according to the environment.  Vim will first try to find a matching tag
+in the preferred language(s).  English is used when it cannot be found.
+
+To find a tag in a specific language, append "@ab" to a tag, where "ab" is the
+two-letter language code.  Example: >
+	:he user-manual@it
+	:he user-manual@en
+The first one finds the Italian user manual, even when 'helplang' is empty.
+The second one finds the English user manual, even when 'helplang' is set to
+"it".
+
+When using command-line completion for the ":help" command, the "@en"
+extension is only shown when a tag exists for multiple languages.  When the
+tag only exists for English "@en" is omitted.  When the first candidate has an
+"@ab" extension and it matches the first language in 'helplang' "@ab" is also
+omitted.
+
+When using |CTRL-]| or ":help!" in a non-English help file Vim will try to
+find the tag in the same language.  If not found then 'helplang' will be used
+to select a language.
+
+Help files must use latin1 or utf-8 encoding.  Vim assumes the encoding is
+utf-8 when finding non-ASCII characters in the first line.  Thus you must
+translate the header with "For Vim version".
+
+The same encoding must be used for the help files of one language in one
+directory.  You can use a different encoding for different languages and use
+a different encoding for help files of the same language but in a different
+directory.
+
+Hints for translators:
+- Do not translate the tags.  This makes it possible to use 'helplang' to
+  specify the preferred language.  You may add new tags in your language.
+- When you do not translate a part of a file, add tags to the English version,
+  using the "tag@en" notation.
+- Make a package with all the files and the tags file available for download.
+  Users can drop it in one of the "doc" directories and start use it.
+  Report this to Bram, so that he can add a link on www.vim.org.
+- Use the |:helptags| command to generate the tags files.  It will find all
+  languages in the specified directory.
+
+==============================================================================
+3. Writing help files					*help-writing*
+
+For ease of use, a Vim help file for a plugin should follow the format of the
+standard Vim help files, except for the first line.  If you are writing a new
+help file it's best to copy one of the existing files and use it as a
+template.
+
+The first line in a help file should have the following format:
+
+*plugin_name.txt*	{short description of the plugin}
+
+The first field is a help tag where ":help plugin_name" will jump to.  The
+remainder of the line, after a Tab, describes the plugin purpose in a short
+way.  This will show up in the "LOCAL ADDITIONS" section of the main help
+file.  Check there that it shows up properly: |local-additions|.
+
+If you want to add a version number or last modification date, put it in the
+second line, right aligned.
+
+At the bottom of the help file, place a Vim modeline to set the 'textwidth'
+and 'tabstop' options and the 'filetype' to "help".  Never set a global option
+in such a modeline, that can have undesired consequences.
+
+
+TAGS
+
+To define a help tag, place the name between asterisks (*tag-name*).  The
+tag-name should be different from all the Vim help tag names and ideally
+should begin with the name of the Vim plugin.  The tag name is usually right
+aligned on a line.
+
+When referring to an existing help tag and to create a hot-link, place the
+name between two bars (|) eg. |help-writing|.
+
+When referring to a Vim command and to create a hot-link, place the
+name between two backticks, eg. inside `:filetype`.  You will see this is
+highlighted as a command, like a code block (see below).
+
+When referring to a Vim option in the help file, place the option name between
+two single quotes, eg. 'statusline'
+
+When referring to any other technical term, such as a filename or function
+parameter, surround it in backticks, eg. `~/.path/to/init.vim`.
+
+
+HIGHLIGHTING
+
+To define a column heading, use a tilde character at the end of the line.
+This will highlight the column heading in a different color.  E.g.
+
+Column heading~
+#^^^^^^^^^^^^^ markup.heading.header
+#             ^ punctuation.definition.keyword
+
+To separate sections in a help file, place a series of '=' characters in a
+line starting from the first column.  The section separator line is highlighted
+differently.
+
+To quote a block of ex-commands verbatim, place a greater than (>) character
+at the end of the line before the block and a less than (<) character as the
+first non-blank on a line following the block.  Any line starting in column 1
+also implicitly stops the block of ex-commands before it.  E.g. >
+    function Example_Func()
+	echo "Example"
+    endfunction
+<
+
+The following are highlighted differently in a Vim help file:
+  - a special key name expressed either in <> notation as in <PageDown>, or
+    as a Ctrl character as in CTRL-X
+  - anything between {braces}, e.g. {lhs} and {rhs}
+
+The word "Note", "Notes" and similar automagically receive distinctive
+highlighting.  So do these:
+	*Todo	something to do
+	*Error	something wrong
+
+You can find the details in $VIMRUNTIME/syntax/help.vim
+
+
+ vim:tw=78:ts=8:noet:ft=help:norl:
+#^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ comment.line.modeline