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