diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/pinlabel/src/pinlabdoc.tex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/pinlabel/src/pinlabdoc.tex | 200 |
1 files changed, 144 insertions, 56 deletions
diff --git a/Master/texmf-dist/doc/latex/pinlabel/src/pinlabdoc.tex b/Master/texmf-dist/doc/latex/pinlabel/src/pinlabdoc.tex index e56e96c3cb2..4a09784cc52 100644 --- a/Master/texmf-dist/doc/latex/pinlabel/src/pinlabdoc.tex +++ b/Master/texmf-dist/doc/latex/pinlabel/src/pinlabdoc.tex @@ -1,3 +1,4 @@ + \documentclass[microtype]{gtpart} \usepackage{pinlabel} @@ -5,7 +6,7 @@ %%% running feet for documentation files \makeatletter \def\@oddfoot{\ifnum\count0=1 -\small\copyright\ Copyright 2006 Mathematical Sciences +\small\copyright\ Copyright 2006--11 Mathematical Sciences Publishers\hfill\else \small\it Mathematical Sciences Publishers: documentation\hfill\fi} \let\@evenfoot\@oddfoot @@ -150,38 +151,43 @@ using plain "tex" then it also calls "miniltx.tex"---a basic latex interpreter for plain "tex"---which should also be available, but if not, can be collected from the CTAN server.} -\subsection{Graphics files} - -Your figures must exist as ".eps" files. If you are using "pdflatex" -and your figures are PDF files then run "pdftops" to create ".eps" -versions. The syntax is: +\subsection{Graphics files}\label{subsec:graph} -\medskip -"pdftops -eps fig.pdf" +Your figures must exist either as ".eps" or as ".pdf" files. If you + are using only "pdflatex" then you can create and label using ".pdf" + figures throughout if you wish. -where "fig" should be replaced by the relevant filename. If you are -creating your figures from scratch, for example by using "xfig" -(highly recommended) then export as ``EPS (Encapsulated Postscript)'' -and NOT as PDF or any combined format. Do not draw your labels in -your drawing package. +{\small{\bf Smallprint}\qua This is a major change introduced in + version 1.2. In version 1.1 it was necessary to create ".eps" copies + of all figure files. However this {\em does not mean\/} that you can + now safely discard the ".eps" versions for figures already labelled. + There is a problem with bounding boxes and your labels are likely to + move to unexpected places. Read smallprint note \ref{subsec:bb}.} -If you are using "pdflatex" then you will also need PDF versions of -your figures which can be created by running "epstopdf". The syntax -is: +If you are creating your figures from scratch, for example by using + "xfig" (highly recommended) then export as ``EPS (Encapsulated + Postscript)'' if you are using plain "tex" or if you may need to + compile using "latex", and as ``PDF (Portable Document Format)'' if + you are using only "pdflatex". If you want to be able to compile + using both "latex" and "pdflatex" then export as EPS and create a PDF + version by running "epstopdf". The syntax is: \medskip "epstopdf fig.eps" -{\bf Note}\qua Do not use the similar sounding programs "eps2pdf" and -"pdf2ps" both of which change the bounding box. +{\bf Note}\qua Do not use the similar sounding program "eps2pdf" which +may change the bounding box. + +Do not draw your labels in your drawing package. \subsection{GhostView} You will also need a working copy of "GhostView" or "gv" or "GSview" -for reading coordinate positions. Most "unix" or "linux" -installations include this program and you can collect a copy for -Windows or Macintosh by visiting: + for reading coordinate positions. Most "unix" or "linux" + installations include this program, as does "cywin" running under + Windows, and you can collect a stand-alone copy for Windows or + Macintosh by visiting: \href{http://www.cs.wisc.edu/~ghost/gsview/}{\tt http://www.cs.wisc.edu/\char'176ghost/gsview/}\quad or\newline \href{http://www.cs.wisc.edu/~ghost/macos/}{\tt http://www.cs.wisc.edu/\char'176ghost/macos/} @@ -190,16 +196,17 @@ Windows or Macintosh by visiting: \subsection{Labelling a new figure} -Load your figure (the ".eps" version) into "GhostView" or equivalent. -You will notice that the cursor position is recorded (in PS points) -either at the bottom or the side. This position is what you will read -as your labelling coordinates. +Load your figure (the ".eps" version if you have made one, or the + ".pdf" version if not) into "GhostView" or equivalent. You will + notice that the cursor position is recorded (in PS points) either at + the bottom or the side. This position is what you will read as your + labelling coordinates. -Assuming that you are using "latex" (the changes for plain "tex" are -indicated later) then include your figure using instructions as in the -following typical example: +Assuming that you are using "latex" or "pdflatex" (the changes for + plain "tex" are indicated later) then include your figure using + instructions as in the following typical example: -\eject +\medskip "\begin{figure}[ht!] \labellist \small\hair 2pt @@ -362,7 +369,7 @@ program automatically looks for the correct file which would be warning: \medskip -"cannot open figure fig6.eps.ps or fig6.eps.eps on input line ..." +"cannot open figure fig6.eps.ps or .eps or .pdf on input line ..." and no figure will appear. @@ -426,7 +433,7 @@ easier than it sounds. Text in a PostScript file is usually enclosed in round brackets. For example here is an excerpt from the file "put.eps" used in \fullref{fig:ori}: -\eject +\medskip "% Polyline 7.500 slw [60] 0 sd @@ -451,9 +458,18 @@ course if you have the source code (eg the ".fig" file for "xfig") then you can edit the figure directly and then re-export it as an ".eps" file. +If your figure only exists as a ".pdf" file, then you can try + coverting to ".eps" by running "epstops -eps fig.pdf" and then + looking for text as above. After removing labels, convert back. If + these dodges fail then you will have to remake the figure without + labels using the original graphics program. + Once the old labels have been removed, relabelling is identical to labelling a new figure as described above. + + + \subsection{Rotated and other exotic labels}\label{rotate} Nothing has been said so far about the actual label. As far as @@ -826,12 +842,12 @@ suppress labelling in the label or \TeX\ will go into an infinte loop (4)\qua Autotranslation of "\includegraphics" is far from perfect. Many of the options are not supported. Read \fullref{sec:bugs} (on -bugs) below if you run into trouble. +bugs) below if you run into trouble.} \section{Smallprint}\label{sec:smallprint} -\subsection{Syntax}\label{subsec:syn} +{\small\subsection{Syntax}\label{subsec:syn} {\bf Basic syntax} @@ -953,6 +969,35 @@ where "[#2]" is the mistyped code. If you make a basic "tex" error "missing $" or similar. If all else fails, check each "\pinlabel" command against the samples given here. +\subsection{Bounding boxes}\label{subsec:bb} + +In \ref{subsec:graph} it was mentioned that conversion from ".eps" to + ".pdf" may change the bounding box. In a ".pdf" file the bounding + box always has bottom-left corner at "0 0" but this is not true for + an ".eps" file. The recommended converter "epstopdf" does not change + the {\em size} of the bounding box but merely moves the bottom-left + corner to "0 0". This implies that an ".eps" file used to position + labels can safely be discarded if and only if the bottom-left corner + in the bounding box in the ".eps" file is in fact at "0 0". + + +If you need to know the deep detail on how "pinlabel" reads the + bounding box, read on. If a bounding box is supplied via options to + "\includegraphics" or "\psfig", eg + +{\footnotesize\medskip + "\includegraphics[bbllx=10bp,bblly=12bp,bburx=150bp,bbury=273bp,width=2in]{fig}",} + + which specifies the box "10 12 150 273" (the "bp" specifies + postscript points), then this specification is used {\em whatever the + actual bounding box is for the graphics files.} Otherwise pinlabel + looks for a file named "fig.ps" or "fig.eps" or "fig.pdf" {\em in + that order}. If it finds such a file, it reads the bounding box and + uses that. If there is no file "fig.ps" or "fig.eps" or "fig.pdf" or + if "pinlabel" cannot find a bounding box in the first of these that + exists, then you get an error message and no figure is typeset.} + + \section{Bugs}\label{sec:bugs} @@ -965,9 +1010,11 @@ be typed "\includegraphics[width=4in]{foo}". Spaces are permitted with other arguments. Many of the options in "graphicx" are not supported by -autotranslation. The supported ones are: "width", "height", "scale", -"bbllx", "bblly", "bburx", "bbury" and "clip". The syntax for clip is -"clip=". Replace "keepaspectratio=true" by "proportional=". + autotranslation. The supported ones are: "width", "height", "scale", + "bbllx", "bblly", "bburx", "bbury" and "clip". The syntax for clip + is "clip=". Replace "keepaspectratio=true" by "proportional=". The + arguments to "bbllx" etc must be specified in postscript points (see + the example above). \medskip "\graphicspath{}" is not supported. @@ -1017,19 +1064,22 @@ relabelled using "rlepsf" or "psfrag", the most robust way to make it \medskip "xfig" is capable of creating figures with properly formatted "tex" -labels using "combined ps/latex (pstex)" output. This works well, and -existing figures using this system can be used with "pdflatex" with -only minor changes: you have to rename the ".pstex" file (which is in -fact an ".eps" file) to an ".eps" file, convert to ".pdf" and edit the -"\includegraphics{}" command to remove the ".pstex" extension. + labels using "combined ps/latex (pstex)" or "combined pdf/latex" + output. This works well, and existing figures using this system can + be used with "pdflatex" with only minor changes: if you export as + "combined ps/latex (pstex)" you have to rename the ".pstex" file + (which is in fact an ".eps" file) to an ".eps" file and convert to + ".pdf" and in both cases you have edit the "\includegraphics{}" + command to remove the ".pstex" or ".pdf" extension. However starting from scratch, it is much more efficient to create -unlabelled ".eps" files in "xfig" and then add labels with "pinlabel". -The positioning of the labels in "xfig" is hit-and-miss and difficult -to adjust: you have to keep the ".fig" file open, move the label a -little, re-export, reconvert to ".pdf", recompile, repeat \ldots. Using -"pinlabel" the label is usually positioned perfectly first time and -can be adjusted without reopening "xfig", which is far more efficient. + unlabelled ".eps" or ".pdf" files in "xfig" and then add labels with + "pinlabel". The positioning of the labels in "xfig" is hit-and-miss + and difficult to adjust: you have to keep the ".fig" file open, move + the label a little, re-export, reconvert to ".pdf", recompile, repeat + \ldots. Using "pinlabel" the label is usually positioned perfectly + first time and can be adjusted without reopening "xfig", which is far + more efficient. \subsection{overpic, labelfig, xyoverpic and WARMreader} @@ -1097,7 +1147,7 @@ because it is rarely necessary in hand constructed diagrams, but for machine generated code it is very useful indeed. For example Silvio Levy (who originated this feature) writes: -{\leftskip 15pt\rightskip 15pt``{\em I find it very convenient to +{\leftskip 15pt\rightskip 15pt\leavevmode\llap{``}{\em I find it very convenient to place (small, "mathematica"-generated) labels around a circle, say, by pinning the label at $(-\cos\theta,-\sin \theta)$ in label coordinates. This works very well.}''\par} @@ -1114,9 +1164,44 @@ placement) and then "epstopdf" to produce a ".pdf" file for inclusion in the usual way. -\section{Acknowledgements} +\section{Pinlabeler and labelpin} + +Peter Storm has written an extremely useful extension to "gv", called + "pinlabeler" which automatically copies the coordinates of the cursor + in "gv" to a text file open for editing. To be precise it writes a + line like: + +\medskip +"\pinlabel {$$} [] at XXX YYY " + +into the file at the position of the cursor (in the editor) where + " XXX YYY " are the PS coordinates of the cursor in "gv". It does this + when you click on a point in the "gv" window. This makes + transcribing coordinates much simpler: you just click on the label + position and then fill in the label and positioning code. + +You can find full details (including installation instructions) at: + +\href{http://hans.math.upenn.edu/~pstorm/pinlabeler.html}{\tt + http://hans.math.upenn.edu/\char'176pstorm/pinlabeler.html} + + +Nathan Dunfield has written a similar program "labelpin", which is a + python script and therefore, unlike Storm's program, does not need + compilation. Both work perfectly with "cygwin" under Windows + ("pinlabeler" comes ready compiled for "cygwin") and both work + perfectly with ".pdf" figures, moreover "labelpin" works on a Mac. + +The script and instructions for "labelpin" can be downloaded from: + +\href{http://www.math.uiuc.edu/~nmd/software/}{\tt + http://www.math.uiuc.edu/\char'176nmd/software/} + + + + +\section{Acknowledgements and copyright notice} - "pinlabel" is based on "geompsfi.sty" written by Silvio Levy which in turn is based on "psfig.sty" written by Trevor Darrell. Their agreement to this development is gratefully acknowledged. Silvio Levy @@ -1124,17 +1209,20 @@ has made several helpful suggestions and done extensive testing and debugging. Thanks also to Walter Neumann, Paulo Ney de Souza, Nicholas Jackson -and Noam Shomron for helpful suggestions, testing and debugging. + and Noam Shomron for helpful suggestions, testing and debugging, and + also to Mark Peletier for providing the code that reads the bounding + box from a ".pdf" file, thus making ".eps" versions of figure files + unnecessary when using "pdflatex". -\eject +\subsection*{Copyright notice} -\section{Copyright notice} The following notice appears at the start of the source file: +{\small \medskip " - Copyright 2006 Mathematical Sciences Publishers (MSP) + Copyright 2006-11 Mathematical Sciences Publishers (MSP) NOTICE @@ -1154,8 +1242,8 @@ The following notice appears at the start of the source file: It comprises the files: pinlabel.sty (this file) and the manual pinlabdoc.pdf where full documentation may be found, together with - the source files for the documentation." -} + the source files for the documentation."} + \begin{thebibliography} |