]> git.wincent.com - vim-docvim.git/blob - after/syntax/vim.vim
Add source documentation
[vim-docvim.git] / after / syntax / vim.vim
1 ""
2 " @plugin docvim Syntax highlighting for docvim comments
3 "
4 " @header
5 "
6 "                                                                    *vim-docvim*
7 " # Intro
8 "
9 " vim-docvim provides syntax highlighting for Vim script files that contain
10 " embedded docvim comments.
11 "
12 " docvim (the tool, not this plug-in) is a documentation generator that
13 " processes those embedded comments and produces documentation in Markdown and
14 " Vim "help" formats. To avoid confusion, this document refers to the Vim
15 " plug-in as "vim-docvim" and the separate generation tool as "docvim".
16 "
17 "
18 " # Installation
19 "
20 " To install vim-docvim, use your plug-in management system of choice.
21 "
22 " If you don't have a "plug-in management system of choice", I recommend
23 " Pathogen (https://github.com/tpope/vim-pathogen) due to its simplicity and
24 " robustness. Assuming that you have Pathogen installed and configured, and that
25 " you want to install vim-docvim into `~/.vim/bundle`, you can do so with:
26 "
27 " ```
28 " git clone https://github.com/wincent/vim-docvim.git ~/.vim/bundle/vim-docvim
29 " ```
30 "
31 " Alternatively, if you use a Git submodule for each Vim plug-in, you could do
32 " the following after `cd`-ing into the top-level of your Git superproject:
33 "
34 " ```
35 " git submodule add https://github.com/wincent/vim-docvim.git ~/vim/bundle/vim-docvim
36 " git submodule init
37 " ```
38 "
39 " To generate help tags under Pathogen, you can do so from inside Vim with:
40 "
41 " ```
42 " :call pathogen#helptags()
43 " ```
44 "
45 "
46 " # Related
47 "
48 " The docvim tool itself is an NPM module, available at:
49 "
50 "   https://www.npmjs.com/package/docvim
51 "
52 " The official source code repo is at:
53 "
54 "   http://git.wincent.com/docvim.git
55 "
56 " A mirror exists at:
57 "
58 "   https://github.com/wincent/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 2015-present Greg Hurrell. All rights reserved.
79 "
80 " Redistribution and use in source and binary forms, with or without
81 " modification, are permitted provided that the following conditions are met:
82 "
83 " 1. Redistributions of source code must retain the above copyright notice,
84 "    this list of conditions and the following disclaimer.
85 " 2. Redistributions in binary form must reproduce the above copyright notice,
86 "    this list of conditions and the following disclaimer in the documentation
87 "    and/or other materials provided with the distribution.
88 "
89 " THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
90 " AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
91 " IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
92 " ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
93 " LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
94 " CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
95 " SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
96 " INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
97 " CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
98 " ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
99 " POSSIBILITY OF SUCH DAMAGE.
100 "
101 "
102 " # Development
103 "
104 " ## Contributing patches
105 "
106 " Patches can be sent via mail to greg@hurrell.net, or as GitHub pull requests
107 " at: https://github.com/wincent/vim-docvim/pulls
108 "
109 " ## Cutting a new release
110 "
111 " At the moment the release process is manual:
112 "
113 " - Perform final sanity checks and manual testing
114 " - Update the |docvim-history| section of the documentation
115 " - Verify clean work tree:
116 "
117 " ```
118 " git status
119 " ```
120 "
121 " - Tag the release:
122 "
123 " ```
124 " git tag -s -m "$VERSION release" $VERSION
125 " ```
126 "
127 " - Publish the code:
128 "
129 " ```
130 " git push origin master --follow-tags
131 " git push github master --follow-tags
132 " ```
133 "
134 " - Produce the release archive:
135 "
136 " ```
137 " git archive -o vim-docvim-$VERSION.zip HEAD -- .
138 " ```
139 "
140 " - Upload to http://www.vim.org/scripts/script.php?script_id=[TODO]
141 "
142 "
143 " # Authors
144 "
145 " vim-docvim is written and maintained by Greg Hurrell <greg@hurrell.net>.
146 "
147 "
148 " # History
149 "
150 " 0.1 (not yet released)
151 "
152 " - Initial release.
153
154 syntax region docvimBlock start='\v^ *""' end='\v\zs\ze^( *$|[^"])'
155 syntax region docvimPre start='\v^\s*"\s+\zs```\s*$' end='\v^\s*"\s+```\s*$' containedin=docvimBlock contained keepend
156
157 syntax match docvimAnnotation '@command' containedin=docvimBlock contained
158 syntax match docvimAnnotation '@dedent' containedin=docvimBlock contained
159 syntax match docvimAnnotation '@footer' containedin=docvimBlock contained
160 syntax match docvimAnnotation '@function' containedin=docvimBlock contained
161 syntax match docvimAnnotation '@header' containedin=docvimBlock contained
162 syntax match docvimAnnotation '@indent' containedin=docvimBlock contained
163 syntax match docvimAnnotation '@mapping' containedin=docvimBlock contained
164 syntax match docvimAnnotation '@option' containedin=docvimBlock contained
165 syntax match docvimAnnotation '@param' containedin=docvimBlock contained
166 syntax match docvimAnnotation '@plugin' containedin=docvimBlock contained
167 syntax match docvimAnnotation '@private' containedin=docvimBlock contained
168 syntax match docvimBackticks '\v`[^ `]+`' containedin=docvimBlock contained
169 syntax match docvimBlockquote '\v^\s*"\s+\zs\>\s+.+$' containedin=docvimBlock contained
170 syntax match docvimCrossReference '\v\c\|:?[a-z0-9()<>-]+\|' containedin=docvimBlock contained
171 syntax match docvimHeading '\v^\s*"\s+\zs#\s+.+$' containedin=docvimBlock contained
172 syntax match docvimPreComment '\v^\s*"' containedin=docvimPre contained
173 syntax match docvimSetting "\v'[a-z]{2,}'" containedin=docvimBlock contained
174 syntax match docvimSetting "\v't_..'" containedin=docvimBlock contained
175 syntax match docvimSpecial '\v\<CSM-.\>' containedin=docvimBlock contained
176 syntax match docvimSpecial '\v\<[-a-zA-Z0-9_]+\>' containedin=docvimBlock contained
177 syntax match docvimSubheading '\v^\s*"\s+\zs##\s+.+$' containedin=docvimBlock contained
178 syntax match docvimTarget '\v\c\*:?[a-z0-9()<>-]+\*' containedin=docvimBlock contained
179
180 " Stolen from $VIMRUNTIME/syntax/help.vim:
181 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
182
183 if has('conceal')
184   syntax match docvimBacktick '\v`' containedin=docvimBackticks contained conceal
185   syntax match docvimBar '\v\|' containedin=docvimCrossReference contained conceal
186   syntax match docvimHeadingPrefix '\v# ' containedin=docvimHeading contained conceal
187   syntax match docvimStar '\v\*' containedin=docvimTarget contained conceal
188   syntax match docvimSubheadingPrefix '\v## ' containedin=docvimSubheading contained conceal
189 else
190   syntax match docvimBacktick '\v`' containedin=docvimBackticks contained
191   syntax match docvimBar '\v\|' containedin=docvimCrossReference contained
192   syntax match docvimHeadingPrefix '\v# ' containedin=docvimHeading contained
193   syntax match docvimStar '\v\*' containedin=docvimTarget contained
194   syntax match docvimSubheadingPrefix '\v## ' containedin=docvimSubheading contained
195 endif
196
197 highlight default link docvimAnnotation String
198 highlight default link docvimBacktick Ignore
199 highlight default link docvimBackticks Ignore
200 highlight default link docvimBar Identifier
201 highlight default link docvimBlock Normal
202 highlight default link docvimBlockquote Comment
203 highlight default link docvimComment Normal
204 highlight default link docvimCrossReference Identifier
205 highlight default link docvimHeading Identifier
206 highlight default link docvimHeadingPrefix Identifier
207 highlight default link docvimPre Ignore
208 highlight default link docvimSetting Type
209 highlight default link docvimSpecial Special
210 highlight default link docvimStar String
211 highlight default link docvimSubheading PreProc
212 highlight default link docvimSubheadingPrefix PreProc
213 highlight default link docvimTarget String
214 highlight default link docvimURL String