Customize your own key mappings for Vim plugins

2010-11-21 12:29:26 +0900 / tag:vim / Comments
On Sun, 21 Nov 2010 04:58:17 +0900, **** **** <****@************> wrote:
> I am trying to figure out how to customize the textobj-entire plugin.
> The default mappings are for `ie` and `ae` to select the entire
> document. I would like to use `ia` and `aa` instead.

Short answer

Put the following lines in your vimrc:

xmap aa <Plug>(textobj-entire-a)
omap aa <Plug>(textobj-entire-a)
xmap ia <Plug>(textobj-entire-i)
omap ia <Plug>(textobj-entire-i)

Long answer

Most of plugins provide key mappings which start with <Plug>, and textobj-entire also provides <Plug> key mappings. See :help textobj-entire-mappings for the details. Such a key mapping is corresponding to a function of the plugin, and it is provided to define custom key mappings like the above lines.

In the case of textobj-entire, it provides text objects. So that aa and ia should be mapped to proper <Plug> key mappings in both Visual mode (with :xmap) and Operator-pending mode (with :omap).

Since aa and ia consist of usual alphabets, :xmap should be used instead of :vmap to avoid unexpected behavior in Select mode (see :help Select-mode-mapping for the details).

There are two kinds of Ex commands to define key mappings; one is :map family which expands key mappings recursively, and the other is :noremap family which does not expands recursively. <Plug>(textobj-entire-a) and other <Plug> key mappings are mapped to internal stuffs, so that custom key mappings such as aa must be expanded recursively. Therefore :xmap and others must be used instead of :xnoremap and others to define custom key mappings.

For example, imagine the following lines in your vimrc:

xnoremap <Plug>(textobj-entire-a)  **internal-stuff**
xmap aa-with-xmap  <Plug>(textobj-entire-a)
xnoremap aa-with-xnoremap  <Plug>(textobj-entire-a)

Whenever user types aa-with-xmap:

  1. aa-with-xmap is expanded to <Plug>(textobj-entire-a). aa-with-xmap is defined with :xmap, so
  2. <Plug>(textobj-entire-a) is expanded to **internal-stuff**.
  3. As a result, aa-with-xmap works properly because it does the same stuff as **internal-stuff**.

Whenever user types aa-with-xnoremap:

  1. aa-with-xnoremap is expanded to <Plug>(textobj-entire-a). aa-with-xnoremap is defined with :xnoremap, so
  2. <Plug>(textobj-entire-a) is not expanded to **internal-stuff**.
  3. As a result, aa-with-xnoremap does not properly because it does not the same stuff as **internal-stuff**.

Use Vim as syntax-highlighting filter for AsciiDoc

2010-11-03 20:12:10 +0900 / tag:asciidoc tag:vim / Comments

AsciiDoc documents can be converted into various formats, especially HTML family. And it’s possible to colorize source code embedded in an AsciiDoc document. AsciiDoc uses GNU Source-highlight (by default) or Pygments to colorize source code. Though both filters support many languages/formats, it’s not enough. For example, AsciiDoc format is not supported by both filters.

So that I tried using Vim as syntax-highlighting filter for AsciiDoc documents, and I succeeded. Here are the steps:

  1. Customize AsciiDoc configuration to use Vim as a syntax-highlighting filter – save the following content as custom.asciidoc.conf:

    source-style=template="source-highlight-block",presubs=(),postsubs=("callouts",),posattrs=("style","language","src_numbered","src_tab"),filter="highlight-with-vim filetype={language} {src_numbered!no}number {src_tab=tabstop=8}"
  2. Create the following script, save it as highlight-with-vim, then put it to a directory in PATH environment variable:

    # Usage: $0 {vim-option} ...
    # Notes:
    # - For some reason "-" doesn't work to read from the standard input.
    # - :TOhtml makes a link for each URI, but it's unwanted service.
    # - :TOhtml makes empty <span>s in many cases, but it's invalid result.
    # - For some reason Vim always exits with non-zero status.
    # - Vim can take up to 10 "-c" flags.
    vim -u NONE -i NONE -N -e -s \
    -c 'set encoding=utf-8' \
    -c 'syntax enable' \
    -c "setlocal ${*:-nonumber}" \
    -S <(cat <<'END'
      let g:html_ignore_folding = 1
      let g:html_use_css = 1
      let g:html_use_xhtml = 1
      silent! runtime syntax/2html.vim
      % substitute!\c<a\s\+[^<>]*>\([^<>]\{-}\)</a>!\1!g
      % substitute!\c<span\s\+[^<>]*>\(\_s\{-}\)<\/span>!\1!g
      /^<pre>$/+1,/^<\/pre>$/-1 print
    ) /dev/stdin
    # __END__
  3. Write CSS for syntax-highlighted text.

  4. Run the AsciiDoc command like the following:

    asciidoc -b xhtml11 -f custom.asciidoc.conf foo.txt

Then you’ll get a syntax-highlighted page like this page.