Debian Codegraph @

texmf-dist/doc/latex/pinlabel/src/pinlabdoc.tex

raw
1
2 \documentclass[microtype]{gtpart}
3 \usepackage{pinlabel}
4
5
6 %%% running feet for documentation files
7 \makeatletter
8 \def\@oddfoot{\ifnum\count0=1
9 \small\copyright\ Copyright 2006--11 Mathematical Sciences
10 Publishers\hfill\else
11 \small\it Mathematical Sciences Publishers: documentation\hfill\fi}
12 \let\@evenfoot\@oddfoot
13 \makeatother
14
15 %%%% verbatim macro
16
17 \def\dq{"} % define a code for " so it can be used when \verb is on
18 \def\ttq{{\tt\dq}} % code for " in cmtt
19 %
20 \def\verb{\catcode`\"=\active} % The main
21 \def\brev{\catcode`\"=12} % switches.
22 %
23 \brev % Prime switches and
24 \verb % switch on.
25 %
26 {\obeyspaces\gdef {\ }}
27 {\catcode`\`=\active\gdef`{\relax\lq}}
28 \def"{%
29 \begingroup\baselineskip=12pt\def\par{\leavevmode\endgraf}%
30 \tt\obeylines\obeyspaces\parskip=0pt\parindent=0pt%
31 \catcode`\$=12\catcode`\&=12\catcode`\^=12\catcode`\#=12%
32 \catcode`\_=12\catcode`\~=12%
33 \catcode`\{=12\catcode`\}=12\catcode`\%=12\catcode`\\=12%
34 \catcode`\`=\active\let"\endgroup}
35 %
36 \brev % Finally switch the macro off (for safety)
37
38
39 \def\cross{\vrule height 0.2pt depth 0.2pt width 12pt\kern -6.2pt
40 \vrule height 6pt width 0.4pt depth 6pt}
41
42 %%%% metadata
43
44 \title[{\tt pinlabel}\qua A \TeX\ labelling package]{\texttt{pinlabel}\qua A \TeX\ labelling package}
45
46 \author{Colin Rourke}
47 \givenname{Colin}
48 \surname{Rourke}
49 \address{Mathematical Sciences Publishers\\
50 Department of Mathematics\\\newline
51 University of California\\
52 CA 94720-3840\\USA}
53 \email{[email protected]}
54 \urladdr{http://www.mathscipub.org}
55
56 \volumenumber{1}
57 \issuenumber{}
58 \publicationyear{2006}
59 \papernumber{}
60 \startpage{1}
61 \endpage{15}
62
63 \doi{}
64 \MR{}
65 \Zbl{}
66
67 \keyword{manual}
68 \keyword{labelling}
69 \keyword{diagram}
70 \keyword{figure}
71 \subject{primary}{msc2000}{68-01}
72 \subject{secondary}{msc2000}{68N01}
73
74 \received{}
75 \revised{}
76 \accepted{}
77 \published{2006}
78 \publishedonline{2006}
79 \proposed{}
80 \seconded{}
81 \corresponding{}
82 \editor{}
83 \version{}
84
85 \arxivreference{}
86 \arxivpassword{}
87
88 \begin{document}
89
90 \begin{asciiabstract}
91 pinlabel is a labelling package designed for attaching perfectly
92 formatted TeX labels to figures and diagrams in both eps and pdf
93 formats. It is a tool for use by both authors and editors and can be
94 used both for labelling a new diagram and for relabelling an existing
95 diagram. It is the recommended package for (re)labelling diagrams or
96 figures in papers intended for publication by Mathematical Sciences
97 Publishers. The main features of the package are that it uses
98 coordinates read from the diagram in ghostview (or gv) and that labels
99 are placed with automatic and consistent spacing from the object that
100 they are labelling. Many adjustment and positioning options are
101 provided. The end result is a package which is easy and quick to use
102 and which provides accurate and eye-pleasing labelling, completely
103 consistent with the text.
104 \end{asciiabstract}
105
106 \begin{abstract}
107 {\tt pinlabel} is a labelling package designed for attaching perfectly
108 formatted \TeX\ labels to figures and diagrams in both eps and pdf
109 formats. It is a tool for use by both authors and editors and can be
110 used both for labelling a new diagram and for relabelling an existing
111 diagram. It is the recommended package for (re)labelling diagrams or
112 figures in papers intended for publication by Mathematical Sciences
113 Publishers. The main features of the package are that it uses
114 coordinates read from the diagram in {\tt GhostView} (or {\tt gv}) and
115 that labels are placed with automatic and consistent spacing from the
116 object that they are labelling. Many adjustment and positioning
117 options are provided. The end result is a package which is easy and
118 quick to use and which provides accurate and eye-pleasing labelling,
119 completely consistent with the text.
120
121 For a comparison of {\tt pinlabel} with other labelling packages which
122 allow one to attach \TeX\ labels, see \fullref{sec:why}.
123
124 \end{abstract}
125
126 \maketitle
127 \verb %%% switch on verbatim
128
129
130 \section{Essential ingredients}\label{sec:ess}
131
132
133 \subsection{Input files}
134
135 To use "pinlabel" you need just one file "pinlabel.sty".
136
137 If you are using "latex", then you need only add the line
138 "\usepackage{pinlabel}" near the top of your file; if using plain
139 "tex" then add the line "\input pinlabel.sty" instead.
140
141 Occasionally there will be a paragraph labelled {\small{\bf
142 Smallprint}}, which can safely be omitted on first reading, but which
143 you may need to read if problems arise. There is a whole section of
144 smallprint near the end.
145
146
147 {\small{\bf Smallprint}\qua The package calls a standard latex package
148 "graphicx.sty" which all recent "tex" installations will have
149 available, so you should not have to worry about this. If you are
150 using plain "tex" then it also calls "miniltx.tex"---a basic latex
151 interpreter for plain "tex"---which should also be available, but if
152 not, can be collected from the CTAN server.}
153
154 \subsection{Graphics files}\label{subsec:graph}
155
156 Your figures must exist either as ".eps" or as ".pdf" files. If you
157 are using only "pdflatex" then you can create and label using ".pdf"
158 figures throughout if you wish.
159
160 {\small{\bf Smallprint}\qua This is a major change introduced in
161 version 1.2. In version 1.1 it was necessary to create ".eps" copies
162 of all figure files. However this {\em does not mean\/} that you can
163 now safely discard the ".eps" versions for figures already labelled.
164 There is a problem with bounding boxes and your labels are likely to
165 move to unexpected places. Read smallprint note \ref{subsec:bb}.}
166
167 If you are creating your figures from scratch, for example by using
168 "xfig" (highly recommended) then export as ``EPS (Encapsulated
169 Postscript)'' if you are using plain "tex" or if you may need to
170 compile using "latex", and as ``PDF (Portable Document Format)'' if
171 you are using only "pdflatex". If you want to be able to compile
172 using both "latex" and "pdflatex" then export as EPS and create a PDF
173 version by running "epstopdf". The syntax is:
174
175 \medskip
176 "epstopdf fig.eps"
177
178 {\bf Note}\qua Do not use the similar sounding program "eps2pdf" which
179 may change the bounding box.
180
181 Do not draw your labels in your drawing package.
182
183
184 \subsection{GhostView}
185
186 You will also need a working copy of "GhostView" or "gv" or "GSview"
187 for reading coordinate positions. Most "unix" or "linux"
188 installations include this program, as does "cywin" running under
189 Windows, and you can collect a stand-alone copy for Windows or
190 Macintosh by visiting:
191
192 \href{http://www.cs.wisc.edu/~ghost/gsview/}{\tt http://www.cs.wisc.edu/\char'176ghost/gsview/}\quad or\newline
193 \href{http://www.cs.wisc.edu/~ghost/macos/}{\tt http://www.cs.wisc.edu/\char'176ghost/macos/}
194
195 \section{Basic use}\label{sec:bas}
196
197 \subsection{Labelling a new figure}
198
199 Load your figure (the ".eps" version if you have made one, or the
200 ".pdf" version if not) into "GhostView" or equivalent. You will
201 notice that the cursor position is recorded (in PS points) either at
202 the bottom or the side. This position is what you will read as your
203 labelling coordinates.
204
205 Assuming that you are using "latex" or "pdflatex" (the changes for
206 plain "tex" are indicated later) then include your figure using
207 instructions as in the following typical example:
208
209 \medskip
210 "\begin{figure}[ht!]
211 \labellist
212 \small\hair 2pt
213 \pinlabel $B^3_+$ at 57 246
214 \pinlabel $B^3_-$ [l] at 187 207
215 \pinlabel {$(S^3 \times I,A)$} [tr] at 76 26
216 \pinlabel $O$ [t] at 233 63
217 \pinlabel $K$ [r] at 125 272
218 \pinlabel $S^3$ [bl] at 253 283
219 \pinlabel $A$ [r] at 125 153
220 \endlabellist
221 \centering
222 \includegraphics[scale=0.65]{fig6}
223 \caption{A concordance between $K$ and the unknot}
224 \label{fig:cobo}
225 \end{figure}"
226
227 The result is shown in \fullref{fig:cobo}, taken from Kim \cite[Figure
228 6]{kim}.
229
230 %with the unlabelled figure
231 %included on the left (rather smaller) for reference. (This example is
232
233 \begin{figure}[ht!]
234 \centering
235 %\mbox{\raise 30pt\hbox{\includegraphics[scale=0.4]{fig6}}}
236 %\qquad\qquad
237 \labellist
238 \small\hair 2pt
239 \pinlabel $B^3_+$ at 57 246
240 \pinlabel $B^3_-$ [l] at 187 207
241 \pinlabel {$(S^3 \times I,A)$} [tr] at 76 26
242 \pinlabel $O$ [t] at 233 63
243 \pinlabel $K$ [r] at 125 272
244 \pinlabel $S^3$ [bl] at 253 283
245 \pinlabel $A$ [r] at 125 153
246 \endlabellist
247 \includegraphics[scale=0.65]{fig6}
248 \caption{A concordance between $K$ and the unknot}
249 \label{fig:cobo}
250 \end{figure}
251
252 Let's look at this example line-by-line.
253
254 \medskip
255 "\begin{figure}[ht!]"
256
257 opens the figure environment and instructs "latex" that we want the
258 figure to be printed either {\bf h}ere or at the {\bf t}op of the page
259 ({\bf !} and no-where else).
260
261 \medskip
262 "\labellist"
263
264 opens the list of labels.
265
266 \medskip
267 "\small" and "\hair 2pt"
268
269 are formatting commands which apply to all the labels: "\small"
270 typesets them approximately 1 point smaller than the text
271 (recommended) and "\hair 2pt" adjusts the spacing between the label
272 and the point which is being labelled (more on this below). Now come
273 the actual labels. The first label instruction:
274
275 \medskip
276 "\pinlabel $B^3_+$ at 57 246"
277
278 is the simplest form. It tells "latex" to pin the label $B^3_+$ with
279 its centre at the point with coordinates $(57,246)$ in the figure. The
280 remaining labels all have optional position codes.
281
282 \medskip
283 "\pinlabel $B^3_-$ [l] at 187 207"
284
285 tells "latex" to pin the label $B^3_-$ by the point centre-left of its
286 bounding box (this is what the position code "[l]" tells it to
287 do) at the point with with coordinates $(187,207)$. But "pinlabel"
288 does not do this. It applies automatic spacing. The point with
289 coordinates $(187,207)$ is the end of the arrow we are labelling. We
290 want the label to be placed a little way away and this is what
291 "pinlabel" does. It sets the label exactly 2 points away. The "tex"
292 dimension "\hair" is this spacing and we just set it equal to 2
293 points. The default for "\hair" is "3pt", but you can reset it to any
294 dimension you like for a particular label (or set of labels). If you
295 want no autospacing, then use the starred form of the command:
296
297 \medskip
298 "\pinlabel* $B^3_-$ [l] at 187 207"
299
300 which will set the label with the centre-left of its bounding box
301 {\em exactly\/} at the point $(187,207)$.
302
303 The next label:
304
305 \medskip
306 "\pinlabel {$(S^3 \times I,A)$} [tr] at 76 26"
307
308 introduces an important point. The label code "$(S^3 \times I,A)$"
309 has spaces in it. But "pinlabel" uses spaces to separate the various
310 instructions, so to avoid "pinlabel" attempting to use "$(S^3" as the
311 label (and falling over in the process) the label must be enclosed in
312 braces. The position code in this label is "[tr]" (top-right) and
313 this makes "pinlabel" pin this label by the point which is top-right
314 of the label bounding box (with autospacing) at $(76,26)$, which are
315 the coordinates read off from a point on the bottom curve of the
316 figure. A full list of position codes will be given shortly.
317
318 In \fullref{fig:screen} is a screenshot showing how the coordinates
319 are read in "GSview". The label being processed is "$S^3$", the end
320 of the arrow is located at $(253,283)$ and these coordinates are being
321 copied into the "latex" file.
322
323 \begin{figure}[ht!]
324 \centering
325 \labellist\small
326 \pinlabel $\cross$ <-2pt,1pt> at 428 512
327 \pinlabel {{\tt GSview} cursor} [b] <-10pt,20pt> at 428 512
328 \pinlabel $\downarrow$ [b] <1pt,7pt> at 428 512
329 \pinlabel $\uparrow$ [t] at 281 1
330 \pinlabel {coords read here} [t] <0pt,-10pt> at 281 1
331 \pinlabel {$\leftarrow$ coords copied here} [l] <0pt,0pt> at 753 516
332 \endlabellist
333 \includegraphics[width=.97\hsize]{screen}
334 \vspace{3mm}
335 \caption{Screenshot}
336 \label{fig:screen}
337 \end{figure}
338
339 In the screenshot the text editor "Emacs" is the active window on top
340 of "GSview" but the mouse is pointing at the point in "GSview" whose
341 coordinates are being read (from the bottom of the "GSview" window).
342 By using cursor keys in emacs, the mouse is not disturbed and the
343 coordinates can be copied across very rapidly and accurately. In this
344 example, the transcription of the coordinates took just a couple of
345 minutes.
346
347 Continuing with the example, there are further labels which do not
348 introduce anything new and then the list of labels is closed with:
349
350 \medskip
351 "\endlabellist"
352
353 after which come the commands for including the figure, the caption,
354 the label (for cross-referencing) and for closing the "figure"
355 environment:
356
357 \medskip
358 "\includegraphics[scale=0.65]{fig6}
359 \caption{A concordance between $K$ and the unknot}
360 \label{fig:cobo}
361 \end{figure}"
362
363 \medskip {\bf Important note}\qua The filename of the figure to be
364 included (ie "fig6") {\em must be given without extension\/}. The
365 program automatically looks for the correct file which would be
366 "fig6.ps" or "fig6.eps", if using "tex" or "latex", and would be
367 "fig6.pdf" if using "pdflatex". If you type
368 "\includegraphics[scale=0.65]{fig6.eps}" then the program will give a
369 warning:
370
371 \medskip
372 "cannot open figure fig6.eps.ps or .eps or .pdf on input line ..."
373
374 and no figure will appear.
375
376
377
378 \subsection{Position codes}\label{subsec:pos}
379
380 Here is a full list of position codes: "r"=right, "l"=left, "t"=top,
381 "b"=bottom and "B"=baseline. The default is centre and any sensible
382 combination of two codes may be give (in either order) eg
383 "[tl]"="[lt]"=top-left of label bounding box. The baseline is the
384 line that "tex" uses for lining up characters. In \fullref{fig:ori}
385 we illustrate all the possible position codes for a simple piece of
386 text.
387
388 \labellist\hair 1.5pt
389 \pinlabel "[tr]" [bl] at 162 86
390 \pinlabel "[br]" [tl] at 162 4
391 \pinlabel "[tl]" [br] at 29 86
392 \pinlabel "[bl]" [tr] at 29 4
393 \pinlabel "[t]" [b] at 96 86
394 \pinlabel "[b]" [t] at 96 4
395 \pinlabel "[r]" [l] at 162 45
396 \pinlabel "[l]" [r] at 29 45
397 \pinlabel "[Br]" [bl] at 162 21
398 \pinlabel "[Bl]" [br] at 29 21
399 \pinlabel "[B]" [b] at 96 21
400 \pinlabel {\Large .} at 96 21.7
401 \pinlabel {\Large .} at 162.3 21.7
402 \pinlabel {\Large .} at 28.6 21.7
403 \pinlabel {\Large .} at 162.3 86
404 \pinlabel {\Large .} at 162.3 3.7
405 \pinlabel {\Large .} at 28.6 86
406 \pinlabel {\Large .} at 28.6 3.7
407 \pinlabel {\Large .} at 96 86
408 \pinlabel {\Large .} at 96 3.7
409 \pinlabel {\Large .} at 162.3 45
410 \pinlabel {\Large .} at 28.6 45
411 \pinlabel {\Large .} at 96 45
412 \pinlabel {baseline} [l] <0pt,2pt> at 187 21
413 \pinlabel {$\leftarrow$ bounding box} [l] <0pt,1pt> at 162 65
414 \endlabellist
415
416
417 \begin{figure}[ht!]\small
418 \centering\vspace{1.5mm}
419 \includegraphics[width=.5\hsize]{put}
420 \vspace{1.5mm}
421 \caption{Position codes}
422 \label{fig:ori}
423 \end{figure}
424
425 If no position code is given then the label is pinned by the centre
426 (unlabelled dot in the figure).
427
428 \subsection{Relabelling an existing figure}
429
430 Print the figure (with its labels) as a record of how the labels go.
431 Then edit the ".eps" file to remove the given labels. This is usually
432 easier than it sounds. Text in a PostScript file is usually enclosed
433 in round brackets. For example here is an excerpt from the file
434 "put.eps" used in \fullref{fig:ori}:
435
436 \medskip
437 "% Polyline
438 7.500 slw
439 [60] 0 sd
440 n 5492 3949 m 7720 3949 l 7720 2577 l 5491 2576 l
441 cp gs col0 s gr [] 0 sd
442 /Helvetica-Bold ff 1500.00 scf sf
443 5422 3615 m
444 gs 1 -1 sc (put) col11 sh gr
445 % here ends figure;
446 %
447 % here starts figure with depth 0
448 % Polyline
449 7.500 slw
450 n 5027 3649 m"
451
452 The text "(put)" is obvious and easily searchable. In this example
453 ``put'' is in fact a graphic element, rather than a label, so we would
454 not edit it out, but a label would be given in the file in a similar
455 format. If ``put'' were a label to be removed, you would edit it out
456 by replacing "(put)" with "()". Do the same for all labels. Of
457 course if you have the source code (eg the ".fig" file for "xfig")
458 then you can edit the figure directly and then re-export it as an
459 ".eps" file.
460
461 If your figure only exists as a ".pdf" file, then you can try
462 coverting to ".eps" by running "epstops -eps fig.pdf" and then
463 looking for text as above. After removing labels, convert back. If
464 these dodges fail then you will have to remake the figure without
465 labels using the original graphics program.
466
467 Once the old labels have been removed, relabelling is identical to
468 labelling a new figure as described above.
469
470
471
472
473 \subsection{Rotated and other exotic labels}\label{rotate}
474
475 Nothing has been said so far about the actual label. As far as
476 "pinlabel" is concerned the label is just a box. Any valid "(la)tex"
477 code can be used inside that box. For example you can use a
478 "\rotatebox" for your label which results in a rotated label:
479
480 \medskip
481 "\pinlabel \rotatebox{-35}{$a^b$} at 50 30"
482
483 You could even label by another picture:
484
485 \medskip
486 "\pinlabel \reallyincludegraphics[height=1cm]{pic} at 50 30"
487
488 where "pic.eps" is the labelling picture.
489
490 The reason for using the command "\reallyincludegraphics" rather than
491 the usual "\includegraphics" is that it has the effect of suppressing
492 labelling in the small picture. This is necessary because otherwise
493 \TeX\ will go into an infinite loop as it tries to label by a picture,
494 which is in turn labelled by a picture, which \dots\ \ For more detail
495 about the command "\reallyincludegraphics" see the
496 \hyperlink{really}{smallprint note (3)} near the end of
497 \fullref{sec:adv}.
498
499 \fullref{fig:exotic} shows an exotic example where we have used the
500 whole picture as a rotated label inside itself. The code for this
501 figure is as follows:
502
503 \medskip
504 "\begin{figure}[ht!]
505 \labellist\hair 1.5pt
506 \pinlabel \rotatebox{57}{\reallyincludegraphics[width=1cm]{put}}
507 [bl] at 162 86
508 \endlabellist
509 \centering\vspace{4.5mm}
510 \includegraphics[width=.5\hsize]{put}
511 \vspace{1.5mm}
512 \caption{An exotic label}
513 \label{fig:exotic}
514 \end{figure}"
515
516
517 \begin{figure}[ht!]
518 \labellist\hair 1.5pt
519 \pinlabel \rotatebox{57}{\reallyincludegraphics[width=1cm]{put}}
520 [bl] at 162 86
521 \endlabellist
522 \centering\vspace{4.5mm}
523 \includegraphics[width=.5\hsize]{put}
524 \vspace{1.5mm}
525 \caption{An exotic label}
526 \label{fig:exotic}
527 \end{figure}
528
529
530 \subsection{Using plain tex}
531
532 Since the package automatically loads "miniltx.tex", all the "latex"
533 commands connected with graphics will be available. So the basic
534 commands for relabelling are the same. Probably you will have a
535 figure inclusion macro included in whatever package you are using.
536 Assuming this is "\fig ... \endfig" a pinlabelled figure might look
537 this:
538
539 \medskip
540 "\fig
541 \labellist\ninepoint\hair 2.5pt
542 \pinlabel {$\partial_1 X$} [r] at 156 426
543 \pinlabel {$\partial_2 X$} [tl] at 334 429
544 \pinlabel $X_1$ at 431 513
545 \pinlabel $X_2$ at 428 460
546 \pinlabel $H_X$ [lb] at 311 622
547 \pinlabel* $H_X'$ [tr] at 178 370
548 \endlabellist
549 \centerline{\includegraphics[width=3in]{decomp}}
550 \centerline{Figure 23: Labelling the boundary components of $X$}
551 \endfig"
552
553 \section{Advanced features}\label{sec:adv}
554
555 There are three features which give the package immense flexibility in
556 pinning labels: pinning by coordinates, fine adjustment and the use of
557 an external label file.
558
559 \subsection{Pinning by coordinates}
560
561 You can pin a label by {\em any\/} point, not just by the 12 points
562 illustrated in \fullref{fig:ori}. Intrinsic coordinates are defined
563 in the ``label-space'' by taking the origin at the centre and using
564 affine coordinates with horizontal unit half the width of the bounding
565 box and vertical half the height plus depth. These are illustrated in
566 \fullref{fig:coords}.
567
568 \begin{figure}[ht!]
569 \centering\vspace{1.5mm}
570 \labellist\small\hair 1.5pt
571 \pinlabel $(1,1)$ [b] at 162 86
572 \pinlabel $(1,-1)$ [tl] at 162 4
573 \pinlabel $(-1,1)$ [br] at 29 86
574 \pinlabel $(-1,-1)$ [tr] at 29 4
575 \pinlabel $(0,1)$ [b] at 96 86
576 \pinlabel $(0,-1)$ [t] at 96 4
577 \pinlabel $(1,0)$ [l] at 162 45
578 \pinlabel $(-1,0)$ [r] at 29 45
579 \pinlabel {\Large .} at 162.3 86
580 \pinlabel {\Large .} at 162.3 3.7
581 \pinlabel {\Large .} at 28.6 86
582 \pinlabel {\Large .} at 28.6 3.7
583 \pinlabel {\Large .} at 96 86
584 \pinlabel {\Large .} at 96 3.7
585 \pinlabel {\Large .} at 162.3 45
586 \pinlabel {\Large .} at 28.6 45
587 {\hair 0pt \pinlabel {\Large .} at 96 45 }
588 \pinlabel $(0,0)$ [t] at 96 45
589 \pinlabel {\Large .} at 129 65
590 \pinlabel $(0.5,0.5)$ [t] at 129 65
591 \pinlabel {\Large .} at 228 86
592 \pinlabel $(2,1)$ [b] at 228 86
593 \pinlabel {\Large .} at -71 45
594 \pinlabel $(-2.5,0)$ [l] at -71 45
595 \pinlabel {$\leftarrow$ bounding box} [l] <0pt,1pt> at 162 65
596 \endlabellist
597 \includegraphics[width=.5\hsize]{put2}
598 \vspace{1.5mm}
599 \caption{Intrinsic coordinates in label-space}
600 \label{fig:coords}
601 \end{figure}
602
603 Then the command:
604
605 \medskip
606 "\pinlabel* $a^b$ by -1.5 0 at 231 47"
607
608 will pin the label $a^b$ so that the point $(-1.5,0)$ in label space
609 (the ``label-point'') coincides with the point with (PostScript)
610 coordinates $(231,47)$ in the diagram (the ``diagram point''). You
611 can imagine a pin inserted through the label (on an extended
612 transparent sheet if necessary) at the label-point and then this used
613 to pin the label to the diagram at the diagram-point. This is the
614 reason for the name that we have adopted for the package.
615
616 We have used the starred form of "\pinlabel" in this example. If you use
617 the unstarred form:
618
619 \medskip
620 "\pinlabel $a^b$ by -1.5 0 at 231 47"
621
622 then the label is pinned so that the point $(-1.5,0)$ in label space
623 is pinned to a point exactly "\hair" away from the point $(231,47)$ in
624 the diagram. The direction of this autospacing is determined by the
625 program. In practice you let the program decide on this direction,
626 but if you want to know exactly how it decides, read part (2) of the
627 next smallprint.
628
629 You will now observe that there are several equivalent ways to pin
630 labels using standard points. For example the following are all
631 exactly equivalent:
632
633 \medskip
634 "\pinlabel* $t-u^2$ by -1 -1 at 231 47
635 \pinlabel* $t-u^2$ [lb] at 231 47
636 \pinlabel* $t-u^2$ [bl] at 231 47
637 {\hair 0pt \pinlabel $t-u^2$ by -1 -1 at 231 47 }
638 {\hair 0pt \pinlabel $t-u^2$ [lb] at 231 47 }
639 {\hair 0pt \pinlabel $t-u^2$ [bl] at 231 47 }"
640
641 Note the space after the final coordinate in the above examples. The
642 commands use spaces as separators and are syntax sensitive. There
643 must be a space (or a line return) after the final coordinate. The
644 program will attempt to recover if the syntax is wrong, but often
645 crashes with strange errors. If you copy the syntax in the examples
646 in this file, then all will be well. For more about syntax and errors
647 see \fullref{subsec:syn} and \fullref{subsec:err}.
648
649 {\small{\bf Smallprint}\qua (1)\qua The use of spaces as separators
650 means that the commands will not work with "\obeyspaces" set.
651
652 (2)\qua There are eight directions for autospacing: E, NE, N, NW, W,
653 SW, S, SE. The choice of a discrete set of directions makes the
654 spacing look consistent over the diagram, whilst allowing sufficient
655 flexibility to space labels away from the points being labelled. If
656 you use the position code "[tl]" etc then the choice of direction is
657 determined by the position code in the obvious way, eg "[tl]"
658 determines NW, ie the label is set so that the diagram-point is
659 "\hair" away from the label-point in the north-west direction. The
660 position code "[B]" suppresses autospacing and "[Bl]" chooses W, "[Br]"
661 chooses E as you would expect. When pinning by coordinates rather
662 than by letters, the program uses the direction (of the eight
663 available) closest to direction from $(0,0)$ to the label-point. If
664 the label-point is $(0,0)$ then autospacing is again suppressed. The
665 effect of these rules is that for example:
666
667 \medskip
668 "\pinlabel {label} by 1 1 at 231 56"
669
670 is not always equivalent to:
671
672 \medskip
673 "\pinlabel {label} [tr] at 231 56"
674
675 If the label is rather wide, then $(1,1)$ in diagram space may be
676 closer to E than NE and the first command will autospace using E and
677 the second NE.}
678
679 \subsection{Fine adjustment}
680
681 There is an optional manual ``fine adjustment'' that can be applied to
682 any label which moves the label a specified amount. This may be
683 inserted before "at" or directly after the label. The adjustment
684 goes inside diamond brackets "<x-adj,y-adj>" where "x-adj" and "y-adj"
685 are arbitrary "tex" dimensions.
686
687 For example the following commands are all equivalent:
688
689 \medskip
690 "\pinlabel $a^b$ [l] <-2pt,1pt> at 231 47
691 \pinlabel $a^b$ by -1 0 <-2pt,1pt> at 231 47
692 \pinlabel $a^b$ <-2pt,1pt> [l] at 231 47
693 \pinlabel $a^b$ <-2pt,1pt> by -1 0 at 231 47"
694
695 They all pin the label $a^b$ by centre-left at $(231,47)$ with two
696 adjustments: "\hair" (autospacing) and then "(-2pt,1pt)" manual (in other
697 words the label is moved 2 points to the left and 1 point upwards).
698
699 \medskip
700 "\pinlabel* $a^b$ [l] <-2pt,1pt> at 231 47"
701
702 will do the same but with "\hair" set to "0pt" (ie autospacing
703 suppressed).
704
705 In practice, you label your diagram as described in \fullref{sec:bas}
706 using either position codes or coordinates. Then you inspect it in a
707 viewer and make final adjustments by (a) adjusting "\hair" (this can
708 be done for each label separately if necessary) and (b) adding a final
709 manual adjustment "<x-adj,y-adj>" again, if necessary. For example,
710 inspecting \fullref{fig:cobo}, we see that the label $B^3_-$ has been
711 placed a little too far from the arrow tail, because of the sloping
712 italic type, and that $K$ is also a tad too far from its arrow because
713 of the shape of the letter $K$. So to perfect the labelling you could
714 make fine adjustments as follows:
715
716 \medskip
717 "...
718 \pinlabel $B^3_-$ [l] <-1pt,0pt> at 187 207
719 \pinlabel {$(S^3 \times I,A)$} [tr] at 76 26
720 \pinlabel $O$ [t] at 233 63
721 \pinlabel $K$ [r] <1pt,0pt> at 125 272
722 ..."
723
724 It is worth stressing that both "\hair" and the fine adjustment
725 "<x-adj,y-adj>" are absolute dimensions. They do not change if the
726 figure is rescaled. By contrast the coordinates of the diagram point,
727 "at XXX YYY", are given in PostScript points scaled by any scaling
728 applied to the figure and are therefore instrinsic to the figure.
729 This means that if the figure is rescaled, the diagram point moves
730 with the scaling (as you would expect) but the spacing given by
731 autospacing and fine adjustment stays fixed. Thus you can make
732 last-minute changes of scale to a labelled diagram and the labels will
733 continue to be perfectly positioned.
734
735
736 \subsection{Using a .lab file}\label{labfile}
737
738 Labels can either be given as a list in the "tex" file (they must come
739 between "\labellist" and "\endlabellist") as described above or given
740 in the form of an external ".lab" file. This is particularly useful
741 if you have a complicated diagram with labels generated by an external
742 program, for example the "mathfig" software, which automatically
743 generates ".lab" files from Mathematica input. The syntax is identical
744 but the commands "\labellist" and "\endlabellist" must not be given.
745 The filename must be exactly the same as the figure being labelled
746 (but with a ".lab" extension instead of a ".eps" or ".ps" or ".pdf"
747 extension) and the label file must be in the same directory as the
748 figure file.
749
750 The program is based on "psfig" and uses "psfig" internally. In the
751 examples above, we have used "graphicx" commands for figure insertion
752 but we could equally well have used "psfig" commands. In the first
753 example, \fullref{fig:cobo} we used:
754
755 \medskip
756 "\includegraphics[scale=0.65]{fig6}"
757
758 but we could equivalently have used:
759
760 \medskip
761 "\psfig{file=fig6,scale=65}"
762
763 This works because the program automatically translates to "psfig"
764 (and adjusts the scale command correctly). However it only does this
765 if there is a "labellist" waiting to be used. This is a feature that
766 allows you to use "\includegraphics" in its full power (eg with
767 rotation) for figures that are not being pinlabelled. But it means
768 that if you use an external ".lab" file then you {\em must\/} use
769 "psfig" syntax. For example, suppose that your figure is "diag.eps"
770 in the subdirectory "figs" then if you type:
771
772 \medskip
773 "\centerline{\psfig{file=figs/diag,width=.7\hsize}}"
774
775 and if the file "figs/diag.lab" reads:
776
777 \medskip
778 "\small\hair 2pt
779 \pinlabel $(-1,-1)$ [tr] at 29 4
780 \pinlabel $(0,1)$ [b] at 96 86
781 \normalsize\hair 3pt
782 \pinlabel $(0,-1)$ [t] at 96 4
783 \pinlabel $(1,0)$ [l] at 162 45
784 \pinlabel $(-1,0)$ [r] at 29 45
785 \pinlabel {\Large .} at 162.3 86
786 \pinlabel {\Large .} at 162.3 3.7"
787
788 Then these labels will be pinned to the diagram exactly as if they had
789 been typed in the main file. Note the change of formatting
790 instructions within this list of labels. The labels after the change
791 will be typeset "\normalsize" instead of "\small" with "\hair" set to
792 "3pt".
793
794
795 {\small{\bf Smallprint}\qua (1)\qua Labelling instructions do not have
796 to be given inside the "figure" environment. Indeed they can be given
797 at any time before the next "\includegraphics" or "\psfig" command.
798 If there are both a "labellist" pending {\em and\/} an appropriate
799 ".lab" file available, then the "labellist" will override the ".lab"
800 file (and you will get a warning to that effect). Any formatting that
801 is in force when the "labellist" is typed is ignored and the
802 formatting that is in force inside the figure environment is used
803 instead. For example the command "\small" can be given either at the
804 start of the "labellist" or at the start of the ".lab" file or after
805 "\begin{figure}[ht!]" with identical effect.
806
807 (2)\qua Formatting instructions can be given at any stage within the
808 labellist or the ".lab" file as in the above example (the change of
809 formatting in that example would work equally well within a
810 "labellist"). There is a facility for setting a global format that
811 automatically applies to all labels. If you type:
812
813 \medskip
814 "\gdef\hyperactivelabels{\small\sl\hair2.5pt}"
815
816 at the start of your file (or anywhere else you like) then all figures
817 that come after that line will have formatting applied exactly as if
818 you had typed:
819
820 \medskip
821 "\small\sl\hair2.5pt"
822
823 at the start of the "labellist" or ".lab" file. This facility is
824 extremely useful for machine generated ".lab" files. You can reset
825 "\hyperactivelabels" between figures. To cancel this automatic
826 formatting between any two figures, type:
827
828 \medskip
829 "\global\let\hyperactivelabels\relax"
830
831 \hypertarget{really}{(3)}\qua You can force the program to use "graphicx" rather than
832 autotranslating to the appropriate "psfig" command by typing
833 "\reallyincludegraphics". Since autotranslation only takes place when
834 there is a "labellist" pending, this will only be necessary if, for
835 some reason, a labellist has been supplied that applies to a later
836 figure. Labelling will take not place if autotranslation is
837 suppressed and the "labellist" will be saved and applied to the next
838 figure. An example where this was essential was given in
839 \fullref{rotate}. When using a picture as a label, you need to
840 suppress labelling in the label or \TeX\ will go into an infinte loop
841
842
843 (4)\qua Autotranslation of "\includegraphics" is far from perfect.
844 Many of the options are not supported. Read \fullref{sec:bugs} (on
845 bugs) below if you run into trouble.}
846
847
848 \section{Smallprint}\label{sec:smallprint}
849
850 {\small\subsection{Syntax}\label{subsec:syn}
851
852 {\bf Basic syntax}
853
854 \medskip
855 "\pinlabel {label} by x-pin y-pin at x-location y-location"
856
857 or
858
859 \medskip
860 "\pinlabel* {label} by x-pin y-pin at x-location y-location"
861
862 where "x-pin y-pin" is the point in intrinsic coords in label space
863 where we are placing the pin and "x-location y-location" is the point
864 in diagram space (in PS points as read in gv) where the label is
865 pinned. "\pinlabel" uses "\hair" autospacing "\pinlabel*" does not.
866 "\mathsurround" is set to "0pt" for parsing the label. If the label
867 contains spaces, it {\em must\/} be enclosed in braces "{}".
868
869 \medskip
870 "x-pin", "y-pin", "x-location" and "y-location" are pure numbers,
871 {\em not\/} dimensions. The program converts them to the relevant
872 dimension. The "by" and "at" are essential as are all the spaces.
873
874
875 {\bf Options}
876
877 \medskip
878 "by x-pin y-pin" may be omitted, the default is "0 0".
879
880 \medskip
881 "by x-pin y-pin" may be replaced by position codes "[r]", "[Bl]"
882 etc (see \fullref{subsec:pos} for full detail of these codes).
883
884 A manual adjustment "<x-adj, y-adj>" may be added either after the label or
885 before "at". Here "x-adj" and "y-adj" are "tex" dimensions, eg "5pt" or
886 "-2mm".
887
888 Full examples (for more examples see earlier):
889
890 \medskip
891 "\pinlabel $B^3_-$ <-1pt,0pt> by -1 0 at 187 207
892 \pinlabel* $K$ [r] <1pt,0pt> at 125 272"
893
894
895 \subsection{Old syntax}\label{subsec:old}
896
897 "pinlabel.sty" is a revised version of "geompsfi.sty" and the old
898 syntax remains available for backwards compatibility. The simplest
899 version is:
900
901 \medskip
902 "\setlabel{a^b}{321}{33}{1}{1}"
903
904 which pins the label $a^b$ by (1,1) (ie "[tr]") to $(321,33)$ with
905 autospacing applied. Note that the "$$"'s for math mode are not given
906 with the label in this syntax. Two new options have been added to the
907 old syntax. There is a starred form:
908
909 \medskip
910 "\setlabel*{a^b}{321}{33}{1}{1}"
911
912 which is the same but with autospacing suppressed, and fine
913 adjustments may be added:
914
915 \medskip
916 "\setlabel<-2pt,-1pt>{a^b}{321}{33}{1}{1}
917 \setlabel*<-2pt,-1pt>{a^b}{321}{33}{1}{1}"
918
919 which are the same but with a "(-2pt,-1pt)" adjustment added.
920
921 The old and new syntax may be mixed in a "labellist" or inside a
922 ".lab" file.
923
924 {\bf Important notes}\qua (1)\qua "\mathsurround" is set to zero when
925 parsing the label. This was not done in "geompsfi", so the command is
926 {\em not quite\/} backwards compatible. If no "\mathsurround" is used
927 there is no change in label positioning. If "\mathsurround" is used
928 then labels may move a small amount horizontally.
929
930 (2)\qua The label is in horizontal mode in standard ("\pinlabel")
931 syntax but in math mode in the old ("\setlabel") syntax, so care
932 should be taken if the syntaxes are mixed.
933
934 \subsection{Errors}\label{subsec:err}
935
936
937 The program will attempt to recover from syntax errors. Roughly
938 speaking, provided the "\pinlabel" command terminates with%
939 " at XXX YYY" where there are spaces round the "at" and "XXX", "YYY"
940 are pure numbers, then the label (the code after "\pinlabel" up
941 to the first unbraced space) will appear in the diagram. If the
942 program does not recognise the syntax between the label and the "at"
943 then you will get the following warning:
944
945 \medskip
946 "I don't understand your positioning information for label #1 and shall
947 ignore it; or perhaps your label has a space and needs braces."
948
949 where "#1" is replaced by the actual label code. If there is no "at"
950 then the program has a harder time recovering but you should get the
951 following warning:
952
953 \medskip
954 "There is something wrong with your syntax for label #1;
955 you must finish with "\ttq" at XXX YYY"\ttq" : the "\ttq"at"\ttq" and spaces are important!
956 I'm going to try to ignore this label: don't blame me if there are some
957 funny numbers in your diagram and later labels are out-of-position."
958
959 By looking at the finished diagram, you should be able to pick out
960 where the error lies. If all that is wrong with the syntax is that
961 the position code has been mistyped then you should just get the
962 following warning:
963
964 \medskip
965 "Unknown position code [#2]; I shall ignore it."
966
967 where "[#2]" is the mistyped code. If you make a basic "tex" error
968 (unmatched "$..$"'s for example) then you should get an error
969 "missing $" or similar. If all else fails, check each "\pinlabel"
970 command against the samples given here.
971
972 \subsection{Bounding boxes}\label{subsec:bb}
973
974 In \ref{subsec:graph} it was mentioned that conversion from ".eps" to
975 ".pdf" may change the bounding box. In a ".pdf" file the bounding
976 box always has bottom-left corner at "0 0" but this is not true for
977 an ".eps" file. The recommended converter "epstopdf" does not change
978 the {\em size} of the bounding box but merely moves the bottom-left
979 corner to "0 0". This implies that an ".eps" file used to position
980 labels can safely be discarded if and only if the bottom-left corner
981 in the bounding box in the ".eps" file is in fact at "0 0".
982
983
984 If you need to know the deep detail on how "pinlabel" reads the
985 bounding box, read on. If a bounding box is supplied via options to
986 "\includegraphics" or "\psfig", eg
987
988 {\footnotesize\medskip
989 "\includegraphics[bbllx=10bp,bblly=12bp,bburx=150bp,bbury=273bp,width=2in]{fig}",}
990
991 which specifies the box "10 12 150 273" (the "bp" specifies
992 postscript points), then this specification is used {\em whatever the
993 actual bounding box is for the graphics files.} Otherwise pinlabel
994 looks for a file named "fig.ps" or "fig.eps" or "fig.pdf" {\em in
995 that order}. If it finds such a file, it reads the bounding box and
996 uses that. If there is no file "fig.ps" or "fig.eps" or "fig.pdf" or
997 if "pinlabel" cannot find a bounding box in the first of these that
998 exists, then you get an error message and no figure is typeset.}
999
1000
1001
1002
1003 \section{Bugs}\label{sec:bugs}
1004
1005 No spaces are permitted in the file argument of "\psfig".
1006 Autotranslation of "graphicx" means that no spaces are permitted in
1007 the file argument to "\includegraphics". \newline Thus
1008 "\includegraphics[width=4in]{ foo }" will produce errors. It should
1009 be typed "\includegraphics[width=4in]{foo}". Spaces are permitted
1010 with other arguments.
1011
1012 Many of the options in "graphicx" are not supported by
1013 autotranslation. The supported ones are: "width", "height", "scale",
1014 "bbllx", "bblly", "bburx", "bbury" and "clip". The syntax for clip
1015 is "clip=". Replace "keepaspectratio=true" by "proportional=". The
1016 arguments to "bbllx" etc must be specified in postscript points (see
1017 the example above).
1018
1019 \medskip
1020 "\graphicspath{}" is not supported.
1021
1022 Automatic configuration for "dvips" and "pdflatex" is included in the
1023 program. No support is provided for other drivers.
1024
1025 The program is fully compatible with plain "tex" via the "latex"
1026 interpreter "miniltx.tex" written by David Carlisle. It works with
1027 "dvips" but {\em not\/} with "pdftex". For pdf output from plain
1028 "tex" use "dvips" followed by "ps2pdf".
1029
1030 {\bf Note}\qua "\psfig" ouputs a vbox, which is not centred in the
1031 "latex" "{center}" environment. Either use "\centerline{}" or type
1032 "\leavevmode" before "\psfig{..}". The translator adds "\leavevmode"
1033 for "\includegraphics", which therefore centres correctly as usual
1034 in the "{center}" environment.
1035
1036 \section{Why pinlabel?}\label{sec:why}
1037
1038 This section reviews other labelling packages and attempts to answer
1039 the obvious question: why do we need a new package? Well the first
1040 obvious comment is that the package is not new. It is the old package
1041 "geompfsi", rewritten, with extra functionality and new syntax.
1042 However it is fully backwardly compatible and all "geompfsi" diagrams
1043 should compile perfectly with "pinlabel" (with one small caveat, see
1044 note (1) in \fullref{subsec:old}).
1045
1046
1047 \subsection{rlepsf and psfrag}
1048
1049 Turning to other packages which are capable of perfect \TeX\ formatted
1050 labels, there are two relabelling packages "rlepsf" and "psfrag" which
1051 replace dummy labels in the ".eps" file with "tex" labels specified in
1052 the ".tex" file. Both of these are incompatible with "pdflatex",
1053 which makes them now unsuitable for figures created from scratch.
1054 They depend on low level interfacing with PostScript via "\special"
1055 commands. Indeed both are somewhat sensitive as to the precise nature
1056 of the ".eps" file being relabelled. If you have a file with figures
1057 relabelled using "rlepsf" or "psfrag", the most robust way to make it
1058 "pdflatex" compatible is to relabel the figures using "pinlabel".
1059 (But you can also treat the figures like "pstricks" figures etc, see
1060 \fullref{subsec:pst}.)
1061
1062
1063 \subsection{Combined output from xfig}
1064
1065 \medskip
1066 "xfig" is capable of creating figures with properly formatted "tex"
1067 labels using "combined ps/latex (pstex)" or "combined pdf/latex"
1068 output. This works well, and existing figures using this system can
1069 be used with "pdflatex" with only minor changes: if you export as
1070 "combined ps/latex (pstex)" you have to rename the ".pstex" file
1071 (which is in fact an ".eps" file) to an ".eps" file and convert to
1072 ".pdf" and in both cases you have edit the "\includegraphics{}"
1073 command to remove the ".pstex" or ".pdf" extension.
1074
1075 However starting from scratch, it is much more efficient to create
1076 unlabelled ".eps" or ".pdf" files in "xfig" and then add labels with
1077 "pinlabel". The positioning of the labels in "xfig" is hit-and-miss
1078 and difficult to adjust: you have to keep the ".fig" file open, move
1079 the label a little, re-export, reconvert to ".pdf", recompile, repeat
1080 \ldots. Using "pinlabel" the label is usually positioned perfectly
1081 first time and can be adjusted without reopening "xfig", which is far
1082 more efficient.
1083
1084
1085 \subsection{overpic, labelfig, xyoverpic and WARMreader}
1086
1087 There are three packages which, like "pinlabel" add the labels as an
1088 overlay on an existing ".eps" figure and therefore produce robust code
1089 suitable for "pdflatex". "overpic" is the most basic. Reading label
1090 positioning is pure guesswork (using a simple grid) and there are no
1091 fine adjustments for positioning, which makes the final tuning very
1092 time-consuming (and highly sensitive to any last-minute change of
1093 scale). "labelfig" is slightly more sophisticated, but reading label
1094 positioning is the same guesswork as for "overpic", there are some
1095 position codes, but again there is no fine adjustment and moreover
1096 the syntax is {\em awful\/}:
1097
1098 \medskip
1099 "\SetLabels
1100 \E(.18*.68) $F$\\
1101 \E(.39*.68) $G$\\
1102 ...
1103 \E(.75*.2) or\\
1104 \E(.88*.2) $F$\\
1105 \endSetLabels
1106 %\ShowGrid
1107 \AffixLabels{\BoxedEPSF{Mutant.ART scaled 500}}}"
1108
1109 \medskip "xyoverpic" is much more sophisticated, offering a good deal
1110 of the functionality of "pinlabel". But accurate positioning of
1111 labels requires a preprocessor such as "WARMreader". You can also
1112 read the label positions using "ghostview" but you have to be clever
1113 to do this. Firstly you need to make sure that your ".eps" file has
1114 its bounding box starting at "(0,0)" then you need to supply the other
1115 bounding box coordinates directly after "\begin{xyoverpic*}" (they are
1116 "(280,210)" in the example below) to set the scaling; then the
1117 "ghostview" coordinates can be used. The syntax for the actual labels
1118 is, if anything, worse than "labelfig" but it does have both a
1119 position code and an element of fine positioning built in:
1120
1121 \medskip
1122 "\begin{xyoverpic*}{(280,210)}{scale=0.75}{figures/pgl-orbifold}
1123 ,(0, 107)*++!R{4}
1124 ,(64,178)*++!DR{4}
1125 ,(278,107)*++!L{2}
1126 ,(130, 136)*++!LD{2}
1127 ,(172,107)*++!U{3}
1128 \end{xyoverpic*}}"
1129
1130 By contrast, "pinlabel" uses "ghostview" coordinates for files whose
1131 bounding box does not start at "(0,0)" and the syntax is transparent.
1132
1133 \subsection{Summary}
1134
1135 To summarise the advantages of "pinlabel" over existing packages which
1136 do a broadly similar job: only "xyoverpic" with the the tweaks
1137 described above (or with "WARMreader" input) gets location in diagram
1138 accurate first time. But it is marred by impossible syntax and
1139 limited fine adjustment.
1140
1141 \medskip "pinlabel" gets a similar accuracy in positioning and has
1142 transparent syntax and arbitrary fine adjustment. Moreover "pinlabel"
1143 has a powerful feature not shared by any other package: the ability to
1144 pin labels using arbitrary pin positions, specified in instrinsic
1145 coordinates in the label. This has not been stressed in this manual
1146 because it is rarely necessary in hand constructed diagrams, but for
1147 machine generated code it is very useful indeed. For example Silvio
1148 Levy (who originated this feature) writes:
1149
1150 {\leftskip 15pt\rightskip 15pt\leavevmode\llap{``}{\em I find it very convenient to
1151 place (small, "mathematica"-generated) labels around a circle, say, by
1152 pinning the label at $(-\cos\theta,-\sin \theta)$ in label
1153 coordinates. This works very well.}''\par}
1154
1155 \subsection{pstricks, eepic, specials}\label{subsec:pst}
1156
1157 Before leaving the topic of other packages, there are a number of
1158 packages which, like "rlepsf" and "psfrag" interface directly with
1159 PostScript. All are unsuitable for use with "pdflatex" for this
1160 reason. If faced with a file containing such figures, you need to
1161 precompile the figures using "latex" then "dvips -E" (or "dvips"
1162 followed by "ps2epsi", which is more robust about bounding box
1163 placement) and then "epstopdf" to produce a ".pdf" file for inclusion
1164 in the usual way.
1165
1166
1167 \section{Pinlabeler and labelpin}
1168
1169 Peter Storm has written an extremely useful extension to "gv", called
1170 "pinlabeler" which automatically copies the coordinates of the cursor
1171 in "gv" to a text file open for editing. To be precise it writes a
1172 line like:
1173
1174 \medskip
1175 "\pinlabel {$$} [] at XXX YYY "
1176
1177 into the file at the position of the cursor (in the editor) where
1178 " XXX YYY " are the PS coordinates of the cursor in "gv". It does this
1179 when you click on a point in the "gv" window. This makes
1180 transcribing coordinates much simpler: you just click on the label
1181 position and then fill in the label and positioning code.
1182
1183 You can find full details (including installation instructions) at:
1184
1185 \href{http://hans.math.upenn.edu/~pstorm/pinlabeler.html}{\tt
1186 http://hans.math.upenn.edu/\char'176pstorm/pinlabeler.html}
1187
1188
1189 Nathan Dunfield has written a similar program "labelpin", which is a
1190 python script and therefore, unlike Storm's program, does not need
1191 compilation. Both work perfectly with "cygwin" under Windows
1192 ("pinlabeler" comes ready compiled for "cygwin") and both work
1193 perfectly with ".pdf" figures, moreover "labelpin" works on a Mac.
1194
1195 The script and instructions for "labelpin" can be downloaded from:
1196
1197 \href{http://www.math.uiuc.edu/~nmd/software/}{\tt
1198 http://www.math.uiuc.edu/\char'176nmd/software/}
1199
1200
1201
1202
1203 \section{Acknowledgements and copyright notice}
1204
1205 "pinlabel" is based on "geompsfi.sty" written by Silvio Levy which in
1206 turn is based on "psfig.sty" written by Trevor Darrell. Their
1207 agreement to this development is gratefully acknowledged. Silvio Levy
1208 has made several helpful suggestions and done extensive testing and
1209 debugging.
1210
1211 Thanks also to Walter Neumann, Paulo Ney de Souza, Nicholas Jackson
1212 and Noam Shomron for helpful suggestions, testing and debugging, and
1213 also to Mark Peletier for providing the code that reads the bounding
1214 box from a ".pdf" file, thus making ".eps" versions of figure files
1215 unnecessary when using "pdflatex".
1216
1217 \subsection*{Copyright notice}
1218
1219
1220 The following notice appears at the start of the source file:
1221
1222 {\small
1223 \medskip
1224 "
1225 Copyright 2006-11 Mathematical Sciences Publishers (MSP)
1226
1227 NOTICE
1228
1229 This package may be distributed and/or modified under the
1230 conditions of the LaTeX Project Public License, either version
1231 1.3 of this license or (at your option) any later version.
1232 The latest version of this license is in"
1233
1234 \noindent\hspace{1in}\href{http://www.latex-project.org/lppl.txt}{{\tt http://www.latex-project.org/lppl.txt}}
1235
1236 \medskip
1237 " and version 1.3 or later is part of all distributions of LaTeX
1238 version 2005/12/01 or later.
1239
1240 This package has the LPPL maintenance status `maintained' and is
1241 currently maintained by MSP: [email protected]
1242
1243 It comprises the files: pinlabel.sty (this file) and the manual
1244 pinlabdoc.pdf where full documentation may be found, together with
1245 the source files for the documentation."}
1246
1247
1248
1249 \begin{thebibliography}
1250
1251 \bibitem{kim}
1252 \textbf{H\,J Kim}, \href{http://dx.doi.org/10.2140/gt.2006.10.27}{\emph{Modifying surfaces in 4--manifolds by twist spinning}}, Geom.
1253 Topol. 10 (2006) 27--56
1254
1255 \end{thebibliography}
1256
1257 \end{document}
1258