diff options
| author | Manuel Pégourié-Gonnard <mpg@elzevir.fr> | 2008-06-21 14:42:14 +0000 |
|---|---|---|
| committer | Manuel Pégourié-Gonnard <mpg@elzevir.fr> | 2008-06-21 14:42:14 +0000 |
| commit | 836f497d5ba479fdc19164951941f051cdd804d0 (patch) | |
| tree | f90cd5cb3cf497aea05d961315c26bad32ac7471 /Master/texmf-dist/doc | |
| parent | 4683bcefcc8e380dda5f46ff09833a4b9b7f7804 (diff) | |
pstricks update
git-svn-id: svn://tug.org/texlive/trunk@8901 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc')
20 files changed, 7074 insertions, 28 deletions
diff --git a/Master/texmf-dist/doc/generic/pstricks/Changes.dvips b/Master/texmf-dist/doc/generic/pstricks/Changes.dvips new file mode 100644 index 00000000000..70c6a76dbe0 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pstricks/Changes.dvips @@ -0,0 +1,33 @@ +---- pstricks.pro +1.04 2008-05-11 - added Rand for a real random 0<=Rand<=1 +1.03 2008-04-15 - only some cosmetics to the code +1.02 2008-01-01 - added the arrowtype D>, sides as curves (ArrowD) + - added the whole algebraic parser stuff + - added function tan := sin cos div + - added function Tan := sin cos Div + - added Pyth2 for 2 points given by xA yA xB yB + - change variable names from x,y to xOrig, yOrig for + EllipticArcArrow + - move font setting for \psgrid into pstricks.tex +1.01 2006-01-11 (vg) fix a bug with ArcAdjust when both angles ares negative + add Sqrt sunction +1.00 2005-09-19 move the code for arcs of an ellipse from + the main pstricks.tex into this pro +97, patch 7 2005-09-11 added new fillstyles +97, patch 6 2005-05-17 added some helper stuff + RadtoDeg, DegtoRad, Pi, TwoPi, ATAN +97, patch 5 2005-03-08 bugfix for DashLine + + +---- pst-text.pro +1.00 2005-11-29 add a patch for japanese text (hv) + + +---- pst-dots.pro +2.02 2008-04-19 add octogon symbol (hv) +2.01 2008-04-18 add some comments to the code (hv) +2.00 2006-12-19 add more dot symbols from Etienne Riga (hv) + + +---- pst-alpparser.pro +0.01 2008-01-01 initial version (hv) diff --git a/Master/texmf-dist/doc/generic/pstricks/Makefile b/Master/texmf-dist/doc/generic/pstricks/Makefile index 38c4f089a4f..ce772c9e8cd 100644 --- a/Master/texmf-dist/doc/generic/pstricks/Makefile +++ b/Master/texmf-dist/doc/generic/pstricks/Makefile @@ -1,48 +1,97 @@ -# `Makefile' for `pst-3dplot.pdf', hv, 2007/03/17 +# Rolf Niepraschk, niepraschk@ptb.de, 2003-02-23 -.SUFFIXES : .tex .ltx .dvi .ps .pdf .eps +.SUFFIXES : .tex .dvi .ps .pdf .eps -PACKAGE = pst-news2008 - -MAIN = $(PACKAGE) +MAIN = pst-user +# D.G. modification begin - Feb. 28, 2003 +#LATEX = elatex LATEX = latex +# D.G. modification end +PDFLATEX = pdfelatex +PS2PDF = ps2pdf -ARCHNAME = $(MAIN)-$(shell date +%y%m%d) +# D.G. modification begin - Feb. 28, 2003 +PS2PDF_OPT1 = -sPAPERSIZE=letter +#PS2PDF_OPT1 = -sPAPERSIZE=a4 +# D.G. modification end +PS2PDF_OPT2 = -sPAPERSIZE=letter -ARCHFILES = $(PACKAGE).sty $(PACKAGE).tex $(PACKAGE).pro $(MAIN).tex README Changes Makefile +DVIPSFLAGS1 = -Ppdf -G0 +DVIPSFLAGS2 = -Pwww -E +#GSOPT = GS_OPTIONS=-dAutoRotatePages=/None +GSOPT = GS_OPTIONS=-dPDFSETTINGS=/prepress -all : doc clean -doc: $(MAIN).pdf +PICS := $(PICS:.eps=.pdf) -$(MAIN).pdf : $(MAIN).ps - GS_OPTIONS=-dAutoRotatePages=/None ps2pdf $< +# D.G. modification begin - Mar. 7, 2003 +#ADDINPUTS = pst-user.cls defaults.pst +ADDINPUTS = pst-user.cls defaults.pst \ + psd-cove.tex psd-esse.tex psd-basi.tex psd-para.tex psd-cust.tex \ + psd-pict.tex psd-text.tex psd-node.tex psd-tree.tex psd-fill.tex \ + psd-3d.tex psd-spec.tex psd-help.tex +# D.G. modification end -$(MAIN).ps : $(MAIN).dvi - dvips $< +ARCHNAME = $(MAIN)-$(shell date +%y%m%d).zip -$(MAIN).dvi : $(MAIN).tex - $(LATEX) $< - $(LATEX) $< - if ! test -f $(basename $<).glo ; then touch $(basename $<).glo; fi - if ! test -f $(basename $<).idx ; then touch $(basename $<).idx; fi - makeindex -s gglo.ist -t $(basename $<).glg -o $(basename $<).gls \ - $(basename $<).glo - makeindex -t $(basename $<).ilg -o $(basename $<).ind \ - $(basename $<).idx - bibtex $(basename $<) +# D.G. modification begin - Mar. 7, 2003 +TARNAME = $(MAIN)-$(shell date +%y%m%d).tar +# D.G. modification end + +# D.G. modification begin - Feb. 28, 2003 +#all : $(MAIN).pdf $(MAIN)-old.pdf +all : $(MAIN).pdf +# D.G. modification end + + +$(MAIN).dvi : $(MAIN).tex $(ADDINPUTS) $(LATEX) $< +# D.G. modification begin - Feb. 28, 2003 +# makeindex -t $(basename $<).ilg $(basename $<) +# D.G. modification end + makeindex -t $(basename $<).ilg -s pst-user.ist $(basename $<) $(LATEX) $< +$(MAIN).pdf : $(MAIN).ps + $(PS2PDF) $(PS2PDF_OPT1) $< $@ + +%.ps : %.dvi + dvips $(DVIPSFLAGS1) $< -o $@ + +pst-user-old.pdf : pst-user-old.tex pst-usr1.pdf pst-usr2.pdf pst-usr3.pdf \ + pst-usr4.pdf + $(PDFLATEX) $< + +pst-usr%.pdf : pst-usr%.ps.gz + zcat $< | $(PS2PDF) $(PS2PDF_OPT2) - > $@ + clean : - $(RM) $(addprefix $(MAIN), .log .aux .glg .glo .gls .ilg .idx .ind .tmp .toc .out .blg .Roessler .bbl ) - $(RM) $(addprefix $(MAIN), .dvi .ps) + $(RM) $(addprefix $(MAIN), .aux .ilg .ind .idx .log .out .tmp .toc) +# D.G. modification begin - Mar. 7, 2003 +# $(RM) $(addprefix $(MAIN)-old, .log .aux) +# $(RM) pst-usr?.pdf +# D.G. modification end veryclean : clean - $(RM) $(addprefix $(MAIN), .pdf .bbl .blg) + $(RM) $(addprefix $(MAIN), .ps .dvi .pdf) +# D.G. modification begin - Mar. 7, 2003 +# $(RM) $(MAIN)-old.pdf + $(RM) *.aux +# D.G. modification end arch : - zip $(ARCHNAME).zip $(ARCHFILES) + zip $(ARCHNAME) $(MAIN).tex $(ADDINPUTS) pst-user-old.tex Makefile + @ echo ; echo $(ARCHNAME) ; echo -# EOF +# D.G. modification begin - Mar. 7, 2003 +tar: + tar -cf $(TARNAME) $(MAIN).tex $(ADDINPUTS) \ + pst-user.ist pst-user.idx \ + CHANGES VERSIONS TODO \ + Makefile artistic.txt defaults.pst \ + pstricks.tex pst-eps.tex pst-node.tex pst-tree.tex \ + *.sty pst-user.pdf + gzip --force $(TARNAME) + ls -l $(TARNAME).gz +# D.G. modification end diff --git a/Master/texmf-dist/doc/generic/pstricks/defaults.pst b/Master/texmf-dist/doc/generic/pstricks/defaults.pst new file mode 100644 index 00000000000..4e3ba5f27f2 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pstricks/defaults.pst @@ -0,0 +1,149 @@ +%% defaults.pst +%% Created with unix shell commands: +%% grep ^.psset\@ pstricks.tex > defaults.pst +%% grep ^.psset\@ pst-node.tex >> defaults.pst +%% grep ^.psset\@ pst-grad.tex >> defaults.pst +%% grep ^.psset\@ pst-coil.tex >> defaults.pst +%% grep ^.psset\@ pst-eps.tex >> defaults.pst +%% grep ^.psset\@ pst-plot.tex >> defaults.pst +%% grep ^.psset\@ pst-tree.tex >> defaults.pst +%% Input by pst-user.tex +\psset@swapaxes{false} +\psset@showpoints{false} +\psset@border{0pt} +\psset@bordercolor{white} +\psset@doubleline{false} +\psset@doublesep{1.25\pslinewidth} +\psset@doublecolor{white} +\psset@shadow{false} +\psset@shadowsize{3pt} +\psset@shadowangle{-45} +\psset@shadowcolor{darkgray} +\psset@linewidth{.8pt} +\psset@linecolor{black} +\psset@dash{5pt 3pt} +\psset@dashadjust{true} +\psset@dotsep{3pt} +\psset@linestyle{solid} +\psset@fillcolor{white} +\psset@hatchwidth{.8pt} +\psset@hatchsep{4pt} +\psset@hatchcolor{black} +\psset@hatchangle{45} +\psset@fillstyle{none} +\psset@arrowscale{1} +\psset@arrowsize{1.5pt 2} +\psset@arrowlength{1.4} +\psset@arrowinset{.4} +\psset@tbarsize{2pt 5} +\psset@bracketlength{.15} +\psset@rbracketlength{.15} +\psset@arrows{-} +\psset@liftpen{0} +\psset@linetype{0} +\psset@gangle{0} +\psset@curvature{1 .1 0} +\psset@dotsize{2pt 2} +\psset@dotscale{1} +\psset@dotangle{0} +\psset@dotstyle{*} +\psset@linearc{0pt} +\psset@framearc{0} +\psset@cornersize{relative} +\psset@dimen{outer} +\psset@gridwidth{.8pt} +\psset@griddots{0} +\psset@gridcolor{black} +\psset@subgridwidth{.4pt} +\psset@subgridcolor{gray} +\psset@subgriddots{0} +\psset@subgriddiv{5} +\psset@gridlabels{10pt} +\psset@gridlabelcolor{black} +\psset@framesep{3pt} +\psset@boxsep{true} +\psset@trimode{U} +\psset@arcsep{0} +\psset@radius{.25cm} +\psset@ref{c} +\psset@rot{0} +\psset@labelsep{5pt} +\psset@refangle{0} +\psset@nodealign{false} +\psset@href{0} +\psset@vref{.7ex} +\psset@framesize{10pt} +\psset@nodesep{0pt} +\psset@arm{10pt} +\psset@offset{0pt} +\psset@angle{0} +\psset@arcangle{8} +\psset@ncurv{.67} +\psset@loopsize{1cm} +\psset@boxsize{.4cm} +\psset@nrot{0} +\psset@npos{} +\psset@tpos{.5} +\psset@shortput{none} +\psset@colsep{1.5cm} +\psset@rowsep{1.5cm} +\psset@mcol{c} +\psset@mnodesize{-1pt} +\psset@mnode{R} +\psset@emnode{none} +\psset@gradbegin{gradbegin} +\psset@gradend{gradend} +\psset@gradlines{500} +\psset@gradmidpoint{.9} +\psset@gradangle{0} +\psset@coilwidth{1cm} +\psset@coilheight{1} +\psset@coilarm{.5cm} +\psset@coilaspect{45} +\psset@coilinc{10} +\psset@bbllx{0pt} +\psset@bblly{0pt} +\psset@bburx{0pt} +\psset@bbury{0pt} +\psset@headers{none} +\psset@checkfile{true} +\psset@makeeps{new} +\psset@headerfile{} +\psset@plotstyle{line} +\psset@plotpoints{50} +\psset@ticksize{3pt} +\psset@tickstyle{full} +\psset@ticks{all} +\psset@labels{all} +\psset@Ox{0} +\psset@Dx{1} +\psset@dx{0} +\psset@Oy{0} +\psset@Dy{1} +\psset@dy{0} +\psset@showorigin{true} +\psset@axesstyle{axes} +\psset@treemode{D} +\psset@treeflip{false} +\psset@root{\TC} +\psset@treesep{.75cm} +\psset@xtreesep{0pt} +\psset@treenodesize{-1pt} +\psset@treefit{tight} +\psset@treerep{1} +\psset@showbbox{false} +\psset@levelsep{2cm} +\psset@varlevelsep{false} +\psset@treeshift{0} +\psset@skiplevels{0} +\psset@unary{middle} +\psset@leafalign{false} +\psset@edge{\ncline} +\psset@skipedge{} +\psset@fansize{1cm} +\psset@tnsep{} +\psset@tnyref{} +\psset@tnheight{\ht\strutbox} +\psset@tndepth{\dp\strutbox} +\psset@tnpos{} +\endinput diff --git a/Master/texmf-dist/doc/generic/pstricks/psd-3d.tex b/Master/texmf-dist/doc/generic/pstricks/psd-3d.tex new file mode 100644 index 00000000000..9837db6e91f --- /dev/null +++ b/Master/texmf-dist/doc/generic/pstricks/psd-3d.tex @@ -0,0 +1,12 @@ +%% BEGIN psd-3d.tex + +\part{Three Dimensional Graphics\label{P-threeD}} + +\Section{Overview} + +\File{pst-3d} +The... + +\endinput + +%% END psd-3d.tex diff --git a/Master/texmf-dist/doc/generic/pstricks/psd-basi.tex b/Master/texmf-dist/doc/generic/pstricks/psd-basi.tex new file mode 100644 index 00000000000..0d9f5ccea8b --- /dev/null +++ b/Master/texmf-dist/doc/generic/pstricks/psd-basi.tex @@ -0,0 +1,648 @@ +%% BEGIN psd-basi.tex + +\part{Basic graphics objects\label{P-graphics}} + +\Section{Lines and polygons\label{S-lines}} + +The objects in this section also use the following parameters: +\begin{description} + \pitem[linearc=dim] The radius of arcs drawn at the corners of lines by the + \n\psline{} and \n\pspolygon{} graphics objects. <dim> should be positive. + \pitem[framearc=num] In the \n\psframe{} and the related box framing macros, + the radius of rounded corners is set, by default, to one-half <num> times + the width or height of the frame, whichever is less. <num> should be between + 0 and 1. + \pitem[cornersize=relative/absolute] If \p{cornersize} is "relative", then + the \p{framearc} parameter determines the radius of the rounded corners for + \n\psframe, as described above (and hence the radius depends on the size of + the frame). If \p{cornersize} is "absolute", then the \p{linearc} parameter + determines the radius of the rounded corners for \n\psframe{} (and hence the + radius is of constant size). +\end{description} + + +Now here are the lines and polygons: +\begin{description} + +\oitem \psline`{arrows}(\x0,\y0)'(\x1,\y1)`\ldots(\x n,\y n)' + + This draws a line through the list of coordinates. For example: +\begin{MEx*}(4,2) + \psline[linewidth=2pt,linearc=.25]{->}(4,2)(0,1)(2,0) +\end{MEx*} + +\mitem \qline(coor0)(coor1) + + This is a streamlined version of \n\psline{} that does not pay attention to +the \p{arrows} parameter, and that can only draw a single line segment. Note +that both coordinates are obligatory, and there is no optional argument for +setting parameters (use \n\psset{} if you need to change the \p{linewidth}, or +whatever). For example: +\begin{MEx*}(2,1) + \qline(0,0)(2,1) +\end{MEx*} + +\oitem \pspolygon`(\x0,\y0)'(\x1,\y1)(\x2,\y2)`\ldots(\x n,\y n)' + + This is similar to \n\psline, but it draws a closed path. For example: +\begin{MEx*}(4,2) + \pspolygon[linewidth=1.5pt](0,2)(1,2) + \pspolygon*[linearc=.2,linecolor=darkgray](1,0)(1,2)(4,0)(4,2) +\end{MEx*} + +\oitem \psframe`(\x0,\y0)'(\x1,\y1) + + \n\psframe{} draws a rectangle with opposing corners \c0 and \c1. For +example: +\begin{MEx*}(4,2) + \psframe[linewidth=2pt,framearc=.3,fillstyle=solid, + fillcolor=lightgray](4,2) + \psframe*[linecolor=white](1,.5)(2,1.5) +\end{MEx*} + +\oitem \psdiamond`\c0'\c1 + + \n\psdiamond{} draws a diamond centered at \c0, and with the half width and +height equal to \x1\ and \y1, respectively. +\begin{MEx*}(4,2) + \psdiamond[framearc=.3,fillstyle=solid, + fillcolor=lightgray](2,1)(1.5,1) +\end{MEx*} + +The diamond is rotated about the center by +\begin{Ex} + \Par{gangle=gangle} +\end{Ex} + +\oitem \pstriangle`\c0'\c1 + + \n\pstriangle{} draws an isosceles triangle with the base centered at \c0, +and with width (base) and height equal to \x1{} and \y1, respectively. +\begin{MEx*}(4,2) + \pstriangle*[gangle=10](2,.5)(4,1) +\end{MEx*} + +\end{description} + +\Section{Arcs, circles and ellipses} + +\begin{description} + +\oitem \pscircle`(\x0,\y0)'{radius} + +This draws a circle whose center is at \c0 and that has radius <radius>. For +example: +\begin{MEx*}[-1,-1](2,2) + \pscircle[linewidth=2pt](.5,.5){1.5} +\end{MEx*} + +\mitem \qdisk(coor){radius} + + This is a streamlined version of \n{\pscircle*}. Note that the two arguments +are obligatory and there is no parameters arguments. To change the color of +the disks, you have to use \n\psset: +\begin{MEx}[1.9,2.9](2.1,3.1) + \psset{linecolor=gray} + \qdisk(2,3){4pt} +\end{MEx} + +\oitem \pswedge`(\x0,\y0)'{radius}{angle1}{angle2} + + This draws a wedge whose center is at \c0, that has radius <radius>, and +that extends counterclockwise from <angle1> to <angle2>. The angles must be +specified in degrees. For example: +\begin{MEx*}(2,2) + \pswedge[linecolor=gray,linewidth=2pt,fillstyle=solid]{2}{0}{70} +\end{MEx*} + +\oitem \psellipse`(\x0,\y0)'(\x1,\y1) + +\c0 is the center of the ellipse, and \x1 and \y1 are the horizontal and +vertical radii, respectively. For example: +% D.G. modification begin - Mar. 3, 2003 +%\begin{MEx*}[-1,-1.5](2,1) +% D.G. modification end +\begin{MEx*}[-1,-1](2,1) + \psellipse[fillcolor=lightgray](.5,0)(1.5,1) +\end{MEx*} + +\oitem \psarc`{arrows}\c~'{radius}{angleA}{angleB} + + This draws an arc from <angleA> to <angleB>, going counter clockwise, for a +circle of radius <radius> and centered at \c{}. You must include either the +{arrows} argument or the \c{} argument. For example: +\begin{MEx*}(3,2) + \psarc*[showpoints=true](1.5,1.5){1.5}{215}{0} +\end{MEx*} +See how \p{showpoints=true} draws a dashed line from the center to the arc; +this is useful when composing pictures. + +\n\psarc{} also uses the parameters: +\begin{description} + +\pitem[arcsepA=dim](0pt) + + <angleA> is adjusted so that the arc would just touch a line of width <dim> +that extended from the center of the arc in the direction of <angleA>. + +\pitem[arcsepB=dim](0pt) This is like \p{arcsepA}, but <angleB> is adjusted. + +\pitem[arcsep=dim] This just sets both \p{arcsepA} and \p{arcsepB}. +\end{description} +These parameters make it easy to draw two intersecting lines and then use +\n\psarc{} with arrows to indicate the angle between them. For example: +\begin{MEx*}(4,3) + \SpecialCoor + \psline[linewidth=2pt](4;50)(0,0)(4;10) + \psarc[arcsepB=2pt]{->}{3}{10}{50} +\end{MEx*} + +\oitem \psarcn`{arrows}\c~'{radius}{angleA}{angleB} + + This is like \n\psarc, but the arc is drawn \emph{clockwise}. You can achieve +the same effect using \n\psarc{} by switching <angleA> and <angleB> and the +arrows.\footnote{% +However, with \n\pscustom{} graphics object, described in Part \ref{P-custom}, +\n\psarcn{} is not redundant.} + +\oitem \psellipticarc`{arrows}(\x0,\y0)'(\x1,\y1){angleA}{angleB} + + This draws an elliptic from <angleA> to <angleB>, going counter clockwise, +with \c0 the center of the ellipse and \x1 and \y1 the horizontal and +vertical radii, respectively. For example: +\begin{MEx*}[-1,-1](2,1) + \psellipticarc[showpoints=true,arrowscale=2]{->}(.5,0)(1.5,1){215}{0} +\end{MEx*} +See how \p{showpoints=true} draws a dashed line from the center to the arc; +this is useful when composing pictures. + +Like \n\psarc, \n\psellipticarc{} use the \p{arcsep}/\p{arcsepA}/\p{arcsepB} +parameters. + +Unlike \n\psarc, \n\psellipticarc use the +\p{dimen}=\p{inner}/\p{middle}/\p{outer} parameter. + +\oitem \psellipticarcn`{arrows}(\x0,\y0)'(\x1,\y1){angleA}{angleB} + + This is like \n\psellipticarc, but the arc is drawn \emph{clockwise}. You can +achieve the same effect using \n\psellipticarc{} by switching <angleA> and +<angleB> and the arrows.\footnote{% +However, with \n\pscustom{} graphics object, described in Part \ref{P-custom}, +\n\psellipticarcn{} is not redundant.} + +\end{description} + + +\Section{Curves} + +\begin{description} + +\oitem \psbezier`{arrows}(\x0,\y0)'(\x1,\y1)(\x2,\y2)(\x3,\y3) + + \n\psbezier{} draws a bezier curve with the four control points. The curve +starts at the first coordinate, tangent to the line connecting to the second +coordinate. It ends at the last coordinate, tangent to the line connecting to +the third coordinate. The second and third coordinates, in addition to +determining the tangency of the curve at the endpoints, also ``pull'' the +curve towards themselves. For example: +\begin{MEx}(4,4) + \psbezier[linewidth=2pt,showpoints=true]{->}(0,0)(1,4)(2,1)(4,3.5) +\end{MEx} +\p{showpoints=true} puts dots in all the control points, and connects them by +dashed lines, which is useful when adjusting your bezier curve. + +\oitem \parabola`{arrows}'\c0\c1 + + Starting at \c0, \n\parabola{} draws the parabola that passes through \c0 and +whose maximum or minimum is \c1. For example: +\begin{MEx*}(4,3) + \parabola*(1,1)(2,3) + \psset{xunit=.01} + \parabola{<->}(400,3)(200,0) +\end{MEx*} +\end{description} + +The next three graphics objects interpolate an open or closed curve through +the given points. The curve at each interior point is perpendicular to the +line bisecting the angle ABC, where B is the interior point, and A and C are +the neighboring points. Scaling the coordinates \emph{does not} cause the curve +to scale proportionately. + +The curvature is controlled by the following parameter: +\begin{description} +\pitem[curvature=num1 num2 num3] + + You have to just play around with this parameter to get what you want. +Individual values outside the range -1 to 1 are either ignored or are for +entertainment only. Below is an explanation of what each number does. A, B and +C refer to three consecutive points. + + Lower values of <num1> make the curve tighter. + + Lower values of <num2> tighten the curve where the angle ABC is greater than +45 degrees, and loosen the curve elsewhere. + + <num3> determines the slope at each point. If <num3>=0, then the curve is +perpendicular at B to the bisection of ABC. If <num3>=-1, then the curve at B +is parallel to the line AC. With this value (and only this value), scaling the +coordinates causes the curve to scale proportionately. However, positive +values can look better with irregularly spaced coordinates. Values less than +-1 or greater than 2 are converted to -1 and 2, respectively. +\end{description} + +Here are the three curve interpolation macros: +\begin{description} + +\oitem \pscurve`{arrows}'\c1`\ldots\cn' + + This interpolates an open curve through the points. For example: +\begin{MEx*}(4,2) + \pscurve[showpoints=true]{<->}(0,1.3)(0.7,1.8) + (3.3,0.5)(4,1.6)(0.4,0.4) +\end{MEx*} +Note the use of \p{showpoints=true} to see the points. This is helpful when +constructing a curve. + +\oitem \psecurve`{arrows}'\c1`\ldots\cn'] + + This is like \n\pscurve, but the curve is not extended to the first and last +points. This gets around the problem of trying to determine how the curve +should join the first and last points. The "e" has something to do with +``endpoints''. For example: +% D.G. modification begin - Mar. 3, 2003 +%\begin{MEx*}[0,-.9](4,4) +% D.G. modification end +\begin{MEx*}(4,4) + \psecurve[showpoints=true](.125,8)(.25,4)(.5,2) + (1,1)(2,.5)(4,.25)(8,.125) +\end{MEx*} + +\oitem \psccurve`{arrows}'\c1`\ldots\cn' + +This interpolates a closed curve through the points. "c" stands for +``closed''. For example: +\begin{MEx*}(4,1) + \psccurve[showpoints=true] + (.5,0)(3.5,1)(3.5,0)(.5,1) +\end{MEx*} +\end{description} + +\Section{Dots\label{S-dots}} + +The graphics objects +\begin{Ex} + \object \psdot`*[par](\x1,y1)' + \object \psdots`*[par]'(\x1,\y1)`(\x2,\y2)\ldots(\x n,\y n)' +\end{Ex} +put a dot at each coordinate. + +What a ``dot'' is depends on the value of the +\begin{Ex} + \Par{dotstyle=style} +\end{Ex} +parameter. This also determines the dots you get when \p{showpoints=true}. + +The dot styles are also pretty intuitive:% +\newbox\dottable +\setbox\dottable=\hbox{% + \psset{fillcolor=lightgray} + \def\mydots#1{% + \psdots[dotstyle=#1](.1,1ex)(.55,1ex)(1,1ex)(1.45,1ex)(1.9,1ex)}% + \hfill + \begin{tabular}{cl}% + \emph{Style} & \hbox to 2cm{\emph{Example}\hss} \\[2pt] + "*" & \mydots{*}\\ + "o" & \mydots{o}\\ + "Bo" & \mydots{Bo}\\ + "x" & \mydots{x}\\ + "+" & \mydots{+}\\ + "B+" & \mydots{B+}\\ + "asterisk" & \mydots{asterisk}\\ + "Basterisk" & \mydots{Basterisk}\\ + "oplus" & \mydots{oplus}\\ + "otimes" & \mydots{otimes}\\ + "|" & \mydots{|}\\ + "B|" & \mydots{B|} + \end{tabular}% + \hfill + \begin{tabular}{cl} + \emph{Style} & \hbox to 2cm{\emph{Example}\hss} \\[2pt] + "square" & \mydots{square}\\ + "Bsquare" & \mydots{Bsquare}\\ + "square*" & \mydots{square*}\\ + "diamond" & \mydots{diamond}\\ + "diamond*" & \mydots{diamond*}\\ + "triangle" & \mydots{triangle}\\ + "Btriangle" & \mydots{Btriangle}\\ + "triangle*" & \mydots{triangle*}\\ + "pentagon" & \mydots{pentagon}\\ + "Bpentagon" & \mydots{Bpentagon}\\ + "pentagon*" & \mydots{pentagon*}\\ + \end{tabular}% + \hfill}% +\addtoquickref{center}{% + {\large\textbf{Dot styles}}\par + \leavevmode\hbox to \hsize{\unhbox\dottable}} +\begin{center} + \leavevmode + \hbox to \hsize{\unhcopy\dottable}% +\end{center} + +Except for "diamond", the center of dot styles with a hollow center is colored +\p{fillcolor}. + +Here are the parameters for changing the size and orientation of the dots: +\begin{description} + +\pitem[dotsize=dim `num'] + The diameter of a circle or disc is <dim> plus <num> times \p{linewidth} +(if the optional <num> is included). The size of the other dots styles is +similar (except for the size of the "|" dot style, which is set by the +\p{tbarsize} parameter described on page \pageref{p+tbarsize}). + +\pitem[dotscale=num1 `num2'] +The dots are scaled horizontally by <num1> and vertically by <num2>. If you +only include <num1>, the arrows are scaled by <num1> in both directions. + +\pitem[dotangle=angle] + After setting the size and scaling the dots, the dots are rotated by <angle>. + +\end{description} + + +\Section{Grids\label{S-grids}} + +PSTricks has a powerful macro for making grids and graph paper: + \Mac \psgrid`(\x0,\y0)(\x1,\y1)(\x2,\y2)' +\n\psgrid{} draws a grid with opposing corners \c1 and \c2. The intervals are +numbered, with the numbers positioned at \x0 and \y0. The coordinates are +always interpreted as Cartesian coordinates. For example: +\begin{MEx}[-1,-1](3,2) + \psgrid(0,0)(-1,-1)(3,2) +\end{MEx} +(Note that the coordinates and label positioning work the same as with +\n\psaxes.) + +The main grid divisions occur on multiples of \p{xunit} and \p{yunit}. +Subdivisions are allowed as well. Generally, the coordinates would be given as +integers, without units. + +If the \c0 coordinate is omitted, \c1 is used. The default for \c1 is "(0,0)". +If you don't give any coordinates at all, then the coordinates of the current +\n\pspicture{} environment are used or a 10x10 grid is drawn. Thus, you can +include a \n\psgrid{} command without coordinates in a \n\pspicture\ +environment to get a grid that will help you position objects in the picture. + +The main grid divisions are numbered, with the numbers drawn next to the +vertical line at \x0 (away from \x2) and next to the horizontal line at \x1 +(away from \y2). \c1 can be any corner of the grid, as long as \c2 is the +opposing corner, you can position the labels on any side you want. For +example, compare +\begin{MEx}(4,1) + \psgrid(0,0)(4,1) +\end{MEx} +and +\begin{MEx}(4,1) + \psgrid(4,1)(0,0) +\end{MEx} + +The following parameters apply only to \n\psgrid: +\begin{description} + +\pitem[gridwidth=dim] + The width of grid lines. + +\pitem[gridcolor=color] + The color of grid lines. + +\pitem[griddots=num] + If <num> is positive, the grid lines are dotted, with <num> dots per +division. + +\pitem[gridlabels=dim] + The size of the numbers used to mark the grid. + +\pitem[gridlabelcolor=color] + The color of the grid numbers. + +\pitem[subgriddiv=int] + The number of grid subdivisions. + +\pitem[subgridwidth=dim] + The width of subgrid lines. + +\pitem[subgridcolor=color] + The color of subgrid lines. + +\pitem[subgriddots=num] + Like \p{griddots}, but for subdivisions. + +\end{description} + +Here is a familiar looking grid which illustrates some of the parameters: +\begin{MEx}[-1,-1](3,1) + \psgrid[subgriddiv=1,griddots=10,gridlabels=7pt](-1,-1)(3,1) +\end{MEx} + +Note that the values of \p{xunit} and \p{yunit} are important parameters for +\n\psgrid, because they determine the spacing of the divisions. E.g., if the +value of these is "1pt", and then you type +\begin{LVerb} + \psgrid(0,0)(10in,10in) +\end{LVerb} +you will get a grid with 723 main divisions and 3615 subdivisions! (Actually, +\n\psgrid{} allows at most 500 divisions or subdivisions, to limit the damage +done by this kind of mistake.) Probably you want to set \p{unit} to ".5in" or +"1in", as in +\begin{LVerb} + \psgrid[unit=.5in](0,0)(20,20) +\end{LVerb} + + +\Section{Plots} + +\File{pst-plot} +The plotting commands described in this part are defined in +"pst-plot.tex" / "pst-plot.sty", which you must load first. + +The \n\psdots, \n\psline, \n\pspolygon, \n\pscurve, \n\psecurve{} and +\n\psccurve{} graphics objects let you plot data in a variety of ways. However, +first you have to generate the data and enter it as coordinate pairs \c{}. +The plotting macros in this section give you other ways to get and use the +data. (Section \ref{S-axes} tells you how to generate axes.) + +To parameter +\begin{Ex} + \Par{plotstyle=style} +\end{Ex} +determines what kind of plot you get. Valid styles are "dots", "line", +"polygon", "curve", "ecurve", "ccurve". E.g., if the \p{plotstyle} is +"polygon", then the macro becomes a variant of the \n\pspolygon{} object. + +You can use arrows with the plot styles that are open curves, but there is no +optional argument for specifying the arrows. You have to use the \p{arrows} +parameter instead. + +\begin{Warning} +No PostScript error checking is provided for the data arguments. Read Appendix +\ref{S-raw} before including PostScript code in the arguments. + +There are system-dependent limits on the amount of data \TeX{} and PostScript +can handle. You are much less likely to exceed the PostScript limits when you +use the "line", "polygon" or "dots" plot style, with \p{showpoints=false}, +\p{linearc=0pt}, and no arrows. +\end{Warning} + +Note that the lists of data generated or used by the plot commands cannot +contain units. The values of \n\psxunit{} and \n\psyunit{} are used as the unit. + + +\begin{description} + +\oitem \fileplot{file} + +\n\fileplot{} is the simplest of the plotting functions to use. You just need a +file that contains a list of coordinates (without units), such as generated by +Mathematica or other mathematical packages. The data can be delimited by curly +braces "{"~"}", parentheses "("~")", commas, and/or white space. Bracketing +all the data with square brackets "[ ]" will significantly speed up the rate +at which the data is read, but there are system-dependent limits on how much +data \TeX{} can read like this in one chunk. (The "[" \emph{must} go at the +beginning of a line.) The file should not contain anything else (not even +"\endinput"), except for comments marked with "%". + +\n\fileplot{} only recognizes the "line", "polygon" and "dots" plot styles, and +it ignores the \p{arrows}, \p{linearc} and \p{showpoints} parameters. The +\n\listplot{} command, described below, can also plot data from file, without +these restrictions and with faster \TeX{} processing. However, you are less +likely to exceed PostScript's memory or operand stack limits with \n\fileplot. + +If you find that it takes \TeX{} a long time to process your \n\fileplot\ +command, you may want to use the \n\PSTtoEPS{} command described on page +\pageref{+PSTtoEPS}. This will also reduce \TeX's memory requirements. + +\oitem \dataplot{commands} + +\n\dataplot{} is also for plotting lists of data generated by other programs, +but you first have to retrieve the data with one of the following commands: +\begin{Ex} + \object \savedata{command}[data] + \object \readdata{command}{file} +\end{Ex} +<data> or the data in <file> should conform to the rules described above for +the data in \n\fileplot{} (with \n\savedata, the data must be delimited by +"["~"]", and with \n\readdata, bracketing the data with "["~"]" speeds things +up). You can concatenate and reuse lists, as in +\begin{LVerb} + \readdata{\foo}{foo.data} + \readdata{\bar}{bar.data} + \dataplot{\foo\bar} + \dataplot[origin={0,1}]{\bar} +\end{LVerb} + +The \n\readdata{} and \n\dataplot{} combination is faster than \n\fileplot{} +if you reuse the data. \n\fileplot{} uses less of \TeX's memory than +\n\readdata{} and \n\dataplot{} if you are also use \n\PSTtoEPS. + +Here is a plot of "Integral(sin(x))". The data was generated by Mathematica, +with +\begin{LVerb} + Table[{x,N[SinIntegral[x]]},{x,0,20}] +\end{LVerb} +and then copied to this document. +\begin{MEx}(4,3) + \psset{xunit=.2cm,yunit=1.5cm} + \savedata{\mydata}[ + {{0, 0}, {1., 0.946083}, {2., 1.60541}, {3., 1.84865}, {4., 1.7582}, + {5., 1.54993}, {6., 1.42469}, {7., 1.4546}, {8., 1.57419}, + {9., 1.66504}, {10., 1.65835}, {11., 1.57831}, {12., 1.50497}, + {13., 1.49936}, {14., 1.55621}, {15., 1.61819}, {16., 1.6313}, + {17., 1.59014}, {18., 1.53661}, {19., 1.51863}, {20., 1.54824}}] + \dataplot[plotstyle=curve,showpoints=true, + dotstyle=triangle]{\mydata} + \psline{<->}(0,2)(0,0)(20,0) +\end{MEx} + +\oitem \listplot{list} + +\n\listplot{} is yet another way of plotting lists of data. This time, <list> +should be a list of data (coordinate pairs), delimited only by white space. +<list> is first expanded by \TeX{} and then by PostScript. This means that +<list> might be a PostScript program that leaves on the stack a list of data, +but you can also include data that has been retrieved with \n\readdata{} and +\n\dataplot. However, when using the "line", "polygon" or "dots" plotstyles +with \p{showpoints=false}, \p{linearc=0pt} and no arrows, \n\dataplot{} is much +less likely than \n\listplot{} to exceed PostScript's memory or stack limits. +In the preceding example, these restrictions were not satisfied, and so the +example is equivalent to when \n\listplot{} is used: +\begin{LVerb} + ... + \listplot[plotstyle=curve,showpoints=true, + dotstyle=triangle]{\mydata} + ... +\end{LVerb} + +\oitem \psplot{$x_!\min@$}{$x_!\max@$}{function} + + \n\psplot{} can be used to plot a function $f(x)$, if you know a little +PostScript. <function> should be the PostScript code for calculating $f(x)$. +Note that you must use $x$ as the dependent variable. PostScript is not +designed for scientific computation, but \n\psplot{} is good for graphing +simple functions right from within \TeX. E.g., +\begin{LVerb} + \psplot[plotpoints=200]{0}{720}{x sin} +\end{LVerb} +plots $\sin(x)$ from 0 to 720 degrees, by calculating $\sin(x)$ roughly every +3.6 degrees and then connecting the points with \n\psline. Here are plots of +$\sin(x)\cos((x/2)^2)$ and $\sin^2(x)$: +\begin{MEx}[0,-1](4,1) + \psset{xunit=1.2pt} + \psplot[linecolor=gray,linewidth=1.5pt,plotstyle=curve]% + {0}{90}{x sin dup mul} + \psplot[plotpoints=100]{0}{90}{x sin x 2 div 2 exp cos mul} + \psline{<->}(0,-1)(0,1) + \psline{->}(100,0) +\end{MEx} + +\oitem \parametricplot{$t_!\min@$}{$t_!\max@$}{function} + +This is for a parametric plot of $(x(t),y(t))$. <function> is the PostScript +code for calculating the pair $x(t)$ $y(t)$. + +For example, +\begin{MEx*}(3,3) + \parametricplot[plotstyle=dots,plotpoints=13]% + {-6}{6}{1.2 t exp 1.2 t neg exp} +\end{MEx*} +plots 13 points from the hyperbola $xy=1$, starting with $(1.2^{-6},1.2^6)$ +and ending with $(1.2^6,1.2^{-6})$. + +Here is a parametric plot of $(\sin(t),\sin(2t))$: +\begin{MEx}[-2,-1](2,1) + \psset{xunit=1.7cm} + \parametricplot[linewidth=1.2pt,plotstyle=ccurve]% + {0}{360}{t sin t 2 mul sin} + \psline{<->}(0,-1.2)(0,1.2) + \psline{<->}(-1.2,0)(1.2,0) +\end{MEx} + +\end{description} + +The number of points that the \n\psplot{} and \n\parametricplot{} commands +calculate is set by the +\begin{Ex} + \Par{plotpoints=int} +\end{Ex} +parameter. Using "curve" or its variants instead of "line" and increasing the +value of \p{plotpoints} are two ways to get a smoother curve. Both ways +increase the imaging time. Which is better depends on the complexity of the +computation. (Note that all PostScript lines are ultimately rendered as a +series (perhaps short) line segments.) Mathematica generally uses "lineto" to +connect the points in its plots. The default minimum number of plot points for +Mathematica is 25, but unlike \n\psplot{} and \n\parametricplot, Mathematica +increases the sampling frequency on sections of the curve with greater +fluctuation. + +\endinput + +%% END psd-basi.tex diff --git a/Master/texmf-dist/doc/generic/pstricks/psd-cove.tex b/Master/texmf-dist/doc/generic/pstricks/psd-cove.tex new file mode 100644 index 00000000000..177e0bff2c1 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pstricks/psd-cove.tex @@ -0,0 +1,108 @@ +%% BEGIN psd-cove.tex + +\begingroup +\evensidemargin \paperwidth\relax +\advance\evensidemargin -2in +\advance\evensidemargin -\textwidth +\divide\evensidemargin 2 +\oddsidemargin\evensidemargin + +\begin{titlepage} + +\let\footnotesize\small +\let\footnoterule\relax +\setcounter{page}{0} + +\null +\vfil +\vskip 25pt +\begin{center} + {\LARGE\textbf{PSTricks}}:\\[5pt] + {\large\textbf{PostScript macros for Generic TeX}.}\\ +\end{center} + +\bigskip\bigskip +\hbox to \hsize{% + \hss + \psset{unit=.4cm} + \begin{pspicture}(0,-2)(31,12) + \catcode`\<=12 + \rput(1.5,0){% + \psellipse[linewidth=1pt](8,7)(1,3) + \psframe[linecolor=white,fillstyle=solid,fillcolor=white] + (6.4,6.5)(8,7.5) + \psline[linearc=.3,linewidth=1pt](8,8)(8,7.5)(4,7.5) + \psbezier[linewidth=1pt](4,7.5)(3,7.5)(3,6.5)(3,5.5) + \psline[linearc=.3,linewidth=1pt](8,6)(8,6.5)(5,6.5) + \psbezier[linewidth=1pt](5,6.5)(4,6.5)(4,6.5)(4,5.5) + \psline[linewidth=1pt](3,5.5)(4,5.5) + \psline[linearc=.3,linewidth=1pt](5,7.5)(5,8)(6,8)(6,7.5) + \psframe[linewidth=1pt](5.3,8)(5.7,8.7) + \psframe[linewidth=1pt,framearc=1,fillstyle=solid, + fillcolor=white](4,8.7)(7,9) + \multirput(3.5,4.8)(0,-1){4}{% + \psbezier[linewidth=.5pt](0,0)(.25,-.4)(-.25,-.4)(0,0)} + \rput[t](5.5,0){Dripping Faucet}} + \rput(20,5){% + \pspolygon[linecolor=white,fillstyle=vlines, + fillcolor=darkgray,hatchsep=.2](1,4.5)(1,4)(4,4)(4,4.5) + \psline[linewidth=2pt](1,4)(4,4) + \psline[linewidth=1.5pt](2.5,4)(2.5,3.5)(2.9,3.3)(2.1,2.9) + (2.9,2.5)(2.1,2.1)(2.9,1.7)(2.1,1.3)(2.5,1.1)(2.5,0.6) + \psframe[linecolor=black,linewidth=1.5pt,fillstyle=solid, + fillcolor=lightgray](1.8,-1)(3.2,.6) + \rput(2.5,-.2){$M$} + \psline{<->}(3.7,-.9)(3.7,.5) + \psframe[linecolor=black,linewidth=1.5pt,fillstyle=solid, + fillcolor=lightgray](1.8,-3.5)(3.2,-1.9) + \rput(2.5,-2.7){$m$} + \psline{->}(5,1)(5,-1) + \rput[l](5.5,0){$g$} + \psline{->}(3.7,-2)(3.7,-3.4) + \rput[t](2.5,-4){Mathematical Model for} + \rput[t](2.5,-5){a Dripping Faucet} + \rput(-6,-2){% + \psset{linewidth=2pt} + \psline(0,.5)(2,.5) + \psline(0,-.5)(2,-.5) + \psline(1.5,1)(2.5,0)(1.5,-1)}} + \psframe[linewidth=2pt,framearc=.05,linecolor=gray](0,-2.5)(31,12) + \uput[l]{90}(0,4.75){\texttt{leecheng}} + \end{pspicture}% + \hss} +\bigskip +\bigskip + +\begin{center} +{\LARGE\textbf{User's Guide}}\par +\vskip 3em +{\large \lineskip .75em Timothy Van Zandt}\par +\vskip 1.5em +{\large \thefiledate\\[2pt] + Version \Version% + \footnote{Documentation edited and repacked at \today\ by Rolf Niepraschk + \url{niepraschk@gmx.de} + and Herbert Vo\ss\ \url{voss@pstricks.de}.}}\par +% \Verb[codes={\catcode`\<=12}]+<niepraschk@ptb.de>+ +% and Herbert Voß \Verb[codes={\catcode`\<=12}]+<voss@perce.de>+.}}\par +\end{center} +\vfil +\small +Author's address:\\ + Department of Economics and Political Science\\ + INSEAD\\ + Boulevard de Constance\\ + 77305 Fontainebleau Cedex\\ + France\\[3mm] + Internet: \Verb[codes={\catcode`\<=12}]+<tvz@econ.insead.fr>+ +\end{titlepage} + +\endgroup + +\setcounter{footnote}{0} +\tableofcontents +\pagenumbering{arabic} + +\endinput + +%% END psd-cove.tex diff --git a/Master/texmf-dist/doc/generic/pstricks/psd-cust.tex b/Master/texmf-dist/doc/generic/pstricks/psd-cust.tex new file mode 100644 index 00000000000..03441baca4f --- /dev/null +++ b/Master/texmf-dist/doc/generic/pstricks/psd-cust.tex @@ -0,0 +1,406 @@ +%% BEGIN psd-cust.tex + +\part{Custom graphics\label{P-custom}} + +\Section{The basics} + +PSTricks contains a large palette of graphics objects, but sometimes you need +something special. For example, you might want to shade the region between two +curves. The + \Mac \pscustom`*[par]'{commands} +command lets you ``roll you own'' graphics object. + +Let's review how PostScript handles graphics. A \emph{path} is a line, in the +mathematical sense rather than the visual sense. A path can have several +disconnected segments, and it can be open or closed. PostScript has various +operators for making paths. The end of the path is called the \emph{current +point}, but if there is no path then there is no current point. To turn the +path into something visual, PostScript can \emph{fill} the region enclosed by +the path (that is what \p{fillstyle} and such are about), and \emph{stroke} the +path (that is what \p{linestyle} and such are about). + +At the beginning of \n\pscustom, there is no path. There are various commands +that you can use in \n\pscustom{} for drawing paths. Some of these (the open +curves) can also draw arrows. \n\pscustom{} fills and strokes the path at the +end, and for special effects, you can fill and stroke the path along the way +using \n\fill{} and \n\stroke{} (see below). + +\begin{drivers} +\n\pscustom{} uses \n\pstverb{} and \n\pstunit. There are system-dependent +limits on how long the argument of "\special" can be. You may run into this +limit using \n\pscustom{} because all the PostScript code accumulated by +\n\pscustom{} is the argument of a single "\special" command. +\end{drivers} + +\Section{Parameters} + +You need to keep the separation between drawing, stroking and filling paths in +mind when setting graphics parameters. The \p{linewidth} and \p{linecolor} +parameters affect the drawing of arrows, but since the path commands do not +stroke or fill the paths, these parameters, and the \p{linestyle}, +\p{fillstyle} and related parameters, do not have any other effect (except +that in some cases \p{linewidth} is used in some calculations when drawing the +path). \n\pscustom{} and \n\fill{} make use of \p{fillstyle} and related +parameters, and \n\pscustom{} and \n\stroke{} make use of p{linestyle} and +related parameters. + +For example, if you include +\begin{LVerbatim} + \psline[linewidth=2pt,linecolor=blue,fillstyle=vlines]{<-}(3,3)(4,0) +\end{LVerbatim} +in \n\pscustom, then the changes to \p{linewidth} and \p{linecolor} will +affect the size and color of the arrow but not of the line when it is stroked, +and the change to \p{fillstyle} will have no effect at all. + +The \p{shadow}, \p{border}, \p{doubleline} and \p{showpoints} parameters are +disabled in \n\pscustom, and the \p{origin} and \p{swapaxes} parameters only +affect \n\pscustom{} itself, but there are commands (described below) that let +you achieve these special effects. + +The \p{dashed} and \p{dotted} line styles need to know something about the +path in order to adjust the dash or dot pattern appropriately. You can give +this information by setting the +\begin{Ex} + \Par{linetype=int} +\end{Ex} +parameter. If the path contains more than one disconnected segment, there is +no appropriate way to adjust the dash or dot pattern, and you might as well +leave the default value of \p{linetype}. Here are the values for simple paths: +\begin{center} +\begin{tabular}{cl} + \emph{Value} & \emph{Type of path}\\ + 0 & Open curve without arrows.\\ + -1 & Open curve with an arrow at the beginning.\\ + -2 & Open curve with an arrow at the end.\\ + -3 & Open curve with an arrow at both ends.\\ + 1 & Closed curve with no particular symmetry.\\ + $n$\textgreater 1 & Closed curve with $n$ symmetric segments. +\end{tabular} +\end{center} + +\Section{Graphics objects} + +You can use most of the graphics objects in \n\pscustom. These draw paths and +making arrows, but do not fill and stroke the paths. + +There are three types of graphics objects: +\begin{description} +\item[Special] + Special graphics objects include \n\psgrid, \n\psdots, \n\qline{} and +\n\qdisk. You cannot use special graphics objects in \n\pscustom. + +\item[Closed] + You are allowed to use closed graphics objects in \n\pscustom, but their +effect is unpredictable.\footnote{% +The closed objects never use the current point as an coordinate, but typically +they will close any existing paths, and they might draw a line between the +currentpoint and the closed curved.} +Usually you would use the open curves plus \n\closepath{} (see below) to draw +closed curves. + +\item[Open]The open graphics objects are the most useful commands for drawing +paths with \n\pscustom. By piecing together several open curves, you can draw +arbitrary paths. The rest of this section pertains to the open graphics +objects. +\end{description} + + By default, the open curves draw a straight line between the current point, +if it exists, and the beginning of the curve, except when the curve begins +with an arrow. For example +\begin{MEx*}(3,3) + \pscustom{% + \psarc(0,0){1.5}{5}{85} + \psarcn{->}(0,0){3}{85}{5}} +\end{MEx*} + +Also, the following curves make use of the current point, if it exists, as a +first coordinate: +\begin{quote} + \n\psline{} and \n\pscurve.\\ + The plot commands, with the "line" or "curve" \p{plotstyle}.\\ + \n\psbezier\, if you only include three coordinates.\\ +\end{quote} +For example: +\begin{MEx*}(4,3) + \pscustom[linewidth=1.5pt]{% + \psplot[plotstyle=curve]{.67}{4}{2 x div} + \psline(4,3)} +\end{MEx*} +We'll see later how to make that one more interesting. Here is another example +\begin{MEx*}(4,3) + \pscustom{% + \psline[linearc=.2]{|-}(0,2)(0,0)(2,2) + \psbezier{->}(2,2)(3,3)(1,0)(4,3)} +\end{MEx*} + +However, you can control how the open curves treat the current point with the +\begin{Ex} + \Par{liftpen=0/1/2} +\end{Ex} +parameter. + +If \p{liftpen=0}, you get the default behavior described above. For example +\begin{MEx*}(4,3) + \pscustom[linewidth=2pt,fillstyle=solid,fillcolor=gray]{% + \pscurve(0,2)(1,2.5)(2,1.5)(4,3) + \pscurve(4,1)(3,0.5)(2,1)(1,0)(0,.5)} +\end{MEx*} + +If \p{liftpen=1}, the curves do not use the current point as the first +coordinate (except \n\psbezier, but you can avoid this by explicitly including +the first coordinate as an argument). For example: +\begin{MEx*}(4,3) + \pscustom[linewidth=2pt,fillstyle=solid,fillcolor=gray]{% + \pscurve(0,2)(1,2.5)(2,1.5)(4,3) + \pscurve[liftpen=1](4,1)(3,0.5)(2,1)(1,0)(0,.5)} +\end{MEx*} + +If \p{liftpen=2}, the curves do not use the current point as the first +coordinate, and they do not draw a line between the current point and the +beginning of the curve. For example +\begin{MEx*}(4,3) + \pscustom[linewidth=2pt,fillstyle=solid,fillcolor=gray]{% + \pscurve(0,2)(1,2.5)(2,1.5)(4,3) + \pscurve[liftpen=2](4,1)(3,0.5)(2,1)(1,0)(0,.5)} +\end{MEx*} + +Later we will use the second example to fill the region between the two +curves, and then draw the curves. + +\Section{Safe tricks} + +The commands described under this heading, which can only be used in +\n\pscustom, do not run a risk of PostScript errors (assuming your document +compiles without \TeX{} errors). + +Let's start with some path, fill and stroke commands: +\begin{description} + +\mitem \newpath + +Clear the path and the current point. + +\mitem \moveto(coor) + + This moves the current point to \c{}. + +\mitem \closepath + + This closes the path, joining the beginning and end of each piece (there may +be more than one piece if you use \n\moveto).\footnote{% +Note that the path is automatically closed when the region is filled. Use +\n\closepath{} if you also want to close the boundary.} + +\mitem \stroke`[par]' + + This strokes the path (non-destructively). \n\pscustom{} automatically +strokes the path, but you might want to stroke it twice, e.g., to add a +border. Here is an example that makes a double line and adds a border (this +example is kept so simple that it doesn't need \n\pscustom{} at all): +\begin{MEx*}(4,3) + \psline(0,3)(4,0) + \pscustom[linecolor=white,linewidth=1.5pt]{% + \psline(0,0)(4,3) + \stroke[linewidth=5\pslinewidth] + \stroke[linewidth=3\pslinewidth,linecolor=black]} +\end{MEx*} + +\mitem \fill`[par]' + + This fills the region (non-destructively). \n\pscustom{} automatically fills +the region as well. + +\mitem \gsave + + This saves the current graphics state (i.e., the path, color, line width, +coordinate system, etc.) \n\grestore{} restores the graphics state. \n\gsave{} +and \n\grestore{} must be used in pairs, properly nested with respect to \TeX{} +groups. You can have have nested \n\gsave-\n\grestore{} pairs. + +\mitem \grestore + + See above. + +Here is an example that fixes an earlier example, using \n\gsave{} and +\n\grestore: +\begin{MEx}(4,3) + \psline{<->}(0,3)(0,0)(4,0) + \pscustom[linewidth=1.5pt]{ + \psplot[plotstyle=curve]{.67}{4}{2 x div} + \gsave + \psline(4,3) + \fill[fillstyle=solid,fillcolor=gray] + \grestore} +\end{MEx} +Observe how the line added by "\psline(4,3)" is never stroked, because it is +nested in "\gsave" and "\grestore". + +Here is another example: +\begin{MEx*}(4,3) + \pscustom[linewidth=1.5pt]{ + \pscurve(0,2)(1,2.5)(2,1.5)(4,3) + \gsave + \pscurve[liftpen=1](4,1)(3,0.5)(2,1)(1,0)(0,.5) + \fill[fillstyle=solid,fillcolor=gray] + \grestore} + \pscurve[linewidth=1.5pt](4,1)(3,0.5)(2,1)(1,0)(0,.5) +\end{MEx*} +Note how I had to repeat the second \n\pscurve{} (I could have repeated it +within \n\pscustom, with \p{liftpen=2}), because I wanted to draw a line +between the two curves to enclose the region but I didn't want this line to be +stroked. +\end{description} + +The next set of commands modify the coordinate system. +\begin{description} + +\mitem \translate(coor) + + Translate coordinate system by \c{}. This shifts everything that comes later +by \c{}, but doesn't affect what has already been drawn. + +\mitem \scale{num1 `num2'} + + Scale the coordinate system in both directions by <num1>, or horizontally by +<num1> and vertically by <num2>. + +\mitem \rotate{angle} + + Rotate the coordinate system by <angle>. + +\mitem \swapaxes + + Switch the x and y coordinates. This is equivalent to +\begin{LVerb} + \rotate{-90} + \scale{-1 1 scale} +\end{LVerb} + +\mitem \msave + + Save the current coordinate system. You can then restore it with +\n\mrestore. You can have nested \n\msave-\n\mrestore{} pairs. \n\msave{} and +\n\mrestore{} do not have to be properly nested with respect to \TeX{} groups or +\n\gsave{} and \n\grestore. However, remember that \n\gsave{} and \n\grestore +also affect the coordinate system. \n\msave-\n\mrestore{} lets you change the +coordinate system while drawing part of a path, and then restore the old +coordinate system without destroying the path. \n\gsave-\n\grestore, on the +other hand, affect the path and all other componments of the graphics state. + +\mitem \mrestore + + See above. +\end{description} + +And now here are a few shadow tricks: +\begin{description} +\mitem \openshadow`[par]' + +Strokes a replica of the current path, using the various shadow parameters. + +\mitem \closedshadow`[par]' + +Makes a shadow of the region enclosed by the current path as if it were opaque +regions. + +\mitem \movepath(coor) + +Moves the path by \c{}. Use \n\gsave-\n\grestore{} if you don't want to lose +the original path. +\end{description} + +\Section{Pretty safe tricks} + +The next group of commands are safe, \emph{as long as there is a current +point}! + +\begin{description} +\mitem \lineto(coor) + + This is a quick version of "\psline(<coor>)". + +\mitem \rlineto(coor) + + This is like \n\lineto, but \c{} is interpreted relative to the current +point. + +\mitem \curveto\c1\c2\c3 + + This is a quick version of "\psbezier"\c1\c2\c3. + +\mitem \rcurveto\c1\c2\c3 + + This is like \n\curveto, but \c1, \c2 and \c3 are interpreted relative to +the current point. +\end{description} + +\Section{For hackers only} + +For PostScript hackers, there are a few more commands. Be sure to read +Appendix \ref{S-raw} before using these. Needless to say: +\begin{Warning} +Misuse of the commands in this section can cause PostScript errors. +\end{Warning} + + The PostScript environment in effect with \n\pscustom{} has one unit equal to +one \TeX{} "pt". + +\begin{description} + +\mitem \code{code} + Insert the raw PostScript code. + +\mitem \dim{dim} + + Convert the PSTricks dimension to the number of "pt"'s, and inserts it in +the PostScript code. + +\mitem \coor\c1`\c2...\cn' + +Convert one or more PSTricks coordinates to a pair of numbers (using "pt" +units), and insert them in the PostScript code. + +\mitem \rcoor\c1`\c2...\cn' + +Like \n\coor, but insert the coordinates in reverse order. + +\mitem \file{file} + + This is like \n\code, but the raw PostScript is copied verbatim (except +comments delimited by "%") from <file>. + +\mitem \arrows{arrows} + + This defines the PostScript operators "ArrowA" and "ArrowB" so that +\begin{LVerb} + x2 y2 x1 y1 ArrowA + x2 y2 x1 y1 ArrowB +\end{LVerb} +each draws an arrow(head) with the tip at \c1 and pointing from \c2. "ArrowA" +leaves the current point at end of the arrowhead, where a connect line should +start, and leaves \c2 on the stack. "ArrowB" does not change the current +point, but leaves +\begin{LVerb} + x2 y2 x1' y1' +\end{LVerb} +on the stack, where \c{1'} is the point where a connecting line should join. +To give an idea of how this work, the following is roughly how PSTricks draws +a bezier curve with arrows at the end: +\begin{MEx*}(4,3) + \pscustom{ + \arrows{|->} + \code{ + 80 140 5 5 ArrowA + 30 -30 110 75 ArrowB + curveto}} +\end{MEx*} + +\mitem \setcolor{color} + + Set the color to <color>. + +\end{description} + +\endinput + +%% END psd-cust.tex 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 diff --git a/Master/texmf-dist/doc/generic/pstricks/psd-fill.tex b/Master/texmf-dist/doc/generic/pstricks/psd-fill.tex new file mode 100644 index 00000000000..e9df05eb744 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pstricks/psd-fill.tex @@ -0,0 +1,12 @@ +%% BEGIN psd-fill.tex + +\part{Filling and Tiling\label{P-tiling}} + +\Section{Overview} + +\File{pst-fill} +The... + +\endinput + +%% END psd-fill.tex diff --git a/Master/texmf-dist/doc/generic/pstricks/psd-help.tex b/Master/texmf-dist/doc/generic/pstricks/psd-help.tex new file mode 100644 index 00000000000..0c4bf708ab0 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pstricks/psd-help.tex @@ -0,0 +1,332 @@ +%% BEGIN psd-help.tex + +\appendix\part*{Help} + +\Section{Boxes\label{S-boxes}} + +Many of the PSTricks macros have an argument for text that is processed in +restricted horizontal mode (in \LaTeX{} parlance, LR-mode) and then transformed +in some way. This is always the macro's last argument, and it is written +"{<stuff>}" in this \emph{User's Guide}. Examples are the framing, rotating, +scaling, positioning and node macros. I will call these ``LR-box'' macros, and +use framing as the leading example in the discussion below. + +In restricted horizontal mode, the input, consisting of regular characters and +boxes, is made into one (long or short) line. There is no line-breaking, nor +can there be vertical mode material such as an entire displayed equation. +However, the fact that you can include another box means that this isn't +really a restriction. + +For one thing, alignment environments such as "\halign" or \LaTeX's "tabular" +are just boxes, and thus present no problem. Picture environments and the box +macros themselves are also just boxes. Actually, there isn't a single PSTricks +command that cannot be put directly in the argument of an LR-box macro. +However, entire paragraphs or other vertical mode material such as displayed +equations need to be nested in a "\vbox" or \LaTeX{} "\parbox" or "minipage". +\LaTeX{} users should see "fancybox.sty" and its documentation, "fancybox.doc", +for extensive tips and trick for using LR-box commands. + +The PSTricks LR-box macros have some features that are not found in most other +LR-box macros, such as the standard \LaTeX{} LR-box commands. + +With \LaTeX{} LR-box commands, the contents is always processed in text mode, +even when the box occurs in math mode. PSTricks, on the other hand, preserves +math mode, and attempts to preserve the math style as well. \TeX{} has four +math styles: text, display, script and scriptscript. Generally, if the box +macro occurs in displayed math (but not in sub- or superscript math), the +contents are processed in display style, and otherwise the contents are +processed in text style (even here the PSTricks macros can make mistakes, but +through no fault of their own). If you don't get the right style, explicitly +include a "\textstyle", "\displaystyle", "\scriptstyle" or +"\scriptscriptstyle" command at the beginning of the box macro's argument. + + In case you want your PSTricks LR-box commands to treat math in the same as +your other LR-box commands, you can switch this feature on and off with the +commands +\begin{Ex} + \object \psmathboxtrue + \object \psmathboxfalse +\end{Ex} + +You can have commands (such as, but not restricted to, the math style +commands) automatically inserted at the beginning of each LR-box using the + \Mac \everypsbox{commands} +command.\footnote{This is a token register.} + +If you would like to define an LR-box environment <name> from an LR-box +command <cmd>, use + \Mac \pslongbox{name}{cmd} +For example, after +\begin{LVerbatim} + \pslongbox{MyFrame}{\psframebox} +\end{LVerbatim} +you can write +\begin{LVerbatim} + \MyFrame <stuff>\endMyFrame +\end{LVerbatim} +instead of +\begin{LVerbatim} + \psframebox{<stuff>} +\end{LVerbatim} +Also, \LaTeX{} users can write +\begin{LVerbatim} + \begin{MyFrame} <stuff>\end{MyFrame} +\end{LVerbatim} +It is up to you to be sure that <cmd> is a PSTricks LR-box command; if it +isn't, nasty errors can arise. + +Environments like have nice properties: +\begin{itemize} + \item The syntax is clearer when <stuff> is long. + \item It is easier to build composite LR-box commands. For example, here is +a framed minipage environment for \LaTeX: +\begin{LVerb} + \pslongbox{MyFrame}{\psframebox} + \newenvironment{fminipage}% + {\MyFrame\begin{minipage}}% + {\end{minipage}\endMyFrame} +\end{LVerb} + \item You include verbatim text and other "\catcode" tricks in <stuff>. +\end{itemize} + +The rest of this section elaborates on the inclusion of verbatim text in +LR-box environments and commands, for those who are interested. "fancybox.sty" +also contains some nice verbatim macros and tricks, some of which are useful +for LR-box commands. + +The reason that you cannot normally include verbatim text in an LR-box +commands argument is that \TeX{} reads the whole argument before processing the +"\catcode" changes, at which point it is too late to change the category +codes. If this is all Greek to you,\footnote{% +Incidentally, many foreign language macros, such as "greek.tex", use +"\catcode" tricks which can cause problems in LR-box macros.} then just try +this \LaTeX{} example to see the problem: +\begin{LVerbatim} + \psframebox{\verb+\foo{bar}+} +\end{LVerbatim} + +The LR-box environments defined with \n\pslongbox{} do not have this problem +because <stuff> is not processed as an argument. Thus, this works: +\begin{example} + \pslongbox{MyFrame}{\psframebox} + \MyFrame \verb+\foo{bar}+\endMyFrame +\end{example} + +The commands +\begin{Ex} + \object \psverbboxtrue + \object \psverbboxfalse +\end{Ex} +switch into and out of, respectively, a special PSTricks mode that lets you +include verbatim text in any LR-box command. For example: +\begin{example} + \psverbboxtrue + \psframebox{\verb+\foo{bar}+} +\end{example} +However, this is not as robust. You must explicitly group color commands in +<stuff>, and LR-box commands that usually ignore spaces that follow +"{<stuff>}" might not do so when \n\psverbboxtrue{} is in effect. + + +\Section{Tips and More Tricks\label{tips}} + +\faq{How do I rotate/frame this or that with \LaTeX?} + +See "fancybox.sty" and its documentation. + +\faq{How can I suppress the PostScript so that I can use my document with a +non-PostScript dvi driver?} + +Put the command + \Mac \PSTricksOff +at the beginning of your document. You should then be able to print or preview +drafts of your document (minus the PostScript, and perhaps pretty strange +looking) with any dvi driver. + + +\faq{How can I improve the rendering of halftones?} + +This can be an important consideration when you have a halftone in the +background and text on top. You can try putting +\begin{LVerb} + \pstverb{106 45 {dup mul exch dup mul add 1.0 exch sub} setscreen} +\end{LVerb} +before the halftone, or in a header (as in headers and footers, not as in +PostScript header files), if you want it to have an effect on every page. + +"setscreen" is a device-dependent operator. + +\faq{What special characters can be active with PSTricks?} + +\Section{Including PostScript code\label{S-raw}} + +To learn about the PostScript language, consult Adobe's \emph{PostScript +Language Tutorial and Cookbook} (the ``Blue Book''), or Henry McGilton and +Mary Campione's \emph{PostScript by Example} (1992). Both are published by +Addison-Wesley. You may find that the Appendix of the Blue Book, plus an +understanding of how the stack works, is all you need to write simple code for +computing numbers (e.g., to specify coordinates or plots using PostScript). + +You may want to define \TeX{} macros for including PostScript fragments in +various places. All \TeX{} macros are expanded before being passed on to +PostScript. It is not always clear what this means. For example, suppose you +write +\begin{LVerb} + \SpecialCoor + \def\mydata{23 43} + \psline(!47 \mydata add) + \psline(!47 \mydata\ add) + \psline(!47 \mydata~add) + \psline(!47 \mydata{} add) +\end{LVerb} +You will get a PostScript error in each of the \n\psline{} commands. To see +what the argument is expanding to, try use \TeX's "\edef" and "\show". E.g., +\begin{LVerb} + \def\mydata{23 43} + \edef\temp{47 \mydata add} + \show\temp + \edef\temp{47 \mydata\ add} + \show\temp + \edef\temp{47 \mydata~add} + \show\temp + \edef\temp{47 \mydata{} add} + \show\temp +\end{LVerb} +\TeX{} expands the code, assigns its value to "\temp", and then displays the +value of "\temp" on your console. Hit <return> to procede. You fill find that +the four samples expand, respectively, to: +\begin{LVerb} + 47 23 43add + 47 23 43\ add + 47 23 43\penalty \@M \ add + 47 23 43{} add +\end{LVerb} +All you really wanted was a space between the "43" and "add". The command +"\space" will do the trick: +\begin{LVerb} + \psline(!47 \mydata\space add) +\end{LVerb} + +You can include balance braces "{"~"}"; these will be passed on verbatim to +PostScript. However, to include an unbalanced left or right brace, you have to +use, respectively, +\begin{Ex} + \object \pslbrace + \object \psrbrace +\end{Ex} +Don't bother trying "\}" or "\{". + +Whenever you insert PostScript code in a PSTricks argument, the dictionary on +the top of the dictionary stack is "tx@Dict", which is PSTrick's main +dictionary. If you want to define you own variables, you have two options: +\begin{description} + \item[Simplest] Always include a "@" in the variable names, because PSTricks +never uses "@" in its variables names. You are at a risk of overflowing the +"tx@Dict" dictionary, depending on your PostScript interpreter. You are also +more likely to collide with someone else's definitions, if there are multiple +authors contributing to the document. + \item[Safest] Create a dictionary named "TDict" for your scratch +computations. Be sure to remove it from the dictionary stack at the end of any +code you insert in an argument. E.g., +\begin{LVerb} + TDict 10 dict def TDict begin <your code> end +\end{LVerb} +\end{description} + +\section{Troubleshooting\label{troubleshooting}} +\setcounter{faq}{0} + +\faq{Why does the document bomb in the printer when the first item in a +\LaTeX{} file is a float?} + +When the first item in a \LaTeX{} file is a float, "\special"'s in the preamble +are discarded. In particular, the "\special" for including PSTricks's header +file is lost. The workaround is to but something before the float, or to +include the header file by a command-line option with your dvi-to-ps driver. + +\faq{I converted a \texttt{.dvi} file to PostScript, and then mailed it to a +colleague. It prints fine for me but bombs on her printer.} + +Here is the most likely (but not the only) cause of this problem. The +PostScript files you get when using PSTricks can contain long lines. This +should be acceptable to any proper PostScript interpreter, but the lines can +get chopped when mailing the file. There is no way to fix this in PSTricks, +but you can make a point of wrapping the lines of your PostScript files when +mailing them. E.g., on UNIX you can use "uuencode" and "uudecode", or you can +use the following AWK script to wrap the lines: +\begin{LVerb} + #! /bin/sh + # This script wraps all lines + # Usage (if script is named wrap): + # wrap < infile > outfile + awk ' + BEGIN { + N = 78 # Max line length + } + { if (length($0)<=N) + print + else { + currlength = 0 + for (i = 1; i <=NF; i++) { + if ((currlength = currlength + length($i) + 1) > N) { + printf "\n" + printf "%s", $i + currlength = length($i) + } + else + printf \ %s", $i + } + printf "\n" + } + } ' +\end{LVerb} + +\faq{The color commands cause extraneous vertical space to be inserted.} + +For example, this can happen if you start a \LaTeX{} "\parbox" or a "p{}" +column with a color command. The solution usually is to precede the color +command with "\leavevmode". + + +\faq{The color commands interfere with other color macros I use.} + +Try putting the command \Main\altcolormode{} at the beginning of your document. +This may or may not help. Be extra careful that the scope of color commands +does not extend across pages. This is generally a less robust color scheme. + +\faq{How do I stop floats from being the same color as surrounding material?} + +That's easy: Just put an explicit color command at the beginning of the float, +e.g., \n\black. + +\faq{When I use some color command in box macros or with \texttt{\string\setbox}, +the colors get all screwed up.} + +\label{colorboxproblems}% +If "\mybox" is a box register, and you write +\begin{LVerb} + \green Ho Hum. + \setbox\mybox=\hbox{Foo bar \blue fee fum} + Hi Ho. \red Diddley-dee + \box\mybox hum dee do +\end{LVerb} +then when "\mybox" is inserted, the current color is red and so "Foo bar" +comes out red (rather than green, which was the color in effect when the box +was set). The command that returns from \n\blue{} to the current color "green", +when the box is set, is executed after the "\hbox" is closed, which means that +"Hi Ho" is green, but "hum dee do" is still blue. + +This odd behavior is due to the fact that \TeX{} does not support color +internally, the way it supports font commands. The first thing to do is to +explicitly bracket any color commands inside the box. Second, be sure that the +current color is black when setting the box. Third, make other explicit color +changes where necessary if you still have problems. The color scheme invoked +by \n\altcolormode{} is slightly better behaved if you follow the first two +rules. + +Note that various box macros use "\setbox" and so these anomalies can arise +unexpectedly. + +\endinput + +%% END psd-help.tex diff --git a/Master/texmf-dist/doc/generic/pstricks/psd-node.tex b/Master/texmf-dist/doc/generic/pstricks/psd-node.tex new file mode 100644 index 00000000000..e6504ca8bf2 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pstricks/psd-node.tex @@ -0,0 +1,1279 @@ +%% BEGIN psd-node.tex + +\part{Nodes and Node Connections\label{P-nodes}} + +% This is a file marker for pst-node (e.g., \File{pst-node}), defined as a node: +\leavevmode +\marginpar{% + \leavevmode\lower 20pt\hbox{% + \hbox to0pt{\hbox to \linewidth{\hss\rnode{file}{\copy\filebox}\hss}\hss}% + \raise 10pt\hbox to \linewidth{\hss\large\bfseries\sffamily pst-node\hss}}}% +All the commands described in this part are contained in the file +"pst-node.tex" / "pst-node.sty". + +The node and node connection macros let you connect information and place +labels, without knowing the exact position of what you are connecting or of +where the lines should connect. These macros are useful for making graphs and +trees, mathematical diagrams, linguistic syntax diagrams, and connecting ideas +of any kind. They are the trickiest tricks in PSTricks! + +The node and node connection macros let you connect information and place +labels, without knowing the exact position of what you are connecting or where +the lines should connect. These macros are useful for making graphs and trees, +mathematical diagrams, linguistic syntax diagrams, and connecting ideas of any +kind. They are the trickiest tricks in PSTricks! + +There are three components to the node macros: +\begin{description} + \item[Node definitions] The node definitions let you assign a name and shape + to an object. See Section \ref{S-nodes}. + \item[Node connections] The node connections connect two nodes, identified + by their names. See Section \ref{S-nc}. + \item[Node labels] The node label commands let you affix labels to the node + connections. See Section \ref{S-nodelabels}. +\end{description} + +You can use these macros just about anywhere. The best way to position them +depends on the application. For greatest flexibility, you can use the nodes in +a \n\pspicture, positioning and rotating them with \n\rput. You can also use +them in alignment environments. "pst-node.tex" contains a special alignment +environment, \n\psmatrix, which is designed for positioning nodes in a grid, +such as in mathematical diagrams and some graphs. \n\psmatrix{} is described in +Section \ref{S-psmatrix}. "pst-node.tex" also contains high-level macros for +trees. These are described in Part \ref{P-trees}. + +But don't restrict yourself to these more obvious uses. For example: +\begin{example**} + \rnode{A}{% + \parbox{4cm}{\raggedright + I made the file symbol a node. Now I can draw an + arrow so that you know what I am talking about.}} + \ncarc[nodesep=8pt]{->}{A}{file} +\end{example**} + +\Section{Nodes\label{S-nodes}} + +Nodes have a name. a boundary and a center. + +\begin{Warning} +The name is for refering to the node when making node connections and labels. +You specify the name as an argument to the node commands. The name must +contain only letters and numbers, and must begin with a letter. Bad node names +can cause PostScript errors. +\end{Warning} + +The center of a node is where node connections point to. The boundary is for +determining where to connect a node connection. The various nodes differ in +how they determine the center and boundary. They also differ in what kind of +visable object they create. + +Here are the nodes: + +\begin{description} + +\mitem \rnode`[refpoint]'{name}{stuff} + + \n\rnode{} puts <stuff> in a box. The center of the node is <refpoint>, which +you can specify the same way as for \n\rput. + +\oitem \Rnode{name}{stuff} + + \n\Rnode{} also makes a box, but the center is set differently. If you align +\n\rnode's by their baseline, differences in the height and depth of the nodes +can cause connecting lines to be not quite parallel, such as in the following +example: +\begin{example**} + \Large + \rnode{A}{sp} \hskip 2cm \rnode{B}{Bit} + \ncline{A}{B} +\end{example**} +With \n\Rnode, the center is determined relative to the baseline: +\begin{example**} + \Large + \Rnode{A}{sp} \hskip 2cm \Rnode{B}{Bit} + \ncline{A}{B} +\end{example**} + +You can usually get by without fiddling with the center of the node, but to +modify it you set the +\begin{Ex} + \Par{href=num} + \Par{vref=dim} +\end{Ex} +parameters. In the horizontal direction, the center is located fraction +\p{href} from the center to the edge. E.g, if \p{href=-1}, the center is on +the left edge of the box. In the vertical direction, the center is located +distance \p{vref} from the baseline. The \p{vref} parameter is evaluated each +time \n\Rnode{} is used, so that you can use "ex" units to have the distance +adjust itself to the size of the current font (but without being sensitive to +differences in the size of letters within the current font). + +\mitem \pnode`\c~'{name} + + This creates a zero dimensional node at \c{}. + +\oitem \cnode`\c~'{radius}{name} + + This draws a circle. Here is an example with \n\pnode{} and \n\cnode: +\begin{MEx}(3,1.25) + \cnode(0,1){.25}{A} + \pnode(3,0){B} + \ncline{<-}{A}{B} +\end{MEx} + +\oitem \Cnode`\c~'{name} + + This is like \n\cnode, but the radius is the value of +\begin{Ex} + \Par{radius=dim} +\end{Ex} +This is convenient when you want many circle nodes of the same radius. + +\oitem \circlenode{name}{stuff} + + This is a variant of \n\pscirclebox{} that gives the node the shape of the +circle. + +\oitem \cnodeput`{angle}\c~'{name}{stuff} + + This is a variant of \n\cput{} that gives the node the shape of the +circle. That is, it is like +\begin{LVerb*} + \rput{<angle>}(<x>,<y>){\circlenode{<name>}{<stuff>}} +\end{LVerb*} + +\oitem \ovalnode{name}{stuff} + + This is a variant of \n\psovalbox{} that gives the node the shape of an +ellipse. Here is an example with \n\circlenode{} and \n\ovalnode: +\begin{example**} + \circlenode{A}{Circle} and \ovalnode{B}{Oval} + \ncbar[angle=90]{A}{B} +\end{example**} + + +\oitem \dianode{name}{stuff} + + This is like \n\diabox. + + +\oitem \trinode{name}{stuff} + + This is like \n\tribox. + +\begin{MEx}(4,3) + \rput[tl](0,3){\dianode{A}{Diamond}} + \rput[br](4,0){\trinode[trimode=L]{B}{Triangle}} + \nccurve[angleA=-135,angleB=90]{A}{B} +\end{MEx} + +\oitem \dotnode`\c~'{name} + + This is a variant of \n\psdot. For example: +\begin{MEx}(3,2) + \dotnode[dotstyle=triangle*,dotscale=2 1](0,0){A} + \dotnode[dotstyle=+](3,2){B} + \ncline[nodesep=3pt]{A}{B} +\end{MEx} + + +\oitem \fnode`\c~'{name} + + The "f" stands for ``frame''. This is like, but easier than, putting a +\n\psframe{} in an \n\rnode. +\begin{MEx}(3,2) + \fnode{A} + \fnode*[framesize=1 5pt](2,2){B} + \ncline[nodesep=3pt]{A}{B} +\end{MEx} +There are two differences between \n\fnode{} and \n\psframe: +\begin{itemize} + \item There is a single (optional) coordinate argument, that gives the + \emph{center} of the frame. + \item The width and height of the frame are set by the +\begin{Ex} + \Par{framesize=dim1 `dim2'} +\end{Ex} + parameter. If you omit <dim2>, you get a square frame. +\end{itemize} + +\end{description} + + +\Section{Node connections\label{S-nc}} + +All the node connection commands begin with "nc", and they all have the same +syntax:\footnote{% +The node connections can be used with \n\pscustom. The beginning of the node +connection is attached to the current point by a straight line, as with +\n\psarc.}$^,$\footnote{% +See page \protect\pageref{S-SpecialCoor} if you want to use the nodes as +coordinates in other PSTricks macros.} +\begin{LVerb*} + \<nodeconnection>[<par>]{<arrows>}{<nodeA>}{<nodeB>} +\end{LVerb*} +A line of some sort is drawn from <nodeA> to <nodeB>. Some of the node +connection commands are a little confusing, but with a little experimentation +you will figure them out, and you will be amazed at the things you can do. +When we refer to the "A" and "B" nodes below, we are referring only to the +order in which the names are given as arguments to the node connection +macros.\footnote{% +When a node name cannot be found on the same page as the node connection +command, you get either no node connection or a nonsense node connection. +However, \TeX{} will not report any errors.} + +The node connections use many of the usual graphics parameters, plus a few +special ones. Let's start with one that applies to all the node connections: +\begin{Ex} + \Par{nodesep=dim} +\end{Ex} +\p{nodesep} is the border around the nodes that is added for the purpose of +determining where to connect the lines. + +For this and other node connection parameters, you can set different values +for the two ends of the node connection. Set the parameter \p{nodesepA} for +the first node, and set \p{nodesepB} for the second node. + +The first two node connections draw a line or arc directly between the two +nodes: +\begin{description} + +\oitem \ncline`{arrows}'{nodeA}{nodeB} + +This draws a straight line between the nodes. For example: +\begin{MEx}(4,3) + \rput[bl](0,0){\rnode{A}{Idea 1}} + \rput[tr](4,3){\rnode{B}{Idea 2}} + \ncline[nodesep=3pt]{<->}{A}{B} +\end{MEx} + +\oitem \ncarc`{arrows}'{nodeA}{nodeB} + +This connects the two nodes with an arc. +\begin{MEx}[-.5,-.5](3.5,2.5) + \cnodeput(0,0){A}{X} + \cnodeput(3,2){B}{Y} + \psset{nodesep=3pt} + \ncarc{->}{A}{B} + \ncarc{->}{B}{A} +\end{MEx} +The angle between the arc and the line between the two nodes is\footnote{% +Rather than using a true arc, \n\ncarc{} actually draws a bezier curve. When +connecting two circular nodes using the default parameter values, the curve +will be indistinguishable from a true arc. However, \n\ncarc{} is more +flexible than an arc, and works right connecting nodes of different shapes and +sizes. You can set \p{arcangleA} and \p{arcangleB} separately, and you can +control the curvature with the \p{ncurv} parameter, which is described on page +\pageref{p+ncurv}.} +\begin{Ex} + \Par{arcangle=angle} +\end{Ex} + +\end{description} + +\n\ncline{} and \n\ncarc{} both determine the angle at which the node +connections join by the relative position of the two nodes. With the next +group of node connections, you specify one or both of the angles in absolute +terms, by setting the +\begin{Ex} + \Par{angle=angle} +\end{Ex} +(and \p{angleA} and \p{angleB}) parameter. + +You also specify the length of the line segment where the node connection +joins at one or both of the ends (the ``arms'') by setting the +\begin{Ex} + \Par{arm=dim} +\end{Ex} +(and \p{armA} and \p{armB}) parameter. + +These node connections all consist of several line segments, including the +arms. The value of \p{linearc} is used for rounding the corners. + +Here they are, starting with the simplest one: + +\begin{description} + +\oitem \ncdiag`{arrows}'{nodeA}{nodeB} + +An arm is drawn at each node, joining at angle \p{angleA} or \p{angleB}, +and with a length of \p{armA} or \p{armB}. Then the two arms are connected +by a straight line, so that the whole line has three line segments. +For example: +\begin{MEx}(4,3) + \rput[tl](0,3){\rnode{A}{\psframebox{Node A}}} + \rput[br](4,0){\ovalnode{B}{Node B}} + \ncdiag[angleA=-90, angleB=90, arm=.5, linearc=.2]{A}{B} +\end{MEx} + +You can also set one or both of the arms to zero length. For example, if you +set \p{arm=0}, the nodes are connected by a straight line, but you get to +determine where the line connects (whereas the connection point is determined +automatically by \n\ncline). Compare this use of \n\ncdiag{} with \n\ncline{} +in the following example: +\begin{MEx}[0,-.5](4,2.5) + \rput[r](4,1){\ovalnode{R}{Root}} + \cnodeput(1,2){A}{XX} + \cnodeput(1,0){B}{YY} + \ncdiag[angleB=180, arm=0]{<-}{A}{R} + \ncline{<-}{B}{R} +\end{MEx} +(Note that in this example, the default value \p{angleA=0} is used.) + +\oitem \ncdiagg`{arrows}'{nodeA}{nodeB} + +\n\ncdiagg{} is similar to \n\ncdiag, but only the arm for node A is drawn. +The end of this arm is then connected directly to node B. Compare +\n\ncdiagg{} with \n\ncdiag{} when \p{armB=0}: +\begin{MEx}[-.5,-1](3.5,1) + \cnode(0,0){12pt}{a} + \rput[l](3,1){\rnode{b}{H}} + \rput[l](3,-1){\rnode{c}{T}} + \ncdiagg[angleA=180, armA=1.5, nodesepA=3pt]{b}{a} + "\nbput[npos=1.2]{\texttt{\string\ncdiagg}} + \ncdiag[angleA=180, armA=1.5, armB=0, nodesepA=3pt]{c}{a} + "\naput[npos=1.2]{\texttt{\string\ncdiag}} +\end{MEx} + + You can use \n\ncdiagg{} with \p{armA=0} if you want a straight line that +joins to node A at the angle you specify, and to node B at an angle that is +determined automatically. + +\oitem \ncbar`{arrows}'{nodeA}{nodeB} + + This node connection consists of a line with arms dropping ``down'', at +right angles, to meet two nodes at an angle \p{angleA}. Each arm is at least +of length \p{armA} or \p{armB}, but one may be need to be longer. +\begin{example**} + \rnode{A}{Connect} some \rnode{B}{words}! + \ncbar[nodesep=3pt,angle=-90]{<-**}{A}{B} + \ncbar[nodesep=3pt,angle=70]{A}{B} +\end{example**} + Generally, the whole line has three straight segments. + +\oitem \ncangle`{arrows}'{nodeA}{nodeB} + + + Now we get to a more complicated node connection. \n\ncangle{} typically +draws three line segments, like \n\ncdiag. However, rather than fixing the +length of arm A, we adjust arm A so that the line joining the two arms meets +arm A at a right angle. For example: +\begin{MEx}(4,3) + \rput[tl](0,3){\rnode{A}{\psframebox{Node A}}} + \rput[br](4,0){\ovalnode{B}{Node B}} + \ncangle[angleA=-90,angleB=90,armB=1cm]{A}{B} +\end{MEx} +Now watch what happens when we change \p{angleA}: +\begin{MEx}(4,3) + \rput[tl](0,3){\rnode{A}{\psframebox{Node A}}} + "\nput[labelsep=0]{-70}{A}{% + " \psarcn(0,0){.4cm}{0}{-70} + " \uput{.4cm}[-35](0,0){\texttt{angleA}}} + \rput[br](4,0){\ovalnode{B}{Node B}} + \ncangle[angleA=-70,angleB=90,armB=1cm,linewidth=1.2pt]{A}{B} + "\nput[labelsep=0]{90}{B}{% + " \rput[bl](2pt,1pt){% + " \valign{% + " \vfil#\vfil\cr + " \hbox{\psscaleboxto(.3,.95cm){\}}}\cr% + " \hbox{\kern 1pt{\texttt{armB}}}\cr}}} + "\ncput[nrot=:U,npos=1]{\psframe[dimen=middle](0,0)(.35,.35)} +\end{MEx} + +\n\ncangle{} is also a good way to join nodes by a right angle, with just two +line segments, as in this example: +\begin{MEx}(4,2) + \rput[tl](0,2){\rnode{A}{\psframebox{Node A}}} + \rput[br](4,0){\ovalnode{B}{Node B}} + \ncangle[angleB=90, armB=0, linearc=.5]{A}{B} +\end{MEx} + +\oitem \ncangles`{arrows}'{nodeA}{nodeB} + + \n\ncangles{} is similar to \n\ncangle, but the length of arm A is fixed by +he \p{armA} parameter. Arm A is connected to arm B by two line segments that +eet arm A and each other at right angles. The angle at which they join arm B, +and the length of the connecting segments, depends on the positions of the two +arms. \n\ncangles{} generally draws a total of four line segments.\footnote{% +Hence there is one more angle than \n\ncangle, and hence the "s" in +\n\ncangles.} +For example: +\begin{MEx}(4,4) + \rput[tl](0,4){\rnode{A}{\psframebox{Node A}}} + \rput[br](4,0){\ovalnode{B}{Node B}} + \ncangles[angleA=-90, armA=1cm, armB=.5cm, linearc=.15]{A}{B} +\end{MEx} + +Let's see what happens to the previous example when we change \p{angleB}: +\begin{MEx}(4,4) + \rput[tl](0,4){\rnode{A}{\psframebox{Node A}}} + \rput[br](4,0){\ovalnode{B}{Node B}} + \ncangles[angleA=-90, angleB=135, armA=1cm, armB=.5cm, + linearc=.15]{A}{B} + "\nput[labelsep=0]{-90}{A}{% + " \psarcn(0,0){.4cm}{0}{-90} + " \uput{.4cm}[-45](0,0){\texttt{angleA}} + " \rput[tr](-2pt,0){% + " \valign{% + " \vfil#\vfil\cr + " \hbox{\texttt{armA}\kern 1pt}\cr + " \hbox{\psscaleboxto(.28,.95cm){\{}}\cr% + " \cr}}} + "\nput[labelsep=0]{135}{B}{% + " \psarc(0,0){.4cm}{0}{133} + " \uput{.4cm}[50.5](0,0){\texttt{angleB}} + " } + "\ncput[nrot=:L,npos=2]{\psline(0,-.35)(-.35,-.35)(-.35,0)} + "\ncput[npos=3.5]{% + " \rput[r](-.8,0){\rnode{arm}{\texttt{armB}}} + " \pnode{brak}}% + "\ncline[nodesep=3pt]{->}{arm}{brak} +\end{MEx} + +\oitem \ncloop`{arrows}'{nodeA}{nodeB} + + \n\ncloop{} is also in the same family as \n\ncangle{} and \n\ncangles, but +now typically 5 line segments are drawn. Hence, \n\ncloop{} can reach around +to opposite sides of the nodes. The lengths of the arms are fixed by \p{armA} +and \p{armB}. Starting at arm A, \n\ncloop{} makes a 90 degree turn to the +left, drawing a segment of length +\begin{Ex} + \Par{loopsize=dim} +\end{Ex} +This segment connects to arm B the way arm A connects to arm B with \n\ncline; +that is, two more segments are drawn, which join the first segment and each +other at right angles, and then join arm B. For example: +\begin{example**} + "\vrule width 0pt height 1cm + \rnode{a}{\psframebox{\Huge A loop}} + \ncloop[angleB=180,loopsize=1,arm=.5,linearc=.2]{->}{a}{a} + "\ncput[npos=3.5,nrot=:U]{\psline{|<->|}(.5,-.2)(-.5,-.2)} + "\nbput[npos=3.5,nrot=:D,labelsep=.35cm]{{\tt loopsize}} + "\kern .5cm +\end{example**} +In this example, node A and node B are the same node! You can do this with all +the node connections (but it doesn't always make sense). + +Here is an example where \n\ncloop{} connects two different nodes: +\begin{example**} + \parbox{3cm}{% + \rnode{A}{\psframebox{\large\textbf{Begin}}} + \vspace{1cm}\hspace*{\fill} + \rnode{B}{\psframebox{\large\textbf{End}}} + \ncloop[angleA=180,loopsize=.9,arm=.5,linearc=.2]{->}{A}{B}} + "\ncput[npos=1.5,nrot=:U]{\psline{|<->|}(.45,-.2)(-.45,-.2)} + "\nbput[npos=1.5,nrot=:D,labelsep=.35cm]{\texttt{loopsize}} + "\kern .5cm +\end{example**} + +\end{description} + +The next two node connections are a little different from the rest. + +\begin{description} +\oitem \nccurve`{arrows}'{nodeA}{nodeB} + + \n\nccurve{} draws a bezier curve between the nodes. +\begin{MEx}(4,3) + \rput[bl](0,0){\rnode{A}{\psframebox{Node A}}} + \rput[tr](4,3){\ovalnode{B}{Node B}} + \nccurve[angleB=180]{A}{B} +\end{MEx} +You specify the angle at which the curve joins the nodes by setting the +\p{angle} (and \p{angleA} and \p{angleB}) parameter. The distance to the +control points is set with the +\begin{Ex} + \Par{ncurv=num} +\end{Ex} +(and \p{ncurvA} and \p{ncurvB}) parameter. A lower number gives a tighter +curve. (The distance between the beginning of the arc and the first control +point is one-half \p{ncurvA} times the distance between the two endpoints.) + +\oitem \nccircle`{arrows}'{node}{radius} + +\n\nccircle{} draws a circle, or part of a circle, that, if complete, would +pass through the center of the node counterclockwise, at an angle of +\p{angleA}. +\begin{example**} + "\vrule width 0pt height 1.4cm + \rnode{A}{\textbf{back}} + \nccircle[nodesep=3pt]{->}{A}{.7cm} + \kern 5pt +\end{example**} +\n\nccircle{} can only connect a node to itself; it is the only node +connection with this property. \n\nccircle{} is also special because it has an +additional argument, for specifying the radius of the circle. + +\end{description} + +The last two node connections are also special. Rather than connecting the +nodes with an open curve, they enclose the nodes in a box or curved box. You +can think of them as variants of \n\ncline{} and \n\ncarc. In both cases, the +half the width of the box is +\begin{Ex} + \Par{boxsize=dim} +\end{Ex} +You have to set this yourself to the right size, so that the nodes fit inside +the box. The \p{boxsize} parameter actually sets the \p{boxheight} and +\p{boxdepth} parameters. The ends of the boxes extend beyond the nodes by +\p{nodesepA} and \p{nodesepB}. + +\begin{description} + +\oitem \ncbox{nodeA}{nodeB} + \n\ncbox{} encloses the nodes in a box with straight sides. For example: +\begin{MEx}[0,-.5](4,2.5) + \rput[bl](.5,0){\rnode{A}{Idea 1}} + \rput[tr](3.5,2){\rnode{B}{Idea 2}} + \ncbox[nodesep=.5cm,boxsize=.6,linearc=.2, + linestyle=dashed]{A}{B} +\end{MEx} + +\oitem \ncarcbox{nodeA}{nodeB} + + \n\ncarcbox{} encloses the nodes in a curved box that is \p{arcangleA} away +from the line connecting the two nodes. +\begin{MEx}[0,-.5](4,2.5) + \rput[bl](.5,0){\rnode{A}{1}} + \rput[tr](3.5,2){\rnode{B}{2}} + \ncarcbox[nodesep=.2cm,boxsize=.4,linearc=.4, + arcangle=50]{<->}{A}{B} +\end{MEx} +The arc is drawn counterclockwise from node A to node B. + +\end{description} + +There is one other node connection parameter that applies to all the node +connections, except \n\ncarcbox: +\begin{Ex} + \Par{offset=dim} +\end{Ex} +(You can also set \p{offsetA} and \p{offsetB} independently.) This shifts the +point where the connection joins up by <dim> (given the convention that +connections go from left to right). + +There are two main uses for this parameter. First, it lets you make two +parallel lines with \n\ncline, as in the following example: +\begin{MEx}[-.5,-.5](3.5,2.5) + \cnodeput(0,0){A}{X} + \cnodeput(3,2){B}{Y} + \psset{nodesep=3pt,offset=4pt,arrows=->} + \ncline{A}{B} + \ncline{B}{A} +\end{MEx} + +Second, it lets you join a node connection to a rectangular node at a right +angle, without limiting yourself to positions that lie directly above, below, +or to either side of the center of the node. This is useful, for example, if +you are making several connections to the same node, as in the following +example: +\begin{example**} + \rnode{A}{Word1} and \rnode{B}{Word2} and \rnode{C}{Word3} + \ncbar[offsetB=4pt,angleA=-90,nodesep=3pt]{->}{A}{B} + \ncbar[offsetA=4pt,angleA=-90,nodesep=3pt]{->}{B}{C} +\end{example**} + +Sometimes you might be aligning several nodes, such as in a tree, and you want +to ends or the arms of the node connections to line up. This won't happen +naturally if the nodes are of different size, as you can see in this example: +\begin{MEx}[-.5,0](3.5,3) + "\psset{unit=.9} + \Huge + \cnode(1,3){4pt}{a} + \rput[B](0,0){\Rnode{b}{H}} + \rput[B](2,0){\Rnode{c}{a}} + \psset{angleA=90,armA=1,nodesepA=3pt} + \ncdiagg{b}{a} + \ncdiagg{c}{a} +\end{MEx} + +%%??? FIXME +If you set the \p{nodesep} or \p{arm} parameter to a negative value, PSTricks +will measure the distance to the beginning of the node connection or to the +end of the arm relative to the center of the node, rather than relative to the +boundary of the node or the beginning of the arm. Here is how we fix the +previous example: +\begin{MEx}[-.5,0](3.5,3) + "\psset{unit=.9} + \Huge + \cnode(1,3){4pt}{a} + \rput[B](0,0){\Rnode{b}{H}} + \rput[B](2,0){\Rnode{c}{a}} + \psset{angleA=90,armA=1,YnodesepA=12pt} + \ncdiagg{b}{a} + \ncdiagg{c}{a} +\end{MEx} +Note also the use of \n\Rnode. + +One more parameter trick: By using the \p{border} parameter, you can create +the impression that one node connection passes over another. + +The node connection commands make interesting drawing tools as well, as an +alternative to \n\psline{} for connecting two points. There are variants of +the node connection commands for this purpose. Each begins with "pc" (for +``point connection'') rather than "nc". E.g., +\begin{LVerb} + \pcarc{<->}(3,4)(6,9) +\end{LVerb} +gives the same result as +\begin{LVerb} + \pnode(3,4){A} + \pnode(6,9){B} + \pcarc{<->}{A}{B} +\end{LVerb} + +Only \n\nccircle{} does not have a "pc" variant: +\begin{center} +\def\oitem{\GetMacroDef\oitemi} +\def\oitemi#1{\addtoquickref{object}{#1}{\MainFont\Main#1}} +\addtolength{\tabcolsep}{8pt} +\begin{tabular}{ll} + \emph{Command} & \emph{Corresponds to:}\\ + + \oitem \pcline`{arrows}'\c1\c2 + & \n\ncline\\ + + \oitem \pccurve`{arrows}'\c1\c2 + & \n\nccurve\\ + + \oitem \pcarc`{arrows}'\c1\c2 + & \n\ncarc\\ + + \oitem \pcbar`{arrows}'\c1\c2 + & \n\ncbar\\ + + \oitem \pcdiag`{arrows}'\c1\c2 + & \n\ncdiag\\ + + \oitem \pcdiagg`{arrows}'\c1\c2 + & \n\ncdiagg\\ + + \oitem \pcangle`{arrows}'\c1\c2 + & \n\ncangle\\ + + \oitem \pcangles`{arrows}'\c1\c2 + & \n\ncangles\\ + + \oitem \pcloop`{arrows}'\c1\c2 + & \n\ncloop\\ + + \oitem \pcbox\c1\c2 + & \n\ncbox\\ + + \oitem \pcarcbox\c1\c2 + & \n\ncarcbox +\end{tabular} +\end{center} + + +\Section{Node connections labels: I\label{S-nodelabels}} + +Now we come to the commands for attaching labels to the node connections. The +label command must come right after the node connection to which the label is +to be attached. You can attach more than one label to a node connection, and a +label can include more nodes. + +The node label commands must end up on the same \TeX{} page as the node +connection to which the label corresponds. + +There are two groups of connection labels, which differ in how they select the +point on the node connection. In this section we describe the first group: +\begin{Ex} + \object \ncput`*[par]'{stuff} + \object \naput`*[par]'{stuff} + \object \nbput`*[par]'{stuff} +\end{Ex} + +These three command differ in where the labels end up with respect to the line: +\begin{quote} +\begin{tabular}{ll} + \n\ncput & \emph{on} the line\\ + \n\naput & \emph{above} the line\\ + \n\nbput & \emph{below} the line +\end{tabular} +\end{quote} +(using the convention that node connections go from left to right). + +Here is an example: +\begin{MEx}[0,-1.5](3.5,1.5) + \cnode(0,0){.5cm}{root} + \cnode*(3,1.5){4pt}{A} + \cnode*(3,0){4pt}{B} + \cnode*(3,-1.5){4pt}{C} + \psset{nodesep=3pt} + \ncline{root}{A} + \naput{above} + \ncline{root}{B} + \ncput*{on} + \ncline{root}{C} + \nbput{below} +\end{MEx} + +\n\naput{} and \n\nbput{} use the same algorithm as \n\uput{} for displacing +the labels, and the distance beteen the line and labels is \p{labelsep} (at +least if the lines are straight). + +\n\ncput{} uses the same system as \n\rput{} for setting the reference +point. You change the reference point by setting the +\begin{Ex} + \Par{ref=ref} +\end{Ex} +parameter. + +Rotation is also controlled by a graphics parameter: +\begin{Ex} + \Par{nrot=rot} +\end{Ex} +<rot> can be in any of the forms suitable for \n\rput, and you can also use +the form +\begin{LVerb*} + {:<angle>} +\end{LVerb*} +The angle is then measured with respect to the node connection. E.g., if the +angle is "{:U}", then the label runs parallel to the node connection. Since +the label can include other put commands, you really have a lot of control +over the label position. + +The next example illustrates the use "{:<angle>}", the \p{offset} parameter, +and \n\pcline: +\begin{MEx}(4,2.3) + \pspolygon(0,0)(4,2)(4,0) + \pcline[offset=12pt]{|-|}(0,0)(4,2) + \ncput*[nrot=:U]{Length} +\end{MEx} + +Here is a repeat of an earlier example, now using "{:<angle>}": +\begin{MEx}[0,-1.5](3.5,1.5) + \cnode(0,0){.5cm}{root} + \cnode*(3,1.5){4pt}{A} + \cnode*(3,0){4pt}{B} + \cnode*(3,-1.5){4pt}{C} + \psset{nodesep=3pt,nrot=:U} + \ncline{root}{A} + \naput{above} + \ncline{root}{B} + \ncput*{on} + \ncline{root}{C} + \nbput{below} +\end{MEx} + +The position on the node connection is set by the +\begin{Ex} + \Par{npos=num} +\end{Ex} +parameter, roughly according to the following scheme: Each node connection has +potentially one or more segments, including the arms and connecting lines. +A number \p{npos} between 0 and 1 picks a point on the first segment from node +"A" to "B" (fraction \p{npos} from the beginning to the end of the segment), +a number between 1 and 2 picks a number on the second segment, and so on. + +Each node connection has its own default value of \p{npos}. If you leave the +\p{npos} parameter value empty (e.g., "[npos=]"), then the default is +substituted. This is the default mode. + +Here are the details for each node connection: +\begin{center} + \catcode`\@=11\setbox\@tempboxa=\hbox{1.5}% + \edef\t#1{\noexpand\hbox to \the\wd\@tempboxa{\noexpand\tt\noexpand\hss#1}} + \begin{tabular}{lccc} + \emph{Connection} & \emph{Segments} & \emph{Range} & \emph{Default}\\[2pt] + \n\ncline & 1 & $0\leq pos\leq 1$ & "0.5"\\ + \n\nccurve & 1 & $0\leq pos\leq 1$ & "0.5"\\ + \n\ncarc & 1 & $0\leq pos\leq 1$ & "0.5"\\ + \n\ncbar & 3 & $0\leq pos\leq 3$ & "1.5"\\ + \n\ncdiag & 3 & $0\leq pos\leq 3$ & "1.5"\\ + \n\ncdiagg & 2 & $0\leq pos\leq 2$ & "0.5"\\ + \n\ncangle & 3 & $0\leq pos\leq 3$ & "1.5"\\ + \n\ncangles & 4 & $0\leq pos\leq 4$ & "1.5"\\ + \n\ncloop & 5 & $0\leq pos\leq 5$ & "2.5"\\ + \n\nccircle & 1 & $0\leq pos\leq 1$ & "0.5"\\ + \n\ncbox & 4 & $0\leq pos\leq 4$ & "0.5"\\ + \n\ncarcbox & 4 & $0\leq pos\leq 4$ & "0.5" + \end{tabular} +\end{center} + +Here is an example: +\begin{MEx}(4,3) + \rput[tl](0,3){\rnode{A}{\psframebox{Node A}}} + \rput[br](3.5,0){\ovalnode{B}{Node B}} + \ncangles[angleA=-90,arm=.4cm,linearc=.15]{A}{B} + \ncput*{d} + \nbput[nrot=:D,npos=2.5]{par} +\end{MEx} + +With \n\ncbox{} and \n\ncarcbox, the segments run counterclockwise, starting +with the lower side of the box. Hence, with \n\nbput{} the label ends up +outside the box, and with \n\naput{} the label ends up inside the box. +\begin{MEx}[0,-.5](4,2.5) + \rput[bl](.5,0){\rnode{A}{1}} + \rput[tr](3.5,2){\rnode{B}{2}} + \ncarcbox[nodesep=.2cm,boxsize=.4,linearc=.4, + arcangle=50,linestyle=dashed]{<->}{A}{B} + \nbput[nrot=:U]{set} + \nbput[npos=2]{II} +\end{MEx} + +If you set the parameter +\begin{Ex} + \Par{shortput=none/nab/tablr/tab} +\end{Ex} +to "nab", then immediately following a node connection or another node +connection label you can use "^" instead of \n\naput{} and "_" instead of +\n\nbput. +\begin{MEx}[0,-1.5](3.5,1.5) + \cnode(0,0){.5cm}{root} + \cnode*(3,1.5){4pt}{A} + \cnode*(3,-1.5){4pt}{C} + \psset{nodesep=3pt,shortput=nab} + \ncline{root}{A}^{$x$} + \ncline{root}{C}_{$y$} +\end{MEx} +You can still have parameter changes with the short "^" and "_" forms. Another +example is given on page \pageref{nab-example}. + +If you have set \p{shortput=nab}, and then you want to use a true "^" or "_" +character right after a node connection, you must precede the "^" or "_" by +"{}" so that PSTricks does not convert it to "\naput" or "\nbput". + +You can change the characters that you use for the short form with the + \Mac \MakeShortNab{<char1>}{<char2>} +command.\footnote{% +You can also use \n\MakeShortNab{} if you want to use "^" and "_" with +non-standard category codes. Just invoke the command after you have made your +"\catcode" changes.} + +The \p{shortput=tablr} and \p{shortput=tab} options are described on pages +\pageref{tablr} and \pageref{tab}, respectively. + +\Section{Node connection labels: II} + +Now the second group of node connections: +\begin{Ex} + \object \tvput`*[par]'{stuff} + \object \tlput`*[par]'{stuff} + \object \trput`*[par]'{stuff} + \object \thput`*[par]'{stuff} + \object \taput`*[par]'{stuff} + \object \tbput`*[par]'{stuff} +\end{Ex} + +The difference between these commands and the "\n*put" commands is that these +find the position as an intermediate point between the centers of the nodes, +either in the horizontal or vertical direction. These are good for trees and +mathematical diagrams, where it can sometimes be nice to have the labels be +horizontally or vertically aligned. The "t" stands for ``tree''. + +You specify the position by setting the +\begin{Ex} + \Par{tpos=num} +\end{Ex} +parameter. + +\n\tvput, \n\tlput{} and \n\trput{} find the position that lies fraction +<tpos> in the \emph{vertical} direction from the upper node to the lower +node. \n\thput, \n\taput{} and \n\tbput{} find the position that lies fraction +<tpos> in the \emph{horizontal} direction from the left node to the right +node. +Then the commands put the label on or next to the line, as follows: +\begin{center} +\begin{tabular}{lll} + \emph{Command} & \emph{Direction} & \emph{Placement}\\[3pt] + \n\tvput & vertical & middle\\ + \n\tlput & vertical & left\\ + \n\trput & vertical & right\\ + \n\thput & horizontal & middle\\ + \n\taput & horizontal & above\\ + \n\tbput & horizontal & below +\end{tabular} +\end{center} + +Here is an example: +\begin{example*} + \[ + \setlength{\arraycolsep}{1.1cm} + \begin{array}{cc} + \Rnode{a}{(X-A)} & \Rnode{b}{A} \\[1.5cm] + \Rnode{c}{x} & \Rnode{d}{\tilde{X}} + \end{array} + \psset{nodesep=5pt,arrows=->} + \everypsbox{\scriptstyle} + \ncline{a}{c}\tlput{r} + \ncline{a}{b}\taput{u} + \ncline[linestyle=dashed]{c}{d}\tbput{b} + \ncline{b}{d}\trput{s} + " \everypsbox{} + " \begin{array}{cc} + " \rnode{a}{(X-A)} & \rnode{b}{a} \\[1.5cm] + " \rnode{c}{x} & \rnode{d}{\tilde{X}} + " \end{array} + " \psset{nodesep=5pt,arrows=->}\everypsbox{\scriptstyle} + " \ncline{a}{c}\nbput{r} + " \ncline{a}{b}\naput{u} + " \ncline[linestyle=dashed]{c}{d}\nbput{b} + " \ncline{b}{d}\naput{s} + \] +\end{example*} +On the left is the diagram with \n\tlput, \n\trput\, \n\tbput{} and \n\Rnode, +as shown in the code. On the right is the same diagram, but with \n\naput\, +\n\nbput{} and \n\rnode. + +These do not have a rotation argument or parameter. However, you can rotate +<stuff> in 90 degree increments using box rotations (e.g., \n\rotateleft). + +If you set \p{shortput=tablr}, then you can use the following single-character +abbreviations for the "t" put commands:\label{tablr} +\begin{center} + \begin{tabular}{rl} + \emph{Char.} & \emph{Short for:}\\[2pt] + "^" & \n\taput \\ + "_" & \n\tbput \\ + \DeleteShortMeta "<" & \n\tlput \\ + ">" & \n\trput + \end{tabular} +\end{center} + +You can change the character abbreviations with + \Mac \MakeShortTablr{<char1>}{<char2>}{<char3>}{<char4>} + +The "t" put commands, including an example of \p{shortput=tablr}, will be +shown further when we get to mathematical diagrams and trees. + +\begin{drivers} The node macros use \n\pstVerb{} and \n\pstverbscale. +\end{drivers} + +\Section{Attaching labels to nodes} + +The command + \Mac \nput`*[par]'{refangle}{name}{stuff} +affixes <stuff> to node <name>. It is positioned distance \p{labelsep} from +the node, in the direction <refangle> from the center of the node. The +algorithm is the same as for \n\uput. If you want to rotate the node, set the +\begin{Ex} + \Par{rot=rot} +\end{Ex} +parameter, where <rot> is a rotation that would be valid for \n\rput.% +\footnote{Not to be confused with the "nput" parameter.} +The position of the label also takes into account the \p{offsetA} +parameter. If \p{labelsep} is negative, then the distance is from the center +of the node rather than from the boundary, as with \p{nodesep}. + +Here is how I used \n\nput{} to mark an angle in a previous example: +\begin{MEx}(4,3) + \rput[br](4,0){\ovalnode{B}{Node B}} + \rput[tl](0,3){\rnode{A}{\psframebox{Node A}}} + \nput[labelsep=0]{-70}{A}{% + \psarcn(0,0){.4cm}{0}{-70} + \uput{.4cm}[-35](0,0){\texttt{angleA}}} + \ncangle[angleA=-70,angleB=90,armB=1cm,linewidth=1.2pt]{A}{B} + \ncput[nrot=:U,npos=1]{\psframe[dimen=middle](0,0)(.35,.35)} +\end{MEx} + +\Section{Mathematical diagrams and graphs\label{S-psmatrix}} + +For some applications, such as mathematical diagrams and graphs, it is useful +to arrange nodes on a grid. You can do this with alignment environments, such +as \TeX's "\halign"primitive, \LaTeX's "tabular" environment, and \AmS-\TeX's +"\matrix", but PSTricks contains its own alignment environment that is +especially adapted for this purpose: +\begin{Ex} + \object \psmatrix{} ... \string\endpsmatrix +\end{Ex} + +Here is an example +\begin{example**} + $ + \psmatrix[colsep=1cm,rowsep=1cm] + & A \\ + B & E & C \\ + & D & + \endpsmatrix + $ +\end{example**} + +As an alignment environment, \n\psmatrix{} is similar to \AmS-\TeX's +"\matrix". There is no argument for specifying the columns. Instead, you can +just use as many columns as you need. The entries are horizontally centered. +Rows are ended by "\\". \n\psmatrix{} can be used in or out of math mode. + +Our first example wasn't very interesting, because we didn't make use of the +nodes. Actually, each entry is a node. The name of the node in row <row> and +column <col> is "{<row>,<col>}", with no spaces. Let's see some node +connections: +\begin{example**} + $ + \psmatrix[colsep=1cm] + & X \\ + Y & Z + \endpsmatrix + \everypsbox{\scriptstyle}% + \psset{nodesep=3pt,arrows=->} + \ncline{1,2}{2,1} + \tlput{f} + \ncline{1,2}{2,2} + \trput{g} + \ncline[linestyle=dotted]{2,1}{2,2} + \tbput{h} + $ +\end{example**} + +You can include the node connections inside the \n\psmatrix, in the last entry +and right before \n\endpsmatrix. One advantage to doing this is that +\p{shortput=tab} is the default within a \n\psmatrix. +\begin{example**} + $ + \begin{psmatrix} + U \\ + & X\times_Z Y & X \\ + & Y & Z + \psset{arrows=->,nodesep=3pt} + \everypsbox{\scriptstyle} + \ncline{1,1}{2,2}_{y} + \ncline[doubleline=true,linestyle=dashed]{-}{1,1}{2,3}^{x} + \ncline{2,2}{3,2}<{q} + \ncline{2,2}{2,3}_{p} + \ncline{2,3}{3,3}>{f} + \ncline{3,2}{3,3}_{g} + \end{psmatrix} + $ +\end{example**} + +You can change the kind of nodes that are made by setting the +\begin{Ex} + \Par{mnode=type} +\end{Ex} +parameter. Valid types are "R", "r", "C", "f", "p", "circle", "oval", "dia", +"tri", "dot" and "none", standing for \n\Rnode, \n\rnode, \n\Cnode, \n\fnode, +\n\pnode, \n\circlenode, \n\ovalnode, \n\dotnode{} and no node, +respectively. Note that for circles, you use \p{mnode=C} and set the radius +with the \p{radius} parameter. + +For example:\label{nab-example} +\begin{example**} + \psmatrix[mnode=circle,colsep=1] + & A \\ + B & E & C \\ + & D & + \endpsmatrix + \psset{shortput=nab,arrows=->,labelsep=3pt} + \small + \ncline{2,2}{2,3}^[npos=.75]{a} + \ncline{2,2}{2,1}^{b} + \ncline{3,2}{2,1}^{c} + \ncarc[arcangle=-40,border=3pt]{3,2}{1,2} + _[npos=.3]{d}^[npos=.7]{e} + \ncarc[arcangle=12]{1,2}{2,1}^{f} + \ncarc[arcangle=12]{2,1}{1,2}^{g} +\end{example**} + +Note that a node is made only for the non-empty entries. You can also specify +a node for the empty entries by setting the +\begin{Ex} + \Par{emnode=type} +\end{Ex} +parameter. + +You can change parameters for a single entry by starting this entry with the +parameter changes, enclosed in square brackets. Note that the changes affect +the way the node is made, but not contents of the entry (use \n\psset{} for +this purpose). For example: +\begin{example**} + $ + \psmatrix[colsep=1cm] + & [mnode=circle] X \\ + Y & Z + \endpsmatrix + \psset{nodesep=3pt,arrows=->} + \ncline{1,2}{2,1} + \ncline{1,2}{2,2} + \ncline[linestyle=dotted]{2,1}{2,2} + $ +\end{example**} +If you want your entry to begin with a "[" that is not meant to indicate +parameter changes, the precede it by "{}". + +You can assign your own name to a node by setting the +\begin{Ex} + \Par{name=<name>} +\end{Ex} +parameter at the beginning of the entry, as described above. You can still +refer to the node by "{<row>,<col>}", but here are a few reasons for giving +your own name to a node: +\begin{itemize} + \item The name may be easier to keep track of; + \item Unlike the "{<row>,<col>}" names, the names you give remain valid + even when you add extra rows or columns to your matrix. + \item The names remain valid even when you start a new \n\psmatrix{} that + reuses the "{<row>,<col>}" names. +\end{itemize} + + +Here a few more things you should know: +\begin{itemize} + \item The baselines of the nodes pass through the centers of the + nodes. \n\psmatrix{} achieves this by setting the +\begin{Ex} + \Par{nodealign=true/false} +\end{Ex} +parameter to "true". You can also set this parameter outside of \n\psmatrix{} +when you want this kind of alignment. + + \item You can left or right-justify the nodes by setting the +\begin{Ex} + \Par{mcol=l/r/c} +\end{Ex} +parameter. "l", "r" and "c" stand for "left", "right" and "center", +respectively. + + \item The space between rows and columns is set by the +\begin{Ex} + \Par{rowsep=dim} + \Par{colsep=dim} +\end{Ex} +parameters. + + \item If you want all the nodes to have a fixed width, set +\begin{Ex} + \Par{mnodesize=dim} +\end{Ex} +to a positive value. + + \item If \n\psmatrix{} is used in math mode, all the entries are set in math + mode, but you can switch a single entry out of math mode by starting and + ending the entry with "$". + + \item The radius of the "c" \p{mnode} (corresponding to \n\cnode) is set by +the \p{radius} parameter. + + \item Like in \LaTeX, you can end a row with "\\[<dim>]" to insert an extra + space <dim> between rows. + + \item The command "\psrowhookii" is executed, if defined, at the beginning of + every entry in row "ii" (row 2), and the command "\pscolhookv" is executed at + athe beginning of every entry in column "v" (etc.). You can use these hooks, + for example, to change the spacing between two columns, or to use a special + \p{mnode} for all the entries in a particular row. + + \item An entry can itself be a node. You might do this if you want an entry + to have two shapes. + + \item If you want an entry to stretch across several (<int>) columns, use the + \Mac \psspan{int} + \emph{at the end of the entry}. This is like Plain \TeX's \n\multispan, or + \LaTeX's \n\multicolumn, but the template for the current column (the first + column that is spanned) is still used. If you want wipe out the template as + well, use "\multispan{<int>}" \emph{at the beginning of the entry} instead. + If you just want to wipe out the template, use "\omit" before the entry. + + \item \n\psmatrix{} can be nested, but then all node connections and other + references to the nodes in the "{<row>,<col>}" form for the nested matrix + \emph{must go inside} the \n\psmatrix. This is how PSTricks decides which + matrix you are referring to. It is still neatest to put all the node + connections towards the end; just be sure to put them before \n\endpsmatrix. + Be careful also not to refer to a node until it actually appears. The whole + matrix can itself go inside a node, and node connections can be made as + usual. This is not the same as connecting nodes from two different + \n\psmatrix's. To do this, you must give the nodes names and refer to them + by these names. + +\end{itemize} + +\section{Obsolete put commands} + +This is old documentation, but these commands will continue to be supported. + +There is also an obsolete command \n\Lput\MainIndex\Lput{} for putting labels +next to node connections. The syntax is +\begin{LVerb*} + \Lput{<labelsep>}[<refpoint>]{<rotation>}(<pos>){<stuff>} +\end{LVerb*} +It is a combination of \n\Rput{} and \n\lput, equivalent to +\begin{LVerb*} + \lput(<pos>){\Rput{<labelsep>}[<refpoint>]{<rotation>}(0,0){<stuff>}} +\end{LVerb*} +\n\Mput\MainIndex\Mput{} is a short version of \n\Lput{} with no +"{<rotation>}" or "(<pos>)" argument. \n\Lput{} and \n\Mput{} remain part of +PSTricks only for backwards compatibility. + +Here are the node label commands: +\begin{description} + +\mitem \lput`*[refpoint]{rotation}'(pos){stuff} + +The "l" stands for ``label''. Here is an example illustrating the use of the +optional star and ":<angle>" with \n\lput, as well as the use of the +\p{offset} parameter with \n\pcline: +\begin{MEx}(4,2.3) + \pspolygon(0,0)(4,2)(4,0) + \pcline[offset=12pt]{|-|}(0,0)(4,2) + \lput*{:U}{Length} +\end{MEx} +(Remember that with the "put" commands, you can omit the coordinate if you +include the angle of rotation. You are likely to use this feature with the +node label commands.) + +With \n\lput{} and \n\rput, you have a lot of control over the position of the +label. E.g., +\begin{MEx}(4,2) + \pcline(0,0)(4,2) + \lput{:U}{\rput[r]{N}(0,.4){label}} +\end{MEx} +puts the label upright on the page, with right side located .4 centimeters +``above'' the position ".5" of the node connection (above if the node +connection points to the right). However, the \n\aput{} and \n\bput{} commands +described below handle the most common cases without \n\rput.\footnote{% +There is also an obsolete command \n\Lput\MainIndex\Lput{} for putting labels +next to node connections. The syntax is +\begin{LVerb*} + \Lput{<labelsep>}[<refpoint>]{<rotation>}(<pos>){<stuff>} +\end{LVerb*} +It is a combination of \n\Rput{} and \n\lput, equivalent to +\begin{LVerb*} + \lput(<pos>){\Rput{<labelsep>}[<refpoint>]{<rotation>}(0,0){<stuff>}} +\end{LVerb*} +\n\Mput\MainIndex\Mput{} is a short version of \n\Lput{} with no +"{<rotation>}" or "(<pos>)" argument. \n\Lput{} and \n\Mput{} remain part of +PSTricks only for backwards compatibility.} + +\mitem \aput`*[labelsep]{angle}'(pos){stuff} + + <stuff> is positioned distance \n\pslabelsep{} \emph{above} the node +connection, given the convention that node connections point to the right. +"\aput" is a node-connection variant of \n\uput. For example: +\begin{MEx}(4,2) + \pspolygon(0,0)(4,2)(4,0) + \pcline[linestyle=none](0,0)(4,2) + \aput{:U}{Hypotenuse} +\end{MEx} + +\mitem \bput`*[labelsep]{angle}'(pos){stuff} + + This is like \n\aput, but <stuff> is positioned \emph{below} the node +connection. + +\end{description} + + It is fairly common to want to use the default position and rotation with +these node connections, but you have to include at least one of these +arguments. Therefore, PSTricks contains some variants: +\begin{Ex} + \object \mput`*[refpoint]'{stuff} + \object \Aput`*[labelsep]'{stuff} + \object \Bput`*[labelsep]'{stuff} +\end{Ex} +of \n\lput, \n\aput{} and \n\bput, respectively, that have no angle or +positioning argument. For example: +\begin{MEx}(4,2) + \cnode*(0,0){3pt}{A} + \cnode*(4,2){3pt}{B} + \ncline[nodesep=3pt]{A}{B} + \mput*{1} +\end{MEx} +Here is another: +\begin{MEx}(4,2) + \pcline{<->}(0,0)(4,2) + \Aput{Label} +\end{MEx} + +\endinput + +%% END psd-node.tex diff --git a/Master/texmf-dist/doc/generic/pstricks/psd-para.tex b/Master/texmf-dist/doc/generic/pstricks/psd-para.tex new file mode 100644 index 00000000000..d644733a5dc --- /dev/null +++ b/Master/texmf-dist/doc/generic/pstricks/psd-para.tex @@ -0,0 +1,345 @@ +%% BEGIN psd-para.tex + +\part{More graphics parameters} + +The graphics parameters described in this part are common to all or most of +the graphics objects. + +\Section{Coordinate systems} + +The following manipulations of the coordinate system apply only to pure +graphics objects. + +A simple way to move the origin of the coordinate system to \c{} is with the +\begin{Ex} + \Par{origin=\{coor\}}({0pt,0pt}) +\end{Ex} +This is the one time that coordinates \emph{must} be enclosed in curly brackets +"{}" rather than parentheses "()". + +A simple way to switch swap the axes is with the +\begin{Ex} + \Par{swapaxes=true} +\end{Ex} +parameter. E.g., you might change your mind on the orientation of a plot after +generating the data. + +\Section{Line styles\label{S-linestyles}} + +The following graphics parameters (in addition to \p{linewidth} and +\p{linecolor}) determine how the lines are drawn, whether they be open or +closed curves. +\begin{description}\raggedright + +\pitem[linestyle=style] + Valid styles are "none", "solid", "dashed" and "dotted". + +\pitem[dash=dim1 dim2] + The <black-white> dash pattern for the "dashed" line style. For example: +\begin{MEx}(4,2) + \psellipse[linestyle=dashed,dash=3pt 2pt](2,1)(2,1) +\end{MEx} + +\pitem[dotsep=dim] + The distance between dots in the "dotted" line style. For example +\begin{MEx}(4,1) + \psline[linestyle=dotted,dotsep=2pt]{|->>}(4,1) +\end{MEx} + +\pitem[border=dim] + A positive value draws a border of width <dim> and color \p{bordercolor} on +each side of the curve. This is useful for giving the impression that one line +passes on top of another. The value is saved in the dimension register +\n\psborder. + +\pitem[bordercolor=color] + See \p{border} above. + + For example: +\begin{MEx}(4,3) + \psline(0,0)(1.8,3) + \psline[border=2pt]{*->}(0,3)(1.8,0) + \psframe*[linecolor=gray](2,0)(4,3) + \psline[linecolor=white,linewidth=1.5pt]{<->}(2.2,0)(3.8,3) + \psellipse[linecolor=white,linewidth=1.5pt, + bordercolor=gray,border=2pt](3,1.5)(.7,1.4) +\end{MEx} + +\pitem[doubleline=true/false] + When "true", a double line is drawn, separated by a space that is +\p{doublesep} wide and of color \p{doublecolor}. This doesn't work as expected +with the "dashed" \p{linestyle}, and some arrows look funny as well. + +\pitem[doublesep=dim] + See \p{doubleline}, above. + +\pitem[doublecolor=color] + See \p{doubleline}, above. + +Here is an example of double lines: +\begin{MEx}(4,1) + \psline[doubleline=true,linearc=.5, + doublesep=1.5pt]{->}(0,0)(3,1)(4,0) +\end{MEx} + +\pitem[shadow=true/false] + When "true", a shadow is drawn, at a distance \p{shadowsize} from the +original curve, in the direction \p{shadowangle}, and of color +\p{shadowcolor}. + +\pitem[shadowsize=dim] + See \p{shadow}, above. + +\pitem[shadowangle=angle] + See \p{shadow}, above. + +\pitem[shadowcolor=color] + See \p{shadow}, above. + +Here is an example of the \p{shadow} feature, which should look familiar: +\begin{MEx}[-1,-.5](1,.7) + \pspolygon[linearc=2pt,shadow=true,shadowangle=45, + xunit=1.1](-1,-.55)(-1,.5)(-.8,.5)(-.8,.65) + (-.2,.65)(-.2,.5)(1,.5)(1,-.55) +\end{MEx} +\end{description} + +Here is another graphics parameter that is related to lines but that applies +only to the closed graphics objects \n\psframe, \n\pscircle, \n\psellipse{} and +\n\pswedge: +\begin{Ex} + \Par{dimen=outer/inner/middle} +\end{Ex} +It determines whether the dimensions refer to the inside, outside or middle of +the boundary. The difference is noticeable when the linewidth is large: +\begin{MEx*}(4,3) + \psset{linewidth=.25cm} + \psframe[dimen=inner](0,0)(2,1) + \psframe[dimen=middle](0,2)(2,3) + \psframe[dimen=outer](3,0)(4,3) +\end{MEx*} +With "\pswedge", this only affects the radius; the origin always lies in the +middle the boundary. The right setting of this parameter depends on how you +want to align other objects. + + +\Section{Fill styles\label{S-fillstyles}} + +The next group of graphics parameters determine how closed regions are filled. +Even open curves can be filled; this does not affect how the curve is painted. +\begin{description}\raggedright + +\pitem[fillstyle=style] + Valid styles are + \begin{quote}\raggedright + "none", "solid", "vlines", "vlines*", "hlines", "hlines*", "crosshatch" and +"crosshatch*". + \end{quote} + "vlines", "hlines" and "crosshatch" draw a pattern of lines, according to +the four parameters list below that are prefixed with "hatch". The "*" +versions also fill the background, as in the "solid" style. + +\pitem[fillcolor=color] + The background color in the "solid", "vlines*", "hlines*" and "crosshatch*" +styles. + +\pitem[hatchwidth=dim] + Width of lines. + +\pitem[hatchsep=dim] + Width of space between the lines. + +\pitem[hatchcolor=color] + Color of lines. Saved in \n\pshatchcolor. + +\pitem[hatchangle=rot] + Rotation of the lines, in degrees. For example, if \p{hatchangle} is set to +"45", the "vlines" style draws lines that run NW-SE, and the "hlines" style +draws lines that run "SW-NE", and the "crosshatch" style draws both. +\end{description} + +Here is an example of the "vlines" and related fill styles:\footnote{% +PSTricks adjusts the lines relative to the resolution so that they all have +the same width and the same intervening space. Otherwise, the checkered +pattern in this example would be noticeably uneven, even on 300 dpi devices. +This adjustment is resolution dependent, and may involve adjustments to the +\p{hatchangle} when this is not initially a multiple of 45 degrees.} +\begin{MEx}(4,3) + \pspolygon[fillstyle=vlines](0,0)(0,3)(4,0) + \pspolygon[fillstyle=hlines](0,0)(4,3)(4,0) + \pspolygon[fillstyle=crosshatch*,fillcolor=black, + hatchcolor=white,hatchwidth=1.2pt,hatchsep=1.8pt, + hatchangle=0](0,3)(2,1.5)(4,3) +\end{MEx} + +Each of the pure graphics objects (except those beginning with "q") has a +starred version that produces a solid object of color \p{linecolor}. (It +automatically sets \p{linewidth} to zero, \p{fillcolor} to \p{linecolor}, +\p{fillstyle} to "solid", and \p{linestyle} to "none".) + + +\Section{Arrowheads and such\label{S-arrows}} + + Lines and other open curves can be terminated with various arrowheads, +t-bars or circles. The +\begin{Ex} + \Par{arrows=style} +\end{Ex} +parameter determines what you get. It can have the following values, which are +pretty intuitive:\footnote{This is \TeX's version of WYSIWYG.}% +\newbox\arrowtable +\setbox\arrowtable=\hbox{% + \def\myline#1{\psline{#1}(0,1ex)(1.3,1ex)}% + \catcode`\<=12 + \begin{tabular}{cll}% + \emph{Value} & \hbox to 1.3cm{\emph{Example}}\hss & \emph{Name} \\[2pt] + "-" & \myline{-} & None\\ + "<->" & \myline{<->} & Arrowheads.\\ + ">-<" & \myline{>-<} & Reverse arrowheads.\\ + "<<->>" & \myline{<<->>} & Double arrowheads.\\ + ">>-<<" & \myline{>>-<<} & Double reverse arrowheads.\\ + "|-|" & \myline{|-|} & T-bars, flush to endpoints.\\ + "|*-|*" & \myline{|*-|*} & T-bars, centered on endpoints.\\ + "|<->|" & \myline{|<->|} & T-bars and arrowheads.\\ + "|<*->|*" & \myline{|<*->|*} & T-bars and arrowheads, flush.\\ + "[-]" & \myline{[-]} & Square brackets.\\ + "(-)" & \myline{(-)} & Rounded brackets.\\ + "o-o" & \myline{o-o} & Circles, centered on endpoints.\\ + "*-*" & \myline{*-*} & Disks, centered on endpoints.\\ + "oo-oo" & \myline{oo-oo} & Circles, flush to endpoints.\\ + "**-**" & \myline{**-**} & Disks, flush to endpoints.\\ + "c-c" & \myline{c-c} & Extended, rounded ends.\\ + "cc-cc" & \myline{cc-cc} & Flush round ends.\\ + "C-C" & \myline{C-C} & Extended, square ends. + \end{tabular}}% +\addtoquickref{center}{% + {\large\textbf{Arrows}}\par + \leavevmode\box\arrowtable} +\begin{center} + \leavevmode\copy\arrowtable +\end{center} +You can also mix and match. E.g., "->", "*-)" and "[->" are all valid values +of the \p{arrows} parameter. + +Well, perhaps the "c", "cc" and "C" arrows are not so obvious. "c" and "C" +correspond to setting PostScript's "linecap" to 1 and 2, respectively. "cc" is +like "c", but adjusted so that the line flush to the endpoint. These arrows +styles are noticeable when the \p{linewidth} is thick: +\begin{MEx}[-.25,-.25](3.25,2.25) + \psline[linewidth=.5cm](0,0)(0,2) + \psline[linewidth=.5cm]{c-c}(1,0)(1,2) + \psline[linewidth=.5cm]{cc-cc}(2,0)(2,2) + \psline[linewidth=.5cm]{C-C}(3,0)(3,2) + "\rput[t](0,-.3){\texttt{-}} + "\rput[t](1,-.3){\texttt{c-c}} + "\rput[t](2,-.3){\texttt{cc-cc}} + "\rput[t](3,-.3){\texttt{C-C}} +\end{MEx} + +Almost all the open curves let you include the \p{arrows} parameters as an +optional argument, enclosed in curly braces and before any other arguments +(except the optional parameters argument). E.g., instead of +\begin{LVerb} + \psline[arrows=<-,linestyle=dotted](3,4) +\end{LVerb} +you can write +\begin{LVerb} + \psline[linestyle=dotted]{<-}(3,4) +\end{LVerb} +The exceptions are a few streamlined macros that do not support the use of +arrows (these all begin with "q"). + +The size of these line terminators is controlled by the following parameters. +In the description of the parameters, the width always refers to the dimension +perpendicular to the line, and length refers to a dimension in the direction +of the line. +\begin{description} + +\pitem[arrowsize=dim `num'] + The width of arrowheads is <dim> plus <num> times \p{linewidth} +(if the optional `num' is inclued). See the diagram below. + +\pitem[arrowlength=num] + Length of arrowheads, as a fraction of the width, as shown below. + +\pitem[arrowinset=num] + Size of inset for arrowheads, as a fraction of the length, as shown below. + +\begin{center}\leavevmode +\hbox to \linewidth{% + \psset{unit=.5cm} + \pspicture[shift=3cm](-3.6,-1.3)(3.4,4.8) + \pspolygon*(-2,0)(0,4)(2,0)(0,1) + \psset{arrows=|-|} + \psline(-2.5,0)(-2.5,4)\rput(-2.7,2){\psframebox*{\emph{length}}} + \psline(-2,-.5)(2,-.5)\rput(0,-.5){\psframebox*{\emph{width}}} + \psline(2.5,0)(2.5,1)\rput[l](2.8,.5){\emph{inset}} + \endpspicture + \hfill + \begin{tabular}{rcl} + \texttt{arrowsize} & = & <dim num>\\ + \emph{width} & = & <num> x \p{linewidth} + <dim1>\\ + \emph{length} & = & \p{arrowlength} x \emph{width}\\ + \emph{inset} & = & \p{arrowinset} x \emph{height} + \end{tabular}} +\end{center} + +\pitem[tbarsize=dim `num'] + The width of a t-bar, square bracket or rounded bracket is <dim> plus <num> +times \p{linewidth} (if the optional `num' is included). +\p{linewidth}, plus <dim>. + +\pitem[bracketlength=num] + The height of a square bracket is <num> times its width. + +\pitem[rbracketlength=num] + The height of a round bracket is <num> times its width. + +\pitem[arrowscale=arrowscale=num1 <num2>] + Imagine that arrows and such point down. This scales the width of the arrows +by <num1> and the length (height) by <num2>. If you only include one number, +the arrows are scaled the same in both directions. Changing \p{arrowscale} can +give you special effects not possible by changing the parameters described +above. E.g., you can change the width of lines used to draw brackets. + +\end{description} + +The size of dots is controlled by the \p{dotsize} parameter. + + +\Section{Custom styles} + +You can define customized versions of any macro that has parameter changes as +an optional first argument using the \n\newpsobject{} command: + \Mac \newpsobject{name}{object}{par1=value1`,\ldots'} +as in +\begin{LVerb} + \newpsobject{myline}{psline}{linecolor=green,linestyle=dotted} + \newpsobject{mygrid}{psgrid}{subgriddiv=1,griddots=10, + gridlabels=7pt} +\end{LVerb} +The first argument is the name of the new command you want to define. The +second argument is the name of the graphics object. Note that both of these +arguments are given without the backslash. The third argument is the special +parameter values that you want to set. + +With the above examples, the commands "\myline" and "\mygrid" work just like +the graphics object \n\psline{} it is based on, and you can even reset the +parameters that you set when defining "\myline", as in: +\begin{LVerb} + \myline[linecolor=gray,dotsep=2pt](5,6) +\end{LVerb} + +Another way to define custom graphics parameter configurations is with the + \Mac \newpsstyle{name}{par1=value1`,\ldots'} +command. You can then set the \p{style} graphics parameter to <name>, rather +than setting the parameters given in the second argument of \n\newpsstyle. For +example, +\begin{LVerb} + \newpsstyle{mystyle}{linecolor=green,linestyle=dotted} + \psline[style=mystyle](5,6) +\end{LVerb} + +\endinput + +%% END psd-para.tex diff --git a/Master/texmf-dist/doc/generic/pstricks/psd-pict.tex b/Master/texmf-dist/doc/generic/pstricks/psd-pict.tex new file mode 100644 index 00000000000..59fa301d2dd --- /dev/null +++ b/Master/texmf-dist/doc/generic/pstricks/psd-pict.tex @@ -0,0 +1,500 @@ +%% BEGIN psd-pict.tex + +\part{Picture Tools\label{P-pictures}} + +\Section{Pictures\label{S-pspic}} + +The graphics objects and \n\rput{} and its variants do not change \TeX's +current point (i.e., they create a 0-dimensional box). If you string several +of these together (and any other 0-dimensional objects), they share the same +coordinate system, and so you can create a picture. For this reason, these +macros are called \emph{picture objects}. + +If you create a picture this way, you will probably want to give the whole +picture a certain size. You can do this by putting the picture objects in a +\p{pspicture} environment, as in: +\begin{Ex} + \object \pspicture`*[baseline](\x0,\y0)'\c1 + < picture objects> + \object \endpspicture +\end{Ex} +The picture objects are put in a box whose lower left-hand corner is at \c0 +(by default, "(0,0)") and whose upper right-hand corner is at \c1. + +By default, the baseline is set at the bottom of the box, but the optional +argument "[<baseline>]" sets the baseline fraction <baseline> from the bottom. +Thus, <baseline> is a number, generally but not necessarily between 0 and 1. +If you include this argument but leave it empty (\texttt{[\kern 1pt]}), then +the baseline passes through the origin. + +Normally, the picture objects can extend outside the boundaries of the box. +However, if you include the "*", anything outside the boundaries is clipped. + +Besides picture objects, you can put anything in a \n\pspicture{} that does +not take up space. E.g., you can put in font declarations and use \n\psset, +and you can put in braces for grouping. PSTricks will alert you if you include +something that does take up space.\footnote{% +When PSTricks picture objects are included in a \n\pspicture{} environment, +they gobble up any spaces that follow, and any preceding spaces as well, +making it less likely that extraneous space gets inserted. (PSTricks objects +always ignore spaces that follow. If you also want them to try to neutralize +preceding space when used outside the \n\pspicture{} environment (e.g., in a +\LaTeX{} "picture" environment), then use the command \Main\KillGlue. The +command \Main\DontKillGlue{} turns this behavior back off.)} + +\LaTeX{} users can type +\begin{Ex} + "\begin{pspicture}" \ldots\ "\end{pspicture}" +\end{Ex} +You can use PSTricks picture objects in a \LaTeX{} "picture" environment, and +you can use \LaTeX{} picture objects in a PSTricks {\UsageFont pspicture} +environment. However, the {\UsageFont pspicture} environment makes \LaTeX's +"picture" environment obsolete, and has a few small advantages over the +latter. Note that the arguments of the {\UsageFont pspicture} environment work +differently from the arguments of \LaTeX's "picture" environment (i.e., the +right way versus the wrong way). + + +\begin{drivers} The clipping option ("*") uses \n\pstVerb{} and +\n\pstverbscale. +\end{drivers} + + +\Section{Placing and rotating whatever\label{S-rput}} + +PSTricks contains several commands for positioning and rotating an HR-mode +argument. All of these commands end in "put", and bear some similarity to +\LaTeX's "\put" command, but with additional capabilities. Like \LaTeX's +"\put" and unlike the box rotation macros described in Section +\ref{S-rotation}, these commands do not take up any space. They can be used +inside and outside \n\pspicture{} environments. + +Most of the PSTricks "put" commands are of the form: +\begin{Ex} + \Backslash <put>*<arg>"{<rotation>}(<coor>){<stuff>}" +\end{Ex} +With the optional "*" argument, <stuff> is first put in a +\begin{LVerb*} + \psframebox*[boxsep=false]{<stuff>} +\end{LVerb*} +thereby blotting out whatever is behind <stuff>. This is useful for +positioning text on top of something else. + +<arg> refers to other arguments that vary from one "put" command to another, +The optional <rotation> is the angle by which <stuff> should be rotated; this +arguments works pretty much the same for all "put" commands and is described +further below. The "(<coor>)" argument is the coordinate for positioning +<stuff>, but what this really means is different for each "put" command. The +"(<coor>)" argument is shown to be obligatory, but you can actually omit it if +you include the <rotation> argument. + +The <rotation> argument should be an angle, as described in Section +\ref{S-coor}, but the angle can be preceded by an "*". This causes all the +rotations (except the box rotations described in Section \ref{S-rotation}) +within which the \n\rput{} command is be nested to be undone before setting the +angle of rotation. This is mainly useful for getting a piece of text right +side up when it is nested inside rotations. For example, +\begin{MEx}[-1,-.5](2,2) + \rput{34}{% + \psframe(-1,0)(2,1) + \rput[br]{*0}(2,1){\emph{stuff}}} +\end{MEx} + +There are also some letter abbreviations for the command angles. These +indicate which way is up: +\begin{trivlist}\item[] + \leavevmode + \hbox to \hsize{\hfill + \begin{tabular}{clr} + \emph{Letter} & \emph{Short for} & \emph{Equiv.\ to}\\ + "U" & Up & 0\\ + "L" & Left & 90\\ + "D" & Down & 180\\ + "R" & Right & 270\\ + \end{tabular} + \hfill + \begin{tabular}{clr} + \emph{Letter} & \emph{Short for} & \emph{Equiv.\ to}\\ + "N" & North & *0\\ + "W" & West & *90\\ + "S" & South & *180\\ + "E" & East & *270 + \end{tabular}\hfill} +\end{trivlist} + + +This section describes just a two of the PSTricks "put" commands. The most +basic one command is + \Mac \rput`*[refpoint]{rotation}'\c~{stuff} +<refpoint> determines the reference point of <stuff>, and this reference point +is translated to \c{}. + +By default, the reference point is the center of the box. This can be changed +by including one or two of the following in the optional <refpoint> argument: +\begin{center} +\begin{tabular}{rlcrl} +\multicolumn{2}{l}\emph{Horizontal} & & \multicolumn{2}{l}\emph{Vertical}\\ +"l" & Left & & "t" & Top\\ +"r" & Right & & "b" & Bottom\\ + & & & "B" & Baseline +\end{tabular} +\end{center} +Visually, here is where the reference point is set of the various combinations +(the dashed line is the baseline): +\begin{center} +\begin{pspicture}(-2.4,-.9)(2.4,1.9) + \ttfamily\bfseries + \psframe(-2,-.5)(2,1.5) + \psline[linestyle=dashed](-2,0)(2,0) + \uput[u](0,1.5){t} + \uput[d](0,-.5){b} + \rput*(0,0){B} + \uput[l](-2,.5){l} + \uput[l](-2,0){Bl} + \uput[dl](-2,-.5){bl} + \uput[ul](-2,1.5){tl} + \uput[r](2,.5){r} + \uput[r](2,0){Br} + \uput[dr](2,-.5){br} + \uput[ur](2,1.5){tr} +\end{pspicture} +\end{center} + +There are numerous examples of \n\rput{} in this documentation, but for now +here is a simple one: +\begin{example**} + \rput[b]{90}(-1,0){Here is a marginal note.} +\end{example**} + +One common use of a macro such as \n\rput{} is to put labels on things. +PSTricks has a variant of \n\rput{} that is especially designed for labels: + \Mac \uput`*{labelsep}'[refangle]`{rotation}\c~'{stuff} +This places <stuff> distance <labelsep> from \c{}, in the direction +<refangle>. + +The default value of <labelsep> is the dimension register + \Mac \pslabelsep +You can also change this be setting the +\begin{Ex} + \Par{labelsep=dim} +\end{Ex} +parameter (but remember that \n\uput{} does have an optional argument for +setting parameters). + +Here is a simple example: +\begin{MEx}(3,2) + \qdisk(1,1){1pt} + \uput[45](1,1){(1,1)} +\end{MEx} + +Here is a more interesting example where \n\uput{} is used to make a pie +chart: +\begin{example} + \psset{unit=1.2cm} + \pspicture(-2.2,-2.2)(2.2,2.2) + \pswedge[fillstyle=solid,fillcolor=gray]{2}{0}{70} + \pswedge[fillstyle=solid,fillcolor=lightgray]{2}{70}{200} + \pswedge[fillstyle=solid,fillcolor=darkgray]{2}{200}{360} + \SpecialCoor + \psset{framesep=1.5pt} + \rput(1.2;35){\psframebox*{\small\$9.0M}} + \uput{2.2}[45](0,0){Oreos} + \rput(1.2;135){\psframebox*{\small\$16.7M}} + \uput{2.2}[135](0,0){Heath} + \rput(1.2;280){\psframebox*{\small\$23.1M}} + \uput{2.2}[280](0,0){M\&M} + \endpspicture +\end{example} + +You can use the following abbreviations for <refangle>, which indicate the +direction the angle points:% +\footnote{Using the abbreviations when applicable is more efficient.}% +\footnote{% +There is an obsolete command \n\Rput\MainIndex{\Rput}{} that has the same +syntax as \n\uput{} and that works almost the same way, except the <refangle> +argument has the syntax of \n\rput's <refpoint> argument, and it gives the +point in <stuff> that should be aligned with \c{}. E.g., +\begin{Ex} + "\qdisk(4,0){2pt}"\qdisk(4,0){2pt}\Rput[tl](4,0){$(x,y)$}\\ + "\Rput[tl](4,0){$(x,y)$}" +\end{Ex} +Here is the equivalence between \n\uput's <refangle> abbreviations and +\n\Rput's <refpoint> abbreviations: +\begin{center} + \ttfamily + \begin{tabular}{rcccccccc} + \n\uput & r & u & l & d & ur & ul & dr & dl \\ + \n\Rput & l & b & r & t & bl & br & tr & rl \\ + \end{tabular} +\end{center} +Some people prefer \n\Rput's convention for specifying the position of <stuff> +over \n\uput's.}% +\begin{trivlist}\item[] + \leavevmode + \hbox to \hsize{\hfill + \begin{tabular}{clr} + \emph{Letter} & \emph{Short for} & \emph{Equiv.\ to}\\ + "r" & right & 0\\ + "u" & up & 90\\ + "l" & left & 180\\ + "d" & down & 270\\ + \end{tabular} + \hfill + \begin{tabular}{clr} + \emph{Letter} & \emph{Short for} & \emph{Equiv.\ to}\\ + "ur" & up-right & 45\\ + "ul" & up-left & 135\\ + "dl" & down-left & 225\\ + "dr" & down-right & 315 + \end{tabular}\hfill} +\end{trivlist} +The first example could thus have been written: +\begin{MEx}(3,2) + \qdisk(1,1){1pt} + \uput[ur](1,1){(1,1)} +\end{MEx} + +\begin{drivers} The rotation macros use \n\pstVerb{} and \n\pstrotate. +\end{drivers} + + +\Section{Repetition\label{S-loops}} + +The macro + \Mac \multirput`*[refpoint]{angle}\c0'\c1{int}{stuff} +is a variant of \n\rput{} that puts down <int> copies, starting at \c0 and +advancing by \c1 each time. \c0 and \c1 are always interpreted as Cartesian +coordinates. For example: +\begin{MEx}(4,1.3) + \multirput(.5,0)(.3,.1){12}{*} +\end{MEx} + +If you want copies of pure graphics, it is more efficient to use + \Mac \multips`{angle}\c0'\c1{int}{graphics} +<graphics> can be one or more of the pure graphics objects described in Part +\ref{P-graphics}, or \n\pscustom. Note that \n\multips{} has the same syntax as +\n\multirput, except that there is no <refpoint> argument (since the graphics +are zero dimensional anyway). Also, unlike \n\multirput, the coordinates can +be of any type. An "Overfull \hbox" warning indicates that the <graphics> +argument contains extraneous output or space. For example: +\begin{MEx}[0,-.25](4,.25) + \def\zigzag{\psline(0,0)(.5,1)(1.5,-1)(2,0)}% + \psset{unit=.25,linewidth=1.5pt} + \multips(0,0)(2,0){8}{\zigzag} +\end{MEx} + +PSTricks can heavily benefit of a much more general loop macro, called +\n\multido. +\File{multido} You must input the file "multido.tex" or "multido.sty". See the +documentation "multido.doc" for details. Here is a sample of what you can do: +\begin{example} + \begin{pspicture}(-3.4,-3.4)(3.4,3.4) + \newgray{mygray}{0} % Initialize `mygray' for benefit + \psset{fillstyle=solid,fillcolor=mygray} % of this line. + \SpecialCoor + \degrees[1.1] + \multido{\n=0.0+.1}{11}{% + \newgray{mygray}{\n} + \psset{fillcolor=mygray}% + \rput{\n}{\pswedge{3}{-.05}{.05}} + \uput{3.2}[\n](0,0){\small\n}} + \end{pspicture} +\end{example} + +All of these loop macros can be nested. + + +\Section{Axes\label{S-axes}} + +\File{pst-plot} +The axes command described in this section is defined in "pst-plot.tex" / +"pst-plot.sty", which you must input first. "pst-plot.tex", in turn, will +automatically input "multido.tex", which is used for putting the labels on the +axes. + +The macro for making axes is: + \Mac \psaxes`*[par]{arrows}\c0\c1'\c2 + +The coordinates must be Cartesian coordinates. They work the same way as with +\n\psgrid. That is, if we imagine that the axes are enclosed in a rectangle, +\c1 and \c2 are opposing corners of the rectangle. (I.e., the x-axis extends +from \x1 to \x2 and the y-axis extends from \y1 to \y2.) The axes intersect at +\c0. For example: +\begin{MEx*}(4,3) + \psaxes[linewidth=1.2pt,labels=none, + ticks=none]{<->}(2,1)(0,0)(4,3) + "\psset{nodesep=3pt} + "\pnode(4,3){B} + "\rput*[tr](4,2.3){\rnode{A}{\c2}} + "\ncline{->}{A}{B} + "\pnode(2,1){B} + "\rput*[br](1.3,1.7){\rnode{A}{\c0}} + "\ncline{->}{A}{B} + "\pnode(0,0){B} + "\rput*[bl](0,-.9){\rnode{A}{\c1}} + "\ncline{->}{A}{B} +\end{MEx*} + +If \c0 is omitted, then the origin is \c1. If both \c0 and \c1 are omitted, +"(0,0)" is used as the default. For example, when the axes enclose a single +orthont, only \c2 is needed: +\begingroup +\psset{unit=.8} +\begin{MEx}[-.5,-.5](4,2) + "\small + \psaxes{->}(4,2) +\end{MEx} +\endgroup + +Labels (numbers) are put next to the axes, on the same side as \x1 and \y1. +Thus, if we enclose a different orthont, the numbers end up in the right +place: +\begingroup +\psset{unit=.8} +\begin{MEx}[-.5,-2](4,.5) + "\small + \psaxes{->}(4,-2) +\end{MEx} +\endgroup + +Also, if you set the \p{arrows} parameter, the first arrow is used for the +tips at <x1> and <y1>, while the second arrow is used for the tips at <x2> and +<y2>. Thus, in the preceding examples, the arrowheads ended up in the right +place too.\footnote{% +Including a first arrow in these examples would have had no effect because +arrows are never drawn at the origin.} + +When the axes don't just enclose an orthont, that is, when the origin is not +at a corner, there is some discretion as to where the numbers should go. The +rules for positioning the numbers and arrows described above still apply, and +so you can position the numbers as you please by switching <y1> and <y2>, or +<x1> and <x2>. For example, compare +\begingroup +\psset{unit=.8} +\begin{MEx}[-1.5,-.5](2.5,2.5) + "\small + \psaxes{<->}(0,0)(-2.5,0)(2.5,2.5) +\end{MEx} +\endgroup +with what we get when <x1> and <x2> are switched: +\begingroup +\psset{unit=.8} +\begin{MEx}[-1.5,-.5](2.5,2.5) + "\small + \psaxes{<->}(0,0)(2.5,0)(-2.5,2.5) +\end{MEx} +\endgroup + +\n\psaxes{} puts the ticks and numbers on the axes at regular intervals, using +the following parameters: +\newbox\axesbox +\MainParIndex{Ox} +\MainParIndex{Dx} +\MainParIndex{dx} +\MainParIndex{Oy} +\MainParIndex{Dy} +\MainParIndex{dy} +\setbox\axesbox=\hbox{% + \large + \begin{tabular}{|c|c|c|l|} + \hline + \emph{Horitontal} & \emph{Vertical} & \emph{Dflt} & + \emph{Description}\\[2pt] + \p{Ox=num} & \p{Oy=num} & "0" & Label at origin.\\ + \p{Dx=num} & \p{Dy=num} & "1" & Label increment.\\ + \p{dx=dim} & \p{dy=dim} & "0pt" & Dist btwn labels.\\ + \hline + \end{tabular}} +\addtoquickref{center}{% + {\large\textbf{Axes label parameters}}\par + \leavevmode\box\axesbox} +\begin{center} +\leavevmode\copy\axesbox +\end{center} +When \p{dx} is 0, "Dx\psxunit" is used instead, and similarly for \p{dy}. +Hence, the default values of "0pt" for \p{dx} and \p{dy} are not as peculiar +as they seem. + +You have to be very careful when setting \p{Ox}, \p{Dx}, \p{Oy} and \p{Dy} to +non-integer values. "multido.tex" increments the labels using rudimentary +fixed-point arithmetic, and it will come up with the wrong answer unless +\p{Ox} and \p{Dx}, or \p{Oy} and \p{Dy}, have the same number of digits to the +right of the decimal. The only exception is that \p{Ox} or \p{Oy} can always +be an integer, even if \p{Dx} or \p{Dy} is not. (The converse does not work, +however.)% +\footnote{For example, \p{Ox=1.0} and \p{Dx=1.4} is okay, as is \p{Ox=1} and +\p{Dx=1.4}, but \p{Ox=1.4} and \p{Dx=1}, or \p{Ox=1.4} and \p{Dx=1.15}, is not +okay. If you get this wrong, PSTricks won't complain, but you won't get the +right labels either.} + +Note that \n\psaxes's first coordinate argument determines the physical +position of the origin, but it doesn't affect the label at the origin. E.g., +if the origin is at "(1,1)", the origin is still labeled "0" along each axis, +unless you explicitly change \p{Ox} and \p{Oy}. For example: +\begin{MEx}[-2,0](2,3) + \psaxes[Ox=-2](-2,0)(2,3) +\end{MEx} + +The ticks and labels use a few other parameters as well: +\begin{description} + +\pitem[labels=all/x/y/none] + To specify whether labels appear on both axes, the x-axis, the y-axis, or +neither. + +\pitem[showorigin=true/false] + If "true", then labels are placed at the origin, as long as the label +doesn't end up on one of the axes. If "false", the labels are never placed at +the origin. + +\pitem[ticks=all/x/y/none] + To specify whether ticks appear on both axes, the x-axis, the y-axis, or +neither. + +\pitem[tickstyle=full/top/bottom] + For example, if \p{tickstyle=top}, then the ticks are only on the side of +the axes away from the labels. If \p{tickstyle=bottom}, the ticks are on the +same side as the labels. "full" gives ticks extending on both sides. + +\pitem[ticksize=dim] + Ticks extend <dim> above and/or below the axis. + +\end{description} + +The distance between ticks and labels is \n\pslabelsep, which you can change +with the \p{labelsep} parameter. + +The labels are set in the current font (ome of the examples above were +preceded by "\small" so that the labels would be smaller). You can do fancy +things with the labels by redefining the commands: +\begin{Ex} + \object \pshlabel + \object \psvlabel +\end{Ex} +E.g., if you want change the font of the horizontal labels, but not the +vertical labels, try something like +\begin{LVerb} + \def\pshlabel#1{\small #1} +\end{LVerb} + +You can choose to have a frame instead of axes, or no axes at all (but you +still get the ticks and labels), with the parameter: +\begin{Ex} + \Par{axesstyle=axes/frame/none} +\end{Ex} +The usual \p{linestyle}, \p{fillstyle} and related paremeters apply. + +For example: +\begin{MEx}[-3,-.5](.5,3) + \psaxes[Dx=.5,dx=1,tickstyle=top,axesstyle=frame](-3,3) +\end{MEx} + +The \n\psaxes{} macro is pretty flexible, but PSTricks contains some other +tools for making axes from scratch. E.g., you can use \n\psline{} and +\n\psframe{} to draw axes and frames, respectively, \n\multido{} to generate +labels (see the documentation for "multido.tex"), and \n\multips{} to make +ticks. + +\endinput + +%% END psd-pict.tex 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 diff --git a/Master/texmf-dist/doc/generic/pstricks/psd-text.tex b/Master/texmf-dist/doc/generic/pstricks/psd-text.tex new file mode 100644 index 00000000000..ebc44abd8d7 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pstricks/psd-text.tex @@ -0,0 +1,260 @@ +%% BEGIN psd-text.tex + +\part{Text Tricks\label{P-text}} + +\Section{Framed boxes\label{S-framebox}} + +The macros for framing boxes take their argument, put it in an "\hbox", and +put a PostScript frame around it. (They are analogous to \LaTeX's "\fbox"). +Thus, they are composite objects rather than pure graphics objects. In +addition to the graphics parameters for \n\psframe, these macros use the +following parameters: +\begin{description} + +\pitem[framesep=dim] + Distance between each side of a frame and the enclosed box. + +\pitem[boxsep=true/false] + When "true", the box that is produced is the size of the frame or whatever +that is drawn around the object. When "false", the box that is produced is the +size of whatever is inside, and so the frame is ``transparent'' to \TeX. This +parameter only applies to \n\psframebox, \n\pscirclebox, and \n\psovalbox. + +\end{description} + +Here are the three box-framing macros: +\begin{description} + +\oitem \psframebox{stuff} + + A simple frame (perhaps with rounded corners) is drawn using \n\psframe. The +"*" option is of particular interest. It generates a solid frame whose color +is \p{fillcolor} (rather than \p{linecolor}, as with the closed graphics +objects). Recall that the default value of \p{fillcolor} is "white", and so +this has the effect of blotting out whatever is behind the box. For example, +\begin{MEx}(3,2) + \pspolygon[fillcolor=gray,fillstyle=crosshatch*](0,0)(3,0) + (3,2)(2,2) + \rput(2,1){\psframebox*[framearc=.3]{Label}} +\end{MEx} + +\oitem \psdblframebox{stuff} + + This draws a double frame. It is just a variant of \n\psframebox, defined by +\begin{LVerb} + \newpsobject{psdblframebox}{psframebox}{doublesep=\pslinewidth} +\end{LVerb} +For example, +\begin{example} + \psdblframebox[linewidth=1.5pt]{% + \parbox[c]{6cm}{\raggedright A double frame is drawn + with the gap between lines equal to \texttt{doublesep}}} +\end{example} + +\oitem \psshadowbox{stuff} + + This draws a single frame, with a shadow. +\begin{example**} + \psshadowbox{\textbf{Great Idea!!}} +\end{example**} +You can get the shadow with \n\psframebox{} just be setting the \p{shadowsize} +parameter, but with \n\psframebox{} the dimensions of the box won't reflect the +shadow (which may be what you want!). + +\oitem \pscirclebox{stuff} + + This draws a circle. With \p{boxsep=true}, the size of the box is close to +but may be larger than the size of the circle. For example: +\begin{example**} + \pscirclebox{\begin{tabular}{c} You are \\ here \end{tabular}} +\end{example**} +is distributed with +\oitem \cput<{angle}\c~>{stuff} + + This combines the functions of \n\pscirclebox{} and \n\rput. It is like +\begin{LVerb*} + \rput{<angle>}(x0,y0){\pscirclebox*[<par>]{<stuff>}} +\end{LVerb*} +but it is more efficient. Unlike the \n\rput{} command, there is no argument +for changing the reference point; it is always the center of the box. Instead, +there is an optional argument for changing graphics parameters. For example +\begin{MEx*}(2,1) + \cput[doubleline=true](1,.5){\large $K_1$} +\end{MEx*} + +\oitem \psovalbox{stuff} + + This draws an ellipse. If you want an oval with square sides and rounded +corners, then use \n\psframebox{} with a positive value for \p{rectarc} or +\p{linearc} (depending on whether \p{cornersize} is "relative" or "absolute"). +Here is an example that uses \p{boxsep=false}: +\begin{example**} + "\parbox{\marginparwidth}{ + At the introductory price of + \psovalbox[boxsep=false,linecolor=darkgray]{\$13.99}, + it pays to act now! + "} +\end{example**} + +\oitem \psdiabox{stuff} + + \n\psdiabox{} draws a diamond. +\begin{example**} + \psdiabox[shadow=true]{\Large\textbf{Happy?}} +\end{example**} + +\oitem \pstribox{stuff} + + \n\pstribox{} draws a triangle. +\begin{example**} + \pstribox[trimode=R,framesep=5pt]{\Large\textbf{Begin}} +\end{example**} + The triangle points in the direction: +\begin{Ex} + \Par{trimode=*U/D/R/L} +\end{Ex} +If you include the optional "*", then an equilateral triangle is drawn, +otherwise, you get the minimum-area isosceles triangle. +\begin{example**} + \pstribox[trimode=*U]{\Huge Begin} +\end{example**} + +\end{description} + +You can define variants of these box framing macros using the \n\newpsobject{} +command. + +If you want to control the final size of the frame, independently of the +material inside, nest <stuff> in something like \LaTeX's "\makebox" command. + + +\Section{Clipping\label{S-clipping}} + +The command + \Mac \clipbox`[dim]'{stuff} +puts <stuff> in an "\hbox" and then clips around the boundary of the box, at a +distance <dim> from the box (the default is "0pt"). + +The \n\pspicture{} environment also lets you clip the picture to the boundary. + +The command + \Mac \psclip{graphics} \ldots\ \Main\endpsclip +sets the clipping path to the path drawn by the graphics object(s), until the +\n\endpsclip{} command is reached. \n\psclip{} and \n\endpsclip{} must be +properly nested with respect to \TeX{} grouping. Only pure graphics (those +described in Part \ref{P-graphics} and \n\pscustom) are permitted. An +"Overfull \hbox" warning indicates that the <graphics> argument contains +extraneous output or space. Note that the +graphics objects otherwise act as usual, and the \n\psclip{} does not otherwise +affect the surrounded text. Here is an example: +\begin{example**} + \parbox{4.5cm}{% + \psclip{\psccurve[linestyle=none](-3,-2) + (0.3,-1.5)(2.3,-2)(4.3,-1.5)(6.3,-2)(8,-1.5)(8,2)(-3,2)} + "\def\baselinestretch{.85}\small + ``One of the best new plays I have seen all year: cool, poetic, + ironic \ldots'' proclaimed \emph{The Guardian} upon the London + premiere of this extraordinary play about a Czech director and + his actress wife, confronting exile in America.\vspace{-1cm} + \endpsclip} +\end{example**} + +If you don't want the outline to be painted, you need to include +\p{linestyle=none} in the parameter changes. You can actually include more +than one graphics object in the argument, in which case the clipping path is +set to the intersection of the paths. + +\n\psclip{} can be a useful tool in picture environments. For example, here it +is used to shade the region between two curves: +\begin{MEx}(4,4) + \psclip{% + \pscustom[linestyle=none]{% + \psplot{.5}{4}{2 x div} + \lineto(4,4)} + \pscustom[linestyle=none]{% + \psplot{0}{3}{3 x x mul 3 div sub} + \lineto(0,0)}} + \psframe*[linecolor=gray](0,0)(4,4) + \endpsclip + \psplot[linewidth=1.5pt]{.5}{4}{2 x div} + \psplot[linewidth=1.5pt]{0}{3}{3 x x mul 3 div sub} + \psaxes(4,4) +\end{MEx} + +\begin{drivers} + The clipping macros use \n\pstverbscale{} and \n\pstVerb. Don't be surprised +if PSTricks's clipping does not work or causes problem---it is never robust. +"\endpsclip" uses "initclip". This can interfere with other clipping +operations, and especially if the \TeX{} document is converted to an +Encapsulated PostScript file. The command \n\AltClipMode{} causes \n\psclip{} +and \n\endpsclip{} to use "gsave" and "grestore" instead. This bothers some +drivers, especially if \n\psclip{} and \n\endpsclip{} do not end up on the same +page. +\end{drivers} + +\Section{Rotation and scaling boxes\label{S-rotation}} + +There are versions of the standard box rotation macros: +\begin{Ex} + \object \rotateleft{stuff} + \object \rotateright{stuff} + \object \rotatedown{stuff} +\end{Ex} +<stuff> is put in an "\hbox" and then rotated or scaled, leaving the +appropriate amount of spaces. Here are a few uninteresting examples: +\begin{example**} + \Large\bfseries \rotateleft{Left} \rotatedown{Down} \rotateright{Right} +\end{example**} + + +There are also two box scaling macros: +\begin{description} + +\mitem \psscalebox{num1 `num2'}{stuff} + + If you give two numbers in the first argument, <num1> is used to scale +horizontally and <num2> is used to scale vertically. If you give just one +number, the box is scaled by the same in both directions. You can't scale by +zero, but negative numbers are OK, and have the effect of flipping the box +around the axis. You never know when you need to do something like +\psscalebox{-1 1}{this} ("\psscalebox{-1 1}{this}"). + +\mitem \psscaleboxto\c~{stuff} + + This time, the first argument is a (Cartesian) coordinate, and the box is +scaled to have width \x{} and height (plus depth) \y{}. If one of the +dimensions is 0, the box is scaled by the same amount in both directions. For +example: +\begin{example**} + \psscaleboxto(4,2){Big and long} +\end{example**} + +\end{description} + +PSTricks defines LR-box environments for all these box rotation and scaling +commands: +\begin{LVerb} + \pslongbox{Rotateleft}{\rotateleft} + \pslongbox{Rotateright}{\rotateright} + \pslongbox{Rotatedown}{\rotatedown} + \pslongbox{Scalebox}{\psscalebox} + \pslongbox{Scaleboxto}{\psscaleboxto} +\end{LVerb} + +Here is an example where we \n\Rotatedown{} for the answers to exercises: +\begin{example**} + "\parbox{4cm}{\raggedright\noindent\hsize 4cm + Question: How do Democrats organize a firing squad? + + \begin{Rotatedown} + \parbox{\hsize}{Answer: First they get in a circle, \ldots\hss}% + \end{Rotatedown} + "} +\end{example**} + +See the documentation of the "fancybox" package for tips on rotating +a \LaTeX{} "table" or "figure" environment, and other boxes. + +\endinput + +%% END psd-text.tex diff --git a/Master/texmf-dist/doc/generic/pstricks/psd-tree.tex b/Master/texmf-dist/doc/generic/pstricks/psd-tree.tex new file mode 100644 index 00000000000..c7a7d78320e --- /dev/null +++ b/Master/texmf-dist/doc/generic/pstricks/psd-tree.tex @@ -0,0 +1,816 @@ +%% BEGIN psd-tree.tex + +\part{Trees\label{P-trees}} + +\Section{Overview} + +\File{pst-tree} +The node and node connections are perfect tools for making trees, but +positioning the nodes using "\rput" would be rather tedious.\footnote{% +Unless you have a computer program that generates the coordinates.} +The file "pstree.tex" / "pstree.sty" contains a high-level interface for +making trees. + +The tree commands are +\begin{Ex} + \object \pstree{<root>}{<successors>} + \object \psTree{<root>} <successors> \Main\endpsTree +\end{Ex} +These do the same thing, but just have different syntax. "\psTree" is the +``long'' version.\footnote{% +\LaTeX{} purists can write "\begin{psTree}" and "\end{psTree}" instead.} +These macros make a box that encloses all the nodes, and whose baseline passes +through the center of the root. + +Most of the nodes described in Section \ref{S-nodes} has a variant for use +within a tree. These variants are called tree nodes, and are described in +Section \ref{S-treenodes}. + +Trees and tree nodes are called \emph{tree objects}. The <root> of a tree +should be a single tree object, and the <successors> should be one or more +tree objects. Here is an example with only nodes: +\begin{example**} + \pstree[radius=3pt]{\Toval{root}}{\TC* \TC* \TC* \TC*} +\end{example**} +There is no difference between a terminal node and a root node, other than +their position in the \n\pstree{} command. + +Here is an example where a tree is included in the list of successors, and +hence becomes subtree: +\begin{example**} + \pstree[radius=3pt]{\Tp}{% + \TC* + \pstree{\TC}{\TC* \TC*} + \TC*} +\end{example**} + + +\Section{Tree Nodes} + +For most nodes described in Section \ref{S-nodes}, there is a variant for use +in trees, called a tree node. In each case, the name of the tree node is +formed by omitting "node" from the end of the name and adding "T" at the +beginning. For example, "\ovalnode" becomes "\Toval". Here is the list of such +tree nodes: +\begin{Ex} + \object \Tp`*[par]' + \object \Tc`*[par]'{dim} + \object \TC`*[par]' + \object \Tf`*[par]' + \object \Tdot`*[par]' + \object \Tr`*[par]'{stuff} + \object \TR`*[par]'{stuff} + \object \Tcircle`*[par]'{stuff} + \object \TCircle`*[par]'{stuff} + \object \Toval`*[par]'{stuff} + \object \Tdia`*[par]'{stuff} + \object \Ttri`*[par]'{stuff} +\end{Ex} + +The syntax of a tree node is the same as of its corresponding ``normal'' node, +except that: +\begin{itemize} + \item There is always an optional argument for setting graphics parameters, + even if the original node did not have one; + \item There is no argument for specifying the name of the node; + \item There is never a coordinate argument for positioning the node; and + \item To set the reference point with \n\Tr, set the \p{ref} parameter. +\end{itemize} + +Figure \ref{allnodes} gives a reminder of what the nodes look like. + +\begin{figure} +\begin{example*} + \small + \psset{armB=1cm, levelsep=3cm, treesep=-3mm, + angleB=-90, angleA=90, nodesepA=3pt} + \def\s#1{#1~{\tt\string#1}} + \def\b#1{#1{\tt\string#1}} + \def\psedge#1#2{\ncangle{#2}{#1}} + \psTree[treenodesize=1cm]{\Toval{Tree nodes}} + \s\Tp + \Tc{.5}~{\tt\string\Tc} + \s\TC + \psTree[levelsep=4cm,armB=2cm]{\Tp[edge=\ncline]} + \b\Tcircle + \s\Tdot + \TCircle[radius=1.2]{\tt\string\TCircle} + \Tn + \b\Toval + \b\Ttri + \b\Tdia + \endpsTree + \s\Tf + \b\Tr + \b\TR + \endpsTree +\end{example*} +\caption{The tree nodes.\label{allnodes}} +\end{figure} + +The difference between "\Tr" and "\TR" (variants of "\rnode" and "\Rnode", +respectively) is important with trees. Usually, you want to use "\TR" with +vertical trees because the baselines of the text in the nodes line up +horizontally. For example: +\begin{example**} + $ + \pstree[nodesepB=3pt]{\Tcircle{X}}{% + \TR{\tilde{\tilde{X}}} + \TR{x} + \TR{y}} + $ +\end{example**} +Compare with this example, which uses \n\Tr: +\begin{example**} + $ + \pstree[nodesepB=3pt]{\Tcircle{X}}{% + \Tr{\tilde{\tilde{X}}} + \Tr{x} + \Tr{y}} + $ +\end{example**} + +There is also a null tree node: + \Mac \Tn +It is meant to be just a place holder. Look at the tree in Figure +page~\pageref{allnodes}. The bottom row has a node missing in the middle. +\n\Tn{} was used for this missing node. + +There is also a special tree node that doesn't have a ``normal'' version and +that can't be used as the root node of a whole tree: + \Mac \Tfan`*[par]' +This draws a triangle whose base is +\begin{Ex} + \Par{fansize=dim} +\end{Ex} +and whose opposite corner is the predecessor node, adjusted by the value of +\p{nodesepA} and \p{offsetA}. +For example: +\begin{example**} + \pstree[dotstyle=oplus,dotsize=8pt,nodesep=2pt]{\Tcircle{11}}{% + \Tdot + \pstree{\Tfan}{\Tdot} + \pstree{\Tdot}{\Tfan[linestyle=dashed]}} +\end{example**} + + +\Section{Tree orientation} + +Trees can grow down, up, right or left, depending on the +\begin{Ex} + \Par{treemode=D/U/R/L} +\end{Ex} +parameter. + +Here is what the previous example looks like when it grows to the right: +\begin{example**} + \pstree[dotstyle=oplus,dotsize=8pt,nodesep=2pt,treemode=R] + {\Tcircle{11}}{% + \Tdot + \pstree{\Tfan}{\Tdot} + \pstree{\Tdot}{\Tfan[linestyle=dashed]}} +\end{example**} + +You can change the \p{treemode} in the middle of the tree. +For example, here is a tree that grows up, and that has a subtree which grows +to the left: +\begin{example**} + \footnotesize + \pstree[treemode=U,dotstyle=otimes,dotsize=8pt,nodesep=2pt] + {\Tdot}{% + \pstree[treemode=L]{\Tdot}{\Tcircle{1} \Tcircle{2}} + \pstree{\Tdot}{\Tcircle{3} \Tcircle{4}}} +\end{example**} + +Since you can change a tree's orientation, it can make sense to include a tree +(<treeB>) as a root node (of <treeA>). This makes a single logical tree, whose +root is the root of <treeB>, and that has successors going off in different +directions, depending on whether they appear as a successor to <treeA> or to +<treeB>. +\begin{example**} + \pstree{\pstree[treemode=L]{\Tcircle{root}}{\Tr{B}}}{% + \Tr{A1} + \Tr{A2}} +\end{example**} + +%%DG: to do + +On a semi-related theme, note that any node that creates an LR-box can contain +a tree. However, nested trees of this kind are not related in any way to the +rest of the tree. Here is an example: +\begin{example**} + \psTree{\Tcircle{% + \pstree[treesep=0.4,levelsep=0.6, + nodesepB=-6pt]{\Tdot}{% + \TR{a} \TR{b}}}} + \TC + \TC + \endpsTree +\end{example**} + +When the tree grows up or down, the successors are lined up from left to right +in the order they appear in \n\pstree. When the tree grows to the left or +right, the successors are lined up from top to bottom. As an afterthought, you +might want to flip the order of the nodes. The +\begin{Ex} + \Par{treeflip=true/false} +\end{Ex} +let's you do this. For example: +\begin{example**} + \footnotesize + \pstree[treemode=U,dotstyle=otimes,dotsize=8pt, + nodesep=2pt,treeflip=true]{\Tdot}{% + \pstree[treemode=R]{\Tdot}{\Tcircle{1} \Tcircle{2}} + \pstree{\Tdot}{\Tcircle{3} \Tcircle{4}}} +\end{example**} +Note that I still have to go back and change the \p{treemode} of the subtree +that used to grow to the left. + + +\Section{The distance between successors} + +The distance between successors is +\begin{Ex} + \Par{treesep=dim} +\end{Ex} +The rest of this section describes ways to fine-tune the spacing between +successors. + +You can change the method for calculating the distance between subtrees by +setting the +\begin{Ex} + \Par{treefit=tight/loose} +\end{Ex} +parameter. Here are the two methods: +\begin{description} + \item[tight] When \p{treefit=tight}, which is the default, \p{treesep} is + the minimum distance between each of the levels of the subtrees. + \item[loose] When \p{treefit=loose}, \p{treesep} is the distance between the + subtrees' bounding boxes. Except when you have large intermediate nodes, the + effect is that the horizontal distance (or vertical distance, for horizontal + trees) between all the terminal nodes is the same (even when they are on + different levels).\footnote{% + When all the terminal nodes are on the same level, and the intermediate + nodes are not wider than the base of their corresponding subtrees, then + there is no difference between the two methods.} +\end{description} + +Compare: +\begin{center} +\tabcolsep=1cm +\begin{tabular}{cc} + \psset{radius=2pt} + \pstree{\TC*}{% + \TC + \pstree{\TC*}{% + \pstree{\Tc{3pt}}{\TC \TC} + \TC*}} + & + \psset{radius=2pt} + \pstree[treefit=loose]{\TC*}{% + \TC + \pstree{\TC*}{% + \pstree{\Tc{3pt}}{\TC \TC} + \TC*}} +\end{tabular} +\end{center} + +With \p{treefit=loose}, trees take up more space, but sometimes the structure +of the tree is emphasized. + +%Another (orthogonal) way to highlight the structure of the tree is by setting +%\begin{Ex} +% \Par{xtreesep=dim} +%\end{Ex} +%to a positive value. The effect is that adjacent nodes with different parents +%are farther apart than adjacent nodes with the same parent.\footnote{% +%When \p{treefit=tight}, the minimum distance between levels other than the top +%of the subtrees is increased by \p{xtreesep}. When \p{treefit=loose}, the +%minimum distance between subtrees is increased by \p{xtreesep}}. + +%This would have no effect in the previous two examples, but compare the +%spacing between the two subtrees in +%\begin{example**} +% \psTree[radius=2pt,levelsep=1.5,xtreesep=.25cm] \TC* \\ +% \pstree{\TC*}{\TC* \TC*} +% \pstree{\TC*}{\TC* \TC*} +% \endpsTree +%\end{example**} +%with the spacing in +%\begin{example**} +% \psTree[radius=2pt,levelsep=1.5] \TC* \\ +% \pstree{\TC*}{\TC* \TC*} +% \pstree{\TC*}{\TC* \TC*} +% \endpsTree +%\end{example**} + +Sometimes you want the spacing between the centers of the nodes to be regular +even though the nodes have different sizes. If you set +\begin{Ex} + \Par{treenodesize=dim} +\end{Ex} +to a non-negative value, then PSTricks sets the width (or height+depth for +vertical trees) to \p{treenodesize}, \emph{for the purpose of calculating the +distance between successors}. + +For example, ternary trees look nice when they are symmetric, as in the +following example: +\begin{example**} + \pstree[nodesepB=-8pt,treenodesize=.85]{\Tc{3pt}}{% + \TR{$x=y$} + \TR{$x_1=y_1$} + \TR{$x_{11}=y_{11}$}}%$ +\end{example**} +Compare with this example, where the spacing varies with the size of the +nodes: +\begin{example**} + \pstree[nodesepB=-8pt]{\Tc{3pt}}{% + \TR{$x=y$} + \TR{$x_1=y_1$} + \TR{$x_{11}=y_{11}$}}%$ +\end{example**} + +Finally, if all else fails, you can adjust the distance between two successors +by inserting + \Mac \tspace{dim} +between them: +\begin{example**} + \pstree{\Tc{3pt}}{% + \Tdia{foo} + \tspace{-0.5} + \Toval{and} + \Ttri{bar}} +\end{example**} + +\Section{Spacing between the root and successors} + +The distance between the center lines of the tree levels is: +\begin{Ex} + \Par{levelsep=*dim} +\end{Ex} + +If you want the spacing between levels to vary with the size of the levels, +use the * convention. Then \p{levelsep} is the distance between the bottom of +one level and the top of the next level (or between the sides of the two +levels, for horizontal trees). + +Note: PSTricks has to write some information to your ".aux" file if using +\LaTeX, or to "\jobname.pst" otherwise, in order to calculate the spacing. +You have to run your input file a few times before PSTricks gets the spacing +right. + +%%DG: to do +%You are most likely to want to set \p{varlevelsep} to "true" in horizontal +trees. Compare the following example: +\begin{example} + \def\psedge#1#2{\ncdiagg[nodesep=3pt,angleA=180,armA=0]{#2}{#1}} + \pstree[treemode=R,levelsep=*1cm] + {\Tr{George Alexander Kopf VII}}{% + \pstree{\Tr{Barry Santos}}{\Tr{James Kyle} \Tr{Ann Ada}} + \pstree{\Tr{Terri Maloney}}{\Tr{Uwe Kopf} \Tr{Vera Kan}}} +\end{example} +with this one, were the spacing between levels is fixed: +\begin{example} + \def\psedge#1#2{\ncdiagg[nodesep=3pt,angleA=180,armA=0]{#2}{#1}} + \pstree[treemode=R,levelsep=3cm] + {\Tr{George Alexander Kopf VII}}{% + \pstree{\Tr{Barry Santos}}{\Tr{James Kyle} \Tr{Ann Ada}} + \pstree{\Tr{Terri Maloney}}{\Tr{Uwe Kopf} \Tr{Vera Kan}}} +\end{example} + +%The center of the root node of a tree is positioned above the midpoint between +%the centers of the two outer successors. If you want the root to be positioned +%drectly above one of the successors, put the command +% \Mac \treecenter +%right \emph{after} that successor. For example: +%\begin{example**} +% \def\myfan#1{\Tfan[fillstyle=solid,fillcolor=#1]\treecenter}% +% \pstree{\Tcircle{$x_2$}}{% +% \pstree{\Tcircle{$x_1$}}{% +% \pstree{\Tcircle{$x_0$}}{\myfan{black}} +% \myfan{gray}} +% \myfan{white}} +%\end{example**} + +%Here is another interesting example: +%\begin{example} +% \def\psedge{\ncangle[angleA=0,angleB=90]} +% \pstree[treesep=10pt]{\Tcircle[name=after]{$x_0$}}{% +% \Tfan[fillstyle=solid,fillcolor=black] +% \treecenter +% \pstree{\Tcircle{$x_1$}}{\Tfan[fillstyle=solid,fillcolor=darkgray]} +% \pstree{\Tcircle{$x_2$}}{\Tfan[fillstyle=solid,fillcolor=gray]} +% \pstree{\Tcircle{$x_3$}}{\Tfan[fillstyle=solid,fillcolor=lightgray]} +% \pstree{\Tcircle{$x_4$}}{\Tfan[fillstyle=solid,fillcolor=white]}} +%\end{example} + + +\Section{Edges} + +Right after you use a tree node command, "\pssucc" is equal to the name of the +node, and "\pspred" is equal to the name of the node's predecessor. Therefore, +you can draw a line between the node and its predecessor by inserting, for +example, +\begin{LVerbatim} + \ncline{\pspred}{\pssucc} +\end{LVerbatim} + +To save you the trouble of doing this for every node, each tree node executes +\begin{LVerbatim} + \psedge{\pspred}{\pssucc} +\end{LVerbatim} +The default definition of "\psedge" is "\ncline", but you can redefine it as +you please with "\def" or \LaTeX's "\renewcommand". + +For example, here I use \n\ncdiag, with \p{armA=0}, to get all the node +connections to emanate from the same point in the predecessor:\footnote{% +\LaTeX{} users can instead type: +\begin{LVerbatim} + \renewcommand{\psedge}{\ncdiag[armA=0,angleB=180,armB=1cm]} +\end{LVerbatim} +} +\begin{example} + \def\psedge{\ncdiag[armA=0,angleB=180,armB=1cm]} + \pstree[treemode=R,levelsep=3.5cm,framesep=2pt] + {\Tc{6pt}}{% + \small \Tcircle{K} \Tcircle{L} \Tcircle{M} \Tcircle{N}} +\end{example} + +Here is an example with \n\ncdiagg. Note the use of a negative \p{armA} value +so that the corners of the edges are vertically aligned, even though the nodes +have different sizes: +\begin{example} + $ + \def\psedge#1#2{% + \ncdiagg[angleA=180, armA=-3cm,nodesep=4pt]{#2}{#1}} + % Or: \renewcommand{\psedge}[2]{ ... } + \pstree[treemode=R, levelsep=5cm]{\Tc{3pt}}{% + \Tr{z_1\leq y} + \Tr{z_1<y\leq z_2} + \Tr{z_2<y\leq x} + \Tr{x<y}} + $ +\end{example} + +Another way to define \n\psedge{} is with the +\begin{Ex} + \Par{edge=command} +\end{Ex} +parameter. Be sure to enclose the value in braces "{}" if it contains commas +or other parameter delimiters. This gets messy if your command is long, and +you can't use arguments like in the preceding example, but for simple changes +it is useful. For example, if I want to switch between a few node connections +frequently, I might define a command for each node connection, and then use +the \p{edge} parameter. +\begin{example**} + \def\dedge{\ncline[linestyle=dashed]} + \pstree[treemode=U,radius=2pt]{\Tc{3pt}}{% + \TC*[edge=\dedge] + \pstree{\Tc{3pt}}{\TC*[edge=\dedge] \TC*} + \TC*} +\end{example**} + +You can also set \n{edge=none} to suppress the node connection. + +If you want to draw a node connection between two nodes that are not direct +predecessor and successor, you have to give the nodes a name that you can +refer to, using the \p{name} parameter. For example, here I connect two nodes +on the same level: +\begin{example**} + \pstree[nodesep=3pt,radius=2pt]{\Toval{nature}}{% + \pstree{\Tc[name=top]{3pt}}{\TC* \TC*} + \pstree{\Tc[name=bot]{3pt}}{\TC* \TC*}} + \ncline[linestyle=dashed]{top}{bot} +\end{example**} + +We conclude with the more examples. + +\begin{example**} + \def\psedge{\nccurve[angleB=180, nodesepB=3pt]} + \pstree[treemode=R, treesep=1.5, levelsep=3.5]% + {\Toval{root}}{\Tr{X} \Tr{Y} \Tr{Z}} +\end{example**} + +\begin{example**} + \pstree[nodesepB=3pt, arrows=->, xbbl=15pt, + xbbr=15pt, levelsep=2.5cm]{\Tdia{root}}{% + $ + \TR[edge={\ncbar[angle=180]}]{x} + \TR{y} + \TR[edge=\ncbar]{z} + $} +\end{example**} + +\begin{example**} + \psset{armB=1cm, levelsep=3cm, treesep=1cm, + angleB=-90, angleA=90, arrows=<-, nodesepA=3pt} + \def\psedge#1#2{\ncangle{#2}{#1}} + \pstree[radius=2pt]{\Ttri{root}}{\TC* \TC* \TC* \TC*} +\end{example**} + + +\Section{Edge and node labels} + +Right after a node, an edge has typically been drawn, and you can attach +labels using \n\ncput\, \n\tlput, etc. + +With \n\tlput, \n\trput, \n\taput{} and \n\tbput, you can align the labels +vertically or horizontally, just like the nodes. This can look nice, at least +if the slopes of the node connections are not too different. +\begin{example**} + \pstree[radius=2pt]{\Tp}{% + \psset{tpos=.6} + \TC* \tlput{k} + \pstree{\Tc{3pt} \tlput[labelsep=3pt]{r}}{% + \TC* \tlput{j} + \TC* \trput{i}} + \TC* \trput{m}} +\end{example**} +Within trees, the \p{tpos} parameter measures this distance from the +predecessor to the successor, whatever the orientation of the true. +(Outside of trees it measures the distance from the top to bottom or left to +right nodes.) + +PSTricks also sets \p{shortput=tab} within trees. This is a special +\p{shortput} option that should not be used outside of trees. It implements +the following abbreviations, which depend of the orientation of the true: +\begin{center} +\begin{tabular}{ccc} + & \multicolumn{2}{c}{Short for:}\\ + \emph{Char.} & \emph{Vert.} & \emph{Horiz.}\\[2pt] + "^" & \n\tlput & \n\taput \\ + "_" & \n\trput & \n\tbput +\end{tabular} +\end{center} +(The scheme is reversed if \p{treeflip=true}.) +\begin{example**} + \psset{tpos=.6} + \pstree[treemode=R, thistreesep=1cm, + thislevelsep=3cm,radius=2pt]{\Tc{3pt}}{% + \pstree[treemode=U, xbbr=20pt]{\Tc{3pt}^{above}}{% + \TC*^{left} + \TC*_{right}} + \TC*^{above} + \TC*_{below}} +\end{example**} + +You can change the character abbreviations with + \Mac \MakeShortTab{<char1>}{<char2>} + +The "\n*put" commands can also give good results: +\begin{example**} + \psset{npos=.6,nrot=:U} + \pstree[treemode=R, thistreesep=1cm, + thislevelsep=3cm]{\Tc{3pt}}{% + \Tc{3pt}\naput{above} + \Tc*{2pt}\naput{above} + \Tc*{2pt}\nbput{below}} +\end{example**} + +You can put labels on the nodes using \n\nput. However, \n\pstree{} won't take +these labels into account when calculating the bounding boxes. + +There is a special node label option for trees that does keep track of the +bounding boxes: + \Mac ~`*[par]'{stuff} +Call this a ``tree node label''. + +Put a tree node label right after the node to which it applies, before any +node connection labels (but node connection labels, including the short forms, +can follow a tree node label). The label is positioned directly below the node +in vertical trees, and similarly in other trees. For example: +\begin{example**} + \pstree[radius=2pt]{\Tc{3pt}\nput{45}{\pssucc}{root}}{% + \TC*~{$h$} \TC*~{$i$} \TC*~{$j$} \TC*~{$k$}} +\end{example**} +Note that there is no ``long form'' for this tree node label. However, you can +change the single character used to delimit the label with + \Mac \MakeShortTnput{<char1>} +If you find it confusing to use a single character, you can also use a command +sequence. E.g., +\begin{LVerb} + \MakeShortTnput{\tnput} +\end{LVerb} + +You can have multiple labels, but each successive label is positioned relative +to the bounding box that includes the previous labels. Thus, the order in +which the labels are placed makes a difference, and not all combinations will +produce satisfactory results. + +You will probably find that the tree node label works well for terminal nodes, +without your intervention. However, you can control the tree node labels be +setting several parameters. + +To position the label on any side of the node ("l"eft, "r"ight, "a"bove or +"b"elow), set: +\begin{Ex} + \Par{tnpos=l/r/a/b} +\end{Ex} +\begin{example**} + \psframebox{% + \pstree{\Tc{3pt}~[tnpos=a,tndepth=0pt,radius=4pt]{root}}{% + \TC*~[tnpos=l]{$h$} + \TC*~[tnpos=r]{$i$}}} +\end{example**} +When you leave the argument empty, which is the default, PSTricks chooses the +label position is automatically. + +To change the distance between the node and the label, set +\begin{Ex} + \Par{tnsep=<dim>} +\end{Ex} +When you leave the argument empty, which is the default, PSTricks uses the +value of \p{labelsep}. When the value is negative, the distance is measured +from the center of the node. + +When labels are positioned below a node, the label is given a minimum height +of +\begin{Ex} + \Par{tnheight=<dim>}(\string\ht\string\strutbox) +\end{Ex} +Thus, if you add labels to several nodes that are horizontally aligned, and if +either these nodes have the same depth or \p{tnsep} is negative, and if the +height of each of the labels is no more than \p{tnheight}, then the labels +will also be aligned by their baselines. The default is "\ht\strutbox", which +in most \TeX{} formats is the height of a typical line of text in the current +font. Note that the value of \p{tnheight} is not evaluated until it is used. + +The positioning is similar for labels that go below a node. The label is given +a minimum \emph{depth} of +\begin{Ex} + \Par{tndepth=<dim>}(\string\dp\string\strutbox) +\end{Ex} + +For labels positioned above or below, the horizontal reference point of the +label, i.e., the point in the label directly above or below the center of the +node, is set by the \p{href} parameter. + +When labels are positioned on the left or right, the right or left edge of the +label is positioned distance \p{tnsep} from the node. The vertical point that +is aligned with the center of the node is set by +\begin{Ex} + \Par{tnyref=<num>} +\end{Ex} +When you leave this empty, \p{vref} is used instead. Recall that \p{vref} +gives the vertical \emph{distance} from the baseline. Otherwise, the +\p{tnyref} parameter works like the \p{yref} parameter, giving the fraction of +the distance from the bottom to the top of the label. + +\Section{Details} + +PSTricks does a pretty good job of positioning the nodes and creating a box +whose size is close to the true bounding box of the tree. However, PSTricks +does not take into account the node connections or labels when calculating the +bounding boxes, except the tree node labels. + +If, for this or other reasons, you want to fine tune the bounding box of the +nodes, you can set the following parameters: +\begin{Ex} + \Par{bbl=dim} + \Par{bbr=dim} + \Par{bbh=dim} + \Par{bbd=dim} + \Par{xbbl=dim} + \Par{xbbr=dim} + \Par{xbbh=dim} + \Par{xbbd=dim} +\end{Ex} +The "x" versions increase the bounding box by <dim>, and the others set the +bounding box to <dim>. There is one parameter for each direction from the +center of the node, \textbf{l}eft, \textbf{r}ight, \textbf{h}eight, and +\textbf{d}epth. + +These parameters affect trees and nodes, and subtrees that switch directions, +but not subtrees that go in the same direction as their parent tree (such +subtrees have a profile rather than a bounding box, and should be adjusted by +changing the bounding boxes of the constituent nodes). + +Save any fiddling with the bounding box until you are otherwise finished with +the tree. + +You can see the bounding boxes by setting the +\begin{Ex} + \Par{showbbox=true/false} +\end{Ex} +parameter to "true". To see the bounding boxes of all the nodes in a tree, you +have to set this parameter before the tree. + +In the following example, the labels stick out of the bounding box: +\begin{example**} + \psset{tpos=.6,showbbox=true} + \pstree[treemode=U]{\Tc{5pt}}{% + \TR{foo}^{left} + \TR{bar}_{right}} +\end{example**} +Here is how we fix it: +\begin{example**} + \psset{tpos=.6,showbbox=true} + \pstree[treemode=U,xbbl=8pt,xbbr=14pt]{\Tc{5pt}}{% + \TR{foo}^{left} + \TR{bar}_{right}} +\end{example**} +Now we can frame the tree: +\begin{example**} + \psframebox[fillstyle=solid,fillcolor=lightgray,framesep=14pt, + linearc=14pt,cornersize=absolute,linewidth=1.5pt]{% + \psset{tpos=.6,border=1pt,nodesepB=3pt} + \pstree[treemode=U,xbbl=8pt,xbbr=14pt]{% + \Tc[fillcolor=white,fillstyle=solid]{5pt}}{% + \TR*{foo}^{left} + \TR*{bar}_{right}}} +\end{example**} +We would have gotten the same result by changing the bounding box of the two +terminal nodes. + +To skip levels, use +\begin{Ex} + \object \skiplevel`*[par]'{nodes or subtrees} + \object \skiplevels`*[par]'{int} <nodes or subtrees> \string\endskiplevels +\end{Ex} +These are kind of like subtrees, but with no root node. +\begin{example} + \pstree[treemode=R,levelsep=1.8,radius=2pt]{\Tc{3pt}}{% + \skiplevel{\Tfan} + \pstree{\Tc{3pt}}{% + \TC* + \skiplevels{2} + \pstree{\Tc{3pt}}{\TC* \TC*} + \TC* + \endskiplevels + \pstree{\Tc{3pt}}{\TC* \TC*}}} +\end{example} +The profile at the missing levels is the same as at the first non-missing +level. You can adjust this with the bounding box parameters. You get greatest +control if you use nested \n\skiplevel{} commands instead of \n\skiplevels. + +\begin{example} + \large + \psset{radius=6pt, dotsize=4pt} + \pstree[thislevelsep=0,edge=none,levelsep=2.5cm]{\Tn}{% + \pstree{\TR{Player 1}}{\pstree{\TR{Player 2}}{\TR{Player 3}}} + \psset{edge=\ncline} + \pstree + {\pstree[treemode=R]{\TC}{\Tdot ~{(0,0,0)} ^{N}}}{% + \pstree{\TC[name=A] ^{L}}{% + \Tdot ~{(-10,10.-10)} ^{l} + \pstree{\TC[name=C] _{r}}{% + \Tdot ~{(3,8,-4)} ^{c} + \Tdot ~{(-8,3,4)} _{d}}} + \pstree{\TC[name=B] _{R}}{% + \Tdot ~{(10,-10.0)} ^{l} + \pstree{\TC[name=D]_{r}}{% + \Tdot ~{(4,8,-3)} ^{c} + \Tdot ~{(0,-5,0)} _{d}}}}} + \ncbox[linearc=.3,boxsize=.3,linestyle=dashed,nodesep=.4]{A}{B} + \ncarcbox[linearc=.3,boxsize=.3,linestyle=dashed, + arcangle=25,nodesep=.4]{D}{C} +\end{example} + +\Section{The scope of parameter changes} + +\p{edge} is the only parameter which, when set in a tree node's parameter +argument, affects the drawing of the node connection (e.g., if you want to +change the \p{nodesep}, your edge has to include the parameter change, or you +have to set it before the node). + +As noted at the beginning of this section, parameter changes made with +\n\pstree{} affect all subtrees. However, there are variants of some of these +parameters for making local changes, i.e, changes that affects only the +current level: +\begin{Ex} + \Par{thistreesep=dim} + \Par{thistreenodesize=dim} + \Par{thistreefit=tight/loose} + \Par{thislevelsep=dim} +\end{Ex} +For example: +\begin{example**} + \pstree[thislevelsep=.5cm,thistreesep=2cm,radius=2pt]{\Tc*{3pt}}{% + \pstree{\TC*}{\TC* \TC*} + \pstree{\TC*}{\TC* \TC*}} +\end{example**} + +There are some things you may want set uniformly across a level in the tree, +such as the \p{levelsep}. At level <n>, the command "\pstreehook<roman(n)>" +(e.g., "\pstreehookii") is executed, if it is defined (the root node of the +whole tree is level 0, the successor tree objects and the node connections +from the root node to these successors is level 1, etc.). In the following +example, the \p{levelsep} is changed for level 2, without having to set the +\p{thislevelsep} parameter for each of the three subtrees that make of level +2: +\begin{example*} + \[ + \def\pstreehookiii{\psset{thislevelsep=3cm}} + \pstree[treemode=R,levelsep=1cm,radius=2pt]{\Tc{4pt}}{% + \pstree{\TC*}{% + \pstree{\TC*}{\Tr{X_1} \Tr{X_2}} + \pstree{\TC*}{\Tr{Y_1} \Tr{Y_2}}} + \pstree{\TC*}{% + \pstree{\TC*}{\Tr{K_1} \Tr{K_2}} + \pstree{\TC*}{\Tr{J_1} \Tr{J_2}}}} + \] +\end{example*} + +\endinput + +%% END psd-tree.tex diff --git a/Master/texmf-dist/doc/generic/pstricks/pst-user.cls b/Master/texmf-dist/doc/generic/pstricks/pst-user.cls new file mode 100644 index 00000000000..19cd07b6ee6 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pstricks/pst-user.cls @@ -0,0 +1,1111 @@ +%% BEGIN pst-user.cls + +%% Macros for typesetting "pst-user.tex" v97. + +%DG \errorcontextlines=100\relax + +\NeedsTeXFormat{LaTeX2e} + +\ProvidesClass{pst-user}[2003/03/03 Class for PSTricks User's Guide (TvZ,RN,DG)] + +\DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} + +\ProcessOptions\relax +\LoadClass{article} + +% Packages +\RequirePackage{pstcol} +\RequirePackage{pst-coil} +\RequirePackage{pst-plot} +\RequirePackage{pst-tree} + +\RequirePackage{fancybox} % Use for the Quick Reference +\RequirePackage{fancyvrb} + +\RequirePackage[dvips]{geometry} + +% The paper dimensions for `dvips' or `VTeX' or `pdfTeX' +% Why not `\AtEndOfClass' or `\AtBeginDocument'? RN + +\RequirePackage{url} +\RequirePackage[ps2pdf,hyperfootnotes=false,colorlinks=true,bookmarks=true] + {hyperref}[2000/03/02] +%\AtEndOfClass{% +% \RequirePackage[ps2pdf,hyperfootnotes=false,colorlinks=false,% +% bookmarks=false] +% %pdfpagelabels,plainpages=false] +% {hyperref}[2000/03/02]} + +%\AtEndOfClass{\AtBeginDocument{\RequirePackage{showframe}}} + +% Fonts related packages +\usepackage[T1]{fontenc} +\RequirePackage{times} +%\RequirePackage{mathptmx} +\RequirePackage[scaled]{helvet} +%\RequirePackage{courier} +\RequirePackage{pifont} + +% Title, version and date +\def\thetitle{PSTricks: User's Guide} +\let\theheadertitle\thetitle % Used with twoside option. +\let\fileversion\Version +\let\filedate\Date + +% Paragraphs are marked by large space rather than indentation: +\parindent 0pt +\parskip 7pt plus 1pt minus 1pt + +% Page layout and various dimensions + +%%% TODO: Using the `geometry' package and `\DeclareOption' -- RN + +% These are for 8.5inx11in paper: +\oddsidemargin 5cm +\evensidemargin 5cm +\textwidth 11.5cm + +% Total bottom margin 1in, text height 8.8in +\topmargin\z@ +\textheight 8.8in +\footskip .625in + +% No headers, 1in top margin +\headheight 0pt +\headsep 0pt + +% Marginal notes always on left. +\marginparwidth 3.5cm +\marginparsep .5cm +\reversemarginpar + +% Now adjust margins for a4 paper size: +\ifdim\paperwidth=210mm \papersizeadjust\fi + +%DG % Now adjust margins for different paper size: +%DG % The a4 option sets \paperwidth and \paperheight for a4 paper: +%DG \@ifundefined{paperwidth}% +%DG {% +%DG \def\paperwidth{8.5in} +%DG \def\paperheight{11in} +%DG }{% +%DG \@tempdima=\paperwidth\relax +%DG \advance\@tempdima-8.5in +%DG \divide\@tempdima 2 +%DG \advance\oddsidemargin\@tempdima +%DG \advance\evensidemargin\@tempdima +%DG \@tempdima=\paperheight\relax +%DG \advance\@tempdima-11in +%DG \divide\@tempdima 2 +%DG \advance\topmargin\@tempdima +%DG } + +%DG % Now adjust left and right margins for twosided printing: +%DG \if@twoside +%DG \advance\oddsidemargin.75cm +%DG \advance\evensidemargin-.75cm +%DG \fi + +%%%%%%%%%%%%%%%%%%%% Various customizations %%%%%%%%%%%%%%%%%%%% + +\def\arraystretch{1.2} + +\hfuzz 1pt + +\def\twosideclearpage{% + \clearpage + \if@twoside + \ifodd\c@page\else + \thispagestyle{empty}% + \null\leavevmode + \clearpage + \fi + \fi} + + + +% Paragraphs are marked by large space rather than indentation: +\setlength{\parindent}{0pt} +\setlength{\parskip}{7pt plus 1pt minus 1pt} + +% Reduce \topsep: +\def\@listI{% + \leftmargin\leftmargini + \parsep 5\p@ plus2.5\p@ minus\p@ + %\topsep 10\p@ plus4\p@ minus6\p@ + \topsep 5\p@ plus2\p@ minus2\p@ + \itemsep 5\p@ plus2.5\p@ minus\p@} +\let\@listi\@listI +\@listi +\def\@listii{% + \leftmargin\leftmarginii + \labelwidth\leftmarginii + \advance\labelwidth-\labelsep + %\topsep 5\p@ plus2.5\p@ minus\p@ + \topsep 2\p@ plus.5\p@ minus\p@ + \parsep 2.5\p@ plus\p@ minus\p@ + \itemsep \parsep} +\def\@listiii{% + \leftmargin\leftmarginiii + \labelwidth\leftmarginiii + \advance\labelwidth-\labelsep + %\topsep 2.5\p@ plus\p@ minus\p@ + \topsep 1\p@ plus.2\p@ minus.2\p@ + \parsep \z@ + \partopsep \p@ plus\z@ minus\p@ + \itemsep \topsep} + +\skip\footins 20pt plus 4pt minus 2pt + +%%%%%%%%%%%%%%%%%%%% Special hacks for User's Guides %%%%%%%%%%%%%%%%%%%% + +%% Listing questions +\newcounter{faq}[section] +\def\thefaq{\arabic{faq}} +\let\l@faq\@gobbletwo +\def\faq{\@startsection{faq}{2}{\z@}% + {3.25ex plus 1ex minus .2ex}{1.5ex plus .2ex}{\faqfont}} +\def\faqfont{\normalsize\sffamily} +\def\faqmark#1{} + +%% Listing errors +\def\error{\vskip 2ex\noindent} + +%%%%%%%%%%%%%%%%%%%% Sections %%%%%%%%%%%%%%%%%%%% + +% Section headings use customizable fonts, leave less space above +% and below, and may overhang on left. + +\def\section{\@startsection{section}{1}{\sechang}% + {-3ex plus -1ex minus -.2ex}{1.5ex plus .2ex}{\secfont}} +\def\subsection{\@startsection{subsection}{2}{\subsechang}% + {-2.75ex plus -1ex minus -.2ex}{1.25ex plus .2ex}{\subsecfont}} +\newdimen\sechang +\newdimen\subsechang +\sechang=-.75in +\subsechang=-.375in +\def\secfont{\sffamily\LARGE\bfseries} % Section headings +\def\subsecfont{\sffamily\Large\bfseries} % Subsection headings + +%%%%%%%%%%%%%%%%%%%% Page style %%%%%%%%%%%%%%%%%%%% + +%% Headings: +\def\ps@docheadings{% + \let\@mkboth\markboth + \def\@oddhead{}% + \let\@evenhead\@oddhead% + \def\@oddfoot{% + \small\sffamily + \rightmark + \hfil + \thepage}% + \def\@evenfoot{% + \small\sffamily + \thepage + \hfil + \theheadertitle}% + \def\sectionmark##1{\markright {##1}}}% +\pagestyle{docheadings} + +%%%%%%%%%%%%%%%%%%%% Table of contents %%%%%%%%%%%%%%%%%%%% + +%% Tight up spacing in TOC: +\newskip\tempskip +\def\TOCshrink{.5} +\def\TableOfContents{% + \begin{quote} + \begin{center} \Large\bf Contents \end{center} + \def\numberline##1{\hbox to 0pt{\hss##1\hskip 1em}}% + \let\oldaddvspace\addvspace + \def\addvspace##1{% + \tempskip##1\relax + \oldaddvspace{\TOCshrink\tempskip}} + \@starttoc{toc}% + \end{quote}} +\def\tableofcontents{% + \clearpage + \markright{Table of contents}% + \TableOfContents + \clearpage} + + +%%%%%%%%%%%%%%%%%%%% Dates %%%%%%%%%%%%%%%%%%%% + +%% This expands the date, as defined in \filedate. + +\def\expanddate#1/#2/#3/{% + \number#3{} + \month=#2 + \ifcase\month\or + January \or February \or March \or April \or May \or June \or + July \or August \or September \or October \or November \or December + \fi + 20#1} +\def\thefiledate{\expandafter\expanddate\Date/} +\date{\thefiledate} + +%%%%%%%%%%%%%%%%%%%% Codes and examples %%%%%%%%%%%%%%%%%%%% + +%% This is an environment for putting samples of code. It is like +%% a variant of \begin{quote}\ttfamily ... \end{quote}. It is NOT verbatim. + +\def\NotNested{\def\begin##1{% + \@latexerr{Bad nesting of environments. + Perhaps missing \end{\@currenvir}}\@eha + \end{\@currenvir}% + \begin{##1}}} +\def\Ex{% + \NotNested + \list{}{}\item[]% + \if@minipage\else\vskip\parskip\fi + \leftskip\@totalleftmargin + \rightskip\z@ + \parindent\z@ + \parskip\z@ + \parfillskip\@flushglue + \hfuzz 1pt + \@@par + \global\@inlabelfalse} +\def\endEx{\endlist} + +%% Various things to make it easier to write code and examples: +\begingroup + \catcode`\{=12 \catcode`\}=12 + \catcode`\(=1 \catcode`\)=2 + \catcode`\+=0 \catcode`\\=12 + +gdef+|(\) % \| = character \ + +gdef+{({) % \{ = character { + +gdef+}(}) % \} = character } ++endgroup +\def\Backslash{\protect\|} + +%%%%%%%%%%%%%%%%%%%% Fonts %%%%%%%%%%%%%%%%%%%% + +% Use scaled versions of the ps fonts. + +\def\times@scale{.96} +\def\helv@scale{.82} +\def\courier@scale{.985} + +%DG \DeclareFontFamily{T1}{times}{} +%DG \def\1{\DeclareFontShape{T1}{times}} +%DG \1{m}{n}{<->s*[\times@scale]ptmrq}{}% +%DG \1{m}{it}{<->s*[\times@scale]ptmriq}{}% +%DG \1{m}{sc}{<->s*[\times@scale]ptmrcq}{}% +%DG \1{b}{n}{<->s*[\times@scale]ptmbq}{}% +%DG \1{b}{it}{<->s*[\times@scale]ptmbiq}{}% +%DG \1{m}{sl}{<->ssub * times/m/it}{}% +%DG \1{b}{sc}{<->sub * times/m/sc}{}% +%DG \1{b}{sl}{<->ssub * times/b/it}{}% +%DG \1{bx}{n}{<->ssub * times/b/n}{}% +%DG \1{bx}{it}{<->ssub * times/b/it}{}% +%DG \1{bx}{sc}{<->sub * times/m/sc}{}% +%DG \1{bx}{sl}{<->ssub * times/b/it}{}% + +%DG \DeclareFontFamily{OT1}{times}{}% +%DG \def\1{\DeclareFontShape{OT1}{times}} +%DG \1{m}{n}{<->s*[\times@scale]ptmr}{}% +%DG \1{m}{it}{<->s*[\times@scale]ptmri}{}% +%DG \1{m}{sc}{<->s*[\times@scale]ptmrc}{}% +%DG \1{b}{n}{<->s*[\times@scale]ptmb}{}% +%DG \1{b}{it}{<->s*[\times@scale]ptmbi}{}% +%DG \1{m}{sl}{<->ssub * times/m/it}{}% +%DG \1{b}{sc}{<->sub * times/m/sc}{}% +%DG \1{b}{sl}{<->ssub * times/b/it}{}% +%DG \1{bx}{n}{<->ssub * times/b/n}{}% +%DG \1{bx}{it}{<->ssub * times/b/it}{}% +%DG \1{bx}{sc}{<->sub * times/m/sc}{}% +%DG \1{bx}{sl}{<->ssub * times/b/it}{}% + +%DG \DeclareFontFamily{T1}{helvetica}{} +%DG \def\1{\DeclareFontShape{T1}{helvetica}} +%DG \1{m}{n}{<->s*[\helv@scale]phvrq}{}% +%DG \1{m}{it}{<->s*[\helv@scale]phvroq}{}% +%DG \1{m}{sc}{<->s*[\helv@scale]phvrcq}{}% +%DG \1{b}{n}{<->s*[\helv@scale]phvbq}{}% +%DG \1{b}{it}{<->s*[\helv@scale]phvboq}{}% +%DG \1{m}{sl}{<->ssub * helvetica/m/it}{}% +%DG \1{b}{sc}{<->sub * helvetica/m/sc}{}% +%DG \1{b}{sl}{<->ssub * helvetica/b/it}{}% +%DG \1{bx}{n}{<->ssub * helvetica/b/n}{}% +%DG \1{bx}{it}{<->ssub * helvetica/b/it}{}% +%DG \1{bx}{sc}{<->sub * helvetica/m/sc}{}% +%DG \1{bx}{sl}{<->ssub * helvetica/b/it}{}% + +%DG \DeclareFontFamily{OT1}{helvetica}{}% +%DG \def\1{\DeclareFontShape{OT1}{helvetica}} +%DG \1{m}{n}{<->s*[\helv@scale]phvr}{}% +%DG \1{m}{it}{<->s*[\helv@scale]phvro}{}% +%DG \1{m}{sc}{<->s*[\helv@scale]phvrc}{}% +%DG \1{b}{n}{<->s*[\helv@scale]phvb}{}% +%DG \1{b}{it}{<->s*[\helv@scale]phvbo}{}% +%DG \1{m}{sl}{<->ssub * helvetica/m/it}{}% +%DG \1{b}{sc}{<->sub * helvetica/m/sc}{}% +%DG \1{b}{sl}{<->ssub * helvetica/b/it}{}% +%DG \1{bx}{n}{<->ssub * helvetica/b/n}{}% +%DG \1{bx}{it}{<->ssub * helvetica/b/it}{}% +%DG \1{bx}{sc}{<->sub * helvetica/m/sc}{}% +%DG \1{bx}{sl}{<->ssub * helvetica/b/it}{}% + +%DG \DeclareFontFamily{T1}{r-helvetica}{} +%DG \def\1{\DeclareFontShape{T1}{r-helvetica}} +%DG \1{m}{n}{<->s*[\helv@scale]rphvrq}{}% +%DG \1{m}{it}{<->s*[\helv@scale]rphvroq}{}% +%DG \1{m}{sc}{<->s*[\helv@scale]rphvrcq}{}% +%DG \1{b}{n}{<->s*[\helv@scale]rphvbq}{}% +%DG \1{b}{it}{<->s*[\helv@scale]rphvboq}{}% +%DG \1{m}{sl}{<->ssub * helvetica/m/it}{}% +%DG \1{b}{sc}{<->sub * helvetica/m/sc}{}% +%DG \1{b}{sl}{<->ssub * helvetica/b/it}{}% +%DG \1{bx}{n}{<->ssub * helvetica/b/n}{}% +%DG \1{bx}{it}{<->ssub * helvetica/b/it}{}% +%DG \1{bx}{sc}{<->sub * helvetica/m/sc}{}% +%DG \1{bx}{sl}{<->ssub * helvetica/b/it}{}% + +%DG \DeclareFontFamily{OT1}{r-helvetica}{}% +%DG \def\1{\DeclareFontShape{OT1}{r-helvetica}} +%DG \1{m}{n}{<->s*[\helv@scale]rphvr}{}% +%DG \1{m}{it}{<->s*[\helv@scale]rphvro}{}% +%DG \1{m}{sc}{<->s*[\helv@scale]rphvrc}{}% +%DG \1{b}{n}{<->s*[\helv@scale]rphvb}{}% +%DG \1{b}{it}{<->s*[\helv@scale]rphvbo}{}% +%DG \1{m}{sl}{<->ssub * helvetica/m/it}{}% +%DG \1{b}{sc}{<->sub * helvetica/m/sc}{}% +%DG \1{b}{sl}{<->ssub * helvetica/b/it}{}% +%DG \1{bx}{n}{<->ssub * helvetica/b/n}{}% +%DG \1{bx}{it}{<->ssub * helvetica/b/it}{}% +%DG \1{bx}{sc}{<->sub * helvetica/m/sc}{}% +%DG \1{bx}{sl}{<->ssub * helvetica/b/it}{}% + +%DG \DeclareFontFamily{OT1}{symbol}{} +%DG \DeclareFontShape{OT1}{symbol}{m}{n}{<->s*[\times@scale]rpsyr}{} + +%DG \let\saved@fontwarning\font@warning +%DG \let\font@warning\@gobble +%DG \DeclareSymbolFont{operators}{OT1}{times} {m}{n} +%DG \DeclareSymbolFont{letters} {OT1}{times} {m}{it} + +%DG \SetSymbolFont{operators}{bold}{OT1}{times} {b}{n} +%DG \SetSymbolFont{letters} {bold}{OT1}{times} {b}{it} + +%DG \renewcommand{\default@family}{times}% +%DG \renewcommand{\rmdefault}{times}% +%DG \renewcommand{\sfdefault}{helvetica}% +%DG \renewcommand{\ttdefault}{r-helvetica}% +%DG \fontfamily\default@family\selectfont + +%DG \@namedef{FV@fontfamily@helvetica}{% +%DG \def\FV@FontScanPrep{}% +%DG \def\FV@FontFamily{\fontfamily{r-helvetica}}} + +% A few tricks to avoid math fonts: + +\def\AmS{AMS} + +%RN \def\symchar#1{% +%RN \mbox{% +%RN \kern .3pt +%RN \fontfamily{symbol}\fontseries{m}\fontshape{n}\selectfont +%RN \char#1 +%RN \kern .3pt}} + +\def\symchar#1{% + \mbox{% + \kern .3pt + \Pisymbol{psy}{#1} + \kern .3pt}} + +\def\lt{\symchar{'074}} +\def\gt{\symchar{'076}} +\def\leq{\symchar{'243}} +\def\geq{\symchar{'263}} +\def\bullet{\symchar{'267}} +\def\ldots{\symchar{'274}} +\mathcode`\-="20B1 + +\renewcommand{\ttdefault}{\sfdefault} + +% The font commands: +\def\MainFont{\ttfamily\bfseries\large} % For macro definitions. +\def\UsageFont{\ttfamily\bfseries} % For in-line macro names. +\def\InlineFont{\ttfamily} % For other in-line snipets of code. +\def\MetaFont{\sffamily\slshape} % For meta arguments. +%\def\OpArgFont{\fontseries{m}\selectfont} % For optional arguments. +\def\OpArgFont{\normalfont} % For optional arguments. + +\begingroup + \catcode`\<=\active + \gdef\ShortMeta{% + \catcode`\<=\active + \def<##1>{{\MetaFont ##1\/}}} +\endgroup + +\def\DeleteShortMeta{\catcode`\<=12\relax} + +% <foo> is short for {\MetaFont foo}. +% Works with \Verb command and LVerb* environment, +% but is disabled in LVerb environment. +\ShortMeta + +% Short-cuts for coordinates: +\def\x#1{{\MetaFont x#1\/}} +\def\y#1{{\MetaFont y#1\/}} +\def\c#1{{\InlineFont(\x{#1},\kern 1pt\y{#1})}} +\def\cn{\c{n}} + +%%%%%%%%%%%%%%%%%%%% Verbatim %%%%%%%%%%%%%%%%%%%% + +% `fancyvrb' modifications to suppress the management of the < and > +% characters, to allow to use them to change the font. + +% So, we suppress the codes in `fancyvrb' to disable ligatures management. +% (D.G. - 02/28/03) +\def\FV@SetupFont{% + \FV@BaseLineStretch + \FV@FontSize + \FV@FontFamily + \FV@FontSeries + \FV@FontShape + \selectfont +% D.G. modification begin - Feb. 28, 2003 +% \@noligs} +} +% D.G. modification end + +% D.G. modification begin - Feb. 28, 2003 +%\def\FV@GetLine{\@noligs\expandafter\FV@CheckScan\FancyVerbGetLine} +\def\FV@GetLine{\expandafter\FV@CheckScan\FancyVerbGetLine} +% D.G. modification end + +\AtBeginDocument{\DefineShortVerb{\"}} + +\VerbatimFootnotes + +\fvset{gobble=2,commentchar=\",codes={\catcode`\<=12},fontfamily=helvetica, + frame=single,numbers=left,numbersep=1mm} + +\DefineVerbatimEnvironment{LVerb}{LVerbatim}{fontsize=\small} +\DefineVerbatimEnvironment{LVerb*}{LVerbatim}% + {fontsize=\small,codes={\catcode`\<=13}} + +\def\FV@Space{\ \ } + +% Verbatim items: + +\newcommand{\vitem}{\SaveVerb[codes={\catcode`\<=13}, + aftersave={\item[\UseVerb{item}]}]{item}} + +%%%%%%%%%%%%%%%%%%%% Example environments %%%%%%%%%%%%%%%%%%%% + +% The Example environment uses the fancybox.sty macros +% 1. Save example verbatim to \jobname.tmp, +% 2. Input verbatim with \catcode`\"=14 (" is a comment). +% 3. Input again with \catcode\`"=9 (" is ignored). + +% There are 5 example environments: +% 1. example : center output +% 2. example* : process output with no special formatting. +% 3. example** : Place on left side of verbatim input. +% 4. MEx : Like example**, but contents put in picture environment. +% 5. MEx* : Like MEx, but with grid. +\newcommand{\BeginExample}{% + \VerbatimEnvironment + \catcode`\<=12\relax + \catcode`\"=9\relax + \begin{VerbatimOut}[commentchar=none,codes={\catcode`\"=12}]{\jobname.tmp}} + +\newcommand{\EndExample}{% + \end{VerbatimOut} + \fvset{gobble=0,fontsize=\small}} + +\newenvironment{example}{\BeginExample}{% + \EndExample + \LVerbatimInput{\jobname.tmp}% + \begin{center}\leavevmode\input{\jobname.tmp}\end{center}} + +\newenvironment{example*}{\BeginExample}{% + \EndExample\LVerbatimInput{\jobname.tmp}\input{\jobname.tmp}} + +\newenvironment{example**}{\BeginExample}{% + \EndExample\SideBySideEx{\input{\jobname.tmp}}} + +\newif\ifgrid +\newpsobject{usergrid}{psgrid}{subgriddiv=1,griddots=10,gridlabels=7pt} + +\def\MEx{\@ifnextchar[{\@MEx}{\@MEx[0,0]}} +\def\@MEx[#1,#2](#3,#4){% + \def\PictureSize{(#1,#2)(#3,#4)}% + \BeginExample} +\def\endMEx{% + \EndExample + \SideBySideEx{% + \expandafter\pspicture\PictureSize + \ifgrid\usergrid\fi\relax + \input{\jobname.tmp}% + \endpspicture}} + +\def\SideBySideEx#1{% + \trivlist\item[]% + \leavevmode\kern-\@totalleftmargin + \hbox{\valign{% + \vfil##\vfil\cr + \hbox to \z@{\hss#1}\cr + \hbox to \leftmargini{\hss}\cr + \@tempdimc=\textwidth + \advance\@tempdimc-\leftmargini + \advance\@tempdimc-\psframesep + \advance\@tempdimc-\psframesep + \advance\@tempdimc-\pslinewidth + \advance\@tempdimc-\pslinewidth + \hbox{\psframebox{\BVerbatimInput[frame=none,numbersep=2mm, + boxwidth=\@tempdimc]{\jobname.tmp}}}\cr}}% + \endtrivlist} + +\@namedef{MEx*}{\gridtrue\MEx} +\@namedef{endMEx*}{\endMEx} + +% `fancyvrb' modificatons to be able to handle number lines +% with the \BVerbatim environment and the \BVerbatimInput macro +% (DG - 11/04/98) + +% D.G. modification begin - Nov. 4, 1998 +%\def\FV@BProcessLine#1{\hbox{\FancyVerbFormatLine{#1}}} +\def\FV@BProcessLine#1{% +\hbox\ifx\FV@boxwidth\relax\else to\FV@boxwidth\fi{% +\FV@LeftListNumber +\FV@LeftListFrame +\FancyVerbFormatLine{#1}\hss +\FV@RightListFrame +\FV@RightListNumber}} +% D.G. modification end + +% To be able to handle number lines with \BUseVerbatim macro +% D.G. modification begin - Nov. 4, 1998 +%\def\BUseVerbatim{\FV@Command{}{BUseVerbatim}} +\def\BUseVerbatim{\FV@Command{}{BNumbersUseVerbatim}} + +\def\FVC@BNumbersUseVerbatim#1{\FV@CheckIfSaved{#1}{\FV@BNumbersUseVerbatim}} + +\def\FV@BNumbersUseVerbatim#1{\FV@BNumbersVerbatimBegin#1\FV@BVerbatimEnd} + +\def\FV@BNumbersVerbatimBegin{% + \begingroup + \FV@UseKeyValues + \FV@BeginVBox + \let\FV@ProcessLine\FV@BNumbersProcessLine + \FV@FormattingPrep + \FV@ObeyTabsInit}% + +\def\FV@BNumbersProcessLine#1{% +\global\advance\FV@CodeLineNo\@ne +\FV@StepLineNo +\FV@BProcessLine{#1}} +% D.G. modification end + +%%%%%%%%%%%%%%%%%%%% Logos %%%%%%%%%%%%%%%%%%%% + +\def\b@LaTeX{% + \begingroup + \csname reset@font\endcsname + \rmfamily\bfseries + L\kern-.32em + \raise.36ex\hbox{% + \ifx\@currsize\Huge\LARGE\else + \ifx\@currsize\huge\Large\else + \ifx\@currsize\LARGE\large\else + \ifx\@currsize\Large\normalsize\else + \ifx\@currsize\large\small\else + \ifx\@currsize\normalsize\footnotesize\else + \ifx\@currsize\small\scriptsize\else + \ifx\@currsize\footnotesize\scriptscriptsize + \fi\fi\fi\fi\fi\fi\fi\fi + \textbf{A}}% + \kern-.15em + T\kern-.1667em + \lower.7ex\hbox{E}\kern-.125em + X% + \endgroup} +\def\bLaTeX{\b@LaTeX} + +%DG \@ifundefined{AmSTeX} +%DG {\def\AmSTeX{\leavevmode\hbox{$\cal A\kern-.2em\lower.376ex% +%DG \hbox{$\cal M$}\kern-.2em\cal S$-\TeX}}}{} +\@ifundefined{BibTeX} + {\def\BibTeX{{\rmfamily B\kern-.05em{\sc i\kern-.025em b}\kern-.08em% + T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}}}{} +\@ifundefined{ConTeXt} + {\def\ConTeXt{{\rmfamily Con\TeX t}}}{} +%DG \@ifundefined{SliTeX} +%DG {\def\SliTeX{{\rmfamily S\kern-.06emL\kern-.18em\raise.32ex\hbox +%DG \textsc{i}\kern -.03em\TeX}}}{} +\@ifundefined{PlainTeX}{\def\PlainTeX{\textsc{Plain}\kern2pt\TeX}}{} + +%%%%%%%%%%%%%%%%%%%% Quick reference %%%%%%%%%%%%%%%%%%%% + +%% The macro definitions are stored in in the command sequence +%% \quickref as they appear in the text. This is much easier +%% than trying to output the stuff to an auxiliary file and having +%% to worry about catcodes. + +% An entry in \quickref is of the form: \qentry{type}{entry} +\def\quickref{} +\long\def\addtoquickref#1#2{% + \expandafter\gdef\expandafter\quickref\expandafter{% + \quickref\qentry{#1}{#2}}} +\def\qentry#1{\@nameuse{qr@#1}} + +\long\def\addtoquickref#1#2{} + +\def\MakeQuickRef{% + \long\def\addtoquickref##1##2{% + \wlog{}% + \toks@{\qentry{##1}{##2}}% + \message{\the\toks@}% + \wlog{}% + \let\MakeQuickRef\relax}} + +%% For switching into landscape mode for the Quick Reference: +\let\NormalShipout\shipout +\newbox\OutputBox +\def\LandscapeMode{% + \long\def\shipout##1##2{% + \setbox\OutputBox=\hbox{\rput[tl]{90}{\vbox{##2}}}% + \NormalShipout\box\OutputBox}% + \voffset 9in} + +% This makes the Quick Reference: +\def\QuickReference{% + \begin{Landscape}{\paperwidth}{\paperheight}{\rotateleft} + \oddsidemargin 0pt + \evensidemargin 0pt + \topmargin -.5in + \textheight 6.5in + \textwidth 9in + \columnsep 60pt + \footskip 0pt + \footheight 0pt + \headheight 15pt + \headsep 40pt + \parskip 4pt plus 1pt minus 1pt + \UsePageParameters + \twocolumn + \def\label##1{} + \subsechang=-.25in + \pagenumbering{Roman} + \pagestyle{quickref} + \MacroDefCodes + \let\Main\string + \let\MainFont\UsageFont + \MainFont + \quickref + \end{Landscape}} +\let\QuickReference\relax + +\def\ps@quickref{% + \def\@oddhead{% + \large\bfseries\sffamily + \hbox to .5\textwidth{PSTricks v\Version\hfill}% + \hbox to \z@{\hss Quick Reference\hss}% + \hbox to .5\textwidth{\hfill\thepage}} + \let\@evenhead\@oddhead + \def\@oddfoot{}\def\@evenfoot{}} + +% For page numbering in the QR: +\setbox\pst@boxg=\hbox{\UsageFont 99} +\newdimen\refnumdim +\refnumdim=\wd\pst@boxg +\def\refnum#1{\hbox to \refnumdim{\hss\rmfamily\bfseries\pageref{#1}}} + +% Section commands that add an entry to the QR: +\def\Section#1{\addtoquickref{section}{#1}\@checksec\section{#1}} +\def\Subsection#1{\addtoquickref{section}{#1}\subsection{#1}} + +% This is just an error checker: +\def\@checksec{% + \def\@tempa{document}% + \ifx\@tempa\@currenvir\else + \@latexerr{\string\Section\space occurred inside + \@currenvir\space environment}\@ehc + \expandafter\end\expandafter{\@currenvir}% + \expandafter\@checksec + \fi} + +% The qr@ definitions: +\def\qr@@object#1{\mbox{\begingroup\escapechar`\+% + \refnum{\string#1}\endgroup\hskip 1em\string#1}} +\def\qr@object#1{\qr@@object#1\par} +\def\qr@@param#1=#2\@nil{\refnum{\string#1}} +\def\qr@param#1{\leavevmode\hbox to\hsize{\qr@@param#1\@nil\hskip 1em#1}\par} +\def\qr@section#1{\subsection*{#1}} +\long\def\qr@center#1{\begin{center}#1\end{center}} + +%%%%%%%%%%%%%%%%%%%% Parts %%%%%%%%%%%%%%%%%%%% + +\font\bighelv=phvb at 88bp + +% Macro names changed for compatibility with `hyperref' (D.G. - 02/28/03) +\def\part{\clearpage\leavevmode\@ifstar{\part@ii}{\part@i}} +\def\part@i#1{% + \refstepcounter{part}% + \addcontentsline{toc}{part}{\protect\pnumberline{\thepart}#1}% + \lower 20pt\hbox to \z@{\hss{\bighelv\Roman{part}}\hskip 2em}% + \part@iii{#1}} +\def\part@ii#1{\addcontentsline{toc}{part}{#1}\part@iii{#1}} +\def\part@iii#1{% +\markright{#1}{\sffamily\Huge\bfseries#1}\par\vskip 2cm\@afterheading} +\def\thepart{\Roman{part}} +% Problem with `hyperref' (D.G. - 02/28/03) +%\def\pnumberline#1{\hbox to2cm{Part #1\hfill}} +\def\pnumberline#1{Part #1\hspace{1cm}} + +\def\l@part#1#2{% + \addpenalty{\@secpenalty}% + \addvspace{\lpartskip}% + \begingroup + \@tempdima 1em + \parindent \z@ \rightskip \@pnumwidth + \parfillskip -\@pnumwidth + {\large\bfseries\leavevmode#1\hfil \hbox to\@pnumwidth{\hss #2}}\par + \nobreak + \endgroup} +\newskip\lpartskip +\lpartskip 1.25em plus 1pt minus 1pt + +%%%%%%%%%%%%%%%%%%%% Parameter definitions and indexing %%%%%%%%%%%%%%%%%%%% + +% Like \MainEnvIndex, etc., but for parameters: +\def\MainParIndex{\SpecialIndex{parameter}{main}} +\def\UsageParIndex{\SpecialIndex{parameter}{usage}} + +% Like \MainPar, but for parameters. Can optionally include =foo. +\def\MainPar#1{\@MainPar#1==\@nil} +\def\@MainPar#1=#2=#3\@nil{% + \MainParIndex{#1}% + \label{#1}% + {\MainFont #1\ifx#3=\relax=\MetaFont#2\fi}} + +% Analogous to \n, but optionally argument can include =foo. +\def\p#1{\@p#1==\@nil} +\def\@p#1=#2=#3\@nil{% + \UsageParIndex{#1}% + {\UsageFont #1\ifx#3=\relax=#2\fi}} + +% For listing parameter definitions in a {description} environment: +\def\pitem[#1]{\@ifnextchar({\@pitem#1}{\@@pitem#1\@nil}} +\def\@pitem#1=#2(#3){% + \item[\MainFont#1=\MetaFont#2]% % Set the definition in \MainFont + \MainParIndex{#1}% + \label{#1}% + \addtoquickref{param}{#1={\MetaFont #2}\hfill {\rmfamily Default:} #3}% + \hfill {\MainFont {\rmfamily Default:} #3}\par} +\def\@@pitem#1=#2\@nil{% + \@ifundefined{default@#1}% + {\@warning{Parameter `#1' default not defined.}\@eha\@pitem#1=#2()} + {\@pitem#1=#2(\csname default@#1\endcsname)}} + +% Read in a list of defaults extracted from pstricks.doc: +\begingroup + \catcode`\@=12 + \catcode`\{=12 + \catcode`\}=12 + \catcode`\&=1 + \catcode`\^=2 + \def\psset@&% + \begingroup + \catcode`\\=12 + \pssetxx^ + \def\pssetxx#1{#2}&% + \expandafter\gdef\csname default@#1\endcsname^% + \endgroup^ + \csname @input\endcsname&defaults.pst^ +\endgroup + +% For putting parameter definitions in an Ex environment: +\def\Par#1{\@ifnextchar({\@Par#1}{\@@Par#1\@nil}} +\def\@Par#1=#2(#3){% + \leavevmode + \MainParIndex{#1}% + \label{#1}% + \addtoquickref{param}{#1={\MetaFont #2}\hfill {\rmfamily Default:} #3}% + \hbox to\linewidth{% + \MainFont #1={\MetaFont#2}\hfill {\rmfamily Default:} #3}\par} +\def\@@Par#1=#2\@nil{% + \@ifundefined{default@#1}% + {\@warning{Parameter `#1' default not defined.}\@Par#1=#2()} + {\@Par#1=#2(\csname default@#1\endcsname)}} + + +%%%%%%%%%%%%%%%%%%%% Macro definitions and indexing %%%%%%%%%%%%%%%%%%%% + +% There are four commands for listing macro definitions: +% 1. \mitem : List in a description environment +% 2. \oitem : Like \mitem, but optional *[par] automatically inserted. +% 3. \object : List in a description environment. +% 4. \Mac : Short for \begin{Ex}\object foo\end{Ex}. +% +% In each case: +% 1. definition is delimited only by end-of-line. +% 2. {}, () and [] are literal, with contents set in \MetaFont +% 3. = and , are literal. +% 4. `foo' is for optional arguments. +% 5. <foo> is meta, as usual. + +\begingroup + \catcode`\(=13 + \catcode`\,=13 + \catcode`\==13 + \gdef\MacroDefCodes{% + \@MD + \catcode`\(13 + \catcode`\^^M12 + \catcode`\`13 + \catcode`\,13 + \catcode`\!1 + \catcode`\@2 + \def~{}% + \def={{\fontshape{n}\selectfont\string=}}% + \def,{{\fontshape{n}\selectfont\string,}}% + \def(##1){\string({\MetaFont ##1})}} +\endgroup + +\begingroup + \catcode`\`=13 \gdef`#1'{{\OpArgFont #1}} +\endgroup + +\begingroup + \catcode`\^^M=12\relax% + \gdef\GetMacroDef#1{\begingroup\MacroDefCodes\@GetMacroDef{#1}}% + \gdef\@GetMacroDef#1#2^^M{#1{#2}\endgroup}% +\endgroup + +% For listing macro definitions in a "description" environment: +\def\mitem{\GetMacroDef\@mitem} +\def\@mitem#1{% + \item[{\MainFont\Main#1}]% + \addtoquickref{object}{#1}% + \leavevmode\par} + +% For listing graphics object definitions in a {description} environment: +% The optional *[par] is inserted automatically. +\def\oitem{\GetMacroDef\@oitem} +\def\@oitem#1{\@@oitem#1\@nil} +\def\@@oitem#1#2\@nil{\@mitem{#1{\OpArgFont*[{\MetaFont par}]}#2}} + +% For generic macro definition, usually to be put in a displayed env. +\def\object{\GetMacroDef\@object} +\def\@object#1{\addtoquickref{object}{#1}{\MainFont\Main#1\@@par}} + +% For a single displayed macro definition: +\def\Mac{\GetMacroDef\@Mac} +\def\@Mac#1{\begin{Ex}\@object{#1}\end{Ex}} + + +%% We must hack the generation of indexes modified by `hyperref' +%% to generate the \hyperpage macro by ourselves (D.G. - 02/28/03) +\def\@@wrindex#1|#2|#3\\{% + \ifx\\#2\\% + \protected@write\@indexfile{}{% +% D.G. modification begin - Feb. 28, 2003 +% \string\indexentry{#1|hyperpage}{\thepage}% + \string\indexentry{#1}{\thepage}% +% D.G. modification end + }% + \else + \def\Hy@temp@A{#2}% + \ifcase0\ifx\Hy@temp@A\HyInd@ParenLeft 1\fi + \ifx\Hy@temp@A\HyInd@ParenRight 1\fi + \relax + \protected@write\@indexfile{}{% + \string\indexentry{#1|#2}{\thepage}% + }% + \else + \protected@write\@indexfile{}{% + \string\indexentry{#1|#2hyperpage}{\thepage}% + }% + \fi + \fi + \endgroup + \@esphack +} + +%%%%%%%%%%%%%%%%%%%% Indexes %%%%%%%%%%%%%%%%%%%% + +\def\PrintUserIndex{% + \clearpage + \columnsep=20pt + \advance\oddsidemargin\sechang + \advance\evensidemargin\sechang + \advance\textwidth-\sechang + \sechang=0pt + \onecolumn + \@input{\jobname.ind}} + +%%%%%%%%%%%%%%%%%%%% Special indexing for User's Guides %%%%%%%%%%%%%%%%%%%% + +\@ifundefined{actualchar}{\def\actualchar{@}}{} +\@ifundefined{quotechar}{\def\quotechar{"}}{} +\@ifundefined{levelchar}{\def\levelchar{!}}{} +\@ifundefined{encapchar}{\def\encapchar{|}}{} +\@ifundefined{verbatimchar}{\def\verbatimchar{+}}{} + +%% These are the indexing commands: + +%% Commands: \MainIndex \UsageIndex +%% Environments: \MainEnvIndex \UsageEnvIndex +%% Style options: \MainOptionIndex \UsageOptionIndex +%% Counters: \MainCntIndex \UsageCntIndex + +\def\@Index#1{\@bsphack\index{#1}\@esphack} +\def\Index#1#2{% + \@bsphack + \index{\expandafter\@gobble\string#2\actualchar\string + \verb\quotechar*\verbatimchar\string#2\verbatimchar + \encapchar #1}} +{\catcode`\!=0 !catcode`!\=12!gdef!special@gobble#1{!if\#1!else#1!fi}} +\def\MainIndex{\Index{main}} +\def\UsageIndex{\Index{usage}} +\def\SpecialIndex#1#2#3{% + \@Index{#3\actualchar{\ttfamily #3} (#1)\encapchar #2}% + \@Index{#1s:\levelchar{\ttfamily #3}\encapchar #2}} +\def\MainEnvIndex{\SpecialIndex{environment}{main}} +\def\UsageEnvIndex{\SpecialIndex{environment}{usage}} +\def\MainOptionIndex{\SpecialIndex{option}{main}} +\def\UsageOptionIndex{\SpecialIndex{option}{usage}} +\def\MainCntIndex{\SpecialIndex{counter}{main}} +\def\UsageCntIndex{\SpecialIndex{counter}{usage}} + +%% Font for index page numbers: +%% We add hyperlinks (D.G. - 02/28/03) +\def\main#1{\textbf{\hyperpage{#1}}} +\def\usage#1{\hyperpage{#1}} + +%% These combine various functions: + +%% Commands: \Main \Usage +%% Environments: \MainEnv \UsageEnv +%% Style options: \MainOption \UsageOption +%% Counters: \MainCnt \UsageCnt + +%% The "Main" ones +%% * Index argument. +%% * Print argument with \MainFont +%% * Create label +foo, e+foo or o+foo. + +%% The "Usage" ones +%% * Index argument. +%% * Print argument with \UsageFont. + +\def\SpecialLabel#1#2+{\label{+#2}} +\def\LabelIndex#1{\MainIndex{#1}\expandafter\SpecialLabel\string#1+} +\def\Main#1{% + \MainIndex{#1}% + \expandafter\SpecialLabel\string#1+% + {\MainFont\string#1}} +\def\Usage#1{\UsageIndex{#1}{\UsageFont\string#1}} +\def\MainEnv#1{% + \MainEnvIndex{#1}% + \label{e+#1}% + {\MainFont #1}} +\def\UsageEnv#1{\UsageEnvIndex{#1}{\UsageFont #1}} +\def\MainOption#1{% + \MainOptionIndex{#1}% + \label{o+#1}% + {\MainFont #1}} +\def\UsageOption#1{\UsageOptionIndex{#1}{\UsageFont #1}} +\def\MainCnt#1{% + \MainCntIndex{#1}% + \label{c+#1}% + {\MainFont #1}} +\def\UsageCnt#1{\UsageCntIndex{#1}{\UsageFont #1}} + +%% These are abbreviations. +\def\N{\Main} +\def\n{\Usage} +\def\E{\MainEnv} +\def\e{\UsageEnv} +\def\O{\MainOption} +\def\o{\UsageOption} +\def\C{\MainCnt} +% D.G. modification begin - Mar. 4, 2003 +% The \c macro was already defined for coordinates +%\def\c{\UsageCnt} +% D.G. modification end + +%% User's guide and documented code have different index prologue. +\def\PrintUserIndex{{\let\ps@plain\@empty\@input{\jobname.ind}}} + +%% This is for listing commands in a description environment. +\def\xitem#1{\item[\Main{#1}]} + +\begingroup + \catcode`\<=1 \catcode`\>=2 + \catcode`\{=13 \catcode`\}=12 + \catcode`\[=13 + \gdef\@MD<% + \catcode`\{=13 \catcode`\}=12 \catcode`\[=13 + \def{##1}<\{<\MetaFont ##1\/>\}>% + \def[##1]<\string[<\MetaFont ##1\/>]>> +\endgroup +\def\MD{% + \NotNested + \Ex + \begingroup + \@MD + \def\end{\par\endgroup\end}% + \def\\{\@centercr\Main}% + \MainFont + \Main} +\def\endMD{\endEx} + +%%%%%%%%%%%%%%%%%%%% Framed warnings %%%%%%%%%%%%%%%%%%%% + +\newbox\bombbox +\setbox\bombbox=\hbox to\z@{% + \hss + \rput[r](-1.5cm,0){% + \psset{unit=7pt} + \begin{pspicture}(-4,-4)(4,4) + \pscircle[fillcolor=gray,fillstyle=solid]{4} + \rput{45}{\psscaleboxto(6,0){PS\kern-1pt}} + \psellipse*(0,3.8)(1,.2) + \psellipse*(0,5.5)(1,.2) + \psframe*(-1,3.8)(1,5.5) + \psbezier(0,5.5)(0,7)(1,8)(3.5,8) + \multido{\r=-0+40}{9}{\rput{\r}(3.5,8){\psline(0,0)(.4,0)}} + \end{pspicture}}} + +\def\Warning{% + \trivlist\item[] + \leavevmode\kern\@totalleftmargin + \valign\bgroup% + \vfil##\vfil\cr + \copy\bombbox\cr + \minipage{\textwidth} + \quote + \emph{Warning:}\hskip 1em + \ignorespaces} +\def\endWarning{\endquote\endminipage\cr\egroup\endtrivlist} + +\newbox\filebox +\setbox\filebox=\hbox{% + \pspicture(-1,-.5)(1,.7) + \pspolygon[linearc=2pt,shadow=true,shadowangle=45,xunit=1.1]% + (-1,-.55)(-1,.5)(-.8,.5)(-.8,.65)(-.2,.65)(-.2,.5)(1,.5)(1,-.55) + \endpspicture} +\def\File#1{% + \leavevmode + \marginpar{% + \leavevmode\lower 20pt\hbox{% + \hbox to0pt{\hbox to \linewidth{\hss\copy\filebox\hss}\hss}% + \raise 10pt\hbox to \linewidth{\hss\large\bfseries\sffamily #1\hss}}}% + \ignorespaces} + + +%%%%%%%%%%%%%%%%%%%% Miscellaneous %%%%%%%%%%%%%%%%%%%% + +% Driver notes: +\def\drivers{\noindent\small Driver notes:\hskip 1em\ignorespaces} + +\endinput + +%% END pst-user.cls diff --git a/Master/texmf-dist/doc/generic/pstricks/pst-user.ist b/Master/texmf-dist/doc/generic/pstricks/pst-user.ist new file mode 100644 index 00000000000..a00718a2e08 --- /dev/null +++ b/Master/texmf-dist/doc/generic/pstricks/pst-user.ist @@ -0,0 +1,7 @@ +% headings_flag 1 +% heading_prefix "{\\Large\\textbf{Letter}" +% heading_suffix "}" + +delim_0 " \\dotfill \ " +delim_1 " \\dotfill \ " +delim_2 " \\dotfill \ " diff --git a/Master/texmf-dist/doc/generic/pstricks/pst-user.tex b/Master/texmf-dist/doc/generic/pstricks/pst-user.tex new file mode 100644 index 00000000000..08ef5b2bc5b --- /dev/null +++ b/Master/texmf-dist/doc/generic/pstricks/pst-user.tex @@ -0,0 +1,87 @@ +%% BEGIN pst-user.tex +%% +%% LaTeX file pst-user.tex. Source for the PSTricks User's Guide. +%% +%% COPYRIGHT 1993-2003, by Timothy Van Zandt, tvz@econ.insead.fr +%% COPYRIGHT 2008, by Herbert Voss, voss@pstricks.de +%% +%% This program can be redistributed and/or modified under the terms +%% of the Artistic License. +%% A copy of that license is included in the file artistic.txt. +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% +%% Under normal circumstances, you do not need to LaTeX this file because +%% the User's Guide is distributed with the PSTricks package, already +%% typeset and converted to PDF in the file pst-user.pdf. +%% +%% If you do need/want to run it again, here is what to do: +%% +%% * You must have installed the PSTricks package. +%% +%% * You must have the LaTeX packages `fancybox', `fancyvrb', `geometry', +%% `hyperref' and the file "pst-user.cls" which is the document class +%% to format this documentation. +%% +%% * An index, pst-user.ind, is also distributed with PSTricks. You +%% can use makeindex, without any special styles, to remake the index. +%% +%% * Style options: +%% a4paper : For A4 paper. +%% twoside : For two-sided printing. +%% 2up : For two-up printing. +%% makeindex : Create a new idx file for making an index. +%% (it is not necessary to remake the index, +%% if you make no other changes.) +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\listfiles + +%\documentclass[a4paper]{pst-user} +%\documentclass[11pt,makeindex]{pst-user} +\documentclass[11pt]{pst-user} + +\def\Date{07/12/10} +\def\Version{1.5} + +\includeonly{% + psd-cove,% + psd-esse,% + psd-basi,% + psd-para,% + psd-cust,% + psd-pict,% + psd-text,% + psd-node,% + psd-tree,% + psd-fill,% + psd-3d,% + psd-spec,% + psd-help% +} + +\makeindex % Comment it to do regenerate the index + +\begin{document} + +\include{psd-cove} % Cover page; Table of Contents +\include{psd-esse} % Welcome to PSTricks; The essentials +\include{psd-basi} % Basic graphics objects +\include{psd-para} % More graphics parameters +\include{psd-cust} % Custom graphics +\include{psd-pict} % Picture tools +\include{psd-text} % Text tricks +\include{psd-node} % Nodes and node connections +\include{psd-tree} % Trees +\include{psd-fill} % Filling and tilings +\include{psd-3d} % 3d graphics +\include{psd-spec} % Special Tricks +\include{psd-help} % Help (appendix) + +\PrintUserIndex % Comment out to suppress index +\QuickReference % Comment out to suppress quick reference + +\end{document} + +%% END pst-user.tex diff --git a/Master/texmf-dist/doc/generic/pstricks/pst-user.tgz b/Master/texmf-dist/doc/generic/pstricks/pst-user.tgz Binary files differdeleted file mode 100644 index f234c090838..00000000000 --- a/Master/texmf-dist/doc/generic/pstricks/pst-user.tgz +++ /dev/null |