%% BEGIN psd-spec.tex \part{Special Tricks\label{P-special}} \Section{Coils and zigzags} \File{pst-coil} The file "pst-coil.tex"/"pst-coil.sty" (and optionally the header file "pst-coil.pro") defines the following graphics objects for coils and zigzags: \begin{Ex} \object \pscoil`*[par]{arrows}\c0'\c1 \object \psCoil`*[par]'{angle1}{angle2} \object \pszigzag`*[par]{arrows}\c0'\c1 \end{Ex} These graphics objects use the following parameters: \begin{Ex} \Par{coilwidth=dim} \Par{coilheight=num} \Par{coilarm=dim} \Par{coilaspect=angle} \Par{coilinc=angle} \end{Ex} All coil and zigzag objects draw a coil or zigzag whose width (diameter) is \p{coilwidth}, and with the distance along the axes for each period (360 degrees) equal to \begin{quote} \p{coilheight} x \p{coilwidth}. \end{quote} Both \n\pscoil{} and \n\psCoil{} draw a ``3D'' coil, projected onto the xz-axes. The center of the 3D coil lies on the yz-plane at angle p{coilaspect} to the z-axis. The coil is drawn with PostScript's "lineto", joining points that lie at angle \p{coilinc} from each other along the coil. Hence, increasing \p{coilinc} makes the curve smoother but the printing slower. \n\pszigzag\ does not use the \p{coilaspect} and \p{coilinc} parameters. \n\pscoil{} and \n\pszigzag{} connect \c0 and \c1, starting and ending with straight line segments of length \p{coilarmA} and \p{coilarmB}, resp. Setting \p{coilarm} is the same as setting \p{coilarmA} and \p{coilarmB}. Here is an example of \n\pscoil: \begin{MEx}(4,2) \pscoil[coilarm=.5cm,linewidth=1.5pt,coilwidth=.5cm]{<-|}(4,2) \end{MEx} Here is an example of \n\pszigzag: \begin{MEx}[0,-.5](4,.5) \pszigzag[coilarm=.5,linearc=.1]{<->}(4,0) \end{MEx} Note that \n\pszigzag{} uses the \p{linearc} parameters, and that the beginning and ending segments may be longer than \p{coilarm} to take up slack. \n\psCoil{} just draws the coil horizontally from to . Use \n\rput{} to rotate and translate the coil, if desired. \n\psCoil{} does not use the \p{coilarm} parameter. For example, with \p{coilaspect=0} we get a sine curve: \begin{MEx}[0,-.375](4,.375) \psCoil[coilaspect=0,coilheight=1.33, coilwidth=.75,linewidth=1.5pt]{0}{1440} \end{MEx} \File{pst-node} "pst-coil.tex" also contains coil and zigzag node connections. You must also load "pst-node.tex" / "pst-node.sty" to use these. The node connections are: \begin{Ex} \object \nccoil`*[par]{arrows}'{nodeA}{nodeB} \object \nczigzag`*[par]{arrows}'{nodeA}{nodeB} \object \pccoil`*[par]{arrows}'\c1\c2 \object \pczigzag`*[par]{arrows}'\c1\c2 \end{Ex} The end points are chosen the same as for \n\ncline{} and \n\pcline, and otherwise these commands work like \n\pscoil{} and \n\pszigzag. For example: \begin{MEx}(4,3) \cnode(.5,.5){.5}{A} \cnode[fillstyle=solid,fillcolor=lightgray](3.5,2.5){.5}{B} \nccoil[coilwidth=.3]{<->}{A}{B} \end{MEx} \Section{Special coordinates\label{S-SpecialCoor}} The command \Mac \SpecialCoor enables a special feature that lets you specify coordinates in a variety of ways, in addition to the usual Cartesian coordinates.\footnote{% There is an obsolete command \n\Polar\MainIndex\Polar{} that causes coordinates in the form "(,)" to be interpreted as polar coordinates. The use of \n\Polar{} is not recommended because it does not allow one to mix Cartesian and polar coordinates the way \n\SpecialCoor{} does, and because it is not as apparent when examining an input file whether, e.g., "(3,2)" is a Cartesian or polar coordinate. The command for undoing \n\Polar{} is \n\Cartesian\MainIndex\Cartesian. It has an optional argument for setting the default units. I.e., \begin{LVerb*} \Cartesian(,) \end{LVerb*} has the effect of \begin{LVerb*} \psset{xunit=,yunit=} \end{LVerb*} \n\Cartesian{} can be used for this purpose without using \n\Polar.} Processing is slightly slower and less robust, which is why this feature is available on demand rather than by default, but you probably won't notice the difference. Here are the coordinates you can use: \begin{description} \vitem"(,)" The usual Cartesian coordinate. E.g., "(3,4)". \vitem"(;)" Polar coordinate, with radius $r$ and angle $a$. The default unit for $r$ is \p{unit}. E.g., "(3;110)". \vitem"()" The center of . E.g., "(A)". \vitem"([])" The position relative to determined using the \p{angle}, \p{nodesep} and \p{offset} parameters. E.g., "([angle=45]A)". \vitem"(!)" Raw PostScript code. should expand to a coordinate pair. The units \p{xunit} and \p{yunit} are used. For example, if I want to use a polar coordinate $(3,110)$ that is scaled along with \p{xunit} and \p{yunit}, I can write \begin{LVerb} (!3 110 cos mul 3 110 sin mul) \end{LVerb} \vitem"(|)" The $x$ coordinate from and the $y$ coordinate from . and can be any other coordinates for use with \n\SpecialCoor. For example, "(A|1in;30)". \end{description} \n\SpecialCoor{} also lets you specify angles in several ways: \begin{description} \vitem"" A number, as usual, with units given by the \n\degrees{} command. \vitem"()" A coordinate, indicating where the angle points to. Be sure to include the "()", in addition to whatever other delimiters the angle argument uses. For example, the following are two ways to draw an arc of .8 inch radius from 0 to 135 degrees: \begin{MEx}(3,2) \SpecialCoor \psarc(0,0){.8in}{0}{135} \psarc(0,0){.8in}{0}{(-1,1)} \end{MEx} \vitem"!" Raw PostScript code. should expand to a number. The same units are used as with . \end{description} \newbox\specialbox \setbox\specialbox=\hbox{% \bfseries \begin{tabular}{|c|c|l|} \hline \emph{Coordinate} & \emph{Example} & \emph{Description} \\[2pt] "(,)" & "(3,4)" & Cartesian coordinate.\\ "(;)" & "(3;110)" & Polar coordinate.\\ "()" & "(A)" & Center of .\\ "([])" & "([angle=45]A)" & Relative to .\\ "(!)" & "(!5 3.3 2 exp)" & Raw PostScript.\\ "(|)" & "(A|1in;30)" & Combination.\\ \hline\hline \emph{Angle} & \emph{Example} & \emph{Description} \\[2pt] "" & "45" & Angle.\\ "()" & "(-1,1)" & Coordinate (vector).\\ "!" & "!33 sqrt" & Raw PostScript.\\ \hline \end{tabular}}% \addtoquickref{center}{% {\large\textbf{Special coordinates and angles}}\par \leavevmode\box\specialbox} The command \Mac \NormalCoor disables the \n\SpecialCoor{} features. \Section{Overlays\label{S-overlays}} Overlays are mainly of interest for making slides, and the overlay macros described in this section are mainly of interest to \TeX{} macro writers who want to implement overlays in a slide macro package. For example, the "seminar.sty" package, a \LaTeX{} style for notes and slides, uses PSTricks to implement overlays. Overlays are made by creating an "\hbox" and then outputting the box several times, printing different material in the box each time. The box is created by the commands \Mac \overlaybox < stuff >\Main\endoverlaybox \LaTeX{} users can instead write: \begin{LVerb*} \begin{overlaybox} \end{overlaybox} \end{LVerb*} The material for overlay should go within the scope of the command \Mac \psoverlay{string} can be any string, after expansion. Anything not in the scope of any \n\psoverlay{} command goes on overlay "main", and material within the scope of {\UsageFont "\psoverlay{all}"} goes on all the overlays. \n\psoverlay\ commands can be nested and can be used in math mode. The command \Mac \putoverlaybox{string} then prints overlay . Here is an example: \begin{example} \overlaybox \psoverlay{all} \psframebox[framearc=.15,linewidth=1.5pt]{% \psoverlay{main} \parbox{3.5cm}{\raggedright Foam Cups Damage Environment {\psoverlay{one} Less than Paper Cups,} Study Says.}} \endoverlaybox \putoverlaybox{main} \hspace{.5in} \putoverlaybox{one} \end{example} \begin{drivers} Overlays use \n\pstVerb{} and \n\pstverbscale.\end{drivers} \section{The gradient fill style} \File{pst-grad} The file "pst-grad.tex"/"pst-grad.sty", along with the PostScript header file "pst-grad.pro", defines the "gradient" \p{fillstyle}, for gradiated shading. This \p{fillstyle} uses the following parameters: \begin{description} \pitem[gradbegin=color] The starting and ending color. \pitem[gradend=color] The color at the midpoint. \pitem[gradlines=int] The number of lines. More lines means finer gradiation, but slower printing. \pitem[gradmidpoint=num] The position of the midpoint, as a fraction of the distance from top to bottom. should be between 0 and 1. \pitem[gradangle=angle] The image is rotated by . \end{description} \p{gradbegin} and \p{gradend} should preferably be "rgb" colors, but grays and "cmyk" colors should also work. The definitions of the colors "gradbegin" and "gradend" are: \begin{LVerb} \newrgbcolor{gradbegin}{0 .1 .95} \newrgbcolor{gradend}{0 1 1} \end{LVerb} Here are two ways to change the gradient colors: \begin{LVerb} \newrgbcolor{gradbegin}{1 .4 0} \end{LVerb} and \begin{LVerb} \psset{gradbegin=blue} \end{LVerb} Try this example: \begin{LVerb} \psframe[fillstyle=gradient,gradangle=45](10,-20) \end{LVerb} % D.G. modification begin - Mar. 7, 2003 %\section{Adding color to tables\label{S-colortab}} %\File{colortab} %The file "colortab.tex"/"colortab.sty" contains macros that, when used with %color commands such as those in PSTricks, let you color the cells and lines in %tables. See "colortab.doc" for more information. % D.G. modification end \Section{Typesetting text along a path} \File{pst-text} The file "pst-text.tex"/"pst-text.sty" defines the command \n\pstextpath, for typesetting text along a path. It is a remarkable trick, but there are some caveats: \begin{itemize}\label{tp-res} \item "pst-text.tex" only works with certain DVI-to-PS drivers. Here is what is currently known: \begin{itemize} \item It works with Rokicki's "dvips". \item ``Does not work'' means that it has no effect, for better or for worse. \item This may work with other drivers. The requirement is that the driver only use PostScript's "show" operator, unbound and unloaded, to show characters. \end{itemize} \item You must also have installed the PostScript header file "pst-text.pro", and \n\pstheader{} must be properly defined in "pstricks.con" for your driver. \item Like other PSTricks that involve rotating text, this works best with PostScript (outline) fonts. \item PostScript rendering with "pst-text.tex" is slow. \end{itemize} Because of all this, no samples are shown here. However, there is a test file "tp-test.tex" and PostScript output "tp-test.ps" that are distributed with PSTricks. Here is the command: \Mac \pstextpath`[pos](x,y)'{graphics object}{text} is placed along the path, from beginning to end, defined by the PSTricks graphics object. (This object otherwise behaves normally. Set \p{linestyle=none} if you don't want it to appear.) can only contain characters. No TeX{} rules, no PSTricks, and no other "\special"'s. (These things don't cause errors; they just don't work right.) Math mode is OK, but math operators that are built from several characters (e.g., large integral signs) may break. Entire boxes (e.g., "\parbox") are OK too, but this is mainly for amusement. is either \begin{center} \begin{tabular}{cl} l & justify on beginning of path\\ c & center on path\\ r & justify on end of path. \end{tabular} \end{center} The default is "l". "(,)" is an offset. Characters are shifted distance along path, and are shifted up by . ``Up'' means with respect to the path, at whatever point on the path corresponding to the middle of the character. "(,)" must be Cartesian coordinates. Both coordinates use \n\psunit{} as the default. The default coordinate is "(0,\TPoffset)", where \n\TPoffset{} a command whose default value is "-.7ex". This value leads to good spacing of the characters. Remember that "ex" units are for the font in effect when \n\pstextpath{} occurs, not inside the argument. More things you might want to know: \begin{itemize} \item Like with "\rput" and the graphics objects, it is up to you to leave space for "\pstextpath". \item Results are unpredictable if is wider than length of path. \item "\pstextpath" leaves the typesetting to \TeX. It just intercepts the "show" operator to remap the coordinate system. \end{itemize} \Section{Stroking and filling character paths} \File{pst-char} The file "pst-char.tex"/"pst-char.sty" defines the command: \Mac \pscharpath`*[par]'{text} It strokes and fills the character paths using the PSTricks \p{linestyle} and \p{fillstyle}. The restrictions on DVI-to-PS drivers listed on page \pageref{tp-res} for "\pstextpath" apply to "\pscharpath". Furthermore, only outline (PostScript) fonts are affected. Sample input and output files "chartest.tex" and "chartest.ps" are distributed with PSTricks. With the optional "*", the character path is not removed from the PostScript environment at the end. This is mainly for special hacks. For example, you can use "\pscharpath*" in the first argument of "\pstextpath", and thus typeset text along the character path of some other text. See the sample file "denis1.tex". (However, you cannot combine "\pscharpath" and "\pstextpath" in any other way. E.g., you cannot typeset character outlines along a path, and then fill and stroke the outlines with "\pscharpath".) The command \Mac \pscharclip`*[par]'{text} ... \Main \endpscharclip works just like \n\pscharpath, but it also sets the clipping path to the character path. You may want to position this clipping path using \n\rput{} \emph{inside} \n\pscharclip's argument. Like \n\psclip{} and \n\endpsclip, \n\pscharclip{} and \n\endpscharclip{} should come on the same page and should be properly nested with respect to \TeX{} groups (unless \n\AltClipMode{} is in effect). The file "denis2.tex" contains a sample of \n\pscharclip. \section{Importing EPS files} PSTricks does not come with any facility for including Encapsulated PostScript files, because there are other very good and well-tested macros for exactly that, specially the "graphicx" package for \LaTeX, usable also with \TeX. What PSTricks \emph{is} good for is embellishing your EPS picture. You can include an EPS file in in the argument of \n\rput, as in \begin{LVerb} \rput(3,3){\epsfbox{myfile.eps}} \end{LVerb} and hence you can include an EPS file in the \n\pspicture{} environment. Turn on \n\psgrid, and you can find the coordinates for whatever graphics or text you want to add. This works even when the picture has a weird bounding box, because with the arguments to \n\pspicture{} you control the bounding box from \TeX's point of view. This isn't always the best way to work with an EPS file, however. If the PostScript file's bounding box is the size you want the resulting picture to be, after your additions, then try \begin{LVerb*} \hbox{ \includegraphics{} \end{LVerb*} This will put all your picture objects at the lower left corner of the EPS file. If you need to determine the bounding box of an EPS file, then you can try of the automatic bounding box calculating programs, such as "bbfig" (distributed with Rokicki's "dvips"). However, all such programs are easily fooled; the only sure way to determine the bounding box is visually. \n\psgrid{} is a good tool for this. \Section{Exporting EPS files} \File{pst-eps} You must load "pst-eps.tex" or "pst-eps.sty" to use the PSTricks macros described in this section. If you want to export an EPS file that contains both graphics and text, then you need to be using a DVI-to-PS driver that suports such a feature. If you just want to export pure graphics, then you can use the \n\PSTricksEPS{} command. Both of these options are described in this section. Newer versions of Rokicki's "dvips" support an "-E" option for creating EPS files from \TeX{} ".dvi" files. E.g., \[ dvips foo.dvi -E -o foo.eps \] Your document should be a single page. "dvips" will find a tight bounding box that just encloses the printed characters on the page. This works best with outline (PostScript) fonts, so that the EPS file is scalable and resolution independent. There are two inconvenient aspects of this method. You may want a different bounding box than the one calculated by "dvips" (in particular, "dvips" ignores all the PostScript generated by PSTricks when calculating the bounding box), and you may have to go out of your way to turn off any headers and footers that would be added by output routines. PSTricks contains an environment that tries to get around these two problems: \begin{Ex} \object \TeXtoEPS " "\\ \object \endTeXtoEPS \end{Ex} This is all that should appear in your document, but headers and whatever that would normally be added by output routines are ignored. "dvips" will again try to find a tight bounding box, but it will treat as if there was a frame around it. Thus, the bounding box will be sure to include , but might be larger if there is output outside the boundaries of this box. If the bounding box still isn't right, then you will have to edit the \begin{LVerb*} %%BoundingBox \end{LVerb*} specification in the EPS file by hand. If your goal is to make an EPS file for inclusion in other documents, then "dvips -E" is the way to go. However, it can also be useful to generate an EPS file from PSTricks graphics objects and include it in the same document,% \footnote{See the preceding section on importing EPS files.} rather than just including the PSTricks graphics directly, because \TeX{} gets involved with processing the PSTricks graphics only when the EPS file is initially created or updated. Hence, you can edit your file and preview the graphics, without having to process all the PSTricks graphics each time you correct a typo. This speed-up can be significant with complex graphics such as "\pslistplot"'s with a lot of data. To create an EPS file from PSTricks graphics objects, use \Mac \PSTtoEPS`[par]'{file}{graphics objects} The file is created immediately, and hence you can include it in the same document (after the \n\PSTtoEPS{} command) and as many times as you want. Unlike with "dvips -E", only pure graphics objects are processed (e.g., "\rput" commands have no effect). \n\PSTtoEPS{} cannot calculate the bounding box of the EPS file. You have to specify it yourself, by setting the following parameters: \begin{Ex} \Par{bbllx=dim} \Par{bblly=dim} \Par{bburx=dim} \Par{bbury=dim} \end{Ex} Note that if the EPS file is only to be included in a PSTricks picture with \n\rput\, you might as well leave the default bounding box. \n\PSTricksEPS{} also uses the following parameters: \begin{description} \pitem[makeeps=none/new/all/all*] This parameter determines which \n\PSTtoEPS\ commands just skip over their arguments, and which create files, as follows: \begin{description} \vitem"none" No files are created. \vitem"new" Only those files not found {\em anywhere on the system\/} are created. \vitem"all" All files are created. \vitem"all*" All files are created, but you are asked for approval before existing files are deleted. \end{description} \pitem[headerfile=files] This parameter is for specifying PostScript header files that are to be included in the EPS file. The argument should contain one or more file names, separated by commas. If you have more than one file, however, the entire list must be enclosed in braces "{}". \pitem[headers=none/all/user] When "none", no header files are included. When "all", the header files used by PSTricks plus the header files specified by the \p{headerfile} parameter are included. When "user", only the header files specified by the \p{headerfile} parameter are included. If the EPS file is to be included in a \TeX{} document that uses the same PSTricks macros and hence loads the relevant PSTricks header files anyway (in particular, if the EPS file is to be included in the same document), then \p{headers} should be "none" or "user". \end{description} \endinput %% END psd-spec.tex