% output=pdftex

%\def\Lit[#1]{\unskip\high{\in[lit:#1]}}
\def\Lit[#1]{[\in[lit:#1]]}

\setuphead[chapter][page=no,style=\bfc,after=\blank]
\setuphead[section][page=no,style=\bfb,after=\blank]
\setupwhitespace[big]

\usemodule[graph]

\starttext


\title[title]{Shifted bullets in graphs with \METAPOST}

\startnarrower
\startlines
Frans Goddijn
\type{frans@goddijn.com}
Karel H Wesseling
\type{k.h.wesseling@planet.nl}
\stoplines
\stopnarrower

\subject[abstract]{Abstract}

With \METAPOST\ fully integrated in \CONTEXT\ using this graphic 
language has become convenient. When we tried to use John Hobby's 
``Graph.mp'' package, however, it turned out to require extra
initializations and to produce unacceptable, shifted data graphs. 
Solutions to both problems are given. 


\section[introduction]{Introduction}

\METAPOST\ has become fun for these users when it became 
integrated in \CONTEXT, which was the trigger for this exercise, 
but the same can be done in \LATEX\ \Lit[popineau]. 
\METAPOST\ is known for the high precision of its graphics 
output and for its perfect scalability. Since this sounds 
promising also for the presentation of scientific data in 
graphical form we looked for a package that would ease the 
plotting of data files. This was found in the ``graph'' 
package written by John Hobby \Lit[hobby], the author of 
\METAPOST. In using this package we met with two problems: one, 
the lacking of proper initializations and two, the inaccurate 
placement of bullets at given coordinates. 


\section[initialization]{Initialization}

The inclusion of a \METAPOST\ graphics specification in a 
\CONTEXT\ document is simple and below is a code fragment that 
produces an XY||plot and places it as a graphic in this document. 

\starttyping
\startuseMPgraphic{plot}
  draw begingraph(3in,2in);
    gdraw "bdoffset.d";
    endgraph;
\stopuseMPgraphic
\midaligned{\useMPgraphic{plot}}
\stoptyping

\startuseMPgraphic{plot}
  draw begingraph(3in,2in);
    gdraw "bdoffset.d";
    endgraph;
\stopuseMPgraphic
\midaligned{\useMPgraphic{plot}}

With \type{\startuseMPgraphic{plot}} \CONTEXT\ is told that all 
instructions until the \type{\stopuseMPgraphic} are to be 
understood as \METAPOST||speak. \type{draw} is a \METAPOST\ 
instruction and \type{gdraw} is one included in Hobby's ``graph'' 
package which lives on top of \METAPOST. The file 
\type{bdoffset.d} is a small data file arranged as: 

\starttyping 
83 141 
93 118 
103 100 
113 86 
123 74 <EOF> 
\stoptyping 

This file must not have any extra empty lines (or all hell breaks 
loose). As a reminder, therefore, we placed an unnecessary 
\type{<EOF>} right after the final datum. The ``graph'' package 
accepts extra characters on a line, but no extra lines.

If you would try this program, the reason that it doesn't work 
right away is that the ``graph'' package has not been input. This 
would usually be accomplished by an instruction 

\starttyping 
\startMPinclusions input graph; \stopMPinclusions 
\stoptyping 

placed near the top between the start/stop of \type{useMPgraphic}.
Since extra initializations appeared also needed, however, Hans 
Hagen \footnote{of Pragma||ADE, the author of \CONTEXT.} wrote 
the following little module that must be input for use 
(\type{\usemodule[graph]}) in the preamble area of the source file, 
i.e. before \type{\starttext}: 

\starttyping
\forceMPTEXgraphictrue
\appendtoks
  initialize_numbers; % assure that pseudo typesetting is set up
  input graph;        % load the graph package
  Autoform:="@g";     % change the % template char into @
\to \MPinitializations
\stoptyping

Place these instructions in a file named \type{m-graph.tex} and 
the graph package is input, properly initialized, and ready for 
work. Note that the file \type{m-graph.tex} is input with 
\type{\usemodule[graph]}. When \CONTEXT\ reads 
\type{\usemodule} it inserts \type{m-} and appends \type{.tex} to 
the name automatically to find the correct file. Be sure to also 
place Hobby's \type{graph.mp} in the same directory or at least 
where it can be found by \CONTEXT. Using a rather recent version 
of \CONTEXT\ (see \about[references]) and this module, 
compile again, and the data plot shown above should result. 


\section[bullets]{Shifted bullets}

In the data plot the data pairs are plotted interconnected with 
straight lines. Since the curve is featureless the positions of 
the individual data points are barely discernable. Let us try to 
mark them more clearly. The manual for the ``graph'' package 
offers a solution. Simply replot the data but this time as 
bullets with the instruction 

\starttyping 
    gdraw "bdoffset.d" plot btex$\bullet$etex
\stoptyping

The \type{btex...etex} pair signifies to \METAPOST\ that the 
instructions in between should be interpreted as \TeX||typeset 
instructions. Thus, within the \CONTEXT\ document we first 
instruct \CONTEXT\ to look at a set of text lines as \METAPOST\ and 
within these lines \METAPOST\ is asked to consider some words as 
instructions to \TeX, which is why you need a recent version 
\CONTEXT. Still, the system works and the result is the following 
graphic: 

\startuseMPgraphic{plotbul}
  draw begingraph(3in,2in);
    gdraw "bdoffset.d";
    gdraw "bdoffset.d" plot btex$\bullet$etex;
    endgraph;
\stopuseMPgraphic
\midaligned{\useMPgraphic{plotbul}}

The dots don't fall on the line. Our first thought was that we 
did something wrong and our first action was to ask for help. Our 
second action was to check the graphic made with similar 
instructions in the ``graph'' manual. By tearing out the 
manual's page on which Fig.~2 is plotted and placing it over 
Fig.~1 such that the tick marks match we observed that equally in 
the manual the dots appear shifted towards the upper right. It 
turns out that \TeX\ positions each glyph with its reference 
point, not its midpoint, at the specified coordinates 
\Lit[knuth]. The reference point of the bullet is at the lower 
left of its box: \footnote{This can be observed in \CONTEXT\ by 
typing \type{\ruledhbox{$\bullet$}}} \ruledhbox{$\bullet$}. Thus, 
neither \TeX\ nor we did wrong but the instruction is wrong. 

The first solution suggested is to shift the bullet in opposite 
direction by replacing the \TeX\ instruction \type{$\bullet$} 
with:

\starttyping
  \kern-1mm\raisebox{-1mm}[0mm][0mm]{$\bullet$}
\stoptyping

which should shift the dot 1~mm to the left and 1~mm down, but 
doesn't. \TeX\ within \METAPOST\ within \CONTEXT\ forgets the 
original coordinates somewhere on the way and nothing is output. 
Since we hard||program shifts in mm for glyphs that could vary in 
dimension with the symbol specified it is not a general purpose 
solution either. Yet, it might have worked.

A solution which stays within \METAPOST\ came from the 
author of \METAFUN\ \Lit[hagen]. It declares and defines the 
bullet as a \METAPOST\ picture and plots the picture repeatedly 
at each coordinate specified. The full text of the example 
becomes: 

\starttyping 
\startuseMPgraphic{buldot} 
  picture Buldot; 
    Buldot:=image(draw origin withpen pencircle scaled 2mm;);
  draw begingraph(3in,2in);
    gdraw "other.d";
    gdraw "other.d" plot Buldot;
    endgraph;
\stopuseMPgraphic
\midaligned{\useMPgraphic{buldot}}
\stoptyping

\startuseMPgraphic{buldot}
  picture Buldot; 
    Buldot:=image(draw origin withpen pencircle scaled 2mm;);
  draw begingraph(3in,2in);
    gdraw "other.d";
    gdraw "other.d" plot Buldot;
    endgraph;
\stopuseMPgraphic
\midaligned{\useMPgraphic{buldot}}

The problem is solved. The `picture', of course, could be 
anything, like stars or squares or triangles or even doughnuts, 
as long as its midpoint is defined at the origin. And yes, we did 
change the data points to something more recognizable (a big 
dipper). 


\subject[acknowledgement]{Acknowledgement} 

We would like to express our appreciation to the respondents to 
our questions, they know who they are, that offered help and 
helped to a nice solution, all within the timespan of one 
workday. 


\subject[references]{References}

\startitemize[n,packed]
  \item[lit:popineau] Popineau F: \METAPOST\ pratique. Cahiers 
GUTenberg n\high{o}~41 |---| Novembre 2001.
  \item[lit:hobby] Hobby J D: Drawings graphs with MetaPost. 
\crlf \type{\texmf\doc\metapost\base\mpgraph.pdf}
  \item[lit:knuth] Knuth D E: The \TeX book (Chapter~11). Addison 
Wesley 1970. 
  \item[lit:hagen] Hagen H: Metafun. \crlf 
\type{\texmf\doc\context\manuals\metafun-p.pdf}
\stopitemize

The directory paths above are for the \TeX Live CDROM set, issue 
nr~7, June~2002, Volume~1. The \METAFUN\ manual and the \CONTEXT\ 
software are also available from \type{http://www.pragma-ade.com/} 

\stoptext