Add tutorial/demo

README.md

@@ -1,5 +1,7 @@
 # bak
 
+[![](https://gist.github.com/veracioux/5281aa92b29e89c0da0086207640dfd2/raw/1a35f46b3b1ae00baed35911789faedb6fe8519f/bak_demo.svg)](https://asciinema.org/a/442668)
+
 **bak** is a command-line utility for creating and restoring backup copies of single files - `.bak` files - without clutter.
 
 - [Description and Usage](#description-and-usage)

docs/demo/.gitignore

@@ -0,0 +1,2 @@
+bak_demo.svg
+bak_cast.cast

docs/demo/README.md

@@ -0,0 +1,33 @@
+## Dependencies
+
+- [asciinema](https://github.com/asciinema/asciinema)
+- [tuterm](https://github.com/veracioux/tuterm)
+
+## Running
+
+To run a non-interactive demo:
+
+```shell
+tuterm bak.tut --mode demo
+```
+
+To run an interactive tutorial:
+
+```shell
+tuterm bak.tut
+```
+
+To upload the demo to asciinema and create an SVG animated image:
+
+```
+./asciinema_upload_and_create_svg.sh
+```
+
+This will copy the asciinema URL to your clipboard and print it to your
+terminal. The SVG animation will be created as `./bak_demo.svg`.
+
+**NOTE:**
+- You should preview the demo first to verify it, so as to avoid uploading
+  content unnecessarily.
+- You should run the upload script in a new terminal so it doesn't mess up your
+  terminal size

docs/demo/asciinema_upload_and_create_svg.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env sh
+
+# NOTE: Change this to suit your needs
+
+TERM_WIDTH=90
+TERM_HEIGHT=25
+RECORDED_COMMAND="tuterm bak.tut --mode demo"
+alias copy='xsel -b'
+
+# Dependencies:
+# - asciinema (https://github.com/asciinema/asciinema)
+# - svg-term (https://github.com/marionebl/svg-term-cli)
+# - xsel
+
+# Since you are here, please also look at tuterm:
+#   https://github.com/veracioux/tuterm
+
+rm -f /tmp/bakfile_bak.cast
+
+stty cols "$TERM_WIDTH" rows "$TERM_HEIGHT"
+# Record the command
+asciinema rec -c "$RECORDED_COMMAND" /tmp/bakfile_bak.cast
+
+# Change terminal width and height
+# NOTE: for some reason the yes command prints Broken pipe; this is a workaround
+sed -e "1 s/\(\"width\": \)[0-9]\+/\1$TERM_WIDTH/" \
+    -e "1 s/\(\"height\": \)[0-9]\+/\1$TERM_HEIGHT/" \
+    -e '/Broken pipe/d' \
+    -i /tmp/bakfile_bak.cast
+
+# Upload to asciinema.org
+output="$(asciinema upload /tmp/bakfile_bak.cast)"
+echo "$output"
+
+# Copy URL to clipboard
+echo "$output" | grep 'https:' | sed 's/^\s*//' | copy
+
+# Create local SVG animation
+cat /tmp/bakfile_bak.cast | svg-term --out bak_demo.svg
+
+echo "SVG animation saved as 'bak_demo.svg'"

docs/demo/bak.tut

@@ -0,0 +1,107 @@
+#!/usr/bin/env tuterm
+
+export PYTHONPATH="$(pip show bak | grep 'Location:' | sed 's/Location: //')"
+USER_HOME="$HOME"
+
+configure() {
+    if mode demo; then
+        DELAY='0.05s'
+        DELAY_SEP='0.2s'
+        DELAY_PROMPT='1s'
+        TUTERM_NAME='bak-demo'
+    else
+        TUTERM_NAME='bak-tutorial'
+    fi
+}
+
+bak() {
+    python "$PYTHONPATH"/bak/__main__.py "$@"
+}
+
+editor() {
+    if mode tutorial; then
+        "$EDITOR" "$@"
+    else
+        # This is a bit of a hack
+        timeout 2.5 tmux new-session "$EDITOR +'set ft=sh' $*" >/dev/null
+    fi
+}
+
+run() {
+    # Prepare the working environment
+    mkdir -p ~/.config
+    cp "$USER_HOME/.config/bak.cfg.default" ~/.config/
+    if mode demo; then
+        EDITOR="vim"
+        echo "set -g status off" > ~/.tmux.conf
+    fi
+    echo -e "- [X] Install bak\n- [X] Make my life easier" > todo.txt
+
+# ┏━━━━━━━━━━━━━━━━━━━━━┓
+# ┃ Tutorial/demo start ┃
+# ┗━━━━━━━━━━━━━━━━━━━━━┛
+    if mode tutorial; then
+        m "-- bak tutorial start --"
+        echo
+    fi
+                                                                    # Command tracker
+    c ls
+    c cat todo.txt                                                  #
+    sleep 1
+
+    echo
+    M "Backup todo.txt"
+    c bak todo.txt                                                  #
+    if mode tutorial; then sleep 1; fi
+    m
+    m "<< You won't usually have to know where bakfiles are >>"
+    m
+    if mode tutorial; then sleep 1; fi
+    M "Change the file"
+
+    echo "- [ ] Take out trash         # Freshly added" >> todo.txt
+    e "$EDITOR" todo.txt                                            #
+    editor todo.txt
+    M "Let's back up the changes"
+    c bak todo.txt                                                  #
+    c bak list todo.txt                                             #
+
+    echo
+    sleep 1
+    M "Restore the file from entry #1 (the original)"
+    e bak down todo.txt 1                                           #
+    if mode tutorial; then
+        bak down todo.txt 1
+    else
+        echo "1 bakfiles discarded"
+        # { sleep 1 && yes; } | bak down todo.txt 1
+        yes | bak down todo.txt 1
+        echo y
+    fi
+    echo
+    c cat todo.txt                                                  #
+
+    if mode demo; then
+        exit
+    fi
+# ┏━━━━━━━━━━┓
+# ┃ Demo end ┃
+# ┗━━━━━━━━━━┛
+
+    m "Let's see where the backup is located:"
+    c bak where todo.txt                                            #
+
+    m "We're done here"
+    c bak off todo.txt                                              #
+
+    m "If you have any questions, just run:"
+    c bak                                                           #
+
+    m
+    m "-- bak tutorial end --"
+# ┏━━━━━━━━━━━━━━┓
+# ┃ Tutorial end ┃
+# ┗━━━━━━━━━━━━━━┛
+}
+
+# vim: filetype=sh