\documentclass{article}
\usepackage[notipa]{ot-tableau}
% use the usehhline option to use the hhline for prettier lines (which currently does not work)
%\usepackage[notipa,usehhline]{ot-tableau}
\usepackage{fullpage,pifont}
\title{The \textsf{ot-tableau} package}
\date{Revised 2021-05-19}
\author{Adam Baker}
\def\eg{e.g.,~}
\def\tabl{\textsf{ot-tableau}}

\begin{document}
\maketitle

\section{Introduction}
The \tabl\ package makes it easy to create beautiful optimality-theoretic tableaux. The \LaTeX\ source is visually very similar to a formatted tableau, which makes working with the source code painless (well, less painful). A variety of stylistic variants can be modified to suit personal taste.

\begin{center}
	\begin{tableau}{c:c|c}
	\inp{\ips{stap}}        \const{*Complex} \const{Anchor-IO} \const{Contiguity-IO}
	\cand{stap}             \vio{*!}         \vio{}            \vio{}
	\cand[\Optimal]{sap}    \vio{}           \vio{}            \vio{*}
	\cand{tap}              \vio{}           \vio{*!}          \vio{}
	\end{tableau}
\end{center}

\begin{verbatim}
\begin{tableau}{c:c|c}
\inp{\ips{stap}}        \const{*Complex} \const{Anchor-IO} \const{Contiguity-IO}
\cand{stap}             \vio{*!}         \vio{}            \vio{}
\cand[\Optimal]{sap}    \vio{}           \vio{}            \vio{*}
\cand{tap}              \vio{}           \vio{*!}          \vio{}
\end{tableau}
\end{verbatim}
Pertinent features:
\begin{itemize}
\item The package introduces the \verb+tableau+ environment.
\item Indicate solid or dashed lines between constraints with \verb+\begin{tableau}{c:c|c}+. A solid line is indicated by a pipe, a dashed line with a colon.
\item The input is specified with the \verb+\inp+ command. (Here the \verb+\ips+ macro is being used to render the text using TIPA and put it within slashes.)
\item Indicate the constraints with the \verb+\const+ command.
\item Add a candidate with the \verb+\cand+ command. An optional argument can be used to annotate the candidate (\eg to use \HandLeft, \verb+\cand[\HandLeft]+)
\item Violations are indicated with the \verb+\vio+ macro. You need to include these commands even when there are no violations.
\item Use of whitespace is optional. Keeping the columns aligned in the source code, though, makes the tableau much easier to edit.
\end{itemize}

\noindent Very large tableaux are not much more difficult---for instance in Table~\ref{large_example}.

\begin{sidewaystable}
\ShadingOn
\begin{center}
	\LetterBeforeFinger
	\begin{tableau}{c:c:c|c:c|s:s}
	\inp{Input: /\textsc{red}, \ipa{ulampoy}/}	\const{Red=$\sigma$}	\const{Dep-IO}	\const{Max-IO}	\const{Onset}	\const{No-Coda}	\const{Align-Red-L}	\const{Max-BR}
	\cand[\HandRight]{u-\underline{la}-lam.poy}			\vio{}			\vio{}		\vio{}		\vio{*}		\vio{**}	\vio{u}			\vio{mpoy}
	\cand{u-\underline{lam}-lam.poy}				\vio{}			\vio{}		\vio{}		\vio{*}		\vio{***!}	\vio{u}			\vio{poy}
	\cand{\underline{u}-u.lam.poy}				\vio{}			\vio{}		\vio{}		\vio{**!}	\vio{**}	\vio{}			\vio{lampoy}
	\cand{\underline{ul}-u.lam.poy}				\vio{}			\vio{}		\vio{}		\vio{**!}	\vio{***}	\vio{}			\vio{ampoy}
	\cand{\underline{la}-lam.poy}				\vio{}			\vio{}		\vio{*!}	\vio{}		\vio{**}	\vio{}			\vio{mpoy}
	\cand{\underline{tu}-tu-lam.poy}				\vio{}			\vio{*!}	\vio{}		\vio{}		\vio{**}	\vio{}			\vio{lampoy}
	\cand{\underline{u.l}-u.lam.poy}				\vio{l!}		\vio{}		\vio{}		\vio{}		\vio{**}	\vio{}			\vio{lampoy}
	\cand{u-\underline{lam.poy}-lam.poy}			\vio{p!oy}		\vio{}		\vio{}		\vio{}		\vio{****}	\vio{u}			\vio{}
	\end{tableau}
\end{center}
\caption{After Kager (1999:229).}\label{large_example}
\end{sidewaystable}

\section{Parameters}

\subsection{Changing formats}
The default \verb+\cand+ and \verb+\const+ commands typeset the argument with TIPA's \verb+\textipa+  command, and small caps, respectively. Though this is generally appropriate, there are also commands \verb+\cand*+ and \verb+\const*+ that apply no formatting. The following code and tableau illustrate this.

