Merge efd12c91d9 into 7908a678df

README.md

@@ -4,6 +4,23 @@
 cheat
 =====
 
+<div align="center">
+  <!-- TODO: change link to point to your upload to asciinema. -->
+  <a href="https://asciinema.org/a/Euf4KZlGhbHmmUfrROMel2yny">
+    <img width="600" src="/doc/demo/cheat_demo.svg" />
+  </a>
+  <br />
+  <sub>
+    This demo was created using
+    <a href="https://github.com/veracioux/tuterm">tuterm</a>.
+  </sub>
+  <br />
+  <sub>
+    Run <code>tuterm doc/demo/cheat.tut</code> in this repository for an interactive tutorial.
+  </sub>
+</div>
+<br />
+
 `cheat` allows you to create and view interactive cheatsheets on the
 command-line. It was designed to help remind \*nix system administrators of
 options for commands that they use frequently, but not frequently enough to

doc/demo/README.md

@@ -0,0 +1,13 @@
+# Automated demo/interactive tutorial
+
+[Tuterm](https://github.com/veracioux/tuterm) is used to create a fully automated real-time demonstration of the program.
+The demonstration is generated from the script `cheat.tut`, and it can be
+played in the terminal by running `tuterm -m demo cheat.tut`.
+
+To upload the demonstration, run `./asciinema_upload_and_create_svg.sh`. This
+script will upload to asciinema and give you back the URL, and create the SVG
+file `cheat_demo.svg`, both of which are meant to be included in the `README.md`.
+The SVG file should be included in version control. If you open the script, you
+will find some tweakable parameters.
+
+The `cheat.tut` can also serve as an interactive tutorial, if you run `tuterm cheat.tut`.

doc/demo/asciinema_upload_and_create_svg.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env sh
+
+# NOTE: Change this to suit your needs
+
+TERM_WIDTH=80
+TERM_HEIGHT=18
+RECORDED_COMMAND="tuterm cheat.tut --mode demo"
+alias copy='xsel -b'
+
+# Dependencies:
+# - asciinema (https://github.com/asciinema/asciinema)
+# - svg-term (https://github.com/marionebl/svg-term-cli)
+# - xsel
+
+# Tuterm can be found here:
+#   https://github.com/veracioux/tuterm
+
+rm -f /tmp/cheat.cast
+
+stty cols "$TERM_WIDTH" rows "$TERM_HEIGHT"
+# Record the command
+asciinema rec -c "$RECORDED_COMMAND" /tmp/cheat.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/cheat.cast
+
+# Upload to asciinema.org
+output="$(asciinema upload /tmp/cheat.cast)"
+echo "$output"
+
+# Copy URL to clipboard
+echo "$output" | grep 'https:' | sed 's/^\s*//' | copy
+
+# Create local SVG animation
+cat /tmp/cheat.cast | svg-term --out cheat_demo.svg
+
+echo "SVG animation saved as 'cheat_demo.svg'"

doc/demo/cheat.tut

@@ -0,0 +1,112 @@
+#!/usr/bin/env tuterm
+
+depends unbuffer
+if mode demo; then depends tmux; fi
+
+configure() {
+    # Configure delays and colors (optional)
+    if mode demo; then
+        DELAY='0.08s'
+        DELAY_SEP='0.2s'
+        DELAY_PROMPT='1s'
+        TUTERM_NAME='cheat-demo'
+    else
+        TUTERM_NAME='cheat-tutorial'
+    fi
+}
+
+# timeout a command but only in demo mode
+demo_timeout() {
+    if mode demo; then
+        unbuffer timeout "$@"
+    else
+        "${@:2}"
+    fi
+}
+
+demo_clear() {
+    if mode demo; then
+        clear
+    fi
+}
+
+_Message() {
+    Message "# $@"
+}
+alias M=_Message
+
+generate_custom_vim_cheatsheet() {
+    echo "---"
+    echo "tags: [ custom, vim ]"
+    echo "---"
+    echo "# Open files in a horizontal split"
+    echo "vim -o file1 file2 ..."
+    echo "# Open files in a vertical split"
+    echo "vim -O file1 file2 ..."
+    echo "# Go to next buffer"
+    echo ":n"
+    echo "# Go to previous buffer"
+    echo -n ":N"
+}
+
+# Print prompt but only in demo mode
+demo_prompt() {
+    mode demo && prompt
+}
+
+run() {
+    # This is where the demo/tutorial happens           # Command tracker
+    M "Read cheat sheets"
+    e cheat tar                                         #
+    demo_timeout 2.5 cheat tar
+
+    demo_clear
+    M "Comes with many cheat sheets preinstalled"
+    e cheat -l                                          #
+    demo_timeout 1.5 cheat -l
+
+    demo_clear
+    M "Search for a command"
+    e cheat -s git                                      #
+    demo_timeout 2 cheat -s git
+
+    demo_clear
+    M "Organize cheat sheets by tag"
+    c cheat --tag vcs                                   #
+
+    demo_prompt
+    mode demo && sleep 1.5
+
+    demo_clear
+    mkdir .cheat
+    generate_custom_vim_cheatsheet > .cheat/custom_vim
+    rm .lesshst
+
+    M "Local cheat sheets"
+    e tree -a                                           #
+    tree -a --noreport
+    e cheat custom_vim                                  #
+    cheat custom_vim
+
+    demo_prompt
+    if mode demo; then sleep 1.5; fi
+
+    demo_clear
+    M "Easily edit cheat sheets"
+    e cheat -e custom_vim                               #
+    if mode demo; then
+        # NOTE: A bit of a hack needed to display the editor
+        timeout 2 tmux new-session "tmux set status off; vim -R .cheat/custom_vim" >/dev/null
+    else
+        cheat -e custom_vim
+    fi
+
+    demo_clear
+    e cheat cheat                                       #
+    demo_timeout 1 cheat cheat
+
+    # Demo ends here
+    if mode demo; then c exit; fi
+}
+
+# vim: filetype=sh