\documentclass{article}

\marginparwidth 0pt
\oddsidemargin  0pt
\evensidemargin  0pt
\marginparsep 0pt

\parindent 0pt

\topmargin   0pt

\textwidth   6.5in
\textheight  8.5 in

\usepackage{a4}
\usepackage{camtex}
\usepackage{verbatim}

\def\aspas#1{``#1''}
\def\camila{{\sc Camila}}
\def\camtex{{\sc Cam}\TeX}
\def\enlist#1{\mathopen{<}#1\mathclose{>}} % <a,b,...z>
\def\deff{\stackrel{\rm def}{=}}          % function definition symbol

\title
{
    \camtex\ Users Guide
}
\author
{
    Jos\'{e} Jo\~{a}o Almeida
    \thanks
    {
        Email: jj@di.uminho.pt;
        Http: http://www.di.uminho.pt/$\sim$jj
    }
        { }
        and
    Jos\'{e} N. Oliveira
    \thanks
    {
        Email: jno@di.uminho.pt;
        Http: http://www.di.uminho.pt/$\sim$jno
    }
        { }
        and
    F. Lu\'{\i}s Neves
    \thanks
    {
        Email: fln@di.uminho.pt;
        Http: http://s700.uminho.pt/$\sim$fln
    }
    \\ \\
    {\sc Inesc} Group 2361 and Dep.\ Inform\'{a}tica, Universidade do Minho \\
    Campus de Gualtar, 4700 Braga, Portugal \\
        Tel: 351+53-604470\\
        Fax: 351+53-612954
}
\date\today

\begin{document} 

\maketitle

\section{Introduction}

\camtex\ is a sofwatre package merging \LaTeX\ document processing with
the \camila\ rapid prototyping environment.
Its main purpose is to provide for
the incorporation of \camila\ expression evaluations
into \LaTeX\ documents. There are two ways of achieving this:

\begin{enumerate}
\item by loading a \camila\ prototype and then using its available
      functionality;
\item by direct invocation of \camila\ expressions.
\end{enumerate}

\noindent
These two methods are explained in detail in the next sections.

\section{How to Install \camtex}

To install \camtex\ in your machine follow the next instructions:

\begin{enumerate}
\item download the \camtex\ package from
      http://camila.di.uminho.pt/camila-bin/camtex.tgz
\item execute the following command (or equivalent):
      \emph{tar -zxvf camtex.tgz}
\end{enumerate}

You should obtain a (new) directory \texttt{camtex} in your file system
including the following files:

\begin{description}
\item[camtex] -  a  perl file;
\item[camtex.sty] -  a  \LaTeX\ style;
\item[usersguide.tex] - this file.
\end{description}

\subsection{Important Note}

In order to use \camtex\ it is necessary to have the following executable
files installed in your machine:

\begin{itemize}
\item camila
\item camilax
\item jjpretty
\item perl
\end{itemize}

\subsection{How to Execute \camtex}

\camtex\ is a two-phase compilation pre-processor for \LaTeX\ following
the Bib\TeX\ tradition.

Let us suppose you have a file called \emph{example.tex}
embedeed with \camtex\ commands
(in a way which will be described later).
All you have to do is to 
execute the following lines at the command prompt:

\begin{enumerate}
\item latex example
\item camtex example (or perl camtex example)
\item latex example
\end{enumerate}

\section{About the \camtex\ Style}

In order to use \camtex\ you should include the \camtex\ package
in your document by doing:

\begin{verbatim}
\usepackage{camtex}
\end{verbatim}

or

\begin{verbatim}
\documentstyle[camtex]{article}
\end{verbatim}

\section{Loading CAMILA Prototypes}

In normal \camtex, the first thing to do is to load a prototype.
It has no side-effect on the output. One simply writes:

\begin{verbatim}
\prototype{stack}
\end{verbatim}
\prototype{stack}

This command loads a camila program named ``stack.cam'' containing functions
and state definitions to be used in the text.

There is a little difference, spot where
(CR-LF problems are well-known in \LaTeX).

\section{How to prettyprint \camila\ in \LaTeX}

The simplest way of integrating \camila\ specifications
in \LaTeX\ text is provided by \camtex\ \verb@\campretty@ macro.

For example:
\begin{verbatim}
 \campretty{f(x) = x U { y | y<-  {1,3,5} /\ y >= 2} }
\end{verbatim}

produce:

 \campretty{f(x) = x U { y | y<-  {1,3,5} /\ y >= 2} }

\section{How to Embed \camila\ Expresssions into \LaTeX}

