| Current File : //usr/share/texlive/texmf-dist/doc/generic/pst-tools/pst-tools-doc.tex |
%% $Id: pst-tools-doc.tex 1163 2020-03-24 09:47:58Z herbert $
\documentclass[11pt,english,BCOR=10mm,DIV=13,toc=bibliography,parskip=false,
headings=small,headinclude=false,footinclude=false,oneside]{pst-doc}
\usepackage[utf8]{inputenc}
\usepackage{pst-tools}
\let\pstToolsFV\fileversion
\usepackage{xltabular}
\usepackage{pst-plot}
\renewcommand\bgImage{}
\lstset{language=PSTricks,
morekeywords={psPrintValue},basicstyle=\footnotesize\ttfamily}
%
\usepackage{biblatex}
\addbibresource{pst-tools-doc.bib}
\begin{document}
\title{\texttt{pst-tools}}
\subtitle{Helper functions; v.\pstToolsFV}
\author{Herbert Voß}
\docauthor{}
\date{\today}
\maketitle
\begin{abstract}
This package defines some tools which are useful for all packages not only the PSTricks like packages.
Since the version 0.10 it includes the macros from \texttt{random.tex}.
\vfill
\noindent
Thanks to:
Rolf Niepraschk;
\end{abstract}
\newpage
\tableofcontents
\psset{unit=1cm}
\section{Predefined styles}
The style \Lkeyword{mmpaper} is defined for \Lcs{psgrid}:
%\newpsstyle{mmpaper}{subgriddiv=5,gridlabels=0,gridwidth=1pt,gridcolor=orange,subgridwidth=0.1pt,subgridcolor=orange!90}
\begin{LTXexample}[width=0.5\linewidth,frame=,pos=r]
\begin{pspicture}(6,3)
\psgrid[style=mmpaper](6,3)
\end{pspicture}
\begin{pspicture}(6,3)
\psgrid[style=mmpaper,
gridcolor=blue,subgridcolor=blue!80](6,3)
\end{pspicture}
\end{LTXexample}
\section{\Lcs{psPrintValue}}\label{sec:printValue}
This macro allows to \Index{print} single values of a math function. It has the syntax
\begin{BDef}
\Lcs{psPrintValue}\OptArgs\Largb{PostScript code}\\
\Lcs{psPrintValue}\OptArg{algebraic,\ldots}\Largb{x value, algebraic code}
\end{BDef}
Important is the fact, that \Lcs{psPrintValue} works on \PS\ side. For \TeX\ it is only a box of
zero dimension. This is the reason why you have to put it into a box, which reserves horizontal
space.
There are the following valid options for \Lcs{psPrintValue}:
\noindent\medskip
\begin{xltabular}{\linewidth}{@{}l|>{\ttfamily}l>{\ttfamily}lX@{}}
\textrm{name} & \textrm{value} & \textrm{default}\\\hline
\endhead
\Lkeyword{PSfont} & PS font name & Times & only valid \PS\ font names are possible, e.g.
\Lps{Times-Roman}, \Lps{Helvetica}, \Lps{Courier}, \Lps{Helvetica}, \Lps{Bookman}. If you want to embed the fonts
use always the URW names NimbusRomNo9L-Regu, NimbusSanL-Regu and NimbusMonL-Regu. However, the names
may vary on different operating systems.\\
\Lkeyword{postString} & <string> & \{\} & will be appended to the number string\\
\Lkeyword{trimSpaces} & <boolean> & false & will strip spaces on the right\\
\Lkeyword{fontscale} & <number> & 10 & the font scale in pt\\
\Lkeyword{valuewidth} & <number> & 10 & the width of the string for the converted
real number; if it is too small, no value is printed\\
\Lkeyword{decimals} & <number> & -1 & the number of printed decimals, a negative value
prints all possible digits.\\
\Lkeyword{xShift} & <number> & 0 & the x shift in pt for the output, relative to the current point.\\
\Lkeyword{algebraic} & <boolean> & false & function in algebraic notation.\\
\Lkeyword{VarName} & <string> & \{\} & saves the value in /<VarName> for further use\\
\Lkeyword{comma} & <boolean> & false & comma instead of the dor for decimals\\
\end{xltabular}
\begin{center}
\psset{fontscale=12}
\makebox[2em]{x(deg)} \makebox[5em]{$\sin x$} \makebox[4em]{$\cos x$}\hspace{1em}
\makebox[5em]{$\sqrt x$}\makebox[7em]{$\sin x+\cos x$}\makebox[6em]{$\sin^2 x+\cos^2 x$}\\[3pt]
\multido{\iA=0+10}{18}{
\makebox[1em]{\iA}
\makebox[5em]{\psPrintValue[PSfont=NimbusRomNo9L-Regu,xShift=-10]{\iA\space sin}}
\makebox[4em][r]{\psPrintValue[PSfont=NimbusMonL-Regu,fontscale=10,decimals=3,xShift=-20]{\iA\space cos}}\hspace{1em}
\makebox[5em]{\psPrintValue[valuewidth=15,linecolor=blue,PSfont=NimbusSanL-Regu]{\iA\space sqrt}}
\makebox[7em]{\psPrintValue[comma,PSfont=NimbusRomNo9L-ReguItal]{\iA\space dup sin exch cos add}}
\makebox[6em]{\psPrintValue[PSfont=Palatino-Roman]{\iA\space dup sin dup mul exch cos dup mul add}}\\}
\end{center}
\bigskip
\begin{lstlisting}
\psset{fontscale=12}
\makebox[2em]{x(deg)} \makebox[5em]{$\sin x$} \makebox[4em]{$\cos x$}\hspace{1em}
\makebox[5em]{$\sqrt x$}\makebox[7em]{$\sin x+\cos x$}\makebox[6em]{$\sin^2 x+\cos^2 x$}\\[3pt]
\multido{\iA=0+10}{18}{
\makebox[1em]{\iA}
\makebox[5em]{\psPrintValue[PSfont=NimbusRomNo9L-Regu,xShift=-10]{\iA\space sin}}
\makebox[4em][r]{\psPrintValue[PSfont=NimbusMonL-Regu,fontscale=10,decimals=3,xShift=-20]{\iA\space cos}}\hspace{1em}
\makebox[5em]{\psPrintValue[valuewidth=15,linecolor=blue,PSfont=NimbusSanL-Regu]{\iA\space sqrt}}
\makebox[7em]{\psPrintValue[comma,PSfont=NimbusRomNo9L-ReguItal]{\iA\space dup sin exch cos add}}
\makebox[6em]{\psPrintValue[PSfont=Palatino-Roman]{\iA\space dup sin dup mul exch cos dup mul add}}\\}
\end{lstlisting}
With enabled \Lkeyword{algebraic} option there must be two arguments, separated by a comma.
The first one is the x value as a number, which can also be PostScript code, which leaves a
number on the stack. The second part is the function described in algebraic notation.
Pay attention, in algebraic notation angles must be in radian and not degrees.
\clearpage
\begin{center}
\psset{algebraic, fontscale=12}% All functions now in algebraic notation
\makebox[2em]{x(deg)} \makebox[5em]{$\sin x$} \makebox[4em]{$\cos x$}\hspace{1em}
\makebox[5em]{$\sqrt x$}\makebox[7em]{$\sin x+\cos x$}\makebox[6em]{$\sin^2 x+\cos^2 x$}\\[3pt]
\multido{\rA=0+0.1}{18}{\makebox[1em]{\rA}
\makebox[5em]{\psPrintValue[PSfont=NimbusSanL-Regu,xShift=-10]{\rA, sin(x)}}
\makebox[4em][r]{\psPrintValue[PSfont=NimbusMonL-Regu,fontscale=10,decimals=3,xShift=-20]{\rA,cos(x)}}\hspace{1em}
\makebox[5em]{\psPrintValue[valuewidth=15,linecolor=blue,PSfont=NimbusSanL-Regu]{\rA,sqrt(x)}}
\makebox[7em]{\psPrintValue[comma,PSfont=NimbusRomNo9L-ReguItal]{\rA,sin(x)+cos(x)}}
\makebox[6em]{\psPrintValue[PSfont=Palatino-Roman]{\rA,sin(x)^2+cos(x)^2}}\\}
\end{center}
\bigskip
\begin{lstlisting}
\psset{algebraic, fontscale=12}% All functions now in algebraic notation
\makebox[2em]{x(deg)} \makebox[5em]{$\sin x$} \makebox[4em]{$\cos x$}\hspace{1em}
\makebox[5em]{$\sqrt x$}\makebox[7em]{$\sin x+\cos x$}\makebox[6em]{$\sin^2 x+\cos^2 x$}\\[3pt]
\multido{\rA=0+0.1}{18}{\makebox[1em]{\rA}
\makebox[5em]{\psPrintValue[PSfont=NimbusSanL-Regu,xShift=-10]{\rA, sin(x)}}
\makebox[4em][r]{\psPrintValue[PSfont=NimbusMonL-Regu,fontscale=10,decimals=3,xShift=-20]{\rA,cos(x)}}\hspace{1em}
\makebox[5em]{\psPrintValue[valuewidth=15,linecolor=blue,PSfont=NimbusSanL-Regu]{\rA,sqrt(x)}}
\makebox[7em]{\psPrintValue[comma,PSfont=NimbusRomNo9L-ReguItal]{\rA,sin(x)+cos(x)}}
\makebox[6em]{\psPrintValue[PSfont=Palatino-Roman]{\rA,sin(x)^2+cos(x)^2}}\\}
\end{lstlisting}
\begin{center}
foo \makebox[2em][l]{\psPrintValue[comma]{3.14 10 mul round 10 div}}bar\\[3pt]
foo \makebox[2em][l]{\psPrintValue[comma,PSfont=StandardSymL,
postString=\string\260]{3.14 10 mul round 10 div}}bar\\[3pt]
foo \makebox[3.5em][l]{\psPrintValue[PSfont=StandardSymL,decimals=6,
postString=\string\260]{3.14 dup mul}}bar
\end{center}
\bigskip
\begin{lstlisting}
foo \makebox[2em][l]{\psPrintValue[comma]{3.14 10 mul round 10 div}}bar\\[3pt]
foo \makebox[2em][l]{\psPrintValue[comma,PSfont=StandardSymL,
postString=\string\260]{3.14 10 mul round 10 div}}bar\\[3pt]
foo \makebox[3.5em][l]{\psPrintValue[PSfont=StandardSymL,decimals=6,
postString=\string\260]{3.14 dup mul}}bar
\end{lstlisting}
\clearpage
\section{\nxLcs{psRegisterList}}\label{sec:getElement}
The macro defines for every list item an own macro for an easy access to the items.
It must be a comma separated list.
\begin{BDef}
\Lcs{psRegisterList}\Largb{Name}\Largb{value list}\\
\nxLcs{\Larga{Name}}\Largb{Index}
\end{BDef}
\begin{lstlisting}
\psRegisterList{Color}{yellow,blue,green,red}% defines macro \Color
\begin{pspicture}(-7,-4.5)(7,5.5)
\psaxes{->}(0,0)(-6.5,-4.5)(6.75,5)
\psset{plotpoints=400,algebraic,linewidth=1pt,fillstyle=solid,opacity=0.4}
\multido{\iA=1+1}{4}{%
\psplot[linecolor=\Color{\iA},
fillcolor=\Color{\iA}!60]{-6.283}{6.283}{\iA*sin(\iA*x)}}%
\psset{plotpoints=400,algebraic}
\psforeach{\iA}{1,2,3,4}{%
\psplot[linecolor=\Color{\iA}]{-6.28}{6.28}{\iA*sin(\iA*x)}}
\end{pspicture}
\end{lstlisting}
\psRegisterList{Color}{yellow,blue,green,red}% defines macro \Color
\begin{pspicture}(-7,-4.5)(7,5.5)
\psaxes{->}(0,0)(-6.5,-4.5)(6.75,5)
\psset{plotpoints=400,algebraic,linewidth=1pt,fillstyle=solid,opacity=0.4}
\multido{\iA=1+1}{4}{%
\psplot[linecolor=\Color{\iA},fillcolor=\Color{\iA}!60]{-6.283}{6.283}{\iA*sin(\iA*x)}}%
\psset{plotpoints=400,algebraic}
\psforeach{\iA}{1,2,3,4}{%
\psplot[linecolor=\Color{\iA}]{-6.28}{6.28}{\iA*sin(\iA*x)}}
\end{pspicture}
\section{Random numbers}
The file \LFile{random.tex} from Donald Arseneau is no more part of CTAN due to a missing licence statement.
\LFile{pst-tools} at version 0.10 includes the code. The documentation was inside the package otself:
Random integers are generated in the range 1 to 2147483646 by the
macro \Lcs{nextrandom}. The result is returned in the counter \Lcs{randomi}.
Do not change \Lcs{randomi} except, perhaps, to initialize it at some
random value. If you do not initialize it, it will be initialized
using the time and date. (This is a sparse initialization, giving
fewer than a million different starting values, but you should use
other sources of numbers if they are available--just remember that
most of the numbers available to TeX are not at all random.)
The \Lcs{nextrandom} command is not very useful by itself, unless you
have exactly 2147483646 things to choose from. Much more useful
is the \Lcs{setrannum} command which sets a given counter to a random
value within a specified range. There are three parameters:
\Lcs{setrannum\{<counter>\}\{<minimum>\}\{<maximum>\}}
For example, to
simulate a die-roll:
\verb|\setrannum{\die}{1}{6}| \verb|\ifcase\die...| .
If you need random numbers that are not integers, you will have to
use dimen registers and \Lcs{setrandimen}. For example, to set a random
page width:
\Lcs{setrandimen} \Lcs{hsize\{3in\}\{6.5in\}}
The »\Lcs{pointless}« macro
will remove the »pt« that TeX gives so you can use the dimensions
as pure `real' numbers. In that case, specify the range in pt units.
For example,
\verb|\setrandimen\answer{2.71828pt}{3.14159pt}|
The answer is \verb|\pointless\answer|.
The random number generator is the one by Lewis, Goodman, and Miller
(1969) and used as \texttt{ran0} in »Numerical Recipies« using Schrage's
method for avoiding overflows. The multiplier is $16807 (7^5)$, the
added constant is 0, and the modulus is $2147483647 (2^{31}-1)$. The
range of integers generated is $1 - 2147483646$. A smaller range would
reduce the complexity of the macros a bit, but not much--most of the
code deals with initialization and type-conversion. On the other hand,
the large range may be wasted due to the sparse seed initialization.
\section{List of the defined PostScript functions}
\footnotesize
\begin{verbatim}
/Pi2 1.57079632679489661925640 def
/factorial { % n on stack, returns n!
/MoverN { % m n on stack, returns the binomial coefficient m over n
/ps@ReverseOrderOfPoints { % on stack [P1 P2 P3 ...Pn]=>[Pn,Pn-1,...,P2,P1]
/cxadd { % [a1 b1] [a2 b2] = [a1+a2 b1+b2]
/cxneg { % [a b]
/cxsub { cxneg cxadd } def % same as negative addition
/cxmul { % [a1 b1] [a2 b2]
/cxsqr { % % [a b]^2 = [a^2-b^2 2ab] = [a2 b2]
/cxsqrt { %
/cxarg { % [a b]->arg(z)=atan(b/a)
/cxlog { % [a b]->log[a b] = [a^2-b^2 2ab] = [a2 b2]
/cxnorm2 { % [a b]->a^2+b^2
/cxnorm { %
/cxconj { % [a b]->[a -b]
/cxre { 0 get } def % real value
/cxim { 1 get } def % imag value
/cxrecip { % [a b]->1/[a b] = ([a -b]/(a^2+b^2)
/cxmake1 { 0 2 array astore } def % make a complex number, real given
/cxmake2 { 2 array astore } def % dito, both given
/cxdiv { cxrecip cxmul } def
/cxrmul { % [a b] r->[r*a r*b]
/cxrdiv { % [a b] r->[1/r*a 1/r*b]
/cxconv { % theta->exp(i theta) = cos(theta)+i sin(theta) polar<->cartesian
/bubblesort { % on stack must be an array [ ... ]
/concatstringarray{ % [(a) (b) ... (z)] --> (ab...z) 20100422
/concatstrings{ % (a) (b) -> (ab)
/reversestring { % (aBC) -> (CBa)
/concatarray{ % [a c] [b d] -> [a c b d]
/dot2comma {% on stack a string (...)
/rightTrim { % on stack the string and the character number to be stripped
/psStringwidth /stringwidth load def
/psShow /show load def
\end{verbatim}
\normalsize
\clearpage
\section{List of all optional arguments for \texttt{pst-tools}}
\xkvview{family=pst-tools,columns={key,type,default}}
\bgroup
\raggedright
\nocite{*}
%\bibliographystyle{plain}
\printbibliography
\egroup
\printindex
\end{document}