diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pstricks/psd-spec.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pstricks/psd-spec.tex | 500 |
1 files changed, 500 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pstricks/psd-spec.tex b/Master/texmf-dist/doc/generic/pstricks/psd-spec.tex new file mode 100644 index 00000000000..1b7e205a311 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pstricks/psd-spec.tex @@ -0,0 +1,500 @@ +%% 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 <angle1> to <angle2>. 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 "(<r>,<a>)" 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(<x>,<y>) +\end{LVerb*} +has the effect of +\begin{LVerb*} + \psset{xunit=<x>,yunit=<y>} +\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"(<x>,<y>)" The usual Cartesian coordinate. E.g., "(3,4)". + \vitem"(<r>;<a>)" Polar coordinate, with radius $r$ and angle $a$. The +default unit for $r$ is \p{unit}. E.g., "(3;110)". + \vitem"(<node>)" The center of <node>. E.g., "(A)". + \vitem"([<par>]<node>)" The position relative to <node> determined using the +\p{angle}, \p{nodesep} and \p{offset} parameters. E.g., "([angle=45]A)". + \vitem"(!<ps>)" Raw PostScript code. <ps> 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"(<coor1>|<coor2>)" The $x$ coordinate from <coor1> and the $y$ +coordinate from <coor2>. <coor1> and <coor2> 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"<num>" A number, as usual, with units given by the \n\degrees{} command. +\vitem"(<coor>)" 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"!<ps>" Raw PostScript code. <ps> should expand to a number. The same +units are used as with <num>. +\end{description} + +\newbox\specialbox +\setbox\specialbox=\hbox{% + \bfseries + \begin{tabular}{|c|c|l|} + \hline + \emph{Coordinate} & \emph{Example} & \emph{Description} \\[2pt] + "(<x>,<y>)" & "(3,4)" & Cartesian coordinate.\\ + "(<r>;<a>)" & "(3;110)" & Polar coordinate.\\ + "(<node>)" & "(A)" & Center of <node>.\\ + "([<par>]<node>)" & "([angle=45]A)" & Relative to <node>.\\ + "(!<ps>)" & "(!5 3.3 2 exp)" & Raw PostScript.\\ + "(<coor1>|<coor2>)" & "(A|1in;30)" & Combination.\\ + \hline\hline + \emph{Angle} & \emph{Example} & \emph{Description} \\[2pt] + "<num>" & "45" & Angle.\\ + "(<coor>)" & "(-1,1)" & Coordinate (vector).\\ + "!<ps>" & "!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} <stuff> \end{overlaybox} +\end{LVerb*} + +The material for overlay <string> should go within the scope of the command + \Mac \psoverlay{string} +<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 <string>. + +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. <num> should be between 0 and 1. + \pitem[gradangle=angle] The image is rotated by <angle>. +\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} + +<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.) + +<text> 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. + +<pos> 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". + +"(<x>,<y>)" is an offset. Characters are shifted distance <x> along path, and +are shifted up by <y>. ``Up'' means with respect to the path, at whatever +point on the path corresponding to the middle of the character. "(<x>,<y>)" +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 <text> 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 <text> 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 <text> 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{<picture objects> \includegraphics{<file.eps>} +\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 + " "<stuff>\\ + \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 <stuff> as if there was a +frame around it. Thus, the bounding box will be sure to include <stuff>, 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 <llx lly urx ury> +\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 |