# 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 important 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 anchor 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}|