path: root/Master/texmf-dist/doc/generic/pstricks/psd-esse.tex

%% BEGIN psd-esse.tex

\part*{Welcome to PSTricks}

PSTricks is a collection of PostScript-based \TeX{} macros that is compatible
with most \TeX{} macro packages, including Plain \TeX, \LaTeX{} and \ConTeXt,
PSTricks gives you color, graphics, rotation, trees and overlays. PSTricks
puts the icing (PostScript) on your cake (\TeX)!

To install PSTricks, follow the instructions in the file "read-me.pst" that
comes with the PSTricks package. Even if PSTricks has already been installed
for you, give "read-me.pst" a look over.

This \emph{User's Guide} verges on being a reference manual, meaning that it is
not designed to be read linearly. Here is a recommended strategy: Finish
reading this brief overview of the features in PSTricks. Then thumb through
the entire \emph{User's Guide} to get your own overview. Return to
Part~\ref{P-essentials} (Essentials) and read it carefully. Refer to the
remaining sections as the need arises.

When you cannot figure out how to do something or when trouble arises, check
out the appendices (Help). You just might be lucky enough to find a solution.
There is also a \LaTeX{} file "samples.pst" of samples that is distributed with
PSTricks. Look to this file for further inspiration.

This documentation is written with \LaTeX. Some examples use \LaTeX{} specific
constructs and some don't. However, there is nothing \LaTeX{} specific about
any of the macros, nor is there anything that does not work with \LaTeX. This
package has been tested with Plain \TeX, \LaTeX{} and \ConTeXt{} and
should work with other \TeX{} macro packages as well.

\File{pstricks}
The main macro file is "pstricks.tex"/"pstricks.sty". Each of the PSTricks
macro files comes with a ".tex" extension and a ".sty" extension; these are
equivalent, but the ".sty" extension means that you can include the file name
as a \LaTeX{} package.

There are numerous supplementary macro files. A file, like the one above and
the left, is used in this \emph{User's Guide} to remind you that you must input
a file before using the macros it contains.

For most PSTricks macros, even if you misuse them, you will not get PostScript
errors in the output. However, it is recommended that you resolve any \TeX{}
errors before attempting to print your document. A few PSTricks macros pass on
PostScript errors without warning. Use these with care, especially if you are
using a networked printer, because PostScript errors can cause a printer to
bomb. Such macros are pointed out in strong terms, using a warning like this
one:

\begin{Warning}
Use macros that do not check for PostScript errors with care. PostScript
errors can cause a printer to bomb!
\end{Warning}

Keep in mind the following typographical conventions in this User's Guide.
\begin{itemize}
  \item All literal input characters, i.e., those that should appear verbatim
  in your input file, appear in upright "Helvetica" and {\UsageFont
  Helvetica-Bold} fonts.
  \item Meta arguments, for which you are supposed to substitute a value
  (e.g., <angle>) appear in slanted <Helvetica-Oblique> and
  {\UsageFont\MetaFont Helvetica-BoldOblique} fonts.
  \item The main entry for a macro or parameter that states its syntax appears
  in a large bold font, \emph{except for the optional arguments, which are in
    medium weight}. This is how you can recognize the optional arguments.
  \item References to PSTricks commands and parameters within paragraphs are
  set in {\UsageFont Helvetica-Bold}.

\end{itemize}

\part{The Essentials\label{P-essentials}}


\section{Arguments and delimiters}

Here is some nitty-gritty about arguments and delimiters that is really
important to know.

The PSTricks macros use the following delimiters:
\begin{center}
%% DG: to do
% Begin modification RN, 2002-12-29
\iffalse
\begin{tabular}{rl}
Curly braces & "{<arg>}" \\
Brackets (only for optional arguments) & "[<arg>]" \\
Parentheses and commas for coordinates & \c{} \\
"=" and "," for parameters & "<par1>=<val1>," \ldots\\
\end{tabular}
\fi
\begin{tabular}{rl}
Curly braces & "{"<arg>"}" \\
Brackets (only for optional arguments) & "["<arg>"]" \\
Parentheses and commas for coordinates & \c{} \\
"=" and "," for parameters & <par1>"="<val1>"," \ldots\\
\end{tabular}
% End modification RN
\end{center}
Spaces and commas are also used as delimiters within arguments, but in this
case the argument is expanded before looking for the delimiters.

Always use a period rather than a comma to denote the decimal point, so that
PSTricks doesn't mistake the comma for a delimiter.

The easiest mistake to make with the PSTricks macros is to mess up the
delimiters. This may generate complaints from \TeX{} or PSTricks about bad
arguments, or other unilluminating errors such as the following:
\begin{description}\itemsep=0pt\parsep=0pt
\item[] "! Use of \get@coor doesn't match its definition."
\item[] "! Paragraph ended before \pst@addcoor was complete."
\item[]
"! Forbidden control sequence found while scanning use of \check@arrow."
\item[] "! File ended while scanning use of \lput."
\end{description}
Delimiters are generally the first thing to check when you get errors with a
PSTricks macro.

Since PSTricks macros can have many arguments, it is useful to know that you
can leave a space or new line between any arguments, except between arguments
enclosed in curly braces. If you need to insert a new line between arguments
enclosed in curly braces, put a comment character "%" at the end of the line.

As a general rule, the first non-space character after a PSTricks macro should
not be a "[" or "(". Otherwise, PSTricks might think that the "[" or "(" is
actually part of the macro. You can always get around this by inserting a pair
"{}" of braces somewhere between the macro and the "[" or "(".


\Section{Color\label{S-color}}

The grayscales
\begin{quote}
  "black", "darkgray", "gray", "lightgray", and "white",
\end{quote}
and the colors
\begin{quote}
  "red", "green", "blue", "cyan", "magenta", and "yellow"
\end{quote}
are predefined in PSTricks.

This means that these names can be used with the graphics objects that are
described in later sections. This also means that the command \n\gray{} (or
\n\red, etc.) can be used much like "\rm" or "\tt", as in
\begin{Ex}
  \gray\Large"{\gray This stuff should be gray.}"
\end{Ex}
The commands \n\gray, \n\red, etc. can be nested like the font commands as
well. There are a few important ways in which the color commands differ from
the font commands:
\begin{enumerate}
  \item The color commands can be used in and out of math mode (there are no
  restrictions, other than proper \TeX{} grouping).
  \item The color commands affect whatever is in their scope (e.g., lines),
  not simply characters.
  \item The scope of the color commands does not extend across pages.
  \item The color commands are not as robust as font commands when used inside
  box macros. See page \pageref{colorboxproblems} for details. You can avoid
  most problems by explicitly grouping color commands (e.g., enclosing the
  scope in braces "{}") whenever these are in the argument of another
  command.\footnote{%
However, this is not necessary with the PSTricks LR-box commands, expect when
\n\psverbboxtrue{} is in effect. See Section \ref{S-boxes}.}

\end{enumerate}

You can define or redefine additional colors and grayscales with the following
commands. In each case, <numi> is a number between 0 and 1. Spaces are used as
delimiters---don't add any extraneous spaces in the arguments.

\begin{description}

\mitem \newgray{color}{num}

  <num> is the gray scale specification, to be set by PostScript's "setgray"
operator. 0 is black and 1 is white. For example:
\begin{LVerb}
  \newgray{darkgray}{.25}
\end{LVerb}

\mitem \newrgbcolor{color}{num1 num2 num3}

  <num1 num2 num3> is a \emph{red-green-blue} specification, to be set by
PostScript's "setrgbcolor" operator. For example,
\begin{LVerb}
  \newrgbcolor{green}{0 1 0}
\end{LVerb}

\mitem \newhsbcolor{color}{num1 num2 num3}

  <num1 num2 num3> is an \emph{hue-saturation-brightness} specification, to be
set by PostScript's "sethsbcolor" operator. For example,
\begin{LVerb}
  \newhsbcolor{mycolor}{.3 .7 .9}
\end{LVerb}

\mitem \newcmykcolor{color}{num1 num2 num3 num4}

  <num1 num2 num3 num4> is a \emph{cyan-magenta-yellow-black} specification, to
be set by PostScript's "newcmykcolor" operator. For example,
\begin{LVerb}
  \newcmykcolor{hercolor}{.5 1 0 .5}
\end{LVerb}

\end{description}

For defining new colors, the \emph{rbg} model is a sure thing. \emph{hsb} is not
recommended. \emph{cmyk} is not supported by all Level 1 implementations of
PostScript, although it is best for color printing. For more information on
color models and color specifications, consult the \emph{PostScript Language
Reference Manual}, 2nd Edition (Red Book), and a color guide.

\begin{drivers} The command \n\pstVerb{} must be defined.\end{drivers}


\Section{Setting graphics parameters\label{S-par}}

PSTricks uses a key-value system of graphics parameters to customize the
macros that generate graphics (e.g., lines and circles), or graphics combined
with text (e.g., framed boxes). You can change the default values of
parameters with the command \n\psset, as in
\begin{LVerb}
  \psset{fillcolor=yellow}
  \psset{linecolor=blue,framearc=.3,dash=3pt 6pt}
\end{LVerb}
The general syntax is:
  \Mac  \psset{par1=value1`,par2=value2,\ldots'}
As illustrated in the examples above, spaces are used as delimiters for some
of the values. Additional spaces are allowed only following the comma that
separates <par>"="<value> pairs (which is thus a good place to start a new
line if there are many parameter changes). E.g., the first example is
acceptable, but the second is not:
\begin{LVerb}
  \psset{fillcolor=yellow, linecolor=blue}
  \psset{fillcolor= yellow,linecolor =blue }
\end{LVerb}
The parameters are described throughout this \emph{User's Guide}, as they are
needed.

Nearly every macro that makes use of graphics parameters allows you to include
changes as an optional first argument, enclosed in square brackets.
For example,
\begin{LVerb}
  \psline[linecolor=green,linestyle=dotted](8,7)
\end{LVerb}
draws a dotted, green line. It is roughly equivalent to
\begin{LVerb}
  {\psset{linecolor=green,linestyle=dotted}\psline(8,7)}
\end{LVerb}

For many parameters, PSTricks processes the value and stores it in a peculiar
form, ready for PostScript consumption. For others, PSTricks stores the value
in a form that you would expect. In the latter case, this \emph{User's Guide}
will mention the name of the command where the value is stored. This is so
that you can use the value to set other parameters. E.g.,
\begin{LVerb}
  \psset{linecolor=\psfillcolor,doublesep=.5\pslinewidth}
\end{LVerb}
However, even for these parameters, PSTricks may do some processing and
error-checking, and you should always set them using \n\psset{} or as optional
parameter changes, rather than redefining the command where the value is
stored.

\Section{Dimensions, coordinates and angles\label{S-coor}}

Whenever an argument of a PSTricks macro is a dimension, the unit is optional.
The default unit is set by the
\begin{Ex}
  \Par{unit=dim}   (1cm)
\end{Ex}
parameter. For example, with the default value of "1cm", the following are
equivalent:
\begin{LVerb}
  \psset{linewidth=.5cm}
  \psset{linewidth=.5}
\end{LVerb}
By never explicitly giving units, you can scale graphics by changing the value
of \p{unit}.

You can use the default coordinate when setting non-PSTricks dimensions as
well, using the commands
\begin{Ex}
  \object  \pssetlength{cmd}{dim}
  \object  \psaddtolength{cmd}{dim}
\end{Ex}
where <cmd> is a dimension register (in \LaTeX{} parlance, a ``length''), and
<dim> is a length with optional unit. These are analogous to \LaTeX's
"\setlength" and "\addtolength".

Coordinate pairs have the form \c{}. The origin of the coordinate system is at
\TeX's currentpoint. The command \n\SpecialCoor{} lets you use polar
coordinates, in the form "(<r>;<a>)", where <r> is the radius (a dimension)
and <a> is the angle (see below). You can still use Cartesian coordinates. For
a complete description of \n\SpecialCoor, see Section \ref{S-SpecialCoor}.

The \p{unit} parameter actually sets the following three parameters:
\begin{Ex}
  \Par{xunit=dim}  (1cm)
  \Par{yunit=dim}  (1cm)
  \Par{runit=dim}  (1cm)
\end{Ex}
These are the default units for x-coordinates, y-coordinates, and all other
coordinates, respectively. By setting these independently, you can scale the x
and y dimensions in Cartesian coordinate unevenly. After changing \p{yunit} to
"1pt", the two \n\psline's below are equivalent:
\begin{LVerb}
  \psset{yunit=1pt}
  \psline(0cm,20pt)(5cm,80pt)
  \psline(0,20)(5,80)
\end{LVerb}

The values of the \p{runit}, \p{xunit} and \p{yunit} parameters are stored in
the dimension registers \n\psunit{} (also \n\psrunit), \n\psxunit{} and
\n\psyunit.

Angles, in polar coordinates and other arguments, should be a number giving
the angle in degrees, by default. You can also change the units used for
angles with the command
  \Mac  \degrees`[num]'
<num> should be the number of units in a circle. For example, you might use
\begin{LVerb}
  \degrees[100]
\end{LVerb}
to make a pie chart when you know the shares in percentages. \n\degrees{}
without the argument is the same as
\begin{LVerb}
  \degrees[360]
\end{LVerb}
The command
  \Mac  \radians
is short for
\begin{Ex}
  "\degrees[6.28319]"
\end{Ex}
\n\SpecialCoor{} lets you specify angles in other ways as well.

\Section{Basic graphics parameters}

The width and color of lines is set by the parameters:
\begin{Ex}
  \Par{linewidth=dim}
  \Par{linecolor=color}
\end{Ex}
The \p{linewidth} is stored in the dimension register \n\pslinewidth, and the
\p{linecolor} is stored in the command \n\pslinecolor.

The regions delimited by open and closed curves can be filled, as determined
by the parameters:
\begin{Ex}
  \p{fillstyle=<style>}\\
  \p{fillcolor=<color>}
\end{Ex}
When \p{fillstyle=none}, the regions are not filled. When \p{fillstyle=solid},
the regions are filled with \p{fillcolor}. Other \p{fillstyle}'s are described
in Section \ref{S-fillstyles}.

The graphics objects all have a starred version (e.g., \n\psframe*) which
draws a solid object whose color is \p{linecolor}. For example,
\begin{MEx}(2,1)
  \psellipse*(1,.5)(1,.5)
\end{MEx}

Open curves can have arrows, according to the
\begin{Ex}
  \p{arrows=<arrows>}
\end{Ex}
parameter. If \p{arrows=-}, you get no arrows.
\begingroup
\catcode`\<=12
If \p{arrows=<->}, you get arrows on both ends of the curve. You can also set
\p{arrows=->} and \p{arrows=<-},
\endgroup
if you just want an arrow on the end or beginning of the curve, respectively.
With the open curves, you can also specify the arrows as an optional argument
enclosed in "{}" brackets. This should come after the optional parameters
argument. E.g.,
\begin{MEx}(2,1)
  \psline[linewidth=2pt]{<-}(2,1)
\end{MEx}
Other arrow styles are described in Section \ref{S-arrows}

If you set the
\begin{Ex}
  \Par{showpoints=true/false}
\end{Ex}
parameter to "true", then most of the graphics objects will put dots at the
appropriate coordinates or control points of the object.\footnote{%
The parameter value is stored in the conditional "\ifshowpoints".}
Section \ref{S-dots} describes how to change the dot style.

\endinput

%% END psd-esse.tex