Recently, I needed to create end-user documentation for a desktop application. Although screencasting is a possible alternative, I didn’t feel it was appropriate in this type of situation, where the end user really needs something printer-friendly to have in hand while using the application.

Although I did want the document to be highly visual, I wasn’t looking forward to the tedious process of capturing screens manually, one by one, then inserting them into a document, manually, one by one. I needed something that would streamline both of these processes so I could concentrate on making good documentation.

Fortunately, I found Screencasting with Linux by Chad Files which demonstrated how to use the flexibility of ImageMagick to capture screenshots in the background. What follows is an embellishment of Chad’s script that attempts to make it a little more convenient to use for the specific purpose I had in mind:

#!/bin/bash

trap bashtrap INT
bashtrap()
{
  convert *.miff %03d.png
  rm -r *.miff
  exit
}

NAME="screencaps"
if [ ! -d ${NAME} ]
then
  mkdir "${NAME}"
fi
cd "${NAME}"

echo 'Select the window you want to record.'
WINDOWID="`xwininfo -frame | grep Window\\ id: | awk '{ print $4}'`"

i=0
while [ 1 ]
do
   x=$[i+10000];
   import -silent -frame -window "${WINDOWID}" -screen "cap_${x/1/}.miff"
   i=$(( $i + 1 ))
done

First, I included a call to xwininfo directly in the script so this didn’t have to be a separate step in the process. When the script starts, I can select the window I want to capture by clicking on it, then the ImageMagick import command immediately begins an infinite loop capturing screenshots of that window.

I added the -silent option to make import run quietly, although you may want to leave that out yourself. I also added the -screen option which is necessary to capture things that get overlayed on the window such as expanded menus and pop-up dialog boxes.

Finally, I added the bashtrap() function so that when I want to stop the capturing process with CTRL-c, the program will automatically convert the native ImageMagick .miff files to .png files (in this case) before quitting. It does this using the more common ImageMagick command: convert. As you can see, all files end up in a subdirectory called ’screencaps’ wherever I ran the script.

I found that it was most effective to divide the functionality I wanted to document into small chunks and run this script separately for each one, moving slowly through the use of the software to make sure that each step gets captured. It takes a little time to save the screen captures and if you move too quickly, something important might get missed. After each run, I reviewed the thumbnails in my file viewer to make sure I captured everything I wanted, deleting anything extraneous. I then moved the final set of images to a separate folder and began the process again for the next feature I wanted to document.

I found this to be a pretty effective solution for the first problem I mentioned, but now I wanted a way to quickly add all my images as a batch to a document–in this case, OpenOffice Impress–where I would then add text and possibly other graphical elements explaining each image.

For this, I found the Impress Photo Album Creator by Russ Phillips, an OpenOffice macro that allows you to batch import all images in a folder into Impress, one image to a slide. In many cases, one image on a slide was exactly what I wanted, but even in those situations where I wanted multiple images on a slide, that’s easy enough to do within Impress and much easier than the normal multi-step process of adding single images to slides, so this approach seemed very reasonable.

Thanks to Chad Files’ article and several widely available open source tools, most of which were already on my computer, I was able to get the images I needed in a usable form pretty quickly, which allowed me to concentrate on my real goal, making good documentation.