% configuration.newst
%
% 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: configuration.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{Configuring Pyxplot}
\label{ch:configuration}

\renewcommand{\arraystretch}{1.80}

In Parts~I and~II, we encountered numerous configuration options within Pyxplot
which can controlled using the \indcmdt{set}. There are times, however, when
many plots are wanted in a homogeneous style, or when a single plot is
repeatedly generated, when it is desirable to change the default set of
configuration options with which Pyxplot starts up, in order to avoid having to
repeated enter a large number of {\tt set} commands. In this chapter, we
describe the use of configuration files to program Pyxplot's default state.

\section{Configuration files}

Configuration files for Pyxplot have the filename {\tt .pyxplotrc}, and may be
placed either in a user's home directory, in which case they globally affect
all of that user's Pyxplot sessions, or in particular directories, in which
case they only affect Pyxplot sessions which are instantiated with that
particular directory as the current working directory.  When configuration
files are present in both locations, both are read; settings found in the {\tt
.pyxplotrc} file in the current working directory take precedence over those
found in the user's home directory. Configuration files are read only once,
upon startup, and subsequent changes to the configuration files do not affect
copies of Pyxplot which are already running.

Changes to settings made in configuration files affect not only the values that
these settings have upon startup; they also changes the values to which the
\indcmdt{unset} returns settings. Thus, whilst the command
\begin{verbatim}
unset multiplot
\end{verbatim}
ordinarily turns off multiplot mode, it may turn it on if a configuration file
contains the line
\begin{verbatim}
multiPlot=on
\end{verbatim}
When colored terminal output is enabled, the color-coding of the
\indcmdt{show} also reflects the current default configuration: settings which
match their default values are shown in green\footnote{This color can be
changed using the {\tt color\_rep} setting in a configuration file.} whilst
those settings which have been changed from their default values are shown in
amber\footnote{This color can be changed using the {\tt color\_wrn} setting
in a configuration file.}.

Configuration files should take the form of a series of sections, each headed
by a section heading enclosed in square brackets. Each section heading should
be followed by a series of settings, which often take the form of
\begin{verbatim}
setting_name = value
\end{verbatim}
In {\it most} cases, neither the setting name nor the value are case sensitive.

The following sections are used, although they do not all need to be present in
any given file, and they may appear in any order:

\begin{itemize}
\item {\tt colors} -- contains a single setting {\tt palette}, which should be
set to a comma-separated list of colors which should make up the palette used
to plot datasets. The first will be called color~1 in Pyxplot, the second
color~2, etc. A list of recognised color names is given in
Section~\ref{sec:color_names}.
\item {\tt filters} -- can be used to define input filters which should be used
for certain file types (see Section~\ref{sec:filters}).
\item {\tt functions} -- contains user-defined function definitions which
become predefined in Pyxplot's mathematical environment, for example
\begin{verbatim}
sinc(x) = sin(x)/(x)
\end{verbatim}
\item {\tt latex} -- contains a single setting {\tt preamble}, which is
prefixed to the beginning of all \latexdcf\ text items, before the {\tt
\textbackslash begin\{document\}} statement. It can be used to define custom
\latexdcf\ macros or to include packages using the {\tt \textbackslash
includepackage\{\}} command.  The preamble can be also changed using the
\indcmdt{set preamble}.
\item {\tt script} -- can contain a list of \indcmdt{set}s, using the same
syntax which would be used to enter them at a Pyxplot command prompt. This
section provides an alternative and more general way of controlling the
settings which can be changed in the {\tt settings} section. Note that this
section may only contain instances of the \indcmdt{set}; other Pyxplot
commands may not be used. The \indcmdt{set}'s {\tt item} modifier may not be
used.
\item {\tt settings} -- contains settings similar to those which can be set
with the \indcmdt{set}. A complete list is given in
Section~\ref{sec:configfile_settings} below.
\item {\tt styling} -- contains settings which control various detailed aspects
of the graphical output which Pyxplot produces. These settings cannot be
accessed by any other means.
\item {\tt terminal} -- contains settings for altering the behaviour and
appearance of Pyxplot's interactive terminal. These cannot be changed with the
\indcmdt{set}, and can only be controlled via configuration files. A complete
list of the available settings is given in
Section~\ref{sec:configfile_terminal}.
\item {\tt units} -- can be used to define new physical units for use in
Pyxplot's mathematical environment.
\item {\tt variables} -- contains variable definitions, in the format
\begin{verbatim}
variable = value
\end{verbatim}
Any variables defined in this section will be pre-defined in Pyxplot's
mathematical environment upon startup.

\end{itemize}

\section{An example configuration file}
\index{configuration files}

\noindent The following configuration file represents Pyxplot's default
configuration, and provides a useful index to all of the settings which are
available. In subsequent sections, we describe the effect of each setting in
detail.

