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 '@command' containedin=docvimBlock contained
 156 syntax match docvimAnnotation '@dedent' containedin=docvimBlock contained
 157 syntax match docvimAnnotation '@footer' containedin=docvimBlock contained
 158 syntax match docvimAnnotation '@function' containedin=docvimBlock contained
 159 syntax match docvimAnnotation '@indent' containedin=docvimBlock contained
 160 syntax match docvimAnnotation '@mapping' containedin=docvimBlock contained
 161 syntax match docvimAnnotation '@option' containedin=docvimBlock contained
 162 syntax match docvimAnnotation '@param' containedin=docvimBlock contained
 163 syntax match docvimAnnotation '@plugin' containedin=docvimBlock contained
 164 syntax match docvimAnnotation '@private' containedin=docvimBlock contained
 165 syntax match docvimBackticks '\v`[^\s`]+`' containedin=docvimBlock contained
 166 syntax match docvimBlockquote '\v^\s*"\s+\zs\>\s+.+$' containedin=docvimBlock contained
 167 syntax match docvimCrossReference '\v\c\|:?[a-z0-9()<>\.:-]+\|' containedin=docvimBlock contained
 168 syntax match docvimHeading '\v^\s*"\s+\zs#\s+.+$' containedin=docvimBlock contained
 169 syntax match docvimPreComment '\v^\s*"' containedin=docvimPre contained
 170 syntax match docvimSetting "\v'[a-z]{2,}'" containedin=docvimBlock contained
 171 syntax match docvimSetting "\v't_..'" containedin=docvimBlock contained
 172 syntax match docvimSpecial '\v\<CSM-.\>' containedin=docvimBlock contained
 173 syntax match docvimSpecial '\v\<[-a-zA-Z0-9_]+\>' containedin=docvimBlock contained
 174 syntax match docvimSubheading '\v^\s*"\s+\zs##\s+.+$' containedin=docvimBlock contained
 175 syntax match docvimTarget '\v\c\*:?[a-z0-9()<>-]+\*' containedin=docvimBlock contained
 176
 177 " Stolen from $VIMRUNTIME/syntax/help.vim:
 178 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
 179
 180 if has('conceal')
 181   syntax match docvimBacktick '\v`' containedin=docvimBackticks contained conceal
 182   syntax match docvimBar '\v\|' containedin=docvimCrossReference contained conceal
 183   syntax match docvimHeadingPrefix '\v# ' containedin=docvimHeading contained conceal
 184   syntax match docvimStar '\v\*' containedin=docvimTarget contained conceal
 185   syntax match docvimSubheadingPrefix '\v## ' containedin=docvimSubheading contained conceal
 186 else
 187   syntax match docvimBacktick '\v`' containedin=docvimBackticks contained
 188   syntax match docvimBar '\v\|' containedin=docvimCrossReference contained
 189   syntax match docvimHeadingPrefix '\v# ' containedin=docvimHeading contained
 190   syntax match docvimStar '\v\*' containedin=docvimTarget contained
 191   syntax match docvimSubheadingPrefix '\v## ' containedin=docvimSubheading contained
 192 endif
 193
 194 highlight default link docvimAnnotation String
 195 highlight default link docvimBacktick Ignore
 196 highlight default link docvimBackticks Ignore
 197 highlight default link docvimBar Identifier
 198 highlight default link docvimBlock Normal
 199 highlight default link docvimBlockquote Comment
 200 highlight default link docvimComment Normal
 201 highlight default link docvimCrossReference Identifier
 202 highlight default link docvimHeading Identifier
 203 highlight default link docvimHeadingPrefix Identifier
 204 highlight default link docvimPre Ignore
 205 highlight default link docvimSetting Type
 206 highlight default link docvimSpecial Special
 207 highlight default link docvimStar String
 208 highlight default link docvimSubheading PreProc
 209 highlight default link docvimSubheadingPrefix PreProc
 210 highlight default link docvimTarget String
 211 highlight default link docvimURL String