Kakoune: Add a tutorial like `vimtutor`

Created on 10 Jan 2017 · 25Comments · Source: mawww/kakoune

As mentioned in https://github.com/mawww/kakoune/issues/249

Source

nathanl

👍19 ❤1

Most helpful comment

I don't like the "tutor" thing, the interactivity has always been used as an excuse to copy what vim has, rather than a real tool to help newcomers learn. In my opinion making a user type things and then look at what's happening on the screen isn't a very efficient learning method:

the contents of the tutors are generally rewrites of already existing documentation, which is a great waste of time
the users end up forgetting the keys they used because they didn't have a real use for them, aside from hitting them in order to move forward in the tutorial
users will remember what they read in the tutor when hitting a given key, but if they have a doubt they can't easily go back to the paragraph that explained what the key did
it's more important that users finish the tutor, than the tutor be describing all the options possible at any given time; except all the tutors out there are way to long to be quickly finished, and give a minimal toolset that allows a new user to get started

That's why, a month ago, I started writing a document that I call a _trampoline_. I'm assuming that users who want to learn how to use the editor are actually trying to write a small project, and learn on the fly how to do the things they want. With that in mind, the trampoline describes the basics of editing primitives in the editor in small paragraphs, clearly shows what keys are used in them on the side, and can be refered to easily by keeping it open in a pager on the side. But more importantly, it doesn't try to be exhaustive and explain every single primitive implemented by the editor, as that's the documentation's job.

The second section about advanced primitives is being written, but in the mean time here is my first draft:

