]> git.madduck.net Git - etc/vim.git/commitdiff

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

Generate vim help from README.md using vim-tools
authorHiroshi Shirosaki <h.shirosaki@gmail.com>
Thu, 10 Dec 2015 08:16:22 +0000 (17:16 +0900)
committerHiroshi Shirosaki <h.shirosaki@gmail.com>
Wed, 16 Dec 2015 07:24:41 +0000 (16:24 +0900)
Add a make rule to generate vim help file.
Tweak vim help using `sed`.
Add doc/vim-markdown.txt to `make install`.

.gitignore
CONTRIBUTING.md
Makefile
doc/vim-markdown.txt [new file with mode: 0644]
registry/markdown.yaml

index 378eac25d311703f3f2cd456d8036da525cd0366..c6f45953484f79b73f54180039d150ee3c524f0a 100644 (file)
@@ -1 +1,2 @@
 build
 build
+/doc/tags
index a2c158087b5759bcdb1c039aa4b4d953676c08ca..832072dc4c40d2efa99c6d182b404732cbd17d93 100644 (file)
@@ -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.
 
 
 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:
 # 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:
index 9260a5281f14a940f3faaf31b9a61add8bf03aaa..5d231146a8798d3a07f4c0fd78b969775f699611 100644 (file)
--- 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
        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
 
        mkdir -pv ${REGISTRY}
        cp -v registry/markdown.yaml ${REGISTRY}/markdown.yaml
 
@@ -33,3 +35,25 @@ build/vader.vim: | build
 
 build:
        mkdir 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 (file)
index 0000000..1fcec7b
--- /dev/null
@@ -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 '<Plug>' 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. '<Plug>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
+
+  <http://example.com>
+  ^  ^               ^
+  1  2               3
+<
+  Known limitation: does not work for links that span multiple lines.
+
+                                                                           *]]*
+- ']]': go to next header. '<Plug>Markdown_MoveToNextHeader'
+
+                                                                           *[[*
+- '[[': go to previous header. Contrast with ']c'.
+  '<Plug>Markdown_MoveToPreviousHeader'
+
+                                                                           *][*
+- '][': go to next sibling header if any.
+  '<Plug>Markdown_MoveToNextSiblingHeader'
+
+                                                                           *[]*
+- '[]': go to previous sibling header if any.
+  '<Plug>Markdown_MoveToPreviousSiblingHeader'
+
+                                                                           *]c*
+- ']c': go to Current header. '<Plug>Markdown_MoveToCurHeader'
+
+                                                                           *]u*
+- ']u': go to parent header (Up). '<Plug>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 <Plug>Markdown_MoveToParentHeader
+<
+To disable a map use:
+>
+  map <Plug> <Plug>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 '<Enter>' 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
index 00c6b9f451b56432042f9b226c481b5211a0c6b3..4d293ee58fe9d6d7b8ebadb0cf0ebba47c2dd20c 100644 (file)
@@ -6,3 +6,4 @@ files:
   - syntax/markdown.vim
   - after/ftplugin/markdown.vim
   - indent/markdown.vim
   - syntax/markdown.vim
   - after/ftplugin/markdown.vim
   - indent/markdown.vim
+  - doc/vim-markdown.txt