From 8ec1cccb36f0054a613c94005a535f3b376abe31 Mon Sep 17 00:00:00 2001 From: Rane Brown Date: Mon, 15 Jul 2019 07:28:12 -0600 Subject: [PATCH] Update documentation for intro and folding sections. Originals modifications from PR #694. --- doc/vimwiki.txt | 83 +++++++++++++++++++++++++++++++++++++------------ 1 file changed, 63 insertions(+), 20 deletions(-) diff --git a/doc/vimwiki.txt b/doc/vimwiki.txt index 7416d4c..9fbe562 100644 --- a/doc/vimwiki.txt +++ b/doc/vimwiki.txt @@ -57,40 +57,53 @@ CONTENTS *vimwiki* ============================================================================== 1. Intro *vimwiki-intro* -Vimwiki is a personal wiki for Vim -- a number of linked text files that have -their own syntax highlighting. +Vimwiki makes it very easy for you create a personal wiki using the Vim text +editor. A wiki is a collection of text documents linked together and formatted +with wiki or markdown syntax that can be highlighted for readability using +Vim's syntax highlighting feature. With Vimwiki you can: - organize notes and ideas - manage todo-lists - write documentation - maintain a diary - - export everything to HTML + - export your documents to HTML -To do a quick start press ww (this is usually \ww) to go to your index -wiki file. By default it is located in ~/vimwiki/index.wiki +Getting started with Vimwiki is easy. Once intalled, simply type `vim` into +your terminal to launch Vim and then type ww (the key is `\` +by default) to create or open the index wiki file, the "top" page in your +hierarchical collection of wiki pages. By default, this page will be located +at ~/vimwiki/index.wiki. -Feed it with the following example: +Now add the following example lines to the document: = My knowledge base = * Tasks -- things to be done _yesterday_!!! * Project Gutenberg -- good books are power. * Scratchpad -- various temporary stuff. -Place your cursor on 'Tasks' and press Enter to create a link. Once pressed, -'Tasks' will become '[[Tasks]]' -- a Vimwiki link. Press Enter again to -open it. Edit the file, save it, and then press Backspace to jump back to -your index. +Next, move your cursor to the word 'Tasks' and press `Enter`. This will create +a Vimwiki link by surrounding 'Tasks' with double square brackets: +'[[Tasks]]'. Pressing `Enter` a second time will generate a new blank buffer +in Vim where you can input your tasks. After you add some tasks and save the +new file, you can hit `Backspace` to jump back to the index document. -A Vimwiki link can be constructed from more than one word. Just visually -select the words to be linked and press Enter. Try it with 'Project -Gutenberg'. The result should look something like: +A Vimwiki link can contain multiple words by entering Vim's "visual" mode (the +"v" key, by default) and selecting the words to be linked. Once selected, +press `Enter`. + +Try this now by selecting 'Project Gutenberg' in visual mode and hitting +`Enter`. The sample text should now look something like this: = My knowledge base = * [[Tasks]] -- things to be done _yesterday_!!! * [[Project Gutenberg]] -- good books are power. * Scratchpad -- various temporary stuff. +By continuing this way and creating sub pages with links to even more sub +pages, you can create an unlimited number of neatly structured, interconnected +documents to help you organize your notes, documenation, and tasks. + ============================================================================== 2. Prerequisites *vimwiki-prerequisites* @@ -1499,11 +1512,15 @@ Tags-related commands and options: ============================================================================== 6. Folding/Outline *vimwiki-folding* -Vimwiki can fold or outline sections using headers and preformatted blocks. -Alternatively, one can fold list subitems instead. Folding is not enabled -by default, and requires the |g:vimwiki_folding| variable to be set. +Vimwiki allows you to use Vim's folding methods and options so you can fold +your outline to make it less distracting and easier to navigate. You can use +Vimwiki's built-in folding methods or supply custom methods for folding. You +control how folds behave with by setting the |g:vimwiki_folding| variable to +the desired value in your configuration file: > -Example for list folding with |g:vimwiki_folding| set to 'list': + let g:vimwiki_folding = 'value' + +Here's an example of how folds work with |g:vimwiki_folding| set to 'list': = My current task = * [ ] Do stuff 1 @@ -1545,8 +1562,34 @@ Note: If you use the default Vimwiki syntax, folding on list items will work properly only if all of them are indented using the current 'shiftwidth'. For Markdown and MediaWiki syntax, * or # should be in the first column. -To turn folding on/off check |g:vimwiki_folding|. +For maximum control over folds, set |g:vimwiki_folding| to 'custom' so you can +allow other plugins or your vim configuration file to control how folding is +performed. For example, let's say you are using markdown syntax and prefer to +fold so that the last blank line before a header is not folded, you can add +this function to your configuration file: > + function! VimwikiFoldLevelCustom(lnum) + let pounds = strlen(matchstr(getline(a:lnum), '^#\+')) + if (pounds) + return '>' . pounds " start a fold level + endif + if getline(a:lnum) =~? '\v^\s*$' + if (strlen(matchstr(getline(a:lnum + 1), '^#\+'))) + return '-1' " don't fold last blank line before header + endif + endif + return '=' " return previous fold level + endfunction + +Note that you will also need to add the following vim options to your configuration: > + + augroup VimrcAuGroup + autocmd! + autocmd FileType vimwiki setlocal foldmethod=expr | + \ setlocal foldenable | set foldexpr=VimwikiFoldLevelCustom(v:lnum) + augroup END + +See the |g:vimwiki_folding| documentation for more details. ============================================================================== 7. Placeholders *vimwiki-placeholders* @@ -2697,8 +2740,8 @@ Value Description~ 'expr' Folding based on expression (folds sections and code blocks) 'syntax' Folding based on syntax (folds sections; slower than 'expr') 'list' Folding based on expression (folds list subitems; much slower) -'custom' Leave the folding settings as they are (e.g. set by another - plugin) +'custom' Allow folding options to be set by another plugin or a vim + configuration file Default: ''