veracioux/tuterm

A better way to learn CLI programs.

tuterm

Learn the CLI by doing instead of watching

Also check out: A collection of tutorials for your favorite CLI programs

Tuterm is a framework for running and creating real-time interactive tutorials and demonstrations of CLI programs.

Key features:

For users

• Ridiculously easy to use
• Step by step instructions
• Learn at your own pace
• No mistakes possible
• Customizable colors, delays and prompts

For tutorial creators

• Nothing more than a bash extension
• Create interactive tutorials and non-interactive demos with the same code
• Simple framework and minimalistic design
• Well documented
• Doesn't reinvent the wheel
• 100% repeatable

Example

The following script defines a short tutorial/demo for the command ls.

# file: ls_tutorial
configure() {
    DELAY=0.09
    DELAY_SEP=0.12
    DELAY_PROMPT=1.5
    COLOR_MESSAGE='1;32'
}

run() {
    mkdir dir
    touch file1 file2 .file3 dir/file
    M "Let's just run the command."
    cmdline ls
    M "The -a option shows hidden files."
    # c is an alias for cmdline
    c ls -a
    M "The -R option recurses into directories"
    c ls -R
    M "You can also see the file modes"
    c ls -l
}

This script is run as:

tuterm ls_tutorial --mode MODE

There are two supported MODEs: tutorial and demo. Demo mode types out the commands in real time just like a human would. Tutorial mode shows the user what to type and then waits for them to type it, correcting any mistakes.

Demo mode is great for creating terminal recordings. The video below was generated using asciinema:

asciinema rec -c 'tuterm ls_tutorial --mode demo' ls_tutorial.cast

Installation

Arch Linux

[aur-helper] -S tuterm

From source

After cloning this repository or downloading the source code, simply run

make install

(You may need to use sudo)

This will install tuterm under /usr/local. You can change this by setting PREFIX=/your/path/of/choice.

Documentation

Everything is documented inside the man page that is installed with tuterm.

Projects using tuterm

Contributing

Please, feel free to report any issues or feature requests here. But before you do that, have a look at TODO. (this file will steadily dissolve into GitHub issues)

If you want to submit a bug fix, you can simply open a pull request. But if you want to add a new feature, open an issue so we can discuss it first.

Everyone is welcome to contribute.

A note: Tuterm is a simple program, so most issues or features should be a good choice for a beginner.

tuterm's Issues

Add shell functions for skipping part of a tutorial/demo

When I create tuterm scripts, I often want to test out a certain portion of the tutorial starting somewhere from the middle. What I can do is comment out the part of the code that I want to skip. But this is annoying, and it comes with a problem:

What if those previous commands create or modify files that are necessary for the rest of the tutorial/demo to run correctly?

I propose the following solution: add SKIP and UNSKIP shell functions. SKIP sets a kind of state flag that indicates that all the commands that follow should be skipped. UNSKIP should do the opposite: unset the flag so that the commands that follow are not skipped.

cmdline ...           # Runs normally
SKIP
message "open a file" # Skipped
cmdline xdg-open file # Skipped
UNSKIP
cmdline ...           # Runs normally

What do skipped commands do?
Regardless of the mode the user specified, they should behave as if tuterm were started with the --mode demo --fast options, along with any other arguments that may have been given by the user.

‼️ Make sure to document the new features in the man page. ‼️

Testing

I'm not sure how we could go about this. What I do know is that it is a pain having to run tutorials/demos every time I make a change. We might have to use pseudoterminals, in which case I'd prefer a python/pytest implementation.

tuterm: error: fake home can only be created once!

I'm trying to follow the ls_tutorial from the README, but I get the following error:

$ tuterm ls_tutorial --mode demo
tuterm: error: fake home can only be created once!
Aborting.

Create cheatsheet for tuterm commands

Create a cheatsheet that can be used with the cheat program that:

