Moved all documentation from pyref.vim to README.md

README.md

@@ -1,49 +1,109 @@
-The file [pyref.vim][formatted_pyref_vim] is a plug-in for the Vim text editor
-that maps the `<F1>` key in Python buffers to search through the Python
-language and library reference documentation for the keyword or identifier at
-the current cursor position and open the first match in your web browser. When
-no GUI is available a command-line web browser like `lynx` or `w3m` will be
-used, otherwise the plug-in prefers a graphical web browser like Mozilla
-Firefox or Google Chrome.
+# Context-sensitive documentation <br> for Python source code in Vim
+
+The file [pyref.vim] [view_plugin] is a plug-in for the [Vim text editor]
+[vim_homepage] that maps the `<F1>` key in [Python] [python_homepage] buffers
+to search through the [Python language reference] [pylangref] and [library
+reference] [pylibref] documentation for the keyword or identifier at the
+current cursor position and open the first match in your web browser. When no
+GUI is available a command-line web browser like `lynx` or `w3m` will be used,
+otherwise the plug-in prefers a graphical web browser like Mozilla Firefox or
+Google Chrome.
+
+## How does it work?
 
 The search works by scanning through a special index file with keyword, URL
 pairs separated by tabs and delimited by newlines. You can create this index
-yourself using a Python script I've written (see [create-index.py][formatted_create_index_py])
-or you can download the index that I've already created (see [vimpythonindex][formatted_vimpythonindex]).
+yourself using a Python script I've written (see the file [create-index.py]
+[view_spider]) or you can download the index that I've already created (see
+the file [vimpythonindex] [view_index]).
+
+## Usage and options
 
-[formatted_pyref_vim]: http://github.com/xolox/vim-pyref/blob/master/pyref.vim
-[formatted_create_index_py]: http://github.com/xolox/vim-pyref/blob/master/create-index.py
-[formatted_vimpythonindex]: http://github.com/xolox/vim-pyref/blob/master/vimpythonindex
+Right-click and save the file [pyref.vim][download_plugin] as
+`~/.vim/plugin/pyref.vim` (if you're on Windows save the file as
+`%USERPROFILE%\vimfiles\plugin\pyref.vim` instead), likewise save the file
+[vimpythonindex][download_index] as `~/.vimpythonindex` (if you're on Windows
+then save this file as `%USERPROFILE%\_vimpythonindex` instead) and restart
+Vim. Now try it out: Open some Python source code in Vim and press the `<F1>`
+key. If it doesn't work at first, please see the `pyref_browser` and
+`pyref_mapping` options below.
 
- USAGE
-=======
+The following paragraphs explain the available options:
 
