+=head2 USING REMOTE CONTROL ROBUSTLY FROM SHELL SCRIPTS
+
+From Bash, you can use the following code which creates a guestfish
+instance, correctly quotes the command line, handles failure to start,
+and cleans up guestfish when the script exits:
+
+ #!/bin/bash -
+
+ set -e
+
+ guestfish[0]="guestfish"
+ guestfish[1]="--listen"
+ guestfish[2]="--ro"
+ guestfish[3]="-a"
+ guestfish[4]="disk.img"
+
+ GUESTFISH_PID=
+ eval $("${guestfish[@]}")
+ if [ -z "$GUESTFISH_PID" ]; then
+ echo "error: guestfish didn't start up, see error messages above"
+ exit 1
+ fi
+
+ cleanup_guestfish ()
+ {
+ guestfish --remote -- exit >/dev/null 2>&1 ||:
+ }
+ trap cleanup_guestfish EXIT ERR
+
+ guestfish --remote -- run
+
+ # ...
+
+=head2 REMOTE CONTROL RUN COMMAND HANGING
+
+Using the C<run> (or C<launch>) command remotely in a command
+substitution context hangs, ie. don't do (note the backquotes):
+
+ a=`guestfish --remote run`
+
+Since the C<run> command produces no output on stdout, this is not
+useful anyway. For further information see
+L<https://bugzilla.redhat.com/show_bug.cgi?id=592910>.
+