%Projection = Flat
\begin{verbatim}
[settings]
aspect = auto
axesColor = black
axisUnitStyle = ratio
backup = off
bar = 1.0
binOrigin = auto
binWidth = auto
boxFrom = auto
boxWidth = auto
calendarIn = British
calendarOut = British
clip = off
colKey = on
colKeyPos = Right
color = on
contours = 12
c1Range_log = false
c1Range_max = 0
c1Range_max_Auto = true
c1Range_min = 0
c1Range_min_Auto = true
c1Range_renorm = true
c1Range_reverse = false
c2Range_log = false
c2Range_max = 0
c2Range_max_auto = true
c2Range_min = 0
c2Range_min_auto = true
c2Range_renorm = true
c2Range_reverse = false
c3Range_log = false
c3Range_max = 0
c3Range_max_auto = true
c3Range_min = 0
c3Range_min_auto = true
c3Range_renorm = true
c3Range_reverse = false
c4Range_log = false
c4Range_max = 0
c4Range_max_auto = true
c4Range_min = 0
c4Range_min_auto = true
c4Range_renorm = true
c4Range_reverse = false
dataStyle = Points
display = on
dpi = 300
fontSize = 1
funcStyle = Lines
grid = off
gridAxisX = 1
gridAxisY = 1
gridAxisZ = 1
gridMajColor = grey70
gridMinColor = grey85
key = on
keyColumns = 0
keyPos = top right
key_Xoff = 0.0
key_Yoff = 0.0
landscape = off
lineWidth = 1.0
multiPlot = off
numComplex = off
numDisplay = natural
numErr = on
numSF = 8
originX = 0.0
originY = 0.0
output =
paperHeight = 297
paperName = a4
paperWidth = 210
pointLineWidth = 1.0
pointSize = 1.0
samples = 250
samples_method = nearestNeighbor
samples_x_auto = false
samples_x = 40
samples_y_auto = false
samples_y = 40
termAntiAlias = on
termEnlarge = off
termInvert = off
termTransparent = off
termType = X11_singleWindow
textColor = black
textHAlign = left
textVAlign = bottom
title =
title_Xoff = 0.0
title_Yoff = 0.0
uRange_log = false
uRange_max = 1.0
uRange_min = 0.0
vRange_log = false
vRange_max = 1.0
vRange_min = 0.0
tRange_log = false
tRange_max = 1.0
tRange_min = 0.0
unitAbbrev = on
unitAngleDimless = on
unitPrefix = on
unitScheme = si
width = 8.0
view_xy = 60
view_yz = 30
zAspect = auto

[terminal]
color = on
color_err = red
color_rep = green
color_wrn = amber
splash = on

[styling]
arrow_headAngle = 45
arrow_headSize = 1.0
arrow_headBackIndent = 0.2
axes_lineWidth = 1.0
axes_majTickLen = 1.0
axes_minTickLen = 1.0
axes_separation = 1.0
axes_textGap = 1.0
colorScale_margin = 1.0
colorScale_width = 1.0
grid_majLineWidth = 1.0
grid_minLineWidth = 0.5
baseline_lineWidth = 1.0
baseline_pointSize = 1.0

[variables]
pi = 3.14159265358979

[colors]
palette = black, red, blue, magenta, cyan, brown, salmon, gray,
green, navyBlue, periwinkle, pineGreen, seaGreen, greenYellow,
orange, carnationPink, plum

[latex]
preamble =
\end{verbatim}

\section{Setting definitions}

We now provide a more detailed description of the effect of each of the
settings which can be found in configuration files, including where appropriate
a list of possible values for each. Settings are arranged by section.

\subsection{The {\tt filters} section}

The {\tt filters} section allows input filters to be specified for \datafile s
whose filenames match particular wildcards. Each line should be in the format
\begin{verbatim}
wildcard = filter_binary
\end{verbatim}
For example, the line
\begin{verbatim}
*.gz = /usr/bin/gzip
\end{verbatim}
would set the application {\tt /usr/bin/gzip} to be used as an input filter for
all \datafile s with a {\tt .gz} suffix. For more information about input
filters, see Section~\ref{sec:filters}.

\subsection{The {\tt settings} section}
\label{sec:configfile_settings}

The {\tt settings} section can contain any of the following settings in any order:

