summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pstricks/psd-esse.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pstricks/psd-esse.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pstricks/psd-esse.tex392
1 files changed, 392 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pstricks/psd-esse.tex b/Master/texmf-dist/doc/generic/pstricks/psd-esse.tex
new file mode 100644
index 00000000000..a76636d0d3b
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pstricks/psd-esse.tex
@@ -0,0 +1,392 @@
+%% 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