%%% ==================================================================== %%% @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}