summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/generic/pstricks/psd-pict.tex
diff options
context:
space:
mode:
authorManuel Pégourié-Gonnard <mpg@elzevir.fr>2008-06-21 14:42:14 +0000
committerManuel Pégourié-Gonnard <mpg@elzevir.fr>2008-06-21 14:42:14 +0000
commit836f497d5ba479fdc19164951941f051cdd804d0 (patch)
treef90cd5cb3cf497aea05d961315c26bad32ac7471 /Master/texmf-dist/source/generic/pstricks/psd-pict.tex
parent4683bcefcc8e380dda5f46ff09833a4b9b7f7804 (diff)
pstricks update
git-svn-id: svn://tug.org/texlive/trunk@8901 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/generic/pstricks/psd-pict.tex')
-rw-r--r--Master/texmf-dist/source/generic/pstricks/psd-pict.tex500
1 files changed, 500 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/generic/pstricks/psd-pict.tex b/Master/texmf-dist/source/generic/pstricks/psd-pict.tex
new file mode 100644
index 00000000000..59fa301d2dd
--- /dev/null
+++ b/Master/texmf-dist/source/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