| 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 |
|