%!TEX TS-program =  latex
\documentclass{article}
\usepackage[margin=1.25in]{geometry}
\usepackage[T1]{tipa}
\usepackage{pst-vowel}

\usepackage{fancyvrb, multicol, array}
\usepackage[small]{titlesec}
\usepackage{enumitem}
\begin{document}
\newcommand\bs{\textbackslash}
\begin{center}
{\Large\bfseries The pst-vowel package}
\vspace{.5in}

\large Alan Munn\\Michigan State University\\\texttt{amunn@msu.edu}

\bigskip
April 24, 2008
\end{center}


\section{Introduction}
Rei Fukui's vowel.sty package (distributed as part of the TIPA package) provides a simple way of drawing vowel charts. It very nicely places vowels at either cardinal positions or in arbitrarily placed locations on a variety of differently shaped vowel charts.

One thing that the package lacks is a way to show diphthongs on the chart by relating two vowels on the chart with a (labelled) arrow. Such arrows can also be put to good effect to show chain shifts in sociolinguistics.  The present package addresses this issue by adding a set of predefined nodes corresponding to the cardinal positions, and allowing the user to specify explicit node labels for non-cardinal vowels. These nodes can then be referenced with pstricks commands to connect them with arrows.

This documentation describes only the differences between the original vowel.sty and pst\-vowel.sty.  I assume that the reader is familiar with vowel.sty commands; see the documentation for vowel.sty for more details.

\section{Requirements}
Since the package depends on pstricks, any documents using it must be compiled with latex+dvips and not with pdflatex. It can, however be used with xelatex using the (default) xdvipdfmx driver. Please note that this package changes certain commands in vowel.sty, and thus vowel charts created using vowel.sty may need to be modified to work correctly with pst-vowel.sty.

\section{Cardinal vowels}
For the cardinal vowels, (defined here as any vowel placed with the \texttt{\bs putcvowel} command) the package defines 16 nodes, v1 \ldots v16 which correspond to each of the 16 cardinal positions on the vowel chart. A node is created whenever a vowel is placed at that place on the chart using the \texttt{\bs putcvowel} command.  These nodes can then be referred to with \texttt{\bs ncline}, \texttt{\bs ncarc} or \texttt{\bs nccurve} commands to connect them together. Note that the \texttt{\bs putcvowel} command identifies the vowel position simply by a number; reference to the \emph{node} corresponding to that vowel is with the node label v1, v2, etc. Here is an example:

\begin{tabular}{m{3.5in}m{1in}}
\begin{Verbatim}[fontsize=\small]
\begin{vowel}
\putcvowel{\textipa{i}}{1}
\putcvowel{\textipa{u}}{8}
\putcvowel{\textipa{\textturna}}{15}
\end{vowel}
\psset{arrowsize=.75ex, nodesep=.25ex}
\ncline{->}{v15}{v1}
\ncarc{<-}{v8}{v15}
\end{Verbatim} 
&
\Large
\begin{vowel}
\putcvowel{\textipa{i}}{1}
\putcvowel{\textipa{u}}{8}
\putcvowel{\textipa{\textturna}}{15}
\end{vowel}
\psset{arrowsize=.75ex, nodesep=.25ex}
\ncline{->}{v15}{v1}
\ncarc{<-}{v8}{v15}
\end{tabular}

The vowel.sty cardinal vowel commands are unchanged in pst-vowel.sty. Vowels can be placed to the left and right of a dot at the vowel position as usual.  In this case, the node is defined at the dot:

\begin{tabular}{m{3.5in}m{1in}}
\begin{Verbatim}[fontsize=\small]
\begin{vowel}
\putcvowel[l]{\textipa{i}}{1}
\putcvowel[r]{\textipa{y}}{1}
\putcvowel[r]{\textipa{u}}{8}
\putcvowel[l]{\textipa{\textturnm}}{8}
\putcvowel{\textipa{\textturna}}{15}
\end{vowel}
\psset{arrowsize=.75ex, nodesep=.25ex}
\ncline{->}{v15}{v1}
\ncline{->}{v15}{v8}
\end{Verbatim}
&
\Large\begin{vowel}
\putcvowel[l]{\textipa{i}}{1}
\putcvowel[r]{\textipa{y}}{1}
\putcvowel[r]{\textipa{u}}{8}
\putcvowel[l]{\textipa{\textturnm}}{8}
\putcvowel{\textipa{\textturna}}{15}
\end{vowel}
\psset{arrowsize=.75ex, nodesep=.25ex}
\ncline{->}{v15}{v1}
\ncline{->}{v15}{v8}
\end{tabular}
\section{Non-cardinal vowels}\label{sec:arb}
For vowels placed at non-cardinal positions using the vowel.sty command \texttt{\bs putvowel}, an extra argument must be provided with the label for that node in pst-vowel.sty.  Thus, the \texttt{\bs putvowel} command has the following syntax, where \emph{x} and \emph{y} are horizontal and vertical distances (as in vowel.sty) and \emph{node} is the node label.
\begin{itemize}
\item[] \texttt{\bs putvowel$[$l|r$]$\{x\}\{y\}\{node\}}
\end{itemize}
It is usually prudent to make sure that these node labels are NOT v1 \ldots v16, since this could lead to duplicate node labels if used in conjunction with cardinal vowels.  Duplicate labels will not throw an error, but may cause unexpected results. Here is an example:

