[WIP] Tutorial proposal #1144

lisael · 2017-01-19T19:33:03Z

Here's a proposal to address #1122. This adds a :tutorial command that opens a tutorial where one can navigate page by page.

There's a mechanism to chose the tutorial language, a draft of a few lessons, added as simple .md file.

I show it now to validate the design, not the content (there must be a lot of gramar and syntax oddities as, I'm not a native English speaker).

I think, if the design is validated, we should resolve wether the tutorial must remain in the main kakoune repo or live in its own repository to avoid poluting the issues with ToC choices, wording, translations and such.

Thank you for the feedback.

mawww

Hello,

Thanks very much for this proposal, its a very good starting point.

I think the markdown files should be converted to asciidoc (they probably just need renaming, markdown is usually valid asciidoc) to stay consistent with other documentation pages.

Also, they should be in doc/tutorial instead of rc/tutorial.

And it probably requires a few more advanced pages, introducing multiple selections, s/S <a-k>/<a-K>, word based movements...

Edit: just saw that its mostly for design validation, I think the design is sound, and it can be worked on in a branch of the main repo until we deem it ready.

mawww · 2017-01-20T00:06:13Z

rc/tutorial/en/030-selections.md

+ - `i` inserts before the selection
+ - `A` moves the selection to the last character of the line and append text
+
+Some move commands perform selecting moves, i.e. the anchor is fixed and only


I think expanding would be a better word than selecting for these moves.

mawww · 2017-01-20T00:06:39Z

rc/tutorial/en/000-introduction.md

+previous page.
+
+The tutorial pages are editable and contain instructions to change them. At
+any time, you cah restore the pages to their original content with `<<esc>,r`.


typo (cah instead of can)

mawww · 2017-01-20T00:07:54Z

rc/tutorial/en/030-selections.md

+  8. When comfortable, go to the next lesson
+
+...> There all words
+...> There are missing words here.


Its not clear to me what edit should be done here.

mawww · 2017-01-20T00:09:02Z

rc/tutorial/en/meta-help.md

+    2. Give direct feedback to the user (with the help box)
+    3. Incite the user to create and adapt their own tools
+
+Thus, the main documentation should remain a single web page : https://github.com/mawww/kakoune/blob/master/README.asciidoc


Not sure about that, we do have the :doc command thats expected to replace the README.

lisael · 2017-01-20T22:27:47Z

I moved tutorial.kak into rc/base/

lenormf · 2017-01-21T07:09:52Z

rc/base/tutorial.kak

+def tutorial -params .. -docstring %{ Run the kakoune tutorial } -allow-override %{
+    %sh{
+        [ $# -gt 0 ] && tutlang="$1" || tutlang="en"
+        echo "set global tutorial_dir $(dirname ${kak_opt_tutorial_source})/../../doc/tutorial/$tutlang"


Use printf here for POSIX correctness.

lenormf · 2017-01-21T07:10:18Z

rc/base/tutorial.kak

+def -hidden tutorial-load -params 0..1 -allow-override %{
+    %sh{
+        bufname="*${kak_opt_tutorial_lesson}*"
+        if [ $(echo "${kak_buflist}" | grep "${bufname}") ]; then


lenormf · 2017-01-21T07:10:28Z

rc/base/tutorial.kak

+    %sh{
+        bufname="*${kak_opt_tutorial_lesson}*"
+        if [ $(echo "${kak_buflist}" | grep "${bufname}") ]; then
+            echo "buffer ${bufname}"


lenormf · 2017-01-21T07:10:35Z

rc/base/tutorial.kak

+        if [ $(echo "${kak_buflist}" | grep "${bufname}") ]; then
+            echo "buffer ${bufname}"
+        else
+            echo "edit -scratch ${bufname}"


lenormf · 2017-01-21T07:10:45Z

rc/base/tutorial.kak

+            echo "buffer ${bufname}"
+        else
+            echo "edit -scratch ${bufname}"
+            echo "tutorial-reload $@"


lenormf · 2017-01-21T07:11:02Z

rc/base/tutorial.kak

+        if [ "$1" = "-no-nav" ]; then
+            nav=false
+        fi
+        echo "exec -draft -client ${kak_client} \%d"


lenormf · 2017-01-21T07:11:24Z

rc/base/tutorial.kak

+            nav=false
+        fi
+        echo "exec -draft -client ${kak_client} \%d"
+        if $nav ; then


You should use [ -n "$nav" ] here

lenormf · 2017-01-21T07:11:28Z

rc/base/tutorial.kak

+        fi
+        echo "exec -draft -client ${kak_client} \%d"
+        if $nav ; then
+            echo "exec -draft -client ${kak_client} |cat<space>${kak_opt_tutorial_dir}/meta-nav.md<ret>\;"


lenormf · 2017-01-21T07:11:50Z

rc/base/tutorial.kak

+        fi
+        echo "exec -draft -client ${kak_client} ge|cat<space>${kak_opt_tutorial_dir}/${kak_opt_tutorial_lesson}<ret>\;"
+        echo "exec -client ${kak_client} gg"
+        # echo "exec -draft -client ${kak_client} ggO\`<lt>esc<gt>,h\`<space>previous<space>page<esc> Qa<space><esc><esc>35q anext<space>page<space>\`<lt>esc<gt>,l\`<esc> o<esc>"


printf on the last 3 lines

lenormf · 2017-01-21T07:13:10Z

rc/base/tutorial.kak

+
+def tutorial-prev -allow-override %{
+    %sh{
+        next=$(ls "${kak_opt_tutorial_dir}" | grep -v "meta-" | grep -B 1 "${kak_opt_tutorial_lesson}" | head -1)


ls -1 would be safer here I think, and the -B flag for grep isn't POSIX.

lenormf · 2017-01-21T07:13:16Z

rc/base/tutorial.kak

+def tutorial-prev -allow-override %{
+    %sh{
+        next=$(ls "${kak_opt_tutorial_dir}" | grep -v "meta-" | grep -B 1 "${kak_opt_tutorial_lesson}" | head -1)
+        echo "set global tutorial_lesson $next"


lenormf · 2017-01-21T07:14:01Z

Why are all the functions declared as overridable?

lisael · 2017-01-21T15:26:35Z

@lenormf It's a work in progress, I just have to reload the file to test the functions, I remove the -allow-override when I'm satisfied. Thank you for the POSIX advices.

lenormf · 2017-01-22T07:56:47Z

I hadn't seen that there's also an -A flag passed to grep, as well as a -B one. Those are probably not available on all implementations of grep, so they will have to go.

lisael · 2017-01-22T10:44:07Z

Yes, I saw that, I didn't fix -[A|B] yet, because it's less obvious as echo -> printf. I read the POSIX man for grep, it's pretty limited. I probably have to convert the grep to a sed or awk script.

lenormf · 2017-01-22T10:46:48Z

Welcome to cross platform shell script compatibility hell!

lisael · 2017-01-22T12:04:14Z

:)

awk did the trick (I checked, -v is POSIX awk)

Added the tutorial mechanism

89797ea

mawww requested changes Jan 20, 2017

View reviewed changes

Move tutorial files in the doc directory

c31dcaf

lenormf reviewed Jan 21, 2017

View reviewed changes

rc/base/tutorial.kak Outdated

echo "buffer ${bufname}"

else

echo "edit -scratch ${bufname}"

echo "tutorial-reload $@"

Copy link

Contributor

lenormf Jan 21, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

printf

lenormf reviewed Jan 21, 2017

View reviewed changes

rc/base/tutorial.kak Outdated

if [ "$1" = "-no-nav" ]; then

nav=false

fi

echo "exec -draft -client ${kak_client} \%d"

Copy link

Contributor

lenormf Jan 21, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

printf

lenormf reviewed Jan 21, 2017

View reviewed changes

lisael added 2 commits January 21, 2017 19:45

fix the navigation filename in tutorial.kak

c63697d

added a conclusion

b6fca46

lisael mentioned this pull request Jan 21, 2017

Add a tutorial like vimtutor #1122

Open

Use printf instead of echo in tutorial.kak

598a64e

Remove non posix grep invocations

2f4d4f1

mawww force-pushed the master branch from e206727 to d652ec9 Compare October 10, 2018 11:48

MaxCan-Code mentioned this pull request Sep 4, 2021

possibly resolve #1122 #4312

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[WIP] Tutorial proposal #1144

[WIP] Tutorial proposal #1144

lisael commented Jan 19, 2017

mawww left a comment •

edited

mawww Jan 20, 2017

mawww Jan 20, 2017

mawww Jan 20, 2017

mawww Jan 20, 2017

lisael commented Jan 20, 2017

lenormf Jan 21, 2017

lenormf Jan 21, 2017

lenormf Jan 21, 2017

lenormf Jan 21, 2017

lenormf Jan 21, 2017

lenormf Jan 21, 2017

lenormf Jan 21, 2017

lenormf Jan 21, 2017

lenormf Jan 21, 2017

lenormf Jan 21, 2017

lenormf Jan 21, 2017

lenormf commented Jan 21, 2017

lisael commented Jan 21, 2017

lenormf commented Jan 22, 2017

lisael commented Jan 22, 2017

lenormf commented Jan 22, 2017

lisael commented Jan 22, 2017

[WIP] Tutorial proposal #1144

Are you sure you want to change the base?

[WIP] Tutorial proposal #1144

Conversation

lisael commented Jan 19, 2017

mawww left a comment • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lisael commented Jan 20, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lenormf commented Jan 21, 2017

lisael commented Jan 21, 2017

lenormf commented Jan 22, 2017

lisael commented Jan 22, 2017

lenormf commented Jan 22, 2017

lisael commented Jan 22, 2017

mawww left a comment •

edited