Document text folding of headers (issue #106)

NB: I've decided to start including screen shots in version
control because there isn't a better place to keep them...

Author: xolox

README.md

@@ -15,11 +15,12 @@ The vim-notes plug-in for the [Vim text editor] [vim] makes it easy to manage yo
    * **Back-references:** The `:RelatedNotes` command find all notes referencing the current file
    * A [Python 2] [python] script is included that accelerates keyword searches using a keyword index
    * The `:RecentNotes` command lists your notes by modification date, starting with the most recently edited note
+ * **Navigating within notes:** The vim-notes syntax uses atx-style headers just like [Markdown] [markdown] (one to six `#` marks at the start of the line) and supports text folding based on these headers. This allows easy navigation within notes that contain large (and possibly nested) sections of text separated by headers. [Here's a screen shot of text folding] [folding].
  * **Navigating between notes:** The included syntax script highlights note names as hyper links and the file type plug-in redefines [gf] [gf] to jump between notes (the [Control-w f] [ctrlwf] mapping to jump to a note in a split window and the [Control-w gf] [ctrlwgf] mapping to jump to a note in a new tab page also work)
  * **Writing aids:** The included file type plug-in contains mappings for automatic curly quotes, arrows and list bullets and supports completion of note titles using Control-X Control-U and completion of tags using Control-X Control-O
  * **Embedded file types:** The included syntax script supports embedded highlighting using blocks marked with `{{{type … }}}` (triple back ticks ala [GFM] [gfm] are also supported) which allows you to embed highlighted code and configuration snippets in your notes
 
-Here's a screen shot of the syntax mode using the [Slate] [slate] color scheme and the font [Monaco] [monaco]:
+Here's a screen shot of the syntax mode (using the [Slate] [slate] color scheme and the [Monaco] [monaco] font):
 
 ![Syntax mode screen shot](http://peterodding.com/code/vim/notes/syntax.png)
 
@@ -365,6 +366,7 @@ This software is licensed under the [MIT license] [mit].
 [download-notes]: http://peterodding.com/code/vim/downloads/notes.zip
 [edit]: http://vimdoc.sourceforge.net/htmldoc/editing.html#:edit
 [enc]: http://vimdoc.sourceforge.net/htmldoc/options.html#'encoding'
+[folding]: https://raw.githubusercontent.com/xolox/vim-notes/master/screenshots/folding.png
 [geshi]: http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi
 [gf]: http://vimdoc.sourceforge.net/htmldoc/editing.html#gf
 [gfm]: https://help.github.com/articles/github-flavored-markdown/

doc/notes.txt

@@ -106,6 +106,12 @@ notes in Vim:
 - The |:RecentNotes| command lists your notes by modification date, starting
   with the most recently edited note
 
+- **Navigating within notes:** The vim-notes syntax uses atx-style headers
+  just like Markdown [3] (one to six '#' marks at the start of the line) and
+  supports text folding based on these headers. This allows easy navigation
+  within notes that contain large (and possibly nested) sections of text
+  separated by headers. Here's a screen shot of text folding [4].
+
 - **Navigating between notes:** The included syntax script highlights note
   names as hyper links and the file type plug-in redefines |gf| to jump
   between notes (the Control-w f (see |CTRL-W_f|) mapping to jump to a note
@@ -119,13 +125,13 @@ notes in Vim:
 
 - **Embedded file types:** The included syntax script supports embedded
   highlighting using blocks marked with '{{{type … }}}' (triple back ticks
-  ala GFM [3] are also supported) which allows you to embed highlighted code
+  ala GFM [5] are also supported) which allows you to embed highlighted code
   and configuration snippets in your notes
 
-Here's a screen shot of the syntax mode using the Slate [4] color scheme and
-the font Monaco [5]:
+Here's a screen shot of the syntax mode (using the Slate [6] color scheme and
+the Monaco [7] font):
 
-  Image: Syntax mode screen shot (see reference [6])
+  Image: Syntax mode screen shot (see reference [8])
 
 ===============================================================================
                                                           *notes-install-usage*
@@ -134,16 +140,16 @@ Install & usage ~
 _Please note that the vim-notes plug-in requires my vim-misc plug-in which is
 separately distributed._
 
-Unzip the most recent ZIP archives of the vim-notes [7] and vim-misc [8] plug-
+Unzip the most recent ZIP archives of the vim-notes [9] and vim-misc [10] plug-
 ins inside your Vim profile directory (usually this is '~/.vim' on UNIX and
 '%USERPROFILE%\vimfiles' on Windows), restart Vim and execute the command
 ':helptags ~/.vim/doc' (use ':helptags ~\vimfiles\doc' instead on Windows). To
 get started execute |:Note| or ':edit note:', this will start a new note that
 contains instructions on how to continue from there (and how to use the plug-in
 in general).
 
-If you prefer you can also use Pathogen [9], Vundle [10] or a similar tool to
-install & update the vim-notes [11] and vim-misc [12] plug-ins using a local
+If you prefer you can also use Pathogen [11], Vundle [12] or a similar tool to
+install & update the vim-notes [13] and vim-misc [14] plug-ins using a local
 clone of the git repository.
 
 ===============================================================================
@@ -170,7 +176,7 @@ circumstances but should work for most people:
 
 - If the profile directory where the plug-in is installed is writable, the
   directory 'misc/notes/user' under the profile directory is used. This is
-  for compatibility with Pathogen [9]; the notes will be stored inside the
+  for compatibility with Pathogen [11]; the notes will be stored inside the
   plug-in's bundle.
 
 - If the above doesn't work out, the default depends on the platform:
@@ -327,7 +333,7 @@ recreate it manually by executing |:IndexTaggedNotes| (see below).
 -------------------------------------------------------------------------------
 The *g:notes_markdown_program* option
 
-The |:NoteToHtml| command requires the Markdown [13] program. By default the
+The |:NoteToHtml| command requires the Markdown [3] program. By default the
 name of this program is assumed to be simply 'markdown'. If you want to use a
 different program for Markdown to HTML conversion, set this option to the name
 of the program.
@@ -516,7 +522,7 @@ If for any reason you want to recreate the list of tags you can execute the
 The *:NoteToHtml* command
 
 This command converts the current note to HTML. It works by first converting
-the current note to Markdown [13] and then using the 'markdown' program to
+the current note to Markdown [3] and then using the 'markdown' program to
 convert that to HTML. It requires an external program to convert Markdown to
 HTML. By default the program 'markdown' is used, but you can change the name of
 the program using the |g:notes_markdown_program| option. To convert your note
@@ -536,7 +542,7 @@ optimized for speed (yet).
 -------------------------------------------------------------------------------
 The *:NoteToMarkdown* command
 
-Convert the current note to a Markdown document [13]. The vim-notes syntax
+Convert the current note to a Markdown document [3]. The vim-notes syntax
 shares a lot of similarities with the Markdown text format, but there are some
 notable differences, which this command takes care of:
 
@@ -557,7 +563,7 @@ optimized for speed (yet).
 -------------------------------------------------------------------------------
 The *:NoteToMediawiki* command
 
-Convert the current note to a Mediawiki document [14]. This is similar to the
+Convert the current note to a Mediawiki document [15]. This is similar to the
 |:NoteToMarkdown| command, but it produces wiki text that can be displayed on a
 Mediawiki site. That being said, the subset of wiki markup that vim-notes
 actually produces will probably work on other wiki sites. These are the notable
@@ -570,7 +576,7 @@ transforations:
 
 - Preformatted blocks are output into '<syntaxhighlight lang="..">' tags.
   This functionality is enabled on Mediawiki through the SyntaxHighlight
-  GeSHi extention [15]. It is also supported on Wikipedia.
+  GeSHi extention [16]. It is also supported on Wikipedia.
 
 ===============================================================================
                                                                *notes-mappings*
@@ -659,14 +665,14 @@ Other plug-ins that work well with the notes plug-in ~
                                                                 *notes-utl.vim*
 utl.vim ~
 
-The utl.vim [16] universal text linking plug-in enables links between your
+The utl.vim [17] universal text linking plug-in enables links between your
 notes, other local files and remote resources like web pages.
 
 -------------------------------------------------------------------------------
                                                               *notes-shell.vim*
 shell.vim ~
 
-My shell.vim [17] plug-in also enables easy navigation between your notes and
+My shell.vim [18] plug-in also enables easy navigation between your notes and
 environment like local files and directories, web pages and e-mail addresses by
 providing key mappings and commands to e.g. open the file/URL under the text
 cursor. This plug-in can also change Vim to full screen which can be really
@@ -676,7 +682,7 @@ nice for large notes.
                                                                    *notes-voom*
 VOoM ~
 
-The VOoM [18] outlining plug-in should work well for notes if you use the
+The VOoM [19] outlining plug-in should work well for notes if you use the
 Markdown style headers starting with '#', however it has been reported that
 this combination may not always work so well in practice (sometimes losing
 notes!)
@@ -686,7 +692,7 @@ notes!)
 Txtfmt ~
 
 If the text formatting supported by the notes plug-in is not enough for you,
-consider trying the Txtfmt [19] (The Vim Highlighter) plug-in. To use the two
+consider trying the Txtfmt [20] (The Vim Highlighter) plug-in. To use the two
 plug-ins together, create the file 'after/ftplugin/notes.vim' inside your Vim
 profile with the following contents:
 >
@@ -702,7 +708,7 @@ absolute pathnames that most certainly won't match between e.g. Windows and
 Linux or even Windows and Cygwin. The best you can do is keep separate session
 scripts for different platforms (and I would certainly consider Cygwin a
 separate platform altogether :-). For more information please refer to issue
-#85 [20].
+#85 [21].
 
 ===============================================================================
                                                                 *notes-contact*
@@ -711,13 +717,13 @@ Contact ~
 If you have questions, bug reports, suggestions, etc. the author can be
 contacted at [email protected]. The latest version is available at
 http://peterodding.com/code/vim/notes/ and http://github.com/xolox/vim-notes.
-If you like the script please vote for it on Vim Online [21].
+If you like the script please vote for it on Vim Online [22].
 
 ===============================================================================
                                                                 *notes-license*
 License ~
 
-This software is licensed under the MIT license [22]. © 2015 Peter Odding
+This software is licensed under the MIT license [23]. © 2015 Peter Odding
 <[email protected]>.
 
 ===============================================================================
@@ -726,25 +732,26 @@ References ~
 
 [1] http://en.wikipedia.org/wiki/Levenshtein_distance
 [2] http://python.org/
-[3] https://help.github.com/articles/github-flavored-markdown/
-[4] http://code.google.com/p/vim/source/browse/runtime/colors/slate.vim
-[5] http://en.wikipedia.org/wiki/Monaco_(typeface)
-[6] http://peterodding.com/code/vim/notes/syntax.png
-[7] http://peterodding.com/code/vim/downloads/notes.zip
-[8] http://peterodding.com/code/vim/downloads/misc.zip
-[9] http://www.vim.org/scripts/script.php?script_id=2332
-[10] https://github.com/gmarik/vundle
-[11] http://github.com/xolox/vim-notes
-[12] http://github.com/xolox/vim-misc
-[13] http://en.wikipedia.org/wiki/Markdown
-[14] https://www.mediawiki.org/wiki/MediaWiki
-[15] http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi
-[16] http://www.vim.org/scripts/script.php?script_id=293
-[17] http://www.vim.org/scripts/script.php?script_id=3123
-[18] http://www.vim.org/scripts/script.php?script_id=2657
-[19] http://www.vim.org/scripts/script.php?script_id=2208
-[20] https://github.com/xolox/vim-session/issues/85
-[21] http://www.vim.org/scripts/script.php?script_id=3375
-[22] http://en.wikipedia.org/wiki/MIT_License
+[3] http://en.wikipedia.org/wiki/Markdown
+[4] https://raw.githubusercontent.com/xolox/vim-notes/master/screenshots/folding.png
+[5] https://help.github.com/articles/github-flavored-markdown/
+[6] http://code.google.com/p/vim/source/browse/runtime/colors/slate.vim
+[7] http://en.wikipedia.org/wiki/Monaco_(typeface)
+[8] http://peterodding.com/code/vim/notes/syntax.png
+[9] http://peterodding.com/code/vim/downloads/notes.zip
+[10] http://peterodding.com/code/vim/downloads/misc.zip
+[11] http://www.vim.org/scripts/script.php?script_id=2332
+[12] https://github.com/gmarik/vundle
+[13] http://github.com/xolox/vim-notes
+[14] http://github.com/xolox/vim-misc
+[15] https://www.mediawiki.org/wiki/MediaWiki
+[16] http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi
+[17] http://www.vim.org/scripts/script.php?script_id=293
+[18] http://www.vim.org/scripts/script.php?script_id=3123
+[19] http://www.vim.org/scripts/script.php?script_id=2657
+[20] http://www.vim.org/scripts/script.php?script_id=2208
+[21] https://github.com/xolox/vim-session/issues/85
+[22] http://www.vim.org/scripts/script.php?script_id=3375
+[23] http://en.wikipedia.org/wiki/MIT_License
 
 vim: ft=help