Added test script(s), updated documentation

.gitignore

@@ -1,2 +1,4 @@
 *~
 *swp
+test/current_doc.adoc
+test/current_script.vim

README.adoc

@@ -19,6 +19,8 @@ and aims to be extremely lightweight.
 
 == Install
 
+VViki is in the standard Vim plugin structure. Any plugin installation method (incuding popular plugin managers) should work. If you have additional installation instructions to add here, I'll gladly add them:
+
 === Vundle
 
 Add this to your plugin list (in your `.vimrc` file):
@@ -34,25 +36,25 @@ Then run `:source %` and `:BundleInstall`.
 Add something like this to your `~/.vimrc` file (or equivalent):
 
 ----
-" VViki setup
+" VViki setup - relies on the default wiki root dir (~/wiki)
 nnoremap <leader>ww :e ~/wiki/index.adoc<cr>
 ----
 
 The above mapping will open a page called `index` when you type '<leader>ww'. (Vim's default leader key is '\'. If you've not changed it, you'd type type '\ww'.)  Users coming from VimWiki will be familiar with this mapping.
 
-By default, VViki uses `~/wiki` as the wiki "root" directory and looks for pages having an `.adoc` extension.  Any file under this directory (or subdirectory) ending in .adoc will be detected as a wiki page.
-
 Note: VViki does not currently create directories, so you'll need to create `~/wiki` if it does not already exist.
 
 == Advanced Setup
 
+By default, VViki uses `~/wiki` as the wiki "root" directory and looks for pages having an `.adoc` extension.  Any file under this directory (or subdirectory) ending in .adoc will be detected as a wiki page.
+
 Here's a setup example which changes the root directory and extension:
 
 ----
 " VViki setup
 let g:vviki_root = "~/secret_diary"
 let g:vviki_ext  = ".txt"
-nnoremap <leader>ww :e ~/wiki/index.txt<cr>
+nnoremap <leader>ww :e ~/secret_diary/index.txt<cr>
 ----
 
 See `:help vviki` for complete documentation and specifically `:help vviki-configuration` for all settings.
@@ -75,6 +77,21 @@ This table explains the difference:
 |===
 
 
+== Testing
+
+Running the interactive test script is an easy way to try out VViki's basic functionality without setting up or installing anything. VViki does not even need to be installed as a plugin!
+
+To go from nothing to trying out and testing a wiki, try this:
+
+----
+git clone https://github.com/ratfactor/vviki
+cd vviki
+vim -S test/test.vim
+----
+
+The first test document should open immediately. It contains instructions for using the tests (shortcut keys are mapped for fast/easy usage). All tests are self-documented.
+
+
 == TODO
 
 * [x] Absolute vs relative internal links

doc/vviki.txt

@@ -25,7 +25,8 @@
      g:vviki_visual_link_creation |vviki_visual_link_creation|
      g:vviki_links_include_ext    |vviki_links_include_ext|
 5. Version History   |vviki-versions|
-6. License           |vviki-license|
+6. Testing           |vviki-testing|
+7. License           |vviki-license|
 
 
 ==============================================================================
@@ -365,6 +366,12 @@ This option is off by default. Turn it on like so:
 ==============================================================================
 5. Version History                                            *vviki-versions*
 
+1.1.0 December 2020
+ * Added new link sytanx style options
+ * Added multi-word link from visual selection option
+ * Added file extension in link option
+ * Added interactive test script system
+
 1.0.0 June 2020
  * Added Tab mapping (jump cursor to next link)
  * Added default 'index' page for directory links
@@ -377,8 +384,31 @@ Pre-1.0 development starting in late 2019
  * Link macro syntax concealing added
  * Help documentation added
 
+
+==============================================================================
+6. Testing                                                      *vviki-testng*
+
+The VViki project contains a test script at test/test.vim. The script sets up
+test wiki pages with particular settings to be interactively tested.
+
+Running the test script is an easy way to try out VViki's basic functionality
+without setting up or installing anything (VViki does not even need to be
+installed as a plugin!)
+
+To start the test system, enter the VViki project directory and run the
+script:
+>
+    cd ~/coolstuff/vviki
+    vim -S test/test.vim
+<
+
+The first test document should open immediately. It contains instructions for
+using the tests (shortcut keys are mapped for fast/easy usage). All tests are
+self-documented.
+
+
 ==============================================================================
-6. License                                                     *vviki-license*
+7. License                                                     *vviki-license*
 
 MIT License
 

test/current_doc.vim

@@ -0,0 +1,23 @@
+
+= VViki Testing 1
+
+Welcome to the first test document for VViki. The current filename should be
+`test/current_doc.adoc` and it has been created by the test script.
+
+Another script (`test/current_script.vim`) has already run, setting the wiki
+test environment for this particular test. In this case, we're just going with
+the defaults, so there's not much going on in the setup:
+
+----
+Test Script Start
+echo "Hello! Test 1 uses defaults, so there's nothing to set."
+Test Script End
+----
+
+== Test basic linking
+
+Make sure this link looks like `Foo` with cursor off and `link:foo[Foo]` with
+cursor over it. Hitting Enter should take you to the Foo page!
+
+link:foo[Foo]
+

test/foo.adoc

@@ -0,0 +1,14 @@
+= Foo
+
+Welcome to Foo! The link worked!
+
+You can use `Backspace` to return (or press `F5` to reload the test).
+
+== Linking back
+
+One of the following three links should work to get you back:
+
+link  - link:current_doc[Current Test Doc]
+olink - olink:current_doc[Current Test Doc]
+xref  - <<current_doc#,Current Test Doc>>
+

test/test.vim

@@ -0,0 +1,83 @@
+" Testing is manual for now, but aided by this simple script. Run like so:
+"
+"   1. Be in VViki project dir (e.g. cd ~/coolstuff/vviki/)
+"   2. Run this script to start testing (vim -S test/test.vim)
+"   3. Follow the instructions
+"
+" Note that this test script may mess up your current session. It can't
+" be bargained with. It can't be reasoned with. It doesn't feel pity, or
+" remorse, or fear.
+"
+
+nnoremap <f5> :call LoadTest()<cr>
+nnoremap <right> :call NextTest()<cr>
+nnoremap <left> :call PrevTest()<cr>
+
+function! ReloadPlugin()
+    " Reload plugin and reset settings to defaults
+    unlet! g:loaded_vviki
+    unlet! g:vviki_index
+	unlet! g:vviki_ext
+    unlet! g:vviki_conceal_links
+    unlet! g:vviki_page_link_syntax
+    unlet! g:vviki_visual_link_creation
+    unlet! g:vviki_links_include_ext
+    " Set wiki root directory for tests (relative to current dir)
+    let g:vviki_root = getcwd()."/test"
+
+    source plugin/vviki.vim
+endfunction
+
+function! LoadTest()
+    call ReloadPlugin()
+
+    let src_doc = expand("test/test_".s:current_test_num.".adoc")
+    let test_script = expand("test/current_script.vim")
+    let test_doc = expand("test/current_doc.adoc")
+
+    if !filereadable(src_doc)
+        echo "Test ".src_doc." not found. Perhaps we are all done?"
+        return
+    endif
+
+    " Let's make a new script to execute for the current test
+    silent execute "edit ".test_script
+    " Clear file
+    silent %delete
+    " Read current script
+    silent execute "read ".src_doc
+    " Delete everything except the test script in the file
+    silent execute "normal! /Test Script Start\<cr>"
+    silent 0,delete
+    silent execute "normal! /Test Script End\<cr>"
+    silent ,$delete
+    silent write
+    silent source %
+
+    " Let's make a new document to view for the current test
+    silent execute "edit ".test_doc
+    silent %delete
+    silent execute "read ".src_doc
+    silent write
+
+    " Because the autocommands will not fire because we're re-using
+    " the current test doc filename, we need to call the setup function
+    " manually. Should be identical to opening a new file.
+    call VVSetup()
+
+    echo "Test ".s:current_test_num." loaded."
+endfunction
+
+function! NextTest()
+    let s:current_test_num += 1
+    call LoadTest()
+endfunction
+
+function! PrevTest()
+    let s:current_test_num -= 1
+    call LoadTest()
+endfunction
+
+" Create buffers in a split to display messages and wiki test pages.
+let s:current_test_num = 1
+call LoadTest()

test/test_1.adoc

@@ -0,0 +1,32 @@
+= Test 1 - Instructions and basic links
+
+Welcome to the first test document.
+
+== Test basic linking
+
+Make sure this link looks like `Foo` and `link:foo[Foo]` depending on whether
+or not your cursor is on the line. Enter should take you to the Foo page.
+
+link:foo[Foo]  <-- Test this link.
+
+
+== Test script
+
+Every test document also has a script which sets up the environment for that
+particular test. In this case, we're just going with the defaults, so there's
+not much going on in this one:
+
+----
+Test Script Start
+echo "Hello! This test uses defaults, so there's nothing to do here."
+Test Script End
+----
+
+
+== Test controls
+
+To navigate, use the following keyboard shortcuts:
+
+`F5`     Reloads the test (very useful for debugging)
+`Right`  Load the next test
+`Left`   Load the previous test

test/test_2.adoc

@@ -0,0 +1,14 @@
+= Test 2 - xref link syntax
+
+This link should have syntax concealed when the cursor is off the line and it
+should correctly link to the Foo page:
+
+<<foo#,Foo>>  <-- Test this link and note the syntax.
+
+----
+Test Script Start
+let g:vviki_page_link_syntax = 'xref_hack'
+Test Script End
+----
+
+

test/test_3.adoc

@@ -0,0 +1,11 @@
+= Test 3 - olink syntax
+
+olink:foo[Foo]  <-- Test this link and note the `olink` syntax.
+
+----
+Test Script Start
+let g:vviki_page_link_syntax = 'olink'
+Test Script End
+----
+
+

test/test_4.adoc

@@ -0,0 +1,13 @@
+= Test 4 - Visual link creation
+
+Use a visual selection (e.g. `vee`) to highlight the words "foo bar" below
+and then hit Enter to create a multi-word link. Hit Enter again to navigate
+to the link. It should attempt to open a file named "foo bar.adoc".
+
+Link to foo bar should work.  <-- Create `foo bar` link here.
+
+----
+Test Script Start
+let g:vviki_visual_link_creation = 1
+Test Script End
+----

test/test_5.adoc

@@ -0,0 +1,13 @@
+= Test 5 - Links include the filename extension
+
+With this option turned on, the link will include the ".adoc" file extension.
+Create a link by hitting Enter on the word "foo". It should create a link to
+`foo.adoc`. Follow the link to make sure it goes to the file.
+
+foo  <-- Create `foo.adoc` link here and test it.
+
+----
+Test Script Start
+let g:vviki_links_include_ext = 1
+Test Script End
+----

test/test_6.adoc

@@ -0,0 +1,19 @@
+= Test 6 - Link-a-palooza (all three link options altered)
+
+Make sure combos of link options work.
+
+Use a visual selection (e.g. `vee`) to highlight the words "foo bar" below
+and then hit Enter to create a multi-word link. Hit Enter again to navigate
+to the link. It should attempt to open a file named "foo bar.adoc".
+
+Link to foo bar should work.  <-- Create `foo bar` link here.
+
+The created link should look like this: `<<foo bar.adoc#,foo bar>>`
+
+----
+Test Script Start
+let g:vviki_page_link_syntax = 'xref_hack'
+let g:vviki_visual_link_creation = 1
+let g:vviki_links_include_ext = 1
+Test Script End
+----