\begin{longtable}{p{3.4cm}p{9cm}}
{\tt aspect} & {\bf Possible values:} {\tt auto}, or any floating-point number.

               {\bf Analogous set command:} \indcmdts{set size ratio}

               Sets the $y/x$ aspect ratio of plots.
               \\
{\tt autoAspect} & {\bf Possible values:} {\tt on}, {\tt off}.

               {\bf Analogous set command:} {\tt set size ratio}

               Sets whether plots have the automatic $y/x$ aspect ratio, which is the golden ratio. If {\tt on}, then the {\tt aspect} setting is ignored. Deprecated: new scripts should use {\tt aspect=auto} instead.
               \\
{\tt autoZAspect} & {\bf Possible values:} {\tt on}, {\tt off}.

               {\bf Analogous set command:} {\tt set size zratio}

               Sets whether 3d plots have the automatic $z/x$ aspect ratio, which is the golden ratio. If {\tt on}, then the {\tt zAspect} setting is ignored. Deprecated: new scripts should use {\tt zAspect=auto} instead.
               \\
{\tt axesColor} & {\bf Possible values:} Any recognised color.

               {\bf Analogous set command:} \indcmdts{set axescolor}

               Sets the color of axis lines and ticks.
               \\
{\tt axisUnitStyle} & {\bf Possible values:} {\tt Bracketed}, {\tt Ratio}, {\tt SquareBracketed}

               {\bf Analogous set command:} \indcmdts{set axisunitstyle}

               Sets the style in which the physical units of quantities plotted against axes are appended to axis labels.
               \\
{\tt backup} & {\bf Possible values:} {\tt on}, {\tt off}.

               {\bf Analogous set command:} \indcmdts{set backup}

               When this switch is set to {\tt on}, and plot output is being directed to file, attempts to write output over existing files cause a copy of the existing file to be preserved, with a tilde after its old filename (see Section~\ref{sec:file_backup}).
               \\
{\tt bar}     & {\bf Possible values:}  Any floating-point number.

               {\bf Analogous set command:} \indcmdts{set bar}

               Sets the horizontal length of the lines drawn at the end of errorbars, in units of their default length.
               \\
{\tt binOrigin} & {\bf Possible values:} {\tt auto}, or any floating-point number.

               {\bf Analogous set command:} \indcmdts{set binorigin}

               Sets the point along the abscissa axis from which the bins used by the \indcmdt{histogram} originate.
               \\
{\tt binWidth} & {\bf Possible values:} {\tt auto}, or any floating-point number.

               {\bf Analogous set command:} \indcmdts{set binwidth}

               Sets the widths of the bins used by the \indcmdt{histogram}.
               \\
{\tt boxFrom} & {\bf Possible values:} {\tt auto}, or any floating-point number.

               {\bf Analogous set command:} \indcmdts{set boxfrom}

               Sets the horizontal point from which bars on bar charts appear to emanate.
               \\
{\tt boxWidth} & {\bf Possible values:} {\tt auto}, or any floating-point number.

               {\bf Analogous set command:} \indcmdts{set boxwidth}

               Sets the default width of boxes on barcharts. If negative, then the boxes have automatically selected widths, so that the interfaces between bars occur at the horizontal midpoints between the specified datapoints.
               \\
{\tt calendarIn} & {\bf Possible values:} {\tt British}, {\tt French}, {\tt Greek}, {\tt Gregorian}, {\tt Hebrew}, {\tt Islamic}, {\tt Julian}, {\tt Papal}, {\tt Russian}.

               {\bf Analogous set command:} \indcmdts{set calendar}

               Sets the default calendar for the input of dates from day, month and year representation into Julian Date representation. See Section~\ref{sec:time_series} for more details.
               \\
{\tt calendarOut} & {\bf Possible values:} {\tt British}, {\tt French}, {\tt Greek}, {\tt Gregorian}, {\tt Hebrew}, {\tt Islamic}, {\tt Julian}, {\tt Papal}, {\tt Russian}.

               {\bf Analogous set command:} \indcmdts{set calendar}

               Sets the default calendar for the output of dates from Julian Date representation to day, month and year representation. See Section~\ref{sec:time_series} for more details.
               \\
{\tt clip} & {\bf Possible values:} {\tt on}, {\tt off}.

               {\bf Analogous set command:} \indcmdts{set clip}

               Sets whether datapoints close to the edges of graphs should be clipped at the edges ({\tt on}) or allowed to overrun the axes ({\tt off}).
               \\
{\tt colKey} & {\bf Possible values:} {\tt on}, {\tt off}.

               {\bf Analogous set command:} \indcmdts{set colkey}

               Sets whether \indpst{colormap} plots have a scale along one side relating color to ordinate value.
               \\
{\tt colKeyPos} & {\bf Possible values:} {\tt top}, {\tt bottom}, {\tt left}, {\tt right}.

               {\bf Analogous set command:} \indcmdts{set colkey}

               Sets the side of the plot along which the color legend should appear on \indpst{colormap} plots.
               \\
{\tt color} & {\bf Possible values:} {\tt on}, {\tt off}.

               {\bf Analogous set command:} \indcmdts{set terminal}

               Sets whether output should be color ({\tt on}) or monochrome ({\tt off}).
               \\
{\tt contour} & {\bf Possible values:} Any integer.

               {\bf Analogous set command:} \indcmdts{set contour}

               Sets the number of contours which are drawn in the \indpst{contourmap} plot style.
               \\
{\tt c?Range\_log} & {\bf Possible values:} {\tt true}, {\tt false}.

               {\bf Analogous set command:} \indcmdts{set logscale c}

               When the variables {\tt c1}--{\tt c4} are set to renormalise in the {\tt c?Range\_renorm} setting, this setting determines whether color maps are drawn with logarithmic or linear color scales. The {\tt ?} wildcard should be replaced with an integer in the range 1--4 to alter the renormalisation of the variables {\tt c1} through {\tt c4} respectively in the expressions supplied to the {\tt colmap} setting. In the case of {\tt c1}, this setting also determines whether contours demark linear or logarithmic intervals on contour maps.\indps{contourmap}\indps{colormap}
               \\
{\tt c?Range\_max} & {\bf Possible values:} Any floating-point number.

               {\bf Analogous set command:} \indcmdts{set crange}

               When the variables {\tt c1}--{\tt c4} are set to renormalise in the {\tt c?Range\_renorm} setting, this setting determines the upper limit of the range of values demarked by differing colors on color maps. The {\tt ?} wildcard should be replaced with an integer in the range 1--4 to alter the renormalisation of the variables {\tt c1} through {\tt c4} respectively in the expressions supplied to the {\tt colmap} setting. In the case of {\tt c1}, this setting also determines the range of ordinate values for which contours are drawn on contour maps.
               \\
{\tt c?Range\_max\_auto} & {\bf Possible values:} {\tt true}, {\tt false}.

               {\bf Analogous set command:} \indcmdts{set crange}

               When the variables {\tt c1}--{\tt c4} are set to renormalise in the {\tt c?Range\_renorm} setting, this setting determines whether the upper limit of the range of values demarked by differing colors on color maps should autoscale to fit the data, or be a fixed value as specified in the {\tt C?Range\_max} setting. The {\tt ?} wildcard should be replaced with an integer in the range 1--4 to alter the renormalisation of the variables {\tt c1} through {\tt c4} respectively. In the case of {\tt c1}, this setting also affects the range of ordinate values for which contours are drawn on contour maps.
               \\
{\tt c?Range\_min} & {\bf Possible values:} Any floating-point number.

               {\bf Analogous set command:} \indcmdts{set crange}

               When the variables {\tt c1}--{\tt c4} are set to renormalise in the {\tt c?Range\_renorm} setting, this setting determines the lower limit of the range of values demarked by differing colors on color maps. The {\tt ?} wildcard should be replaced with an integer in the range 1--4 to alter the renormalisation of the variables {\tt c1} through {\tt c4} respectively in the expressions supplied to the {\tt colmap} setting. In the case of {\tt c1}, this setting also determines the range of ordinate values for which contours are drawn on contour maps.
               \\
{\tt c?Range\_min\_auto} & {\bf Possible values:} {\tt true}, {\tt false}.

               {\bf Analogous set command:} \indcmdts{set crange}

               When the variables {\tt c1}--{\tt c4} are set to renormalise in the {\tt c?Range\_renorm} setting, this setting determines whether the lower limit of the range of values demarked by differing colors on color maps should autoscale to fit the data, or be a fixed value as specified in the {\tt C?Range\_min} setting. The {\tt ?} wildcard should be replaced with an integer in the range 1--4 to alter the renormalisation of the variables {\tt c1} through {\tt c4} respectively. In the case of {\tt c1}, this setting also affects the range of ordinate values for which contours are drawn on contour maps.
               \\
{\tt c?Range\_renorm} & {\bf Possible values:} {\tt true}, {\tt false}.

               {\bf Analogous set command:} \indcmdts{set crange}

               Sets whether the variables {\tt c1}--{\tt c4}, used in the construction of color maps, should be renormalised into the range 0--1 before being passed to the expressions supplied to the {\tt set colmap} command, or whether they should contain the exact data values supplied in the 3rd--6th columns of data to the {\tt colormap} plot style. The {\tt ?} wildcard should be replaced with an integer in the range 1--4 to alter the renormalisation of the variables {\tt c1} through {\tt c4} respectively.
               \\
{\tt c?Range\_reverse} & {\bf Possible values:} {\tt true}, {\tt false}.

               {\bf Analogous set command:} \indcmdts{set crange}

               When the variables {\tt c1}--{\tt c4} are set to renormalise in the {\tt c?Range\_renorm} setting, this setting determines whether the renormalisation into the range 0--1 is inverted such that the maximum value maps to zero and the minimum value maps to one. The {\tt ?} wildcard should be replaced with an integer in the range 1--4 to alter the renormalisation of the variables {\tt c1} through {\tt c4} respectively.
               \\
{\tt dataStyle} & {\bf Possible values:} Any plot style.

               {\bf Analogous set command:} \indcmdts{set data style}

               Sets the plot style used by default when plotting \datafile s.
               \\
{\tt display} & {\bf Possible values:} {\tt on}, {\tt off}.

               {\bf Analogous set command:} \indcmdts{set display}

               When set to {\tt on}, no output is produced until the \indcmdt{set display} is issued. This is useful for speeding up scripts which produce large multiplots; see Section~\ref{sec:set_display} for more details.
               \\
{\tt dpi} & {\bf Possible values:} Any floating-point number.

               {\bf Analogous set command:} \indcmdts{set terminal dpi}

               Sets the sampling quality used, in dots per inch, when output is sent to a bitmapped terminal (the bmp, jpeg, gif, png and tif terminals).
               \\
{\tt fontSize} & {\bf Possible values:} Any floating-point number.

               {\bf Analogous set command:} \indcmdts{set fontsize}

               Sets the fontsize of text, where $1.0$ represents 10-point text, and other values differ multiplicatively.
               \\
{\tt funcStyle} & {\bf Possible values:} Any plot style.

               {\bf Analogous set command:} \indcmdts{set function style}

               Sets the plot style used by default when plotting functions.
               \\
{\tt grid} & {\bf Possible values:} {\tt on}, {\tt off}.

               {\bf Analogous set command:} \indcmdts{set grid}

               Sets whether a grid should be displayed on plots.
               \\
{\tt gridAxisX} & {\bf Possible values:} Any integer.

               {\bf Analogous set command:} None

               Sets the default horizontal axis to which gridlines should attach, if the {\tt set grid} command is called without specifying which axes to use.
               \\
{\tt gridAxisY} & {\bf Possible values:} Any integer.

               {\bf Analogous set command:} None

               Sets the default vertical axis to which gridlines should attach, if the {\tt set grid} command is called without specifying which axes to use.
               \\
{\tt gridAxisZ} & {\bf Possible values:} Any integer.

               {\bf Analogous set command:} None

               Sets the default $z$-axis to which gridlines should attach, if the {\tt set grid} command is called without specifying which axes to use.
               \\
{\tt gridMajColor} & {\bf Possible values:} Any recognised color.

               {\bf Analogous set command:} \indcmdts{set gridmajcolor}

               Sets the color of major grid lines.
               \\
{\tt gridMinColor} & {\bf Possible values:} Any recognised color.

               {\bf Analogous set command:} \indcmdts{set gridmincolor}

               Sets the color of minor grid lines.
               \\
{\tt key} & {\bf Possible values:} {\tt on}, {\tt off}.

               {\bf Analogous set command:} \indcmdts{set key}

               Sets whether a legend is displayed on plots.
               \\
{\tt keyColumns} & {\bf Possible values:} Any integer $\geq 0$.

               {\bf Analogous set command:} \indcmdts{set keycolumns}

               Sets the number of columns into which the legends of plots should be divided. If a value of zero is given, then the number of columns is decided automatically for each plot.
               \\
{\tt keyPos} & {\bf Possible values:} {\tt top right}, {\tt top xcenter}, {\tt top left}, {\tt ycenter right}, {\tt ycenter xcenter}, {\tt ycenter left}, {\tt bottom right}, {\tt bottom xcenter}, {\tt bottom left}, {\tt above}, {\tt below}, {\tt outside}.

               {\bf Analogous set command:} \indcmdts{set key}

               Sets where the legend should appear on plots.
               \\
{\tt key\_xOff} & {\bf Possible values:} Any floating-point number.

               {\bf Analogous set command:} \indcmdts{set key}

               Sets the horizontal offset, in approximate graph-widths, that should be applied to the legend, relative to its default position, as set by {\tt KEYPOS}.
               \\
{\tt key\_yOff} & {\bf Possible values:} Any floating-point number.

               {\bf Analogous set command:} \indcmdts{set key}

               Sets the vertical offset, in approximate graph-heights, that should be applied to the legend, relative to its default position, as set by {\tt KEYPOS}.
               \\
{\tt landscape} & {\bf Possible values:} {\tt on}, {\tt off}.

               {\bf Analogous set command:} \indcmdts{set terminal}

               Sets whether output is in portrait orientation ({\tt off}), or landscape orientation ({\tt on}).
               \\
{\tt lineWidth} & {\bf Possible values:} Any floating-point number.

               {\bf Analogous set command:} \indcmdts{set linewidth}

               Sets the width of lines on plots, as a multiple of the default.
               \\
{\tt multiPlot} & {\bf Possible values:} {\tt on}, {\tt off}.

               {\bf Analogous set command:} \indcmdts{set multiplot}

               Sets whether multiplot mode is on or off.
               \\
{\tt numComplex} & {\bf Possible values:} {\tt on}, {\tt off}.

               {\bf Analogous set command:} \indcmdts{set numerics}

               Sets whether complex arithmetic is enabled, or whether all non-real results to calculations should raise numerical exceptions.
               \\
{\tt numDisplay} & {\bf Possible values:} {\tt latex}, {\tt natural}, {\tt typeable}.

               {\bf Analogous set command:} \indcmdts{set numerics}

               Sets whether numerical results are displayed in a natural human-readable way, e.g.\ $2\,\mathrm{m}$, in LaTeX, e.g.\ {\tt \$$2\backslash$,$\backslash$mathrm\{m\}\$}, or in a way which may be pasted back into Pyxplot, e.g.\ {\tt 2*unit(m)}.
               \\
{\tt numErr} & {\bf Possible values:} {\tt on}, {\tt off}.

               {\bf Analogous set command:} \indcmdts{set numerics}

               Sets whether explicit error messages are thrown when calculations yield undefined results, as in the cases of division by zero or the evaluation of functions in regions where they are undefined or infinite. If explicit error messages are disabled, such calculations quietly return {\tt nan}.
               \\
{\tt numSF} & {\bf Possible values:} Any integer between 0 and 30.

               {\bf Analogous set command:} \indcmdts{set numerics}

               Sets the number of significant figures to which numerical quantities are displayed by default.
               \\
{\tt originX} & {\bf Possible values:} Any floating point number.

               {\bf Analogous set command:} \indcmdts{set origin}

               Sets the horizontal position, in centimetres, of the default origin of plots on the page. Most useful when multiplotting many plots.
               \\
{\tt originY} & {\bf Possible values:} Any floating point number.

               {\bf Analogous set command:} \indcmdts{set origin}

               Sets the vertical position, in centimetres, of the default origin of plots on the page. Most useful when multiplotting many plots.
               \\
{\tt output} & {\bf Possible values:} Any string (case sensitive).

               {\bf Analogous set command:} \indcmdts{set output}

               Sets the output filename for plots. If blank, the default filename of {\tt pyxplot.foo} is used, where {\tt foo} is an extension appropriate for the file format.
               \\
{\tt paperHeight} & {\bf Possible values:} Any floating-point number.

               {\bf Analogous set command:} \indcmdts{set papersize}

               Sets the height of the papersize for PostScript output in millimetres.
               \\
{\tt paperName} & {\bf Possible values:} A string matching any of the papersizes listed in Chapter~\ref{ch:paper_sizes}.

               {\bf Analogous set command:} \indcmdts{set papersize}

               Sets the papersize for PostScript output to one of the pre-defined papersizes listed in Chapter~\ref{ch:paper_sizes}.
               \\
{\tt paperWidth} & {\bf Possible values:} Any floating-point number.

               {\bf Analogous set command:} \indcmdts{set papersize}

               Sets the width of the papersize for PostScript output in millimetres.
               \\
{\tt pointLineWidth} & {\bf Possible values:} Any floating-point number.

               {\bf Analogous set command:} \indcmdts{set pointlinewidth}

               Sets the linewidth used to stroke points onto plots, as a multiple of the default.
               \\
{\tt pointSize} & {\bf Possible values:} Any floating-point number.

               {\bf Analogous set command:} \indcmdts{set pointsize}

               Sets the sizes of points on plots, as a multiple of their normal sizes.
               \\
