%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% LabelFig.doc
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%%%% LabelFig.tex FOR LABELLING TEX FIGURE INSERTS %%%%%
%%
%% DOCUMENTATION
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
by Laurent Siebenmann
lcs@matups.matups.fr
VERSIONS: July 1991
INTRODUCTION
This small labelling package is intended for TeX users who
rely on non-TeX sources for for their graphics inserts. It
provides means for adding TeX labels to such inserts with a
minimum of fuss. For most labels I find it most convenient to
rely on non-TeX sources, and I only occasionally use these
macros. Typical occasions when the need seems to arise:
(a) the graphics program lacks certain exotic or complex
mathematical symbols
(b) the very highest typographical quality is wanted for the
labels.
Given a fast preview you may find that this package
provides an agreeable paste-up environment; see extra
applications at end.
BASIC INSTRUCTIONS
After reading in the macro file using
\input LabelFig.tex
preview or proof your figure with a coordinate grid printed on
top, by typing the following:
\ShowGrid % without this the grid is absent
\AffixLabels{}
Here is what you would type to insert
the graphics object alone without the grid. This must provide
for the space around it. For example
might well be \BoxedEPSF{MyFigure scaled 700} using the
BoxedEPS.tex package (from same source); this provides a TeX box
containing the encapsulated PostScript insert specified by the
file MyFigure. \AffixLabels{...} provides the grid (supposing
\ShowGrid is present) and later, once you have specified labels
using the grid, it will "stick on" the labels.
The grid is a sort of (usually elongated) checkerboard of
ten rows and ten columns and its (internal) partitions are
numbered .1, ... ,.9 both horizontally (X-coordinate running
left to right) and vertically (Y-coordinate running bottom to
top). Thus the points enclosed by the grid correspond to the
points of the unit square in the cartesian "X-Y" plane, the lower
left corner corresponding to the origin (0,0). By extrapolation,
the full page corresponds to a larger rectangle in the plane.
These coordinates serve to position labels as follows.
Before the \AffixLabels{...} command type label specifications:
\SetLabels
(*) \\
.
.
.
(*) \\
\endSetLabels
Each row specifies one label and is terminated by \\. In each
row the position indicator comes first; it is written as a
standard cartesian point except that the X- and Y- coordinates
are separated by * rather than a comma. There are no dimension
units to specify (the unit is the grid itself).
Normally, this point specifies where the middle of the
baseline of the label will be located. However if you precede
the point by \L [or \R] the left [or right] edge of the baseline
will be located there. Similarly you may also precede the point
by \T or \B to vertically align the top or bottom of the label box
at the specified point. Thus, in all there are nine standard
positions of the label with respect to the insertion point ---
corresponding to the eight principal points of the compas plus
its center.
\L\T \T \R\T
\L 0 \R
\L\B \B \R\B
Remember that you are responsible for preventing labels
from overlapping.
You are also responsible for the label typography
including size and style; a label is just about anything that can
be put in a TeX box. For example, it is quite possible to treat
multiline captions as labels (see below). Note that spaces at the
beginning and end of labels will normally be suppressed; if you
want them you must protect them with TeX braces.
Beware of changing the grid inadvertently after the labels
have been positioned. For example, correcting the bounding box
of a PostScript graphics object can foul up the labels by
changing the coordinate grid to which the labels are attached.
Even a change of scaling can be disruptive, although modest
changes are often well tolerated. Make it a rule to carefully
size and position and the graphics object before using
LabelFig.tex to attach labels.
Here is an artificial but self-contained test which uses
TeX rules to make a graphics object.
TEST
Do not skip this!
%%%%%%%%%%%%%%%%%% --- cut
%%%%%% useful ad hoc macros
%%% \FrameIt#1 frames what it finds in #1
\def\FrameIt#1{\hbox{\vrule$\vcenter {\hrule\kern3pt%
\hbox {\kern3pt #1\kern3pt}%
\kern3pt\hrule}$\vrule}}
%%% \Caption#1#2 gives framed caption width #1
%% containing #2
\def\Caption#1#2{\FrameIt{%
\vtop {\hsize=#1\relax \parindent=0pt
\leftskip=0pt plus10pt\rightskip=0pt plus10pt
\parfillskip=0pt
\lineskip=1pt\baselineskip=0pt
#2}}}
%%% the test proper begins
\SetLabels
(.5*.2) $\cdot\,\zeta$\\
(.9*-.10) $\xi$\\
\R(-.03*.9) $\eta$\\
\T(.5*.9) \Caption{70pt}{%
\it The norm of
$g(\xi+i\eta)$ is indicated on
contours of this invisible surface.}\\
\endSetLabels
\ShowGrid % this makes the grid visible
\AffixLabels{\hbox{\vrule\vbox to 100pt{\vfil
\hbox to100pt{\hfil}\hrule}}}
\end
%%%%%%%%%%%%%%%%%% --- cut
MORE EXOTIC APPLICATIONS
The grid of LabelFig.tex is analogous to a light-table in
classical page makeup with wax or latex glue. In principle you
can use it compose any page from its indivisible parts. This
even has some of the artisanal charm of classical paste-up
provided you have a fast screen preview to make the process
"interactive".
In practice LabelFig.tex is a tool for nonstandard jobs.
Here are a few going beyond the labelling already discussed.
(I) GRAPHICS INTEGRATION.
This is accomplished by treating the imported graphics
objects as labels. The underlying graphics object is then
typically an empty \vbox to {\vfill} in a TeX
\midinsert...\endinsert construction. A label line
might be of the form
(.1*.1) \special{... MyFigure ...}\\
The exact form of the special command varies from driver to
driver. However, in the case of encapsulated PostScript graphics
(EPSF norn), by relying on \BoxedEPS.tex one can have the
following standard syntax (independant of driver (see
\BoxedEPS.tex for details.
(.1.1) \EPSFSpecial{MyFigure}{}\\
One could of course use standard syntax for \BoxedEPS.tex, namely
(.1.1) \BoxedEPSF{MyFigure scaled }\\
but that would be slow since it requires TeX to read the
PostScript file and use many complex macros.
Similarly for graphics of the Macintosh PICT norm ---
using \BoxedArt.tex (same sources) in place of \BoxedEPS.tex.
This approach to integration is to be recommended when one
is making up a composite graphics object.
(II) COMMUTATIVE DIAGRAM ENHANCEMENT
Commutative diagrams or arrays of mathematical objects
connected by arrows of various sorts are common in mathematics.
The mathematical objects require the use of TeX. Recently
TeX acquired a good collection of arrows of all slopes --- that
of LamSTeX --- plus pwerful macros to build the diagrams.
However, even the LamSTeX collection is often inadequate;
it lacks for example double shafted arrows, dotted arrows and
curved arrows. Fortunately it is possible to produce such arrows
on an individual basis using sophisticated graphics programs such
as Illustrator and AldusFreehand (both serving the EPSF norm).
(Since the creation of each new arrow is a work of love, you
probably want to limit the number of arrows by using LamSTeX for
most arrows. Incidentally any texpert can quickly adapt the the
modest sized commutative diagram module of LamSTeX to work with
AmSTeX.)
LabelFig.tex can then be given the role of inserting the
hand-made arrows into the commutative diagram much as it inserts
a "label" into a graphics inclusion. The grid is normally laid
down on the TeX part of the commutative diagram, or some
convenient subobject therein (remember that one can use
coordinate values outside the grid). The latter choice may offer
greater stability if the diagram is altered.
(III) ...
CONCLUDING REMARKS.
Ingenuity pays off in exploiting LabelFig.tex. One can
mix graphics and typography quite freely. LabelFig.tex is good
for freeform or overlapping arrangements, while BoxedEPS.tex (or
BoxedArt.tex) is best for regimented non-overlapping
arrangements --- and the two can be combined.
There are however potential pitfalls. Neither
LabelFig.tex nor BoxedEPS.tex has been tested under extreme
conditions. I expect problems will quickly occur if their
procedures are indiscriminately nested. For BoxedEPSF.tex (not
LabelFig.tex) there is a precise cause for worry, namely many of
its variables are "global", which means that TeX braces will not
provide the protection one might expect.
Address for bugs and other feedback:
Laurent Siebenmann
lcs@matups.matups.fr