path: root/support/tab4tex/docs/tab4tex.tex

% Tab4tex documentation
% Version 0.1
% March 2007
% Guido Milanese - guido.milanese@unicatt.it

\documentclass[a4paper,english]{article}
\usepackage[T1]{fontenc}
\usepackage[utf8x]{inputenc}
\IfFileExists{url.sty}{\usepackage{url}}
                      {\newcommand{\url}{\texttt}}
\usepackage{babel}

\begin{document}

\title{tab4tex\\
Version 0.1}


\author{Guido Milanese\\
\url{guido.milanese@unicatt.it}}


\thispagestyle{empty}
\date{March 2007}
\maketitle
\begin{abstract}
\noindent{}This utility helps to prepare tables to be used in
\LaTeX{}.
The programs are written in Snobol4; the only requirement is to install the
interpreter. For Windows, a standalone file compiled with Spitbol is also
provided, and the programs can be run without the need of an external
interpreter.
\end{abstract}

\tableofcontents

\section{The program}

The program \textsf{tab4tex} reads from the standard input a text file and
outputs a table formatted according to the requirements of the environment
\textsf{tabular}.
It is possible to output a table that can be pasted or included in a complete
\LaTeX{} file or to output a complete standalone \LaTeX{} file.

Some basic formatting aids are provided. Refined features can be added later in
the \LaTeX{} code.

The program must be run as follows:

\begin{center}
		  \texttt{snobol4 -b tab4tex.sno [options] <inputfile >outputfile}
\end{center}

\noindent{}If compiled or from a script:

\begin{center}
		  \texttt{tab4tex [options] <inputfile >outputfile}
\end{center}

Options are:

\begin{description}
					 \item[a]	align (center,left,right)
					 \item[r]	number of rows
					 \item[b]	vertical bar (y/n)
					 \item[c]	complete \LaTeX{} document (y/n)
					 \item[h]	hline (y/n)
\end{description}

First and second argument are compulsory, 3rd, 4th and 5th optional (simple y/n
choice). For example use \texttt{c=y} if you want a complete \LaTeX{} document,
\textsf{c=n} if you want just a table to include in your document.


See the next section for some examples.

\section{Examples and formatting aids}
\subsection{A simple example}
This is file \textsf{test1} provided in the package:

\begin{center}
  \begin{verbatim}
  <M5>*Animals and friends*
  <E>      <M2>!Cats!      <M2>!Dogs!
  <E>      ^John^ ^Martha^ ^John^ ^Martha^
  *Black*    2      5        5      0
  *White*    4      1        0      5
  *Red*      2      1        <M2>Not known
  \end{verbatim}
\end{center}


These lines are very simple:

\begin{verbatim}
*Black*    2      5        5      0
*White*    4      1        0      5
\end{verbatim}

Each line is a row and cells are separated by tabs. Please notice:
\emph{tabs}, not empty spaces.

The asterisks are used to produce bold text in the \LaTeX{} output. The program
provides this simple encoding:

\begin{quote}
		  \begin{tabular}{ll}
					 *cell*	      & produces \textbf{cell}\\
					 !cell!	      & produces \emph{cell}\\
					 \^{}cell\^{}  & produces \textsc{cell}\\
		  \end{tabular}
\end{quote}

The third line uses \texttt{<E>}, meaning \emph{empty cell}:
\begin{center}
		  \begin{verbatim}
		  <E>      ^John^ ^Martha^ ^John^ ^Martha^
		  \end{verbatim}
\end{center}

Empty cells must be separated from the following ones as normal cells are, i.e.
using a tab. Please notice: \emph{tabs}, not empty spaces. In this line, observe
the use of \texttt{\^{}} to obtain small caps in the \LaTeX{} output.

The second and the last row are using multicolumns, i.e. the text is expanded in
two ore more cells:

\begin{center}
		  \begin{verbatim}
		  <E>        <M2>!Cats!      <M2>!Dogs!
		  *Red*      2      1      <M2>Not known
		  \end{verbatim}
\end{center}

The program uses a simple encoding to obtain a multicols output:  precede the
string with \texttt{<M[number]>}, as in the above example.  Multicols cells must
be separated from the following ones as normal cells are, i.e.  using a tab.
Please notice: \emph{tabs}, not empty spaces. Observe the use of \texttt{!} to
obtain italics in the \LaTeX{} output.