%{\tt projection} & {\bf Possible values:} {\tt gnomonic}, {\tt flat}.
%
%               {\bf Analogous set command:} \indcmdts{set projection}
%
%               Sets the projection used on graphs. Flat projection is useful for most purposes, but gnomonic projection is useful for representing curved spaces on flat pieces of paper, when drawing world maps, for example.
%               \\
{\tt samples} & {\bf Possible values:} Any integer.

               {\bf Analogous set command:} \indcmdts{set samples}

               Sets the number of samples (datapoints) to be evaluated along the abscissa axis when plotting a function.
               \\
{\tt samples\_method} & {\bf Possible values:} {\tt inverse\-Square}, {\tt monag\-han\-Lattan\-zio}, {\tt nearest\-Neigh\-bor}.

               {\bf Analogous set command:} \indcmdts{set samples}

               Sets the method used to interpolate two-dimensional non-gridded arrays of datapoints from datafiles within the \indcmdt{interpolate} and when plotting using the \indpst{colormap}, \indpst{contourmap} and \indpst{surface} plot styles.
               \\
{\tt samples\_x} & {\bf Possible values:} Any integer.

               {\bf Analogous set command:} \indcmdts{set samples}

               Sets the number of samples (datapoints) to be evaluated along the first abscissa axis when drawing color maps and surfaces, and when calculating contour maps.
               \\
{\tt samples\_x\_auto} & {\bf Possible values:} {\tt true}, {\tt false}.

               {\bf Analogous set command:} \indcmdts{set samples}

               Sets whether the number of samples (datapoints) to be evaluated along the first abscissa axis when drawing color maps and surfaces, and when calculating contour maps should follow the number of samples set with the \indcmdts{set samples} command.
               \\
{\tt samples\_y} & {\bf Possible values:} Any integer.

               {\bf Analogous set command:} \indcmdts{set samples}

               Sets the number of samples (datapoints) to be evaluated along the second abscissa axis when drawing color maps and surfaces, and when calculating contour maps.
               \\
{\tt samples\_y\_auto} & {\bf Possible values:} {\tt true}, {\tt false}.

               {\bf Analogous set command:} \indcmdts{set samples}

               Sets whether the number of samples (datapoints) to be evaluated along the second abscissa axis when drawing color maps and surfaces, and when calculating contour maps should follow the number of samples set with the \indcmdts{set samples} command.
               \\
{\tt termAntiAlias} & {\bf Possible values:} {\tt on}, {\tt off}.

               {\bf Analogous set command:} \indcmdts{set terminal}

               Sets whether output sent to the bitmapped graphics output terminals -- i.e.\ the bmp, jpeg, gif, png and tif terminals -- is antialiased. Antialiasing smooths the color boundaries to disguise the effects of pixelisation and is almost invariably desirable.
               \\
{\tt termEnlarge} & {\bf Possible values:} {\tt on}, {\tt off}.

               {\bf Analogous set command:} \indcmdts{set terminal}

               When set to {\tt on} output is enlarged or shrunk to fit the current paper size.
               \\
{\tt termInvert} & {\bf Possible values:} {\tt on}, {\tt off}.

               {\bf Analogous set command:} \indcmdts{set terminal}

               Sets whether jpeg/gif/png output has normal colors ({\tt off}), or inverted colors ({\tt on}).
               \\
{\tt termTransparent} & {\bf Possible values:} {\tt on}, {\tt off}.

               {\bf Analogous set command:} \indcmdts{set terminal}

               Sets whether jpeg/gif/png output has transparent background ({\tt on}), or solid background ({\tt off}).
               \\
{\tt termType} & {\bf Possible values:} {\tt bmp}, {\tt eps}, {\tt gif}, {\tt jpg}, {\tt pdf}, {\tt png}, {\tt ps}, {\tt svg}, {\tt tif}, {\tt X11\_multiWindow}, {\tt X11\_persist}, {\tt X11\_singleWindow}.

               {\bf Analogous set command:} \indcmdts{set terminal}

               Sets whether output is sent to the screen, using one of the {\tt X11\_}... terminals, or to disk. In the latter case, output may be produced in a wide variety of graphical formats.
               \\
{\tt textColor} & {\bf Possible values:} Any recognised color.

               {\bf Analogous set command:} \indcmdts{set textcolor}

               Sets the color of all text output.
               \\
{\tt textHAlign} & {\bf Possible values:} {\tt left}, {\tt center}, {\tt right}.

               {\bf Analogous set command:} \indcmdts{set texthalign}

               Sets the horizontal alignment of text labels to their given reference positions.
               \\
{\tt textVAlign} & {\bf Possible values:} {\tt top}, {\tt center}, {\tt bottom}.

               {\bf Analogous set command:} \indcmdts{set textvalign}

               Sets the vertical alignment of text labels to their given reference positions.
               \\
{\tt title} & {\bf Possible values:} Any string (case sensitive).

               {\bf Analogous set command:} \indcmdts{set title}

               Sets the title to appear at the top of the plot.
               \\
{\tt title\_xOff} & {\bf Possible values:} Any floating point number.

               {\bf Analogous set command:} \indcmdts{set title}

               Sets the horizontal offset of the title of the plot from its default central location.
               \\
{\tt title\_yOff} & {\bf Possible values:} Any floating point number.

               {\bf Analogous set command:} \indcmdts{set title}

               Sets the vertical offset of the title of the plot from its default location at the top of the plot.
               \\
{\tt tRange\_log} & {\bf Possible values:} {\tt true}, {\tt false}.

               {\bf Analogous set command:} \indcmdts{set logscale t}

               Sets whether the $t$-axis -- used for parametric plotting -- is linear or logarithmic.
               \\
{\tt tRange\_max} & {\bf Possible values:} Any floating-point number.

               {\bf Analogous set command:} \indcmdts{set trange}

               Sets upper limit of the $t$-axis, used for parametric plotting.
               \\
{\tt tRange\_min} & {\bf Possible values:} Any floating-point number.

               {\bf Analogous set command:} \indcmdts{set trange}

               Sets lower limit of the $t$-axis, used for parametric plotting.
               \\
{\tt unitAbbrev} & {\bf Possible values:} {\tt on}, {\tt off}.

               {\bf Analogous set command:} \indcmdts{set unit}

               Sets whether physical units are displayed in abbreviated form, e.g.\ {\tt mm}, or in full, e.g.\ {\tt millimetres}.
               \\
{\tt unitAngleDimless} & {\bf Possible values:} {\tt on}, {\tt off}.

               {\bf Analogous set command:} \indcmdts{set unit}

               Sets whether angles are treated as dimensionless units, or whether the radian is treated as a base unit.
               \\
{\tt unitPrefix} & {\bf Possible values:} {\tt on}, {\tt off}.

               {\bf Analogous set command:} \indcmdts{set unit}

               Sets whether SI prefixes, such as {\tt milli-} and {\tt mega-} are prepended to SI units where appropriate.
               \\
{\tt unitScheme} & {\bf Possible values:} {\tt ancient}, {\tt cgs}, {\tt imperial}, {\tt planck}, {\tt si}, {\tt USCustomary}.

               {\bf Analogous set command:} \indcmdts{set unit}

               Sets the scheme of physical units in which quantities are displayed.
               \\
{\tt uRange\_log} & {\bf Possible values:} {\tt true}, {\tt false}.

               {\bf Analogous set command:} \indcmdts{set logscale u}

               Sets whether the $u$-axis -- used for parametric plotting -- is linear or logarithmic.
               \\
{\tt uRange\_max} & {\bf Possible values:} Any floating-point number.

               {\bf Analogous set command:} \indcmdts{set urange}

               Sets upper limit of the $u$-axis, used for parametric plotting.
               \\
{\tt uRange\_min} & {\bf Possible values:} Any floating-point number.

               {\bf Analogous set command:} \indcmdts{set urange}

               Sets lower limit of the $t$-axis, used for parametric plotting.
               \\
{\tt vRange\_log} & {\bf Possible values:} {\tt true}, {\tt false}.

               {\bf Analogous set command:} \indcmdts{set logscale v}

               Sets whether the $v$-axis -- used for parametric plotting -- is linear or logarithmic.
               \\
{\tt vRange\_max} & {\bf Possible values:} Any floating-point number.

               {\bf Analogous set command:} \indcmdts{set vrange}

               Sets upper limit of the $v$-axis, used for parametric plotting.
               \\
{\tt vRange\_min} & {\bf Possible values:} Any floating-point number.

               {\bf Analogous set command:} \indcmdts{set vrange}

               Sets lower limit of the $v$-axis, used for parametric plotting.
               \\
{\tt width} & {\bf Possible values:} Any floating-point number.

               {\bf Analogous set commands:} \indcmdts{set width}, \indcmdts{set size}

               Sets the width of plots in centimetres.
               \\
{\tt view\_xy} & {\bf Possible values:} Any floating-point number.

               {\bf Analogous set commands:} \indcmdts{set view}

               Sets the viewing angle of three-dimensional plots in the $x$-$y$ plane in degrees.
               \\
{\tt view\_yz} & {\bf Possible values:} Any floating-point number.

               {\bf Analogous set commands:} \indcmdts{set view}

               Sets the viewing angle of three-dimensional plots in the $y$-$z$ plane in degrees.
               \\
{\tt zAspect} & {\bf Possible values:} {\tt auto}, or any floating-point number.

               {\bf Analogous set command:} \indcmdts{set size ratio}

               Sets the $z/x$ aspect ratio of 3d plots.
               \\