• Shows the basic ways the tuterm command can be invoked
• Shows the most useful shell (API) functions that can be used within tuterm scripts (they are already documented in the man page

`evaluate`: print backslash-escaped characters properly

Right now when I run evaluate -e hella\bo I get

hella\bo

The -e option should behave the same as echo's -e option. In other words, I expect the command to print \b as backspace, ergo:

hello

Turn tuterm into a simple command interpreter (--interactive option)

It would be very useful if we could run tuterm as an interpreter for commands.

An idea for the implementation:

• Create a temporary rcfile that will load all tuterm shell-functions/variables/etc. It will basically just source the contents of /usr/bin/tuterm (or equivalent).
• Run an interactive bash subshell with the -i option that will use the created rcfile

This would make it easier to debug tuterm scripts, and it would make it possible to create tutorials for how to create tuterm scripts!!

Free-roam mode

It would be cool if we implemented a "free-roam" mode. In this mode, the user can run any commands, not just those that are expected by the tutorial. The user could enter/leave this mode by pressing a keybinding. (The leaving part might need some additional consideration)

This is useful if the user wants to pause the tutorial to explore the files created so far. Or experiment in any other way. After exiting the free-roam mode, the files should be restored to their original state, so the tutorial can proceed correctly where it left off.

I'm currently too busy to work on this so I would appreciate any help I can get.

Show tutorial progress

Add a progress indicator in the form current_command_index/total_commands.

The progress indicator could be displayed in the bottom right corner of the terminal. This would require knowledge of the terminal size. A solution that doesn't use additional dependencies (like curses and the like) is preferred.

Implementation note

Obtaining the total number of commands from a tutorial would require parsing the run shell function of a tuterm script once before running the tutorial. The cmdline and other functions should be aware that this first pass is in progress and do nothing except update a counter.

Export in a format compatible with cheat

I think it would be great if we could export tuterm scripts in a format suitable
for the cheat program. To enable exporting, the user should pass a
-x/--export option or similar.

Even then, not all commands should be exported, but only specific ones. I
suggest that we add a cmdline-export shell function along with an alias
C or cx. Only command lines specified using this function should be exported.

To export messages, they should be declared using message-export or
Message-export instead of the usual message and Message respectively.
Naturally, two new aliases would be added: mx and Mx. Alternatively,
exportable messages could be declared using the usual message/Message by
passing a -x option. In the latter approach, parsing the -x option could
prove painful, so I am inclined toward the former, which is also consistent
with the cmdline-export approach.

Note that even if a commandline or message are declared as exportable, they
should not be exported unless tuterm was called with the --export option.

The following question arises: should we allow a tuterm script to both be run
and exported at the same time? I think we should, but we should also add a
-r/--run option. If --export is absent, --run is not necessary, as the
script will run anyway. If the --export option is given, the script will run
only if --run is specified.

feature request: zsh support

If users have custom prompts, etc. configured on zsh, they'd be able to use that configuration with tuterm. While lack of zsh support is not a dealbreaker, it's definitely a nice-to-have.

Use custom shell for the user prompt

Currently the style of the prompt that shows which command a user has to run is set using the prompt shell function that the user can define in tuterm's configuration. It would be great if tuterm could be configured to use the user's shell instead.

This would allow for some very neat things, if the user's shell supports them:

• Autocompletion
• Syntax highlighting
• Shell keybindings
• Consistent prompt between the user's usual shell and tuterm

This doesn't strike me as an easy task. I tried doing this with unbuffer and expect but it doesn't seem to work. Granted, I do not know much about those programs. Currently, my thinking is that this has to be done using pseudoterminals. As far as I know there is not a bash way of working with pseudoterminals in this way, so I am leaning toward a python implementation. I have never done anything with pseudoterminals, so it will take me a while to implement this and I don't know when I'll get around to it. I would very much like this feature implemented because it is just awesome.

Some considerations:

• Should work across different shells (ideally all of them) with shell-specific hard-coding reduced to a minimum
• The command the user typed in must be extracted reliably from the shell's output so that tuterm can verify if it matches the expected command
• The shell must be aborted before it can run the command the user has entered

Packages for other distros

Currently there is only an AUR package, because I only use Arch Linux to a significant degree. I would be very grateful if someone created packages for the other popular distros/package managers. I don't really know how many people use tuterm, so I can't say if tackling this would be useful at the moment. You can also use this issue to request a package for your favorite distro.