\begin{tabular}{m{3.75in}m{1in}}
\begin{Verbatim}[fontsize=\small]
\begin{vowel}
\putvowel{\textipa{i}}{.75\vowelhunit}{0pt}{node1}
\putvowel{\textipa{u}}{3.5\vowelhunit}{1\vowelvunit}{node2}
\putcvowel{\textipa{\textturna}}{15}
\end{vowel}
\psset{arrowsize=.75ex, nodesep=.25ex}
\ncline{->}{v15}{node1}
\ncline{->}{v15}{node2}
\end{Verbatim}
&
\Large\begin{vowel}
\putvowel{\textipa{i}}{.75\vowelhunit}{0pt}{node1}
\putvowel{\textipa{u}}{3.5\vowelhunit}{1\vowelvunit}{node2}
\putcvowel{\textipa{\textturna}}{15}
\end{vowel}
\psset{arrowsize=.75ex, nodesep=.25ex}
\ncline{->}{v15}{node1}
\ncline{->}{v15}{node2}
\end{tabular}
\section{Labelling arrows}
Arrows can be labelled using the pstricks \texttt{\bs n\{a|b|c\}put} commands. Here is an example:

\begin{tabular}{m{3.75in}m{1in}}
\begin{Verbatim}[fontsize=\small]
\begin{vowel}[plain]
\putcvowel{\textipa{I}}{13}
\putcvowel{\textipa{U}}{14}
\putcvowel{\textipa{a}}{15}
\end{vowel}
\psset{arrowsize=.75ex, nodesep=.25ex}
\ncarc{<-}{v13}{v15}
\naput[nrot=:U,labelsep=.5ex]{\textipa{aI}}
\ncarc{->}{v15}{v14}
\ncput*[labelsep=.2ex]{\textipa{aU}}
\end{Verbatim}
&
\Large\begin{vowel}[plain]
\putcvowel{\textipa{I}}{13}
\putcvowel{\textipa{U}}{14}
\putcvowel{\textipa{a}}{15}
\end{vowel}
\psset{arrowsize=.75ex, nodesep=.25ex}
\ncarc{->}{v15}{v13}
\naput[nrot=:D,labelsep=.5ex]{\textipa{aI}}
\ncarc{<-}{v14}{v15}
\ncput*[labelsep=.2ex]{\textipa{aU}}
\end{tabular}
\section{Tricks and Pitfalls}
\subsection{Tricks}
\begin{itemize}
\item Vowels can be enclosed in boxes of various shapes by using pstricks framing commands such as \texttt{\bs psframebox}, \texttt{\bs pscirclebox}, \texttt{\bs pstribox}, and \texttt{\bs psovalbox}, when the vowel is placed.  See the pstricks documentation for more possibilities and box parameters.

\begin{tabular}{m{3.75in}m{1in}}
\begin{Verbatim}[fontsize=\small]
\begin{vowel}
\psset{framesep=1pt}
\putcvowel{\pscirclebox{\textipa{a}}}{15}
\putcvowel{\psframebox{\textipa{U}}}{14}
\putcvowel{\psovalbox{\textipa{i}}}{1}
\putcvowel{\psframebox[framearc=.5]{\textipa{I}}}{13}
\end{vowel}
\end{Verbatim}
&
\Large\begin{vowel}
\psset{framesep=1pt}
\putcvowel{\pscirclebox{\textipa{a}}}{15}
\putcvowel{\psframebox{\textipa{U}}}{14}
\putcvowel{\psovalbox{\textipa{i}}}{1}
\putcvowel{\psframebox[framearc=.5]{\textipa{I}}}{13}
\end{vowel}
\end{tabular}
\item In some cases it may be more useful to show transitions using a dot at the endpoint of an arrow. This can easily be done, either by using the predefined \texttt{\bs vowelsymbol} (which is a bullet) or by inserting any other sort of character (or nothing at all) instead of an actual vowel symbol:

\begin{tabular}{m{3.75in}m{1in}}
\begin{Verbatim}[fontsize=\small]
\begin{vowel}
\putcvowel{\textipa{a}}{15}
\putcvowel{*}{14}
\putcvowel{\vowelsymbol}{13}
\end{vowel}
\psset{arrowsize=.75ex, nodesep=.25ex}
\ncline{->}{v15}{v14}
\ncline{->}{v15}{v13}
\end{Verbatim}
&
\Large\begin{vowel}
\putcvowel{\textipa{a}}{15}
\putcvowel{*}{14}
\putcvowel{\vowelsymbol}{13}
\end{vowel}
\psset{arrowsize=.75ex, nodesep=.25ex}
\ncline{->}{v15}{v14}
\ncline{->}{v15}{v13}
\end{tabular}