\end{longtable}

\subsection{The {\tt styling} section}

The {\tt styling} section can contain any of the following settings in any order:

\begin{longtable}{p{3.4cm}p{9cm}}
{\tt arrow\_headAngle} & {\bf Possible values:} Any floating-point number.

               Sets the angle, in degrees, at which the two sides of arrow heads meet at its point.
               \\
{\tt arrow\_headSize} & {\bf Possible values:} Any floating-point number.

               Sets the size of all arrow heads. A value of 1.0 corresponds to Pyxplot's default size.
               \\
{\tt arrow\_headBackIndent} & {\bf Possible values:} Any floating-point number.

               Sets the size of the indentation in the back of arrow heads. The default size is 0.2. Sensible values lie in the range 0 (no indentation) to 1 (the indentation extends the whole length of the arrow head). Less sensible values may be used by the aesthetically adventurous.
               \\
{\tt axes\_lineWidth}  & {\bf Possible values:} Any floating-point number.

               Sets the line width used to draw graph axes.
               \\
{\tt axes\_majTickLen} & {\bf Possible values:} Any floating-point number.

               Sets the length of major axis ticks. A value of 1.0 corresponds to Pyxplot's default length of $1.2\,\mathrm{mm}$; other values differ from this multiplicatively.
               \\
{\tt axes\_minTickLen} & {\bf Possible values:} Any floating-point number.

               Sets the length of minor axis ticks. A value of 1.0 corresponds to Pyxplot's default length of $0.85\,\mathrm{mm}$; other values differ from this multiplicatively.
               \\
{\tt axes\_separation} & {\bf Possible values:} Any floating-point number.

               Sets the separation between parallel axes on graphs, less the width of any text labels associated with the axes. A value of 1.0 corresponds to Pyxplot's default spacing of $8\,\mathrm{mm}$; other values differ from this multiplicatively.
               \\
{\tt axes\_textGap} & {\bf Possible values:} Any floating-point number.

               Sets the separation between axes and the text labels which are associated with them. A value of 1.0 corresponds to Pyxplot's default spacing of $3\,\mathrm{mm}$; other values differ from this multiplicatively.
               \\
{\tt colorScale\_margin} & {\bf Possible values:} Any floating-point number.

               Sets the separation left between the axes of plots drawn using the {\tt colormap} plot style, and of the color scales drawn alongside them. A value of 1.0 corresponds to Pyxplot's default spacing; other values differ from this multiplicatively.
               \\
{\tt colorScale\_width} & {\bf Possible values:} Any floating-point number.

               Sets the width of the color scale bars drawn alonside plots drawn using the {\tt colormap} plot style. A value of 1.0 corresponds to Pyxplot's width; other values differ from this multiplicatively.
               \\
{\tt grid\_majLineWidth} & {\bf Possible values:} Any floating-point number.

               Sets the line width used to draw major gridlines (default $1.0$).
               \\
{\tt grid\_minLineWidth} & {\bf Possible values:} Any floating-point number.

               Sets the line width used to draw minor gridlines (default $0.5$).
               \\
{\tt baseline\_lineWidth} & {\bf Possible values:} Any floating-point number.

               Sets the PostScript line width which corresponds to a {\tt linewidth} of 1.0. A value of 1.0 corresponds to Pyxplot's default line width of $0.2\,\mathrm{mm}$; other values differ from this multiplicatively.
               \\
{\tt baseline\_pointSize} & {\bf Possible values:} Any floating-point number.

               Sets the baseline point size which corresponds to a {\tt pointsize} of 1.0. A value of 1.0 corresponds to Pyxplot's default; other values differ from this multiplicatively.
               \\
