]> git.wincent.com - vim-docvim.git/blob - after/syntax/vim.vim
Switch to MIT license
[vim-docvim.git] / after / syntax / vim.vim
1 ""
2 " @plugin docvim Syntax highlighting for docvim comments
3 "
4 "                                                                    *vim-docvim*
5 " # Intro
6 "
7 " vim-docvim provides syntax highlighting for Vim script files that contain
8 " embedded docvim comments.
9 "
10 " docvim (the tool, not this plug-in) is a documentation generator that
11 " processes those embedded comments and produces documentation in Markdown and
12 " Vim "help" formats. To avoid confusion, this document refers to the Vim
13 " plug-in as "vim-docvim" and the separate generation tool as "docvim".
14 "
15 "
16 " # Installation
17 "
18 " To install vim-docvim, use your plug-in management system of choice.
19 "
20 " If you don't have a "plug-in management system of choice", I recommend
21 " Pathogen (https://github.com/tpope/vim-pathogen) due to its simplicity and
22 " robustness. Assuming that you have Pathogen installed and configured, and that
23 " you want to install vim-docvim into `~/.vim/bundle`, you can do so with:
24 "
25 " ```
26 " git clone https://github.com/wincent/vim-docvim.git ~/.vim/bundle/vim-docvim
27 " ```
28 "
29 " Alternatively, if you use a Git submodule for each Vim plug-in, you could do
30 " the following after `cd`-ing into the top-level of your Git superproject:
31 "
32 " ```
33 " git submodule add https://github.com/wincent/vim-docvim.git ~/vim/bundle/vim-docvim
34 " git submodule init
35 " ```
36 "
37 " To generate help tags under Pathogen, you can do so from inside Vim with:
38 "
39 " ```
40 " :call pathogen#helptags()
41 " ```
42 "
43 "
44 " # Related
45 "
46 " The docvim tool itself is an NPM module, available at:
47 "
48 "   https://www.npmjs.com/package/docvim
49 "
50 " The official source code repo is at:
51 "
52 "   http://git.wincent.com/docvim.git
53 "
54 " A mirror exists at:
55 "
56 "   https://github.com/wincent/docvim
57 "
58 "
59 " # Website
60 "
61 " The official vim-docvim source code repo is at:
62 "
63 "   http://git.wincent.com/vim-docvim.git
64 "
65 " A mirror exists at:
66 "
67 "   https://github.com/wincent/vim-docvim
68 "
69 " Official releases are listed at:
70 "
71 "   http://www.vim.org/scripts/script.php?script_id=[TODO]
72 "
73 "
74 " # License
75 "
76 " Copyright (c) 2015-present Greg Hurrell
77 "
78 " Permission is hereby granted, free of charge, to any person obtaining
79 " a copy of this software and associated documentation files (the
80 " "Software"), to deal in the Software without restriction, including
81 " without limitation the rights to use, copy, modify, merge, publish,
82 " distribute, sublicense, and/or sell copies of the Software, and to
83 " permit persons to whom the Software is furnished to do so, subject to
84 " the following conditions:
85 "
86 " The above copyright notice and this permission notice shall be
87 " included in all copies or substantial portions of the Software.
88 "
89 " THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
90 " EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
91 " MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
92 " NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
93 " LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
94 " OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
95 " WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
96 "
97 "
98 " # Development
99 "
100 " ## Contributing patches
101 "
102 " Patches can be sent via mail to greg@hurrell.net, or as GitHub pull requests
103 " at: https://github.com/wincent/vim-docvim/pulls
104 "
105 " ## Cutting a new release
106 "
107 " At the moment the release process is manual:
108 "
109 " - Perform final sanity checks and manual testing
110 " - Update the |docvim-history| section of the documentation
111 " - Verify clean work tree:
112 "
113 " ```
114 " git status
115 " ```
116 "
117 " - Tag the release:
118 "
119 " ```
120 " git tag -s -m "$VERSION release" $VERSION
121 " ```
122 "
123 " - Publish the code:
124 "
125 " ```
126 " git push origin master --follow-tags
127 " git push github master --follow-tags
128 " ```
129 "
130 " - Produce the release archive:
131 "
132 " ```
133 " git archive -o vim-docvim-$VERSION.zip HEAD -- .
134 " ```
135 "
136 " - Upload to http://www.vim.org/scripts/script.php?script_id=[TODO]
137 "
138 "
139 " # Authors
140 "
141 " vim-docvim is written and maintained by Greg Hurrell <greg@hurrell.net>.
142 "
143 "
144 " # History
145 "
146 " 0.1 (not yet released)
147 "
148 " - Initial release.
149
150 syntax region docvimBlock start='\v^\s*""' end='\v^\zs\ze\s*($|[^ \t"])' containedin=vimFuncBody
151 syntax region docvimPre start='\v^\s*"\s+\zs```\s*$' end='\v^\s*"\s+```\s*$' containedin=docvimBlock contained keepend
152
153 syntax match docvimAnnotation '\v\@command( .+)?' containedin=docvimBlock contained
154 syntax match docvimAnnotation '@commands' containedin=docvimBlock contained
155 syntax match docvimAnnotation '@dedent' containedin=docvimBlock contained
156 syntax match docvimAnnotation '@footer' containedin=docvimBlock contained
157 syntax match docvimAnnotation '\v\@function( .+)?' containedin=docvimBlock contained
158 syntax match docvimAnnotation '@functions' containedin=docvimBlock contained
159 syntax match docvimAnnotation '@indent' containedin=docvimBlock contained
160 syntax match docvimAnnotation '\v\@mapping( .+)?' containedin=docvimBlock contained
161 syntax match docvimAnnotation '@mappings' containedin=docvimBlock contained
162 syntax match docvimAnnotation '\v\@option( .+)?' containedin=docvimBlock contained
163 syntax match docvimAnnotation '@options' containedin=docvimBlock contained
164 syntax match docvimAnnotation '@param' containedin=docvimBlock contained
165 syntax match docvimAnnotation '\v\@plugin( .+)?' containedin=docvimBlock contained
166 syntax match docvimAnnotation '@private' containedin=docvimBlock contained
167 syntax match docvimBackticks '\v`[^\s`]+`' containedin=docvimBlock contained
168 syntax match docvimBlockquote '\v^\s*"\s+\zs\>\s+.+$' containedin=docvimBlock contained
169 syntax match docvimCrossReference '\v\c\|:?[a-z0-9()<>\.:-]+\|' containedin=docvimBlock contained
170 syntax match docvimHeading '\v^\s*"\s+\zs#\s+.+$' containedin=docvimBlock contained
171 syntax match docvimPreComment '\v^\s*"' containedin=docvimPre contained
172 syntax match docvimSetting "\v'[a-z]{2,}'" containedin=docvimBlock contained
173 syntax match docvimSetting "\v't_..'" containedin=docvimBlock contained
174 syntax match docvimSpecial '\v\<CSM-.\>' containedin=docvimBlock contained
175 syntax match docvimSpecial '\v\<[-a-zA-Z0-9_]+\>' containedin=docvimBlock contained
176 syntax match docvimSubheading '\v^\s*"\s+\zs##\s+.+$' containedin=docvimBlock contained
177 syntax match docvimTarget '\v\c\*:?[a-z0-9()<>-]+\*' containedin=docvimBlock contained
178
179 " Stolen from $VIMRUNTIME/syntax/help.vim:
180 syntax match docvimURL `\v<(((https?|ftp|gopher)://|(mailto|file|news):)[^'     <>"]+|(www|web|w3)[a-z0-9_-]*\.[a-z0-9._-]+\.[^'        <>"]+)[a-zA-Z0-9/]` containedin=docvimBlock contained
181
182 if has('conceal')
183   syntax match docvimBacktick '\v`' containedin=docvimBackticks contained conceal
184   syntax match docvimBar '\v\|' containedin=docvimCrossReference contained conceal
185   syntax match docvimHeadingPrefix '\v# ' containedin=docvimHeading contained conceal
186   syntax match docvimStar '\v\*' containedin=docvimTarget contained conceal
187   syntax match docvimSubheadingPrefix '\v## ' containedin=docvimSubheading contained conceal
188 else
189   syntax match docvimBacktick '\v`' containedin=docvimBackticks contained
190   syntax match docvimBar '\v\|' containedin=docvimCrossReference contained
191   syntax match docvimHeadingPrefix '\v# ' containedin=docvimHeading contained
192   syntax match docvimStar '\v\*' containedin=docvimTarget contained
193   syntax match docvimSubheadingPrefix '\v## ' containedin=docvimSubheading contained
194 endif
195
196 highlight default link docvimAnnotation String
197 highlight default link docvimBacktick Ignore
198 highlight default link docvimBackticks Ignore
199 highlight default link docvimBar Identifier
200 highlight default link docvimBlock Normal
201 highlight default link docvimBlockquote Comment
202 highlight default link docvimComment Normal
203 highlight default link docvimCrossReference Identifier
204 highlight default link docvimHeading Identifier
205 highlight default link docvimHeadingPrefix Identifier
206 highlight default link docvimPre Ignore
207 highlight default link docvimSetting Type
208 highlight default link docvimSpecial Special
209 highlight default link docvimStar String
210 highlight default link docvimSubheading PreProc
211 highlight default link docvimSubheadingPrefix PreProc
212 highlight default link docvimTarget String
213 highlight default link docvimURL String