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