\end{longtable}

\subsection{The {\tt terminal} section}
\label{sec:configfile_terminal}

The {\tt terminal} section can contain any of the following settings in any order:

\begin{longtable}{p{3.4cm}p{9cm}}
{\tt color} & {\bf Possible values:} {\tt on}, {\tt off}.

               {\bf Analogous command-line switches:} {\tt -c}, {\tt --color}, {\tt -m}, {\tt --monochrome}.

               Sets whether color highlighting should be used in the interactive terminal. If turned on, output is displayed in green, warning messages in amber, and error messages in red; these colors are configurable, as described below. Note that not all UNIX terminals support the use of color.
               \\
{\tt color\_err} & {\bf Possible values:} Any recognised terminal color (see below).

               {\bf Analogous command-line switches:} None.

               Sets the color in which error messages are displayed when color highlighting is used. Note that the list of recognised color names differs from that used in Pyxplot; a list is given at the end of this section.
               \\
{\tt color\_rep} & {\bf Possible values:} Any recognised terminal color (see below).

               {\bf Analogous command-line switches:} None.

               As above, but sets the color in which Pyxplot displays its non-error-related output.
               \\
{\tt color\_wrn} & {\bf Possible values:} Any recognised terminal color (see below).

               {\bf Analogous command-line switches:} None.

               As above, but sets the color in which Pyxplot displays its warning messages.
               \\
{\tt splash} & {\bf Possible values:} {\tt on}, {\tt off}.

               {\bf Analogous command-line switches:} {\tt -q}, {\tt --quiet}, {\tt -V}, {\tt --verbose}

               Sets whether the standard welcome message is displayed upon startup.
               \\