\end{itemize}
\subsection{Pitfalls}
\begin{itemize}[listparindent=\parindent, itemsep=\baselineskip,parsep=0pt]
\item Labelling lines with pstricks can be frustrating at times, because of the way it determines directions relative to a line. Here is a simple illustration of the problem:

\begin{tabular}{m{1.5in}m{1.5in}m{1.5in}}
\begin{Verbatim}[fontsize=\small]
\begin{vowel}[plain]
\putcvowel{i}{1}
\putcvowel{u}{8}
\putcvowel{a}{15}
\end{vowel}
\ncline{->}{v15}{v1}
\naput[nrot=:U]{A}
\end{Verbatim}
&
\begin{Verbatim}[fontsize=\small]
\begin{vowel}[plain]
\putcvowel{i}{1}
\putcvowel{u}{8}
\putcvowel{a}{15}
\end{vowel}
\ncline{<-}{v1}{v15}
\naput[nrot=:U]{A}
\end{Verbatim}
&
\begin{Verbatim}[fontsize=\small]
\begin{vowel}[plain]
\putcvowel{i}{1}
\putcvowel{u}{8}
\putcvowel{a}{15}
\end{vowel}
\ncline{->}{v15}{v8}
\naput[nrot=:U]{A}
\end{Verbatim}
\\

\begin{vowel}[plain]
\putcvowel{i}{1}
\putcvowel{u}{8}
\putcvowel{a}{15}
\end{vowel}
&
\ncline{->}{v15}{v1}
\naput[nrot=:U]{A}
\begin{vowel}[plain]
\putcvowel{i}{1}
\putcvowel{u}{8}
\putcvowel{a}{15}
\end{vowel}
&
\ncline{<-}{v1}{v15}
\naput[nrot=:U]{A}
\begin{vowel}[plain]
\putcvowel{i}{1}
\putcvowel{u}{8}
\putcvowel{a}{15}
\end{vowel}
\ncline{->}{v15}{v8}
\naput[nrot=:U]{A}
\\
\multicolumn{1}{c}{Example (a)}&
\multicolumn{1}{c}{Example (b)}&
\multicolumn{1}{c}{Example (c)}
\end{tabular}
\vskip 1ex

In Example (a), the node connection is from v15 to v1. Pstricks therefore treats the orientation of the line as being from left to right starting at v15. This means that when you use \texttt{\bs naput} to place the label, it appears to place it upside down, and ``below'' the line instead of above the line.  In actuality it \emph{is} above the line, and right side up, because the line is taken to start at v15 as the ``left'' node and end at v1 as the ``right'' node. You can see this by rotating the line in your mind so that v15 is on the left.  In that orientation, the label is upright and above the line.

The simplest way to solve this problem is simply to reverse the order of the nodes (and the direction of the arrow) in the \texttt{\bs ncline} command, as in Example (b). Now the label appears in the correct position, because the line is taken to start at v1 and end at v15.

Of course, when the second node is to the \emph{right} of the first node, as in Example (c), the intuitive example works again, since now the beginning of the line is also the leftmost member, so the label appears above the line as expected.

\item As mentioned in section \ref{sec:arb} above, it is a good idea to assign unique node labels to any non-cardinal vowels, and keep the labels v1 \ldots v16 reserved for the cardinal vowels. Pstricks doesn't flag missing or incorrect labels; your output will just not appear.

\end{itemize}
 
\section{Limitations}
There are two limitations to the package: one is that it relies on pstricks, which requires compilation with latex+dvips rather than pdflatex. It can, however, be used with xelatex. (The extent to which this is a limitation depends on how much one requires features special to pdflatex.)  

The second limitation  is that because it redefines the original \texttt{\bs putvowel} command, it is not compatible with vowel charts originally created with vowel.sty using that command. For such documents, any uses of \texttt{\bs putvowel} will need to include the extra node argument as described in section \ref{sec:arb} above. Vowel charts created using only the \texttt{\bs putcvowel} command will work with pst-vowel without modification.
\section{Disclaimer and Acknowledgements}
\subsection{Disclaimer}
All the vowel charts presented in this document are for illustration purposes only. The author is not a phonetician, and bears no responsibility for how realistic or correct the example charts are.

The documentation here is not intended to be a replacement of the vowel.sty documentation, and especially not a replacement of the pstricks documentation. Some familiarity with both is assumed, although there are enough examples in the text to get you started.
\subsection{Acknowledgements}
I would like to thank Rei Fukui for creating the original vowel.sty upon which this package is based. Thanks also to Yoshinari Fujino for inadvertently getting me to write the package itself and providing extremely helpful comments on the documentation (including pointing out the inaccuracies which give rise to the disclaimer above!)
\end{document}