path: root/macros/latex/contrib/pstring/pstring-doc.tex

% Speed-up the compilation with LatexDaemon!!! (http://william.famille-blum.org/software/latexdaemon)
\input{pstring-doc.pre}
%

\author{William Blum}
\title{The pstring package}
\begin{document}
\maketitle
\begin{abstract}
This is a short documentation for the pstring package for Latex. This package allows you to
typeset justified sequences, also called pointing strings.
The latest version of the package can be downloaded from \url{http://william.famille-blum.org/software/latex/index.html}.

\begin{codeexample}[width=5cm]
\Pstr[0.65cm]{ \psi = (n){q^0} \ (n4-n,60){q^1} \ (n5-n4){q^2}
\ (n8-n){q^1} \ (n9-n8){q^2} \ (n10-n){q^3} }.
\end{codeexample}
\end{abstract}

\section{Use and syntax}

From version 0.3, pstring can use either PSTricks or PGF as a rendering engine. To specify which one
you want, use the option \verb|pstricks| or \verb|pgf| when you load the pstring package. For instance to use PGF you must type:
\begin{codeexample}[code only]
\usepackage{pstring}[pgf]
\end{codeexample}
If no option is specified then by default \verb|pgf| is selected if you are running pdflatex
and \verb|pstricks| is selected if you are running latex.

You can specifies other options with the following commands:
\begin{command}{\pstrSetLabelStyle\{style\}}
Change the style used to typeset labels on arrows.
\end{command}
\begin{command}{\pstrSetArrowColor\{color\}}
Change the color used to typeset arrows.
\end{command}
\begin{command}{\pstrSetArrowLineWidth\{size\}}
Change the arrows line width.
\end{command}
\begin{command}{\pstrSetArrowLineStyle\{style\}}
Change the arrows line style. Valid styles are: \verb|none|, \verb|dashed|, \verb|dotted| and \verb|solid|.
\end{command}
The default options are as follows:
\begin{codeexample}[code only]
\pstrSetLabelStyle{\color{blue} \tiny}
\pstrSetArrowColor{orange}
\pstrSetArrowLineWidth{0.3pt}
\pstrSetArrowLineStyle{solid}
\end{codeexample}

\subsection{The succinct syntax}
The syntax for creating a pointing string is as follows:
\begin{command}{\Pstr[raiseamount][nodesep]\{stringspecification\}}
\begin{itemize}
\item  \verb|raiseamount| (optional) is the size by which you want
to raise the box containing the sequence. In
PSTricks mode, the bounding box is not computed automatically therefore
it is necessary to specify this value by hand. Using the PGF mode
 however, this value is ignored since the bounding box
is computed automatically,
\item  \verb|nodesep| (optional) is the vertical distance between
the nodes and the links.
\item  \verb|stringspecification| contains commands describing the nodes
of the string.
This parameter can contain normal text and latex commands (with some restriction, see section \ref{subsec:altsyntax}).
Nodes that have link associated to them, or which have a link pointing to them
must be specified with the node specification syntax described hereunder.\end{itemize}
\end{command}

The syntax for creating nodes is as follows.
If the node has no link associated to it then you just use
the syntax \verb|(nodename){content of the node}| where \verb|nodename| is a name that you give to the node and \verb|content| is the text you want to write inside the node.

If there is a link attached to the node then you use
the syntax
\begin{verbatim}
(targetnode-nodename,angle:label){content}
\end{verbatim}
where
\begin{itemize}
\item \verb|nodename| is a name that you give to the node,
\item \verb|targetnode| is the name of the node where the link must point to,
\item \verb|angle| (optional) specifies the angle between the horizontal line and the line
tangent to the arrow representing the link at the top of the node,
\item  \verb|label| (optional) is a text to be printed out on top of the link,
\item \verb|content| is the content of the node.
\end{itemize}

The arguments  \verb|angle| and \verb|label| are optional. When the angle is not specified it is set to a default value of 45 (degrees).

Here is an example:
\begin{codeexample}[width=7cm]
\Pstr[20pt]{
t = \lambda\cdot (app){@} \cdot (ly){\lambda y}
\ldots (y-ly,35:1){y} \cdot
(lx-app,38:1){\lambda \overline{x}}
\ldots (x-lx,30:i){x_i} \cdot
(leta-y,40:i){\lambda \overline{\eta_i}} {\ldots}
}.
\end{codeexample}


\subsection{Alternative syntax}
\label{subsec:altsyntax}
You can use an alternative syntax to specify sequences. For instance the previous example
can also be defined as follows:
\begin{codeexample}[width=7cm]
\pstr[0.7cm]{
\nd t = \lambda \cdot (app){@}
\nd \cdot (ly){\lambda y}
\nd \ldots (y-ly,35:1) {y}
\nd \cdot (lx-app,38:1){\lambda \overline{x}}
\nd \ldots (x-lx,30:i){x_i}
\nd \cdot (letay-y,40:i){\lambda \overline{\eta_i}}
\txt{\ldots} }.
\end{codeexample}
Although this syntax is more cumbersome than the succinct one, it permits to typeset sequences that are not definable with the succinct syntax. The following example is such an example:
\ifLoadPSengine
\begin{codeexample}[width=6cm]
$\pstr[0.7cm][1pt]{ s = \underbrace{\cdots\ \nd(r){r^O}
\cdots }_{s'}\ \nd(n){n^P}
\ \underbrace{\cdots\ \nd(a-r,35){a}^P \cdots }_{u}
\ \nd(m-n,30){m}^O }$.
\end{codeexample}
\else
\vskip 10pt
[Sorry, you need to compile the documentation with latex in order to view this example]
\vskip 10pt
\fi

{\bf Important note:}
The previous example can only be done using the pstricks engine and using the long syntax. This is due to the use of the
latex command \verb|\overbrace| which embraces several nodes inside the sequence.
This cannot be handled in the PGF rendering mode due to the impossibility to create nodes outside of a PGF environment.
It may be possible to fix this problem by using the overlay feature of PGF/Tikz, however overlays seem to work only
within Tikz environment and not in standard PGF ones. Also overlays have the disadvantage to require two latex compilations in order to resolve node name references, and moreover they work only with pdflatex (not with latex).

\subsubsection{Adding more links}
It is possible to create additional links starting from a same node:
\begin{codeexample}[width=6cm]
\pstr[0.6cm]{\ldots  \nd(r){r}
  \nd\ldots (l1){\lambda \overline{\xi}_1}
  \nd\ldots (l2){\lambda \overline{\xi}_2 }
  \nd\ldots (n-r,45){n}
  \arrow{n}{l1}{45}{}{blue}{dotted}
  \arrow{n}{l2}{45}{}{blue}{dotted}
 }.
 \end{codeexample}
The syntax for arrow creation is:
\begin{command}{\arrow\{source\}\{target\}\{angle\}\{label\}\{linecolor\}\{linestyle\}}
\begin{itemize}
\item \verb|source| is the name of the source node,
\item \verb|target| is the name of the target node,
\item \verb|angle| is the arrow angle,
\item \verb|label| is a text to be printed out on top of the link,
\item \verb|linecolor| is the color to be used to draw the link,
\item \verb|linestyle| is a line style used to draw the arrow. Valid styles are: \verb|none|, \verb|dashed|, \verb|dotted| and \verb|solid|.
\end{itemize}
\end{command}



\section{Examples}

\subsection{A sequence with more links}
\begin{codeexample}[width=7cm]
\Pstr[1cm][2pt]{
t_2 = (n){\lambda f z}      \ (n2){@}
\ (n3-n2,60){\lambda g x}   \ (n4-n){f^{[1]}}
\ (n5-n4){\lambda^{[2]}}    \ (n6-n3){x}
\ (n7-n2,35){\lambda^{[3]}} \ (n8-n,35){f^{[4]}}
\ (n9-n8,45){\lambda^{[5]}} \ (n10-n,35){z} }.
\end{codeexample}


\subsection{Elevation of the links}
A second optional parameter can be passed to \verb|\pstr| in order to elevate the links in the sequence as follows:
\begin{codeexample}[width=5cm]
$\begin{array}{rclrcl}
\mbox{First line} &=& \parbox[t]{8cm}{there should be enough space between the
                        bottom of this line and the arc of the next line.} \\
                s &=& \Pstr[28pt][10pt]{ s \cdot (m){m} \cdot \ldots \cdot (lmd-m,40)
                         {\lambda\overline{\xi}} }
    \quad \mbox{ the arc is elevated using the raise option of pstr.}
\end{array}$
\end{codeexample}

\subsection{Two sequences on the same line}
\begin{codeexample}[width=7cm]
\Pstr[0.8cm]{
t = (n){\lambda f z}\ (n2){@} \ (n3-n2,60){\lambda g x} \ (n4-n,45){f^{[1]}}
\ (n5-n4,45){\lambda^{[2]}} \ (n6-n3,45){x} \ (n7-n2,35){\lambda^{[3]}}
\ (n8-n,35){f^{[4]}} \ (n9-n8,45){\lambda^{[5]}} \ (n10-n,35){z}
}
\qquad
\Pstr[0.9cm]{
t\upharpoonright r = (n){\lambda f z} \ (n4-n,50){f}^{[1]}
\ (n5-n4,60){\lambda}^{[2]} \ (n8-n,45){f}^{[4]}
\ (n9-n8,60){\lambda}^{[5]} \ (n10-n,40){z}}
\end{codeexample}

\subsection{Sequences containing parenthesis}
If you insert text containing parenthesis '(' and ')' between two nodes then you must surround
the text with curly braces otherwise \verb|pstr| will interpret it as a node specification:
\begin{codeexample}[width=7.1cm]
\Pstr[0.8cm]{ {\psi_M(t\upharpoonright r) =\ }
(n){q^0}\ (n4-n,60){q^1}\ (n5-n4,60){q^2}
\ (n8-n,45){q^1}\ (n9-n8,60){q^2}
\ (n10-n,38){q^3} \in [\![ M ]\!] \ .}
\end{codeexample}

\subsection{Example taken from an article}
%\begin{codeexample}[width=4cm]
\newcommand{\oview}[1]{\llcorner #1 \lrcorner}
{\bf (InputVar)} If $t_1 \cdot x \cdot t_2$ is a traversal with
  $x \in N_{var}^{\upharpoonright r}$ and $?(t_1 \cdot x \cdot
  t_2)=?(t_1) \cdot x$ then so is \Pstr[0.4cm]{t_1 \cdot (m){x} \cdot t_2 \cdot (n-m,38:i){n}} for all
  $\lambda$-node $n$ whose parent occurs in $\oview{t_1 \cdot x}$, $n$
  pointing to some occurrence of its parent node in $\oview{t_1 \cdot x}$.

\noindent {\bf (Copycat$^@$)}
  If \Pstr{t \cdot (app){@} \cdot (lz-app,60:0){\lambda \overline{z}}  \ldots  (lzv-lz,60:v){v}_{\lambda \overline{z}} } is a traversal then so is
\Pstr[0.6cm]{t \cdot (app){@} \cdot (lz-app,60){\lambda
\overline{z}} \ldots  (lzv-lz,60:v){v}_{\lambda \overline{z}} \cdot
(appv-app,45:v){v}_@}.

\noindent {\bf (Copycat$^\lambda$)}
 If \Pstr[0.4cm]{t \cdot \lambda \overline{\xi} \cdot (x){x}  \ldots   (xv-x,50:v){v}_x}
is a traversal then so is \Pstr[0.6cm]{t \cdot (lmd){\lambda
\overline{\xi}} \cdot (x){x}  \ldots  (xv-x,50:v){v}_x  \cdot
(lmdv-lmd,30:v){v}_{\lambda \overline{\xi}} }.

\noindent {\bf (Copycat$^{var}$)}
If \Pstr[0.4cm]{t \cdot y \cdot (lmd){\lambda \overline{\xi}}
\ldots (lmdv-lmd,50:v){v}_{\lambda \overline{\xi}} } is a traversal
for some variable $y$ not in $N_{var}^{\upharpoonright r}$ then so
is \Pstr[0.6cm]{t \cdot (y){y} \cdot (lmd){\lambda \overline{\xi}}
\ldots (lmdv-lmd,30:v){v}_{\lambda \overline{\xi}}  \cdot
(vy-y,50:v){v}_y }.
%\end{codeexample}
\end{document}