summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pstricks/psd-spec.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pstricks/psd-spec.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pstricks/psd-spec.tex500
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