diff --git a/doc/airline.txt b/doc/airline.txt
index 1b05d7b..0ee558d 100644
--- a/doc/airline.txt
+++ b/doc/airline.txt
@@ -71,7 +71,7 @@ values):
     endif
   endfunction
 <
-* enable/disable usage of patched powerline font symbols >
+* enable/disable automatic selection of patched powerline font symbols >
   let g:airline_powerline_fonts=0
 <
 * define the set of text to display for each mode.  >
@@ -162,9 +162,10 @@ Note: You must define the dictionary first before setting values: >
 For more intricate customizations, you can replace the predefined sections
 with the usual statusline syntax.
 
-Note: Many of these settings can also be controlled with |airline-configuration|
-variables, which is useful for sections which by default host more than one
-extension.
+Note: If you define any section variables it will replace the default values
+entirely.  If you want to disable only certain parts of a section you can try
+using variables defined in the |airline-configuration| or |airline_extensions|
+section.
 >
   variable names                default contents
   ----------------------------------------------------------------------------
@@ -188,7 +189,7 @@ EXTENSIONS                                              *airline-extensions*
 Most extensions are enabled by default and lazily loaded when the
 corresponding plugin (if any) is detected.
 
-                                                           *airline-default*
+-------------------------------------                      *airline-default*
 The default extension understands all of the `g:` variables in the
 |airline-configuration| section, however it also has some more fine-tuned
 configuration values that you can use.
@@ -204,7 +205,7 @@ configuration values that you can use.
   " Note: set to an empty dictionary to disable truncation.
   let g:airline#extensions#default#section_truncate_width = {}
 <
-                                                        *airline-bufferline*
+-------------------------------------                   *airline-bufferline*
 vim-bufferline <https://github.com/bling/vim-bufferline>
 
 * enable/disable bufferline integration >
@@ -213,7 +214,7 @@ vim-bufferline <https://github.com/bling/vim-bufferline>
 * determine whether bufferline will overwrite customization variables >
   let g:airline#extensions#bufferline#overwrite_variables = 1
 <
-                                                            *airline-branch*
+-------------------------------------                       *airline-branch*
 fugitive.vim <https://github.com/tpope/vim-fugitive>
 lawrencium   <https://bitbucket.org/ludovicchabant/vim-lawrencium>
 
@@ -223,19 +224,19 @@ lawrencium   <https://bitbucket.org/ludovicchabant/vim-lawrencium>
 * change the text for when no branch is detected >
   let g:airline#extensions#branch#empty_message = ''
 <
-                                                         *airline-syntastic*
+-------------------------------------                    *airline-syntastic*
 syntastic <https://github.com/scrooloose/syntastic>
 
 * enable/disable syntastic integration >
   let g:airline#extensions#syntastic#enabled = 1
 <
-                                                            *airline-tagbar*
+-------------------------------------                       *airline-tagbar*
 tagbar <https://github.com/majutsushi/>
 
 * enable/disable tagbar integration >
   let g:airline#extensions#tagbar#enabled = 1
 <
-                                                               *airline-csv*
+-------------------------------------                          *airline-csv*
 csv.vim <https://github.com/chrisbra/csv.vim>
 
 * enable/disable csv integration for displaying the current column. >
@@ -245,7 +246,7 @@ csv.vim <https://github.com/chrisbra/csv.vim>
   let g:airline#extensions#csv#column_display = 'Number' (default)
   let g:airline#extensions#csv#column_display = 'Name'
 <
-                                                             *airline-hunks*
+-------------------------------------                        *airline-hunks*
 vim-gitgutter <https://github.com/airblade/vim-gitgutter>
 vim-signify <https://github.com/mhinz/vim-signify>
 
@@ -258,7 +259,7 @@ vim-signify <https://github.com/mhinz/vim-signify>
 * set hunk count symbols. >
   let g:airline#extensions#hunks#hunk_symbols = ['+', '~', '-']
 <
-                                                        *airline-whitespace*
+-------------------------------------                   *airline-whitespace*
 * enable/disable detection of whitespace errors. >
   let g:airline#extensions#whitespace#enabled = 1
 <
@@ -275,7 +276,7 @@ vim-signify <https://github.com/mhinz/vim-signify>
   let g:airline#extensions#whitespace#trailing_format = 'trailing[%s]'
   let g:airline#extensions#whitespace#mixed_indent_format = 'mixed-indent[%s]'
 <
-                                                             *airline-ctrlp*
+-------------------------------------                        *airline-ctrlp*
 ctrlp <https://github.com/kien/ctrlp.vim>
 
 * configure which mode colors should ctrlp window use (takes effect
@@ -285,8 +286,7 @@ ctrlp <https://github.com/kien/ctrlp.vim>
   let g:airline#extensions#ctrlp#color_template = 'visual'
   let g:airline#extensions#ctrlp#color_template = 'replace'
 <
-                                                        *airline-virtualenv*
-
+-------------------------------------                   *airline-virtualenv*
 virtualenv <https://github.com/jmcantrell/vim-virtualenv>
 
 * enable/disable virtualenv integration >
@@ -298,7 +298,7 @@ FUNCREFS                                                  *airline-funcrefs*
 vim-airline internally uses funcrefs to integrate with third party plugins,
 and you can tap into this functionality to extend it for you needs.
 
-                                                       *add_statusline_func*
+-------------------------------------                  *add_statusline_func*
 The following is an example of how you can extend vim-airline to support a
 new plugin. >
   function! MyPlugin(...)
@@ -311,7 +311,7 @@ new plugin. >
   endfunction
   call airline#add_statusline_func('MyPlugin')
 <
-                                                    *remove_statusline_func*
+-------------------------------------               *remove_statusline_func*
 You can also remove a function as well, which is useful for when you want a
 temporary override. >
   call airline#remove_statusline_func('MyPlugin')
@@ -352,7 +352,7 @@ values such as whether the statusline is active or not, and the window number.
     'active': 'whether the window is active or not',
   }
 <
-                                             *airline-pipeline-return-codes*
+-------------------------------------        *airline-pipeline-return-codes*
 The pipeline accepts various return codes and can be used to determine the
 next action.  The following are the supported codes: >
    0   the default, continue on with the next funcref