pst-plot (1may11)

git-svn-id: svn://tug.org/texlive/trunk@22268 c570f23f-e606-0410-a88d-b1316a301751

3 files changed, 191 insertions, 13 deletions

diff --git a/Master/texmf-dist/doc/generic/pst-plot/pst-plot-doc.pdf b/Master/texmf-dist/doc/generic/pst-plot/pst-plot-doc.pdf
index 8ec3ca043f4..91cf45493c8 100644
--- a/Master/texmf-dist/doc/generic/pst-plot/pst-plot-doc.pdf
+++ b/Master/texmf-dist/doc/generic/pst-plot/pst-plot-doc.pdf
diff --git a/Master/texmf-dist/doc/generic/pst-plot/pst-plot-doc.tex b/Master/texmf-dist/doc/generic/pst-plot/pst-plot-doc.tex
index cb4777742ba..3a772db8548 100644
--- a/Master/texmf-dist/doc/generic/pst-plot/pst-plot-doc.tex
+++ b/Master/texmf-dist/doc/generic/pst-plot/pst-plot-doc.tex
@@ -68,13 +68,191 @@ Arnaud Schmittbuhl
 
 \clearpage
 \part{Basic commands, connections and labels}
+\section{Introduction}
+The plotting commands described in this part are defined in the very first version
+of \LPack{pst-plot.tex} and available for all new and ancient versions.
+
+The \Lcs{psdots}, \Lcs{psline}, \Lcs{pspolygon}, \Lcs{pscurve}, \Lcs{psecurve} and
+\Lcs{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 \CAny.
+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
+ \Lkeyset{plotstyle=style}
+determines what kind of plot you get. Valid styles are \Lkeyval{dots}, \Lkeyval{line},
+\Lkeyval{polygon}, \Lkeyval{curve}, \Lkeyval{ecurve}, \Lkeyval{ccurve}. E\,,g., if the \Lkeyword{plotstyle} is
+\Lkeyval{polygon}, then the macro becomes a variant of the \Lcs{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 \Lkeyword{arrows}
+parameter instead.
+
+No\XInfoDanger{~} 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 \Lkeyval{line}, \Lkeyval{polygon} or \Lkeyval{dots} plot style, with \LKeyword{showpoints=false},
+\LKeyset{linearc=0pt}, and no arrows.
+
+Note that the lists of data generated or used by the plot commands cannot
+contain units. The values of \Lcs{psxunit} and \Lcs{psyunit} are used as the unit.
+
+
+\section{Plotting data records}
+
+\begin{BDef}
+ \Lcs{fileplot}\OptArgs\Largb{file}\\
+ \Lcs{psfileplot}\OptArgs\Largb{file}\\
+ \Lcs{dataplot}\OptArgs\Largb{\Lcs{\Larga{macro}}}\\
+ \Lcs{psdataplot}\OptArgs\Largb{\Lcs{\Larga{macro}}}\\
+ \Lcs{savedata}\Largb{\Lcs{\Larga{macro}}}\Largs{data}\\
+ \Lcs{readdata}\Largb{\Lcs{\Larga{macro}}}\Largb{file}\\
+ \Lcs{listplot}\Largb{data}\\
+ \Lcs{pslistplot}\Largb{data}
+\end{BDef}
+The macros with a preceeding \verb|ps| are equivalent to those without.
+
+\Lcs{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 \verb|{ }|, parentheses \verb|( )|, commas, and/or white space. Bracketing
+all the data with square brackets \verb|[ ]| 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 \verb|[| \emph{must} go at the
+beginning of a line.) The file should not contain anything else (not even
+\Lcs{endinput}), except for comments marked with \verb|%|.
+
+\Lcs{fileplot} only recognizes the \Lkeyval{line}, \Lkeyval{polygon} and \Lkeyval{dots} plot styles, and
+it ignores the \Lkeyword{arrows}, \Lkeyword{linearc} and \Lkeyword{showpoints} parameters. The
+\Lcs{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 \Lcs{fileplot}.
+
+If you find that it takes \TeX{} a long time to process your \Lcs{fileplot}
+command, you may want to use the \Lcs{PSTtoEPS} command described on page
+\pageref{+PSTtoEPS}. This will also reduce \TeX's memory requirements.
+
+\Lcs{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:
+\Larg{data} or the data in \Larg{file} should conform to the rules described above for
+the data in \Lcs{fileplot} (with \Lcs{savedata}, the data must be delimited by
+\verb|[ ]|, and with \Lcs{readdata}, bracketing the data with \verb|[ ]| speeds things
+up). You can concatenate and reuse lists, as in
+\begin{lstlisting}[style=syntax]
+\readdata{\foo}{foo.data}
+\readdata{\bar}{bar.data}
+\dataplot{\foo\bar}
+\dataplot[origin={0,1}]{\bar}
+\end{lstlisting}
+
+The \Lcs{readdata} and \Lcs{dataplot} combination is faster than \Lcs{fileplot}
+if you reuse the data. \Lcs{fileplot} uses less of \TeX's memory than
+\Lcs{readdata} and \Lcs{dataplot} if you are also use \Lcs{PSTtoEPS}.
+
+Here is a plot of $\int\sin(x)\mathrm{d}x$. The data was generated by Mathematica,
+with
+\begin{lstlisting}
+  Table[{x,N[SinIntegral[x]]},{x,0,20}]
+\end{lstlisting}
+and then copied to this document.
+\begin{LTXexample}[pos=t]
+\pspicture(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,dotstyle=triangle]{\mydata}
+  \psline{<->}(0,2)(0,0)(22,0)
+\endpspicture
+\end{LTXexample}
+
+\Lcs{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.
+\Larg{list} is first expanded by \TeX{} and then by PostScript. This means that
+\Larg{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 \Lcs{readdata} and
+\Lcs{dataplot}. However, when using the \Lkeyval{line}, \Lkeyval{polygon} or \Lkeyval{dots} plotstyles
+with \LKeyset{showpoints=false}, \LKeyset{linearc=0pt} and no arrows, \Lcs{dataplot} is much
+less likely than \Lcs{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 \Lcs{listplot} is used:
+\begin{lstlisting}[style=syntax]
+  ...
+\listplot[plotstyle=curve,showpoints=true,dotstyle=triangle]{\mydata}
+  ...
+\end{lstlisting}
+
+\section{Plotting mathematical functions}
+
+
+\begin{BDef}
+\Lcs{psplot}\OptArgs\Largb{$x_!\min@$}\Largb{$x_!\max@$}\Largb{function}\\
+\Lcs{parametricplot}\OptArgs\Largb{$t_!\min@$}\Largb{$t_!\max@$}\Largb{x(t) y(t)}
+\end{BDef}
+
+  \Lcs{psplot} can be used to plot a function $f(x)$, if you know a little
+PostScript.  \Larg{function} should be the PostScript or algebraic code for calculating $f(x)$.
+Note that you must use $x$ as the dependent variable. 
+\begin{lstlisting}
+  \psplot[plotpoints=200]{0}{720}{x sin}
+\end{lstlisting}
+plots $\sin(x)$ from 0 to 720 degrees, by calculating $\sin(x)$ roughly every
+3.6 degrees and then connecting the points with \Lcs{psline}. Here are plots of
+$\sin(x)\cos((x/2)^2)$ and $\sin^2(x)$:
+\begin{LTXexample}[pos=t]
+\pspicture(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)
+\endpspicture
+\end{LTXexample}
+
+\Lcs{parametricplot} is for a parametric plot of $(x(t),y(t))$. \Larg{function} is the PostScript
+code or algebraic expression for calculating the pair $x(t)$ $y(t)$.
+
+For example,
+\begin{LTXexample}[wide,width=4cm]
+\pspicture(3,3)
+\parametricplot[plotstyle=dots,plotpoints=13]%
+    {-6}{6}{1.2 t exp 1.2 t neg exp}
+\endpspicture
+\end{LTXexample}
+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{LTXexample}[wide,width=4cm]
+\pspicture(-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)
+\endpspicture
+\end{LTXexample}
+
+
+The number of points that the \Lcs{psplot} and \Lcs{parametricplot} commands
+calculate is set by the
+  \LKeyset{plotpoints=<value>}
+parameter. Using "curve" or its variants instead of "line" and increasing the
+value of \Lkeyword{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 \Lcs{psplot} and \Lcs{parametricplot}, Mathematica
+increases the sampling frequency on sections of the curve with greater
+fluctuation.
+
 
-\clearpage
-\setcounter{page}{9}
 \part{New commands}
 %--------------------------------------------------------------------------------------
 
-\clearpage
 \section[Extended syntax]{Extended syntax for \nxLcs{psplot}, \nxLcs{psparametricplot}, and \nxLcs{psaxes}}
 There is now a new optional argument for \Lcs{psplot} and \Lcs{psparametricplot} to pass
 additional \PS commands into the code. This makes the use of \Lcs{pstVerb} in 
diff --git a/Master/texmf-dist/source/generic/pst-plot/Makefile b/Master/texmf-dist/source/generic/pst-plot/Makefile
index 1d645655dc6..50bf5814308 100644
--- a/Master/texmf-dist/source/generic/pst-plot/Makefile
+++ b/Master/texmf-dist/source/generic/pst-plot/Makefile
@@ -20,16 +20,16 @@ all : doc clean tds
 doc: $(MAIN).pdf
 
 $(MAIN).pdf : $(MAIN).ps
-	GS_OPTIONS=-dAutoRotatePages=/None ps2pdf $<
-	echo "\documentclass[a4paper]{article}" > temp.tex
-	echo "\usepackage{pdfpages}" >> temp.tex
-	echo "\begin{document}" >> temp.tex
-	echo "\includepdf[pages=1-5]{pst-plot-doc}" >> temp.tex
-	echo "\includepdf[pages=25-29]{../pstricks/doc/pstricks-doc}" >> temp.tex
-	echo "\includepdf[pages=6-]{pst-plot-doc}" >> temp.tex
-	echo "\end{document}" >> temp.tex
-	pdflatex temp
-	mv temp.pdf pst-plot-doc.pdf
+	GS_OPTIONS="-dAutoRotatePages=/None -dNoSafer" ps2pdf $<
+#	echo "\documentclass[a4paper]{article}" > temp.tex
+#	echo "\usepackage{pdfpages}" >> temp.tex
+#	echo "\begin{document}" >> temp.tex
+#	echo "\includepdf[pages=1-5]{pst-plot-doc}" >> temp.tex
+#	echo "\includepdf[pages=25-29]{../pstricks/doc/pstricks-doc}" >> temp.tex
+#	echo "\includepdf[pages=6-]{pst-plot-doc}" >> temp.tex
+#	echo "\end{document}" >> temp.tex
+#	pdflatex temp
+#	mv temp.pdf pst-plot-doc.pdf
 
 $(MAIN).ps : $(MAIN).dvi
 	dvips $<