Open nathanl opened 7 years ago
mawww
commented
7 years ago 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 ?
nathanl
commented
7 years ago And I'm on the opposite end of the spectrum: I'd like something like this to help me learn Kakoune. :)
Delapouite
commented
7 years ago 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
lisael
commented
7 years ago 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)
h j k l - copied from vimtutor, re-write:quit! - copied from vimtutor, re-writed - copied from vimtutor, re-writei - copied from vimtutor, re-writea A - copied from vimtutor, re-write:writeH J K Lw W <a-a> <a-i>yp P <a-prcf t F T / s (too much commands here)s <a-s> <a-k>vg <c-i> <c-o>:buffer :buffer-next :delete-buffer ga| ! <a-|> <a-!>%opt{} %val{} %sh{}:map:define-commandDelapouite
commented
7 years ago 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.
mawww
commented
7 years ago 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.
lisael
commented
7 years ago @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.
lenormf
commented
7 years ago 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:
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 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.
lenormf
commented
7 years ago 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.
alexherbo2
commented
7 years ago I found Vim tutor boring, but I like @lenormf’s trampoline.
Delapouite
commented
7 years ago it's own repository in a Kakoune organizationgithub may be willing to give back this sleeping account: https://github.com/kakoune
lenormf
commented
7 years ago It doesn't matter what the name is, it could be kakoune-editor or something along those lines. @mawww, would you create an organization?
mawww
commented
7 years ago 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.
RandomLetter
commented
7 years ago @lenormf the trampoline is exactly what i'm looking for! any progress on the advance primitives section?
lenormf
commented
7 years ago @RandomLetter none, I will create a PR if I ever finish the document.
TheInitializer
commented
7 years ago 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.
lenormf
commented
7 years ago The playground is just using the editor on a source file.
Delapouite
commented
7 years ago follow up on the trampoline: https://github.com/mawww/kakoune/blob/master/contrib/TRAMPOLINE
alexherbo2
commented
6 years ago Really like @lenormf’s work on trampoline.
lenormf
commented
6 years ago 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!
a12l
commented
6 years ago 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/
sweenu
commented
4 years ago 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.
alexherbo2
commented
4 years ago We need Vimcasts for Kakoune. ^^
pickfire
commented
3 years ago I thought append lists for alt-z is useless, I get to use it when solving advent of code day 3. https://adventofcode.com/2020/day/3
Keys: %<alt-s>Hy30pggZQllj<alt-z>aQ321qs#
Spirarel
commented
3 years ago Echoing Sweenu, it should be 100% painless to direct people to a place they can onboard. Comments like,
The playground is just using the editor on a source file.
Demonstrate a lack of understanding of first-exposure UX. If you open up kakoune, first it doesn't show you an empty buffer. it shows you the changelist. When you do finally press a key, you're maybe going to be in insert mode and you'll be able to paste the trampoline (which you've had to copy from a git-repo). More than likely you'll hit the scratch buffer in normal mode, try pasting and wonder why it's strangely getting clipped.
What's more, people with some vim exposure are going to be a large part of kakoune's early user base—the first thing many of us are going to look for is a vimtutor equivalent.
RedEmberCat
commented
2 years ago @lenormf
Thank you for writing Trampouine. Reference material has a place, surely, and Trampoline is great for that. However, I kindly request that all reference to vimtutor should be removed from the Trampoline material (just do a websearch for "Kakoune tutor" to see what I mean). This affects google searches and makes finding quick start material more difficult. Trampoline fulfills a very different role and is not suited to those who are trying to commit the basics to muscle memory. It certainly isn't suited to those new to vim-like text editing.
When I finished Trampoline, I was still was not comfortable using Kakoune. By contrast, when I first started using vim several years ago, after going through vimtutor a few times, the basics of vim were part of muscle memory and I was quite comfortable to begin using vim. This result is supported by pedagogy research: hands-on experience trumps reading a feature list.
FWIW: I am currently going through vimtutor USING kakoune. That is the state of Kakoune learning material.
I may write such a tutor once I have a better handle on kakoune. I'll make sure to not pull directly from vimtutor to avoid license issues. I see @lisael is making something, which looks wonderful, but seems much more complex and specialized than what is necessary to get folks up and running.
lenormf
commented
2 years ago There’s no reference to any “tutors” in TRAMPOLINE, I don’t know what to do.
The wiki was recently updated to link to a third party “tutor”, maybe that will help: https://git.sr.ht/~voroskoi/tutor.kak
bound-variable
commented
2 years ago There’s no reference to any “tutors” in
TRAMPOLINE, I don’t know what to do.The wiki was recently updated to link to a third party “tutor”, maybe that will help: https://git.sr.ht/~voroskoi/tutor.kak
I couldn't get this tutor to work. Perhaps it's user error, perhaps not - there aren't any instructions. If it doesn't work, the wiki should probably remove its listing.
goyalyashpal
commented
1 year ago Just one thing guys, please dont base that work directly - https://github.com/mawww/kakoune/issues/1122#issuecomment-274328773
We cannot just reword Vim's tutorial, it needs to be written from scratch - https://github.com/mawww/kakoune/issues/1122#issuecomment-274354318
hey @mawww I think it would be better if you append these in the comments near the top, this top-second comment of urs for example: https://github.com/mawww/kakoune/issues/1122#issuecomment-271848838
Ashvith10
commented
12 months ago What is the status of the kakoune tutorial? Haven't see any activities in a while?
As mentioned in https://github.com/mawww/kakoune/issues/249