runtime: Include vim-tutor-mode

vim-tutor-mode provides a mechanism to write and read interactive
tutorials in vim. It's aim is to replace the venerable vimtutor with a
more modern system.

The plugin's development is maintained at https://github.com/fmoralesc
/vim-tutor-mode

Closes #2351.

1 files changed, 259 insertions, 0 deletions

diff --git a/runtime/tutor/tutor.tutor b/runtime/tutor/tutor.tutor
new file mode 100644
index 0000000000..852c1ea74a
--- /dev/null
+++ b/runtime/tutor/tutor.tutor
@@ -0,0 +1,259 @@
+# CREATING A VIM TUTORIAL WITH VIM-TUTOR-MODE
+
+This tutorial will guide you through the steps required to create a tutorial
+file for vim-tutor-mode. It is also meant as a demo of vim-tutor-mode
+capabilities.
+
+Table of contents:
+
+- [Setting up](*setting-up*)
+- [vim-tutor-mode's markup](*markup*)
+    - [emphasis](*emphasis*)
+    - [headers](*headers*)
+    - [links](*links*)
+    - [codeblocks](*codeblocks*)
+- [Interactive elements](*interactive*)
+    - [expect](*expect*)
+
+## SETTING UP *setting-up*
+
+First, you'll need to enable "debug" mode
+~~~ cmd
+    :let g:tutor_debug = 1
+~~~
+This will allow saving changes to the tutor files and will disable conceals, so
+you can more easily check your changes.
+
+After this, create a new .tutor file (we will be practicing on this very file, so you
+don't need to do this now):
+~~~ cmd
+    :e new-tutorial.tutor
+~~~
+
+## VIM-TUTOR-MODE's MARKDOWN *markup*
+
+vim-tutor-mode uses a subset of markdown's syntax to format the tutorials. The
+subset supported should be enough for most tutorials and the maintainers will
+try to keep it as small as possible (if regular markdown allows for several
+ways to do the same thing, tutor markdown will only provide the one the
+maintainers think is easier to handle).
+
+### Emphasis *emphasis*
+
+For emphasized text (italics), as in normal markdown, you use \*. E.g.:
+
+    \*text\*
+
+is displayed like
+
+    *text*
+
+Note: The underscores variant is not supported.
+
+For strong emphasis (bold), you use \*\*. E.g.:
+
+    \*\*this\*\*
+
+is displayed like
+
+    **this**
+
+1. Format the line below so it becomes a lesson description:
+
+---> This is text with importat information {expect:This is text with **important information**}
+---> This is text with **important information** {expect:This is text with **important information**}
+
+Note: Some words (e.g., NOTE, IMPORTANT, tip, ATTENTION, etc.) will also be
+highlighted. You don't need to mark them specially.
+
+2. Turn the line below into a TODO item:
+
+---> Document '&variable' {expect:TODO: Document '&variable'}
+---> TODO: Document '&variable' {expect:TODO: Document '&variable'}
+
+### Headers *headers*
+
+3. Practice fixing the lines below:
+
+---> This is a level 1 header {expect:# This is a level 1 header}
+---> # This is a level 1 header {expect:# This is a level 1 header}
+---> This is a level 3 header {expect:### This is a level 3 header}
+---> ### This is a level 3 header {expect:### This is a level 3 header}
+---> This is a header with a label {expect:# This is a header with a label {*label*}}
+---> # This is a header with a label {*label*} {expect:# This is a header with a label {*label*}}
+
+4. Now, create a 4th level section here, and add a label like in the previous
+exercise:
+
+
+
+   ATTENTION We will use this label later, so remember it.
+
+### Links *links*
+
+It is good practice to include links in your tutorials to reference materials,
+like vim's own help or external documents. You can also link to other parts of
+the document.
+
+Links have the syntax
+
+    \[label\]\(target\)
+
+#### Help links
+
+If the target of a link matches a help topic, opening it will open it.
+
+5. Fix the following line:
+
+---> A link to help for the 'breakindent' option {expect:A link to help for the ['breakindent']('breakindent') option}
+---> A link to help for the ['breakindent']('breakindent') option {expect:A link to help for the ['breakindent']('breakindent') option}
+
+#### Anchor links
+
+A link can also lead to a place in the file itself. Anchors are written
+
+    \*anchor\*
+
+and are hidden by default. Links to them look like
+
+    \[label\]\(\*anchor\*\)
+
+6. Add the appropiate link:
+
+---> A link to the Links section {expect:A link to the [Links](*links*) section}
+---> A link to the [Links](*links*) section {expect:A link to the [Links](*links*) section}
+
+7. Now, create a link to the section you created on exercise 4
+   above.
+
+
+
+# Tutorial links
+
+You can also have links to other tutorials. For this, you'll write the wnchor in the format
+
+    @tutor:TUTORIAL
+
+7. Create a link to this tutorial:
+
+---> A link to the vim-tutor-mode tutorial {expect:A link to [the vim-tutor-mode tutorial](@tutor:tutor)}
+---> A link to [the vim-tutor-mode tutorial](@tutor:tutor) {expect:A link to [the vim-tutor-mode tutorial](@tutor:tutor)}
+
+### Codeblocks *codeblocks*
+
+vim-tutor-mode tutorials can include viml sections
+
+    ~~~ cmd
+    echom "hello"
+    ~~~
+
+is displayed as
+~~~ cmd
+echom "hello"
+~~~
+
+8. Copy the viml section below
+
+--->  {expect:~~~ viml}
+--->  {expect:echom "the value of &number is".string(&number)}
+--->  {expect:~~~}
+
+---> ~~~ viml {expect:~~~ viml}
+---> echom "the value of &number is".string(&number) {expect:echom "the value of &number is".string(&number)}
+---> ~~~ {expect:~~~}
+
+You can inline viml code using "\`" and "\`{vim}":
+
+    \`call myFunction()\`{vim}
+
+is displayed as
+
+    `call myFunction()`{vim}
+
+[normal](Normal-mode) commands can also be embedded in tutorials.
+
+    ~~~ normal
+    ftdaW
+    ~~~
+
+is displayed as
+~~~ normal
+ftdaW
+~~~
+
+Note: you can also write `norm` or `normal`.
+
+9. Copy the normal section below
+
+--->  {expect:~~~ normal}
+--->  {expect:d2w}
+--->  {expect:~~~}
+
+---> ~~~ normal {expect:~~~ normal}
+---> d2w {expect:d2w}
+---> ~~~ {expect:~~~}
+
+You can also inline normal commands by using "\`" and "\`{normal}":
+
+    \`gq\`{normal} is very useful.
+
+is displayed:
+
+    `gq`{normal} is very useful.
+
+10. Complete the line as shown
+
+---> d {expect:«d2w»}
+---> «d2w» {expect:«d2w»}
+
+Commands to run in the system shell can be highlighted by indenting a line starting with "$".
+
+~~~ sh
+    $ vim --version
+~~~
+
+## INTERACTIVE ELEMENTS *interactive*
+
+As visible in this very document, vim-tutor-mode includes some interactive
+elements, to provide feedback to the user about his progress. These elements
+all have the syntax
+
+    \---> TEXT {CLAUSE}
+
+where \---> must start at the beginning of the line. If TEXT satisfies CLAUSE,
+a ✓ sign will appear to the left. A ✗ sign is displayed otherwise. The CLAUSE
+itself is hidden unless debug mode is set or ['conceallevel']('conceallevel')
+is 2.
+
+### expect *expect*
+
+The basic clause is "expect", which is satisfied if TEXT is the same as the
+content of the clause. For example
+
+    \---> TEXT {expect:TEXT}
+
+is satisfied, but
+
+    \---> OTHER TEXT {expect:TEXT}
+
+is not.
+
+13. Make both lines the same:
+
+---> this is not right {expect:---> this is right} |expect:---> this is right {expect:---> this is right}|
+---> ---> this is right {expect:---> this is right} |expect:---> this is right {expect:---> this is right}|
+
+
+If the content of a expect clause is ANYTHING, no checks will be performed. This is
+useful to create a line that is highlighted you want the user to play with.
+
+    \---> TEXT {expect:ANYTHING}
+
+is displayed
+
+---> this is free text {expect:ANYTHING}
+
+14. Turn the line below into free text:
+
+---> this is some text |expect:---> this is some text {expect:ANYTHING}|
+---> ---> this is some text {expect:ANYTHING} |expect:---> this is some text {expect:ANYTHING}|