improving README

Author: dsanson

doc/pandoc.txt

@@ -1,98 +1,110 @@
 *pandoc.txt* 	For Vim version 7.3 	Last change: 2011 Aug 28
 
-# Vim Plugin for Pandoc                                            | *pandoc*
+Vim Plugin for *pandoc*
+=======================
 
 This is a bundle for writing and editing documents in [pandoc][]'s
-[extended markdown][].
+[extended markdown][]. It provides
 
-This documentation is only nominally formatted as a vim help file;
-really it is just markdown with a few vim help file tags between
-asterisks. (Someone want to write a vim-help writer module for pandoc?)
+-   some settings to make vim a pleasant |pandoc-writing-environment|,
+-   |pandoc-syntax-highlighting|, with support for pandoc's extended
+     markdown,
+-   |pandoc-snippets| for use with snipMate,
+-   |pandoc-section-folding|,
+-   |pandoc-citation-completion|,
+-   some simple |pandoc-conversion-functions| and |pandoc-tidying-functions|,
+-   a few |pandoc-localleader-mappings|
 
-In addition to reading this help file, you might take a look at the
-heavily commented ftplugin/pandoc.vim file.
+*pandoc-writing-enviroment*
+===========================
 
-## Known Gotchas
+The bundle sets the following options, in an effort to provide a pleasant writing environment:
 
-1. Filetype detection does not play well with the [markdown-vim plugin][].
-
-2. Filetype detection is aggressive: we assume that if you use this plugin,
-   then you want to use pandoc for you markdown needs. So we match the
-   following extensions: .markdown, .md, .mkd, .pd, .pdk, .pandoc, and .text.
+    setlocal linebreak
+    setlocal breakat-=*
 
-## Maintainers
+`linebreak` tells vim to break lines at word boundaries. `breakat-=*`
+expands vim's sense of a word boundary to handle markdown `*emphasis*`.
 