\end{longtable}

The colors recognised by the {\tt COLOR\_XXX} configuration options above
are: {\tt Red}, {\tt Green}, {\tt Amber}, {\tt Blue}, {\tt Purple}, {\tt
Magenta}, {\tt Cyan}, {\tt White}, {\tt Normal}. The final option produces the
default foreground color of the terminal.

\renewcommand{\arraystretch}{1.00}

\subsection{The {\tt units} section}
\label{sec:configfile_units}

The {\tt units} section can be used to define new physical units for use within
Pyxplot's mathematical environment. Each line should take the format of
\begin{verbatim}
<l_sing> \[ / <s_sing> \] \[ / <lt_sing> \]
   \[ / <l_plur> \] \[ / <s_plur> \] \[ / <lt_plur> \]
   : <quantity_name> = \[ <definition> \]
\end{verbatim}
where
\begin{longtable}{p{3.4cm}p{9cm}}
{\tt l\_sing} & is the long singular name of the unit, e.g.\ {\tt metre}.\\
{\tt s\_sing} & is the short singular name of the unit, e.g.\ {\tt m}.\\
{\tt lt\_sing} & is the singular name of the unit to be used in \latexdcf.\\
{\tt l\_plur} & is the long plural name of the unit, e.g.\ {\tt metres}.\\
{\tt s\_plur} & is the short plural name of the unit, e.g.\ {\tt m}.\\
{\tt lt\_plur} & is the plural name of the unit to be used in \latexdcf.\\
{\tt quantity\_name} & is the physical quantity which the unit measures, e.g.\ {\tt length}.\\
{\tt definition} & is a definition of the unit in terms of other units which
Pyxplot already recognises, e.g.\ {\tt 0.001*km}. The syntax used is identical
to that used in the {\tt unit()} function.\\
\end{longtable}
For example, a definition of the metre would look like
\begin{verbatim}
metre/m/m/metres/m/m:length=0.001*km
\end{verbatim}

