Search code examples
htmlshellmarkdowndocumentation-generation

I need to document a command and its output side-by-side

I'm currently developing a set of shell functions and I want to document its output.

I remember there's a command that generates a basic outline in html (and markdown?) where on the first column you've got the command and it output on the right. A crude example:

ls -a1  | .
        | ..
        | a_dir/
        | a_file
        | another file
        |
ps      |   PID TTY          TIME CMD
        | 2920 pts/2    00:00:00 bash
        | 3015 pts/2    00:00:00 ps

I would like to know a program that given a set of commands will generate something similar to the previous example, whether it is HTML, markdown, or anything similar.

Solution

  • One way is to use the script utility

    SCRIPT(1)                        User Commands                       SCRIPT(1)

NAME
     script — make typescript of terminal session

SYNOPSIS
     script [-a] [-c command] [-e] [-f] [-q] [-t[=file]] [-V] [-h] [file]

DESCRIPTION
     script makes a typescript of everything printed on your terminal.  It is
     useful for students who need a hardcopy record of an interactive session
     as proof of an assignment, as the typescript file can be printed out
     later with lpr(1).

    There is also a python-utility available, called shelllogger

    ShellLogger captures all user interactions with a shell. It is intended to be used for software engineering researchers who are interested in inferring programmer behavior from data that can be captured automatically during a programming session. It is similar to the Unix 'script' program, but provides additional features such as XML output, distinguishing user input from system output and tracking the user's current directory.

    https://code.google.com/p/shelllogger/