]> git.wincent.com - vim-docvim.git/blob - after/syntax/vim.vim
Add @mappings annotation
[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 2015-present Greg Hurrell. All rights reserved.
77 "
78 " Redistribution and use in source and binary forms, with or without
79 " modification, are permitted provided that the following conditions are met:
80 "
81 " 1. Redistributions of source code must retain the above copyright notice,
82 "    this list of conditions and the following disclaimer.
83 " 2. Redistributions in binary form must reproduce the above copyright notice,
84 "    this list of conditions and the following disclaimer in the documentation
85 "    and/or other materials provided with the distribution.
86 "
87 " THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
88 " AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
89 " IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
90 " ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
91 " LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
92 " CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
93 " SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
94 " INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
95 " CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
96 " ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
97 " POSSIBILITY OF SUCH DAMAGE.
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"])'
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 '@dedent' containedin=docvimBlock contained
157 syntax match docvimAnnotation '@footer' containedin=docvimBlock contained
158 syntax match docvimAnnotation '\v\@function( .+)?' 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 '@param' containedin=docvimBlock contained
164 syntax match docvimAnnotation '\v\@plugin( .+)?' containedin=docvimBlock contained
165 syntax match docvimAnnotation '@private' containedin=docvimBlock contained
166 syntax match docvimBackticks '\v`[^\s`]+`' containedin=docvimBlock contained
167 syntax match docvimBlockquote '\v^\s*"\s+\zs\>\s+.+$' containedin=docvimBlock contained
168 syntax match docvimCrossReference '\v\c\|:?[a-z0-9()<>\.:-]+\|' containedin=docvimBlock contained
169 syntax match docvimHeading '\v^\s*"\s+\zs#\s+.+$' containedin=docvimBlock contained
170 syntax match docvimPreComment '\v^\s*"' containedin=docvimPre contained
171 syntax match docvimSetting "\v'[a-z]{2,}'" containedin=docvimBlock contained
172 syntax match docvimSetting "\v't_..'" containedin=docvimBlock contained
173 syntax match docvimSpecial '\v\<CSM-.\>' containedin=docvimBlock contained
174 syntax match docvimSpecial '\v\<[-a-zA-Z0-9_]+\>' containedin=docvimBlock contained
175 syntax match docvimSubheading '\v^\s*"\s+\zs##\s+.+$' containedin=docvimBlock contained
176 syntax match docvimTarget '\v\c\*:?[a-z0-9()<>-]+\*' containedin=docvimBlock contained
177
178 " Stolen from $VIMRUNTIME/syntax/help.vim:
179 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
180
181 if has('conceal')
182   syntax match docvimBacktick '\v`' containedin=docvimBackticks contained conceal
183   syntax match docvimBar '\v\|' containedin=docvimCrossReference contained conceal
184   syntax match docvimHeadingPrefix '\v# ' containedin=docvimHeading contained conceal
185   syntax match docvimStar '\v\*' containedin=docvimTarget contained conceal
186   syntax match docvimSubheadingPrefix '\v## ' containedin=docvimSubheading contained conceal
187 else
188   syntax match docvimBacktick '\v`' containedin=docvimBackticks contained
189   syntax match docvimBar '\v\|' containedin=docvimCrossReference contained
190   syntax match docvimHeadingPrefix '\v# ' containedin=docvimHeading contained
191   syntax match docvimStar '\v\*' containedin=docvimTarget contained
192   syntax match docvimSubheadingPrefix '\v## ' containedin=docvimSubheading contained
193 endif
194
195 highlight default link docvimAnnotation String
196 highlight default link docvimBacktick Ignore
197 highlight default link docvimBackticks Ignore
198 highlight default link docvimBar Identifier
199 highlight default link docvimBlock Normal
200 highlight default link docvimBlockquote Comment
201 highlight default link docvimComment Normal
202 highlight default link docvimCrossReference Identifier
203 highlight default link docvimHeading Identifier
204 highlight default link docvimHeadingPrefix Identifier
205 highlight default link docvimPre Ignore
206 highlight default link docvimSetting Type
207 highlight default link docvimSpecial Special
208 highlight default link docvimStar String
209 highlight default link docvimSubheading PreProc
210 highlight default link docvimSubheadingPrefix PreProc
211 highlight default link docvimTarget String
212 highlight default link docvimURL String