summaryrefslogtreecommitdiff
path: root/support/tab4tex/docs/tab4tex.tex
blob: 82bb98354562d8131cc37bb485f55cb81e9f7dfc (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
% 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}