Table Of Contents

This Page

How to write an article

Wordish is a script which executes a shell session parsed from a documentation in the restructured text [1] format, then tests and builds a report of the execution. To mark up shell code in an article, wordish uses the custom directive sourcecode, with the rquired argument sh. When presented with an article:

  1. wordish filters out the text which is not marked with sourcecode,
  2. then, separates the blocks of shell codes between commands and outputs:
    1. wordish consumes the prompt, parses for the newline which ends command,
    2. then parses for the prompt which ends the output,


.. sourcecode:: sh

   ~$ echo "hello world"   # Mmmh, insightful comment
   hello world

This simply renders like:

~$ echo "hello world"   # Mmmh, insightful comment
hello world

The command starts after the prompt (“~$ “) and continues until the first newline is found in the source code block. Here, it is just after the word comment. The command is echo "hello world" # Mmmh, insightful comment The output is the text block found until the next prompt: this is hello world. There are two possible prompts: ~$, and ~#. Both are required to be followed by a space are are treated the same.

Note: the newlines which are nested in curly brackets or parentheses are not interpreted as an end of command character. Shells do the same: curly brackets are used to define functions and parentheses makes the nested command to be interpreted in a subprocess shell. The two following examples from the introduction make it clear:

~$ (
echo $((1+1)) )

~$ sum () {
echo $(( $1 + $2 ))

The first command is echo $((1+1)) in a subproces, and it’s output is 2. The second command is the definition of a function named sum and has no output. Defining functions sometimes clarify the intent in subsequent uses of the function. For functions to be re-used, the state of the shell must be kept between each snippets. wordish keep a connection with the same shell subprocess (bash is used) for the duration of the article.

~$ sum 42 58

See how the output is obviously incorrect? we will see later how this is reported.

When the output can not be completely predicted, such as when displaying $RANDOM, or displaying the size of a partitions in bytes, there is a handy wildcard pattern which can be used: .... It matches everything like .* in regexp [2].

~$ echo "a random number: " $RANDOM

One last thing, if a command does not exit gracefully, wordish precautiously aborts, refusing to execute commands on the system under test which is in an undefined state. wordish displays the remaining unexecuted commands.

~$ What have the Romans ever done for us
aqueduct? roads? wine !

~$ echo "Bye bye"
Bye bye

This introduction is embedded in the wordish module as the docstring. Just run wordish with no argument to get the example report of this article:

~$ python -m wordish
Trying:      echo "hello world"   # Mmmh, insightful comment...
Expecting:   hello world

Trying:      (
echo $((1+1)) )
Expecting:   2

Trying:      sum () {
echo $(( $1 + $2 ))

Trying:      sum 42 58
Expecting:   3
Failed, got: 100, 0

Trying:      echo "a random number: " $RANDOM
Expecting:   ...

Trying:      What have the Romans ever done for us
Expecting:   aqueduct? roads? wine !
Failed, got: /bin/bash: line 19: What: command not found, 127

Command aborted, bailing out
Untested command:
     echo "Bye bye"
     python -m wordish
6 tests found. 
4 tests passed, 2 tests failed.

There is another example real world article which is also included in the sources distribution, and tested before each release. This is the article which prompted the need for the development of wordish.

[1]This syntax can be seen as light and readable version of html or latex, and was designed with the experience of existing Wiki syntaxes. The Sphinx project has a nice introduction on rst, the reference documentation is here.
[2]Regexp are not directly used so that the various special regexp characters do not need to be escaped.

Debugging an article

When debugging an article, repeatedly executing half of the commands, I have found it handy to:

  • write a cleanup script which resets the system under test to the initial state,
  • use the false shell command in the articles, to explicitly require the execution to bail out at a certain point in the article,
  • Use a log file with python -m wordish my_article.rst | tee my_article.log


Wordish is available on the Python package index and can be installed [3] with:

sudo pip wordish

If you want to separate Python module from outside the debian or rpm repositories, from the Python modules installed managed by your distribution, you can use virtualenv:

virtualenv wordish_env && cd wordish_env
source ./bin/activate
pip wordish

At this point the wordish module is available in the Python path. You can test it with:

python -m wordish

This executes wordish on its docstrings, which is written in restructured text.

[3]pip and distribute are the new black: pip takes care of fetching packages and dependencies while distribute takes care of the definition and the building of the package. They aims replace and be backward compatible with easy_install and setuptools.