DOC: update documentation

Author: eigenfoo

README.md

@@ -3,8 +3,9 @@
 A Vim plugin for the [Stan probabilistic programming
 language](https://mc-stan.org/).
 
-![Screenshot of stan-vim syntax
-highlighting](https://raw.github.com/eigenfoo/stan-vim/master/screenshots/screenshot.png)
+<p align="center">
+  <img src="https://raw.github.com/eigenfoo/stan-vim/master/screenshots/screenshot.png" alt="Screenshot of stan-vim syntax highlighting">
+</p>
 
 ## Table of Contents
 
@@ -18,9 +19,9 @@ highlighting](https://raw.github.com/eigenfoo/stan-vim/master/screenshots/screen
 
 ## Features
 
-1. Syntax highlighting
-1. Automatic indentation
-1. Code folding
+1. Syntax highlighting of Stan types, keywords and built-in functions.
+1. Automatic indentation consistent the recommended Stan code style.
+1. Folding via code indentation.
 
 ## Installation
 

doc/stan.txt

@@ -27,24 +27,27 @@
 CONTENTS                                                        *stan-contents*
 
   1. Introduction.....................................|stan-intro|
-  2. Install..........................................|stan-install|
-  3. License..........................................|stan-license|
-  4. Contributing.....................................|stan-contrib|
-  5. Credits..........................................|stan-credits|
+  2. Installation.....................................|stan-install|
+  3. About............................................|stan-about|
+  4. License..........................................|stan-license|
+  5. Contributing.....................................|stan-contrib|
+  6. Credits..........................................|stan-credits|
 
 ===============================================================================
 INTRODUCTION                                                       *stan-intro*
 
+Vim plugin for the Stan (http://mc-stan.org) probabilistic programming language.
+
 Homepage: https://github.com/eigenfoo/stan-vim
 
-Vim plugin for the Stan (http://mc-stan.org) probabilistic programming language.
+Features include:
 
-  * Syntax highlighting
-  * Automatic indentation
-  * Code folding
+  * Syntax highlighting of Stan types, keywords and built-in functions.
+  * Automatic indentation consistent the recommended Stan code style.
+  * Folding via code indentation.
 
 ===============================================================================
-INSTALL                                                          *stan-install*
+INSTALLATION                                                     *stan-install*
 
   * For Vundle users, place this in your `.vimrc`:
 
@@ -65,6 +68,35 @@ INSTALL                                                          *stan-install*
 
   * For manual installation, copy all files into your `~/.vim` directory.
 
+===============================================================================
+ABOUT                                                              *stan-about*
+
+  * stan-vim supports syntax highlighting of Stan types, keywords and built-in
+    functions, including sampling statements and random number generators. All
+    syntax is manually defined in `syntax/stan.vim`.
+
+    - Refer to `syntax/stan.vim` for details.
+
+  * stan-vim supports automatic indentation consistent the recommended Stan code
+    style: that is, 2 spaces and no tabs.
+
+    - This is achieved by `setlocal expandtab`, and locally setting `tabstop`
+      and `shiftwidth` variables to 2.
+
+    - Furthermore, Vim will reindent when "closing characters" (such as `then`,
+      `else, and `}`) are entered. This is achieved by locally setting
+      `indentkeys`.
+
+    - Refer to `indent/stan.vim` for details.
+
+  * stan-vim supports folding via code indentation: that is, Vim will use code
+    indentation to determine which lines to fold. Thus, folding is dependent on
+    the recommended (or at least, consistent) indentation of Stan programs.
+
+    - This is achieved by `setlocal foldmethod=indent`.
+
+    - Refer to `ftplugin/stan/folding.vim` for details.
+
 ===============================================================================
 LICENSE                                                          *stan-license*
 
@@ -75,11 +107,31 @@ stan-vim is distributed under the MIT license. See the license file on GitHub:
 ===============================================================================
 CONTRIBUTING                                                     *stan-contrib*
 
+stan-vim is developed and maintained in a public repository on GitHub.
+
+      https://github.com/eigenfoo/stan-vim
+
+If you have a bug report, feature request or other question, please file an
+issue on GitHub:
+
+      https://github.com/eigenfoo/stan-vim/issues
+
+If you would like to send a patch or other code contribution to stan-vim, please
+submit a pull request through GitHub:
+
+      https://github.com/eigenfoo/stan-vim/pulls
 
 ===============================================================================
 CREDITS                                                          *stan-credits*
 
-  * Other Vim plugins for inspiration (stan.vim, mc-stan.vim, elm.vim)
   * stan-vim contributors:
 
         https://github.com/eigenfoo/stan-vim/graphs/contributors
+
+  * Steve Losh for his book, Learn Vimscript the Hard Way
+
+        http://learnvimscriptthehardway.stevelosh.com/
+
+  * Other Vim plugins for inspiration (specifically, stan.vim, mc-stan.vim and
+    elm.vim)
+