+=----------------------------------------------------------------------------=+
              _              _
             | |            | |
             | | __   __ _  | | __   ___    _   _   _ __     ___
             | |/ /  / _` | | |/ /  / _ \  | | | | | '_ \   / _ \
             |   <  | (_| | |   <  | (_) | | |_| | | | | | |  __/
             |_|\_\  \__,_| |_|\_\  \___/   \__,_| |_| |_|  \___|

                  Mawww's experiment for a better code editor
+=----------------------------------------------------------------------------=+

This walkthrough is an introduction to Kakoune's basic edition capabilities to
help new users transition over easily from another editor, or simply learn
how to write and edit documents with style.

In the first section, you will learn about the primitives of the edition
language to be able to get to a level of knowledge of the editor that
guarantees that you can work with it efficiently.

In the second section, for users who've gone through the basics and want
to move on to more advanced functionalities, we explain other primitives
whose role has a less dominant place in an everyday editing session, but
still prove themselves powerful when used on the right occasion.

Finally, as this document is in no way an exhaustive list of features, don't
hesitate to check out the official documentation to compliment your toolset,
ask questions to more seasoned users on IRC, and check the documentation
using the onboard `:doc` command.

+=--------------------------------=+ BASICS +=--------------------------------=+

                    =[ MODES

                    Kakoune uses a paradigm called "modal edition" to allow
       .---,        users to either have every single key they type inserted
       | i |        into the file being edited (called "insert mode"),
       `---'        or execute commands that are triggered by the keys hit
                    (the "command mode").  Aside from arrow keys, most keys
       .---,        described in this document are "edition primitives" that
       |esc|        have to be hit in command mode, which is the default mode
       `---'        when you start the editor. To enter insert mode, hit the
                    `i` key, and to leave it, hit the escape key.


                    =[ MOVEMENT
       .---,
       | ^ |        Movement in a buffer (the representation of the contents
   .---'---'---,    of a file opened by Kakoune) can be achieved using the arrow
   | < | v | > |    keys, which will move the cursor up one column/row into
   `---'---'---`    a given direction.

                    However, furthering the tradition of both mode-based
 .---,---,---,---,  editors, the `h`, `j`, `k` and `l` keys can be used for the
 | h | j | k | l |  same purpose, and will respectively move the cursor to the
 `---'---'---'---`  left, down, up, right by one, when hit. Using those keys
   |   |   |   |    is the recommended way of moving around in a buffer.
 .---,---,---,---,  If you're not familiar with this concept, the proximity
 | < | V | ^ | > |  of those four keys with the rest of the lettered keys
 `---'---'---'---`  on a `qwerty` layout allows faster interaction with the
                    primitives than if the user had to moves their hand to
                    reach the arrow keys.
   .---,
   | g |_.          Another way of moving the cursor is the "goto" utility,
   `---' |`.---,    invoked by hitting the `g` key. A menu will pop up with a
         | | g |    summary of all the possible keys that can be hit, along with
         | `---'    the location where they will move the cursor to, but the
          `.---,    most used ones that we are interested in, for now, are `g`
           | e |    and `e`. The first one will jump to the beginning of the
           `---'    buffer, and the second one to its end.


                    =[ VIEW

   .---,            Displacing the cursor can sometimes move the view into an
   | v |_.          inconvenient configuration, leaving some necessary context
   `---' |`.---,    off screen, or simply feel uncomfortable to type into.
         | | t |    Kakoune provides a menu (similar to the `goto` menu
         | `---'    mentioned in the previous section) that allows users to
         |`.---,    move the current view in relation with the position of the
         | | b |    cursor. Upon hitting the `v` key, a short menu appears
         | `---'    which allows us to hit a second key according to how the
          `.---,    view should be centered: to leave the cursor respectively
           | v |    on top, at the bottom or in the middle of the current view,
           `---'    hit the `t`, `b` or `v` keys.


                    =[ SEARCH

                    In order to move the cursor to a specific word, the search
                    command is the way to go. This functionality allows
        .---,       the user to jump to next occurence of a piece of text.
        | / |       Upon hitting the `/` key, a prompt reading "search"
        `---'       will pop up in the status bar in which you can type
                    your text and validate using the `<ret>` (return) key.
     .---, .---,    You'll notice that as you type, the cursor changes location
     |alt|+| / |    to automatically give you a preview of where the cursor
     `---' `---'    would be displaced to if you validated the search. However,
                    this behaviour is only a preview, exiting prompt mode with
                    the `<esc>` (escape) key will leave the current position
        .---,       of the cursor unchanged. Note that you can also use a
        | n |       Perl regular expression as input.  By default the search
        `---'       function will look for results forward, starting from
                    the current location of the cursor, but you can search
     .---, .---,    backwards using `<a-/>` (alt + `/`).
     |alt|+| n |
     `---' `---'    Jumping from one match to the other forward can be achieved
                    using the `n` key, and backwards using the `<a-n>` (alt +
                    `n`) key combination.


                    =[ SELECTIONS

                    You have certainly noticed that when searching for
        .---,       text, the cursor extends to highlight the entire match.
        | ; |       In fact, what we know in other editors as a "cursor" is
        `---'       actually a single character wide selection in Kakoune,
                    and can be expanded using primitives. When "expanded",
     .---, .---,    the selection is an area whose beginning is the "anchor"
     |alt|+| ; |    and the end the "secondary cursor". To switch anchor and
     `---' `---'    cursor, use `<a-;>`, and to collapse the selection onto
                    its anchor, use `;`.

                    Moreover, not only Kakoune expands the principle of
                    "cursor" by introducing selections, but it also allows
        .---,       multiple selections within the same buffer. This makes
        | % |       it very convenient to modify text in multiple locations
        `---'       at once, as edition primitives apply to all the currently
                    selected text.
        .---,
        | s |       Example: to remove all occurrences of the word "foo", one
        `---'       would select the entire buffer (`%`), select occurrences of
                    the word (`s`, "\<foo\>", `<ret>`), then remove it (`d`).

                    ==[ SELECTING OBJECTS

                    In addition to allowing text selection using regular
     .---, .---,    expressions, certain objects are defined by default to
     |alt|+| i |    allow easy selection of text. Objects are bits of text
     `---' `---'    in the buffer that are identified according to their
                    structure, rather than their contents, e.g. a paragraph,
     .---, .---,    a sentence, or a word. When the cursor is located within
     |alt|+| a |    the boundaries of an object you want to interact with,
     `---' `---'    several options are available: selecting the contents of an
                    object without its boundaries (`<a-i>`), a part of it (from
        .---,       the anchor to its end or to its beginning, respectively `]`
        | ] |       and `[`), or the entire object (`<a-a>`). Those "selection
        `---'       ranges" are the first part of a two stages shortcut,
                    as once you've used the key that dictates what part of
        .---,       the object is to be selected, a menu with a description
        | [ |       of all the object types selectable will be displayed,
        `---'       giving a summary of all the keys you can hit to complete
                    the selection procedure.

                    Example: to select the paragraph in which the anchor lies,
                    invoke the "inner object selection" shortcut (`<a-i>`),
                    locate "paragraph" in the information box that pops up and
    .---,           hit the according key (`p`). The entire two steps sequence
    | [ |_.         is thus: `<a-i> p`.
    `---' |`.---,
          | | ( |   Example: to select everything between the anchor and the
          | `---'   beginning of the current paren pair, use the selection
           `.---,   sequence is: `[ (`. Note that common objects that use
            | r |   pairs of opening/closing punctuation signs (brackets,
            `---'   braces, quotes etc) have an alternative second key that
                    is displayed in the information menu that you can use to
                    minimize finger gymnastics. The previous shortcut could
                    thus also be written: `[ r`.

                    ==[ MOVEMENT SELECTIONS

                    If objects are an easy way to select content-agnostic
    .---,           data in a buffer, they can also be seen as a way to move
    | [ |_.         about the buffer. As selecting objects will displace the
    `---'  `.---,   anchor into a given direction, you can wrap or move around
            | p |   particular chunks of text without using the conventional
            `---'   means (e.g. arrow keys or jumps), turning them partially
                    into movement primitives.
    .---,
    | ] |_.         Example: one of the most used object selection combination
    `---'  `.---,   is the "object end/begin paragraph" one: using `[` or
            | p |   `]` will displace the anchor into a given direction, and
            `---'   applying that to the paragraph object allows "jumping"
                    from one newline separated block of text to another.
                    The resulting shortcut is thus: `] p` to move forward, or
                    `[ p` to move backward.


                    =[ FILTERING A SELECTION

                    Selecting an entire buffer (`%`) or parts of it (`s`) is a
                    natural and basic operation in a typical editing session,
     .---, .---,    however there are some cases where we need to be able to
     |alt|+| k |    drop some selections arbitrarily, as opposed to trying
     `---' `---'    to select the ones we need directly. This concept becomes
                    very useful when coming up with a regular expression for
     .---, .---,    the basic selection primitive (`s`) is too tedious (if
     |alt|+| K |    even possible), that's why the editor provides us with a
     `---' `---'    "keep matching" and a "keep not matching" operations,
                    in order to respectively keep exclusively the selections
                    who match or do not match a given regular expression.

                    Example: when parsing a log file whose lines follow the
                    usual log pattern (e.g. "[1484383442] ERROR: some data"),
                    we want to be able to select all the lines individually
     .---, .---,    (`%`, `<a-s>` to split all the lines), keep those that
     |alt|+| s |    start with a bracketed timestamp (`<a-k>^\[`), but
     `---' `---'    exclude the debug messages (`<a-K>DEBUG`). Of course,
                    it's possible to come up with a regular expression to
                    match those simple requirements, but it would take more
                    work to write it than to organically apply filters on a
                    general selection, individually.


                    =[ SELECTION DUPLICATION

        .---,       Duplicating content can be achieved using a widely
        | y |       implemented concept: yanking and pasting. Copying the
        `---'       current selection into the yank register (`y`) allows the
        .---,       user to subsequently insert the copied text in the buffer
        | p |       (`p`).
        `---'
        .---,       Note that the default "paste" primitive will insert the
        | P |       contents of the yank register after the current selection,
        `---'       if you want copied test to be inserted before the current
                    selection then you can use the `P` key.


                    =[ REPLACING SELECTIONS

                    Text replacement is a two step process in Kakoune, which
                    involves selecting text to be replaced, and then erasing it
        .---,       to insert the replacement text. After selections have been
        | c |       made, you can simply hit the deletion primitive (`d`), then
        `---'       either enter insert mode to write down the replacement text
                    (`i`), or stay in command mode to paste the replacement
                    text stored in the yank register. As deleting and entering
        .---,       insert mode can be redundant, a primitive that implements
        | R |       deletion followed by insert mode entrance was implemented:
        `---'       `c`. You can also directly replace the current selection
                    with the content of the yank register using a primitive
                    also implemented for that purpose: `R`.


+=-------------------------------=+ ADVANCED +=-------------------------------=+

TBD

lenormf on 22 Jan 2017

❤17 👍17

All 25 comments

That one would be very nice, but I dont think I am the best person to write that, as I think I am a bit too familiar with Kakoune to see how to teach it to new comers. Any volunteer ?

mawww on 11 Jan 2017

👍5

And I'm on the opposite end of the spectrum: I'd like something like this to help me learn Kakoune. :)

nathanl on 11 Jan 2017

👍1

Here are the various topics from the original vimtutor, this could be a starting point.

I guess the first step is to identify the relevant ones, the ones that do not directly apply to kakoune philosophy and add missing concepts.

Lesson 1.1: MOVING THE CURSOR
Lesson 1.2: EXITING VIM
Lesson 1.3: TEXT EDITING - DELETION
Lesson 1.4: TEXT EDITING - INSERTION
Lesson 1.5: TEXT EDITING - APPENDING
Lesson 1.6: EDITING A FILE

Lesson 2.1: DELETION COMMANDS
Lesson 2.2: MORE DELETION COMMANDS
Lesson 2.3: ON OPERATORS AND MOTIONS
Lesson 2.4: USING A COUNT FOR A MOTION
Lesson 2.5: USING A COUNT TO DELETE MORE
Lesson 2.6: OPERATING ON LINES
Lesson 2.7: THE UNDO COMMAND

Lesson 3.1: THE PUT COMMAND
Lesson 3.2: THE REPLACE COMMAND
Lesson 3.3: THE CHANGE OPERATOR
Lesson 3.4: MORE CHANGES USING c

Lesson 4.1: CURSOR LOCATION AND FILE STATUS
Lesson 4.2: THE SEARCH COMMAND
Lesson 4.3: MATCHING PARENTHESES SEARCH
Lesson 4.4: THE SUBSTITUTE COMMAND

Lesson 5.1: HOW TO EXECUTE AN EXTERNAL COMMAND
Lesson 5.2: MORE ON WRITING FILES
Lesson 5.3: SELECTING TEXT TO WRITE
Lesson 5.4: RETRIEVING AND MERGING FILES

Lesson 6.1: THE OPEN COMMAND
Lesson 6.2: THE APPEND COMMAND
Lesson 6.3: ANOTHER WAY TO REPLACE
Lesson 6.4: COPY AND PASTE TEXT
Lesson 6.5: SET OPTION

Lesson 7.1: GETTING HELP
Lesson 7.2: CREATE A STARTUP SCRIPT
Lesson 7.3: COMPLETION

Delapouite on 12 Jan 2017

I proposed a small tutorial.kak script in #1144, that implements navigation through tutorial lessons. The design principle seems accepted at least by @mawww , I think we can discuss about the content here. Here's a proposal that may evolve (I checked the entries that are already written or copied from vimtutor)

[x] Introduction
[x] Moving the cursor h j k l - copied from vimtutor, re-write
[x] Exiting Kak :quit! - copied from vimtutor, re-write
[x] Deletion d - copied from vimtutor, re-write
[x] Insertion i - copied from vimtutor, re-write
[x] Appending a A - copied from vimtutor, re-write
[ ] Editing a file :write
[x] Selection H J K L
[ ] Text objects w W <a-a> <a-i>
[ ] Yanking y
[ ] Put p P <a-p
[ ] Replace r
[ ] Change c
[ ] Searching f t F T / s (too much commands here)
[ ] Multiple selections s <a-s> <a-k>
[ ] View v
[ ] Moving in the buffer g <c-i> <c-o>
[ ] Buffers :buffer :buffer-next :delete-buffer ga
[ ] External commands | ! <a-|> <a-!>
[ ] Modes
[ ] Scopes
[ ] Substitutions %opt{} %val{} %sh{}
[ ] Mappings :map
[ ] Custom commands :define-command
[ ] Kakrc
[x] Have fun with Kakoune!

lisael on 21 Jan 2017

Nice job lisael, thanks!

I would add two more chapters after the one dedicated to Multiple Selections. One about the g commands and another one about v commands.

How do you want to proceed for the writting? Should we use the wiki as a temporary place to conbribute drafts ? When good enough you could then include these chapters to as proper asciidoc files to your https://github.com/mawww/kakoune/pull/1144/files PR, and then we could remove them from the wiki.

Delapouite on 22 Jan 2017

Just one thing guys, please dont base that work directly on the vimtutor contents. Dont go read and convert part of the vimtutor to make the Kakoune tutorial, as doing that would make Kakoune's tutorial a derived work of Vim's, preventing us from releasing it under the UNLICENSE.

Thanks a lot for taking a look at this, its been missing for far too long.

mawww on 22 Jan 2017

👍1

@Delapouite: I like the wiki idea, that saves me the burden of managing PRs on my branch. Let's do this.

@mawww: yes, I noticed the license issue here: https://github.com/mawww/kakoune/pull/1144/files#diff-a6485e2b20682946e757ea94b4b951f2R10 . If it's not enough, as you seem to think, rewording these sections is far easier than trying to figure out if it's legal or not. We'll re-word them.

lisael on 22 Jan 2017

the contents of the tutors are generally rewrites of already existing documentation, which is a great waste of time
the users end up forgetting the keys they used because they didn't have a real use for them, aside from hitting them in order to move forward in the tutorial
users will remember what they read in the tutor when hitting a given key, but if they have a doubt they can't easily go back to the paragraph that explained what the key did
it's more important that users finish the tutor, than the tutor be describing all the options possible at any given time; except all the tutors out there are way to long to be quickly finished, and give a minimal toolset that allows a new user to get started

The second section about advanced primitives is being written, but in the mean time here is my first draft:

+=----------------------------------------------------------------------------=+
              _              _
             | |            | |
             | | __   __ _  | | __   ___    _   _   _ __     ___
             | |/ /  / _` | | |/ /  / _ \  | | | | | '_ \   / _ \
             |   <  | (_| | |   <  | (_) | | |_| | | | | | |  __/
             |_|\_\  \__,_| |_|\_\  \___/   \__,_| |_| |_|  \___|

                  Mawww's experiment for a better code editor
+=----------------------------------------------------------------------------=+

This walkthrough is an introduction to Kakoune's basic edition capabilities to
help new users transition over easily from another editor, or simply learn
how to write and edit documents with style.

In the first section, you will learn about the primitives of the edition
language to be able to get to a level of knowledge of the editor that
guarantees that you can work with it efficiently.

In the second section, for users who've gone through the basics and want
to move on to more advanced functionalities, we explain other primitives
whose role has a less dominant place in an everyday editing session, but
still prove themselves powerful when used on the right occasion.

Finally, as this document is in no way an exhaustive list of features, don't
hesitate to check out the official documentation to compliment your toolset,
ask questions to more seasoned users on IRC, and check the documentation
using the onboard `:doc` command.

+=--------------------------------=+ BASICS +=--------------------------------=+

                    =[ MODES

                    Kakoune uses a paradigm called "modal edition" to allow
       .---,        users to either have every single key they type inserted
       | i |        into the file being edited (called "insert mode"),
       `---'        or execute commands that are triggered by the keys hit
                    (the "command mode").  Aside from arrow keys, most keys
       .---,        described in this document are "edition primitives" that
       |esc|        have to be hit in command mode, which is the default mode
       `---'        when you start the editor. To enter insert mode, hit the
                    `i` key, and to leave it, hit the escape key.


                    =[ MOVEMENT
       .---,
       | ^ |        Movement in a buffer (the representation of the contents
   .---'---'---,    of a file opened by Kakoune) can be achieved using the arrow
   | < | v | > |    keys, which will move the cursor up one column/row into
   `---'---'---`    a given direction.

                    However, furthering the tradition of both mode-based
 .---,---,---,---,  editors, the `h`, `j`, `k` and `l` keys can be used for the
 | h | j | k | l |  same purpose, and will respectively move the cursor to the
 `---'---'---'---`  left, down, up, right by one, when hit. Using those keys
   |   |   |   |    is the recommended way of moving around in a buffer.
 .---,---,---,---,  If you're not familiar with this concept, the proximity
 | < | V | ^ | > |  of those four keys with the rest of the lettered keys
 `---'---'---'---`  on a `qwerty` layout allows faster interaction with the
                    primitives than if the user had to moves their hand to
                    reach the arrow keys.
   .---,
   | g |_.          Another way of moving the cursor is the "goto" utility,
   `---' |`.---,    invoked by hitting the `g` key. A menu will pop up with a
         | | g |    summary of all the possible keys that can be hit, along with
         | `---'    the location where they will move the cursor to, but the
          `.---,    most used ones that we are interested in, for now, are `g`
           | e |    and `e`. The first one will jump to the beginning of the
           `---'    buffer, and the second one to its end.


                    =[ VIEW

   .---,            Displacing the cursor can sometimes move the view into an
   | v |_.          inconvenient configuration, leaving some necessary context
   `---' |`.---,    off screen, or simply feel uncomfortable to type into.
         | | t |    Kakoune provides a menu (similar to the `goto` menu
         | `---'    mentioned in the previous section) that allows users to
         |`.---,    move the current view in relation with the position of the
         | | b |    cursor. Upon hitting the `v` key, a short menu appears
         | `---'    which allows us to hit a second key according to how the
          `.---,    view should be centered: to leave the cursor respectively
           | v |    on top, at the bottom or in the middle of the current view,
           `---'    hit the `t`, `b` or `v` keys.


                    =[ SEARCH

                    In order to move the cursor to a specific word, the search
                    command is the way to go. This functionality allows
        .---,       the user to jump to next occurence of a piece of text.
        | / |       Upon hitting the `/` key, a prompt reading "search"
        `---'       will pop up in the status bar in which you can type
                    your text and validate using the `<ret>` (return) key.
     .---, .---,    You'll notice that as you type, the cursor changes location
     |alt|+| / |    to automatically give you a preview of where the cursor
     `---' `---'    would be displaced to if you validated the search. However,
                    this behaviour is only a preview, exiting prompt mode with
                    the `<esc>` (escape) key will leave the current position
        .---,       of the cursor unchanged. Note that you can also use a
        | n |       Perl regular expression as input.  By default the search
        `---'       function will look for results forward, starting from
                    the current location of the cursor, but you can search
     .---, .---,    backwards using `<a-/>` (alt + `/`).
     |alt|+| n |
     `---' `---'    Jumping from one match to the other forward can be achieved
                    using the `n` key, and backwards using the `<a-n>` (alt +
                    `n`) key combination.


                    =[ SELECTIONS

                    You have certainly noticed that when searching for
        .---,       text, the cursor extends to highlight the entire match.
        | ; |       In fact, what we know in other editors as a "cursor" is
        `---'       actually a single character wide selection in Kakoune,
                    and can be expanded using primitives. When "expanded",
     .---, .---,    the selection is an area whose beginning is the "anchor"
     |alt|+| ; |    and the end the "secondary cursor". To switch anchor and
     `---' `---'    cursor, use `<a-;>`, and to collapse the selection onto
                    its anchor, use `;`.

                    Moreover, not only Kakoune expands the principle of
                    "cursor" by introducing selections, but it also allows
        .---,       multiple selections within the same buffer. This makes
        | % |       it very convenient to modify text in multiple locations
        `---'       at once, as edition primitives apply to all the currently
                    selected text.
        .---,
        | s |       Example: to remove all occurrences of the word "foo", one
        `---'       would select the entire buffer (`%`), select occurrences of
                    the word (`s`, "\<foo\>", `<ret>`), then remove it (`d`).

                    ==[ SELECTING OBJECTS

                    In addition to allowing text selection using regular
     .---, .---,    expressions, certain objects are defined by default to
     |alt|+| i |    allow easy selection of text. Objects are bits of text
     `---' `---'    in the buffer that are identified according to their
                    structure, rather than their contents, e.g. a paragraph,
     .---, .---,    a sentence, or a word. When the cursor is located within
     |alt|+| a |    the boundaries of an object you want to interact with,
     `---' `---'    several options are available: selecting the contents of an
                    object without its boundaries (`<a-i>`), a part of it (from
        .---,       the anchor to its end or to its beginning, respectively `]`
        | ] |       and `[`), or the entire object (`<a-a>`). Those "selection
        `---'       ranges" are the first part of a two stages shortcut,
                    as once you've used the key that dictates what part of
        .---,       the object is to be selected, a menu with a description
        | [ |       of all the object types selectable will be displayed,
        `---'       giving a summary of all the keys you can hit to complete
                    the selection procedure.

                    Example: to select the paragraph in which the anchor lies,
                    invoke the "inner object selection" shortcut (`<a-i>`),
                    locate "paragraph" in the information box that pops up and
    .---,           hit the according key (`p`). The entire two steps sequence
    | [ |_.         is thus: `<a-i> p`.
    `---' |`.---,
          | | ( |   Example: to select everything between the anchor and the
          | `---'   beginning of the current paren pair, use the selection
           `.---,   sequence is: `[ (`. Note that common objects that use
            | r |   pairs of opening/closing punctuation signs (brackets,
            `---'   braces, quotes etc) have an alternative second key that
                    is displayed in the information menu that you can use to
                    minimize finger gymnastics. The previous shortcut could
                    thus also be written: `[ r`.

                    ==[ MOVEMENT SELECTIONS

                    If objects are an easy way to select content-agnostic
    .---,           data in a buffer, they can also be seen as a way to move
    | [ |_.         about the buffer. As selecting objects will displace the
    `---'  `.---,   anchor into a given direction, you can wrap or move around
            | p |   particular chunks of text without using the conventional
            `---'   means (e.g. arrow keys or jumps), turning them partially
                    into movement primitives.
    .---,
    | ] |_.         Example: one of the most used object selection combination
    `---'  `.---,   is the "object end/begin paragraph" one: using `[` or
            | p |   `]` will displace the anchor into a given direction, and
            `---'   applying that to the paragraph object allows "jumping"
                    from one newline separated block of text to another.
                    The resulting shortcut is thus: `] p` to move forward, or
                    `[ p` to move backward.


                    =[ FILTERING A SELECTION

                    Selecting an entire buffer (`%`) or parts of it (`s`) is a
                    natural and basic operation in a typical editing session,
     .---, .---,    however there are some cases where we need to be able to
     |alt|+| k |    drop some selections arbitrarily, as opposed to trying
     `---' `---'    to select the ones we need directly. This concept becomes
                    very useful when coming up with a regular expression for
     .---, .---,    the basic selection primitive (`s`) is too tedious (if
     |alt|+| K |    even possible), that's why the editor provides us with a
     `---' `---'    "keep matching" and a "keep not matching" operations,
                    in order to respectively keep exclusively the selections
                    who match or do not match a given regular expression.

                    Example: when parsing a log file whose lines follow the
                    usual log pattern (e.g. "[1484383442] ERROR: some data"),
                    we want to be able to select all the lines individually
     .---, .---,    (`%`, `<a-s>` to split all the lines), keep those that
     |alt|+| s |    start with a bracketed timestamp (`<a-k>^\[`), but
     `---' `---'    exclude the debug messages (`<a-K>DEBUG`). Of course,
                    it's possible to come up with a regular expression to
                    match those simple requirements, but it would take more
                    work to write it than to organically apply filters on a
                    general selection, individually.


                    =[ SELECTION DUPLICATION

        .---,       Duplicating content can be achieved using a widely
        | y |       implemented concept: yanking and pasting. Copying the
        `---'       current selection into the yank register (`y`) allows the
        .---,       user to subsequently insert the copied text in the buffer
        | p |       (`p`).
        `---'
        .---,       Note that the default "paste" primitive will insert the
        | P |       contents of the yank register after the current selection,
        `---'       if you want copied test to be inserted before the current
                    selection then you can use the `P` key.


                    =[ REPLACING SELECTIONS

                    Text replacement is a two step process in Kakoune, which
                    involves selecting text to be replaced, and then erasing it
        .---,       to insert the replacement text. After selections have been
        | c |       made, you can simply hit the deletion primitive (`d`), then
        `---'       either enter insert mode to write down the replacement text
                    (`i`), or stay in command mode to paste the replacement
                    text stored in the yank register. As deleting and entering
        .---,       insert mode can be redundant, a primitive that implements
        | R |       deletion followed by insert mode entrance was implemented:
        `---'       `c`. You can also directly replace the current selection
                    with the content of the yank register using a primitive
                    also implemented for that purpose: `R`.


+=-------------------------------=+ ADVANCED +=-------------------------------=+

TBD

lenormf on 22 Jan 2017

❤17 👍17

@lenormf maybe your point against the tutor thing is true for some user, but there are still users, like @nathanl, who expect something like that. Most Vim users will, and they will learn the concepts easily.

That said, either the tutor and trampoline are light enough to be included in the distribution, if it's clearly advertised, these are two options to learn Kakoune.

I've already thought about building a project in an advanced part of the tutorial, showing the code of the tutorial itself, which is simple and uses a few core concepts (mappings, custom commands, options, %sh{}...).

I also wanted the tutorial to emphasis on the extensibility of Kakoune, and that Kakoune tries to ease the integration with external tools.

lisael on 22 Jan 2017

Actually the original issue mentions something that helps new users understand how the editor works, the fact that it was called kaktutor later on probably mislead some of us, but we never officially decided we needed a full on interactive vimtutor clone.

I think the interactive tutor should get it's own repository in a Kakoune organization, to which this repository is also added, and a smaller tutor could be merged upstream.

lenormf on 22 Jan 2017

I found Vim tutor boring, but I like @lenormf’s trampoline.

alexherbo2 on 22 Jan 2017

it's own repository in a Kakoune organization

github may be willing to give back this sleeping account: https://github.com/kakoune

Delapouite on 22 Jan 2017

👍3

It doesn't matter what the name is, it could be kakoune-editor or something along those lines. @mawww, would you create an organization?

lenormf on 22 Jan 2017

I think the tutorial approach makes sense, especially for users not familiar with modal text editors. Guiding new users progressively, introducing concepts/features along with small exercises seems like the traditional method we use to teach almost anything, I think its a pretty good default. As a feature focused on new users, I'd argue it should be bundled with Kakoune, having a :tutorial command available in default installs seems like a good choice.

@lenormf approach is pretty different, and seems tailored towards a different way of learning a tool. I think it would actually be a good alternative to the tutorial, especially for people already familiar with Vim. So I'd be okay to merge both as they serve different purposes, in a sense @lenormf's version is a in depth cheatsheet for Kakoune.

@lisael We cannot just reword Vim's tutorial, it needs to be written from scratch, else its a derivative work from Vim and we have to license it separately. I'd like to avoid introducing pieces with different licenses in the main repo, except in contrib/ where I dont mind much.

mawww on 22 Jan 2017

@lenormf the trampoline is exactly what i'm looking for! any progress on the advance primitives section?

RandomLetter on 10 Feb 2017

@RandomLetter none, I will create a PR if I ever finish the document.

lenormf on 11 Feb 2017

I actually found the vim tutor helpful, this trampoline idea seems to tell you the basic concepts but I like to have a playground to test stuff on.

TheInitializer on 1 Mar 2017

The playground is just using the editor on a source file.

lenormf on 1 Mar 2017

follow up on the trampoline: https://github.com/mawww/kakoune/blob/master/contrib/TRAMPOLINE

Delapouite on 11 Sep 2017

Really like @lenormf’s work on trampoline.

alexherbo2 on 16 Nov 2017

I made a PoC for a gamified "tutorial":

Is that something we would like, or should it be more formal? This is the first "lesson", I still don't know how switching to the next/previous lesson would work.

EDIT: yes, there is collision detection in the maze!

lenormf on 15 Jun 2018

👍2

I think that the blog post _Everyone Who Tried to Convince Me to use Vim was Wrong_ [0] gives a valuable perspective for us.

Maybe the tutorial should focus on just making in easy and simple for current users of other text editors and IDEs to adapt Kakoune into their daily workflows without make an significant impact on their productivity? I don't think that you have to use h, j, k and l from day one. Simple replace your current text editor with Kakoune, but use it as you would with your former one.

Most people don't want to make an _initial huge_ investment into something there they already have a tool that fulfills its purpose. But if they fell comfortable with Kakoune they'll sooner or later begin to explore its capabilities.

[0] https://yehudakatz.com/2010/07/29/everyone-who-tried-to-convince-me-to-use-vim-was-wrong/

a12l on 15 Jun 2018

👍2

I don't know where we are at concerning the dynamic tutorial but I would like to add my two cents.

As much as I like the trampoline, I'd like to defend the fact that having a tutorial with a playground is also good to have.
I remember when I first started using vim 4-5 years ago, vimtutor was what helped me build my first muscle memory that have served me up until now. The advantage of having a playground given for you is that for someone who's only just starting using text editors, as I was back then, it's pretty difficult to set up your own playground. It is a pretty off-puting task for a beginner compared to having an already made playground with the text elements exactly at the right place for you to learn effectively.

What I want to express is that the trampoline way might be the best way for some and the "tutor" way best for others and therefore we shouldn't choose one over the other.