%%% ====================================================================
%%%  @LaTeX-file{
%%%     author          = "Alan Jeffrey",
%%%     version         = "1.1",
%%%     date            = "02 June 1992",
%%%     time            = "13:45:34 BST",
%%%     filename        = "diagramf.tex",
%%%     address         = "School of Cognitive and Computing Sciences
%%%                        University of Sussex
%%%                        Brighton BN1 9QH
%%%                        UK",
%%%     telephone       = "+44 273 606755 x 3238",
%%%     FAX             = "+44 273 678188",
%%%     checksum        = "57849 301 1353 10551",
%%%     email           = "alanje@cogs.sussex.ac.uk",
%%%     codetable       = "ISO/ASCII",
%%%     keywords        = "diagrams, metafont",
%%%     supported       = "yes",
%%%     abstract        = "This is a metafont program which provides
%%%                        commands for setting labels in TeX.",
%%%     docstring       = "This is the documentation for the diagramf
%%%                        package which interfaces TeX and metafont.
%%%
%%%                        Copyright 1992 Alan Jeffrey.
%%%
%%%                        The checksum field above contains a CRC-16
%%%                        checksum as the first value, followed by the
%%%                        equivalent of the standard UNIX wc (word
%%%                        count) utility output of lines, words, and
%%%                        characters.  This is produced by Robert
%%%                        Solovay's checksum utility.",
%%%     package         = "diagramf",
%%%     dependencies    = "diagramf.mf diagramf.sty dmfexmpl.mf
%%%                        arrows.mf ltugboat.sty tugboat.com",
%%%     maintainer      = "Jeremy Gibbons",
%%%     address-maintainer = "Department of Computer Science
%%%                        University of Aukland
%%%                        Private Bag
%%%                        Aukland
%%%                        New Zealand",
%%%     email-maintainer = "jeremy@cs.aukuni.ac.nz",
%%%  }
%%% ====================================================================
%%%
%%% 25 Oct 1990, v1.0: Released version 1.0.
%%%
%%% 2 Jun 1992, v1.1: Added standard headers, and replaced example.mf
%%%    with dmfexmpl.mf.

% Permission is granted to Tugboat to reproduce this.

% A keyboard check:
%
%     @ # $ % ^ & * ~   at hash dollar percent caret ampersand asterisk tilde
%     : ; , .           colon semicolon comma period
%     ? !               question-mark exclamation-mark
%     " ' `             double-quote apostrophe back-quote
%     ( ) { } [ ]       parentheses braces square-brackets
%     - + = / \         minus plus equals forward-slash backslash
%     _ | < >           underscore vertical-bar less-than greater-than

\documentstyle[diagramf]{ltugboat}

\title{Labelled diagrams in \MF}

\author{Alan Jeffrey}

%\address{Programming Research Group\\
%         Oxford University\\
%         11 Keble Road\\
%         Oxford OX1 3QD}
%
%\netaddress{Alan.Jeffrey@prg.ox.ac.uk}

\address{School of Cognitive and Computing Sciences\\
   University of Sussex\\
   Brighton BN1 9QH\\
   UK}

\netaddress{alanje@cogs.sussex.ac.uk}

\signature
   {\medskip
    \signaturemark
    \theauthor{1}\\
    \theaddress{1}\\
    \thenetaddress{1}\\
    \medskip
    \copyright\ 1990 Alan Jeffrey\\
}

% The current version of ltugboat.sty uses (and doesn't define)
% \tensl.

\font\tensl cmsl10

%\typeout{}
%\typeout{I've added a copyright notice to the signature, as TUGboat}
%\typeout{seems not to have one.}

\diagramfile{dmfexmpl}

\bgroup
\catcode`\{=11 \catcode`\}=11 \catcode`\[=1 \catcode`\]=2
\gdef\braces#1[{#1}]
\egroup

\begin{document}

\maketitle

\section{Diagrams in \MF}

In \TUB~11(4),
%\typeout{}%
%\typeout{I've made a reference to Alan's article (without reading}%
%\typeout{it of course!) --- have I got the reference right?}%
Alan Hoenig described a method of producing diagrams in \MF\ with
labels provided by \TeX.  His method relied on passing information
around via font dimensions.  This is a standard method of passing
information from \MF\ to \TeX, but it has some drawbacks:
\begin{itemize}
\item There are only a limited number of font dimensions available,
      and each label uses up two of them.

\item As \MF\ can only communicate with \TeX\ via font dimensions,
      each label has to be assigned a font dimension, and it is difficult
      for the correspondence between font dimensions and labels to be kept
      automatically.

\item Since \TeX\ is providing the labels, and \MF\ is providing the
      diagrams, the diagrams have to be kept in a different file from the
      labels.

\item There is no communication between \TeX\ and \MF, so \MF\ cannot
      change the diagram depending on the size and shape of the labels.
