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