This is the final output:

\footnotesize%
\begin{verbatim}
\begin{tabular}{|c|c|c|c|c|}	
		  \hline
		  \multicolumn{5}{|c|}{\textbf{Animals and friends}}	\\	
		  \hline
		  &	\multicolumn{2}{|c|}{\emph{Cats}}	&	\multicolumn{2}{|c|}{\emph{Dogs}}	\\	
		  \hline
		  &	\textsc{John}	&	\textsc{Martha}	&	\textsc{John}	&	\textsc{Martha}	\\	
		  \hline
		  \textbf{Black}	&	2	&	5	&	5	&	0	\\	
		  \hline
		  \textbf{White}	&	4	&	1	&	0	&	5	\\	
		  \hline
		  \textbf{Red}	&	2	&	1	&	\multicolumn{2}{|c|}{Not known}	\\	
		  \hline
\end{tabular}
\end{verbatim}
\normalsize%

This output was obtained with the following command line:

\begin{center}
		  \begin{verbatim}
		  snobol4 -b tab4tex.sno r=5 a=c b=y h=y c=n <test1.txt >test1.tex
		  \end{verbatim}
\end{center}

The options used are:

\begin{itemize}
		  \item \texttt{r=5} The number of rows.
		  \item \texttt{a=c} Cells are centered
		  \item \texttt{b=y} Vertical bar
		  \item \texttt{h=y} Horizontal bar
		  \item \texttt{c=n} Do not output a standalone \LaTeX{} file
\end{itemize}

Please notice that only the first two options must be entered. If you answer
``no'' to any other option, you can simply omit it.

\subsection{A more complex example}