-+	[Felipe Morales](https://github.com/fmoralesc/)
-+	[David Sanson](https://github.com/dsanson/) 
+    nnoremap <buffer> j gj
+    nnoremap <buffer> k gk
+    vnoremap <buffer> j gj
+    vnoremap <buffer> k gk
 
-Thanks also to [Wei Dai][] for bug fixes and improvements.
+These mappings allow use of j and k to move up and down in the middle of
+a soft-wrapped line.
 
-## Stuff From Elsewhere
+    setlocal display=lastline
 
-The syntax file was originally by jeremy schultz (found [here][]) as
-githubbed by [wunki][].
+If you are using soft-wrapped line, this will tell vim to go ahead and
+show part of a long line that runs off the bottom of the screen.
 
-The snippets file, for use with [snipMate][], is a slight extension (and
-contraction) of the markdown.snippets file that is part of many of the
-[vim-markdown repositories on github][].
+    setlocal nojoinspaces
 
-Autocompletion was implemented by hacking away at [LaTeX Box][]'s
-implementation of bibtex citation completion, even if the results don't
-look much like the original.
+allows you to use CTRL-J to join the next line with the current line
+without adding extra unwanted spaces.
 
-## Features
+    setlocal commentstring=<!--%s-->
+    setlocal comments=s:<!--,m:\ \ \ \ ,e:-->
 
-Here are some key features:
+tells vim that, in your markdown files, use HTML-style commenting.
 
--   Applies settings to make vim a pleasant writing environment.
-    -   soft/hard word wrapping (configurable)
-    -   intelligent line joining
-    -   pandoc-powered tidying up
-    -   other little tweaks along these lines
+*pandoc-hard-wrapping*
+----------------------
 
-Specifically:
+By default, the bundle assumes that you will be using soft wrapping, and
+applies
 
     setlocal formatoptions=1
-    setlocal linebreak
-    nnoremap <buffer> j gj
-    nnoremap <buffer> k gk
-    vnoremap <buffer> j gj
-    vnoremap <buffer> k gk
-    setlocal display=lastline
-    setlocal nojoinspaces
-    setlocal commentstring=<!--%s-->
-    setlocal comments=s:<!--,m:\ \ \ \ ,e:-->
 
-Additional tweaks welcome. Feedback also welcome on whether this is
-appropriate. It would be easy to make some or all of this optional.
+If you prefer hard wrapping, set g:pandoc_use_hard_wraps, i.e., put
+something like
+
+    let g:pandoc_use_hard_wraps = 1
+
+in your vimrc. When that is set, the bundle instead sets
+
+    setlocal formatoptions=qct
 
-Hard word wrapping can be used by setting `g:pandoc_use_hard_wraps` to 1
-in the .vimrc. It will set `formatoptions` to `qct` instead of `1`.
+If you also want autoformatting, set g:pandoc_auto_format:
 
--   Syntax highlighting with support for definition lists, numbered
-    examples, delimited code blocks, LaTeX and HTML, citations,
-    footnotes, ....
+    let g:pandoc_auto_format = 1
 
--   Some snippets for use with snipMate (David says: I never use these,
-    so they could probably use improvement. If you improve them, let
-	us know).
+in your vimrc. (Note that autoformatting can slow things down.)
 
--   Folding of sections. (See `:help fold-commands` if you haven't used
-    vim's folding before.). Quick tips:
+*pandoc-syntax-highlighting*
+============================
 
-    -   `za` toggles folds open and closed (`zA` toggles fold and all
-        its children open and closed)
-    -   `zc` closes a fold (`zC` closes it and all its children)
-    -   `zo` opens a fold (`zO` opens it and all its children).
+The syntax highlighting should be fairly accurate and complete. By
+default, the bundle tries to be smart, and only highlight implicit links
+if there is a matching link definition. This can be expensive on large
+files and slow things down. To disable it, set
+g:pandoc_no_empty_implicits:
 
--   Autocompletion of citations (more details below).
+    let g:pandoc_no_empty_implicits = 1
 
--   Some simple pandoc-powered conversion and tidying functions.
+*pandoc-snippets*
+=================
 
-ftplugin/pandoc.vim is fairly well-commented. Take a look at it to see
-what it does in detail.
+If you use snipMate, take a look at snippets/pandoc.snippets to see what
+is available. One nice example: at the start of a document, type
+`%%<TAB>` to generate a title block, with the filename as title, the
+value of `g:snips-author` as author, and the current date.
 
-## Citation Autocompletion                     | *pandoc-citation-completion*
+*pandoc-section-folding*
+========================
+
+The bundle tells vim to fold documents by section. If you haven't used
+folding before, see |fold-commands|. When used with [FoldList][] this
+also provides a handy navigable outline view of your document.
+
+But folding can slow things down. To disable it, set
+g:pandoc_no_folding:
+
+    let g:pandoc_no_folding = 1
+
+*pandoc-citation-completion*
+============================
 
 If you have a bibtex file (or a symlink to a bibtex file) named
 'default.bib' in one of these folders,
@@ -102,17 +114,17 @@ If you have a bibtex file (or a symlink to a bibtex file) named
     ~/texmf/bibtex/bib
 
 then the plugin will automatically use that file for citation
-autocompletion. If you define `g:PandocBibfile` in your vimrc,
+completion. Or, set g:pandoc_bibfile:
 
-    let g:PandocBibfile = '/the/path/to/your/bibtex/file.bib'
+    let g:pandoc_bibfile = '/the/path/to/your/bibtex/file.bib'
 
-then that file will be used instead.
+to use your preferred file.
 
-To use autocompletion, start typing a citekey, e.g.,
+To use completion, start typing a citekey, e.g.,
 
     @geac
 
-and then, while still in insert mode, hit ctrl-x ctrl-o (vim's shortcut
+and then, while still in insert mode, hit CTRL-X CTRL-O (vim's shortcut
 for omnicompletion), and you'll get a popup window with a list of
 matching keys, e.g.,
 
@@ -132,43 +144,27 @@ will want something like this in your vimrc:
     let g:SuperTabDefaultCompletionType = "context"
 
 Then you can just hit TAB in the middle of typing a citation
-to autocomplete the citation.
+to complete the citation.
 
 > **KNOWN BUGS**:
 >
-> -   SuperTab autocompletion of citations only works after you use ctrl-x
->     ctrl-o autocompletion once within a given file.
+> -   SuperTab completion of citations only works after you use ctrl-x
+>     ctrl-o completion once within a given file.
 > -   Regular expressions don't work when using SuperTab.
 
 > **TODO**: pandoc.vim should be smarter about finding bibliography
 > files. This includes:
 >
+> -   borrowing settings from latex plugins, if present
 > -   finding the local texmf tree programatically
 > -   using (all?) bibtex files found in any of the search paths
 > -   including the directory that the file is in among the search paths
-> -   better support for other bibliography database formats (the parser
->     currently works with bibtex and MODS xml files, but the script
->     doesn't look for MODS xml files)
-
-## Configuration
+> -   better support for other bibliography database formats
 
-Some global variables can modify the plugin's behaviour and performance:
+*pandoc-citation-dictionary*
+----------------------------
 
-1. As mentioned before, soft or hard wrapping can be set with the
-   `g:pandoc_use_hard_wraps` variable set to 1.
-   If desired when using hard wrapping, vim-pandoc will activate
-   autoformatting is `g:pandoc_auto_format` is set to 1. Note that this can be
-   slow.
-
-2. Folding can be disabled by setting `g:pandoc_no_folding` to 1. This can
-   improve performance.
-
-3. Highlighting of empty implicit links can be expensive on large files. To
-   disable it, set `g:pandoc_no_empty_implicits` to 1.
-
-## Dictionary-Based Citation Completions
-
-We are leaving this in for now, but now that proper autocompletion is
+We are leaving this in for now, but now that proper completion is
 working, we'll probably get rid of it. If you create a text file,
 `
     ~/.pandoc/citationkeys.dict
@@ -187,21 +183,55 @@ autocompletion by typing part of a citekey, e.g.,
 
     @adams19
 
-and then hitting ctrl-x ctrl-k (or via SuperTab).
+and then hitting CTRL-X CTRL-K (or via SuperTab).
 
-## Conversion and Tidying Up | *MarkdownTidy* *MarkdownTidyWrap* *PandocHtmlOpen* *PandocPdfOpen* *PandocOdtOpen*
+*pandoc-conversion-functions*
+=============================
 
-Look at the comments in ftpugin/pandoc.vim to see what is there. We've
-made no attempt to provide a complete set of commands, since it is easy
-to do something like
+Pandoc can be used to perform lots of different conversions. We've
+made no attempt to provide functions that cover all these possibilities,
+since it is easy to do something like
 
     :!markdown2pdf %
 
 If there is a particular conversion that you do all the time with a
 particular set of options, you might want to define a leader mapping
 in your vimrc.
 
-The plugin sets
+*PandocHtmlOpen*, *PandocPdfOpen* and *PandocOdtOpen*
+-----------------------------------------------------
+
+We currently provide three convert-and-open functions. When you run *PandocPdfOpen*, for example, the file in the current buffer is converted to PDF and then opened in your default PDF viewer. (Linux users: these commands depend on xdg-open.)
+
+If you have defined maplocalleader in your vimrc, e.g.,
+
+    let maplocalleader = ","
+
+then we will define localleader mappings for each of these commands:
+
+    <localleader>pdf
+    <localleader>odt
+    <localleader>html
+
+So then you can type something like `,pdf` and a PDF version of your current buffer will be displayed.
+
+*pandoc-tidying-functions*
+==========================
+
+The plugin defines two functions designed for tidying up your markdown:
+*MarkdownTidy* and *MarkdownTidyWrap*. Running MarkdownTidyWrap is
+equivalent to
+
+    :%!pandoc -t markdown -s
+
+Note that this can have some unexpected effects: it will replace all of
+your reference link ids with implicit reference links; it will replace
+all of your footnote ids with numbers; it will transform any setext
+style headers into atx style headers; it will process any latex macros
+you may have defined and delete the macro definitions; if your document
+lacks a title block, it will add one.
+
+The plugin also sets
 
     setlocal equalprg=pandoc\ -t\ markdown\ --reference-links
 
@@ -211,47 +241,55 @@ this to
 
     setlocal equalprg=pandoc\ -t\ markdown\ --reference-links\ --no-wrap
 
-Either way, there are a few gotchas to be aware of:
+Note that this will *remove* any title block, as well as processing any
+custom latex macros. So you might not want to `ggvG=`.
 
-1.  The filter will remove pandoc's title block, if that is included in
-    the chunk of filtered text.
-2.  The filter will apply and remove any latex macros you might have
-    defined, if they are included in the chunk of filtered text.
+Maintainers
+===========
 
-So keep your metadata and macros at the top of the file, and avoid
-filtering them with `=`.
++    [Felipe Morales](https://github.com/fmoralesc/)
++    [David Sanson](https://github.com/dsanson/) 
 
-If you know how to work around these problems, let us know (or better,
-fork and fix it).
+Thanks also to [Wei Dai][] for bug fixes and improvements.
 
-## LocalLeader Mappings                      | *pandoc-local-leader-mappings*
+Borrowings
+==========
 
-If you define maplocalleader in your vimrc,
+The syntax file was originally by jeremy schultz (found [here][]) as
+githubbed by [wunki][].
 
-    let maplocalleader = ","
+The snippets file, for use with [snipMate][], is a slight extension (and
+contraction) of the markdown.snippets file that is part of many of the
+[vim-markdown repositories on github][].
 
-then the plugin will define some leader mappings for you. For example,
+Autocompletion was implemented by hacking away at [LaTeX Box][]'s
+implementation of bibtex citation completion, even if the results don't
+look much like the original.
 
-    <localleader>pdf
-    <localleader>odt
-    <localleader>html
+Known Issues
+============
+
+1. Filetype detection does not play well with the [markdown-vim plugin][].
+
+2. Filetype detection is aggressive: we assume that if you use this plugin,
+   then you want to use pandoc for you markdown needs. So we match the
+   following extensions: .markdown, .md, .mkd, .pd, .pdk, .pandoc, and .text.
 
-which convert the buffer to given format and open the results.
 
 * * * *
 
   [pandoc]: http://johnmacfarlane.net/pandoc/
   [extended markdown]: http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown
   [markdown-vim plugin]: http://plasticboy.com/markdown-vim-mode/
-  [Felipe Morales]: https://github.com/fmoralesc
   [Wei Dai]: https://github.com/clvv
   [here]: http://www.vim.org/scripts/script.php?script_id=2389
   [wunki]: https://github.com/wunki/vim-pandoc
   [snipMate]: http://www.vim.org/scripts/script.php?script_id=2540
   [vim-markdown repositories on github]: https://github.com/hallison/vim-markdown
   [LaTeX Box]: http://www.vim.org/scripts/script.php?script_id=3109
   [SuperTab]: http://www.vim.org/scripts/script.php?script_id=1643
+  [FoldList]: http://www.vim.org/scripts/script.php?script_id=500
+
 
+ vim:tw=78:ts=8:ft=help:norl: 
 
-<!-- vim:tw=78:ts=8:ft=pandoc:norl: 
--->