% gnuplot_diffs.tex
%
% The documentation in this file is part of Pyxplot
% <http://www.pyxplot.org.uk>
%
% Copyright (C) 2006-2012 Dominic Ford <coders@pyxplot.org.uk>
%               2008-2012 Ross Church
%
% $Id: gnuplot_diffs.tex 1302 2012-09-05 17:30:27Z dcf21 $
%
% Pyxplot 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.
%
% You should have received a copy of the GNU General Public License along with
% Pyxplot; if not, write to the Free Software Foundation, Inc., 51 Franklin
% Street, Fifth Floor, Boston, MA  02110-1301, USA

% ----------------------------------------------------------------------------

% LaTeX source for the Pyxplot Users' Guide

\chapter{Summary of differences between Pyxplot and \gnuplot}
\chaptermark{Differences between Pyxplot \& \gnuplot}
\label{ch:gnuplot_diffs}

Pyxplot's command-line interface is based loosely upon that of \gnuplot, but
does not completely re-implement the entirety of \gnuplot's command language.
Moreover, Pyxplot's command language includes many extensions of \gnuplot's
interface. In this Appendix, we outline some of the most significant areas in
which \gnuplot\ and Pyxplot differ. This is far from an exhaustive list, but
may provide a useful reference for \gnuplot\ users.

\section{The typesetting of text}

Pyxplot renders all text labels automatically in the \latexdcf\ typesetting
environment. This brings many advantages: it produces neater labels than the
default typesetting engine used by \gnuplot, makes it straightforward to label
graphs with mathematical expressions, and moreover makes it straightforward
when importing graphs into \latexdcf\ documents to match the fonts used in figures
with those used in the main text of the document.  It does, however, also
necessarily introduce some incompatibility with \gnuplot.  Some strings which
are valid in \gnuplot\ are not valid in Pyxplot (see
Section~\ref{sec:latex_incompatibility} for more details). For
example,\index{latex}

\begin{dontdo}
set xlabel 'x\^{}2'
\end{dontdo}

\noindent is a valid label in \gnuplot, but is not valid input for \latexdcf\ and
therefore fails in Pyxplot.  In Pyxplot, it needs to be written in \latexdcf\
mathmode as:

\begin{dodo}
set xlabel '\$x\^{}2\$'
\end{dodo}

\noindent A useful introduction to \latexdcf's syntax can be found in Tobias
Oetiker's\index{Tobias Oetiker} excellent free tutorial, {\it The Not So Short
Guide to \latexdcf\ $2\epsilon$}\index{Not So Short Guide to \latexdcf\ $2\epsilon$,
The}, which is available for free download from:

\noindent \url{http://www.ctan.org/tex-archive/info/lshort/english/lshort.pdf}

Two built-in functions provide some assistance in generating \latexdcf\ labels.
The \indfunt{texify()} takes as its argument a string containing a mathematical
expression, and returns a \latexdcf\ representation of it.  The
\indfunt{texifyText()} takes as its argument a text string, and returns a
\latexdcf\ representation of it, with any necessary escape characters added. For
example:

\vspace{3mm}
\input{fragments/tex/fs_texify.tex}
\vspace{3mm}
Two built-in functions provide some assistance in generating \latexdcf\ labels.
The \indfunt{texify()} takes as its argument a string containing a mathematical
expression, and returns a \latexdcf\ representation of it.  The
\indfunt{texifyText()} takes as its argument a text string, and returns a
\latexdcf\ representation of it, with any necessary escape characters added. For
example:

\vspace{3mm}
\input{fragments/tex/fs_texify.tex}
\vspace{3mm}

\section{Complex numbers}

The syntax used for representing complex numbers in Pyxplot differs from that
used in \gnuplot. Whereas \gnuplot\ expects the real and imaginary components
of complex numbers to be represented {\tt \{a,b\}}, Pyxplot uses the syntax
{\tt a+b*i}, assuming that the variable {\tt i} has been defined to equal {\tt
sqrt(-1)}.  In addition, in Pyxplot complex arithmetic must first be enabled
using the {\tt set numerics complex} command before complex numbers may be
entered.  This is illustrated by the following example:

\vspace{3mm}
\noindent{\tt gnuplot> {\bf print \{1,2\} + \{3,4\}}}\newline
\noindent{\tt \{4.0, 6.0\}}
\vspace{3mm}\newline
\input{fragments/tex/gnu_complex.tex}
\vspace{3mm}

\section{The multiplot environment}

\gnuplot's multiplot environment, used for placing many graphs alongside one
another, is massively extended in Pyxplot.  As well as making it much easier to
produce galleries of plots and inset graphs, a wide range of vector graphs
objects can also be added to the multiplot canvas. This is described in detail
in Chapter~\ref{ch:vector_graphics}.

\section{Plots with multiple axes}

In \gnuplot, a maximum of two horizontal and two vertical axes may be
associated with each graph, placed in each case with one on either side of the
plot. These are referred to as the {\tt x} (bottom) and {\tt x2} (top), or {\tt
y} (left) and {\tt y2} (right) axes.  This behaviour is reproduced in Pyxplot,
and so the syntax

\begin{verbatim}
set x2label 'Axis label'
\end{verbatim}

\noindent works similarly in both programs. However, in Pyxplot the position of
each axis may be set individually using syntax such as

\begin{verbatim}
set axis x2 top
\end{verbatim}

\noindent and furthermore up to~128 axes may be placed parallel to one another:

\begin{verbatim}
set axis x127 top
set x127label "This is axis number 127"
\end{verbatim}

\noindent More details of how to configure axes can be found in
Section~\ref{sec:multiple_axes}.

\section{Plotting parametric functions}

The syntax used for plotting parametric functions differs between \gnuplot\ and
Pyxplot. Whereas parametric plotting is enabled in \gnuplot\ using the {\tt set
parametric} command, in Pyxplot it is enabled on a per-dataset basis by placing
the keyword {\tt parametric} before the algebraic expression to be plotted:

\vspace{3mm}
\noindent{\tt gnuplot> {\bf set parametric}}\newline
\noindent{\tt gnuplot> {\bf set trange [0:2*pi]}}\newline
\noindent{\tt gnuplot> {\bf plot sin(t),cos(t)}}
\vspace{3mm}\newline
\noindent\texttt{pyxplot> \textbf{set trange [0:2*pi]}}\newline
\noindent\texttt{pyxplot> \textbf{plot parametric sin(t):cos(t)}}
\vspace{3mm}

\noindent This makes it straightforward to plot parametric functions alongside
non-parametric functions. For more information, see
Section~\ref{sec:parametric_plotting}.

%\section{Displaying Times and Dates on Axes}