\begin{center}
	\begin{tableau}{c|c}
	\inp{Illustration}            \const{C1}  \const*{C2}
	\cand*{Option 1}              \vio{*!}    \vio{}
	\cand*[\HandRight]{Option 2}  \vio{}      \vio{*}
	\end{tableau}
\end{center}

\begin{verbatim}
	\begin{tableau}{c|c}
	\inp{Illustration}            \const{C1}  \const*{C2}
	\cand*{Option 1}              \vio{*!}    \vio{}
	\cand*[\HandRight]{Option 2}  \vio{}      \vio{*}
	\end{tableau}
\end{verbatim}

\noindent Usage of \verb+\const*+ is illustrated in the next section.

If you are using Unicode input for your phonetic symbols, use the package option \verb+notipa+ to disable TIPA.
 
\subsection{Controlling cell shading}

There are two systems in use for shading OT tableaux. One system is to shade cells in a row after the crucial violation. The other system is to shade an entire column, if the associate constraint generates no crucial violations.

\tabl\ will do cell-shading automatically with the \verb+shadedcells+ package option.\footnote{More specifically, \tabl\ will look for the exclamation point. You have to provide the exclamation point.} This tableau...

\begin{center}
	\ShadingOn
	\begin{tableau}{c|c}
	\inp{\ips{ba}}		\const{*VcdObs}	\const*{\textsc{Ident-IO}-[nas]}
	\cand{ba}		\vio{*!}	\vio{}
	\cand[\HandRight]{pa}	\vio{}		\vio{*}
	\end{tableau}
\end{center}

\noindent ...is produced by the following code...

\begin{verbatim}
	\ShadingOn
	\begin{tableau}{c|c}
	\inp{\ips{ba}}         \const{*VcdObs}  \const*{\textsc{Ident-IO}-[nas]}
	\cand{ba}              \vio{*!}         \vio{}
	\cand[\HandRight]{pa}  \vio{}           \vio{*}
	\end{tableau}
\end{verbatim}

The alternative is to shade an entire column by using `s' instead of `c' in the argument to the \verb+tableau+ environment:

\begin{center}
	\begin{tableau}{c|s}
	\inp{\ips{ba}}         \const{*VcdObs}  \const*{\textsc{Ident-IO}-[nas]}
	\cand{ba}              \vio{*!}         \vio{}
	\cand[\HandRight]{pa}  \vio{}           \vio{*}
	\end{tableau}
\end{center}

\noindent ...is produced by...

\begin{verbatim}
	\begin{tableau}{c|s}
	\inp{\ips{ba}}         \const{*VcdObs}  \const*{\textsc{Ident-IO}-[nas]}
	\cand{ba}              \vio{*!}         \vio{}
	\cand[\HandRight]{pa}  \vio{}           \vio{*}
	\end{tableau}
\end{verbatim}

