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 '@header' containedin=docvimBlock contained
 165 syntax match docvimAnnotation '\v\@image( .+)?' containedin=docvimBlock contained
 166 syntax match docvimAnnotation '@indent' containedin=docvimBlock contained
 167 syntax match docvimAnnotation '\v\@mapping( .+)?' containedin=docvimBlock contained
 168 syntax match docvimAnnotation '@mappings' containedin=docvimBlock contained
 169 syntax match docvimAnnotation '\v\@option( .+)?' containedin=docvimBlock contained
 170 syntax match docvimAnnotation '@options' containedin=docvimBlock contained
 171 syntax match docvimAnnotation '@param' containedin=docvimBlock contained
 172 syntax match docvimAnnotation '\v\@plugin( .+)?' containedin=docvimBlock contained
 173 syntax match docvimAnnotation '@private' containedin=docvimBlock contained
 174 syntax match docvimBackticks '\v`[^\s`]+`' containedin=docvimBlock contained
 175 syntax match docvimBlockquote '\v^\s*"\s+\zs\>\s+.+$' containedin=docvimBlock contained
 176 syntax match docvimCrossReference '\v\c\|:?[a-z0-9()<>\.:-]+\|' containedin=docvimBlock contained
 177 syntax match docvimHeading '\v^\s*"\s+\zs#\s+.+$' containedin=docvimBlock contained
 178 syntax match docvimPreComment '\v^\s*"' containedin=docvimPre contained
 179 syntax match docvimSetting "\v'[a-z]{2,}'" containedin=docvimBlock contained
 180 syntax match docvimSetting "\v't_..'" containedin=docvimBlock contained
 181 syntax match docvimSpecial '\v\<CSM-.\>' containedin=docvimBlock contained
 182 syntax match docvimSpecial '\v\<[-a-zA-Z0-9_]+\>' containedin=docvimBlock contained
 183 syntax match docvimSubheading '\v^\s*"\s+\zs##\s+.+$' containedin=docvimBlock contained
 184 syntax match docvimTarget '\v\c\*:?[a-z0-9()<>-]+\*' containedin=docvimBlock contained
 185
 186 " Stolen from $VIMRUNTIME/syntax/help.vim:
 187 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
 188
 189 if has('conceal')
 190   syntax match docvimBacktick '\v`' containedin=docvimBackticks contained conceal
 191   syntax match docvimBar '\v\|' containedin=docvimCrossReference contained conceal
 192   syntax match docvimHeadingPrefix '\v# ' containedin=docvimHeading contained conceal
 193   syntax match docvimStar '\v\*' containedin=docvimTarget contained conceal
 194   syntax match docvimSubheadingPrefix '\v## ' containedin=docvimSubheading contained conceal
 195 else
 196   syntax match docvimBacktick '\v`' containedin=docvimBackticks contained
 197   syntax match docvimBar '\v\|' containedin=docvimCrossReference contained
 198   syntax match docvimHeadingPrefix '\v# ' containedin=docvimHeading contained
 199   syntax match docvimStar '\v\*' containedin=docvimTarget contained
 200   syntax match docvimSubheadingPrefix '\v## ' containedin=docvimSubheading contained
 201 endif
 202
 203 function! s:italicize(name, link)
 204   try
 205     execute 'highlight! ' . a:name . ' ' . pinnacle#italicize(a:link)
 206   catch
 207     execute 'highlight! link ' . a:name . ' ' . a:link
 208   endtry
 209 endfunction
 210
 211 function! s:highlight()
 212   call s:italicize('docvimAnnotation', 'String')
 213   call s:italicize('docvimBacktick', 'Comment')
 214   call s:italicize('docvimBackticks', 'Comment')
 215   call s:italicize('docvimBar', 'Identifier')
 216   call s:italicize('docvimBlock', 'Normal')
 217   call s:italicize('docvimBlockquote', 'Comment')
 218   call s:italicize('docvimComment', 'Normal')
 219   call s:italicize('docvimCrossReference', 'Identifier')
 220   call s:italicize('docvimHeading', 'Identifier')
 221   call s:italicize('docvimHeadingPrefix', 'Identifier')
 222   call s:italicize('docvimPre', 'Comment')
 223   call s:italicize('docvimSetting', 'Type')
 224   call s:italicize('docvimSpecial', 'Special')
 225   call s:italicize('docvimStar', 'String')
 226   call s:italicize('docvimSubheading', 'PreProc')
 227   call s:italicize('docvimSubheadingPrefix', 'PreProc')
 228   call s:italicize('docvimTarget', 'String')
 229   call s:italicize('docvimURL', 'String')
 230 endfunction
 231
 232 if has('autocmd')
 233   augroup Docvim
 234     autocmd!
 235     autocmd ColorScheme * call s:highlight()
 236   augroup END
 237 endif
 238
 239 call s:highlight()