Not all of the various names which a unit may have need to be specified. If
plural names are not specified then they are assumed to be the same as the
singular names. If short and/or \latexdcf\ names are not specified they are assumed
to be the same as the long name. If the definition is left blank then the unit
is assumed to be a new base unit which is not related to any pre-existing
units.

\section{Recognised color names}
\label{sec:color_names}

The following is a complete list of the color names which Pyxplot recognises
in the {\tt set textcolor}, {\tt set axescolor} commands, and in the {\tt
colors} section of its configuration file.  A color chart of these can be
found in Appendix~\ref{ch:color_charts}.  All color names are case
insensitive.

\vspace{5mm}\noindent
\index{configuration file!colors}\index{colors!configuration file}
{\tt
greenYellow, yellow, goldenrod, dandelion, apricot, peach, melon,\newline\noindent
yellowOrange, orange, burntOrange, bittersweet, redOrange,\newline\noindent
mahogany, maroon, brickRed, red, orangeRed, rubineRed,\newline\noindent
wildStrawberry, salmon, carnationPink, magenta, violetRed,\newline\noindent
rhodamine, mulberry, redViolet, fuchsia, lavender, thistle,\newline\noindent
orchid, darkOrchid, purple, plum, violet, royalPurple,\newline\noindent
blueViolet, periwinkle, cadetBlue, cornflowerBlue, midnightBlue,\newline\noindent
navyBlue, royalBlue, blue, cerulean, cyan, processBlue, skyBlue,\newline\noindent
turquoise, tealBlue, aquamarine, blueGreen, emerald, jungleGreen,\newline\noindent
seaGreen, green, forestGreen, pineGreen, limeGreen, yellowGreen,\newline\noindent
springGreen, oliveGreen, rawSienna, sepia, brown, tan, gray,\newline\noindent
grey, black, white.
}

\vspace{5mm}
In addition, a scale of 100~shades of grey is available, ranging from {\tt
grey00}, which is black, to {\tt grey99}, which is very nearly white.  The US
spelling, {\tt gray??}, is also accepted.

Arbitrary colors may be specified in the forms {\tt rgb0:0:0}, {\tt hsb0:0:0}
or {\tt cmyk0:0:0:0}, where the colon-separated zeros should be replaced by
values in the range of~0 to~1 to represent the components of the desired color
in RGB, HSB or CMYK space
respectively.\index{colors!RGB}\index{colors!HSB}\index{colors!CMYK}