summaryrefslogtreecommitdiff
path: root/macros/latex209/contrib/labelfig/labelfig.doc
blob: 3915a20643095aa413cb82194b37704dfc3c409b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  %% 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{<the graphics insertion>}
 
Here <the graphics insertion> is what you would type to insert
the graphics object alone without the grid.  This must provide
for the space around it. For example <the graphics insertion>
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
   (<X-coordinate>*<X-coordinate>) <first label> \\
   .
   .
   .
   (<X-coordinate>*<X-coordinate>)  <last label> \\
  \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 <dimension>{\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}{<scale in mils>}\\
 
One could of course use standard syntax for \BoxedEPS.tex, namely
 
  (.1.1) \BoxedEPSF{MyFigure scaled <scale in mils>}\\
 
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