The simplest way of integrating \camila\ expression evaluations
into \LaTeX\ text is provided by \camtex\ \verb@\cameval@ macro.

For example, we all know that $2 + 3$ equals $\cameval{2 .+ 3}$.
Let us export $2 + 3$ from \camila:
\begin{verbatim}
For example, we all know that $2 + 3$ equals $\cameval{2 .+ 3}$.
\end{verbatim}
This is precisely what we wrote above.
But we might have written
\begin{verbatim}
For example, we all know that $2 + 3$ equals $\cameval{length(< 1,2,3,4,5>)}$.
\end{verbatim}
because the length of sequence $\enlist{1,2,3,4,5}$ is
$\cameval{length(< 1,2,3,4,5>)}$.

Now suppose that we want to declare a function $square(x)\deff x\times x$
computing the \cameval{square(x)=x.*x}
% \cameval{FUNC square(x:INT):INT RETURN x.*x}
of a number and show that $square(11)$ is $\cameval{square(11)}$.
A \camila\ session fragment for this might have been
\begin{verbatim}
?- square(x)=x.*x;
square 
?- square(11);
121 
?- 
\end{verbatim}

In fact, we have embedded this session in the text above, cf:
\begin{verbatim}
computing the \cameval{square(x)=x.*x}
of a number and show that $square(11)$ is $\cameval{square(11)}$.
\end{verbatim}
This works because the \aspas{result} of declaration {\tt square(x)=x.*x}
is the {\tt square} string. 

%xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Now a simple \emph{cameval} example:
\cameval{ do(s <- < 1,2,3,4,5>, length(s)) }
perfectly integrated in the sentence.
Look to what we wrote for the effect above:

\begin{verbatim}
 Now a simple cameval example : \cameval{ do(s <- < 1,2,3,4,5>, length(s)) }
 perfectly integrated in the sentence.
\end{verbatim}

%For a purely imperative command, scrap the output by using \LaTeX's
%\verb@ \def@:
%\def\lixo{\cameval{INIT()}}

%\begin{verbatim}
%\def\lixo{\cameval{INIT()}}
%\end{verbatim}

%IMHO it is better to simply write: 
%...\cameval{do(INIT(),"")}...
%
%\begin{verbatim}
%...\cameval{do(INIT(),"")}...
%\end{verbatim}

%(the result of the expression is the null string).

Now embedded \verb@\cameval@s:
\begin{eqnarray}
\cameval{do(x <- 2 ,  x <- x ./ x, if x==[] then "a" ++ itoa(x) else "c") } &=&
\cameval{ x .* 12  }
\end{eqnarray}

This was made with:
\begin{verbatim}
\begin{eqnarray}
\cameval{do(x <- 2 ,  x <- x ./ x, if x==[] then "a" ++ itoa(x) else "c") } &=&
\cameval{ x .* 12  }
\end{eqnarray}
\end{verbatim}

Long \verb@\cameval@s are also ok,
\[
\cameval{do (INIT(),

         x <- {  } ,

         if x=="2" then a U b else c,

         [k-> k .+ 1  | k <- inseg(5) ]    )
}
\]

And finally, \verb@\caminput@s:

\caminput{/* INIT(); */
          x <- { 10, 15 };
          if x == {} then princ("The set is empty!")
                     else princ("The result is ",add-orio(0,x)); }

produced by

\begin{verbatim}
\caminput{/* INIT(); */
          x <- { 10, 15 };
          if x == {} then princ("The set is empty!")
                     else princ("The result is ",add-orio(0,x)); }
\end{verbatim}

and also \verb@\camvinput@s (verbatim input):

\camvinput{/* INIT(); */
           a <- "Anything...";
           b <- "Current date: \today";
           x <- { < a, b > };
           pp(x);
           pp(a);
           pp(b);
           pp("");
           pp(x); }

produced by

\begin{verbatim}
\camvinput{/* INIT(); */
           a <- "Anything...";
           b <- "Current date: \today";
           x <- { < a, b > };
           pp(x);
           pp(a);
           pp(b);
           pp("");
           pp(x); }
\end{verbatim}



Recall that the outputs of \verb@\cameval@ or \verb@\caminput@
directives should be proper \TeX\ sentences. 

\section{Known Bugs}

Beware: \verb@\cameval@ and \verb@\caminput@ don't like \verb@%@ in the camila
parameter!

Beware2: they also have problems with \verb@"-@ pair! (I don't understand why
but \LaTeX susbstitute that by a lot of macros!)

\end{document} 
