0.

This tutorial describes how to get image figures from
the ASCII drawings (and sometimes Unicode ditto) that
you produce with industrial ease in Emacs.

The reasoning is: Emacs already looks good. You have
made sure of it. So when you want to export the
figure, or import it somewhere else, why not make it
look exactly as it already is? Ironically, Emacs has
thus become a nice WYSIWYG editor :)

If you have drawn a bunch of such figures, you will
have encountered the problem how to get them into for
example a LaTeX generated PDF or an HTML web page.
There are many ways of including them *as text*, but
that always comes with surprises and side-effects,
which (for once) actually *are* undesirable! ;)

If you have had this problem several times... - wait,
you mean to say you *never* had this problem?
What's wrong with you?! Anyway, here is how to do it
from an Emacs instance that runs in a Linux VT.

All data, and pictures, as well as this document, can
be found at

    http://user.it.uu.se/~embe8573/figure

Now let's begin...


                          1.

Draw the figure. Here is an example figure with ASCII
as well as Unicode chars. (As a parenthesis, to turn
ASCII figures into Unicode, use ascii-art-to-unicode
which is in ELPA.)

             critical      best-effort
             ┌───────────┬───────────┐
             │ ↑ group 1 │           │
    CPU time │ ·         │           │
interference │ ·         │   BE SW   │
             │ ·         │           │
             │ ↓ group n │           │
             └───────────┴───────────┘
                   ←·················
                    DRAM interference

Put the figure in the top left corner so it will be
easy to determine the crop parameter values later on.

Note: Throughout this tutorial, check out the current
stage of transformation by inspecting the images
linked between curly brackets - like this, for the
above figure:


{ http://user.it.uu.se/~embe8573/figure/isolation.txt }


                          2.

Make a screenshot of the current VT with fbgrab(1).
Here is an Elisp wrapper. Enter "isolation" as the
name - the PNG extension (.png) is appended by
default, and for good reason: that's exactly what
it is.

    (defun dump (file)
      (interactive "s Description: ")
      (message nil)
      (shell-command (format "fbgrab ~/%s.png" file)))


{ http://user.it.uu.se/~embe8573/figure/isolation.png }


                          3.

Now compute the width and height in pixels. The size
of a single char is often specified in pixels, like
this - "widthxheight" - e.g.

    FONTSIZE="12x24"

to be found in the file

    /etc/default/console-setup

If not, find out some other way.

Second, count the number of chars that the figure
covers in x and y, or width and height. This can be
done by moving point to the outskirts of the figure,
add some margin, and then read the data in the
mode line.

Now compute the width and height of your figure in
pixels by multiplying the number of chars required
with the dimensions of a single char:

    pixel width  = 40 chars * 12 pixels/char = 480 pixels
    pixel height = 10 lines * 24 pixels/line = 240 pixels

To crop the picture, in the shell, do:

    mogrify -crop 480x240+0+0 -negate -monochrome isolation.png

Or, to create a new file, so to keep the old:

    convert [same settings as above] isolation.png isolation-figure.png

'-negate' inverts the colors, then '-monochrome' turns
everything into a black and white image - suitable to
be included in PDF documents and the like. The order
of the operations are important!


{ http://user.it.uu.se/~embe8573/figure/isolation-figure.png }


                          5.

We're done! Put isolation-figure.png in the right
place. Now we have the figure to be included in HTML
web pages, LaTeX PDFs, and so on. To conclude, as an
example, in LaTeX, it can be included like this:

    \index{isolation \emph{fig.}} % optional stuff
    \vspace{\baselineskip}
    \begin{center}
      \includegraphics[width=1.0\textwidth]{figures/isolation-figure.png}
      \textbf{Isolate us! Resource sharing interference.}
    \end{center}


{ http://user.it.uu.se/~embe8573/figure/isolation.pdf }