%\typeout{}%
%\typeout{At least, I think this is true---I'm having to base this on}%
%\typeout{Alan's talk at Cork.}%
      This is rather inconvenient for diagrams such as
      \begin{center}
          \diagramf{1}
      \end{center}
      where the shape of the ovals depends on the size of the contents.
\end{itemize}
Fired with enthusiasm by Alan's talk at the European \TUG\ meeting, I
stole the best of his ideas, and slightly modified them to produce a
simple \MF--\TeX\ interface.  This allows \TeX\ code to be embedded
within a \MF\ program, for example
\begin{verbatim}
begindiagram(2,30pt#,7pt#,2pt#);
    hboxes(0);
    pickup pencircle scaled 0.4pt;
    .5[hboxl0,hboxr0] = (.5w,0);
    draw hboxbl0..hboxtl0
             ---hboxtr0..hboxbr0
             ---cycle;
    setbox0 "$g \circ h$";
enddiagram;
\end{verbatim}
produces the diagram \diagramf{2}.
The new facilities used are:
\begin{description}
\item[\tt begindiagram(2,30pt\#,7pt\#,2pt\#)]
     starts off diagram~2,
     which is 30pt wide, 7pt tall and 2pt
     deep.

\item[\tt hboxes(0)]
     says that the only label we'll be using is number~0.
     This has a similar syntax to \verb|labels|, so you can say
     \verb|hboxes(1,2,7)| or \verb|hboxes(3 upto 9)|.

\item[\tt hboxl0]
     is the left point of label number~0, at the
     baseline.  Similarly, {\tt hboxbl0} is the bottom left, {\tt
     hboxtr0} is top right, and so on.  In this example, these points
     are
     \begin{center}
         \diagramf{3}
     \end{center}
     You can also use the numeric variables
     {\tt hboxwd0}, {\tt hboxht0} and
     {\tt hboxdp0} which are the width, height and depth of label~0,
     and \verb|hboxwd#0|, \verb|hboxht#0| and \verb|hboxdp#0| which are their
     sharp equivalents.

\item[\tt setbox0 "\$g \string\circ\ h\$"]
     sets label number~0 to be $g \circ h$.

\item[\tt enddiagram]
     finishes it all off.
\end{description}
The rest of the diagram is standard \MF.
Within a \TeX\ document you can use
\begin{description}
\item[\tt\string\diagramfile\braces{dmfexmpl}] to load in the diagrams kept in
{\tt dmfexmpl.mf},

\item[\tt\string\diagramf\braces{2}] to get the second diagram, and

\item[\tt\string\everylabel] which is a token register added to every
label, in the same fashion as \verb|\everymath|.  It should be set
{\em before\/} saying \verb|\diagramfile|.
\end{description}
These commands behave well inside groups, so if you say
\begin{verbatim}
\diagramfile{foo}
{\diagramfile{baz}\diagramf{1}}
\diagramf{2}
\end{verbatim}
you get the first diagram from {\tt baz} and the second diagram from
{\tt foo}.

\section{How it all works}

In the \verb|diagramf| package, \TeX\ and \MF\ communicate by
auxiliary files, in a similar fashion to the {\sf MG} \TeX-\PS\
interface (`Problems on the \TeX/\PS/graphics interface', \TUB~11(3)).

When you run \MF\ on \verb|dmfexmpl.mf| it reads in
\verb|dmfexmpl.dim|, which specifies the dimensions of all the boxes.
In our example, part of \verb|dmfexmpl.dim| is
\begin{verbatim}
wd#[2][0] := 20.3344pt#;
ht#[2][0] := 6.94444pt#;
dp#[2][0] := 1.94444pt#;
\end{verbatim}
So, in diagram~2, label~0 has width~20.3344pt,
height~6.94444pt and depth~1.94444pt.  From this, \MF\ calculates
where to put each label, and outputs a \verb|.dia| file, containing
\TeX\ code.  For example \verb|dmfexmpl.dia|
contains\footnote{Actually, each line ends with {\tt\percent\space diagramf}.}:
\begin{verbatim}
\newdiagram{2}
\diagramlabel{0}{4.88908pt}{0pt}
$g \circ h$
\enddiagramlabel
\diagramchar{2}
\endnewdiagram
\end{verbatim}
This tells \TeX\ that diagram number~2 contains
label~0 at coordinates $\rm(4.88908pt,0pt)$ consisting of
\verb|$g \circ h$|.  The diagram is character number~2 in the {\tt
dmfexmpl} font.

Similarly, when \TeX\ encounters the instruction
\verb|\diagramfile{dmfexmpl}| it loads in \verb|dmfexmpl.dia| and produces
\verb|dmfexmpl.dim|.  And so we can have our \MF\ cake and eat it in
\TeX.

Well, almost.  Unfortunately for all these grand ideas, \MF\ has {\em
no\/} file-handling capabilities at all!  The only files \MF\ generates are
the \verb|.tfm|, \verb|.gf| and \verb|.log| files.

This is rather annoying, but fortunately we can steal an idea from
Section~7 of the Dirty Tricks appendix in \MFB.  There, Knuth uses the
\verb|.log| file as a means of communicating between \MF\ jobs.
Similarly, we use the \verb|.log| file as a way of sending messages to
\TeX.  Our \verb|texoutput| macro is defined
\begin{verbatim}
def texoutput text t =
    for s = t:
        message s & "% diagramf";
    endfor
    message ""
enddef;
\end{verbatim}
So \verb|texoutput "Fred", "Ethel"| produces the output
\begin{verbatim}
Fred% diagramf
Ethel% diagramf
\end{verbatim}
You can then use your favourite file-handling utility to filter the
\verb|.log| file, keeping only the lines containing \verb|% diagramf|.  On
my UNIX set-up, for example, I have an alias \verb|diagramf foo|
which expands out to
\begin{verbatim}
touch foo.dim
mf foo
grep "% diagramf" foo.log > foo.dia
echo Labels written on foo.dia.
\end{verbatim}
The crucial line in this is the \verb|grep|, which takes all the lines
from \verb|foo.log| containing \verb|% diagramf| and puts them in
\verb|foo.dia|.

And so we've achieved labelled diagrams in \MF.  The {\tt diagramf}
package is free software, and is available from the Aston archive.
% Or at least it will be by the time this article appears.

\section{Acknowledgements}

The inspiration, and many of the original ideas, for this article came
from Alan Hoenig's talk on the same subject at Cork.  I'd also like to
thank Jeremy Gibbons and Damian Cugley for comments, advice and
allowing me to bounce ideas off them.

\makesignature

\end{document}