Add tutorial/demo

[veracioux]

I created a tutorial and demonstration for the program:

Something like this is very nice to have in a README. The tutorial/demo is incomplete and unpolished. I wanted to create this proof of concept quickly so I could get your early feedback and avoid falling into a rabbit hole.

Disclaimer: The following is shameless self-promotion.

I created this using a project of my own making: tuterm.
Nothing fancy, just a bash extension that allows you to create both a demonstration and an interactive CLI tutorial all in the same bash script. I created it in the hope that it will be useful for developers and CLI users as well.
Coupled with asciinema, you can create and upload the demo with near-zero manual work.

This is the command I used to create the demo:

cd docs; asciinema rec -c 'tuterm bak.tut --mode demo' bak.cast

to upload it:

asciinema upload bak.cast

Actually, I removed a single line from the bak.cast file before uploading it because it contained an error message. But I'll fix that error in the future so this step won't be necessary.

If you want to run it in interactive tutorial mode, use the following command:

tuterm ./bak.tut

If you want to speed up the printing of user prompts, you can add a --fast or -f option. Also, don't worry about ~ being displayed as the working directory while running the tutorial. Everything is done under a fake home directory that is located under /tmp.

I hope you find this useful :)

[ChanceNCounter]

I sincerely appreciate it. I've blown it with asciinema a couple times, just failing to stick to the script. I'll definitely take a closer look at tuterm later today! Seems like a great util.

By all means, iterate on this, or I can take the handoff. Either way, have a Hacktoberfest credit!

Aside: the missing word "erase" from the bak down confirmation prompt should be fixed.

[veracioux]

By all means, iterate on this, or I can take the handoff.

I'll steadily keep working on it. After a certain checkpoint, I'll take your feedback and put the demo into the README.

Either way, have a Hacktoberfest credit!

Thanks ^^

Aside: the missing word "erase" from the bak down confirmation prompt should be fixed.

Great!

[veracioux]

I think the automatic demonstration is ready. I'm still working on the extended tutorial.

Please look inside the directory docs/demo. There is a README that should explain it nicely.

Customization you can do:

• In the file docs/demo/asciinema_upload_and_create_svg.sh, set a custom terminal size if you don't like the one I chose.
• In the file docs/demo/bak.tut you can change the default prompt, the delays and colors. You'll have to look at the man page of tuterm, or I can help you.

I created an animated SVG and put it into the main README of the repo. And if you click on the animated image in the README, it will take you to the asciicast on asciinema.org. I hosted the files on my personal accounts. Of course, you should host the files on your own (or organization's) account. The SVG can be hosted either as a gist or you can keep it inside this repo under docs/demo/. I personally find the first approach cleaner.

I advise you to change the size of the animated SVG. I didn't want to change it because I thought it's best that you do it.

Let me know what you think. Also let me know if you reach any kind of roadblock.

[ChanceNCounter]

Real life has eaten me, but I swear I haven't forgotten you guys! bak will get some love this week, starting with the open PRs. (@mike-k0)