\documentclass[12pt,a4paper]{article}
\usepackage[latin1]{inputenc}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{amssymb}
\usepackage{makeidx}
\usepackage{graphics}
\author{Felip Alàez Nadal}
\title{CGN User Manual}
\begin{document}
\maketitle
\newpage
\tableofcontents
\newpage
\section{Introduction}
Cgn is a library to control gnuplot from Lisp. Initially thought as simply a pipe to comunicate with gnuplot, It has grown to provide sintactic sugar for the most common operations on Gnuplot: plotting graphics, printing, saving/loading...

Cgn has become big enough to need a manual for itself. It comes here. I hope It to be useful. You can also see the examples at cgn's web at http://common-lisp.net/project/nixies

\subsection{Asking and contributing to cgn}
There's a mail list for cgn at common-lisp.net. You can also mail me at superratoli@gmail.com. 

Contributions to cgn are welcome. Just send me them and I'll add them to cgn. 

\subsection{No warranty}
    cgn
    Copyright (C) Felip Alàez Nadal 2006-2007

    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.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Steet, Fifth Floor, Boston, MA  02111-1307  USA

\section{Plotting functions}
Cgn supports 2D and 3D plotting, with automatic reconigzation of parametrized functions. This means that you don't have to care about what code to use, just use (plot-function what-function ) and cgn will generate all the code needed to do what you want. By example:

(plot-function "cos(x)" )

%He de posar totes aquestes figures al seu lloc, quan sapiga com es fa
\begin{figure}
    \begin{center}
      \resizebox{120mm}{!}{\includegraphics{cos_x.png}}
      \caption{cos(x)}
      \label{test}
    \end{center}
  \end{figure}


(plot-function "cos(t),sin(t)" )

\begin{figure}
    \begin{center}
      \resizebox{120mm}{!}{\includegraphics{cos_t_sin_t.png}}
      \caption{A circle}
      \label{test}
    \end{center}
  \end{figure}


(plot-function "x*y*cos(x*y)")

\begin{figure}
    \begin{center}
      \resizebox{120mm}{!}{\includegraphics{multid.png}}
      \caption{A f(x,y) function}
      \label{test}
    \end{center}
  \end{figure}

(plot-function "sin(u), cos(u) , v " )

\begin{figure}
    \begin{center}
      \resizebox{120mm}{!}{\includegraphics{cilindre.png}}
      \caption{A beautiful cilinder}
      \label{test}
    \end{center}
  \end{figure}

\section{Plotting scatter graphics}
Cgn can create scatter graphics to do that, first of all you must create a scatter-graphic description for your graphic, with:

create-scatter-graphic-description title

and then use It to create data series with

create-scatter-data-serie (sc scatter-graphic) x y x\_error y\_error  title 

where x, y, x\_error and y\_error are lists. Title is the title for the data serie.

At last, plot your description with plot-scatter scatter-graphic .


\textit{Example: create an scatter graphic with points from experiment1: (1,2) , (2,3), (3,4) without errorbars and points from experiment2: (2.5,1) , (3.1,2), (4.5, 7) ,(8,9) with a 10\% of error for x and y.}

\begin{verbatim}
(setq sc (create-scatter-graphic-description "Our experiments"))

(create-scatter-data-serie sc '(1 2 3) '(2 3 4) '(0 0 0) 
			'(0 0 0 ) "Experiment1")

(create-scatter-data-serie sc '(2.5 3.1  4.5 8) '(1 2 7 9)
			 '(0.25 0.31 0.45 0.8) '(0.1 0.2 0.7 0.9) "Experiment2")

(plot-scatter-graphic sc)

\end{verbatim}
\begin{figure}
    \begin{center}
      \resizebox{120mm}{!}{\includegraphics{scatter.png}}
      \caption{A scatter graphic}
      \label{test}
    \end{center}
  \end{figure}

\section{Configuring gnuplot}
Cgn can do some personalization of gnuplot for you. At the moment:

\begin{verbatim}
set-grid    on-off
   set-range    eix min max
   set-title    text
\end{verbatim}


\section{Printing}
Cgn can print directly from gnuplot. To do that, It needs to know what operative system is running\footnote{This is only until release 007. Release 008 can determinate which os is running without the help of the user.} . Just use:
\begin{verbatim}
print-graphic   &optional (os *os*)
\end{verbatim}

os must be set to 'w32\footnote{There's an easy trick to conditionally set *os* to the correct symbol. Just (if (member :win32 *features*) (setq *os* 'w32) (setq *os* 'another)). This code was written for cgn 008, but It's not included in It because I don't know If works everywhere. I've tried It with sbcl and clisp and works. Please, if you've tried It with another lisp for windows, send me a mail to superratoli@gmail.com and this code will be included in cgn 009.} on windows. For non-windows machines, you can use whatever symbol except 'w32: linux, unix, my-beautiful-machine, etc...
\section{Saving/loading}

Cgn can save a gnuplot session to a file, and It can load It later. You have to understand that cgn does not save nothing. It's gnuplot who saves the session. Then, when you load the saved session, you can restore gnuplot's status (plotted functions, title, etc...), but not cgn's status. 

To save use:
\begin{verbatim}
save-cgn    file
\end{verbatim}
And to load:
\begin{verbatim}
load-cgn    file
\end{verbatim}

