pst-2dplot update 2008/12/29

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

1 files changed, 299 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/generic/pst-2dplot/pst-2dplot-doc.tex b/Master/texmf-dist/doc/generic/pst-2dplot/pst-2dplot-doc.tex
new file mode 100644
index 00000000000..3a6b9724748
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pst-2dplot/pst-2dplot-doc.tex
@@ -0,0 +1,299 @@
+%%====================================
+%% This is help file for pst-2dplot
+%% Farshid Delgosha
+%% 12/23/2008
+%%====================================
+
+\documentclass[10pt]{article}
+
+\usepackage[T1]{fontenc}
+\usepackage[latin1]{inputenc}
+\usepackage[cmex10]{amsmath}
+\usepackage[table]{xcolor}
+\usepackage{xspace}
+\usepackage{array}
+\usepackage[bf,labelsep=period]{caption}
+\usepackage[margin=1in,dvips,includemp,reversemp,marginparwidth=.85in,marginparsep=0in]{geometry}
+\usepackage{pst-2dplot}
+\usepackage{pst-node}
+\usepackage{showexpl}
+\lstset{explpreset={numbers=left,numberstyle=\tiny,numbersep=.5em},width=6cm,%
+basicstyle=\ttfamily\footnotesize,rframe=,frame=single,backgroundcolor=\color{orange!30}}
+
+\setlength{\parskip}{.5\baselineskip}
+
+%%=== new macros ====================================================
+\def\package{\texttt{pst-2dplot}\xspace}
+\def\CMD#1{{\ttfamily\textbackslash #1}}
+\def\xyCoor#1{\texttt{($x_{#1}$,$y_{#1}$)}}
+\def\margintext#1{\marginpar{\texttt{\small#1}}}
+%
+\newenvironment{syntax}{%
+\begin{tabbing}%
+\hspace{2cm}\=\hspace{1cm}\=\hspace{1cm}\=\kill%
+}
+{\end{tabbing}}
+%
+\def\xdashline(#1,#2)#3#4{%
+\psset{linecolor=#3}%
+\psline[linestyle=dashed](0,-#2)(#1,-#2)%
+\rput(#1,0){\psline[arrows=|<-](0,0)(0,.5)}%
+\rput(#1,-#2){\psline[arrows=|<-](0,0)(0,-.5)}%
+\rput[l]{90}(#1,.65){\textcolor{#3}{\texttt{#4}}}%
+}
+%
+\def\ydashline(#1,#2)#3#4{%
+\psset{linecolor=#3}%
+\psline[linestyle=dashed](-#1,0)(-#1,#2)%
+\rput(0,#2){\psline[arrows=|<-](0,0)(.5,0)}%
+\rput(-#1,#2){\psline[arrows=|<-](0,0)(-.5,0)}%
+\rput[l](.65,#2){\textcolor{#3}{\texttt{#4}}}%
+}
+%%===================================================================
+
+
+
+%%=== data files ====================================================
+\begin{filecontents*}{data1.dat}
+[0.0]   [0.0]
+[0.1]   [0.1]
+[0.2]   [0.1]
+[0.3]   [0.2]
+[0.4]   [0.2]
+[0.5]   [0.4]
+[0.6]   [0.5]
+[0.7]   [0.8]
+[0.8]   [0.9]
+[0.9]   [1.0]
+[1.0]   [0.2]
+\end{filecontents*}
+
+\begin{filecontents*}{data2.dat}
+[0.0]   [0.8]
+[0.1]   [0.9]
+[0.2]   [1.0]
+[0.3]   [0.8]
+[0.4]   [0.7]
+[0.5]   [0.5]
+[0.6]   [0.3]
+[0.7]   [0.2]
+[0.8]   [0.1]
+[0.9]   [0.2]
+[1.0]   [0.3]
+\end{filecontents*}
+
+\begin{filecontents*}{data3.dat}
+[0.0]   [1.0000000]
+[0.1]   [0.6909830]
+[0.2]   [0.4122150]
+[0.3]   [0.1909830]
+[0.4]   [0.0489435]
+[0.5]   [0.0000000]
+[0.6]   [0.0489435]
+[0.7]   [0.1909830]
+[0.8]   [0.4122150]
+[0.9]   [0.6909830]
+[1.0]   [1.0000000]
+[1.1]   [1.3090200]
+[1.2]   [1.5877900]
+[1.3]   [1.8090200]
+[1.4]   [1.9510600]
+[1.5]   [2.0000000]
+[1.6]   [1.9510600]
+[1.7]   [1.8090200]
+[1.8]   [1.5877900]
+[1.9]   [1.3090200]
+[2.0]   [1.0000000]
+\end{filecontents*}
+%%===================================================================
+
+
+
+
+\title{The \package Package \\ {\large (version 1.5)}}
+\author{Farshid Delgosha \\ \texttt{fdelgosha@gmail.com}}
+\date{26 December, 2008}
+
+
+
+
+\begin{document}
+
+\maketitle
+
+
+
+
+\section{Introduction}
+
+This document introduces the package \package that is an easy-to-use and intuitive tool for drawing two-dimensional plots in \LaTeX{} documents. The main environment introduced by \package is \texttt{pstgraph} that draws grid lines, tag numbers, and labels on both axes. I have to mention that there are more features that I am planning to add. Nevertheless, I felt that the current version is still useful.
+
+To use this package, add the following command to the preamble of your document.
+\begin{syntax}
+\>\CMD{usepackage\{pst-2dplot\}}
+\end{syntax}
+
+The syntax of the \texttt{pstgreaph} \margintext{pstgraph} environment is as follows.
+\begin{syntax}
+\>\CMD{begin\{pstgraph\}[\textrm{\textit{key}=\textit{value}}]\xyCoor{0}} \\
+\>\>$\vdots$ \\
+\>\CMD{end\{pstgraph\}}
+\end{syntax}
+As depicted in Figure~\ref{fig:pstgraph}, the \texttt{pstgraph} environment draws a box of side lengths $x_0$ and $y_0$.
+%%===============================================================================
+\begin{figure}[ht!]
+\centering
+\psset{xunit=1.25cm,yunit=8mm}
+\begin{pspicture}[showgrid=false](-2,-2)(5.5,6)
+%
+\multido{\nx=0+1,\rl=0+.25}{5}{%
+\rput(\nx,0){\psline[linecolor=gray](0,-.25)(0,4)}%
+\rput[t](\nx,-.75){$\rl$}}
+%
+\multido{\ny=0+1,\rl=0+.25}{5}{%
+\rput(0,\ny){\psline[linecolor=gray](-.25,0)(4,0)}%
+\rput[r](-.75,\ny){$\rl$}}
+%
+\psframe(0,0)(4,4)
+%
+\rput[t](2,-1.65){\textit{x label}}
+\rput[b]{90}(-1.75,2){\textit{y label}}
+%
+\dotnode[linecolor=red](0,0){org}
+\dotnode[linecolor=red](4,4){xy0}
+\nput{225}{org}{\textcolor{red}{$(0,0)$}}
+\nput{45}{xy0}{\textcolor{red}{$(x_0,y_0)$}}
+%
+\psset{linewidth=.6pt,arrowinset=.25,arrowsize=.125}
+\xdashline(4.35,.25){blue}{xticksize}
+\xdashline(4.7,.75){orange}{xtagsep}
+\xdashline(5.05,1.65){teal}{xlabelsep}
+%
+\ydashline(.25,4.4){blue}{yticksize}
+\ydashline(.75,5){orange}{ytagsep}
+\ydashline(1.75,5.6){teal}{ylabelsep}
+%
+\psset{linecolor=red,linestyle=dashed,arrows=<->}
+\psline(0,1.5)(4,1.5)
+\rput*(1.5,1.5){\textcolor{red}{$x_0$}}
+\psline(2.5,0)(2.5,4)
+\rput*(2.5,2.5){\textcolor{red}{$y_0$}}
+%
+\end{pspicture}
+%
+\caption{\texttt{pstgraph} environment}
+\label{fig:pstgraph}
+\end{figure}
+%%===============================================================================
+The coordinates of the lower left corner and upper right corner of the box are $(0,0)$ and $(x_0,y_0)$, respectively. Keys of the \texttt{pstgraph} environment can be set either directly or through the \CMD{setpstgraph} \margintext{setpstgraph} macro with the following syntax.
+\begin{syntax}
+\>\CMD{setpstgraph\{\textrm{$key_1$=$value_1,key_2$=$value_2, \dotsc$}\}}
+\end{syntax}
+This macro must be used outside the \texttt{pstgraph} environment for the keys to take effect. The keys defined by the \texttt{pstgraph} environment are summarized in Table~\ref{tab:keys}.
+
+%%===============================================================================
+\rowcolors{1}{}{gray!30}
+\begin{table}[b!]
+\centering
+\caption{\texttt{pstgraph} keys}
+\label{tab:keys}
+\begin{tabular}{>{\ttfamily}l  >{\itshape}c  c  p{2.6in}}
+\hline
+\textit{Key}  &  \textit{Value}  &  \textit{Default}  &  \textit{Description} \\
+\hline
+xmin        &  num     &  $0$                &  Minimum data value on the $x$ axis \\
+xmax        &  num     &  $1$                &  Maximum data value on the $x$ axis \\
+ymin        &  num     &  $0$                &  Minimum data value on the $y$ axis \\
+ymax        &  num     &  $1$                &  Maximum data value on the $y$ axis \\
+xgriddiv    &  num     &  $1$                &  Number of vertical grid lines \\
+ygriddiv    &  num     &  $1$                &  Number of horizontal grid lines \\
+gridstyle   &  style   &  solid              &  Style of grid lines \\
+gridcolor   &  color   &  gray               &  Color of grid lines \\
+gridwidth   &  dimen   &  0.5pt              &  Width of grid lines \\
+xticksize   &  num     &  $0.1$              &  Length of vertical tick lines \\
+yticksize   &  num     &  $0.1$              &  Length of horizontal tick lines \\
+xtagsep     &  num     &  $0.2$              &  Distance of horizontal tags from the $x$ axis \\
+ytagsep     &  num     &  $0.2$              &  Distance of the vertical tags from the $y$ axis \\
+xtagformat  &  format  &  \CMD{scriptstyle}  &  Format of horizontal tags \\
+ytagformat  &  format  &  \CMD{scriptstyle}  &  Format of vertical tags \\
+xlabel      &  text    &  $-$                &  Label of the $x$ axis \\
+ylabel      &  text    &  $-$                &  Label of the $y$ axis \\
+xlabelsep   &  num     &  $0.55$             &  Distance of the $x$ label from the $x$ axis \\
+ylabelsep   &  num     &  $0.75$             &  Distance of the $y$ label from the $y$ axis \\
+framewidth  &  dimen   &  1pt                &  Width of the frame \\
+framecolor  &  color   &  black              &  Color of the frame \\
+\hline
+\end{tabular}
+\end{table}
+\rowcolors{1}{}{}
+%%===============================================================================
+The labels of the $x$ and $y$ axes can be set either directly or through the \CMD{pstlabel} \margintext{pstlabel} macro, which has the following syntax.
+\begin{syntax}
+\>\CMD{pstlabel}\{\textit{x-label}\}\{\textit{y-label}\}
+\end{syntax}
+This macro can be used either inside or outside the \texttt{pstgraph} environment.
+
+The last macro defined by the \package is \CMD{pstfileplot} \margintext{pstfileplot} that is used to draw the data in the file \textit{data-file}. The syntax of this macro is as follows.
+\begin{syntax}
+\>\CMD{pstfileplot[\textrm{\textit{key}=\textit{value}}]\{{\rmfamily\itshape data-file}\}}
+\end{syntax}
+Assuming $(x_0,y_0), (x_1,y_1), (x_2,y_2), \dotsc$ are the points on a curve to be plotted, the data file \textit{data-file} must have the following format.
+\[
+\begin{array}{cc}
+{[x_0]}   &  {[y_0]} \\
+{[x_1]}   &  {[y_1]} \\
+{[x_2]}   &  {[y_2]} \\
+\vdots    &  \vdots
+\end{array}
+\]
+The use of brackets around every data value is optional; however, its usage enhances reading the data from the file. The plotted curve is obtained by connecting every point $(x_i, y_i)$ to $(x_{i+1}, y_{i+1})$ by a straight line segment for all $i = 0, 1, 2, \dotsc$. \emph{It is important to notice that all data values in the data file must be nonnegative; otherwise, unexpected results will occur.} Assume $x_{min} \leq x_i \leq x_{max}$ and $y_{min} \leq y_i \leq y_{max}$ for all $i = 0, 1, 2, \dotsc$. If either $x_{min} < 0$ or $y_{min} < 0$, I suggest the following solution. Generate the data file as follows.
+\[
+\begin{array}{cc}
+{[x_0 - x_{min}]}  &  {[y_0 - y_{min}]} \\
+{[x_1 - x_{min}]}  &  {[y_1 - y_{min}]} \\
+{[x_2 - x_{min}]}  &  {[y_2 - y_{min}]} \\
+\vdots  &  \vdots
+\end{array}
+\]
+Then, set \texttt{xmin}=$x_{min}$, \texttt{xmax}=$x_{max}$, \texttt{ymin}=$y_{min}$, and \texttt{ymax}=$y_{max}$. This solution works because the portions of \texttt{pstgraph} and \CMD{pstfileplot} codes responsible for scaling and drawing the curve depend only on the differences $\mathtt{xmax} - \mathtt{xmin}$ and $\mathtt{ymax} - \mathtt{ymin}$. This solution is, in fact, equivalent to moving the origin of the $xy$-plane to the point $(x_{min}, y_{min})$. I am working on automating this process.
+
+
+
+
+\section{Examples}
+
+In this section, we review some examples.
+
+\begin{LTXexample}
+\begin{pstgraph}(4,3)
+  \psset{linewidth=1.5pt}
+  \pstfileplot[linecolor=purple]{data1.dat}
+  \pstfileplot[linecolor=teal]{data2.dat}
+\end{pstgraph}
+\end{LTXexample}
+
+
+\begin{LTXexample}
+\setpstgraph{gridstyle=dashed,%
+gridwidth=.2pt,framecolor=orange!60!black}
+\begin{pstgraph}[xgriddiv=4,ygriddiv=2](4,3)
+  \psset{linewidth=1.5pt}
+  \pstfileplot[linecolor=purple]{data1.dat}
+  \pstfileplot[linecolor=teal]{data2.dat}
+  \pstlabel{$x$ axis}{$y$ axis}
+\end{pstgraph}
+\end{LTXexample}
+
+Now, assume we would like to plot the curve of $f(x) = \sin(\pi x)$ from $x = -1$ to $x = 1$. First, we generate a data file containing the points of the curve $y = \sin(\pi(x - 1)) + 1$ in which $x$ varies from $0$ to $2$. Notice that the coordinates of all points are nonnegative. Assuming the data file is \texttt{data3.dat}, we plot the curve as follows.
+\begin{LTXexample}
+\setpstgraph{xmin=-1,xmax=1,ymin=-1,ymax=1,%
+xgriddiv=4,ygriddiv=2}
+\begin{pstgraph}(4,3)
+  \psset{linewidth=1.5pt}
+  \pstfileplot[linecolor=purple]{data3.dat}
+  \pstlabel{$x$}{$\sin(\pi x)$}
+\end{pstgraph}
+\end{LTXexample}
+
+
+\end{document} 
\ No newline at end of file