This example is a bit more complex%
\footnote{The table is quoted from
\url{http://www.maths.tcd.ie/~dwilkins/latexprimer/tables.html}. To see the real
file provided in the package set tabs at 12 or similar values and use a fixed
font.}. This is the input file:


\begin{verbatim}
<E>          <M2>Singular       <M2>Plural
<E>          English *Gaeilge*  *English* *Gaeilge*
1st Person   at me   *agam*     at us     *againn*
2nd Person   at you  *agat*     at you    *agaibh*
3rd Person   at him  *aige*     at them   *acu*
<E>          at her  *aici*     <E>        <E>
\end{verbatim}

The file combines empty cells and formatting instructions. This is the output:

\footnotesize%
\begin{verbatim}
\begin{tabular}{|l|l|l|l|l|}	
		  \hline
		  &	\multicolumn{2}{|l|}{Singular}	&	\multicolumn{2}{|l|}{Plural}	\\	
		  \hline
		  &	English	&	\textbf{Gaeilge}	&	\textbf{English}	&	\textbf{Gaeilge}	\\	
		  \hline
		  1st Person	&	at me	&	\textbf{agam}	&	at us	&	\textbf{againn}	\\	
		  \hline
		  2nd Person	&	at you	&	\textbf{agat}	&	at you	&	\textbf{agaibh}	\\	
		  \hline
		  3rd Person	&	at him	&	\textbf{aige}	&	at them	&	\textbf{acu}	\\	
		  \hline
		  &	at her	&	\textbf{aici}	&	 	&	 	\\	
		  \hline
\end{tabular}
\end{verbatim}
\normalsize%

The output was obtained with the following command line:
\begin{center}
		  \begin{verbatim}
		  snobol4 -b tab4tex.sno r=5 a=l b=y h=y c=n <test2.txt >test2.tex
		  \end{verbatim}
\end{center}

Notice that this time we have used \texttt{a=l} and not \texttt{a=c}, so cells
will not be centered but left aligned.


\section{Installation}

\subsection{GNU/Linux and other {*}nix systems}

\begin{enumerate}
		  \item Install \textsf{snobol4} from \url{http://www.snobol4.org}. This is Philip Budne's
		  CSNOBOL implementation. You need a \texttt{c} compiler to compile the
		  interpreter; it's normally a very quick and easy process.
\item Make sure \textsf{snobol4} is in your PATH or make a symbolic link.
\end{enumerate}

You can now run the program as follows:
\begin{center}
		  \begin{verbatim}
		  snobol4 -b tab4tex.sno [OPTIONS] <input >output
		  \end{verbatim}
\end{center}

If you prefer to avoid some typing, write the following line as first line of
the program:

\begin{center}
		  \begin{verbatim}
		  #!/usr/local/bin/snobol4 -b
		  \end{verbatim}
\end{center}

Adapt accordingly to your installation, e.g.

\begin{center}
		  \begin{verbatim}
		  #!/usr/bin/snobol4 -b
		  \end{verbatim}
\end{center}

Make the file \textsf{tab4tex.sno} executable, e.g. \texttt{chmod +x tab4tex.sno}

Run the program as follows:
		  \texttt{./tab4tex.sno [options] <input >output}\\
If the current directory is in your PATH, you do not need \texttt{./}
before the program name.

\subsection{Windows}

The package offers an executable file compiled with Spitbol (see
\url{http://www.snobol4.com}), a powerful commercial Windows version of Snobol.
Make a directory and copy all the file provided in the \textsf{bin/windows}
directory. There must be one \texttt{exe} file and two \texttt{test{*}} files.

Run the programs as follows:

\begin{center}
		  \texttt{tab4tex [options] <input >output}\\
\end{center}


\subsection{Windows from source}

Basically, follow the same directions given about GNU/Linux, but make sure to
use the \texttt{bat} files and to install the Windows version of the interpreter.
Before using the sources, that are in Unix format, use a script to translate
from Unix to Dos-Windows format. If you do not have such a script, open the
files with a text editor and save the sources in Windows-Dos format. This can be
done reading and saving each file with the DOS \textsf{edit} program, with
\textsf{vim} or any other editor able to deal with different file formats.
\subsection{Cygwin}

I suggest to follow the same directions given for GNU/Linux, but the
EXE files provided for native Windows can be used anyway if preferred. 

\subsection{Macintosh}
Not yet tested (I do not have a Mac right now). It's in the TODO list.

\section{Test files}
Please test the program on \textsf{test1.txt} and \textsf{test2.txt}.

\section{Reference}

\begin{tabular}{ll}
\multicolumn{2}{l}{OPTIONS}     \\
a       &       align (center,left,right)       \\
b       &       vertical bar (y/n)      \\
c       &       complete LaTeX document (y/n)   \\
h       &       hline (y/n)     \\
r       &       rows    \\
\end{tabular}

\noindent{}\begin{tabular}{lll}
\multicolumn{3}{l}{FORMATTING CODES}    \\
*cell*       &       produces \textbf{cell}  &       bold    \\
!cell!       &       produces \emph{cell}    &       italics \\
\^{}cell\^{} &       produces \textsc{cell}  &       small caps      \\
\end{tabular}

\section{Bugs and TODO}

List of features that I would like to add:

\begin{enumerate}
		  \item Escape sequences for \textsf{<E>} and formatting codes
					 (\textsf{!*\^{}}). 
\item Better support for multicol
\item Use of tabularx and longtab
\item Some more formatting aids.
\end{enumerate}

\section{Acknowledgements}
My warmest thanks to \textsc{Phil Budne} (\url{phil@ultimate.com}) for making
his excellent CSNOBOL available. Many thanks to the community of Snobol users,
particularly to the members of the Yahoo Snobol group
\url{http://tech.groups.yahoo.com/group/snobol}, and,
among them, to \textsc{Gordon Peterson} (\url{http://personal.terabites.com/}),
\textsc{Michael Radow} (\url{mikeradow@yahoo.com}), \textsc{Gregory L. White}
(\url{glwhite@netconnect.com.au}) and to \textsc{Rafal M. Sulejman}
(\url{rafal@engelsinfo.de}) whose \textsf{vim} syntax files are a daily
blessing.


\section{Author, copyright, license, disclaimer}

This program is Copyright \copyright{} 2007\\
Guido Milanese <\url{guido.milanese@unicatt.it}>\\
under the terms of the GNU General Public License.\\

\footnotesize{}
		  \begin{verbatim}
This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details.

If you do not have a copy of the GNU General Public License write to the Free
Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

If the author of this software was too lazy to include the full GPL text along
with the code, you can find it at: http://www.gnu.org/copyleft/gpl.html.
\end{verbatim}
\normalsize{}

\end{document}