]> git.wincent.com - vim-docvim.git/blob - after/syntax/vim.vim
4f7b7fe707410cc0fbcb0c0b617d585941362c95
[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 additional syntax highlighting for Vim script files that
8 " contain 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 " ## Docvim
47 "
48 " The Docvim tool itself is a Haskell module, available at:
49 "
50 "   http://hackage.haskell.org/package/docvim
51 "
52 " The official source code repo is at:
53 "
54 "   http://git.wincent.com/docvim.git
55 "
56 " Mirrors exist at:
57 "
58 "   - https://github.com/wincent/docvim
59 "   - https://gitlab.com/wincent/docvim
60 "   - https://bitbucket.org/ghurrell/docvim
61 "
62 " # Website
63 "
64 " The official vim-docvim source code repo is at:
65 "
66 "   http://git.wincent.com/vim-docvim.git
67 "
68 " Mirrors exist at:
69 "
70 "   - https://github.com/wincent/vim-docvim
71 "   - https://gitlab.com/wincent/vim-docvim
72 "   - https://bitbucket.org/ghurrell/vim-docvim
73 "
74 " Official releases are listed at:
75 "
76 "   http://www.vim.org/scripts/script.php?script_id=5758
77 "
78 "
79 " # License
80 "
81 " Copyright (c) 2015-present Greg Hurrell
82 "
83 " Permission is hereby granted, free of charge, to any person obtaining
84 " a copy of this software and associated documentation files (the
85 " "Software"), to deal in the Software without restriction, including
86 " without limitation the rights to use, copy, modify, merge, publish,
87 " distribute, sublicense, and/or sell copies of the Software, and to
88 " permit persons to whom the Software is furnished to do so, subject to
89 " the following conditions:
90 "
91 " The above copyright notice and this permission notice shall be
92 " included in all copies or substantial portions of the Software.
93 "
94 " THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
95 " EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
96 " MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
97 " NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
98 " LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
99 " OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
100 " WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
101 "
102 "
103 " # Development
104 "
105 " ## Contributing patches
106 "
107 " Patches can be sent via mail to greg@hurrell.net, or as GitHub pull requests
108 " at: https://github.com/wincent/vim-docvim/pulls
109 "
110 " ## Cutting a new release
111 "
112 " At the moment the release process is manual:
113 "
114 " - Perform final sanity checks and manual testing
115 " - Update the |docvim-history| section of the documentation
116 " - Verify clean work tree:
117 "
118 " ```
119 " git status
120 " ```
121 "
122 " - Tag the release:
123 "
124 " ```
125 " git tag -s -m "$VERSION release" $VERSION
126 " ```
127 "
128 " - Publish the code:
129 "
130 " ```
131 " git push origin master --follow-tags
132 " git push github master --follow-tags
133 " ```
134 "
135 " - Produce the release archive:
136 "
137 " ```
138 " git archive -o vim-docvim-$VERSION.zip HEAD -- .
139 " ```
140 "
141 " - Upload to http://www.vim.org/scripts/script.php?script_id=5758
142 "
143 "
144 " # Authors
145 "
146 " vim-docvim is written and maintained by Greg Hurrell <greg@hurrell.net>.
147 "
148 "
149 " # History
150 "
151 " ## 1.0 (25 December 2018)
152 "
153 " - Initial release.
154
155 syntax region docvimBlock start='\v^\s*""' end='\v^\zs\ze\s*($|[^ \t"])' containedin=vimFuncBody
156 syntax region docvimPre start='\v^\s*"\s+\zs```\s*$' end='\v^\s*"\s+```\s*$' containedin=docvimBlock contained keepend
157
158 syntax match docvimAnnotation '\v\@command( .+)?' containedin=docvimBlock contained
159 syntax match docvimAnnotation '@commands' containedin=docvimBlock contained
160 syntax match docvimAnnotation '@dedent' containedin=docvimBlock contained
161 syntax match docvimAnnotation '@footer' containedin=docvimBlock contained
162 syntax match docvimAnnotation '\v\@function( .+)?' containedin=docvimBlock contained
163 syntax match docvimAnnotation '@functions' containedin=docvimBlock contained
164 syntax match docvimAnnotation '@indent' containedin=docvimBlock contained
165 syntax match docvimAnnotation '\v\@mapping( .+)?' containedin=docvimBlock contained
166 syntax match docvimAnnotation '@mappings' containedin=docvimBlock contained
167 syntax match docvimAnnotation '\v\@option( .+)?' containedin=docvimBlock contained
168 syntax match docvimAnnotation '@options' containedin=docvimBlock contained
169 syntax match docvimAnnotation '@param' containedin=docvimBlock contained
170 syntax match docvimAnnotation '\v\@plugin( .+)?' containedin=docvimBlock contained
171 syntax match docvimAnnotation '@private' containedin=docvimBlock contained
172 syntax match docvimBackticks '\v`[^\s`]+`' containedin=docvimBlock contained
173 syntax match docvimBlockquote '\v^\s*"\s+\zs\>\s+.+$' containedin=docvimBlock contained
174 syntax match docvimCrossReference '\v\c\|:?[a-z0-9()<>\.:-]+\|' containedin=docvimBlock contained
175 syntax match docvimHeading '\v^\s*"\s+\zs#\s+.+$' containedin=docvimBlock contained
176 syntax match docvimPreComment '\v^\s*"' containedin=docvimPre contained
177 syntax match docvimSetting "\v'[a-z]{2,}'" containedin=docvimBlock contained
178 syntax match docvimSetting "\v't_..'" containedin=docvimBlock contained
179 syntax match docvimSpecial '\v\<CSM-.\>' containedin=docvimBlock contained
180 syntax match docvimSpecial '\v\<[-a-zA-Z0-9_]+\>' containedin=docvimBlock contained
181 syntax match docvimSubheading '\v^\s*"\s+\zs##\s+.+$' containedin=docvimBlock contained
182 syntax match docvimTarget '\v\c\*:?[a-z0-9()<>-]+\*' containedin=docvimBlock contained
183
184 " Stolen from $VIMRUNTIME/syntax/help.vim:
185 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
186
187 if has('conceal')
188   syntax match docvimBacktick '\v`' containedin=docvimBackticks contained conceal
189   syntax match docvimBar '\v\|' containedin=docvimCrossReference contained conceal
190   syntax match docvimHeadingPrefix '\v# ' containedin=docvimHeading contained conceal
191   syntax match docvimStar '\v\*' containedin=docvimTarget contained conceal
192   syntax match docvimSubheadingPrefix '\v## ' containedin=docvimSubheading contained conceal
193 else
194   syntax match docvimBacktick '\v`' containedin=docvimBackticks contained
195   syntax match docvimBar '\v\|' containedin=docvimCrossReference contained
196   syntax match docvimHeadingPrefix '\v# ' containedin=docvimHeading contained
197   syntax match docvimStar '\v\*' containedin=docvimTarget contained
198   syntax match docvimSubheadingPrefix '\v## ' containedin=docvimSubheading contained
199 endif
200
201 function! s:italicize(name, link)
202   try
203     execute 'highlight! ' . a:name . ' ' . pinnacle#italicize(a:link)
204   catch
205     execute 'highlight! link ' . a:name . ' ' . a:link
206   endtry
207 endfunction
208
209 function! s:highlight()
210   call s:italicize('docvimAnnotation', 'String')
211   call s:italicize('docvimBacktick', 'Comment')
212   call s:italicize('docvimBackticks', 'Comment')
213   call s:italicize('docvimBar', 'Identifier')
214   call s:italicize('docvimBlock', 'Normal')
215   call s:italicize('docvimBlockquote', 'Comment')
216   call s:italicize('docvimComment', 'Normal')
217   call s:italicize('docvimCrossReference', 'Identifier')
218   call s:italicize('docvimHeading', 'Identifier')
219   call s:italicize('docvimHeadingPrefix', 'Identifier')
220   call s:italicize('docvimPre', 'Comment')
221   call s:italicize('docvimSetting', 'Type')
222   call s:italicize('docvimSpecial', 'Special')
223   call s:italicize('docvimStar', 'String')
224   call s:italicize('docvimSubheading', 'PreProc')
225   call s:italicize('docvimSubheadingPrefix', 'PreProc')
226   call s:italicize('docvimTarget', 'String')
227   call s:italicize('docvimURL', 'String')
228 endfunction
229
230 if has('autocmd')
231   augroup Docvim
232     autocmd!
233     autocmd ColorScheme * call s:highlight()
234   augroup END
235 endif
236
237 call s:highlight()