-Right-click and save [pyref.vim][raw_pyref_vim] as `~/.vim/plugin/pyref.vim`
-(if you're on Windows save the file as `%USERPROFILE%\vimfiles\plugin\pyref.vim`),
-likewise save [vimpythonindex][raw_vimpythonindex] as `~/.vimpythonindex` (if
-you're on Windows then save this file as `%USERPROFILE%\_vimpythonindex`) and
-restart Vim. Now try it out: Open some Python source code in Vim and press the
-`<F1>` key. If it doesn't work out of the box you probably need to change the
-global variable `pyref_browser` to the filename or pathname of a working web
-browser executable, e.g. inside Vim type:
+### The `pyref_browser` option
+
+If the plug-in doesn't work out of the box or you don't like the default web
+browser you can change the global variable `pyref_browser` to the filename or
+pathname of your preferred web browser, e.g. inside Vim type:
 
     :let pyref_browser = '/usr/bin/konqueror'
 
-[raw_pyref_vim]: http://github.com/xolox/vim-pyref/raw/master/pyref.vim
-[raw_vimpythonindex]: http://github.com/xolox/vim-pyref/raw/master/vimpythonindex
+The plug-in tries to find a suitable default web browser but that might not
+always work. To see the currently configured web browser type the following:
+
+    :let pyref_browser
+
+### The `pyref_mapping` option
+
+When you've set `pyref_browser` but it still doesn't work you're probably
+running Vim inside a terminal which doesn't support `<F1>`. In this case you
+can change the key-mapping by setting the global variable `pyref_mapping`
+according to the syntax expected by Vim's `:imap` and `:nmap` commands:
+
+    :let pyref_mapping = 'K'
+
+Note that setting `pyref_mapping` won't change the mapping in existing buffers.
+
+### The `pyref_mirror` option
 
- CONTACT
-=========
+The option `pyref_mirror` is useful when you don't always have a reliable
+internet connection available while coding. Most Linux distributions have an
+installable package containing the Python documentation, for example on Ubuntu
+and Debian you can execute the following command to install the documentation:
+
+    sudo apt-get install python2.6-doc
+
+The above package puts the documentation in `/usr/share/doc/python2.6/html/`
+which happens to be the default location checked by the [pyref.vim]
+[view_plugin] script. If you've installed the documentation elsewhere, change
+the global variable `pyref_mirror` accordingly.
+
+### The `pyref_index` option
+
+If you don't like the default location of the index file you can change it by
+setting the global variable `pyref_index`. Note that a leading `~` in the path
+is expanded to your current home directory (`$HOME` on UNIX, `%USERPROFILE%` on
+Windows).
+
+### General note about options
+
+You can change any of the above options permanently by putting the relevant
+`:let` statements in your `~/.vimrc` script (on UNIX) or `%USERPROFILE%\_vimrc`
+script (on Windows). If you set `pyref_browser` and/or `pyref_mirror` in your
+`vimrc` this can improve Vim's startup speed slightly because the plug-in won't
+have to query the file-system when it's loaded.
+
+## Contact
 
 If you have questions, bug reports, suggestions, etc. the author can be
 contacted at <peter@peterodding.com>. The latest version is available
 at <http://peterodding.com/code/vim/pyref> and <http://github.com/xolox/vim-pyref>.
-If you like the script you can vote for it on [vim.org][vim_scripts_entry].
+If you like the script please vote for it on [vim.org][vim_scripts_entry].
 
-[vim_scripts_entry]: http://www.vim.org/scripts/script.php?script_id=3104
+## License
 
- LICENSE
-=========
+Vim-PyRef is licensed under the [MIT license] [mit_license].<br>
+© 2010 Peter Odding &lt;<peter@peterodding.com>&gt;.
 
-Vim-PyRef is licensed under the MIT license.
-Copyright 2010 Peter Odding <peter@peterodding.com>.
+
+[download_index]: http://github.com/xolox/vim-pyref/raw/master/vimpythonindex
+[download_plugin]: http://github.com/xolox/vim-pyref/raw/master/pyref.vim
+[mit_license]: http://en.wikipedia.org/wiki/MIT_License
+[pylangref]: http://docs.python.org/reference/index.html
+[pylibref]: http://docs.python.org/library/index.html
+[python_homepage]: http://python.org/
+[view_index]: http://github.com/xolox/vim-pyref/blob/master/vimpythonindex
+[view_plugin]: http://github.com/xolox/vim-pyref/blob/master/pyref.vim
+[view_spider]: http://github.com/xolox/vim-pyref/blob/master/create-index.py
+[vim_homepage]: http://www.vim.org/
+[vim_scripts_entry]: http://www.vim.org/scripts/script.php?script_id=3104

pyref.vim

@@ -1,49 +1,10 @@
 " Vim plug-in
 " Maintainer: Peter Odding <peter@peterodding.com>
-" Last Change: June 1, 2010
+" Last Change: June 3, 2010
 " URL: http://peterodding.com/code/vim/pyref
 " License: MIT
 
-" Description:
-" This is a Vim plug-in that maps <F1> in Python buffers to search the Python
-" language and library reference documentation for the keyword or identifier
-" at the current cursor position and open the first match in your web browser.
-" This should work in both graphical Vim and console Vim. The search works by
-" scanning through a special index file with keyword, URL pairs separated by
-" tabs and delimited by newlines. You can create this index yourself using a
-" Python script I've written or you can download an index that I'm making
-" available based on http://docs.python.org/.
-"
-" Configuration options:
-"
-"  "pyref_mapping": If you don't want this plug-in to use the <F1> key then
-"                   you can change this global variable according to the
-"                   syntax expected by :imap and :nmap.
-"  "pyref_browser": If the plug-in doesn't work out of the box you might have
-"                   to change this global variable to the filename or pathname
-"                   of your web browser (the plug-in tries to find a sensible
-"                   default but that might not always work).
-"  "pyref_index":   Set this global variable to change the location of the
-"                   index file from its default (on Windows the default is
-"                   "~/_vimpythonindex", on UNIX it is "~/.vimpythonindex").
-"  "pyref_mirror":  Sometimes I don't have an internet connection available,
-"                   therefor I've installed the Ubuntu package `python2.6-doc'
-"                   which puts the Python language and library reference in
-"                   /usr/share/doc/python2.6/html/. If you're using the exact
-"                   same package everything should just work, but if you've
-"                   installed the Python documentation in another location
-"                   you should set this global variable to the pathname of the
-"                   directory containing the HTML files.
-"
-" Note that you can change any of these options permanently by putting the
-" relevant :let statements in your ~/.vimrc script.
-"
-" Tweaks:
-" You can improve Vim's startup speed slightly by setting the global variables
-" "pyref_browser" and/or "pyref_mirror" in your ~/.vimrc because that avoids
-" querying the file system and searching the $PATH.
-
-" Define the configuration defaults.
+" Configuration defaults. {{{1
 
 if !exists('pyref_index')
   if has('win32') || has('win64')
@@ -103,13 +64,13 @@ if !exists('pyref_browser')
   endif
 endif
 
-" Use an automatic command to map <F1> only inside Python buffers.
+" Automatic command to define key-mapping. {{{1
 
 augroup PluginPyRef
   autocmd! FileType python call s:DefineMappings()
 augroup END
 
-function! s:DefineMappings()
+function! s:DefineMappings() " {{{1
   let command = '%s <silent> <buffer> %s %s:call <Sid>PyRef()<CR>'
   " Always define the normal mode mapping.
   execute printf(command, 'nmap', g:pyref_mapping, '')
@@ -120,16 +81,7 @@ function! s:DefineMappings()
   endif
 endfunction
 
-" This list of lists contains [url_format, method_pattern] pairs that are used
-" to recognize calls to methods of objects that are one of Python's standard
-" types: strings, lists, dictionaries and file handles.
-let s:object_methods = [
-      \ ['library/stdtypes.html#str.%s', '\.\@<=\(capitalize\|center\|count\|decode\|encode\|endswith\|expandtabs\|find\|format\|index\|isalnum\|isalpha\|isdigit\|islower\|isspace\|istitle\|isupper\|join\|ljust\|lower\|lstrip\|partition\|replace\|rfind\|rindex\|rjust\|rpartition\|rsplit\|rstrip\|split\|splitlines\|startswith\|strip\|swapcase\|title\|translate\|upper\|zfill\)$'],
-      \ ['tutorial/datastructures.html#more-on-lists', '\.\@<=\(append\|count\|extend\|index\|insert\|pop\|remove\|reverse\|sort\)$'],
-      \ ['library/stdtypes.html#dict.%s', '\.\@<=\(clear\|copy\|fromkeys\|get\|has_key\|items\|iteritems\|iterkeys\|itervalues\|keys\|pop\|popitem\|setdefault\|update\|values\)$'],
-      \ ['library/stdtypes.html#file.%s', '\.\@<=\(close\|closed\|encoding\|errors\|fileno\|flush\|isatty\|mode\|name\|newlines\|next\|read\|readinto\|readline\|readlines\|seek\|softspace\|tell\|truncate\|write\|writelines\|xreadlines\)$']]
-
-function! s:PyRef()
+function! s:PyRef() " {{{1
 
   " Get the identifier under the cursor including any dots to match
   " identifiers like `os.path.join' instead of single words like `join'.
@@ -196,7 +148,16 @@ function! s:PyRef()
 
 endfunction
 
-function! s:JumpToEntry(lines, pattern)
+" This list of lists contains [url_format, method_pattern] pairs that are used
+" to recognize calls to methods of objects that are one of Python's standard
+" types: strings, lists, dictionaries and file handles.
+let s:object_methods = [
+      \ ['library/stdtypes.html#str.%s', '\.\@<=\(capitalize\|center\|count\|decode\|encode\|endswith\|expandtabs\|find\|format\|index\|isalnum\|isalpha\|isdigit\|islower\|isspace\|istitle\|isupper\|join\|ljust\|lower\|lstrip\|partition\|replace\|rfind\|rindex\|rjust\|rpartition\|rsplit\|rstrip\|split\|splitlines\|startswith\|strip\|swapcase\|title\|translate\|upper\|zfill\)$'],
+      \ ['tutorial/datastructures.html#more-on-lists', '\.\@<=\(append\|count\|extend\|index\|insert\|pop\|remove\|reverse\|sort\)$'],
+      \ ['library/stdtypes.html#dict.%s', '\.\@<=\(clear\|copy\|fromkeys\|get\|has_key\|items\|iteritems\|iterkeys\|itervalues\|keys\|pop\|popitem\|setdefault\|update\|values\)$'],
+      \ ['library/stdtypes.html#file.%s', '\.\@<=\(close\|closed\|encoding\|errors\|fileno\|flush\|isatty\|mode\|name\|newlines\|next\|read\|readinto\|readline\|readlines\|seek\|softspace\|tell\|truncate\|write\|writelines\|xreadlines\)$']]
+
+function! s:JumpToEntry(lines, pattern) " {{{1
   let index = match(a:lines, a:pattern)
   if index >= 0
     let url = split(a:lines[index], '\t')[1]
@@ -206,7 +167,7 @@ function! s:JumpToEntry(lines, pattern)
   return 0
 endfunction
 
-function! s:OpenBrowser(url)
+function! s:OpenBrowser(url) " {{{1
   let browser = g:pyref_browser
   if browser =~ '\<\(lynx\|links\|w3m\)\>'
     execute '!' . browser fnameescape(a:url)