\section{Creating animations}
Since cgn 008, cgn can create animations. To do that, simply use \textit{(animate-function what-function what-parameter initial-value increments number-of-frames  rapidity)}. 

\section{Debugging cgn}
Since cgn 008, debugging is supported. You shouldn't enable debug for a normal use. Enable It only if you are developing some kind of extension to cgn. To enable debug, just use:
\begin{verbatim}
(enable-debug)
\end{verbatim}

And to disable It:
\begin{verbatim}
(disable-debug)
\end{verbatim}

With debug enabled, cgn will print to *standard-output* everything that It sends to gnuplot.
\section{Inside Cgn}
Basically, cgn is constructed over two different parts:
\begin{itemize}
\item A pipe that can comunicate with gnuplot and a function to send messages to It and
\item Lots of Lisp functions wrapping the most common operations you can do with gnuplot.
\end{itemize}

Cgn uses Ltk for the pipe issue. Ltk is a graphical toolkit for Lisp that uses a pipe to communicate with Tk\footnote{Tk is the Tcl ToolKit. It's an interpreter that, when called without arguments, waits for code on standard input. Ltk just creates the Tk code needed to create windows, buttons, etc...  }. It runs everywhere a Lisp implementation exists and is well supported and mantained. It provides a function that creates a pipe and returns a stream to the executed program. But with 2 goodies: It's mantained by other people than me ( less work for me) and wraps code for lots of different Lisp implementations. Using It, cgn works everywhere. 

\subsection{Extending Cgn}
It's easy to extend cgn. Everything you have to do is create a new function that sends to gnuplot the code that fills your needs, using format-gnuplot. format-gnuplot is just like format, but provides some features like debuggind. It also makes sure that gnuplot executes the command you send.

The first thing you have to do is creating a package for putting your code in It:

\begin{verbatim}

(defpackage :extending-cgn-example
	(:use :cl :cl-user :cgn)
	(:export #:set-property))

(in-package :extending-cgn-example)
\end{verbatim}

To extend cgn It's not necessary create classes. You just have to write functions that send the code that fills your needs. At this example, we face a very common problem: there are lots of flags that control the behaviour of gnuplot. Cgn doesn't have functions to set all of them. Well, now we're gonna write a function to set all the flags that don't need paramethers. 

First of all, we study what the generated code will seem:

\textit{set timestamp}

\textit{set arrow}

\textit{...}

It becomes clear that this function will do the work:

\begin{verbatim}
(defun set-property ( property )
	(format-gnuplot "set ~A" property ))
\end{verbatim}

Now we can test this function and see what It happens:

\begin{verbatim}
* (start-gnuplot)
* (enable-debug)
T
* (plot-function "cos(x)")
plot cos(x)
* (set-property "timestamp")
set timestamp
* (plot-function "sin(x)")
plot sin(x)
\end{verbatim}
\begin{figure}
    \begin{center}
      \resizebox{120mm}{!}{\includegraphics{extending_1.png}}
      \caption{Before calling set-property}
      \label{test}
    \end{center}
  \end{figure}

\begin{figure}
    \begin{center}
      \resizebox{120mm}{!}{\includegraphics{extending_2.png}}
      \caption{After calling set-property. Watch the timestamp.}
      \label{test}
    \end{center}
  \end{figure}
\section{Seeing release info}
Just type 

\begin{verbatim}
(show-release-info)
\end{verbatim}
And you'll see something like this:

cgn 008 released 9-II-07
\section{Changelog}
\begin{list}{}{}
\item 9-II-07: cgn 008
\begin{list}{}{}

\item Added plot-scatter
\item Added create-scatter-data-serie
\item Added create-scatter-graphic-description
\item Added new structures : data-serie and scatter-graphic, to save
	 information about scatter graphics.
\item Added show-release-info.
\item Added two new flags: *release* and *release-date*.
\item format-gnuplot now does debug if debugging is enabled.
\item Added enable-debug and disable-debug.
\item Added *debug*, a flag to control if cgn must do debug.
\item All the library has been updated to use the new format-gnuplot facilities.
\item Format-gnuplot now understands all the options that format can understand.
\item Replot-function now can replot every type of functions.
\item Created a new manual for Cgn.
\item Animate-function now can create animations for whatever type of
	 function, only for one paramether.
\item Added animate-function, to create animations. At the moment, only
	 for f(x), and one paramether.
\item plot-function now plots using the parametric form.
\end{list}
\item 20-VI-06: cgn 007 
\begin{list}{}{}
\item Added print-graphic, to print directly from cgn.
\item Modified plot-function. Now can be used to plot g(x,y), not
	only f(x).
\item  Added save-cgn, to save.
\item Added load-cgn, to load.
\item Added with-gnuplot, a macro which should be the prefered way
	to use cgn. 
\item Added the *os* special variable, to use with with-gnuplot to let cgn
	  know which os is running. This is used to print, at the moment.
\item Updated cldoc documentation.
\end{list}
\item 8-VI-06: cgn 006
\begin{list}{}{}
\item Corrected bug. Gnuplot keeped running later of using close-gnuplot.
\item Comments now translated to English. It seems that the
	original Catalonian documentation produced slow compilations
	at non Catalonian machines.
\item Added cldoc documentation.
\end{list}


\end{list}

\section{Bibliography}

\end{document}