You can also mix the approaches, which is illustrated in the code for Table~\ref{large_example}. (That code is not printed in this manual, but it's available in the .tex version of this file.)

You can control the darkness of the shading using, \eg \verb+\SetCellShading{0.4}+. A value of 1 corresponds to white, 0 to black. The default is 0.9.

\subsection{Symbol position}
Some people prefer the ``finger-of-optimality'' to go after the letter. This can be done by using the \verb+fingerafter+ package option. For example:

\begin{center}
	\LetterBeforeFinger
	\begin{tableau}{c|c}
	\inp{\ips{ba}}		\const{*VcdObs}	\const*{\textsc{Ident-IO}-[nas]}
	\cand{ba}		\vio{*!}	\vio{}
	\cand[\HandRight]{pa}	\vio{}		\vio{*}
	\end{tableau}
\end{center}

\noindent ...is produced by the following code...

\begin{verbatim}
	\begin{tableau}{c|c}
	\inp{\ips{ba}}         \const{*VcdObs}  \const*{\textsc{Ident-IO}-[nas]}
	\cand{ba}              \vio{*!}         \vio{}
	\cand[\HandRight]{pa}  \vio{}           \vio{*}
	\end{tableau}
\end{verbatim}

\subsection{Circled violations}
In one style of tableau, the optimal candidate's violations are circled. You can enabled this with the \verb+circledviolations+ package option. In this case, the optimal candidate must be marked with \verb+\Optimal+.

\CircledViolationsOn
\begin{center}
	\begin{tableau}{c|c}
	\inp{\ips{ba}}		\const{*VcdObs}	\const*{\textsc{Ident-IO}-[nas]}
	\cand{ba}		\vio{*!}	\vio{}
	\cand[\Optimal]{pa}	\vio{}		\vio{*}
	\end{tableau}
\end{center}
\CircledViolationsOff

\begin{verbatim}
	\begin{tableau}{c|c}
	\inp{\ips{ba}}           \const{*VcdObs}    \const*{\textsc{Ident-IO}-[nas]}
	\cand{ba}                \vio{*!}           \vio{}
	\cand[\Optimal]{pa}      \vio{}             \vio{*}
	\end{tableau}
\end{verbatim}

\subsection{Different symbols}
Using the optional argument to \verb+\cand+, you can add any annotation to a candidate. The following will be a trip down Memory Lane for some people:

\begin{center}
	\begin{tableau}{c|c}
	\inp{\ips{ba}}         \const{*VcdObs} \const*{\textsc{Ident-IO}-[nas]}
	\cand[(FFC)]{ba}       \vio{*!}        \vio{}
	\cand[\HandRight]{pa}  \vio{}          \vio{*}
	\cand[\ding{96}]{ta}   \vio{}          \vio{*}
	\cand[\HandLeft]{sa}   \vio{}          \vio{*}
	\end{tableau}
\end{center}

\noindent Generated by...

\begin{verbatim}
	\begin{tableau}{c|c}
	\inp{\ips{ba}}         \const{*VcdObs} \const*{\textsc{Ident-IO}-[nas]}
	\cand[(FFC)]{ba}       \vio{*!}        \vio{}
	\cand[\HandRight]{pa}  \vio{}          \vio{*}
	\cand[\ding{96}]{ta}   \vio{}          \vio{*}
	\cand[\HandLeft]{sa}   \vio{}          \vio{*}
	\end{tableau}
\end{verbatim}

You can mark the optimal candidate with the \verb+\Optimal+ command. By default, \tabl\ typesets \textsf{bbding}'s \verb+\HandRight+ symbol (\HandRight), which I find to be the most attractive. \tabl\ also replaces asterisks with the more attractive asterisks in \textsf{amssymb}. You can replace these symbols with others if you wish, using \verb+\renewcommand+:

\begin{center}
	\CircledViolationsOn
	\renewcommand\OptimalMarker{$\Cup$}
	\renewcommand\ViolationMarker{$+$}
	\renewcommand\CircledViolationMarker{$\boxplus$}
	\begin{tableau}{c|c}
	\inp{\ips{ba}}         \const{*VcdObs} \const*{\textsc{Ident-IO}-[nas]}
	\cand{ba}       \vio{*!}        \vio{}
	\cand[\Optimal]{ma}  \vio{}          \vio{*}
	\end{tableau}
	\CircledViolationsOff
\end{center}

\begin{verbatim}
	\renewcommand\OptimalMarker{$\Cup$}
	\renewcommand\ViolationMarker{$+$}
	\renewcommand\CircledViolationMarker{$\boxplus$}
	
	\begin{tableau}{c|c}
	\inp{\ips{ba}}         \const{*VcdObs} \const*{\textsc{Ident-IO}-[nas]}
	\cand{ba}              \vio{*!}        \vio{}
	\cand[\Optimal]{ma}    \vio{}          \vio{*}
	\end{tableau}
\end{verbatim}

\subsection{Prettier lines}
\textbf{As of 2021-05-19:} A conflict between \verb+hhline+ and \verb+arydshln+ means that it's not possible to have the prettier tableau lines that \verb+hhline+ offers. (Extra whitespace is introduced above the first line.) It's possible that this will be fixed in the future, in which case you can get the prettier lines back with the \verb+usehhline+ package option, e.g., \verb+\usepackage[notipa,usehhline]{ot-tableau}+.


\section{Package Options}
It makes the most sense to set these options as package options, but if you want to change the settings in the middle of the documents, you can use the commands indicated in parentheses.

\begin{description}
\item[notipa] With this option, the TIPA package will not be loaded, and text in the \verb+\cand+ argument will not be placed in a  \verb+\textipa+ command. Use this option if you are using Unicode input for IPA symbols. (\verb+\TipaOn+, \verb+\TipaOff+)
\item[circledviolations] Circle the optimal candidate's constraint violations. The optimal candidate must be identified with \verb+\cand[\Optimal]+. (\verb+\CircledViolationsOn+, \verb+\CircledViolationsOff+)
\item[shadedcells] Shade cells for a constraint that follow the candidate's fatal violation. (\verb+\ShadingOn+, \verb+\ShadingOff+)
\item[fingerafter] Place the finger-of-optimality after the letter rather than before it. (\verb+\FingerBeforeLetter+, \verb+\LetterBeforeFinger+)
\item[usehhline] Use the \verb+hhline+ package to draw prettier tableau lines. (As of 2021-05-19, a package conflict means that the lines are not actually prettier. Hopefully this will be fixed in the future and we can go back to pretty lines!)
\end{description}

\end{document}
