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