Add a tutorial like `vimtutor` #1122

Open
nathanl opened this Issue Jan 10, 2017 · 6 comments

Projects

None yet

4 participants

@nathanl
nathanl commented Jan 10, 2017

As mentioned in #249

@mawww
Owner
mawww commented Jan 11, 2017

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
nathanl commented Jan 11, 2017

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

@Delapouite
Contributor

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
Contributor
lisael commented Jan 21, 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)

  • Introduction
  • Moving the cursor h j k l
  • Exiting Kak :quit!
  • Deletion d
  • Insertion i
  • Appending a A
  • Editing a file :write
  • 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>
  • Buffers :buffer :buffer-next :delete-buffer ga
  • External commands | ! <a-|> <a-!>
  • Modes
  • Scopes
  • Substitutions %opt{} %val{} %sh{}
  • Mappings :map
  • Custom commands :define-command
  • Kakrc
  • Have fun with Kakoune!
@Delapouite
Contributor

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
Owner
mawww commented Jan 22, 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment