From: Hiroshi Shirosaki Date: Thu, 10 Dec 2015 08:16:22 +0000 (+0900) Subject: Generate vim help from README.md using vim-tools X-Git-Url: https://git.madduck.net/etc/vim.git/commitdiff_plain/dfd237a98e3c4ce1f7494efa50b90ccb921a704a?ds=sidebyside;hp=611c994e1b00ef9dac617fe96cd644f0297e2a19 Generate vim help from README.md using vim-tools Add a make rule to generate vim help file. Tweak vim help using `sed`. Add doc/vim-markdown.txt to `make install`. --- diff --git a/.gitignore b/.gitignore index 378eac2..c6f4595 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ build +/doc/tags diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a2c1580..832072d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,6 +10,8 @@ Every non local identifier must start with `g:vim_markdown_`. Every new feature must be documented under in the [README.md](README.md). Documentation must be written in [GFM](https://help.github.com/articles/github-flavored-markdown) since GitHub itself is the primary to HTML converter used. In particular, remember that GFM adds line breaks at single newlines, so just forget about the 70 characters wide rule. +Vim help file [doc/vim-markdown.txt](doc/vim-markdown.txt) will be generated from [README.md](README.md) by `make doc` using [vim-tools](https://github.com/xolox/vim-tools). + # Markdown Flavors There are many flavors of markdown, each one with an unique feature set. This plugin uses the following strategy to deal with all those flavors: diff --git a/Makefile b/Makefile index 9260a52..5d23114 100644 --- a/Makefile +++ b/Makefile @@ -13,6 +13,8 @@ install: cp -v syntax/markdown.vim ${ADDONS}/syntax/markdown.vim mkdir -pv ${ADDONS}/after/ftplugin cp -v after/ftplugin/markdown.vim ${ADDONS}/after/ftplugin/markdown.vim + mkdir -pv ${ADDONS}/doc + cp -v doc/vim-markdown.txt ${ADDONS}/doc/vim-markdown.txt mkdir -pv ${REGISTRY} cp -v registry/markdown.yaml ${REGISTRY}/markdown.yaml @@ -33,3 +35,25 @@ build/vader.vim: | build build: mkdir build + +doc: build/html2vimdoc build/vim-tools + sed '/^\(\[!\[Build Status\]\|1. \[\)/d' README.md > doc/tmp.md + build/html2vimdoc/bin/python build/vim-tools/html2vimdoc.py -f vim-markdown \ + doc/tmp.md | \ + sed -e "s/\s*$$//; # remove trailing spaces" \ + -e "/^- '[^']*':\( \|$$\)/ { # match command lines" \ + -e "s/^- '\([^']*\)':\( \|$$\)/ \*\1\*\n\0/; # make command references" \ + -e ":a; s/^\(.\{1,78\}\n\)/ \1/; ta } # right align references" \ + > doc/vim-markdown.txt && rm -f doc/tmp.md +.PHONY: doc + +# Prerequire Python and virtualenv. +# $ sudo pip install virtualenv +# Create the virtual environment. +# Install the dependencies. +build/html2vimdoc: | build + virtualenv build/html2vimdoc + build/html2vimdoc/bin/pip install beautifulsoup coloredlogs==4.0 markdown + +build/vim-tools: | build + git clone https://github.com/xolox/vim-tools.git build/vim-tools diff --git a/doc/vim-markdown.txt b/doc/vim-markdown.txt new file mode 100644 index 0000000..1fcec7b --- /dev/null +++ b/doc/vim-markdown.txt @@ -0,0 +1,279 @@ +*vim-markdown* Vim Markdown + +=============================================================================== +Contents ~ + + 1. Introduction |vim-markdown-introduction| + 2. Installation |vim-markdown-installation| + 3. Options |vim-markdown-options| + 1. Disable Folding |vim-markdown-disable-folding| + 2. Change fold style |vim-markdown-change-fold-style| + 3. Disable Default Key Mappings |vim-markdown-disable-default-key-mappings| + 4. Syntax extensions |vim-markdown-syntax-extensions| + 1. LaTeX math |vim-markdown-latex-math| + 2. YAML frontmatter |vim-markdown-yaml-frontmatter| + 4. Mappings |vim-markdown-mappings| + 5. Commands |vim-markdown-commands| + 6. Credits |vim-markdown-credits| + 7. License |vim-markdown-license| + 8. References |vim-markdown-references| + +=============================================================================== + *vim-markdown-introduction* +Introduction ~ + +Syntax highlighting, matching rules and mappings for the original Markdown [1] +and extensions. + +=============================================================================== + *vim-markdown-installation* +Installation ~ + +If you use Vundle [2], add the following line to your '~/.vimrc': +> + Plugin 'godlygeek/tabular' + Plugin 'plasticboy/vim-markdown' +< +The 'tabular' plugin must come _before_ 'vim-markdown'. + +Then run inside Vim: +> + :so ~/.vimrc + :PluginInstall +< +If you use Pathogen [3], do this: +> + cd ~/.vim/bundle + git clone https://github.com/plasticboy/vim-markdown.git +< +To install without Pathogen using the Debian vim-addon-manager [4], do this: +> + git clone https://github.com/plasticboy/vim-markdown.git + cd vim-markdown + sudo make install + vim-addon-manager install markdown +< +If you are not using any package manager, download the tarball [5] and do this: +> + cd ~/.vim + tar --strip=1 -zxf vim-markdown-master.tar.gz +< +=============================================================================== + *vim-markdown-options* +Options ~ + +------------------------------------------------------------------------------- + *vim-markdown-disable-folding* +Disable Folding ~ + +Add the following line to your '.vimrc' to disable the folding configuration: +> + let g:vim_markdown_folding_disabled=1 +< +This option only controls Vim Markdown specific folding configuration. + +To enable/disable folding use Vim's standard folding configuration. +> + set [no]foldenable +< +------------------------------------------------------------------------------- + *vim-markdown-change-fold-style* +Change fold style ~ + +To fold in a style like python-mode [6], add the following to your '.vimrc': +> + let g:vim_markdown_folding_style_pythonic=1 +< +------------------------------------------------------------------------------- + *vim-markdown-disable-default-key-mappings* +Disable Default Key Mappings ~ + +Add the following line to your '.vimrc' to disable default key mappings: +> + let g:vim_markdown_no_default_key_mappings=1 +< +You can also map them by yourself with '' mappings. + +------------------------------------------------------------------------------- + *vim-markdown-syntax-extensions* +Syntax extensions ~ + +The following options control which syntax extensions will be turned on. They +are off by default. + +------------------------------------------------------------------------------- + *vim-markdown-latex-math* +LaTeX math ~ + +Used as '$x^2$', '$$x^2$$', escapable as '\$x\$' and '\$\$x\$\$'. +> + let g:vim_markdown_math=1 +< +------------------------------------------------------------------------------- + *vim-markdown-yaml-frontmatter* +YAML frontmatter ~ + +Highlight YAML frontmatter as used by Jekyll: +> + let g:vim_markdown_frontmatter=1 +< +=============================================================================== + *vim-markdown-mappings* +Mappings ~ + +The following work on normal and visual modes: + + *gx* +- 'gx': open the link under the cursor in the same browser as the standard + 'gx' command. 'Markdown_OpenUrlUnderCursor' + + The standard 'gx' is extended by allowing you to put your cursor anywhere + inside a link. + + For example, all the following cursor positions will work: +> + [Example](http://example.com) + ^ ^ ^^ ^ ^ + 1 2 34 5 6 + + + ^ ^ ^ + 1 2 3 +< + Known limitation: does not work for links that span multiple lines. + + *]]* +- ']]': go to next header. 'Markdown_MoveToNextHeader' + + *[[* +- '[[': go to previous header. Contrast with ']c'. + 'Markdown_MoveToPreviousHeader' + + *][* +- '][': go to next sibling header if any. + 'Markdown_MoveToNextSiblingHeader' + + *[]* +- '[]': go to previous sibling header if any. + 'Markdown_MoveToPreviousSiblingHeader' + + *]c* +- ']c': go to Current header. 'Markdown_MoveToCurHeader' + + *]u* +- ']u': go to parent header (Up). 'Markdown_MoveToParentHeader' + +This plugin follows the recommended Vim plugin mapping interface, so to change +the map ']u' to 'asdf', add to your '.vimrc': +> + map asdf Markdown_MoveToParentHeader +< +To disable a map use: +> + map Markdown_MoveToParentHeader +< +=============================================================================== + *vim-markdown-commands* +Commands ~ + + *:HeaderDecrease* +- ':HeaderDecrease': + + Decrease level of all headers in buffer: 'h2' to 'h1', 'h3' to 'h2', etc. + + If range is given, only operate in the range. + + If an 'h1' would be decreased, abort. + + For simplicity of implementation, Setex headers are converted to Atx. + + *:HeaderIncrease* +- ':HeaderIncrease': Analogous to ':HeaderDecrease', but increase levels + instead. + + *:SetexToAtx* +- ':SetexToAtx': + + Convert all Setex style headers in buffer to Atx. + + If a range is given, e.g. hit ':' from visual mode, only operate on the + range. + + *:TableFormat* +- ':TableFormat': Format the table under the cursor like this [7]. + + Requires Tabular [8]. + + The input table _must_ already have a separator line as the second line of + the table. That line only needs to contain the correct pipes '|', nothing + else is required. + + *:Toc* +- ':Toc': create a quickfix vertical window navigable table of contents with + the headers. + + Hit '' on a line to jump to the corresponding line of the markdown + file. + + *:Toch* +- ':Toch': Same as ':Toc' but in an horizontal window. + + *:Toct* +- ':Toct': Same as ':Toc' but in a new tab. + + *:Tocv* +- ':Tocv': Same as ':Toc' for symmetry with ':Toch' and 'Tocv'. + +=============================================================================== + *vim-markdown-credits* +Credits ~ + +The main contributors of vim-markdown are: + +- **Ben Williams** (A.K.A. **plasticboy**). The original developer of vim- + markdown. Homepage [9]. + +If you feel that your name should be on this list, please make a pull request +listing your contributions. + +=============================================================================== + *vim-markdown-license* +License ~ + +The MIT License (MIT) + +Copyright (c) 2012 Benjamin D. Williams + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies +of the Software, and to permit persons to whom the Software is furnished to do +so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +=============================================================================== + *vim-markdown-references* +References ~ + +[1] http://daringfireball.net/projects/markdown/ +[2] https://github.com/gmarik/vundle +[3] https://github.com/tpope/vim-pathogen +[4] http://packages.qa.debian.org/v/vim-addon-manager.html +[5] https://github.com/plasticboy/vim-markdown/archive/master.tar.gz +[6] https://github.com/klen/python-mode +[7] http://www.cirosantilli.com/markdown-styleguide/#tables +[8] https://github.com/godlygeek/tabular +[9] http://plasticboy.com/ + +vim: ft=help diff --git a/registry/markdown.yaml b/registry/markdown.yaml index 00c6b9f..4d293ee 100644 --- a/registry/markdown.yaml +++ b/registry/markdown.yaml @@ -6,3 +6,4 @@ files: - syntax/markdown.vim - after/ftplugin/markdown.vim - indent/markdown.vim + - doc/vim-markdown.txt