Document BufWritePost example, improve documentation structure (issue #46)

Issue #46 on GitHub:
  https://github.com/xolox/vim-easytags/issues/46

1 files changed, 50 insertions, 27 deletions

diff --git a/doc/easytags.txt b/doc/easytags.txt
index 2aba0dc..f6edef1 100644
--- a/doc/easytags.txt
+++ b/doc/easytags.txt
@@ -27,19 +27,21 @@ Contents ~
   14. The |g:easytags_resolve_links| option
   15. The |g:easytags_suppress_ctags_warning| option
   16. The |g:easytags_ignored_syntax_groups| option
- 5. Faster syntax highlighting using Python |easytags-faster-syntax-highlighting-using-python|
+ 5. Customizing the easytags plug-in              |customizing-easytags-plug-in|
+  1. Passing custom command line arguments to Exuberant Ctags
+  2. Update & highlight tags immediately after save
+  3. How to customize the highlighting colors?
+ 6. Faster syntax highlighting using Python |easytags-faster-syntax-highlighting-using-python|
   1. The |g:easytags_python_enabled| option
   2. The |g:easytags_python_script| option
- 6. How to customize the highlighting colors?
- 7. Passing custom command line arguments to Exuberant Ctags
- 8. Troubleshooting                                   |easytags-troubleshooting|
+ 7. Troubleshooting                                   |easytags-troubleshooting|
   1. |:HighlightTags| only works for the tags file created by |:UpdateTags|
   2. The plug-in complains that Exuberant Ctags isn't installed
   3. Vim locks up while the plug-in is running
   4. Failed to highlight tags because pattern is too big!
   5. The plug-in doesn't seem to work in Cygwin
- 9. Contact                                                   |easytags-contact|
- 10. License                                                  |easytags-license|
+ 8. Contact                                                   |easytags-contact|
+ 9. License                                                   |easytags-license|
 
 ===============================================================================
                                                          *easytags-introduction*
@@ -423,28 +425,37 @@ This variable is a string of comma separated names of syntax groups in which
 dynamic highlighting is not applied. It defaults to '.*String.*,.*Comment.*,cIncluded'.
 
 ===============================================================================
-                              *easytags-faster-syntax-highlighting-using-python*
-Faster syntax highlighting using Python ~
+                                                  *customizing-easytags-plug-in*
+Customizing the easytags plug-in ~
 
-The Vim script implementation of dynamic syntax highlighting is quite slow on
-large tags files. When the Python Interface to Vim is enabled the easytags
-plug-in will therefor automatically use a Python script that performs dynamic
-syntax highlighting about twice as fast as the Vim script implementation. The
-following options are available to change the default configuration.
+Advanced users may wish to customize how the easytags plug-in works beyond the
+point of changing configuration defaults. This section contains some hints
+about this. If you have suggestions, please feel free to submit them.
 
 -------------------------------------------------------------------------------
-The *g:easytags_python_enabled* option
+Passing custom command line arguments to Exuberant Ctags ~
 
-To disable the Python implementation of dynamic syntax highlighting you can
-set this option to false (0).
+You may want to run Exuberant Ctags with specific command line options, for
+example the code_complete [13] plug-in requires the signature field to be
+present. To do this you can create a configuration file for Exuberant Ctags,
+e.g. '~/.ctags' on UNIX or '%USERPROFILE%\ctags.cnf' on Windows. The file
+should contain one command line option per line. See the Exuberant Ctags
+manual [14] for details.
 
 -------------------------------------------------------------------------------
-The *g:easytags_python_script* option
+Update & highlight tags immediately after save ~
 
-This option defines the pathname of the script that contains the Python
-implementation of dynamic syntax highlighting.
+By default the easytags plug-in automatically updates & highlights tags for
+the current file after several seconds of inactivity. This is done to prevent
+the easytags plug-in from interrupting your workflow.
 
-===============================================================================
+If you want the easytags plug-in to automatically update & highlight tags for
+the current file right after you save the file, you can add the following line
+to your |vimrc| script:
+>
+    :autocmd BufWritePost * call xolox#easytags#autoload('BufWritePost')
+
+-------------------------------------------------------------------------------
 How to customize the highlighting colors? ~
 
 The easytags plug-in defines new highlighting groups for dynamically
@@ -484,14 +495,26 @@ tried to match the existing highlighting groups defined by popular syntax
 modes (except of course for the 'Tag' suffix).
 
 ===============================================================================
-Passing custom command line arguments to Exuberant Ctags ~
+                              *easytags-faster-syntax-highlighting-using-python*
+Faster syntax highlighting using Python ~
 
-You may want to run Exuberant Ctags with specific command line options, for
-example the code_complete [13] plug-in requires the signature field to be
-present. To do this you can create a configuration file for Exuberant Ctags,
-e.g. '~/.ctags' on UNIX or '%USERPROFILE%\ctags.cnf' on Windows. The file
-should contain one command line option per line. See the Exuberant Ctags
-manual [14] for details.
+The Vim script implementation of dynamic syntax highlighting is quite slow on
+large tags files. When the Python Interface to Vim is enabled the easytags
+plug-in will therefor automatically use a Python script that performs dynamic
+syntax highlighting about twice as fast as the Vim script implementation. The
+following options are available to change the default configuration.
+
+-------------------------------------------------------------------------------
+The *g:easytags_python_enabled* option
+
+To disable the Python implementation of dynamic syntax highlighting you can
+set this option to false (0).
+
+-------------------------------------------------------------------------------
+The *g:easytags_python_script* option
+
+This option defines the pathname of the script that contains the Python
+implementation of dynamic syntax highlighting.
 
 ===============================================================================
                                                       *easytags-troubleshooting*