update ast 8.6.2

1 files changed, 53979 insertions, 0 deletions

diff --git a/ast/sun211.tex b/ast/sun211.tex
new file mode 100644
index 0000000..b18a925
--- /dev/null
+++ b/ast/sun211.tex
@@ -0,0 +1,53979 @@
+\documentclass[twoside,11pt]{starlink}
+
+% ? Specify used packages
+% ? End of specify used packages
+
+% -----------------------------------------------------------------------------
+% ? Document identification
+% Fixed part
+\stardoccategory    {Starlink User Note}
+\stardocinitials    {SUN}
+\stardocsource      {sun\stardocnumber}
+
+% Variable part - replace [xxx] as appropriate.
+\stardocnumber      {211.28}
+\stardocauthors     {R.F. Warren-Smith \& D.S. Berry}
+\stardocdate        {17th October 2017}
+\stardoctitle     {AST\linebreak%
+                                A Library for Handling\linebreak%
+                                World Coordinate Systems\linebreak%
+                                in Astronomy}
+\stardoccopyright   {Copyright (C) 2017 East Asian Observatory}
+\stardocversion     {V8.6}
+\stardocmanual      {Programmer's Guide\\(C Version)}
+\startitlepic{
+   \includegraphics[width=0.25\textwidth]{sun211_figures/fronta}~~~~~\hfill
+   \includegraphics[width=0.25\textwidth]{sun211_figures/frontb}~~~~~\hfill
+   \includegraphics[width=0.25\textwidth]{sun211_figures/frontc}
+}
+\stardocabstract  {
+The AST library provides a comprehensive range of facilities for
+attaching world coordinate systems to astronomical data, for
+retrieving and interpreting that information in a variety of formats,
+including FITS-WCS, and for generating graphical output based on it.
+
+This programmer's manual should be of interest to anyone writing
+astronomical applications which need to manipulate coordinate system
+data, especially celestial or spectral coordinate systems. AST is portable and
+environment-independent.
+}
+% ? End of document identification
+% -----------------------------------------------------------------------------
+% ? Document specific \providecommand or \newenvironment commands.
+
+\providecommand{\appref}[1]{Appendix~\ref{#1}}
+\providecommand{\secref}[1]{\S\ref{#1}}
+
+\providecommand{\fitskey}[3]{{#1}&{#2}&{#3}\\}
+
+% Use {\tt ... } as \texttt{...} does not work if there are new lines in #1
+\providecommand{\sstsynopsis}[1]{\sstdiytopic{Synopsis}{\tt #1}}
+
+%  Format the constructor section.
+\providecommand{\sstconstructor}[1]{\sstdiytopic{Constructor Function}{#1}}
+
+% ? End of document specific commands
+% -----------------------------------------------------------------------------
+%  \htmlref{Title}{Title} Page.
+%  ===========
+\begin{document}
+\scfrontmatter
+
+\begin{center}
+\emph{This is the C version of this document.\\
+  For the Fortran version, please see \xref{SUN/210}{sun210}{}.}
+\end{center}
+
+% Main text of document.
+\vspace{7mm}
+\section{Introduction}
+
+Welcome to the AST library. If you are writing software for astronomy
+and need to use celestial coordinates (\emph{e.g.}\ RA and Dec), spectral
+coordinates (\emph{e.g.}\ wavelength, frequency, \emph{etc.}), or
+other coordinate system information, then this library should be of
+interest. It provides solutions for most of the problems you will meet
+and allows you to write robust and flexible software. It is able to read
+and write WCS information in a variety of formats, including
+\htmladdnormallink{FITS-WCS}{http://fits.gsfc.nasa.gov/fits_wcs.html}.
+
+%\subsection{TBW---What is a World Coordinate \htmlref{System}{System}?}
+
+\subsection{What Problems Does AST Tackle?}
+
+Here are some of the main problems you may face when handling world
+coordinate system (WCS) information and the solutions that AST
+provides:
+
+\begin{description}
+\item[1. The Variety of Coordinate Systems]\mbox{}\\
+Astronomers use a wide range of differing coordinate systems to describe
+positions within a variety of physical domains. For instance, there are a
+large number of celestial coordinate systems in use within astronomy to
+describe positions on the sky. Understanding these, and knowing how to
+convert coordinates between them, can require considerable expertise. It
+can also be difficult to decide which of them your software should support.
+The same applies to coordinate systems describing other domains, such as
+position within an electro-magnetic spectrum.
+
+\textbf{Solution.} AST has built-in knowledge of many coordinate systems
+and allows you to convert freely between them without specialist
+knowledge. This avoids the need to embed details of specific
+coordinate systems in your software. You also benefit automatically
+when new coordinate systems are added to AST.
+
+\item[2. Storing and Retrieving WCS Information]\mbox{}\\
+Storing coordinate system information in astronomical datasets and
+retrieving it later can present a considerable challenge. Typically,
+it requires knowledge of rather complex conventions
+(\emph{e.g.}\ FITS) which are low-level, often mis-interpreted and may
+be subject to change. Exchanging information with other software
+systems is further complicated by the number of different conventions
+in use.
+
+\textbf{Solution.} AST combines a unifying high-level description of WCS
+information with the ability to save and restore this using a variety
+of formats. Details of the formats, which include FITS, are handled
+internally by AST. This frees you from the need to understand them or
+embed the details in your software. Again, you benefit automatically
+when new formats are added to AST.
+
+\item[3. Generating Graphical Output]\mbox{}\\
+Producing graphical displays involving curvilinear coordinate systems,
+such as celestial coordinate grids, can be complicated. Particular
+difficulties arise when handling large areas of sky, the polar regions
+and discontinuous (\emph{e.g.}\ segmented) sky projections.  Even just
+numbering and labelling curvilinear axes is rarely straightforward.
+
+\textbf{Solution.} AST provides plotting facilities especially designed
+for use with curvilinear coordinate systems. These include the
+plotting of axes and complete labelled coordinate grids.  A large
+number of options are provided for tailoring the output to your
+specific needs. Three dimensional coordinate grids can also be produced.
+
+\item[4. Aligning Data from Different Sources]\mbox{}\\
+One of the main uses of coordinate systems is to facilitate the
+inter-comparison of data from different sources. A typical use might
+be to plot (say) radio contours over an optical image.  In practice,
+however, different celestial coordinate systems may have been used,
+making accurate alignment far from simple.
+
+\textbf{Solution} AST provides a one-step method of aligning datasets,
+searching for all possible intermediate coordinate systems.  This
+makes it simple to directly inter-relate the pixel coordinates of
+different datasets.
+
+\item[5. Handling Different Types of Coordinate \htmlref{System}{System}]\mbox{}\\
+Not all coordinate systems used in astronomy are celestial ones, so if
+you are writing general-purpose software such as (say) a display tool,
+you may also need to handle axes representing wavelength, distance,
+time or whatever else comes along. Obviously, you would prefer not to
+handle each one as a special case.
+
+\textbf{Solution} AST uses the same flexible high-level model to
+describe all types of coordinate system. This allows you to write
+software that handles different kinds of coordinate axis without
+introducing special cases.
+\end{description}
+
+\subsection{Other Design Objectives}
+
+As well as its scientific objectives, the AST library's design
+includes a number of technical criteria intended to make it applicable
+to as wide a range of projects as possible. The main considerations
+are described here:
+
+\begin{enumerate}
+\item {\bf{Minimum Software Dependencies.}}
+The AST library depends on no other other software\footnote{It comes with
+bundled copies of the ERFA and
+\xref{Starlink PAL libraries}{sun268}{} which are built
+at the same time as the other AST internal libraries. Alternatively, external
+PAL and ERFA libraries may be used by specifying the ``\texttt{--with-external\_pal}'' option when configuring AST}.
+
+\item {\bf{Environment Independence.}}
+AST is designed so that it can operate in a variety of ``programming
+environments'' and is not tied to any particular one. To allow this,
+it uses simple, flexible interfaces to obtain the following services:
+
+\begin{itemize}
+\item {\bf{Data Storage.}} Data I/O operations are based on text
+and/or FITS headers. This makes it easy to interface to a wide variety
+of astronomical data formats in a machine-independent way.
+
+\item {\bf{Graphics.}} Graphical output is produced \emph{via} a
+simple generic graphics interface, which may easily be re-implemented
+over different graphics systems. AST provides a default implementation
+based on the widely-used PGPLOT graphics system
+(\xref{SUN/15}{sun15}{}).
+
+\item {\bf{Error Handling.}} Error messages are written to standard
+error by default, but go through a simple generic interface similar to
+that used for graphics (above). This permits error message delivery
+\emph{via} other routes when necessary (\emph{e.g.} in a graphical
+interface).
+\end{itemize}
+
+\item {\bf{Multiple Language Support.}}
+AST has been designed to be called from more than one language.
+Both C and Fortran interfaces are available (see
+\xref{SUN/210}{sun210}{} for the Fortran version)
+and use from C$++$ is also straightforward if the C interface is
+included using:
+
+\begin{small}
+\begin{terminalv}
+extern "C" {
+#include "ast.h"
+}
+\end{terminalv}
+\end{small}
+
+A JNI interface (known as ``JNIAST'' - see
+\url{http://www.starlink.ac.uk/jniast/}) has also been developed by Starlink
+which allows AST to be used from Java.
+
+\item {\bf{\htmlref{Object}{Object} Oriented Design.}}
+AST uses ``object oriented'' techniques internally in order to provide
+a flexible and easily-extended programming model.  A fairly
+traditional calling interface is provided, however, so that the
+library's facilities are easily accessible to programmers using
+C and Fortran.
+
+\item {\bf{Portability.}}
+AST is implemented entirely in ANSI standard C and, when called
+\emph{via} its C interface, makes no explicit use of any
+machine-dependent facilities.
+
+The Fortran interface is, unavoidably, machine dependent. However, the
+potential for problems has been minimised by encapsulating the
+interface layer in a compact set of C macros which facilitate its
+transfer to other platforms. No Fortran compiler is needed to build
+the library.
+
+Currently, AST is supported by Starlink on PC~Linux, Sun~Solaris and
+Tru64~Unix (formerly DEC~UNIX) platforms.
+\end{enumerate}
+
+\subsection{What Does ``AST'' Stand For?}
+
+The library name ``AST'' stands for ``ASTrometry Library''. The name
+arose when it was thought that knowledge of ``astrometry''
+(\emph{i.e.}\ celestial coordinate systems) would form the bulk of the
+library.  In fact, it turns out that astrometry forms only a minor
+component, but the name AST has stuck.
+
+\cleardoublepage
+\section{Overview of AST Concepts}
+
+This section presents a brief overview of AST concepts. It is intended
+as a basic orientation course before you move on to the more technical
+considerations in subsequent sections.
+
+\subsection{\label{ss:mappingoverview}Relationships Between Coordinate Systems}
+
+The relationships between coordinate systems are represented in AST by
+Objects called Mappings. A \htmlref{Mapping}{Mapping} does not represent a coordinate
+system itself, but merely the process by which you move from one
+coordinate system to another related one.
+
+   A convenient picture of a Mapping is as a ``black box''
+   (Figure~\ref{fig:mapping}) into which you can feed sets of
+   coordinates.
+   \begin{figure}[bhtp]
+   \begin{center}
+   \includegraphics[width=0.7\textwidth]{sun211_figures/mapping}
+   \caption{A Mapping viewed as a ``black box'' for transforming coordinates.}
+   \label{fig:mapping}
+   \end{center}
+   \end{figure}
+
+For each set you feed in, the Mapping returns a corresponding set of
+transformed coordinates. Since each set of coordinates represents a
+point in a coordinate space, the Mapping acts to inter-relate
+corresponding positions in the two spaces, although what these spaces
+represent is unspecified.  Notice that a Mapping need not have the
+same number of input and output coordinates. That is, the two
+coordinate spaces which it inter-relates need not have the same number
+of dimensions.
+
+In many cases, the transformation can, in principle, be performed in
+either direction: either from the \emph{input} coordinate space to the
+\emph{output}, or \emph{vice versa}. The first of these is termed the
+\emph{forward} transformation and the other the \emph{inverse}
+transformation.
+
+
+\textbf{Further reading:} For a more complete discussion of Mappings,
+see~\secref{ss:mappings}.
+
+\subsection{\label{ss:mappingselection}Mappings Available}
+
+The basic concept of a \htmlref{Mapping}{Mapping} (\secref{ss:mappingoverview}) is rather
+generic and obviously it is necessary to have specific Mappings that
+implement specific relationships between coordinate systems. AST
+provides a range of these, to perform transformations such as the
+following and, where appropriate, their inverses:
+
+\begin{itemize}
+\item Conversions between various celestial coordinate systems (the
+\htmlref{SlaMap}{SlaMap}).
+
+\item Conversions between various spectral coordinate systems (the
+\htmlref{SpecMap}{SpecMap} and \htmlref{GrismMap}{GrismMap}).
+
+\item Conversions between various time systems (the \htmlref{TimeMap}{TimeMap}).
+
+\item Conversion between 2-dimensional spherical celestial coordinates
+(longitude and latitude) and a 3-dimensional vectorial positions (the \htmlref{SphMap}{SphMap}).
+
+\item Various projections of the celestial sphere on to 2-dimensional
+coordinate spaces---\emph{i.e.}\ map projections (the \htmlref{DssMap}{DssMap} and \htmlref{WcsMap}{WcsMap}).
+
+\item Permutation, introduction and elimination of coordinates (the
+\htmlref{PermMap}{PermMap}).
+
+\item Various linear coordinate transformations (the \htmlref{MatrixMap}{MatrixMap}, \htmlref{WinMap}{WinMap},
+\htmlref{ShiftMap}{ShiftMap} and \htmlref{ZoomMap}{ZoomMap}).
+
+\item General N-dimensional polynomial transformations (the \htmlref{PolyMap}{PolyMap} and
+\htmlref{ChebyMap}{ChebyMap}).
+
+\item Lookup tables (the \htmlref{LutMap}{LutMap}).
+
+\item General-purpose transformations expressed using arithmetic
+operations and functions similar to those available in C (the
+\htmlref{MathMap}{MathMap}).
+
+\item Transformations for internal use within a program, based on
+private transformation functions which you write yourself in C (the
+\htmlref{IntraMap}{IntraMap}).
+\end{itemize}
+
+\textbf{Further reading:} For a more complete description of each of the
+Mappings mentioned above, see its entry in
+\appref{ss:classdescriptions}. In addition, see the discussion of the
+PermMap in \secref{ss:permmapexample}, the \htmlref{UnitMap}{UnitMap} in
+\secref{ss:unitmapexample} and the IntraMap in
+\secref{ss:intramaps}. The ZoomMap is used as an example throughout
+\secref{ss:primer}.
+
+\subsection{\label{ss:cmpmapoverview}Compound Mappings}
+
+The Mappings described in \secref{ss:mappingselection} provide a set
+of basic building blocks from which more complex Mappings may be
+constructed. The key to doing this is a type of \htmlref{Mapping}{Mapping} called a
+\htmlref{CmpMap}{CmpMap}, or compound Mapping.  A CmpMap's role is, in principle, very
+simple: it allows any other pair of Mappings to be joined together
+into a single entity which behaves as if it were a single Mapping. A
+CmpMap is therefore a container for another pair of Mappings.
+
+   A pair of Mappings may be combined using a CmpMap in either of two
+   ways. The first of these, \emph{in series}, is illustrated in
+   Figure~\ref{fig:seriescmpmap}.
+   \begin{figure}
+   \begin{center}
+   \includegraphics[width=0.7\textwidth]{sun211_figures/series}
+   \caption[A CmpMap composed of two component Mappings joined in series]{A CmpMap (compound Mapping) composed of two component
+   Mappings joined in series. The output coordinates of the first Mapping
+   feed into the input coordinates of the second one, so that the whole
+   entity behaves like a single Mapping.}
+   \label{fig:seriescmpmap}
+   \end{center}
+   \end{figure}
+
+
+   Here, the transformations implemented by each component Mapping are
+   performed one after the other, with the output from the first Mapping
+   feeding into the second.  The second way, \emph{in parallel}, is shown in
+   Figure~\ref{fig:parallelcmpmap}.
+   \begin{figure}
+   \begin{center}
+   \includegraphics[width=0.5\textwidth]{sun211_figures/parallel}
+   \caption[A CmpMap composed of two Mappings joined in parallel.]{A CmpMap composed of two Mappings joined in parallel. Each
+   component Mapping acts on a complementary subset of the input and
+   output coordinates.}
+   \label{fig:parallelcmpmap}
+   \end{center}
+   \end{figure}
+
+In this case, each Mapping acts on a complementary subset of the
+input and output coordinates.\footnote{A pair of Mappings can be combined
+in a third way using a \htmlref{TranMap}{TranMap}. A TranMap allows the forward
+transformation of one Mapping to be combined with the inverse
+transformation of another to produce a single Mapping.}
+
+   The CmpMap forms the key to building arbitrarily complex Mappings
+   because it is itself a form of Mapping. This means that a CmpMap may
+   contain other CmpMaps as components
+   (\emph{e.g.}\ Figure~\ref{fig:complexcmpmap}). This nesting of CmpMaps
+   can be repeated indefinitely, so that complex Mappings may be built in
+   a hierarchical manner out of simper ones.
+   \begin{figure}
+   \begin{center}
+   \includegraphics[width=0.65\textwidth]{sun211_figures/complex}
+   \caption[CmpMaps may be nested in order to
+   construct complex Mappings out of simpler building blocks.]{CmpMaps
+   (compound Mappings) may be nested in order to
+   construct complex Mappings out of simpler building blocks.}
+   \label{fig:complexcmpmap}
+   \end{center}
+   \end{figure}
+   This gives AST great flexibility in the coordinate transformations it
+   can describe.
+
+\textbf{Further reading:} For a more complete description of CmpMaps,
+see \secref{ss:cmpmaps}. Also see the CmpMap entry in
+\appref{ss:classdescriptions}.
+
+\subsection{Representing Coordinate Systems}
+
+   While Mappings (\secref{ss:mappingoverview}) represent the
+   relationships between coordinate systems in AST, the coordinate
+   systems themselves are represented by Objects called Frames
+   (Figure~\ref{fig:frames}).
+   \begin{figure}
+   \begin{center}
+   \includegraphics[width=0.55\textwidth]{sun211_figures/frames}
+   \caption[Representing coordinate systems as Frames.]{(a) A basic Frame is used to represent a Cartesian coordinate
+   system, here 2-dimensional. (b) A \htmlref{SkyFrame}{SkyFrame} represents a (spherical)
+   celestial coordinate system. (c) The axis order of any \htmlref{Frame}{Frame} may be
+   permuted to match the coordinate space it describes.}
+   \label{fig:frames}
+   \end{center}
+   \end{figure}
+
+A Frame is similar in concept to the frame you might draw around a
+graph.  It contains information about the labels which appear on the
+axes, the axis units, a title, knowledge of how to format the
+coordinate values on each axis, \emph{etc.}  An AST Frame is not,
+however, restricted to two dimensions and may have any number of axes.
+
+A basic Frame may be used to represent a Cartesian coordinate system
+by setting values for its \emph{attributes} (all AST Objects have
+values associated with them called attributes, which may be set and
+enquired).  Usually, this would involve setting appropriate axis
+labels and units, for example.  Functions are provided for use with
+Frames to perform operations such as formatting coordinate values as
+text, calculating distances between points, interchanging axes,
+\emph{etc.}
+
+There are several more specialised forms of Frame, which provide the
+additional functionality required when handling coordinates within some
+specific physical domain. This ranges from tasks such as formatting axis
+values, to complex tasks such as determining the transformation between
+any pair of related coordinate systems. For instance, the SkyFrame
+(Figure~\ref{fig:frames}b,c), represents celestial coordinate systems,
+the \htmlref{SpecFrame}{SpecFrame} represents spectral coordinate systems, and the \htmlref{TimeFrame}{TimeFrame}
+represents time coordinate systems. All these provide a wide range of
+different systems for describing positions within their associated physical
+domain, and these may be selected by setting appropriate attributes.
+
+   As with compound Mappings (\secref{ss:cmpmapoverview}), it is possible
+   to merge two Frames together to form a compound Frame, or \htmlref{CmpFrame}{CmpFrame}, in
+   which both sets of axes are combined.  One could, for example, have
+   celestial coordinates on two axes and an unrelated coordinate
+   (wavelength, perhaps) on a third (Figure~\ref{fig:cmpframe}).
+   Knowledge of the relationships between the axes is preserved
+   internally by the process of constructing the CmpFrame which
+   represents them.
+   \begin{figure}
+   \begin{center}
+   \includegraphics[width=0.4\textwidth]{sun211_figures/cmpframe}
+   \caption[A CmpFrame (compound Frame) formed by combining two simpler
+   Frames.]{A CmpFrame (compound Frame) formed by combining two simpler
+   Frames. Note how the special relationship which exists between the RA
+   and Dec axes is preserved within this data structure. As with compound
+   Mappings (Figure~\ref{fig:complexcmpmap}), CmpFrames may be nested in
+   order to build more complex Frames.}
+   \label{fig:cmpframe}
+   \end{center}
+   \end{figure}
+
+\textbf{Further reading:} For a more complete description of Frames see
+\secref{ss:frames}, for SkyFrames see \secref{ss:skyframes} and for
+SpecFrames see \secref{ss:specframes}.  Also see the Frame, SkyFrame,
+SpecFrame, TimeFrame and CmpFrame entries in \appref{ss:classdescriptions}.
+
+\subsection{Networks of Coordinate Systems}
+
+   Mappings and Frames may be connected together to form networks called
+   FrameSets, which are used to represent sets of inter-related
+   coordinate systems (Figure~\ref{fig:frameset}).
+   \begin{figure}
+   \begin{center}
+   \includegraphics[width=0.65\textwidth]{sun211_figures/frameset}
+   \caption[A FrameSet is a network of Frames.]{A FrameSet is a network of Frames inter-connected by Mappings
+   such that there is exactly one conversion path, \emph{via} Mappings,
+   between any pair of Frames.}
+   \label{fig:frameset}
+   \end{center}
+   \end{figure}
+
+
+A \htmlref{FrameSet}{FrameSet} may be extended by adding a new \htmlref{Frame}{Frame} to it, together with
+an associated \htmlref{Mapping}{Mapping} which relates the new coordinate system to one
+which is already present.  This process ensures that there is always
+exactly one path, \emph{via} Mappings, between any pair of Frames.  A
+function is provided for identifying this path and returning the
+complete Mapping.
+
+One of the Frames in a FrameSet is termed its \emph{base} Frame.  This
+underlies the FrameSet's purpose, which is to calibrate datasets and
+other entities by attaching coordinate systems to them.  In this
+context, the base Frame represents the ``native'' coordinate system
+(for example, the pixel coordinates of an image).  Similarly, one
+Frame is termed the \emph{current} Frame and represents the
+``currently-selected'' coordinates.  It might, typically, be a
+celestial or spectral coordinate system and would be used during
+interactions with
+a user, as when plotting axes on a graph or producing a table of
+results.  Other Frames within the FrameSet represent a library of
+alternative coordinate systems which a software user can select by
+making them current.
+
+\textbf{Further reading:} For a more complete description of
+FrameSets, see \secref{ss:framesets} and \secref{ss:fshigher}. Also
+see the FrameSet entry in \appref{ss:classdescriptions}.
+
+\subsection{Input/Output Facilities}
+
+AST allows you to convert any kind of \htmlref{Object}{Object} into a stream of text
+which contains a full description of that Object. This text may be
+written out by one program and read back in by another, thus allowing
+the original Object to be reconstructed.
+
+The filter which converts Objects into text and back again is itself a
+kind of Object, called a \htmlref{Channel}{Channel}. A Channel provides a number of
+options for controlling the information content of the text, such as
+the addition of comments for human interpretation.  It is also
+possible to intercept the text being processed by a Channel so that it
+may be redirected to/from any chosen external data store, such as a
+text file, an astronomical dataset, or a network connection.
+
+The text format used by the basic Channel class is peculiar to the AST
+library - no other software will understand it. However, more specialised
+forms of Channel are provided which use text formats more widely
+understood.
+
+To further facilitate the storage of coordinate system information in
+astronomical datasets, a more specialised form of Channel called a
+\htmlref{FitsChan}{FitsChan} is provided. Instead of using free-format text, a FitsChan
+converts AST Objects to and from FITS header cards. It also allows the
+information to be encoded in the FITS cards in a number of ways
+(called \emph{encodings}), so that WCS information from a variety of
+sources can be handled.
+
+Another sub-class of Channel, called \htmlref{XmlChan}{XmlChan}, is a specialised form of
+Channel that stores the text in the form of XML markup. Currently, two
+markup formats are provided by the XmlChan class, one is closely related
+to the text format produced by the basic Channel class (currently, no
+schema or DTD is available describing this format). The other is a subset
+of an early draft of the IVOA Space-Time-Coordinates XML (STC-X) schema
+(V1.20) described at
+\url{http://www.ivoa.net/Documents/WD/STC/STC-20050225.html
+}\footnote{XML documents which use only the subset of the STC schema
+supported by AST can be read by the XmlChan class to produce
+corresponding AST objects (subclasses of the \htmlref{Stc}{Stc} class). However, the
+reverse is not possible. That is, AST objects can not currently be
+written out in the form of STC documents.}. The version of STC-X that has
+been adopted by the IVOA differs in several significant respects from
+V1.20, and therefore this XmlChan format is of historical interest only.
+
+Finally, the \htmlref{StcsChan}{StcsChan} class provides facilities for reading and writing
+IVOA STC-S region descriptions. STC-S (see
+\url{http://www.ivoa.net/Documents/latest/STC-S.html}) is a linear string
+syntax that allows simple specification of STC metadata. AST supports a
+subset of the STC-S specification, allowing an STC-S description of a
+region within an AST-supported astronomical coordinate system to be converted
+into an equivalent AST \htmlref{Region}{Region} object, and vice-versa.
+
+\textbf{Further reading:} For a more complete description of Channels
+see \secref{ss:channels} and for FitsChans see \secref{ss:nativefits}
+and \secref{ss:foreignfits}. Also see the Channel and FitsChan entries
+in \appref{ss:classdescriptions} and the \htmlref{Encoding}{Encoding} entry in
+\appref{ss:attributedescriptions}.
+
+\subsection{Producing Graphical Output}
+
+Two dimensional graphical output is supported by a specialised form of
+\htmlref{FrameSet}{FrameSet} called
+a \htmlref{Plot}{Plot}, whose base \htmlref{Frame}{Frame} corresponds with the native coordinates of
+the underlying graphics system.  Plotting operations are specified in
+\emph{physical coordinates} which correspond with the Plot's current
+Frame. Typically, this might be a celestial coordinate system.
+
+Three dimensional plotting is also supported, via the \htmlref{Plot3D}{Plot3D} class -
+sub-class of Plot.
+
+Operations, such as drawing lines, are automatically transformed from
+physical to graphical coordinates before plotting, using an adaptive
+algorithm which ensures smooth curves (because the transformation is
+usually non-linear).  ``Missing'' coordinates (\emph{e.g.}\ graphical
+coordinates which do not project on to the celestial sphere),
+discontinuities and generalised clipping are all consistently handled.
+It is possible, for example, to plot in equatorial coordinates and
+clip in galactic coordinates.  The usual plotting operations are
+provided (text, markers), but a geodesic curve replaces the primitive
+straight line element.  There is also a separate function for drawing
+axis lines, since these are normally not geodesics.
+
+In addition to drawing coordinate grids over an area of the sky, another
+common use of the Plot class is to produce line plots such as flux
+against wavelength, displacement again time, \emph{etc}. For these
+situations the current Frame of the Plot would be a compound Frame
+(\htmlref{CmpFrame}{CmpFrame}) containing a pair of 1-dimensional Frames - the first
+representing the X axis quantity (wavelength, time, etc), and the second
+representing the Y axis quantity (flux, displacement, etc). The Plot
+class includes an option for axes to be plotted logarithmically.
+
+   Perhaps the most useful graphics function available is for drawing
+   fully annotated coordinate grids (\emph{e.g.}\ Figure~\ref{fig:gridplot}).
+   \begin{figure}
+   \begin{center}
+   \includegraphics[width=0.6\textwidth]{sun211_figures/gridplot_bw}
+   \caption[A labelled coordinate grid for an all-sky zenithal equal area
+   projection in ecliptic coordinates.]{A labelled coordinate grid for an all-sky zenithal equal area
+   projection in ecliptic coordinates. This was composed and drawn
+   \emph{via} a Plot using a
+   single function call.}
+   \label{fig:gridplot}
+   \end{center}
+   \end{figure}
+
+This uses a general algorithm which does not depend on knowledge of
+the coordinates being represented, so can also handle
+programmer-defined coordinate systems.  Grids for all-sky projections,
+including polar regions, can be drawn and most aspects of the output
+(colour, line style, \emph{etc.}) can be adjusted by setting
+appropriate Plot attributes.
+
+\textbf{Further reading:} For a more complete description of
+Plots and how to produce graphical output, see \secref{ss:plots}. Also
+see the Plot entry in \appref{ss:classdescriptions}.
+
+\cleardoublepage
+\section{\label{ss:howto}How To\ldots}
+
+For those of you with a plane to catch, this section provides some
+instant templates and recipes for performing the most
+commonly-required operations using AST, but without going into
+detail. The examples given (sort of) follow on from each other, so you
+should be able to construct a variety of programs by piecing them
+together.  Note that some of them appear longer than they actually
+are, because we have included plenty of comments and a few options
+that you probably won't need.
+
+If any of this material has you completely baffled, then you may want
+to read the introduction to AST programming concepts in
+\secref{ss:primer} first. Otherwise, references to more detailed
+reading are given after each example, just in case they don't quite do
+what you want.
+
+\subsection{\ldots Obtain and Install AST}
+The AST library is available both as a stand-alone package and also as
+part of the Starlink Software Collection\footnote{The Starlink Software
+Collection can be downloaded from
+\url{http://www.starlink.ac.uk/Download/}.}. If your site has the Starlink
+Software Collection installed then AST should already be available.
+
+If not, you can download the AST library by itself from
+\url{http://www.starlink.ac.uk/ast/}.
+
+\subsection{\ldots Structure an AST Program}
+
+An AST program normally has the following structure:
+
+\begin{small}
+\begin{terminalv}
+/* Include the interface to the AST library. */
+#include "ast.h"
+
+/* Main program (or could be any function). */
+main () {
+   <normal C declarations and statements>
+
+/* Enclose the parts which use AST between the astBegin and astEnd macros. */
+   astBegin;
+   <C statements which use AST>
+   astEnd;
+
+   <maybe more C statements>
+}
+\end{terminalv}
+\end{small}
+
+The use of \htmlref{astBegin}{astBegin} and \htmlref{astEnd}{astEnd} is optional, but has the effect of
+tidying up after you have finished using AST, so is normally
+recommended. For more details of this, see \secref{ss:contexts}. For
+details of how to access the ``ast.h'' header file, see
+\secref{ss:accessingheaderfile}.
+
+\subsection{\label{ss:howtobuild}\ldots Build an AST Program}
+
+To build a simple AST program that doesn't use graphics, use:
+
+\begin{small}
+\begin{terminalv}
+cc program.c -L/star/lib -I/star/include `ast_link` -o program
+\end{terminalv}
+\end{small}
+
+To build a program which uses PGPLOT for graphics, use:
+
+\begin{small}
+\begin{terminalv}
+cc program.c -L/star/lib `ast_link -pgplot` -o program
+\end{terminalv}
+\end{small}
+
+For more details about accessing the ``ast.h'' header file, see
+\secref{ss:accessingheaderfile}. For more
+details about linking programs, see \secref{ss:linking} and the
+description of the ``\htmlref{ast\_link}{ast\_link}'' command in
+\appref{ss:commanddescriptions}.
+
+\subsection{\label{ss:howtoreadwcs}\ldots Read a WCS Calibration from a Dataset}
+
+Precisely how you extract world coordinate system (WCS) information
+from a dataset obviously depends on what type of dataset it
+is. Usually, however, you should be able to obtain a set of FITS
+header cards which contain the WCS information (and probably much more
+besides). Suppose that ``cards'' is a pointer to a string
+containing a complete set of concatenated FITS header cards (such as
+produced by the CFITSIO function fits\_hdr2str). Then proceed as follows:
+
+\begin{small}
+\begin{terminalv}
+fitsfile *fptr;
+AstFitsChan *fitschan;
+AstFrameSet *wcsinfo;
+char *header;
+int nkeys, status;
+
+...
+
+/* Obtain all the cards in the header concatenated into a single dynamically
+   allocated null-terminated character string. Note, we do not exclude
+   any cards since we may later modify the WCS information within the
+   header and consequently want to write the entire header out again. */
+   if( fits_hdr2str( fptr, 0, NULL, 0, &header, &nkeys, &status ) )
+          printf(" Error getting header\n");
+   ...
+
+/* Header obtained succesfully... */
+   } else {
+
+/* Create a FitsChan and fill it with FITS header cards. */
+      fitschan = astFitsChan( NULL, NULL, "" );
+      astPutCards( fitschan, header );
+
+/* Free the memory holding the concatenated header cards. */
+      header = free( header );
+
+/* Read WCS information from the FitsChan. */
+      wcsinfo = astRead( fitschan );
+
+      ...
+
+\end{terminalv}
+\end{small}
+
+
+The result should be a pointer, ``wcsinfo'', to a \htmlref{FrameSet}{FrameSet} which
+contains the WCS information. This pointer can now be used to perform
+many useful tasks, some of which are illustrated in the following
+recipes.
+
+Some datasets which do not easily yield FITS header cards may require
+a different approach, possibly involving use of a \htmlref{Channel}{Channel} or \htmlref{XmlChan}{XmlChan}
+(\secref{ss:channels}) rather than a \htmlref{FitsChan}{FitsChan}. In the case of the
+Starlink NDF data format, for example, all the above may be replaced
+by a single call to the function
+\xref{ndfGtwcs}{sun33}{ndfGtwcs}---see \xref{SUN/33}{sun33}{}.  The
+whole process can probably be encapsulated in a similar way for
+most data systems, whether they use FITS header cards or not.
+
+For more details about reading WCS information from datasets, see
+\secref{ss:identifyingfitsencoding} and
+\secref{ss:readingforeignfits}. For a more general description of
+FitsChans and their use with FITS header cards, see
+\secref{ss:nativefits} and \secref{ss:foreignfits}. For more details
+about FrameSets, see \secref{ss:framesets} and \secref{ss:fshigher}.
+
+\subsection{\ldots Validate WCS Information}
+
+Once you have read WCS information from a dataset, as in
+\secref{ss:howtoreadwcs}, you may wish to check that you have been
+successful. The following will detect and classify the things that
+might possibly go wrong:
+
+\begin{small}
+\begin{terminalv}
+#include <string.h>
+
+...
+
+if ( !astOK ) {
+   <an error occurred (a message will have been issued)>
+} else if ( wcsinfo == AST__NULL ) {
+   <there was no WCS information present>
+} else if ( strcmp( astGetC( wcsinfo, "Class" ), "FrameSet" ) ) {
+   <something unexpected was read (i.e. not a FrameSet)>
+} else {
+   <WCS information was read OK>
+}
+\end{terminalv}
+\end{small}
+
+For more information about detecting errors in AST functions, see
+\secref{ss:errordetection}. For details of how to validate input data
+read by AST, see \secref{ss:validatinginput} and
+\secref{ss:readingforeignfits}.
+
+\subsection{\ldots Display AST Data}
+
+If you have a pointer to any AST \htmlref{Object}{Object}, you can display the data
+stored in that Object in textual form as follows:
+
+\begin{small}
+\begin{terminalv}
+astShow( wcsinfo );
+\end{terminalv}
+\end{small}
+
+Here, we have used a pointer to the \htmlref{FrameSet}{FrameSet} which we read earlier
+(\secref{ss:howtoreadwcs}).  The result is written to the program's
+standard output stream. This can be very useful during debugging.
+
+For more details about using \htmlref{astShow}{astShow}, see
+\secref{ss:displayingobjects}. For information about interpreting the
+output, also see \secref{ss:textualoutputformat}.
+
+\subsection{\label{ss:howtotransform}\ldots Convert Between Pixel and World Coordinates}
+
+You may use a pointer to a \htmlref{FrameSet}{FrameSet}, such as we read in
+\secref{ss:howtoreadwcs}, to transform a set of points between the
+pixel coordinates of an image and the associated world coordinates. If
+you are working in two dimensions, proceed as follows:
+
+\begin{small}
+\begin{terminalv}
+double xpixel[ N ], ypixel[ N ];
+double xworld[ N ], yworld[ N ];
+
+...
+
+astTran2( wcsinfo, N, xpixel, ypixel, 1, xworld, yworld );
+\end{terminalv}
+\end{small}
+
+Here, N is the number of points to be transformed, ``xpixel'' and
+``ypixel'' hold the pixel coordinates, and ``xworld'' and ``yworld''
+receive the returned world coordinates.\footnote{By pixel coordinates,
+we mean a coordinate system in which the first pixel in the image is
+centred on (1,1) and each pixel is a unit square.  Note that the world
+coordinates will not necessarily be celestial coordinates, but if they
+are, then they will be in radians.}  To transform in the opposite
+direction, interchange the two pairs of arrays (so that the world
+coordinates are given as input) and change the fifth argument of
+\htmlref{astTran2}{astTran2} to zero.
+
+To transform points in one dimension, use \htmlref{astTran1}{astTran1}. In any other
+number of dimensions (or if the number of dimensions is initially
+unknown), use \htmlref{astTranN}{astTranN} or \htmlref{astTranP}{astTranP}. These functions are described in
+\appref{ss:functiondescriptions}.
+
+For more information about transforming coordinates, see
+\secref{ss:transforming} and \secref{ss:framesetasmapping}. For
+details of how to handle missing coordinates, see
+\secref{ss:badcoordinates}.
+
+\subsection{\label{ss:howtotestforcelestial}\ldots Test if a WCS is a Celestial Coordinate System}
+
+The world coordinate system (WCS) currently associated with an image
+may often be a celestial coordinate system, but this need not
+necessarily be the case. For instance, instead of right ascension and
+declination, an image might have a WCS with axes representing
+wavelength and slit position, or maybe just plain old pixels.
+
+If you have obtained a WCS calibration for an image, as in
+\secref{ss:howtoreadwcs}, in the form of a pointer ``wcsinfo'' to a
+\htmlref{FrameSet}{FrameSet}, then you may determine if the current coordinate system is a
+celestial one or not, as follows:
+
+\begin{small}
+\begin{terminalv}
+AstFrame *frame;
+int issky;
+
+...
+
+/* Obtain a pointer to the current Frame and determine if it is a
+   SkyFrame. */
+frame = astGetFrame( wcsinfo, AST__CURRENT );
+issky = astIsASkyFrame( frame );
+frame = astAnnul( frame );
+\end{terminalv}
+\end{small}
+
+This will set ``issky'' to 1 if the WCS is a celestial coordinate
+system, and to zero otherwise.
+
+\subsection{\label{ss:howtotestforspectral}\ldots Test if a WCS is a Spectral Coordinate System}
+Testing for a spectral coordinate system is basically the same as testing
+for a celestial coordinate system (see the previous section). The one
+difference is that you use the
+astIsASpecFrame function
+in place of the
+astIsASkyFrame function.
+
+\subsection{\label{ss:howtoformatcoordinates}\ldots Format Coordinates for Display}
+
+Once you have converted pixel coordinates into world coordinates
+(\secref{ss:howtotransform}), you may want to format them as text
+before displaying them. Typically, this would convert from (say)
+radians into something more comprehensible. Using the \htmlref{FrameSet}{FrameSet} pointer
+``wcsinfo'' obtained in \secref{ss:howtoreadwcs} and a pair of world
+coordinates ``xw'' and ``yw'' (\emph{e.g.}\ see
+\secref{ss:howtotransform}), you could proceed as follows:
+
+\begin{small}
+\begin{terminalv}
+#include <stdio.h>
+const char *xtext, *ytext;
+double xw, yw;
+
+...
+
+xtext = astFormat( wcsinfo, 1, xw );
+ytext = astFormat( wcsinfo, 2, yw );
+
+(void) printf( "Position = %s, %s\n", xtext, ytext );
+\end{terminalv}
+\end{small}
+
+Here, the second argument to \htmlref{astFormat}{astFormat} is the axis number.
+
+With celestial coordinates, this will usually result in sexagesimal
+notation, such as ``12:34:56.7''. However, the same method may be
+applied to any type of coordinates and appropriate formatting will be
+employed.
+
+For more information about formatting coordinate values and how to
+control the style of formatting used, see
+\secref{ss:formattingaxisvalues} and
+\secref{ss:formattingskyaxisvalues}. If necessary, also see
+\secref{ss:normalising} for details of how to ``normalise'' a set of
+coordinates so that they lie within the standard range (\emph{e.g.}\ 0
+to 24 hours for right ascension and $\pm 90^\circ$ for
+declination).
+
+\subsection{\ldots Display Coordinates as they are Transformed}
+
+In addition to formatting coordinates as part of a program's output,
+you may also want to examine coordinate values while debugging your
+program. To save time, you can ``eavesdrop'' on the coordinate values
+being processed every time they are transformed. For example, when
+using the \htmlref{FrameSet}{FrameSet} pointer ``wcsinfo'' obtained in
+\secref{ss:howtoreadwcs} to transform coordinates
+(\secref{ss:howtotransform}), you could inspect the coordinate values
+as follows:
+
+\begin{small}
+\begin{terminalv}
+astSet( wcsinfo, "Report=1" );
+astTran2( wcsinfo, N, xpixel, ypixel, 1, xworld, yworld );
+\end{terminalv}
+\end{small}
+
+By setting the FrameSet's \htmlref{Report}{Report} attribute to 1, coordinate
+transformations are automatically displayed on the program's standard
+output stream, appropriately formatted, for example:
+
+\begin{terminalv}
+(42.1087, 20.2717) --> (2:06:03.0, 34:22:39)
+(43.0197, 21.1705) --> (2:08:20.6, 35:31:24)
+(43.9295, 22.0716) --> (2:10:38.1, 36:40:09)
+(44.8382, 22.9753) --> (2:12:55.6, 37:48:55)
+(45.7459, 23.8814) --> (2:15:13.1, 38:57:40)
+(46.6528, 24.7901) --> (2:17:30.6, 40:06:25)
+(47.5589, 25.7013) --> (2:19:48.1, 41:15:11)
+(48.4644, 26.6149) --> (2:22:05.6, 42:23:56)
+(49.3695, 27.5311) --> (2:24:23.1, 43:32:41)
+(50.2742, 28.4499) --> (2:26:40.6, 44:41:27)
+\end{terminalv}
+
+For a complete description of the Report attribute, see its entry in
+\appref{ss:attributedescriptions}.  For further details of how to set
+and enquire attribute values, see \secref{ss:settingattributes} and
+\secref{ss:gettingattributes}.
+
+\subsection{\ldots Read Coordinates Entered by a User}
+
+In addition to writing out coordinate values generated by your program
+(\secref{ss:howtoformatcoordinates}), you may also need to accept
+coordinates entered by a user, or perhaps read from a file. In this
+case, you will probably want to allow ``free-format'' input, so that
+the user has some flexibility in the format that can be used. You will
+probably also want to detect any typing errors.
+
+Let's assume that you want to read a number of lines of text, each
+containing the world coordinates of a single point, and to split each
+line into individual numerical coordinate values. Using the \htmlref{FrameSet}{FrameSet}
+pointer ``wcsinfo'' obtained earlier (\secref{ss:howtoreadwcs}), you
+could proceed as follows:
+
+\begin{small}
+\begin{terminalv}
+#include <stdio.h>
+char *t;
+char text[ MAXCHARS + 2 ];
+double coord[ 10 ];
+int iaxis, n, naxes;
+
+...
+
+/* Obtain the number of coordinate axes (if not already known). */
+naxes = astGetI( wcsinfo, "Naxes" );
+
+/* Loop to read each line of input text, in this case from the
+   standard input stream (your programming environment will probably
+   provide a better way of reading text than this). Set the pointer
+   "t" to the start of each line read. */
+while ( t = fgets( text, MAXCHARS + 2, stdin ) ) {
+
+/* Attempt to read a coordinate for each axis. */
+   for ( iaxis = 1; iaxis <= naxes; iaxis++ ) {
+      n = astUnformat( wcsinfo, iaxis, t, &coord[ iaxis - 1 ] );
+
+/* If nothing was read and this is not the first axis or the
+   end-of-string, try stepping over a separator and reading again. */
+   if ( !n && ( iaxis > 1 ) && *t )
+      n = astUnformat( wcsinfo, iaxis, ++t, &coord[ iaxis - 1 ] );
+
+/* Quit if nothing was read, otherwise move on to the next coordinate. */
+      if ( !n ) break;
+      t += n;
+   }
+
+/* Test for the possible errors that may occur... */
+
+/* Error detected by AST (a message will have been issued). */
+   if ( !astOK ) {
+      break;
+
+/* Error in input data at character t[n]. */
+   } else if ( *t || !n ) {
+      <handle the error, or report your own message here>
+      break;
+
+   } else {
+      <coordinates were read OK>
+   }
+}
+\end{terminalv}
+\end{small}
+
+This algorithm has the advantage of accepting free-format input in
+whatever style is appropriate for the world coordinates in use (under
+the control of the FrameSet whose pointer you provide). For example,
+wavelength values might be read as floating point numbers
+(\emph{e.g.}\ ``1.047'' or ``4787''), whereas celestial positions
+could be given in sexagesimal format (\emph{e.g.}\ ``12:34:56'' or
+``12~34.5'') and would be converted into radians. Individual
+coordinate values may be separated by white space and/or any
+non-ambiguous separator character, such as a comma.
+
+For more information on reading coordinate values using the
+\htmlref{astUnformat}{astUnformat} function, see \secref{ss:unformattingaxisvalues}. For
+details of how sexagesimal formats are handled, and the forms of input
+that may be used for celestial coordinates, see
+\secref{ss:unformattingskyaxisvalues}.
+
+\subsection{\label{ss:howtocreatenewwcs}\ldots Create a New WCS Calibration}
+
+This section describes how to add a WCS calibration to a data set which you
+are creating from scratch, rather than modifying an existing data set.
+
+In most common cases, the simplest way to create a new WCS calibration
+from scratch is probably to create a set of strings describing the
+required calibration in terms of the keywords used by the FITS WCS
+standard, and then convert these strings into an AST \htmlref{FrameSet}{FrameSet} describing
+the calibration. This FrameSet can then be used for many other purposes, or
+simply stored in the data set.
+
+The full FITS-WCS standard is quite involved, currently running to four
+separate papers, but the basic kernel is quite simple, involving the
+following keywords (all of which end with an integer axis index,
+indicated below by $<i>$):
+
+\begin{description}
+\item[CRPIX<i>]\mbox{}\\
+hold the pixel coordinates at a reference point
+\item[CRVAL<i>]\mbox{}\\
+hold the corresponding WCS coordinates at the reference point
+\item[CTYPE<i>]\mbox{}\\
+name the quantity represented by the WCS axes, together with the
+projection algorithm used to convert the scaled and rotated pixel coordinates
+to WCS coordinates.
+\item[CD<i>\_<j>]\mbox{}\\
+a set of keywords which specify the elements of a matrix. This matrix scales
+pixel offsets from the reference point into the offsets required as input
+by the projection algorithm specified by the CTYPE keywords. This matrix
+specifies the scale and rotation of the image. If there is no rotation
+the off-diagonal elements of the matrix (\emph{e.g.} CD1\_2 and
+CD2\_1) can be omitted.
+\end{description}
+
+As an example consider the common case of a simple 2D image of the sky in
+which north is parallel to the second pixel axis and east parallel to the
+(negative) first pixel axis. The image scale is 1.2 arc-seconds per pixel
+on both axes, and the image is presumed to have been obtained with a
+tangent plane projection. Furthermore, it is known that pixel coordinates
+(100.5,98.4) correspond to an RA of 11:00:10 and a Dec. of  -23:26:02.
+A suitable set of FITS-WCS header cards could be:
+
+\begin{small}
+\begin{terminalv}
+CTYPE1  = 'RA---TAN'       / Axis 1 represents RA with a tan projection
+CTYPE2  = 'DEC--TAN'       / Axis 2 represents Dec with a tan projection
+CRPIX1  = 100.5            / Pixel coordinates of reference point
+CRPIX2  = 98.4             / Pixel coordinates of reference point
+CRVAL1  = 165.04167        / Degrees equivalent of "11:00:10" hours
+CRVAL2  = -23.433889       / Decimal equivalent of "-23:26:02" degrees
+CD1_1   = -0.0003333333    / Decimal degrees equivalent of -1.2 arc-seconds
+CD2_2   = 0.0003333333     / Decimal degrees equivalent of 1.2 arc-seconds
+\end{terminalv}
+\end{small}
+
+Notes:
+\begin{itemize}
+\item a FITS header card begins with the keyword name starting at column 1,
+has an equals sign in column 9, and the keyword value in columns 11 to 80.
+\item string values must be enclosed in single quotes.
+\item celestial longitude and latitude must both be specified in decimal degrees.
+\item the CD1\_1 value is negative to indicate that RA increases as the
+first pixel axis decreases.
+\item the (RA,Dec) coordinates will be taken as ICRS coordinates. For FK5
+you should add:
+
+\begin{small}
+\begin{terminalv}
+RADESYS = 'FK5'
+EQUINOX = 2005.6
+\end{terminalv}
+\end{small}
+
+The EQUINOX value defaults to J2000.0 if omitted. FK4 can also be used in
+place of FK5, in which case EQUINOX defaults to B1950.0.
+
+\end{itemize}
+
+Once you have created these FITS-WCS header card strings, you should
+store them in a \htmlref{FitsChan}{FitsChan} and then read the corresponding FrameSet from the
+FitsChan. How to do this is described in \secref{ss:howtoreadwcs}.
+
+Having created the WCS calibration, you may want to store it in a data
+file. How to do this is described in \secref{ss:howtowritewcs}).\footnote{If
+you are writing the WCS calibration to a FITS file you obviously
+have the choice of storing the FITS-WCS cards directly.}
+
+If the required WCS calibration cannot be described as a set of FITS-WCS
+headers, then a different approach is necessary. In this case, you should
+first create a \htmlref{Frame}{Frame} describing pixel coordinates, and store this Frame
+in a new FrameSet. You should then create a new Frame describing the
+world coordinate system. This Frame may be a specific subclass of Frame such
+as a \htmlref{SkyFrame}{SkyFrame} for celestial coordinates, a \htmlref{SpecFrame}{SpecFrame} for spectral
+coordinates, a Timeframe for time coordinates, or a \htmlref{CmpFrame}{CmpFrame} for a combination
+of different coordinates.
+You also need to create a suitable \htmlref{Mapping}{Mapping} which transforms pixel
+coordinates into world coordinates. AST provides many different types of
+Mappings, all of which can be combined together in arbitrary fashions to
+create more complicated Mappings. The WCS Frame should then be added into
+the FrameSet, using the Mapping to connect the WCS Frame with the pixel
+Frame.
+
+\subsection{\label{ss:howtomodifywcs}\ldots Modify a WCS Calibration}
+
+The usual reason for wishing to modify the WCS calibration associated
+with a dataset is that the data have been geometrically transformed in
+some way (here, we will assume a 2-dimensional image dataset). This
+causes the image features (stars, galaxies, \emph{etc.}) to move with
+respect to the grid of pixels which they occupy, so that any
+coordinate systems previously associated with the image become
+invalid.
+
+To correct for this, it is necessary to set up a \htmlref{Mapping}{Mapping} which
+expresses the positions of image features in the new data grid in
+terms of their positions in the old grid. In both cases, the grid
+coordinates we use will have the first pixel centred at (1,1) with
+each pixel being a unit square.
+
+AST allows you to correct for any type of geometrical transformation
+in this way, so long as a suitable Mapping to describe it can be
+constructed. For purposes of illustration, we will assume here that
+the new image coordinates ``xnew'' and ``ynew'' can be expressed in
+terms of the old coordinates ``xold'' and ``yold'' as follows:
+
+\begin{small}
+\begin{terminalv}
+double xnew, xold, ynew, yold;
+double m[ 4 ], z[ 2 ];
+
+...
+
+xnew = xold * m[ 0 ] + yold * m[ 1 ] + z[ 0 ];
+ynew = xold * m[ 2 ] + yold * m[ 3 ] + z[ 1 ];
+\end{terminalv}
+\end{small}
+
+where ``m'' is a 2$\times$2 transformation matrix and ``z'' represents
+a shift of origin. This is therefore a general linear coordinate
+transformation which can represent displacement, rotation,
+magnification and shear.
+
+In AST, it can be represented by concatenating two Mappings. The first
+is a \htmlref{MatrixMap}{MatrixMap}, which implements the matrix multiplication. The second
+is a \htmlref{WinMap}{WinMap}, which linearly transforms one coordinate window on to
+another, but will be used here simply to implement the shift of
+origin (alternatively, a \htmlref{ShiftMap}{ShiftMap} could have been used in place of a
+WinMap). These Mappings may be constructed and concatenated as follows:
+
+\begin{small}
+\begin{terminalv}
+AstCmpMap *newmap;
+AstMatrixMap *matrixmap;
+AstWinMap *winmap;
+
+...
+
+/* The MatrixMap may be constructed directly from the matrix "m". */
+matrixmap = astMatrixMap( 2, 2, 0, m, "" );
+
+/* For the WinMap, we set up the coordinates of the corners of a unit
+   square (window) and then the same square shifted by the required
+   amount. */
+{
+   double ina[] = { 0.0, 0.0 };
+   double inb[] = { 1.0, 1.0 };
+   double outa[] = {       z[ 0 ],       z[ 1 ] };
+   double outb[] = { 1.0 + z[ 0 ], 1.0 + z[ 1 ] };
+
+/* The WinMap will then implement this shift. */
+   winmap = astWinMap( 2, ina, inb, outa, outb, "" );
+}
+
+/* Join the two Mappings together, so that they are applied one after
+   the other. */
+newmap = astCmpMap( matrixmap, winmap, 1, "" );
+\end{terminalv}
+\end{small}
+
+You might, of course, create any other form of Mapping depending on
+the type of geometrical transformation involved. For an overview of
+the Mappings provided by AST, see \secref{ss:mappingselection}, and
+for a description of the capabilities of each class of Mapping, see
+its entry in \appref{ss:classdescriptions}. For an overview of how
+individual Mappings may be combined, see \secref{ss:cmpmapoverview}
+(\secref{ss:cmpmaps} gives more details).
+
+Assuming you have obtained a WCS calibration for your original image
+in the form of a pointer to a \htmlref{FrameSet}{FrameSet}, ``wcsinfo1''
+(\secref{ss:howtoreadwcs}), the Mapping created above may be used to
+produce a calibration for the new image as follows:
+
+\begin{small}
+\begin{terminalv}
+AstFrameSet *wcsinfo1, *wcsinfo2;
+
+...
+
+/* If necessary, make a copy of the WCS calibration, since we are
+   about to alter it. */
+wcsinfo2 = astCopy( wcsinfo1 );
+
+/* Re-map the base Frame so that it refers to the new data grid
+   instead of the old one. */
+astRemapFrame( wcsinfo2, AST__BASE, newmap );
+\end{terminalv}
+\end{small}
+
+This will produce a pointer, ``wcsinfo2'', to a new FrameSet in which
+all the coordinate systems associated with your original image are
+modified so that they are correctly registered with the new image
+instead.
+
+For more information about re-mapping the Frames within a FrameSet,
+see \secref{ss:remapframe}. Also see \secref{ss:wcsprocessingexample}
+for a similar example to the above, applicable to the case of reducing
+the size of an image by binning.
+
+\subsection{\label{ss:howtowritewcs}\ldots Write a Modified WCS Calibration to a Dataset}
+
+If you have modified the WCS calibration associated with a dataset,
+such as in the example above (\secref{ss:howtomodifywcs}), then you
+will need to write the modified version out along with any new data.
+
+In the same way as when reading a WCS calibration
+(\secref{ss:howtoreadwcs}), how you do this will depend on your data
+system, but we will assume that you wish to generate a set of FITS
+header cards that can be stored with the data. You should usually make
+preparations for doing this when you first read the WCS calibration
+from your input dataset by modifying the example given in
+\secref{ss:howtoreadwcs} as follows:
+
+\begin{small}
+\begin{terminalv}
+AstFitsChan *fitschan1;
+AstFrameSet *wcsinfo1;
+const char *encode;
+
+...
+
+/* Create an input FitsChan and fill it with FITS header cards. Note,
+   if you have all the header cards in a single string, use astPutCards in
+   place of astPutFits. */
+fitschan1 = astFitsChan( NULL, NULL, "" );
+for ( icard = 0; icard < ncard; icard++ ) astPutFits( fitschan1, cards[ icard ], 0 );
+
+/* Note which encoding has been used for the WCS information. */
+encode = astGetC( fitschan1, "Encoding" );
+
+/* Rewind the input FitsChan and read the WCS information from it. */
+astClear( fitschan1, "Card" );
+wcsinfo1 = astRead( fitschan1 );
+\end{terminalv}
+\end{small}
+
+Note how we have added an enquiry to determine how the WCS information
+is encoded in the input FITS cards, storing a pointer to the resulting
+string in the ``encode'' variable. This must be done \textbf{before}
+actually reading the WCS calibration.
+
+\emph{(\textbf{N.B.}\ If you will be making extensive use of astGetC in
+your program, then you should allocate a buffer and make a copy of
+this string, because the pointer returned by astGetC will only remain
+valid for 50 invocations of the function, and you will need to use the
+\htmlref{Encoding}{Encoding} value again later on.)}
+
+Once you have produced a modified WCS calibration for the output
+dataset (\emph{e.g.}\ \secref{ss:howtomodifywcs}), in the form of a
+\htmlref{FrameSet}{FrameSet} identified by the pointer ``wcsinfo2'', you can produce a new
+\htmlref{FitsChan}{FitsChan} containing the output FITS header cards as follows:
+
+\small
+\begin{terminalv}
+AstFitsChan *fitschan2;
+AstFrameSet *wcsinfo2;
+
+...
+
+/* Make a copy of the input FitsChan, AFTER the WCS information has
+   been read from it. This will propagate all the input FITS header
+   cards, apart from those describing the input WCS calibration. */
+fitschan2 = astCopy( fitschan1 );
+
+/* If necessary, make modifications to the cards in "fitschan2"
+   (e.g. you might need to change NAXIS1, NAXIS2, etc., to account for
+   a change in image size). You probably only need to do this if your
+   data system does not provide these facilities itself. */
+<details not shown - see below>
+
+/* Alternatively, if your data system handles the propagation of FITS
+   header cards to the output dataset for you, then simply create an
+   empty FitsChan to contain the output WCS information alone.
+fitschan2 = astFitsChan( NULL, NULL, "" );
+*/
+
+/* Rewind the new FitsChan (if necessary) and attempt to write the
+   output WCS information to it using the same encoding method as the
+   input dataset. */
+astSet( fitschan2, "Card=1, Encoding=%s", encode );
+if ( !astWrite( fitschan2, wcsinfo2 ) ) {
+
+/* If this didn't work (the WCS FrameSet has become too complex), then
+   use the native AST encoding instead. */
+   astSet( fitschan2, "Encoding=NATIVE" );
+   (void) astWrite( fitschan2, wcsinfo2 );
+}
+\end{terminalv}
+\normalsize
+
+For details of how to modify the contents of the output FitsChan in
+other ways, such as by adding, over-writing or deleting header cards,
+see \secref{ss:addressingfitscards}, \secref{ss:addingmulticards}, \secref{ss:addingfitscards} and
+\secref{ss:findingandchangingfits}.
+
+Once you have assembled the output FITS cards, you may retrieve them
+from the FitsChan that contains them as follows:
+
+\small
+\begin{terminalv}
+#include <stdio.h>
+char card[ 81 ];
+
+...
+
+astClear( fitschan2, "Card" );
+while ( astFindFits( fitschan2, "%f", card, 1 ) ) (void) printf( "%s\n", card );
+\end{terminalv}
+\normalsize
+
+Here, we have simply written each card to the standard output stream,
+but you would obviously replace this with a function invocation to
+store the cards in your output dataset.
+
+For data systems that do not use FITS header cards, a different
+approach may be needed, possibly involving use of a \htmlref{Channel}{Channel} or \htmlref{XmlChan}{XmlChan}
+(\secref{ss:channels}) rather than a FitsChan.  In the case of the
+Starlink NDF data format, for example, all of the above may be
+replaced by a single call to the function
+\xref{ndfPtwcs}{sun33}{ndfPtwcs}---see \xref{SUN/33}{sun33}{}. The
+whole process can probably be encapsulated in a similar way for most
+data systems, whether they use FITS header cards or not.
+
+For an overview of how to propagate WCS information through data
+processing steps, see \secref{ss:propagatingwcsinformation}.  For more
+information about writing WCS information to FitsChans, see
+\secref{ss:writingnativefits} and \secref{ss:writingforeignfits}.  For
+information about the options for encoding WCS information in FITS
+header cards, see \secref{ss:nativeencoding},
+\secref{ss:foreignencodings}, and the description of the Encoding
+attribute in \appref{ss:attributedescriptions}.  For a complete
+understanding of FitsChans and their use with FITS header cards, you
+should read \secref{ss:nativefits} and \secref{ss:foreignfits}.
+
+\subsection{\label{ss:howtoplotgrid}\ldots Display a Graphical Coordinate Grid}
+
+   A common requirement when displaying image data is to plot an
+   associated coordinate grid (\emph{e.g.}\ Figure~\ref{fig:overgrid})
+   over the displayed image.
+   \begin{figure}
+   \begin{center}
+   \includegraphics[width=0.7\textwidth]{sun211_figures/overgrid_bw}
+   \caption[An example of a displayed image with a coordinate grid
+   plotted over it.]{An example of a displayed image with a coordinate grid
+   plotted over it.}
+   \label{fig:overgrid}
+   \end{center}
+   \end{figure}
+
+The use of AST in such circumstances is independent of the underlying
+graphics system, so starting up the graphics system, setting up a
+coordinate system, displaying the image, and closing down afterwards
+can all be done using the graphics functions you would normally use.
+
+However, displaying an image at a precise location can be a little
+fiddly with some graphics systems, and obviously the grid drawn by AST
+will not be accurately registered with the image unless this is done
+correctly. In the following template, we therefore illustrate both
+steps, basing the image display on the C interface to the PGPLOT
+graphics package.\footnote{An interface is provided with AST that
+allows it to use PGPLOT (\xref{SUN/15}{sun15}{}) for its graphics,
+although interfaces to other graphics systems may also be written.}
+Plotting a coordinate grid with AST then becomes a relatively minor
+part of what is almost a complete graphics program.
+
+Once again, we assume that a pointer, ``wcsinfo'', to a suitable
+\htmlref{FrameSet}{FrameSet} associated with the image has already been obtained
+(\secref{ss:howtoreadwcs}).
+
+\small
+\begin{terminalv}
+#include "cpgplot.h"
+AstPlot *plot;
+const float *data;
+float hi, lo, scale, x1, x2, xleft, xright, xscale;
+float y1, y2, ybottom, yscale, ytop;
+int nx, ny;
+
+...
+
+/* Access the image data, which we assume has dimension sizes "nx" and
+   "ny", and will be accessed via the "data" pointer.  Also derive
+   limits for scaling it, which we assign to the variables "hi" and
+   "lo". */
+<this stage depends on your data system, so is not shown>
+
+/* Open PGPLOT using the device given by environment variable
+   PGPLOT_DEV and check for success. */
+if( cpgbeg( 0, " ", 1, 1 ) == 1 ) {
+
+/* Clear the screen and ensure equal scales on both axes. */
+   cpgpage();
+   cpgwnad( 0.0f, 1.0f, 0.0f, 1.0f );
+
+/* Obtain the extent of the plotting area (not strictly necessary for
+   PGPLOT, but possibly for other graphics systems). From this, derive
+   the display scale in graphics units per pixel so that the image
+   will fit within the display area. */
+   cpgqwin( &x1, &x2, &y1, &y2 );
+   xscale = ( x2 - x1 ) / nx;
+   yscale = ( y2 - y1 ) / ny;
+   scale = ( xscale < yscale ) ? xscale : yscale;
+
+/* Calculate the extent of the area in graphics units that the image
+   will occupy, so as to centre it within the display area. */
+   xleft   = 0.5f * ( x1 + x2 - nx * scale );
+   xright  = 0.5f * ( x1 + x2 + nx * scale );
+   ybottom = 0.5f * ( y1 + y2 - ny * scale );
+   ytop    = 0.5f * ( y1 + y2 + ny * scale );
+
+/* Set up a PGPLOT coordinate transformation matrix and display the
+   image data as a grey scale map (these details are specific to
+   PGPLOT). */
+   {
+      float tr[] = { xleft - 0.5f * scale, scale, 0.0f,
+                     ybottom - 0.5f * scale, 0.0f, scale };
+      cpggray( data, nx, ny, 1, nx, 1, ny, hi, lo, tr );
+   }
+
+/* BEGINNING OF AST BIT */
+/* ==================== */
+/* Store the locations of the bottom left and top right corners of the
+   region used to display the image, in graphics coordinates. */
+   {
+      float gbox[] = { xleft, ybottom, xright, ytop };
+
+/* Similarly, store the locations of the image's bottom left and top
+   right corners, in pixel coordinates -- with the first pixel centred
+   at (1,1). */
+      double pbox[] = { 0.5, 0.5, nx + 0.5, ny + 0.5 };
+
+/* Create a Plot, based on the FrameSet associated with the
+   image. This attaches the Plot to the graphics surface so that it
+   matches the displayed image. Specify that a complete set of grid
+   lines should be drawn (rather than just coordinate axes). */
+      plot = astPlot( wcsinfo, gbox, pbox, "Grid=1" );
+   }
+
+/* Optionally, we can now set other Plot attributes to control the
+   appearance of the grid. The values assigned here use the
+   colour/font indices defined by the underlying graphics system. */
+   astSet( plot, "Colour(grid)=2, Font(textlab)=3" );
+
+/* Use the Plot to draw the coordinate grid. */
+   astGrid( plot );
+
+   <maybe some more AST graphics here>
+
+/* Annul the Plot when finished (or use the astBegin/astEnd technique
+   shown earlier). */
+   plot = astAnnul( plot );
+
+/* END OF AST BIT */
+/* ============== */
+
+/* Close down the graphics system. */
+   cpgend();
+}
+\end{terminalv}
+\normalsize
+
+Note that once you have set up a \htmlref{Plot}{Plot} which is aligned with a
+displayed image, you may also use it to generate further graphical
+output of your own, specified in the image's world coordinate system
+(such as markers to represent astronomical objects, annotation,
+\emph{etc.}). There is also a range of Plot attributes which gives
+control over most aspects of the output's appearance.  For details of
+the facilities available, see \secref{ss:plots} and the description of
+the Plot class in \appref{ss:classdescriptions}.
+
+For details of how to build a graphics program which uses PGPLOT, see
+\secref{ss:howtobuild} and the description of the \htmlref{ast\_link}{ast\_link} command in
+\appref{ss:commanddescriptions}.
+
+\subsection{\label{ss:howtoswitchgrid}\ldots Switch to Plot a Different Celestial Coordinate Grid}
+
+Once you have set up a \htmlref{Plot}{Plot} to draw a coordinate grid
+(\secref{ss:howtoplotgrid}), it is a simple matter to change things so
+that the grid represents a different celestial coordinate system. For
+example, after creating the Plot with \htmlref{astPlot}{astPlot}, you could use:
+
+\small
+\begin{terminalv}
+astSet( plot, "System=Galactic" );
+\end{terminalv}
+\normalsize
+or:
+\small
+\begin{terminalv}
+astSet( plot, "System=FK5, Equinox=J2010" );
+\end{terminalv}
+\normalsize
+
+and any axes and/or grid drawn subsequently would represent the new
+celestial coordinate system you specified.  Note, however, that this
+will only work if the original grid represented celestial coordinates
+of some kind (see \secref{ss:howtotestforcelestial} for how to
+determine if this is the case\footnote{Note that the methods applied
+to a \htmlref{FrameSet}{FrameSet} may be used equally well with a Plot.}). If it did not,
+you will get an error message.
+
+For more information about the celestial coordinate systems available,
+see the descriptions of the \htmlref{System}{System}, \htmlref{Equinox}{Equinox} and \htmlref{Epoch}{Epoch} attributes in
+\appref{ss:attributedescriptions}.
+
+\subsection{\ldots Give a User Control Over the Appearance of a Plot}
+
+The idea of using a \htmlref{Plot}{Plot}'s attributes to control the appearance of the
+graphical output it produces (\secref{ss:howtoplotgrid} and
+\secref{ss:howtoswitchgrid}) can easily be extended to allow the user
+of a program complete control over such matters.
+
+For instance, if the file ``plot.config'' contains a series of
+plotting options in the form of Plot attribute assignments (see below
+for an example), then we could create a Plot and implement these
+assignments before producing the graphical output as follows:
+
+\small
+\begin{terminalv}
+#include <stdio.h>
+#define MAXCHARS 120
+FILE *stream;
+char line[ MAXCHARS + 2 ];
+int base;
+
+...
+
+/* Create a Plot and define the default appearance of the graphical
+   output it will produce. */
+plot = astPlot( wcsinfo, gbox, pbox,
+                "Grid=1, Colour(grid)=2, Font(textlab)=3" );
+
+/* Obtain the value of any Plot attributes we want to preserve. */
+base = astGetI( plot, "Base" );
+
+/* Open the plot configuration file, if it exists. Read each line of
+   text and use it to set new Plot attribute values. Close the file
+   when done. */
+if ( stream = fopen( "plot.config", "r" ) ) {
+   while ( fgets( line, MAXCHARS + 2, stream ) ) astSet( plot, "%s", line );
+   close( stream );
+}
+
+/* Restore any attribute values we are preserving. */
+astSetI( plot, "Base", base );
+
+/* Produce the graphical output (e.g.). */
+astGrid( plot );
+\end{terminalv}
+\normalsize
+
+Notice that we take care that the Plot's \htmlref{Base}{Base} attribute is preserved
+so that the user cannot change it. This is because graphical output
+will not be produced successfully if the base \htmlref{Frame}{Frame} does not describe
+the plotting surface to which we attached the Plot when we created it.
+
+The arrangement shown above allows the contents of the ``plot.config''
+file to control most aspects of the graphical output produced
+(including the coordinate system used; the colour, line style,
+thickness and font used for each component; the positioning of axes
+and tick marks; the precision, format and positioning of labels;
+\emph{etc.}) \emph{via} assignments of the form:
+
+\small
+\begin{terminalv}
+System=Galactic, Equinox = 2001
+Border = 1, Colour( border ) = 1
+Colour( grid ) = 2
+DrawAxes = 1
+Colour( axes ) = 3
+Digits = 8
+Labelling = Interior
+\end{terminalv}
+\normalsize
+
+For a more sophisticated interface, you could obviously perform
+pre-processing on this input---for example, to translate words like
+``red'', ``green'' and ``blue'' into colour indices, to permit
+comments and blank lines, \emph{etc.}
+
+For a full list of the attributes that may be used to control the
+appearance of graphical output, see the description of the Plot class
+in \appref{ss:classdescriptions}. For a complete description of each
+individual attribute (\emph{e.g.}\ those above), see the attribute's
+entry in \appref{ss:attributedescriptions}.
+
+\cleardoublepage
+\section{\label{ss:primer}An AST Object Primer}
+
+The AST library deals throughout with entities called Objects and a
+basic understanding of how to handle these is needed before you can
+use the library effectively.  If you are already familiar with an
+object-oriented language, such as C$++$, few of the concepts should
+seem new to you.  Be aware, however, that AST is designed to be used
+\emph{via} fairly conventional C and Fortran interfaces, so some
+things have to be done a little differently.
+
+If you are not already familiar with object-oriented programming, then
+don't worry---we will not emphasise this aspect more than is necessary
+and will not assume any background knowledge.  Instead, this section
+concentrates on presenting all the fundamental information you will
+need, explaining how AST Objects behave and how to manipulate them
+from conventional C programs.
+
+If you like to read documents from cover to cover, then you can
+consider this section as an introduction to the programming techniques
+used in the rest of the document. Otherwise, you may prefer to skim
+through it on a first reading and return to it later as reference
+material.
+
+\subsection{AST Objects}
+
+An AST \htmlref{Object}{Object} is an entity which is used to store information and
+Objects come in various kinds, called \emph{classes}, according to the
+sort of information they hold. Throughout this section, we will make
+use of a simple Object belonging to the ``\htmlref{ZoomMap}{ZoomMap}'' class to
+illustrate many of the basic concepts.
+
+A ZoomMap is an Object that contains a recipe for converting
+coordinates between two hypothetical coordinate systems.  It does this
+by multiplying all the coordinate values by a constant called the
+\emph{\htmlref{Zoom}{Zoom} factor}.  A ZoomMap is a very simple Object which exists
+mainly for use in examples. It allows us to illustrate the ways in
+which Objects are manipulated and to introduce the concept of a
+\htmlref{Mapping}{Mapping}---a recipe for converting coordinates---which is fundamental
+to the way the AST library works.
+
+\subsection{\label{ss:objectcreation}Object Creation and Pointers}
+
+Let us first consider how to create a \htmlref{ZoomMap}{ZoomMap}. This is done very
+simply as follows:
+
+\small
+\begin{terminalv}
+#include "ast.h"
+AstZoomMap *zoommap;
+
+...
+
+zoommap = astZoomMap( 2, 5.0, "" )
+\end{terminalv}
+\normalsize
+
+The first step is to include the header file ``ast.h'' which declares
+the interface to the AST library.  We then declare a pointer of type
+AstZoomMap$*$ to receive the result and invoke the function \htmlref{astZoomMap}{astZoomMap}
+to create the ZoomMap. The pattern is the same for all other classes
+of AST \htmlref{Object}{Object}---you simply prefix ``ast'' to the class name to obtain
+the function that creates the Object and prefix ``Ast'' to obtain the
+type of the returned pointer.
+
+These functions are called \emph{constructor functions}, or simply
+\emph{constructors} (you can find an individual description of all AST
+functions in \appref{ss:functiondescriptions}) and the arguments
+passed to the constructor are used to initialise the new Object. In
+this case, we specify 2 as the number of coordinates (\emph{i.e.}\ we
+are going to work in a 2-dimensional
+space) and 5.0 as the \htmlref{Zoom}{Zoom} factor to be applied. Note that this is a C
+double value. We will return to the final argument, an empty string,
+shortly (\secref{ss:attributeinitialisation}).
+
+The value returned by the constructor is termed an \emph{Object pointer}
+or, in this case, a \emph{ZoomMap pointer} and is used to refer to the
+Object.  You perform all subsequent operations on the Object by
+passing this pointer to other AST functions.
+
+\subsection{\label{ss:objecthierarchy}The Object Hierarchy}
+
+Now that we have created our first \htmlref{ZoomMap}{ZoomMap}, let us examine how it
+relates to other kinds of \htmlref{Object}{Object} before investigating what we can do
+with it.
+
+We have so far indicated that a ZoomMap is a kind of Object and have
+also mentioned that it is a kind of \htmlref{Mapping}{Mapping} as well. These statements
+can be represented very simply using the following hierarchy:
+
+\small
+\begin{terminalv}
+Object
+   Mapping
+      ZoomMap
+\end{terminalv}
+\normalsize
+
+which is a way of stating that a ZoomMap is a special class of
+Mapping, while a Mapping, in turn, is a special class of Object.  This
+is exactly like saying that an Oak is a special form of Tree, while a
+Tree, in turn, is a special form of Plant. This may seem almost
+trivial, but before you turn to read something less dull, be assured
+that it is a very important idea to keep in mind in what follows.
+
+If we look at some of the other Objects used by the AST library, we
+can see how these are all related in a similar way (don't worry about
+what they do at this stage):
+\label{ss:mappinghierarchy}
+
+\small
+\begin{terminalv}
+Object
+   Mapping
+      Frame
+         FrameSet
+            Plot
+      UnitMap
+      ZoomMap
+   Channel
+      FitsChan
+      XmlChan
+\end{terminalv}
+\normalsize
+
+Notice that there are several different types of Mapping available
+(\emph{i.e.}\ there are classes of Object indented beneath the
+``Mapping'' heading) and, in addition, other types of Object which are
+not Mappings---Channels for instance (which are at the same
+hierarchical level as Mappings).
+
+The most specialised Object we have shown here is the \htmlref{Plot}{Plot} (which we
+will not discuss in detail until \secref{ss:plots}). As you can see, a
+Plot is a \htmlref{FrameSet}{FrameSet}\ldots\ and a \htmlref{Frame}{Frame}\ldots\ and a Mapping\ldots\ and,
+like everything else, ultimately an Object.
+
+What this means is that you can use a Plot not only for its own
+specialised behaviour, but also whenever any of these other
+less-specialised classes of Object is called for. The general rule is
+that an Object of a particular class may substitute for any of the
+classes appearing above it in this hierarchy. The Object is then said
+to \emph{inherit} the behaviour of these higher classes. We can
+therefore use our ZoomMap whenever a ZoomMap, a Mapping or an Object
+is called for.
+
+Sometimes, this can lead to some spectacular short-cuts by avoiding
+the need to break large Objects down in order to access their
+components. With some practice and a little lateral thinking you
+should soon be able to spot opportunities for this.
+
+You can find the full \emph{class hierarchy}, as this is called, for
+the AST library in \appref{ss:classhierarchy} and you may need to
+refer to it occasionally until you are familiar with the classes you
+need to use.
+
+\subsection{\label{ss:displayingobjects}Displaying Objects}
+
+Let us now return to the \htmlref{ZoomMap}{ZoomMap} that we created earlier
+(\secref{ss:objectcreation}) and examine what it's made of.
+There is a function for doing this, called \htmlref{astShow}{astShow}, which is provided
+mainly for looking at Objects while you are debugging programs.
+
+If you consult the description of astShow in
+\appref{ss:functiondescriptions}, you will find that it takes a
+pointer to an \htmlref{Object}{Object} (of type AstObject$*$) as its argument. Although
+we have only a ZoomMap pointer available, this is not a problem. If
+you refer to the brief class hierarchy described above
+(\secref{ss:mappinghierarchy}), you will see that a ZoomMap is an
+Object, albeit a specialised one, so it inherits the properties of all
+Objects and can be substituted wherever an Object is required.  We can
+therefore pass our ZoomMap pointer directly to astShow, as follows:
+
+\small
+\begin{terminalv}
+astShow( zoommap );
+\end{terminalv}
+\normalsize
+
+The output from this will appear on the standard output stream and
+should look like the following:
+
+\small
+\begin{terminalv}
+Begin ZoomMap
+   Nin = 2
+IsA Mapping
+   Zoom = 5
+End ZoomMap
+\end{terminalv}
+\normalsize
+
+Here, the ``Begin'' and ``End'' lines mark the beginning and end of
+the ZoomMap, while the values 2 and 5 are simply the values we
+supplied to initialise it (\secref{ss:objectcreation}). These have
+been given simple names to make them easy to refer to.
+
+The line in the middle which says ``IsA~\htmlref{Mapping}{Mapping}'' is a dividing line
+between the two values. It indicates that the ``\htmlref{Nin}{Nin}'' value is a
+property shared by all Mappings, so the ZoomMap has inherited this
+from its \emph{parent class} (Mapping). The ``\htmlref{Zoom}{Zoom}'' value, however,
+is specific to a ZoomMap and isn't shared by other kinds of Mappings.
+
+\subsection{\label{ss:gettingattributes}Getting Attribute Values}
+
+We saw above (\secref{ss:displayingobjects}) how to display the
+internal values of an \htmlref{Object}{Object}, but what about accessing these values
+from a program?  Not all internal Object values are accessible in this
+way, but many are. Those that are, are called \emph{attributes}. A
+description of all the attributes used by the AST library can be found
+in \appref{ss:attributedescriptions}.
+
+Attributes come in several data types (character string, integer,
+boolean and floating point) and there is a standard way of obtaining
+their values. As an example, consider obtaining the value of the \htmlref{Nin}{Nin}
+attribute for the \htmlref{ZoomMap}{ZoomMap} created earlier. This could be done as
+follows:
+
+\small
+\begin{terminalv}
+int nin;
+
+...
+
+nin = astGetI( zoommap, "Nin" );
+\end{terminalv}
+\normalsize
+
+Here, the function astGetI is used to extract the attribute value by
+giving it the ZoomMap pointer and the attribute name (attribute names
+are not case sensitive, but we have used consistent capitalisation in
+this document in order to identify them). Remember to use the
+``ast.h'' header file to include the function prototype.
+
+If we had wanted the value of the \htmlref{Zoom}{Zoom} attribute, we would probably
+have used astGetD instead, this being a double version of the same
+function, for example:
+
+\small
+\begin{terminalv}
+double zoom;
+
+...
+
+zoom = astGetD( zoommap, "Zoom" );
+\end{terminalv}
+\normalsize
+
+However, we could equally well have read the Nin value as double, or
+the Zoom value as an integer, or whatever we wanted.
+
+The data type you want returned is specified simply by replacing the
+final character of the astGetX function name with C~(character
+string), D~(double), F~(float), I~(int) or L~(long). If possible, the
+value is converted to the type you want. If not, an error message will
+result. Note that all floating point values are stored internally as
+double, and all integer values as int. Boolean values are also stored
+as integers, but only take the values 1 and 0 (for true/false).
+
+\subsection{\label{ss:settingattributes}Setting Attribute Values}
+
+Some attribute values are read-only and cannot be altered after an
+\htmlref{Object}{Object} has been created. The \htmlref{Nin}{Nin} attribute of a \htmlref{ZoomMap}{ZoomMap} (describing
+the number of coordinates) is like this. It is defined when the
+ZoomMap is created, but cannot then be altered.
+
+Other attributes, however, can be modified whenever you want. A
+ZoomMap's \htmlref{Zoom}{Zoom} attribute is like this. If we wanted to change it, this
+could be done simply as follows:
+
+\small
+\begin{terminalv}
+astSetD( zoommap, "Zoom", 99.6 );
+\end{terminalv}
+\normalsize
+
+which sets the value to 99.6. As when getting an attribute value
+(\secref{ss:gettingattributes}), you have a choice of which data type
+you will use to supply the new value. For instance, you could use an
+integer value, as in:
+
+\small
+\begin{terminalv}
+astSetI( zoommap, "Zoom", 99 );
+\end{terminalv}
+\normalsize
+
+and the necessary data conversion would occur.  You specify the data
+type you want to supply simply by replacing the final character of the
+astSetX function name with C~(character string), D~(double),
+F~(float), I~(int) or L~(long). Setting a boolean attribute to any
+non-zero integer causes it to take the value 1.
+
+An alternative way of setting attribute values for Objects is to use
+the \htmlref{astSet}{astSet} function (\emph{i.e.}\ with no final character specifying a
+data type). In this case, you supply the attribute values in a
+character string. The big advantage of this method is that you can
+assign values to several attributes at once, separating them with
+commas. This also reads more naturally in programs. For example:
+
+\small
+\begin{terminalv}
+astSet( zoommap, "Zoom=99.6, Report=1" );
+\end{terminalv}
+\normalsize
+
+would set values for both the Zoom attribute and the \htmlref{Report}{Report} attribute
+(about which more shortly---\secref{ss:transforming}). You don't really
+have to worry about data types with this method, as any character
+representation will do. Note, when using astSet, a
+literal comma may be included in an attribute value by enclosed the value in
+quotation marks:
+\small
+\begin{terminalv}
+      astSet( skyframe, 'SkyRef="12:13:32,-23:12:44"' );
+\end{terminalv}
+\normalsize
+
+Another attractive feature of astSet is that you can build the
+character string which contains the attribute settings in the same way
+as when using the C run time library ``printf'' function. This is most
+useful when the values you want to set are held in other
+variables. For example:
+
+\small
+\begin{terminalv}
+double zoom = 99.6;
+int report = 1;
+
+...
+
+astSet( zoommap, "Zoom=%g, Report=%d", zoom, report );
+\end{terminalv}
+\normalsize
+
+would replace the ``\%'' conversion specifications by the values
+supplied as additional arguments. Any number of additional arguments
+may be supplied and the formatting rules are exactly the same as for
+the C ``printf'' family of functions. This is a very flexible
+technique, but does contain one pitfall:
+
+\begin{quote}
+\textbf{Pitfall.} The default precision used by ``printf'' (and astSet)
+for floating point values is only 6 decimal digits, corresponding
+approximately to float on most machines, whereas the AST library
+stores such values internally as doubles. You should be careful to
+specify a larger precision (such as DBL\_DIG, as defined in
+$<$float.h$>$) when necessary. For example:
+
+\small
+\begin{terminalv}
+#include <float.h>
+
+...
+
+astSet( zoommap, "Zoom=%.*g", DBL_DIG, double_value );
+\end{terminalv}
+\normalsize
+\end{quote}
+
+Substituted strings may contain commas and this is a useful way of
+assigning such strings as attribute values without the comma being
+interpreted as an assignment separator, for example:
+
+\small
+\begin{terminalv}
+astSet( object, "Attribute=%s", "A string, containing a comma" );
+\end{terminalv}
+\normalsize
+
+This is equivalent to using astSetC and one of these two methods
+should always be used when assigning string attribute values which
+might potentially contain a comma (\emph{e.g.}\ strings obtained from
+an external source). However, you should not attempt to use astSet to
+substitute strings that contain newline characters, since these are
+used internally as separators between adjacent attribute assignments.
+\label{ss:attributeinitialisation}
+
+Finally, a very convenient way of setting attribute values is to do so
+at the same time as you create an Object. Every Object constructor
+function has a final character string argument which allows you to do
+this. Although you can simply supply an empty string, it is an ideal
+opportunity to initialise the Object to have just the attributes you
+want. For example, we might have created our original ZoomMap with:
+
+\small
+\begin{terminalv}
+zoommap = astZoomMap( 2, 5.0, "Report=1" );
+\end{terminalv}
+\normalsize
+
+and it would then start life with its Report attribute set to 1.
+The ``printf''-style substitution described above may also be used
+here.
+
+\subsection{\label{ss:defaultingattributes}Testing, Clearing and Defaulting Attributes}
+
+You can use the astGetX family of functions
+(\secref{ss:gettingattributes}) to get a value for any \htmlref{Object}{Object} attribute
+at any time, regardless of whether a value has previously been set for
+it. If no value has been set, the AST library will generate a suitable
+default value.
+
+Often, the default value of an attribute will not simply be trivial
+(zero or blank) but may involve considerable processing to
+calculate. Wherever possible, defaults are designed to be real-life,
+sensible values that convey information about the state of the
+Object. In particular, they may often be based on the values of other
+attributes, so their values may change in response to changes in these
+other attributes. The \htmlref{ZoomMap}{ZoomMap} class that we have studied so far is a
+little too simple to show this behaviour, but we will meet it later
+on.
+
+An attribute that returns a default value in this way is said to be
+\emph{un-set}. Conversely, once an explicit value has been assigned to
+an attribute, it becomes \emph{set} and will always return precisely
+that value, never a default.
+
+The distinction between set and un-set attributes is important and
+affects the behaviour of several key routines in the AST library. You
+can test if an attribute is set using the function \htmlref{astTest}{astTest}, which
+returns a boolean (integer) result, as in:
+
+\small
+\begin{terminalv}
+if ( astTest( zoommap, "Report" ) ) {
+   <the Report attribute is set>
+}
+\end{terminalv}
+\normalsize
+
+
+Once an attribute is set, you can return it to its un-set state using
+\htmlref{astClear}{astClear}. The effect is as if it had never been set in the first
+place. For example:
+
+\small
+\begin{terminalv}
+astClear( zoommap, "Report" );
+\end{terminalv}
+\normalsize
+
+would ensure that the default value of the \htmlref{Report}{Report} attribute is used
+subsequently.
+
+%\subsection{TBW--Handling Character Attributes}
+
+\subsection{\label{ss:transforming}Transforming Coordinates}
+
+We now have the necessary apparatus to start using our \htmlref{ZoomMap}{ZoomMap} to show
+what it is really for. Here, we will also encounter a routine that is
+a little more fussy about the type of pointer it will accept.
+
+The purpose of a ZoomMap is to multiply coordinates by a constant zoom
+factor. To witness this in action, we will first set the \htmlref{Report}{Report}
+attribute for our ZoomMap to a non-zero value:
+
+\small
+\begin{terminalv}
+astSet( zoommap, "Report=1" );
+\end{terminalv}
+\normalsize
+
+This boolean (integer) attribute, which is present in all Mappings
+(and a ZoomMap is a \htmlref{Mapping}{Mapping}), causes the automatic display of all
+coordinate values that the Mapping converts. It is not a good idea to
+leave this feature turned on in a finished program, but it can save a
+lot of work during debugging.
+
+Our next step is to set up some coordinates for the ZoomMap to work
+on, using two arrays ``xin'' and ``yin'', and two arrays to receive
+the transformed coordinates, ``xout'' and ``yout''.  Note that these
+are arrays of double, as are all coordinate data processed by the AST
+library:
+
+\small
+\begin{terminalv}
+double xin[ 10 ] = { 0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0 };
+double yin[ 10 ] = { 0.0, 2.0, 4.0, 6.0, 8.0, 10.0, 12.0, 14.0, 16.0, 18.0 };
+double xout[ 10 ];
+double yout[ 10 ];
+\end{terminalv}
+\normalsize
+
+We will now use the function \htmlref{astTran2}{astTran2} to transform the input
+coordinates. This is the most commonly-used (2-dimensional) coordinate
+transformation function. If you look at its description in
+\appref{ss:functiondescriptions}, you will see that it requires a
+pointer to a Mapping, so we cannot supply just any old \htmlref{Object}{Object} pointer,
+as we could with the functions discussed previously. If we passed it a
+pointer to an inappropriate Object, an error message would result.
+
+Fortunately, a ZoomMap is a Mapping (\appref{ss:classhierarchy}), so we
+can use it with astTran2 to transform our coordinates, as follows:
+
+\small
+\begin{terminalv}
+astTran2( zoommap, 10, xin, yin, 1, xout, yout );
+\end{terminalv}
+\normalsize
+
+Here, 10 is the number of points we want to transform and the fifth
+argument value of 1 indicates that we want to transform in the
+\emph{forward} direction (from input to output).
+
+Because our ZoomMap's Report attribute is set to 1, this will cause
+the effects of the ZoomMap on the coordinates to be displayed on the
+standard output stream:
+
+\small
+\begin{terminalv}
+(0, 0) --> (0, 0)
+(1, 2) --> (5, 10)
+(2, 4) --> (10, 20)
+(3, 6) --> (15, 30)
+(4, 8) --> (20, 40)
+(5, 10) --> (25, 50)
+(6, 12) --> (30, 60)
+(7, 14) --> (35, 70)
+(8, 16) --> (40, 80)
+(9, 18) --> (45, 90)
+\end{terminalv}
+\normalsize
+
+This shows the coordinate values of each point both before and after
+the ZoomMap is applied. You can see that each coordinate value has
+been multiplied by the factor 5 determined by the \htmlref{Zoom}{Zoom} attribute
+value. The transformed coordinates are now stored in the ``xout'' and
+``yout'' arrays.
+
+If we wanted to transform in the opposite direction, we need simply
+change the fifth argument of astTran2 from 1 to 0. We can also feed
+the output coordinates from the above back into the function:
+
+\small
+\begin{terminalv}
+astTran2( zoommap, 10, xout, yout, 0, xin, yin );
+\end{terminalv}
+\normalsize
+
+The output would then look like:
+
+\small
+\begin{terminalv}
+(0, 0) --> (0, 0)
+(5, 10) --> (1, 2)
+(10, 20) --> (2, 4)
+(15, 30) --> (3, 6)
+(20, 40) --> (4, 8)
+(25, 50) --> (5, 10)
+(30, 60) --> (6, 12)
+(35, 70) --> (7, 14)
+(40, 80) --> (8, 16)
+(45, 90) --> (9, 18)
+\end{terminalv}
+\normalsize
+
+This is termed the \emph{inverse} transformation (we have converted
+from output to input) and you can see that the original coordinates
+have been recovered by dividing by the Zoom factor.
+
+\subsection{\label{ss:annullingpointers}Managing Object Pointers}
+
+So far, we have looked at creating Objects and using them in various
+simple ways but have not yet considered how to get rid of them again.
+
+Every \htmlref{Object}{Object} consumes various computer resources (principally memory)
+and should be disposed of when it is no longer required, so as to free
+up these resources. One way of doing this (not necessarily the
+best---\secref{ss:contexts}) is to \emph{annul} each Object pointer once
+you have finished with it, using \htmlref{astAnnul}{astAnnul}. For example:
+
+\small
+\begin{terminalv}
+zoommap = astAnnul( zoommap );
+\end{terminalv}
+\normalsize
+
+This indicates that you have finished with the pointer. Since astAnnul
+always returns the null value AST\_\_NULL (as defined in ``ast.h''),
+the recommended way of using it, as here, is to assign the returned
+value to the pointer being annulled. This ensures that any attempt to
+use the pointer again will generate an error message.
+
+In general, this process may not delete the Object, because there may
+still be other pointers associated with it. However, each Object
+maintains a count of the number of pointers associated with it and
+will be deleted if you annul the final pointer. Using astAnnul
+consistently will therefore ensure that all Objects are disposed of at
+the correct time. You can determine how many pointers are associated
+with an Object by examining its (read-only) \htmlref{RefCount}{RefCount} attribute.
+
+\subsection{\label{ss:contexts}AST Pointer Contexts---Begin and End}
+
+The use of \htmlref{astAnnul}{astAnnul} (\secref{ss:annullingpointers}) is not completely
+foolproof, however. Consider the following:
+
+\small
+\begin{terminalv}
+astShow( astZoomMap( 2, 5.0, "" ) );
+\end{terminalv}
+\normalsize
+
+This creates a \htmlref{ZoomMap}{ZoomMap} and displays it on standard output
+(\secref{ss:displayingobjects}). Using function invocations as
+arguments to other functions in this way is very convenient because it
+avoids the need for intermediate pointer variables. However, the
+pointer generated by \htmlref{astZoomMap}{astZoomMap} is still active, and since we have not
+stored its value, we cannot use astAnnul to annul it. The ZoomMap will
+therefore stay around until the end of the program.
+
+A simple way to avoid this problem is to enclose all use of AST
+functions between invocations of \htmlref{astBegin}{astBegin} and \htmlref{astEnd}{astEnd}, for example:
+
+\small
+\begin{terminalv}
+astBegin;
+astShow( astZoomMap( 2, 5.0, "" ) );
+astEnd;
+\end{terminalv}
+\normalsize
+
+When the expansion of astEnd (which is a macro) executes, every \htmlref{Object}{Object}
+pointer created since the previous use of astBegin (also a macro) is
+automatically annulled and any Objects left without pointers are
+deleted. This provides a simple solution to managing Objects and their
+pointers, and allows you to create Objects very freely without needing
+to keep detailed track of each one.  Because this is so convenient, we
+implicitly assume that astBegin and astEnd are used in most of the
+examples given in this document.  Pointer management is not generally
+shown explicitly unless it is particularly relevant to the point being
+illustrated.
+
+If necessary, astBegin and astEnd may be nested, like blocks delimited
+by ``\{\ldots\}'' in C, to define a series of AST pointer
+contexts. Each use of astEnd will then annul only those Object
+pointers created since the matching use of astBegin.
+
+\subsection{Exporting, Importing and Exempting AST Pointers}
+The \htmlref{astExport}{astExport} function allows you to export particular pointers from
+one AST context (\secref{ss:contexts}) to the next outer one, as
+follows:
+
+\small
+\begin{terminalv}
+astExport( zoommap );
+\end{terminalv}
+\normalsize
+
+This would identify the pointer stored in ``zoommap'' as being required
+after the end of the current AST context. It causes any pointers
+nominated in this way to survive the next use of \htmlref{astEnd}{astEnd} (but only one
+such use) unscathed, so that they are available to the next outer
+context.  This facility is not needed often, but is invaluable when
+the purpose of your \htmlref{astBegin}{astBegin}\ldots astEnd block is basically to
+generate an \htmlref{Object}{Object} pointer. Without this, there is no way of getting
+that pointer out.
+
+
+The \htmlref{astImport}{astImport} routine can be used in a similar manner to import a
+pointer into the current context, so that it is deleted when the current
+context is closed using astEnd.
+
+Sometimes, you may also want to exempt a pointer from all the effects
+of AST contexts. You should not need to do this often, but it will
+prove essential if you ever need to write a library of functions that
+stores AST pointers as part of its own internal data. Without some
+form of exemption, the caller of your routines could cause the
+pointers you have stored to be annulled---thus corrupting your
+internal data---simply by using astEnd. To avoid this, you should use
+\htmlref{astExempt}{astExempt} on each pointer that you store, for example:
+
+\small
+\begin{terminalv}
+astExempt( zoommap );
+\end{terminalv}
+\normalsize
+
+This will prevent the pointer being affected by any subsequent use of
+astEnd. Of course, it then becomes your responsibility to annul this
+pointer (using \htmlref{astAnnul}{astAnnul}) when it is no longer required.
+
+
+\subsection{AST Objects within Multi-threaded Applications}
+
+When the AST library is built from source, the build process checks to
+see if the POSIX threads library (``\texttt{pthreads}'') is available. If so,
+appropriate \texttt{pthreads} calls are inserted into the AST source code to
+ensure that AST is thread-safe, and the AST\_\_THREADSAFE macro (defined
+in the ``ast.h'' header file) is set to ``\texttt{1}''. If the \texttt{pthreads}
+library cannot be found when AST is built, a working version of the AST
+library will still be created, but it will not be thread-safe. In this
+case the AST\_\_THREADSAFE macro will be set to ``\texttt{0}'' in ast.h. The
+rest of this section assumes that the thread-safe version of AST is being
+used.
+
+Note, some AST functions call externally specified functions (\emph{e.g.}
+the source and sink functions used by the \htmlref{Channel}{Channel} class or the graphics
+primitives functions used by the \htmlref{Plot}{Plot} class). AST does not know whether
+such functions are thread-safe or not. For this reason, invocations of these
+functions within a multi-threaded environment are serialised using a mutex
+in order to avoid two or more threads executing an external function
+simultaneously.
+
+If an application uses more than one thread, the possibility arises that
+an \htmlref{Object}{Object} created by one thread may be accessed by another thread, potentially
+simultaneously. If any of the threads modifies any aspect of the Object,
+this could lead to serious problems within the other threads. For this
+reason, some restrictions are placed on how Objects can be used in a
+multi-threaded application.
+
+\subsubsection{Locking AST Objects for Exclusive Use}
+The basic restriction is that a thread can only access Objects that it
+has previously locked for its own exclusive use. If a thread attempts to
+access any \htmlref{Object}{Object} that it has not locked, an error is reported.
+
+The \htmlref{astAnnul}{astAnnul} function is the one exception to this restriction. Pointers
+for Objects not currently locked by the calling thread can be annulled
+succesfully using astAnnul. This means that a thread that has finished
+with an Object pointer can unlock the Object by passing the pointer to
+\htmlref{astUnlock}{astUnlock} (so that other threads can use the Object via their own cloned
+pointers), and can then annul the pointer using astAnnul. Note, however,
+that an error will be reported by astAnnul if the supplied pointer has
+been locked by another thread using \htmlref{astLock}{astLock}.
+
+When an Object is created, it is initially locked by the calling thread.
+Therefore a thread does not need to lock an Object explicitly if it was
+created in the same thread.
+
+If the Object pointer is then passed to another thread, the first thread
+must unlock the Object using astUnlock and the second thread must then lock
+it using astLock.
+
+If a thread attempts to lock an Object that is already locked by another
+thread, it can choose to report an error immediately or to wait until the
+Object is available.
+
+The \htmlref{astThread}{astThread} function can be used to determine whether an Object is
+locked by the running thread, locked by another thread, or unlocked.
+
+If two or more threads need simultaneous access to an Object, a deep copy
+of the Object should be taken for each thread, using \htmlref{astCopy}{astCopy}, and then
+the copies should be unlocked and passed to the othe threads, which
+should then lock them. Note, if a thread modifies the Object, the
+modification will have no effect on the other threads, because the Object
+copies are independent of each other.
+
+\subsubsection{AST Pointer Contexts}
+
+Each thread maintains its own set of nested AST contexts, so when \htmlref{astEnd}{astEnd}
+is called, only Objects that are locked by the current thread will
+be annulled.
+
+If an \htmlref{Object}{Object} is unlocked by a thread using \htmlref{astUnlock}{astUnlock}, it is exempted from
+context handling so that subsequent invocations of astEnd will not cause it
+to be annulled (this is similar to using \htmlref{astExempt}{astExempt} on the Object). When the
+Object is subsequently locked by another thread using \htmlref{astLock}{astLock}, it will be
+imported into the context that was active when astLock was called.
+
+
+
+\subsection{\label{ss:copyingobjects}Copying Objects}
+
+The AST library makes extensive use of pointers, not only for
+accessing Objects directly, but also as a means of storing Objects
+inside other Objects (a number of classes of \htmlref{Object}{Object} are designed to
+hold collections of other Objects). Rather than copy an Object in its
+entirety, a pointer to the interior Object is simply stored in the
+enclosing Object.
+
+This means that Objects may frequently not be completely independent
+of each other because, for instance, they both contain pointers to the
+same sub-Object. In this situation, changing one Object (say assigning
+an attribute value) may affect the other one \emph{via} the common
+Object.
+
+It is difficult to describe all cases where this may happen, so you
+should always be alert to the possibility. Fortunately, there is a
+simple solution. If you require two Objects to be independent, then
+simply use \htmlref{astCopy}{astCopy} to make a copy of one, \emph{e.g.}:
+
+\small
+\begin{terminalv}
+AstZoomMap *zoommap1, *zoommap2;
+
+...
+
+zoommap2 = astCopy( zoommap1 );
+\end{terminalv}
+\normalsize
+
+This process will create a true copy of any Object and return a
+pointer to the copy. This copy will not contain any pointers to any
+component of the original Object (everything is duplicated), so you
+can then modify it safely, without fear of affecting either the
+original or any other Object.
+
+%\subsection{TBW - Inheritance}
+
+\subsection{C Pointer Types}
+
+At this point it is necessary to confess to a small amount of
+deception. So far, we have been passing \htmlref{Object}{Object} pointers to AST
+functions in order to perform operations on those Objects. In fact,
+however, what we were using were not true C functions at all, but
+merely macros which invoke a related set of hidden functions with
+essentially the same arguments. In practical terms, this makes very
+little difference to how you use the functions, as we will continue to
+call them.\footnote{About the only difference is that you cannot store
+a pointer to an AST ``function'' in a variable and use the variable's
+value to invoke that function again later.}
+
+The reason for this deception has to do with the rules for data typing
+in C. Recall that most AST functions can be used to process Objects
+from a range of different classes (\secref{ss:objecthierarchy}). In C,
+this means passing different pointer types to the same function and
+most C compilers will not permit this (at least, not without
+grumbling) because it usually indicates a programming error. In AST,
+however, it is perfectly safe if done properly. Some way is therefore
+needed of circumventing the normal compiler checking.
+
+The normal way of doing this in C is with a cast. This approach
+quickly becomes cumbersome, however, so we have adopted the strategy
+of wrapping each function in a macro which applies the appropriate
+cast for you. This means that you can pass pointers of any type to any
+AST function. For example, in passing a \htmlref{ZoomMap}{ZoomMap} pointer to \htmlref{astShow}{astShow}:
+
+\small
+\begin{terminalv}
+AstZoomMap *zoommap;
+
+...
+
+zoommap = astZoomMap( 2, 5.0, "" );
+astShow( zoommap );
+\end{terminalv}
+\normalsize
+
+we are exploiting this mechanism to avoid a compiler warning, because
+the notional type of astShow's parameter is AstObject$*$ (not
+AstZoomMap$*$).
+
+We must still guard against programming errors, however, so every
+pointer's type is checked by the enclosing macro immediately before
+any AST function executes. This allows pointer mis-matches (in the
+more liberal AST sense---\emph{i.e.}\ taking account of the class
+hierarchy, rather than the stricter C sense) to be detected at
+run-time and a suitable error message will be reported. This message
+should also identify the line where the error occurs.
+
+A similar strategy is used when pointers are returned by AST functions
+(\emph{i.e.}\ as the function result). In this case the pointer is
+cast to void$*$, although we retain the notional pointer type in the
+function's documentation
+(\emph{e.g.}\ \appref{ss:functiondescriptions}). This allows you to
+assign function results to pointer variables without using an explicit
+cast. For example, the \htmlref{astRead}{astRead} function returns an Object pointer, but
+might be used to read (say) a ZoomMap as follows:
+
+\small
+\begin{terminalv}
+AstChannel *channel;
+AstZoomMap *zoommap;
+
+...
+
+zoommap = astRead( channel );
+\end{terminalv}
+\normalsize
+
+Strictly, there is a C pointer mis-match here, but it is ignored
+because the operation makes perfect sense to AST.
+
+\textbf{There is an important exception to this, however, in that
+constructor functions always return strongly-typed pointers.}  What
+we mean by this is that the returned pointer is never implicitly cast
+to void$*$. You must therefore match pointer types when you initially
+create an Object using its constructor, such as in the following:
+
+\small
+\begin{terminalv}
+AstZoomMap *zoommap;
+
+...
+
+zoommap = astZoomMap( 2, 5.0, "" );
+\end{terminalv}
+\normalsize
+
+If the variable receiving the pointer is of a different type, an
+appropriate cast should be used, as in:
+
+\small
+\begin{terminalv}
+AstMapping *mapping;
+
+...
+
+mapping = (AstMapping *) astZoomMap( 2, 5.0, "" );
+\end{terminalv}
+\normalsize
+
+This is an encouragement for you to declare your pointer types
+consistently, since this is of great benefit to anyone trying to
+understand your software.
+
+Finally, we should also make one more small confession---AST pointers
+are not really pointers at all.  Although they behave like pointers,
+the actual ``values'' stored are not the addresses of C data
+structures. This means that you cannot de-reference an AST pointer to
+examine the data within (although you can use astShow
+instead---\secref{ss:displayingobjects}). This is necessary so that AST
+pointers can be made unique even although several of them might
+reference the same Object.
+
+\subsection{\label{ss:errordetection}Error Detection}
+
+If an error occurs in an AST function (for example, if you supply an
+invalid argument, such as a pointer to the wrong class of \htmlref{Object}{Object}), an
+error message will be written to the standard error stream and the
+function will immediately return.
+
+To indicate than an error has occurred, an AST \emph{error status}
+value is used. This integer value is stored internally by AST and is
+initially clear (\emph{i.e.}\ set to zero\footnote{We will assume
+throughout that the ``OK'' value is zero, as it currently is. However,
+a different value could, in principle, be used if the environment in
+which AST is running requires it. This is why a simple interface is
+provided to isolate you from the actual value of the error status.}
+to indicate no error). If an error occurs, it becomes set to a
+different \emph{error value}, which allows you to detect the error, as
+follows:
+
+\small
+\begin{terminalv}
+zoommap = astZoomMap( 2, 5.0, "Title=My ZoomMap" );
+if ( !astOK ) {
+   <an error has occurred>
+}
+\end{terminalv}
+\normalsize
+
+The macro \htmlref{astOK}{astOK} is used to test whether the AST error status is still
+OK. In this example it would not be, because we have attempted to set
+a value for the \htmlref{Title}{Title} attribute of a \htmlref{ZoomMap}{ZoomMap} and a ZoomMap does not
+have such an attribute.  The actual value of the AST error status can
+be obtained using the \htmlref{astStatus}{astStatus} macro, as follows:
+
+\small
+\begin{terminalv}
+int status;
+
+...
+
+
+status = astStatus;
+\end{terminalv}
+\normalsize
+
+A consequence of the AST error status being set is that almost all AST
+functions will subsequently cease to function and will instead simply
+return without action.  This means that you do not need to use astOK
+to check for errors very frequently. Instead, you can usually simply
+invoke a succession of AST functions. If an error occurs in any of
+them, the following ones will do nothing and you can check for the
+error at the end, for example:
+
+\small
+\begin{terminalv}
+astFunctionA( ... );
+astFunctionB( ... );
+astFunctionC( ... );
+if ( !astOK ) {
+   <an error has occurred>
+}
+\end{terminalv}
+\normalsize
+
+There are, however, a few functions which do not adhere to this
+general rule and which will attempt to execute if the AST error status
+is set. These functions, such as \htmlref{astAnnul}{astAnnul}, are concerned with cleaning
+up and recovering resources. For example, in the following:
+
+\small
+\begin{terminalv}
+zoommap = astZoomMap( 2, 5.0, "" );
+
+astFunctionX( ... );
+astFunctionY( ... );
+astFunctionZ( ... );
+
+zoommap = astAnnul( zoommap );
+if ( !astOK ) {
+   <an error has occurred>
+}
+\end{terminalv}
+\normalsize
+
+astAnnul will execute normally in order to recover the resources
+associated with the ZoomMap that was created earlier, regardless of
+whether an error has occurred in any of the intermediate functions.
+Functions which behave in this way are noted in the relevant
+descriptions in \appref{ss:functiondescriptions}.
+
+If a serious error occurs, you will probably want to abort your
+program, but sometimes you may want to recover and carry on. Because
+very few AST functions will execute once the AST error status has been
+set, you must first clear this status by using the \htmlref{astClearStatus}{astClearStatus}
+macro, as follows:
+
+\small
+\begin{terminalv}
+astClearStatus;
+\end{terminalv}
+\normalsize
+
+This will restore the AST error status to its OK value, so that AST
+functions execute normally again.
+
+Occasionally, you may also need to set the AST error status to an
+explicit error value (see \secref{ss:channelsink} for an
+example). This is done using \htmlref{astSetStatus}{astSetStatus} and can be used to
+communicate to AST that an error has occurred in some other item of
+software, for example:
+
+\small
+\begin{terminalv}
+int new_status;
+
+...
+
+astSetStatus( new_status );
+\end{terminalv}
+\normalsize
+
+The effect is that most AST routines will subsequently return without
+action, just as if an error had occurred within the AST library
+itself.
+
+\subsection{Sharing the Error Status}
+
+In some software, it is usual to maintain a single integer error
+status variable which is accessed by each function as it executes. If
+an error occurs, this status variable is set and other functions can
+detect this and take appropriate action.
+
+If you use AST in such a situation, it can be awkward to have a
+separate internal error status used by AST functions alone. To remedy
+this, AST is capable of sharing the error status variable used by any
+other software, so long as they use the same conventions
+(\emph{i.e.}\ a C int with the same ``OK'' value). To enable this
+facility, you should pass the address of your status variable to
+\htmlref{astWatch}{astWatch}, as follows:
+
+\small
+\begin{terminalv}
+int my_status;
+int *old_address;
+
+...
+
+old_address = astWatch( &my_status );
+\end{terminalv}
+\normalsize
+
+Henceforth, instead of using its own internal error status variable,
+AST will use the one you supply, so that it can detect errors flagged
+by other parts of your software. The address of the original error
+status variable is returned by astWatch, so you can restore the
+original behaviour later if necessary.
+
+Note that this facility is not available \emph{via} the Fortran
+interface to the AST library.
+
+\cleardoublepage
+\section{\label{ss:mappings}Inter-Relating Coordinate Systems (Mappings)}
+
+In \secref{ss:primer} we used the \htmlref{ZoomMap}{ZoomMap} as an example of a
+\htmlref{Mapping}{Mapping}. We saw how it could be used to transform coordinates from its
+input to its output and back again (\secref{ss:transforming}). We also
+saw how its behaviour could be controlled by setting various
+attributes, such as the \htmlref{Zoom}{Zoom} factor and the \htmlref{Report}{Report} attribute that made
+it display coordinate values as it transformed them.
+
+In this section, we will look at Mappings a bit more thoroughly and
+explore the behaviour which is common to all the Mappings provided by
+AST.  This is good background for what follows, because many of the
+Objects we discuss later will also turn out to be Mappings in various
+disguises.
+
+\subsection{\label{ss:mappingclass}The Mapping Class}
+
+Before we start, it is worth taking a quick look at the \htmlref{Mapping}{Mapping} class
+as a whole and some of the sub-classes it contains:
+
+\begin{terminalv}
+   Mapping
+      CmpMap
+      DssMap
+      GrismMap
+      IntraMap
+      LutMap
+      MathMap
+      MatrixMap
+      PermMap
+      PolyMap
+         ChebyMap
+      SlaMap
+      SpecMap
+      TimeMap
+      UnitMap
+      WcsMap
+      ZoomMap
+
+      Frame
+         <various types of Frame>
+\end{terminalv}
+
+The \htmlref{Frame}{Frame} sub-class has been separated out here because it is covered
+in detail in \secref{ss:frames}. We start by looking at the parent
+class, Mapping.
+
+AST does not provide a function to create a basic Mapping
+(\emph{i.e.}\ the astMapping constructor does not exist). This is
+because the Mapping class itself is ``virtual'' and basic Mappings are
+of no use in themselves. The Mapping class serves simply to contain
+the various specialised Mappings that exist.
+However, it provides more than just a convenient heading for them
+because it bestows all classes of Mapping with common properties
+(\emph{e.g.}\ attributes) and behaviour.  By examining the Mapping
+class, we are therefore examining the things that all other Mappings
+have in common.
+
+\subsection{The Mapping Model}
+
+The concept of a \htmlref{Mapping}{Mapping} was illustrated in Figure~\ref{fig:mapping}.
+It is a black box which you can supply with a set of coordinate values
+in return for a set of transformed coordinates. The two sets are
+termed \emph{input} and \emph{output} coordinates. You can also go
+back the other way and transform output coordinates back into input
+coordinates, as we saw in \secref{ss:transforming}.
+
+\subsection{Changing Attributes of a Mapping}
+
+Many classes of \htmlref{Mapping}{Mapping} have attributes that provide values for parameter
+used within the transformation. For instance, the \htmlref{ZoomMap}{ZoomMap} class has an
+attribute called ``\htmlref{Zoom}{Zoom}'' that gives the scalar value by which each
+coordinate is to be multiplied. These attribute values should be set when
+the Mapping is created and should not be changed afterwards. Indeed, the
+AST library will report an error if an attempt is made to change the
+value of a Mapping attribute. This is because, once created, Mappings are
+often later included within other objects such as FrameSets and CmpMaps.
+This means that in general there could be many active references to a single
+Mapping object within a program. Changing an attribute of the Mapping
+via one particular reference (i.e pointer) would cause all the other
+references to change too, with often undesirable or unpredictable
+consequences. To avoid this, Mappings are considered \emph{immutable} in
+most situations. The one exception is if the Mapping has not yet been
+cloned or included in another \htmlref{Object}{Object} (\emph{i.e.} it has a reference
+couint of one) - changing the attributes of such a Mapping is allowed,
+and will not generate an error.
+
+Note, the \htmlref{Invert}{Invert} attribute of a Mapping is not subject to this rule and
+can be changed at any time.
+
+\subsection{Input and Output Coordinate Numbers}
+
+In general, the number of coordinates you feed into a \htmlref{Mapping}{Mapping} to
+represent a single point need not be the same as the number that comes
+out. Often these numbers will be the same, and often they will both
+equal 2 (because 2-dimensional coordinate systems are common), but
+this needn't necessarily be the case.
+
+The number of coordinates required to specify an input point is
+represented by the integer attribute \htmlref{Nin}{Nin} and the number required to
+specify an output point is represented by \htmlref{Nout}{Nout}. These are read-only
+attributes common to all Mappings. Generally, their values are fixed
+when a Mapping is created.
+
+In \secref{ss:objectcreation}, we saw how the Nin attribute for a
+\htmlref{ZoomMap}{ZoomMap} was initialised by the call to the constructor function
+\htmlref{astZoomMap}{astZoomMap} which created it. In this case, the Nout attribute was not
+needed and it implicitly took the same value as Nin, but we could
+have enquired about its value had we wanted, as follows:
+
+\small
+\begin{terminalv}
+#include "ast.h"
+AstZoomMap *zoommap;
+int nout;
+
+...
+
+nout = astGetI( zoommap, "Nout" );
+\end{terminalv}
+\normalsize
+
+\subsection{Forward and Inverse Transformations}
+
+We stated earlier that a \htmlref{Mapping}{Mapping} may be used to transform coordinates
+either from input to output, or \emph{vice versa}. These are termed
+its \emph{forward} and \emph{inverse} transformations.
+
+This statement was not quite accurate, however, because in general
+Mappings are only \textbf{potentially} capable of working in both
+directions. In practice, coordinate transformation may only be
+feasible in one direction or the other because some functions are not
+easily inverted (they may be multi-valued, for instance). Allowance
+must be made for this, so each Mapping has two read-only boolean
+(integer) attributes, \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse}, which indicate
+whether each transformation is available.
+
+A transformation is available if the corresponding attribute is
+non-zero, otherwise it is not.\footnote{Most of the Mappings provided
+by the AST library work in both directions, although the \htmlref{LutMap}{LutMap} can
+behave otherwise.} If you enquire about the value of these attributes,
+a value of 0 or 1 is returned.  Attempting to use a Mapping to apply a
+transformation which is not available will result in an error.
+
+\subsection{\label{ss:invertingmappings}Inverting Mappings}
+
+An important attribute, common to all Mappings, is the \htmlref{Invert}{Invert}
+flag. This is a boolean (integer) attribute that can be assigned a new
+value at any time. If it is non-zero, it has the effect of
+interchanging the \htmlref{Mapping}{Mapping}'s input and output coordinates and the
+Mapping is then said to be \emph{inverted}. By default, the Invert
+attribute is zero.
+
+There is no magic in this. There is no fancy arithmetic involved in
+inverting mathematical functions, for instance. The Invert flag is
+simply a switch that interchanges a Mapping's input and output
+ports. If it is non-zero, the Mapping's \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes are
+swapped, its \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse} attributes are swapped, and
+when you ask for what was once the forward transformation you get the
+inverse transformation instead (and \emph{vice versa}). When you
+return the Invert attribute to zero, or clear it, the Mapping returns
+to its original behaviour.
+
+Often, the actual value of the Invert attribute is unimportant and you
+simply wish to invert its boolean sense, so that what was the
+Mapping's input becomes its output and \emph{vice versa}. This is most
+easily accomplished using \htmlref{astInvert}{astInvert}, as follows:
+
+\small
+\begin{terminalv}
+AstMapping *mapping;
+
+...
+
+astInvert( mapping );
+\end{terminalv}
+\normalsize
+
+If the Mapping you have happens to be the wrong way around, astInvert
+allows you to correct the problem.
+
+\subsection{Finding the Rate of Change of a Mapping Output}
+The
+\htmlref{astRate}{astRate}
+function can be used to find the rate of change of any \htmlref{Mapping}{Mapping} output
+with respect to any Mapping input, at a given input position. The method
+used produces good accuracy (typically a relative error of 10E-10 or
+less) but may require the Mapping to be evaluated 100 or more times.
+An estimate of the second derivative is also produced by this function.
+
+
+\subsection{Reporting Coordinate Transformations}
+
+We have already seen (\secref{ss:transforming}) how the boolean
+(integer) \htmlref{Report}{Report} attribute of a \htmlref{Mapping}{Mapping} works. If it is non-zero, the
+operation of transforming a set of coordinates will result in a report
+being written to standard output. This will display the coordinate
+values before and after transformation. It can save considerable time
+during program development by eliminating the need to add loops and
+output statements to your program.
+
+In a finished program, however, you should be careful that the Report
+attribute is not set to a non-zero value unless you want to see the
+output (there may often be rather a lot of this!). To help prevent
+unwanted output being produced by accident, the Report attribute is
+unusual in that its value is not preserved when a Mapping is copied
+using \htmlref{astCopy}{astCopy} (\secref{ss:copyingobjects}). Instead, it reverts to its
+default of zero (\emph{i.e.}\ un-set) in the copy. It also reverts to
+zero when a Mapping is written out, \emph{e.g.}\ to a file using a
+\htmlref{Channel}{Channel} (\secref{ss:channels}).
+
+%\subsection{TBW---More on Transforming Coordinates}
+
+\subsection{\label{ss:badcoordinates}Handling Missing (Bad) Coordinate Values}
+
+Even when coordinates can, in principle, be transformed in either
+direction by a \htmlref{Mapping}{Mapping}, there may still be instances where specific
+coordinate values cannot be handled. For example, the Mapping may be
+mathematically intractable (\emph{e.g.}\ singular) in certain places,
+or it may map a subset of one space on to another, so that some points
+in one space are not represented in the other.  Sky projections often
+show this behaviour, since it is quite common to project only half of
+the celestial sphere on to two dimensions, omitting points on the
+opposite side of the sky. There are many other examples.
+
+To indicate when coordinates cannot be transformed, for whatever
+reason, AST substitutes a special output coordinate value given by the
+macro AST\_\_BAD (as defined in the ``ast.h'' header file).  Before
+making use of coordinates generated by any of the AST transformation
+functions, therefore, you may need to check for the presence of this
+value.
+
+Because coordinates with the value AST\_\_BAD can be generated in this
+way, all other AST functions are also capable of recognising this
+value and handling it appropriately. The coordinate transformation
+functions do this by propagating any missing input coordinate
+information through to their output.  This means that if you supply
+coordinates with the value AST\_\_BAD, the returned coordinates are
+also likely to contain this value. Here, for example, is what happens
+if you use a \htmlref{ZoomMap}{ZoomMap} (with \htmlref{Zoom}{Zoom} factor 5) to transform such a set of
+coordinates:
+
+\small
+\begin{terminalv}
+(0, 0) --> (0, 0)
+(<bad>, 2) --> (<bad>, 10)
+(2, 4) --> (10, 20)
+(3, 6) --> (15, 30)
+(4, <bad>) --> (20, <bad>)
+(5, 10) --> (25, 50)
+(<bad>, <bad>) --> (<bad>, <bad>)
+(7, 14) --> (35, 70)
+(8, 16) --> (40, 80)
+(9, 18) --> (45, 90)
+\end{terminalv}
+\normalsize
+
+The AST\_\_BAD value is represented by the string ``$<$bad$>$''. This
+is a case of ``garbage in, garbage out'' but at least it's consistent
+garbage that you can recognise!
+
+Note how the presence of the AST\_\_BAD value in one input dimension
+does not necessarily result in the loss of information for all output
+dimensions. Sometimes, such loss will be unavoidable, but in general
+an attempt is made to preserve information as far as possible. The
+exact behaviour will depend on the Mapping involved.
+
+\subsection{\label{ss:unitmapexample}Example---the UnitMap}
+
+The \htmlref{UnitMap}{UnitMap} is the simplest of Mappings. It is a null \htmlref{Mapping}{Mapping}. Its
+purpose is simply to copy coordinate values, unaltered, from its input
+to its output and \emph{vice versa}.
+
+A UnitMap has no additional attributes beyond those of a basic
+Mapping. Its \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes are always equal and are
+specified by the first argument supplied to its constructor. For
+example:
+
+\small
+\begin{terminalv}
+AstUnitMap *unitmap;
+
+...
+
+unitmap = astUnitMap( 2, "" );
+\end{terminalv}
+\normalsize
+
+will create a UnitMap that copies 2-dimensional coordinates. Inverting
+a UnitMap has no effect beyond changing the value of its \htmlref{Invert}{Invert}
+attribute.
+
+The main use of a UnitMap is to allow a Mapping to be supplied when one
+is required (as an argument to a function, for example) but you wish
+it to leave coordinate values unchanged.
+
+\subsection{\label{ss:permmapexample}Example---the PermMap}
+
+The \htmlref{PermMap}{PermMap} is a rather more complicated \htmlref{Mapping}{Mapping} than we have met
+previously.  Its purpose is to change the order, or number, of
+coordinates. It is also able to substitute fixed values for
+coordinates.
+
+To illustrate its action, suppose our input coordinates are denoted by
+($x_1,x_2,x_3,x_4$) in a 4-dimensional space and suppose our output
+coordinates are to be ($x_4,x_1,x_2,x_3$). Our PermMap, therefore,
+should rotate the coordinate values by one position.
+
+To create such a PermMap, we first set up two integer arrays. One of
+these, ``outperm'', controls the selection of input coordinates for
+use in the output and the other, ``inperm'', controls selection of
+output coordinates for use in the input:
+
+\small
+\begin{terminalv}
+int outperm[ 4 ] = { 4, 1, 2, 3 };
+int inperm[ 4 ] = { 2, 3, 4, 1 };
+\end{terminalv}
+\normalsize
+
+Note that the numbers we store in these arrays are the indices of the
+coordinates that we want to select. We have chosen these so that the
+forward and inverse transformations will perform complementary
+permutations on the coordinates.
+
+The PermMap is then created by passing these arrays to its
+constructor, as follows:
+
+\small
+\begin{terminalv}
+AstPermMap *permmap;
+
+...
+
+permmap = astPermMap( 4, inperm, 4, outperm, NULL, "" );
+\end{terminalv}
+\normalsize
+
+Note that we specify the number of input and output coordinates
+separately, but set both to 4 in this example. The resulting PermMap
+would have the following effect when used to transform coordinates:
+
+\begin{terminalv}
+Forward:
+   (1, 2, 3, 4) --> (4, 1, 2, 3)
+   (2, 4, 6, 8) --> (8, 2, 4, 6)
+   (3, 6, 9, 12) --> (12, 3, 6, 9)
+   (4, 8, 12, 16) --> (16, 4, 8, 12)
+   (5, 10, 15, 20) --> (20, 5, 10, 15)
+
+Inverse:
+   (4, 1, 2, 3) --> (1, 2, 3, 4)
+   (8, 2, 4, 6) --> (2, 4, 6, 8)
+   (12, 3, 6, 9) --> (3, 6, 9, 12)
+   (16, 4, 8, 12) --> (4, 8, 12, 16)
+   (20, 5, 10, 15) --> (5, 10, 15, 20)
+\end{terminalv}
+
+If the number of input and output coordinates are unequal so, also,
+will be the size of the ``outperm'' and ``inperm'' arrays. This means,
+however, that we cannot fill them with coordinate indices so that they
+perform complementary permutations, because one transformation will
+lose information (discard a coordinate) that the other cannot recover.
+To give an example, consider the following:
+
+\small
+\begin{terminalv}
+int outperm[ 3 ] = { 4, 3, 2 };
+int inperm[ 4 ] = { -1, 3, 2, 1 };
+double con[ 1 ] = { 99.004 };
+\end{terminalv}
+\normalsize
+
+In this case, the forward transformation will change
+($x_1,x_2,x_3,x_4$) into ($x_4,x_3,x_2$) and will discard $x_1$. The
+inverse transformation restores the original coordinate order, but has
+no value to assign to the first coordinate. In this case, the number
+entered in the ``inperm'' array is $-$1.
+
+This negative value indicates that the coordinate value should be
+obtained by addressing the first element of the ``con'' array
+(\emph{i.e.}\ element zero). This array, ignored in the previous
+example, may then be used to supply a value for the missing
+coordinate.
+
+The constructor function:
+
+\small
+\begin{terminalv}
+permmap = astPermMap( 4, inperm, 3, outperm, con, "" );
+\end{terminalv}
+\normalsize
+
+will then create a PermMap with the following effect when used to
+transform coordinates:
+
+\begin{terminalv}
+Forward:
+   (1, 2, 3, 4) --> (4, 3, 2)
+   (2, 4, 6, 8) --> (8, 6, 4)
+   (3, 6, 9, 12) --> (12, 9, 6)
+   (4, 8, 12, 16) --> (16, 12, 8)
+   (5, 10, 15, 20) --> (20, 15, 10)
+
+Inverse:
+   (4, 3, 2) --> (99.004, 2, 3, 4)
+   (8, 6, 4) --> (99.004, 4, 6, 8)
+   (12, 9, 6) --> (99.004, 6, 9, 12)
+   (16, 12, 8) --> (99.004, 8, 12, 16)
+   (20, 15, 10) --> (99.004, 10, 15, 20)
+\end{terminalv}
+
+The ``con'' array may contain more than one value if necessary and may
+be addressed by both the ``inperm'' and ``outperm'' arrays using
+coordinate indices $-$1, $-$2, $-$3,~\emph{etc.}\ to refer to the
+first, second, third,~\emph{etc.}\ elements.
+
+If there is no suitable replacement value that can be supplied
+\emph{via} the ``con'' array, a value of zero may be entered into the
+``outperm'' and/or ``inperm'' arrays. This causes the value AST\_\_BAD
+to be used for the affected coordinate (as defined in the ``ast.h''
+header file), thus indicating a missing coordinate value
+(\secref{ss:badcoordinates}).
+
+The principle use for a PermMap lies in matching a coordinate system
+to a data array where there is a choice of storage order for the data.
+PermMaps are also useful for discarding unwanted coordinates so as to
+reduce the number of dimensions, such as when selecting a ``slice''
+from a multi-dimensional array.
+
+\cleardoublepage
+\section{\label{ss:cmpmaps}Compound Mappings (CmpMaps)}
+
+We now turn to a rather special form of \htmlref{Mapping}{Mapping}, the \htmlref{CmpMap}{CmpMap}. The
+Mappings we have considered so far have been atomic, in the sense that
+they perform pre-defined elementary transformations. A CmpMap,
+however, is a compound Mapping. In essence, it is a framework for
+containing other Mappings and its purpose is to allow those Mappings
+to work together in various combinations while appearing as a single
+\htmlref{Object}{Object}. A CmpMap's behaviour is therefore not pre-defined, but is
+determined by the other Mappings it contains.
+
+\subsection{\label{ss:seriescmpmap}Combining Mappings in Series}
+
+Consider a simple example based on two 2-dimensional coordinate
+systems. Suppose that to convert from one to the other we must swap
+the coordinate order and multiply both coordinates by 5, so that the
+coordinates ($x_1,x_2$) transform into ($5x_2,5x_1$). This can be done
+in two stages:
+
+\begin{enumerate}
+\item Apply a \htmlref{PermMap}{PermMap} (\secref{ss:permmapexample}) to swap the
+coordinate order.
+
+\item Apply a \htmlref{ZoomMap}{ZoomMap} (\secref{ss:transforming}) to multiply both
+coordinate values by the constant 5.
+\end{enumerate}
+
+The PermMap and ZoomMap are then said to operate \emph{in series},
+because they are applied sequentially
+(\emph{c.f.}\ Figure~\ref{fig:seriescmpmap}).  We can create a \htmlref{CmpMap}{CmpMap}
+that applies these Mappings in series as follows:
+
+\small
+\begin{terminalv}
+#include "ast.h"
+AstCmpMap *cmpmap;
+AstPermMap *permmap;
+AstZoomMap *zoommap;
+
+...
+
+/* Create the individual Mappings. */
+{
+   int inperm[ 2 ] = { 2, 1 };
+   int outperm[ 2 ] = { 2, 1 };
+   permmap = astPermMap( 2, inperm, 2, outperm, NULL, "" );
+}
+zoommap = astZoomMap( 2, 5.0, "" )
+
+/* Combine them in series. */
+cmpmap = astCmpMap( permmap, zoommap, 1, "" );
+
+/* Annul the individual Mapping pointers. */
+permmap = astAnnul( permmap );
+zoommap = astAnnul( zoommap );
+\end{terminalv}
+\normalsize
+
+Here, the third argument (1) of the constructor function \htmlref{astCmpMap}{astCmpMap}
+indicates ``in series''.
+
+When used to transform coordinates in the forward direction, the
+resulting CmpMap will apply the first component \htmlref{Mapping}{Mapping} (the PermMap)
+and then the second one (the ZoomMap). When transforming in the
+inverse direction, it will apply the second one (in the inverse
+direction) and then the first one (also in the inverse direction).  In
+general, although not in this particular example, the order in which
+the two component Mappings are supplied is significant. Clearly, also,
+the \htmlref{Nout}{Nout} attribute (number of output coordinates) for the first
+Mapping must equal the \htmlref{Nin}{Nin} attribute (number of input coordinates) for
+the second one.
+
+\subsection{Combining Mappings in Parallel}
+
+Connecting two Mappings in series (\secref{ss:seriescmpmap}) is not the
+only way of combining them. The alternative, \emph{in parallel},
+involves applying the two Mappings at once but on different subsets of
+the coordinate values.
+
+Consider, for example, a set of 3-dimensional coordinates and suppose
+we wish to transform them by swapping the first two coordinate values
+and multiplying the final one by 5, so that ($x_1,x_2,x_3$) transforms
+into ($x_2,x_1,5x_3$). Again, we can perform each of these steps
+individually using Mappings similar to the \htmlref{PermMap}{PermMap} and \htmlref{ZoomMap}{ZoomMap} used
+earlier (\secref{ss:seriescmpmap}). In this case, however, the ZoomMap is
+1-dimensional and the individual Mappings are applied in parallel
+(\emph{c.f.}\ Figure~\ref{fig:parallelcmpmap}).
+
+Creating a \htmlref{CmpMap}{CmpMap} for this purpose is also very simple:
+
+\small
+\begin{terminalv}
+cmpmap = astCmpMap( permmap, zoommap, 0, "" );
+\end{terminalv}
+\normalsize
+
+The only difference is that the third argument of \htmlref{astCmpMap}{astCmpMap} is now
+zero, meaning ``in parallel''.
+
+As before, the order in which the two component Mappings are supplied
+is significant. The first one acts on the lower-numbered input
+coordinate values (however many it needs) and produces the
+lower-numbered output coordinates, while the second \htmlref{Mapping}{Mapping} acts on
+the higher-numbered input coordinates (however many remain) and
+generates the remaining higher-numbered output coordinates.  When the
+CmpMap transforms coordinates in the inverse direction, both component
+Mappings are applied to the same coordinates, but in the inverse
+direction.
+
+Note that the \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes of the component Mappings
+(\emph{i.e.}\ the numbers of input and output coordinates) will sum to
+give the Nin and Nout attributes of the overall CmpMap.
+
+\subsection{\label{ss:cmpmapcomponents}The Component Mappings}
+
+A \htmlref{CmpMap}{CmpMap} does not store copies of its component Mappings, but simply
+holds pointers to them. In the example above
+(\secref{ss:seriescmpmap}), we were free to annul the individual
+\htmlref{Mapping}{Mapping} pointers after creating the CmpMap because the pointers held
+internally by the CmpMap increased the reference count (\htmlref{RefCount}{RefCount}
+attribute) of each component Mapping by one. The individual components
+are therefore not deleted by \htmlref{astAnnul}{astAnnul}, but retained until the CmpMap
+itself is deleted and annuls the pointers it holds. Consistent use of
+astAnnul (\secref{ss:annullingpointers}) and/or pointer contexts
+(\secref{ss:contexts}) will therefore ensure that all Objects are
+deleted at the appropriate time.
+
+Note that access to a CmpMap's component Mappings is not generally
+available unless pointers to them are retained when the CmpMap is
+created. If such pointers are retained, then subsequent modifications
+to the individual components can be used to indirectly modify the
+behaviour of the overall CmpMap.
+
+There is an important exception to this, however, because a CmpMap
+retains a copy of the initial \htmlref{Invert}{Invert} flag settings of each of its
+components and uses these in order to ignore any subsequent external
+changes. This means that you may invert either component Mapping
+before inserting it into a CmpMap and need not worry if you un-invert
+it again later. The CmpMap's behaviour will not be affected by the
+later action.
+
+\subsection{\label{ss:complexcmpmap}Creating More Complex Mappings}
+
+Because a \htmlref{CmpMap}{CmpMap} is itself a \htmlref{Mapping}{Mapping}, any existing CmpMap can
+substitute (\secref{ss:objecthierarchy}) as a component Mapping when
+constructing a new CmpMap using \htmlref{astCmpMap}{astCmpMap}. This has the effect of
+nesting one CmpMap inside another and opens up many new possibilities.
+For example, combining three Mappings in series can be accomplished as
+follows:
+
+\small
+\begin{terminalv}
+AstMapping *map1, *map2, *map3;
+
+...
+
+cmpmap = astCmpMap( map1, astCmpMap( map2, map3, 1, "" ), 1, "" );
+\end{terminalv}
+\normalsize
+
+The way in which the individual component Mappings are grouped within
+the nested CmpMaps is not usually important.
+
+A similar technique can be used to combine multiple Mappings in
+parallel and, of course, mixed series and parallel combinations are
+also possible (Figure~\ref{fig:complexcmpmap}).  There is no built-in
+limit to how many CmpMaps may be nested in this way, so this mechanism
+provides an indefinitely extensible method of building complex
+Mappings out of the elemental building blocks provided by AST.
+
+In practice, you might not need to construct such complex CmpMaps
+yourself very frequently, but they will often be returned by AST
+routines.  Nested CmpMaps underlie the library's entire ability to
+represent a wide range of different coordinate transformations.
+
+\subsection{\label{ss:cmpmapexample}Example---Transforming Between Two Calibrated Images}
+
+Consider, as a practical example of CmpMaps, two images of the
+sky. Suppose that for each image we have a \htmlref{Mapping}{Mapping} which converts from
+pixel coordinates to a standard celestial coordinate system, say
+FK5~(J2000.0). If we wish to inter-compare these images, we can do so
+by using this celestial coordinate system to align them. That is, we
+first convert from pixel coordinates in the first image into FK5
+coordinates and we then convert from FK5 coordinates into pixel
+coordinates in the second image.
+
+If ``mapa'' and ``mapb'' are pointers to our two original Mappings, we
+could form a \htmlref{CmpMap}{CmpMap} which transforms directly between the pixel
+coordinates of the first and second images by combining these
+Mappings, as follows:
+
+\small
+\begin{terminalv}
+AstCmpMap *alignmap;
+AstMapping *mapa, *mapb;
+
+...
+
+astInvert( mapb );
+alignmap = astCmpMap( mapa, mapb, 1, "" );
+astInvert( mapb );
+\end{terminalv}
+\normalsize
+
+Here, we have used \htmlref{astInvert}{astInvert} (\secref{ss:invertingmappings}) to invert
+``mapb'' before inserting it into the CmpMap because, as supplied, it
+converted in the wrong direction. Afterwards, we invert it again to
+return it to its original state. The CmpMap, however, will ignore this
+subsequent change (\secref{ss:cmpmapcomponents}).
+
+The forward transformation of the resulting CmpMap will now transform
+from pixel coordinates in the first image to pixel coordinates in the
+second image, while its inverse transformation will convert in the
+opposite direction.
+
+\subsection{\label{ss:overcomplexcmpmaps}Over-Complex Compound Mappings}
+
+While a \htmlref{CmpMap}{CmpMap} provides a very flexible way of constructing
+arbitrarily complex Mappings (\secref{ss:complexcmpmap}), it
+unfortunately also provides an opportunity for representing simple
+Mappings in complex ways. Sometimes, unnecessary complexity can be
+difficult to avoid but can obscure important simplifications.
+
+Consider the example above (\secref{ss:cmpmapexample}), in which we
+inter-related two images of the sky \emph{via} a CmpMap.  If the two
+images turned out to be simply offset from each other by a shift along
+each pixel axis, then this approach would align them correctly, but it
+would be inefficient. This is because it would introduce unnecessary
+and expensive transformations to and from an intermediate celestial
+coordinate system, whereas a simple shift of pixel origin would
+suffice.
+
+Recognising that a simpler and more efficient solution exists
+obviously requires a little more than simply joining two Mappings
+end-to-end. We must also determine whether the resulting CmpMap is
+more complex than it needs to be, \emph{i.e.}\ contains redundant
+information. If it is, we then need a way to simplify it.
+
+The problem is not always just one of efficiency, however. Sometimes
+we may also need to know something about the actual form a \htmlref{Mapping}{Mapping}
+takes---\emph{i.e.}\ the nature of the operations it performs.
+Unnecessary complexity can obscure this, but such complexity can
+easily accumulate during normal data processing.
+
+For example, a Mapping that transforms pixel coordinates into
+positions on the sky might be repeatedly modified as changes are made
+to the shape and size of the image. Typically, on each occasion,
+another Mapping will be concatenated to reflect what has happened to
+the image. This could soon make it difficult to discern the overall
+nature of the transformation from the complex CmpMap that
+accumulates. If only shifts of origin were involved on each occasion,
+however, they could be combined into a single shift which could be
+represented much more simply.
+
+Suppose we now wanted to represent our image's celestial coordinate
+calibration using FITS conventions (\secref{ss:foreignfits}). This
+requires AST to determine whether the Mapping which relates pixel
+coordinate to sky positions conforms to the FITS model (for example,
+whether it is equivalent to applying a single set of shifts and scale
+factors followed by a map projection). Clearly, there is an important
+use here for some means of simplifying the internal structure of a
+CmpMap.
+
+\subsection{\label{ss:simplifyingcmpmaps}Simplifying Compound Mappings}
+
+The ability to simplify compound Mappings is provided by the
+\htmlref{astSimplify}{astSimplify} function. This function encapsulates a number of
+heuristics for converting Mappings, or combinations of Mappings within
+a \htmlref{CmpMap}{CmpMap}, into simpler, equivalent ones. When applied to a CmpMap,
+astSimplify tries to reduce the number of individual Mappings within
+it by merging neighbouring component Mappings together. It will do
+this with both series and parallel combinations of Mappings, or both,
+and will handle CmpMaps nested to any depth
+(\secref{ss:complexcmpmap}).
+
+   To illustrate how astSimplify works, consider the combination of
+   Mappings shown in Figure~\ref{fig:simplifyexample}.
+   \begin{figure}
+   \begin{center}
+   \includegraphics[width=0.7\textwidth]{sun211_figures/simpexamp}
+   \caption[An over-complex compound Mapping.]{An over-complex compound Mapping, consisting of PermMaps,
+   ZoomMaps and a \htmlref{UnitMap}{UnitMap}, which can be simplified to become a single
+   UnitMap.  The enclosing nested CmpMaps have been omitted for clarity.}
+   \label{fig:simplifyexample}
+   \end{center}
+   \end{figure}
+
+If this were contained in a CmpMap, it could be simplified as follows:
+
+\small
+\begin{terminalv}
+AstMapping *simpler;
+
+...
+
+simpler = astSimplify( cmpmap );
+\end{terminalv}
+\normalsize
+
+In this case, the result would be a simple 3-dimensional UnitMap (the
+identity \htmlref{Mapping}{Mapping}).  To reach this conclusion, astSimplify will have
+made a number of deductions, roughly as follows:
+
+\begin{enumerate}
+\item The two 2-dimensional ZoomMaps in series are equivalent to a
+single \htmlref{ZoomMap}{ZoomMap} with a combined \htmlref{Zoom}{Zoom} factor of unity. This, in turn, is
+equivalent to a 2-dimensional UnitMap.
+
+\item This UnitMap in parallel with the other 1-dimensional UnitMap is
+equivalent to a single 3-dimensional UnitMap. This UnitMap, sandwiched
+between any other pair of Mappings, can then be eliminated.
+
+\item The remaining two PermMaps in series are equivalent to a single
+3-dimensional \htmlref{PermMap}{PermMap}. When these are combined, the resulting PermMap
+is found to be equivalent to a 3-dimensional UnitMap.
+\end{enumerate}
+
+This example is a little contrived, but illustrates how astSimplify
+can deal with even quite complicated compound Mappings through a
+series of incremental simplifications. Where possible, this will
+result in either a simpler compound Mapping or, if feasible, an atomic
+(non-compound) Mapping, as here. If no simplification is possible,
+astSimplify will just return a pointer to the original Mapping.
+
+Although astSimplify cannot identify every simplification that is
+theoretically possible, sufficient rules are included to deal with the
+most common and important cases.
+
+\cleardoublepage
+\section{\label{ss:frames}Representing Coordinate Systems (Frames)}
+
+An AST \htmlref{Frame}{Frame} is an \htmlref{Object}{Object} that is used to represent a coordinate
+system. Contrast this with a \htmlref{Mapping}{Mapping} (\secref{ss:mappings}), which is
+used to describe how to convert between coordinate systems. The two
+concepts are complementary and we will see how they work together in
+\secref{ss:framesets}.
+
+In this section we will discuss only basic Frames, which represent
+Cartesian coordinate systems. More specialised types of Frame
+(\emph{e.g.}\ the \htmlref{SkyFrame}{SkyFrame}, which represents celestial coordinate
+systems, and the \htmlref{SpecFrame}{SpecFrame}, which represents spectral coordinate
+systems) are covered later (\secref{ss:skyframes} and \secref{ss:specframes})
+and, naturally, inherit the properties and behaviour of the simple Frames
+discussed here.
+
+\subsection{The Frame Model}
+
+The best way to think about a \htmlref{Frame}{Frame} is like the frame that you would
+plot around a graph. In two dimensions, you would have an ``$x$'' and
+a ``$y$'' axis, a title on the graph and labels on the axes, together
+with an indication of the physical units being plotted. The values
+marked along each axis would be formatted in a human-readable way. The
+frame around a graph therefore defines a coordinate space within which
+you can locate points, draw lines, calculate distances, \emph{etc.}
+
+An AST Frame works in much the same way, embodying all of these
+concepts and a few more. It also allows any number of axes, which
+means that a Frame can represent coordinate systems with any number of
+dimensions. You specify how many when you create it.
+
+Remember that the basic Frame we are considering here is completely
+general.  It knows nothing of celestial coordinates, for example, and
+all its axes are equivalent. It can be adapted to describe any general
+purpose Cartesian coordinate system by setting its attributes, such as
+its \htmlref{Title}{Title} and axis Labels, \emph{etc.}\ to appropriate values.
+
+\subsection{\label{ss:creatingframes}Creating a Frame}
+
+Creating a \htmlref{Frame}{Frame} is straightforward and follows the usual pattern:
+
+\small
+\begin{terminalv}
+#include "ast.h"
+astFrame *frame;
+
+...
+
+frame = astFrame( 2, "" );
+\end{terminalv}
+\normalsize
+
+The first argument of the \htmlref{astFrame}{astFrame} constructor function specifies the
+number of axes which the Frame should have.
+
+\subsection{\label{ss:frameasmapping}Using a Frame as a Mapping}
+
+We should briefly point out that the \htmlref{Frame}{Frame} we created above
+(\secref{ss:creatingframes}) is also a \htmlref{Mapping}{Mapping}
+(\secref{ss:mappingclass}) and therefore inherits the properties and
+behaviour common to other Mappings.
+
+One way to see this is to set the Frame's \htmlref{Report}{Report} attribute (inherited
+from the Mapping class) to a non-zero value and pass the Frame pointer
+to a coordinate transformation function, such as \htmlref{astTran2}{astTran2}.
+
+\small
+\begin{terminalv}
+double xin[ 5 ] = { 0.0, 1.0, 2.0, 3.0, 4.0, 5.0 };
+double yin[ 5 ] = { 0.0, 2.0, 4.0, 6.0, 8.0, 10.0 };
+double xout[ 5 ];
+double yout[ 5 ];
+
+...
+
+astSet( frame, "Report=1" );
+astTran2( frame, 5, xin, yin, 1, xout, yout );
+\end{terminalv}
+\normalsize
+
+The resulting output might then look like this:
+
+\begin{terminalv}
+(1, 2) --> (1, 2)
+(2, 4) --> (2, 4)
+(3, 6) --> (3, 6)
+(4, 8) --> (4, 8)
+(5, 10) --> (5, 10)
+\end{terminalv}
+
+This is not very exciting because a Frame implements an identity
+transformation just like a \htmlref{UnitMap}{UnitMap}
+(\secref{ss:unitmapexample}). However, it illustrates that a Frame can
+be used as a Mapping and that its \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes are both
+equal to the number of Frame axes.
+
+When we consider more specialised Frames
+(\emph{e.g.}~\secref{ss:framesets}), we will see that using them as
+Mappings can be very useful indeed.
+
+\subsection{\label{ss:frameaxisattributes}Frame Axis Attributes}
+
+Frames have a number of attributes which can take multiple values, one
+for each axis. These separate values are identified by appending the
+axis number in parentheses to the attribute name. For example, the
+Label(1) attribute is a character string containing the label which
+appears on the first axis.
+
+\htmlref{Axis}{Axis} attributes are accessed in the same way as all other attributes
+(\secref{ss:gettingattributes}, \secref{ss:settingattributes} and
+\secref{ss:defaultingattributes}). For example, the Label on the second
+axis might be obtained as follows:
+
+\small
+\begin{terminalv}
+const char *label;
+
+...
+
+label = astGetC( frame, "Label(2)" );
+\end{terminalv}
+\normalsize
+
+Other attribute access functions (astSetX, \htmlref{astTest}{astTest} and \htmlref{astClear}{astClear}) may
+also be applied to axis attributes in the same way.
+
+If the axis number is stored in a program variable, then its value
+must be formatted to generate a suitable attribute name before using
+this to access the attribute itself. For example, the following will
+print out the Label value for each axis of a \htmlref{Frame}{Frame}:
+
+\small
+\begin{terminalv}
+#include <stdio.h>
+char name[ 18 ];
+int iaxis, naxes;
+
+...
+
+naxes = astGetI( frame, "Naxes" );
+for ( iaxis = 1; iaxis <= naxes; iaxis++ ) {
+   (void) sprintf( name, "Label(%d)", iaxis );
+   label = astGetC( frame, name );
+   (void) printf( "Label %2d: %s\n", iaxis, label );
+}
+\end{terminalv}
+\normalsize
+
+Note the use of the \htmlref{Naxes}{Naxes} attribute to determine the number of Frame
+axes.
+
+The output from this might look like the following:
+
+\begin{terminalv}
+Label  1: Axis 1
+Label  2: Axis 2
+\end{terminalv}
+
+In this case, the Frame's default axis Labels have been revealed as
+rather un-exciting. Normally, you would set much more useful values,
+typically when you create the Frame---perhaps something like:
+
+\small
+\begin{terminalv}
+frame = astFrame( 2, "Label(1)=Offset from centre of field,"
+                     "Unit(1) =mm,"
+                     "Label(2)=Transmission coefficient,"
+                     "Unit(2) =%" );
+\end{terminalv}
+\normalsize
+
+Here, we have also set the (character string) Unit attribute for each
+axis to describe the physical units represented on that axis. All the
+attribute assignments have been combined into a single string,
+separated by commas.
+
+\subsection{\label{ss:frameattributes}Frame Attributes}
+
+We will now briefly outline the various attributes associated with a
+\htmlref{Frame}{Frame} (this is, of course, in addition to those inherited from the
+\htmlref{Mapping}{Mapping} class). We will not delve too deeply into the details of each
+attribute, for which you should consult the appropriate description in
+\appref{ss:attributedescriptions}. Instead, we aim simply to sketch
+the range of facilities available:
+
+\begin{quote}
+\begin{description}
+\item[\htmlref{Naxes}{Naxes}]\mbox{}\\
+A read-only integer giving the number of Frame axes.
+
+\item[\htmlref{Title}{Title}]\mbox{}\\
+A string describing the coordinate system which the Frame represents.
+
+\item[\htmlref{Label(axis)}{Label(axis)}]\mbox{}\\
+A label string for each axis.
+
+\item[\htmlref{Unit(axis)}{Unit(axis)}]\mbox{}\\
+A string describing the physical units on each axis. You can choose
+whether to make this attribute ``active'' or ``passive'' (using
+\htmlref{astSetActiveUnit}{astSetActiveUnit}
+). If active, its value will be taken into account when finding the
+Mapping between two Frames (\emph{e.g.} a scaling of 0.001 would be used
+to connect two axis with units of ``km'' and ``m''). If passive, its value
+is ignored. Its use is described in more detail in \secref{ss:frameunits}.
+
+\item[\htmlref{Symbol(axis)}{Symbol(axis)}]\mbox{}\\
+A string containing a ``short form'' symbol (\emph{e.g.}\ like ``X''
+or ``Y'') used to represent the quantity plotted on each axis.
+
+\item[\htmlref{Digits/Digits(axis)}{Digits/Digits(axis)}]\mbox{}\\
+The preferred number of digits of precision to be used when formatting
+values for display on each axis.
+
+\item[\htmlref{Format(axis)}{Format(axis)}]\mbox{}\\
+A string containing a \emph{format specifier} which determines exactly
+how values should be formatted for display on each axis
+(\secref{ss:formattingaxisvalues}). If this attribute is un-set, the
+formatting is based on the Digits value, otherwise the Format string
+over-rides the Digits value.
+
+\item[\htmlref{Direction(axis)}{Direction(axis)}]\mbox{}\\
+A boolean (integer) value which indicates in which direction each axis
+should be plotted. If it is non-zero (the default), the axis should be
+plotted in the conventional direction---\emph{i.e.}\ increasing to the
+right for the abscissa and increasing upwards for the ordinate. If it
+is zero, the axis should be plotted in reverse.  This attribute is
+provided as a hint only and programs are free to ignore it if they
+wish.
+
+\item[\htmlref{Domain}{Domain}]\mbox{}\\
+A character string which identifies the \emph{physical domain} to
+which the Frame's coordinate system applies. The primary purpose of
+this attribute is to prevent unwanted conversions from occurring
+between coordinate systems which are not related. Its use is described
+in more detail in \secref{ss:framedomains}.
+
+\item[\htmlref{System}{System}]\mbox{}\\
+A character string which identifies the specific coordinate system used
+to describe positions within the physical domain represented by the Frame.
+For a simple Frame, this attribute currently has a fixed value of
+``Cartesian'', but could in principle be extended to include options such
+as ``Polar'', ``Cylindrical'', \emph{etc}. More specialised Frames such
+as the \htmlref{SkyFrame}{SkyFrame}, \htmlref{TimeFrame}{TimeFrame}  and \htmlref{SpecFrame}{SpecFrame}, re-define the allowed values to be
+appropriate to the domain which they describe. For instance, the SkyFrame
+allows values such as ``FK4'' and ``Galactic'', and the SpecFrame allows
+values such as ``frequency'' and ``wavelength''.
+
+\item[\htmlref{Epoch}{Epoch}]\mbox{}\\
+This value is used to qualify a coordinate system by giving the moment in
+time when the coordinates are correct. Usually, this will be the date of
+observation. The Epoch value is important in cases where coordinates
+systems move with respect to each other over time. An example of two such
+coordinate systems are the FK4 and FK5 celestial coordinate systems.
+
+\item[\htmlref{ObsLon}{ObsLon}]\mbox{}\\
+Specifies the longitude of the observer (assumed to be on the surface of
+the earth). The basic Frame class does not use this value, but
+specialised sub-classes may. For instance, the SpecFrame class uses it to
+calculate the relative velocity of the observer and the centre of the
+earth for use in converting between standards of rest.
+
+\item[\htmlref{ObsLat}{ObsLat}]\mbox{}\\
+Specifies the latitude of the observer. Use in conjunction with ObsLon.
+
+\end{description}
+\end{quote}
+
+There are also some further Frame attributes, not described above,
+which are important when Frames are used as templates to search for
+other Frames. Their use goes beyond the present discussion.
+%TBW---Add reference here.
+
+\subsection{\label{ss:formattingaxisvalues}Formatting Axis Values}
+
+The coordinate values associated with each axis of a \htmlref{Frame}{Frame} are stored
+(\emph{e.g.}\ within your program) as double values. The Frame class
+therefore provides a function, \htmlref{astFormat}{astFormat}, to convert these values into
+formatted strings for display:
+
+\small
+\begin{terminalv}
+const char *string
+double value;
+
+...
+
+string = astFormat( frame, iaxis, value );
+\end{terminalv}
+\normalsize
+
+Here, the astFormat function is passed a Frame pointer, the number of
+an axis (``iaxis'') and a double precision value to format
+(``value''). It returns a pointer to character string containing the
+formatted value.
+\label{ss:formattingwithdigits}
+
+By default, the formatting applied will be determined by the Frame's
+Digits attribute and will normally display results with seven digits
+of precision (corresponding approximately to the C ``float'' data type
+on many machines). Setting a different Digits value, however, allows
+you to adjust the precision as necessary to suit the accuracy of the
+coordinate data you are processing.  If finer control is needed, it is
+also possible to set a Digits value for each individual axis by
+appending an axis number to the attribute name
+(\emph{e.g.}\ ``Digits(2)''). If this is done, it over-rides the
+effect of the Frame's main Digits value for that axis.
+
+Even finer control is possible by setting the (character string) Format
+attribute for a Frame axis. The string given should contain a C
+\emph{format specifier} which explicitly determines how the values on
+that axis should be formatted. This will over-ride the effects of any
+Digits value\footnote{The exception to this rule is that if the Format
+value includes a precision of ``$.*$'', then Digits will be used to
+determine the actual precision used.}. Any valid ``printf'' format
+specifier may be used so long as it consumes exactly one double value.
+
+When setting Format values, remember that the ``\%'' which appears in
+the format specifier may need to be doubled to ``\%\%'' if you are
+using a function (such as \htmlref{astSet}{astSet}) which interprets ``printf'' format
+specifiers itself.
+
+It is recommended that you use astFormat whenever you display
+formatted coordinate values, even although you could format them
+yourself using ``sprintf''. This is because it puts the Frame in
+control of formatting. When you start to handle more elaborate Frames
+(representing, say, celestial coordinates), you will need different
+formatting methods. This approach delivers them without any change to
+your software.
+
+You should also consider regularly using the \htmlref{astNorm}{astNorm} function,
+described below (\secref{ss:normalising}), for any values that will be
+made visible to the user of your software.
+
+\subsection{\label{ss:normalising}Normalising Frame Coordinates}
+
+The function \htmlref{astNorm}{astNorm} is provided to cope with the fact that some
+coordinate systems do not extend indefinitely in all directions. Some
+may have boundaries, outside which coordinates are meaningless, while
+others wrap around on themselves, so that after a certain distance you
+return to the beginning again (coordinate systems based on circles and
+spheres, for instance). A basic \htmlref{Frame}{Frame} has no such complications, but
+other more specialised Frames (such as SkyFrames, representing the
+celestial sphere---\secref{ss:skyframes}) do.
+
+The role played by astNorm is to \emph{normalise} any arbitrary set of
+coordinates by converting them into a set which is ``within bounds'',
+interpreted according to the particular Frame in question. For
+example, on the celestial sphere, a right ascension value of 24~hours
+or more can have a suitable multiple of 24~hours subtracted without
+affecting its meaning and astNorm would perform this task. Similarly,
+negative values of right ascension would have a multiple of 24~hours
+added, so that the result lies in the range zero to 24~hours. The
+coordinates in question are modified in place by astNorm, as follows:
+
+\small
+\begin{terminalv}
+double point[ 2 ];
+
+...
+
+astNorm( frame, point );
+\end{terminalv}
+\normalsize
+
+If the coordinates supplied are initially OK, as they would always be
+with a basic Frame, then they are returned unchanged.
+
+Because the main purpose of astNorm is to convert coordinates into the
+preferred range for human consumption, its use is almost always
+appropriate immediately before formatting coordinate values for
+display using \htmlref{astFormat}{astFormat} (\secref{ss:formattingaxisvalues}). Even if
+the Frame in question does not restrict the range of coordinates, so
+that astNorm does nothing, using it will allow you to process other
+more specialised Frames, where normalisation is important, without
+changing your software.
+
+\subsection{\label{ss:unformattingaxisvalues}Reading Formatted Axis Values}
+
+The process of converting a formatted coordinate value for a \htmlref{Frame}{Frame}
+axis, such as might be produced by \htmlref{astFormat}{astFormat}
+(\secref{ss:formattingaxisvalues}), back into a numerical (double)
+value ready for processing is performed by \htmlref{astUnformat}{astUnformat}.  However,
+although this process is essentially the inverse of that performed by
+astFormat, there are a number of additional difficulties that must be
+addressed in practice.
+
+The main use for astUnformat is in reading formatted coordinate values
+which have been entered by the user of a program, or read from a
+file. As such, we can rarely assume that the values are neatly
+formatted in the way that astFormat would produce. Instead, it is
+usually desirable to allow considerable flexibility in the form of
+input that can be accommodated, so as to permit ``free-format'' data
+input by the user. In addition, we may need to extract individual
+coordinate values embedded in other textual data.
+
+Underlying these requirements is the root difficulty that the textual
+format used to represent a coordinate value will depend on the class
+of Frame we are considering. For example, for a basic Frame,
+astUnformat may have to read a value like ``1.25e-6'', whereas for a
+more specialised Frame representing celestial coordinates it may have
+to handle a value like ``-07d~49m~13s''. Of course, the format might
+also depend on which axis is being considered.
+
+Ideally, we would like to write software that can handle any kind of
+Frame. However, this makes it a little more difficult to analyse
+textual input data to extract individual coordinate values, since we
+cannot make assumptions about how the values are formatted. It would
+not be safe, for example, simply to assume that the values being read
+are separated by white space. This is not just because they might be
+separated by some other character, but also because celestial
+coordinate values might themselves contain spaces. In fact, to be
+completely safe, we cannot make any assumptions about how a formatted
+coordinate value is separated from the surrounding text, except that
+it should be separated in some way which is not ambiguous.
+
+This is the very basic assumption upon which astUnformat works. It is
+invoked as follows:
+
+\small
+\begin{terminalv}
+int n;
+
+...
+
+n = astUnformat( frame, iaxis, string, &value );
+\end{terminalv}
+\normalsize
+
+It is supplied with a Frame pointer (``frame''), the number of an axis
+(``iaxis'') and a character string to be read (``string''). If it
+succeeds in reading a value, astUnformat returns the resulting
+coordinate to the address supplied \emph{via} the final argument
+(``\&value''). The returned function value indicates how many
+characters were read from the string in order to obtain this result.
+
+The string is read as follows:
+
+\begin{enumerate}
+\item Any white space at the start is skipped over.
+
+\item Further characters are considered, one at a time, until the next
+character no longer matches any of the acceptable forms of input
+(given the characters that precede it). The longest sequence of
+characters which matches is then considered ``read''.
+
+\item If a suitable sequence of characters was read successfully, it
+is converted into a coordinate value which is returned. Any white
+space following this sequence is then skipped over and the total
+number of characters consumed is returned as the function value.
+
+\item If the sequence of characters read is empty, or insufficient to
+define a coordinate value, then the string does not contain a value to
+read. In this case, the read is aborted and astUnformat returns a
+function value of zero and no coordinate value.  However, it returns
+without error.
+\end{enumerate}
+
+Note that failing to read a coordinate value does not constitute an
+error, at least so far as astUnformat is concerned. However, an error
+can occur if the sequence of characters read appears to have the
+correct form but cannot be converted into a valid coordinate
+value. Typically, this will be because it violates some constraint,
+such as a limit on the value of one of its fields. The resulting error
+message will give details.
+
+For any given Frame axis, astUnformat does not necessarily always use
+the same algorithm for converting the sequence of characters it reads
+into a coordinate value. This is because some forms of input
+(particularly free-format input) can be ambiguous and might be
+interpreted in several ways depending on the context. For example, the
+celestial longitude ``12:34:56.7'' could represent an angle in degrees
+or a right ascension in hours. To decide which to use, astUnformat may
+examine the Frame's attributes and, in particular, the appropriate
+\htmlref{Format(axis)}{Format(axis)} string which is used by astFormat when formatting
+coordinate values (\secref{ss:formattingaxisvalues}). This is done in
+order that astFormat and astUnformat should complement each other---so
+that formatting a value and then un-formatting it will yield the
+original value, subject to any rounding error.
+
+To give a simple (but crucially incomplete!) example, consider reading
+a value for the axis of a basic Frame, as follows:
+
+\small
+\begin{terminalv}
+n = astUnformat( frame, iaxis, " 1.5e6   -99.0", &value );
+\end{terminalv}
+\normalsize
+
+astUnformat will skip over the initial space in the string supplied
+and then examine each successive character. It will accept the
+sequence ``1.5e6'' as input, but reject the space which follows
+because it does not form part of the format of a floating point
+number. It will then convert the characters ``1.5e6'' into a
+coordinate value and skip over the three spaces which follow them. The
+returned function value will therefore be 9, equal to the total number
+of characters consumed. This result may be used to address the string
+during a subsequent read, so as to commence reading at the start of
+``-99.0''.
+
+Most importantly, however, note that if the user of a program
+mistakenly enters the string ``~1.5r6\ldots'' instead of
+``~1.5e6\ldots'', a coordinate value of 1.5 and a function result of 4
+will be returned, because the ``r'' would prematurely terminate the
+attempt to read the value. Because this sort of mistake does not
+automatically result in an error but can produce incorrect results, it
+is \textbf{vital} to check the returned function value to ensure that
+the expected number of characters have been read.\footnote{Anyone who
+seriously uses the C run time library ``scanf'' function will know
+about the need for this check!}  For example, if the string is
+expected to contain exactly one value, and nothing else, then the
+following would suffice:
+
+\small
+\begin{terminalv}
+n = astUnformat( frame, iaxis, string, &value );
+if ( astOK ) {
+   if ( string[ n ] || !n ) {
+      <error in input data>
+   } else {
+      <value read correctly>
+   }
+}
+\end{terminalv}
+\normalsize
+
+If astUnformat does not detect an error itself, we check that it has
+read to the end-of-string and consumed at least one character (which
+traps the case of a zero-length input string). If this reveals an
+error, the value of ``n'' indicates where it occurred.
+
+Another common requirement is to obtain a position by reading a list
+of coordinates from a string which contains one value for each axis of
+a Frame. We assume that the values are separated in some unambiguous
+manner, perhaps using white space and/or some unspecified
+single-character separator. The choice of separator is up to the data
+supplier, who must choose it so as not to conflict with the format of
+the coordinate values, but our software does not need to know what it
+is. The following is a template algorithm for reading data in this
+form:
+
+\small
+\begin{terminalv}
+const char *s;
+double values[ 10 ];
+
+...
+
+/* Initialise a string pointer. */
+s = string;
+
+/* Obtain the number of Frame axes and loop through them. */
+naxes = astGetI( frame, "Naxes" );
+for ( iaxis = 1; iaxis <= naxes; iaxis++ ) {
+
+/* Attempt to read a value for this axis. */
+   n = astUnformat( frame, iaxis, s, &values[ iaxis - 1 ] );
+
+/* If nothing was read and this is not the first axis or the
+   end-of-string, try stepping over a separator and reading again. */
+   if ( !n && ( iaxis > 1 ) && *s )
+      n = astUnformat( frame, iaxis, ++s, &values[ iaxis - 1 ] );
+
+/* Quit if nothing was read, otherwise move on to the next value. */
+   if ( !n ) break;
+   s += n;
+}
+
+/* Check for possible errors. */
+if ( astOK ) {
+   if ( *s || !n ) {
+      <error in input data>
+   } else {
+      <values read correctly>
+   }
+}
+\end{terminalv}
+\normalsize
+
+In this case, ``s'' will point to the location of any input error.
+
+Note that this algorithm is insensitive to the precise format of the
+data and will therefore work with any class of Frame and any
+reasonably unambiguous input data. For example, here is a range of
+suitable input data for a 3-dimensional basic Frame:
+
+\small
+\begin{terminalv}
+1 2.5 3
+3.1,3.2,3.3
+1.5, 2.6, -9.9e2
+-1.1+0.4-1.8
+    .1/.2/.3
+ 44.0 ; 55.1 -14
+\end{terminalv}
+\normalsize
+
+\subsection{\label{ss:permutingaxes}Permuting Frame Axes}
+
+Once a \htmlref{Frame}{Frame} has been created, it is not possible to change the number
+of axes it contains, but it is possible to change the order in which
+these axes occur. To do so, an integer \emph{permutation array} is
+filled with the numbers of the axes so as to specify the new order,
+\emph{e.g.:}
+
+\small
+\begin{terminalv}
+int perm[ 2 ] = { 2, 1 };
+\end{terminalv}
+\normalsize
+
+In this case, the axes of a 2-dimensional Frame could be interchanged
+by passing this permutation array to the \htmlref{astPermAxes}{astPermAxes} function. That
+is, an ($x_1,x_2$) coordinate system would be changed into an
+($x_2,x_1$) coordinate system by:
+
+\small
+\begin{terminalv}
+astPermAxes( frame, perm );
+\end{terminalv}
+\normalsize
+
+If the axes are permuted more than once, the effects are cumulative.
+You are, of course, not restricted to Frames with only two axes.
+
+\subsection{Selecting Frame Axes}
+
+An alternative to changing the number of \htmlref{Frame}{Frame} axes, which is not
+allowed, is to create a new Frame by selecting axes from an existing
+one. The method of doing this is very similar to the way \htmlref{astPermAxes}{astPermAxes}
+is used (\secref{ss:permutingaxes}), in that we supply an integer
+array filled with the numbers of the axes we want, in their new
+order. In this case, however, the number of array elements need not
+equal the number of Frame axes.
+
+For example, we could select axes 3 and 2 (in that order) from a
+3-dimensional Frame as follows:
+
+\small
+\begin{terminalv}
+astFrame *frame1, *frame2;
+astMapping *mapping;
+int pick[ 2 ] = { 3, 2 };
+
+...
+
+frame2 = astPickAxes( frame1, 2, pick, &mapping );
+\end{terminalv}
+\normalsize
+
+This would return a pointer to a 2-dimensional Frame (``frame2'')
+which contains the information associated with axes 3 and 2, in that
+order, from the original Frame (``frame1''). The original Frame is not
+altered by this process. Beware, however, that the axis information
+may still be shared by both Frames, so if you wish to alter either of
+them independently you may first need to use \htmlref{astCopy}{astCopy}
+(\secref{ss:copyingobjects}) to make an independent copy.
+
+In addition to the new Frame pointer, \htmlref{astPickAxes}{astPickAxes} will also return a
+pointer to a new \htmlref{Mapping}{Mapping} \emph{via} its fourth argument (you may supply a
+NULL pointer as an argument if you do not want this Mapping).  This
+Mapping will inter-relate the two Frames. By this we mean that its
+forward transformation will convert coordinates originally in the
+coordinate system represented by ``frame1'' into that represented by
+``frame2'', while its inverse transformation will convert in the
+opposite direction. In this particular case, the Mapping would be a
+\htmlref{PermMap}{PermMap} (\secref{ss:permmapexample}) and would implement the following
+transformations:
+
+\begin{terminalv}
+Forward:
+   (1, 2, 3) --> (3, 2)
+   (2, 4, 6) --> (6, 4)
+   (3, 6, 9) --> (9, 6)
+   (4, 8, 12) --> (12, 8)
+   (5, 10, 15) --> (15, 10)
+
+Inverse:
+   (3, 2) --> (<bad>, 2, 3)
+   (6, 4) --> (<bad>, 4, 6)
+   (9, 6) --> (<bad>, 6, 9)
+   (12, 8) --> (<bad>, 8, 12)
+   (15, 10) --> (<bad>, 10, 15)
+\end{terminalv}
+
+This is our first introduction to the idea of inter-relating pairs of
+Frames \emph{via} a Mapping, but this will assume a central role later on.
+
+Note that when using astPickAxes, it is also possible to request more
+axes than there were in the original Frame. This will involve
+selecting axes from the original Frame that do not exist. To do this,
+the corresponding axis number (in the ``pick'' array) should be set to
+zero and the effect is to introduce an additional new axis which is
+not derived from the original Frame. This axis will have default
+values for all its attributes. You will need to do this because
+astPickAxes does not allow you to select any of the original axes more
+than once.\footnote{It will probably not be obvious why this
+restriction is necessary, but consider creating a Frame with one
+longitude axis and two latitude axes. Which latitude axis should be
+associated with the longitude axis?}
+
+\subsection{\label{ss:distanceandoffset}Calculating Distances, Angles and Offsets}
+Some complementary
+functions
+are provided for use with Frames to allow you to perform geometric
+operations without needing to know the nature of the coordinate system
+represented by the \htmlref{Frame}{Frame}.
+
+Functions
+can be used to find the distance between two points, and to offset a
+specified distance along a line joining two points, \emph{etc.} In essence,
+these define the metric of the coordinate space which the Frame represents. In
+the case of a basic Frame, this is a Cartesian metric.
+
+The first of these functions, \htmlref{astDistance}{astDistance}, returns a double distance
+value when supplied with the Frame coordinates of two points. For
+example:
+
+\small
+\begin{terminalv}
+double dist;
+double point1[ 2 ] = { 0.0, 0.0 };
+double point2[ 2 ] = { 1.0, 1.0 };
+
+...
+
+dist = astDistance( frame, point1, point2 );
+\end{terminalv}
+\normalsize
+
+This calculates the distance between the origin (0,0) and a point at
+position (1,1). In this case, the result, as you would expect, is
+$\surd{2}$. However, this is only true for the Cartesian coordinate
+system which a basic Frame represents. In general, astDistance will
+calculate the geodesic distance between the two points, so that with a
+more specialised Frame (such as a \htmlref{SkyFrame}{SkyFrame}, representing the celestial
+sphere) a great-circle distance might be returned.
+
+The \htmlref{astOffset}{astOffset} function is really the inverse of astDistance. Given two
+points in a Frame, it calculates the coordinates of a third point
+which is offset a specified distance away from the first point along
+the geodesic joining it to the second one. For example:
+
+\small
+\begin{terminalv}
+double point1[ 2 ] = { 0.0, 0.0 };
+double point2[ 2 ] = { 1.0, 1.0 };
+double point3[ 2 ];
+
+...
+
+astOffset( frame, point1. point2, 0.5, point3 );
+\end{terminalv}
+\normalsize
+
+This would fill the ``point3'' array with the coordinates of a point
+which is offset 0.5 units away from the origin (0,0) in the direction
+of the position (1,1). Again, this is a simple result in a Cartesian
+Frame, as varying the offset will trace out a straight line. On the
+celestial sphere, however (\emph{e.g.}\ using a SkyFrame), it would
+trace out a great circle.
+
+The functions \htmlref{astAxDistance}{astAxDistance} and \htmlref{astAxOffset}{astAxOffset} are similar to astDistance
+and astOffset, except that the curves which they use as ``straight
+lines'' are not geodesics, but curves parallel to a specified axis\footnote
+{For instance, a line of constant Declination is not a geodesic}. One
+reason for using these functions is to deal with the cyclic ambiguity of
+longitude and latitude axes.
+
+The \htmlref{astOffset2}{astOffset2} function is similar to astOffset, but instead of using the
+geodesic which passes through two positions, it uses the geodesic which
+passes at a given position angle through the starting position.
+
+Position angles are always measured from the positive direction of the
+second Frame axis to the required line, with positive angles being in the
+same sense as rotation from the positive direction of the second axis to
+the positive direction of the first Frame axis. This definition applies
+to all classes of Frame, including SkyFrame. The default ordering of axes
+in a SkyFrame makes the second axis equivalent to north, and so the
+definition of position angle given above corresponds to the normal
+astronomical usage, ``from north, through east''. However, it should be
+remembered that it is possible to permute the axes of a SkyFrame (or
+indeed any Frame), so that north becomes axis 1. In this case, an AST
+``position angle'' would be the angle ``from east, through north''.
+Always take the axis ordering into account when deriving an astronomical
+position angle from an AST position angle.
+
+Within a Cartesian coordinate system, the position angle of a geodesic
+(\emph{i.e.}\ a straight line) is constant along its entire length, but
+this is not necessarily true of other coordinate systems. Within a
+spherical coordinate system, for instance, the position angle of a geodesic
+will vary along its length (except for the special cases of a meridian and
+the equator). In addition to returning the required offset position, the
+astOffset2 function
+returns the position angle of the geodesic at the
+offset position. This is useful if you want to trace out a path which
+involves turning through specified angles. For instance, tracing out a
+rectangle in which each side is a geodesic involves turning through 90
+degrees at the corners. To do this, use astOffset2 to calculate the
+position of each corner, and then add (or subtract) 90 degrees from the
+position angle returned by astOffset2.
+
+The \htmlref{astAngle}{astAngle} function
+calculates the angle subtended by two points, at a third point.
+If used with a 2-dimensional Frame the returned angle
+is signed to indicate the sense of rotation (clockwise or anti-clockwise)
+in taking the ``shortest route'' from the first point to the second.
+If the Frame has more than 2 axes, the result is un-signed and is always
+in the range zero to $\pi$.
+
+The \htmlref{astAxAngle}{astAxAngle} function is similar to astAngle,
+but the ``reference direction'', from which angles are measured, is
+a specified axis.
+
+The \htmlref{astResolve}{astResolve} function
+resolves a given displacement within a Frame into two components, parallel and
+perpendicular to a given reference direction.
+
+The displacement is specified by two positions within the Frame; the
+starting and ending positions. The reference direction is defined by the
+geodesic curve passing through the starting position and a third specified
+position. The lengths of the two components are returned, together with
+the position on the reference geodesic which is closest to the third
+supplied point.
+
+\subsection{\label{ss:framedomains}The Domain Attribute}
+
+The \htmlref{Domain}{Domain} attribute is one of the most important properties of a
+\htmlref{Frame}{Frame}, although the concept it expresses can sometimes seem a little
+subtle.  We will introduce it here, but its true value will probably
+not become apparent until later (\secref{ss:framesetconverting}).
+
+To understand the need for the Domain attribute, consider using
+different Frames to represent the following different coordinate
+systems associated with a CCD image:
+
+\begin{enumerate}
+\item A coordinate system based on pixel numbers.
+
+\item Positions on the CCD chip, measured in $\mu$m.
+
+\item Positions in the focal plane of the telescope, measured in mm.
+
+\item A celestial coordinate system, measured in radians.
+\end{enumerate}
+
+If we had two such CCD images, we might legitimately want to align
+them pixel-for-pixel (\emph{i.e.}\ using the coordinate system based
+on pixel numbers) in order to, say, divide by a flat-field exposure.
+We might similarly consider aligning them using any of the other
+coordinate systems so as to achieve different results. For example, we
+might consider merging separate images from a CCD mosaic by using
+focal plane positions.
+
+It would obviously not be legitimate, however, to directly compare
+positions in one image measured in pixels with positions in the other
+measured in mm, nor to equate chip positions in $\mu$m with sky
+coordinates in radians. If we wanted to inter-compare these
+coordinates, we would need to do it indirectly, using other
+information based on the experimental set-up. For instance, we might
+need to know the size of the pixels expressed in mm and the
+orientation of the CCD chip in the focal plane.
+
+Note that it is not simply the difference in physical units which
+prevents certain coordinates from being directly inter-compared
+(because the appropriate unit scaling factors could be included
+without any additional information). Neither is it the fact that
+different coordinate systems are in use (because we could legitimately
+inter-compare two different celestial coordinate systems without any
+extra information).  Instead, it is the different nature of the
+coordinate spaces to which these coordinate systems have been applied.
+
+We normally express this by saying that the coordinate systems apply
+to different \emph{physical domains}. Although we may establish
+\emph{ad hoc} relationships between coordinates in different physical
+domains, they are not intrinsically related to each other and we need
+to supply extra information before we can convert coordinates between
+them.
+
+In AST, the role of the (character string) Domain attribute is to
+assign Frames to their respective physical domains. The way it
+operates is as follows:
+
+\begin{itemize}
+\item Coordinate systems which apply to the same physical domain
+(\emph{i.e.}\ whose Frames have the same Domain value) can be directly
+inter-compared.
+
+If the domain has several coordinate systems associated with it
+(\emph{e.g.}\ the celestial sphere), then a coordinate conversion may
+be involved. Otherwise, coordinate values may simply be equated.
+
+\item Coordinate systems which apply to different physical domains
+(\emph{i.e.}\ whose Frames have different Domain values) cannot be
+directly inter-compared.
+
+If any relationship does exist between such coordinate systems---and
+it need not---then additional information must be supplied in order to
+establish the relationship between them in any particular case. We
+will see later (\secref{ss:framesets}) how to establish such
+relationships between Frames in different domains.
+\end{itemize}
+
+With the basic Frames we are considering here, each physical domain only
+has a single (Cartesian) coordinate system associated with it, so that if
+two such Frames have the same Domain value, their coordinate systems will
+be identical and may simply be equated. With more specialised Frames,
+however, more than one coordinate system may apply to each domain. In
+such cases, a coordinate conversion may need to be performed.
+
+When a basic Frame is created, its Domain attribute defaults to an
+empty string. This means that all such Frames belong to the same
+(null) domain by default and therefore describe the same unspecified
+physical coordinate space. In order to assign a Frame to a different
+domain, you simply need to set its Domain value. This is normally most
+conveniently done when it is created, as follows:
+
+\small
+\begin{terminalv}
+frame1 = astFrame( 2, "Domain=CCD_CHIP,"
+                      "Unit(1)=micron,"
+                      "Unit(2)=micron" );
+frame2 = astFrame( 2, "Domain=FOCAL_PLANE,"
+                      "Unit(1)=mm,"
+                      "Unit(2)=mm" );
+\end{terminalv}
+\normalsize
+
+Here, we have created two Frames in different physical
+domains. Although their coordinate values all have units of length,
+they cannot be directly inter-compared (because their axes may be
+rotated with respect to each other, for instance).
+
+All Domain values are automatically converted to upper case and white
+space is removed, but there are no other restrictions on the names you
+may use to label different physical domains. From a practical point of
+view, however, it is worth following a few conventions
+(\secref{ss:domainconventions}).
+
+\subsection{\label{ss:domainconventions}Conventions for Domain Names}
+
+When choosing a value for the \htmlref{Domain}{Domain} attribute of a \htmlref{Frame}{Frame}, it
+obviously makes sense to avoid generic names which might clash with
+those used for similar (but subtly different!) purposes by other
+programmers. If you are developing software for an instrument, for
+example, and want to identify an instrumental coordinate system, then
+it is sensible to add a distinguishing prefix. For instance, you might
+use $<$INST$>$\_FOCAL\_PLANE, where $<$INST$>$ (\emph{e.g.}\ an
+acronym) identifies your instrument.
+
+For some purposes, however, a standard choice of Domain name is
+desirable so that different items of software can communicate. For
+this purpose, the following Domain names are reserved by AST and the
+use recommended below should be carefully observed:
+
+\begin{quote}
+\begin{description}
+\item[GRAPHICS]\mbox{}\\
+Identifies the coordinate space used by an underlying computer
+graphics system to specify plotting operations. Typically, when
+performing graphical operations, AST is used to define additional
+coordinate systems which are related to these ``native'' graphical
+coordinates.  Plotting may be carried out in any of these coordinate
+systems, but the GRAPHICS domain identifies the native coordinates
+through which AST communicates with the underlying graphics system.
+
+\item[GRID]\mbox{}\\
+Identifies the instantaneous \emph{data grid} used to store and handle
+data, together with an associated coordinate system. In this
+coordinate system, the first element stored in an array of data always
+has a coordinate value of unity at its centre and all elements have
+unit extent. This applies to all dimensions.
+
+If data are copied or transformed to a new data grid (by whatever
+means), or a subset of the original grid is extracted, then the same
+rules apply to the copy or subset. Its first element therefore has
+GRID coordinate values of unity at its centre. Note that this means
+that GRID coordinates remain attached to the first element of the data
+grid and not to its data content (\emph{e.g.}\ the features in an
+image).
+
+\item[PIXEL]\mbox{}\\
+Identifies an array of pixels and an associated \emph{pixel-based}
+coordinate system which is related to the GRID coordinate system
+(above) simply by a shift of origin along each axis. This shift may be
+integral, fractional, positive, negative or zero. The data elements
+retain their unit extent along each axis.
+
+Because the amount of shift is unspecified, the PIXEL domain is
+distinct from the GRID domain. The relationship between them contains
+a degree of uncertainty, such as typically arises from the different
+conventions used by different software systems. For instance, in some
+software the first pixel is regarded as being centred at (1,1), while
+in other software it is at (0.5,0.5). In addition, some software
+packages implement a ``pixel origin'' which allows pixel coordinates
+to start at an arbitrary value.
+
+The GRID domain (which corresponds with the pixel-numbering convention
+used by FITS) is a special case of the PIXEL domain and avoids this
+uncertainty. In general, additional information is required in order
+to convert from one to the other.
+
+\item[SKY]\mbox{}\\
+Identifies the domain which contains all equivalent celestial
+coordinate systems. Because these are represented in AST by SkyFrames
+(\secref{ss:skyframes}), it should be no surprise that the default
+Domain value for a \htmlref{SkyFrame}{SkyFrame} is SKY. Since there is only one sky, you
+probably won't need to change this very often.
+
+\item[SPECTRUM]\mbox{}\\
+Identifies the domain used to describe positions within an
+electro-magnetic spectrum. The AST \htmlref{SpecFrame}{SpecFrame} (\secref{ss:specframes})
+class describes positions within this domain, allowing a wide range of
+different coordinate systems to be used (frequency, wavelength,
+\emph{etc}). The default Domain value for a SpecFrame is SPECTRUM.
+
+\item[TIME]\mbox{}\\
+Identifies the domain used to describe moments in time. The AST \htmlref{TimeFrame}{TimeFrame}
+class describes positions within this domain, allowing a wide range of
+different coordinate systems and timescales to be used. The default Domain
+value for a TimeFrame is TIME.
+
+\end{description}
+\end{quote}
+
+Although we have drawn a necessary distinction here between the GRID
+and PIXEL domains, we will continue to refer in general terms to image
+``pixels'' and ``pixel coordinates'' whenever this distinction is not
+important. This should not be taken to imply that the GRID convention
+for numbering pixels is excluded---in fact, it is usually to be
+preferred (at the level of data handling being discussed in this
+document) and we recommend it.
+
+\subsection{\label{ss:frameunits}The Unit Attribute}
+Each axis of a \htmlref{Frame}{Frame} has a Unit attribute which holds the physical units used
+to describe positions on the axis. The index of the axis to which the
+attribute refers should normally be placed in parentheses following the
+attribute name (``Unit(2)'' for instance). However, if the Frame has only
+a single axis, then the axis index can be omitted.
+
+In versions of AST prior to version 2.0, the Unit attribute was nothing
+more than a descriptive string intended purely for human readers---no
+part of the AST system used the Unit string for any purpose (other than
+inclusion in axis labels produced by the \htmlref{Plot}{Plot} class). In particular, no
+account was taken of the Unit attribute when finding the \htmlref{Mapping}{Mapping} between
+two Frames. Thus if the conversion between a pair of 1-dimensional Frames
+representing velocity was found (using
+\htmlref{astConvert}{astConvert}
+) the returned Mapping would always be a \htmlref{UnitMap}{UnitMap}, even if the Unit
+attributes of the two Frames were ``km/h'' and ``m/s''. This behaviour is
+referred to below as a \emph{passive} Unit attribute.
+
+As of AST version 2.0, a facility exists which allows the Unit attribute
+to be \emph{active}; that is, differences in the
+Unit attribute may be taken into account when finding the Mapping between
+two Frames. In order to minimise the risk of breaking older software, the
+\emph{default} behaviour of simple Frames and SkyFrames is unchanged from
+previous versions (\emph{i.e.} they have passive Unit attributes). However,
+the new
+functions \htmlref{astSetActiveUnit}{astSetActiveUnit} and \htmlref{astGetActiveUnit}{astGetActiveUnit}
+allow this default behaviour to be changed. The \htmlref{SpecFrame}{SpecFrame} and \htmlref{TimeFrame}{TimeFrame}
+classes \emph{always} have an active Unit attribute (attempts to change this
+are ignored).
+
+For instance, consider the above example of two 1-dimensional Frames
+describing velocity. These Frames can be created as follows:
+
+\small
+\begin{terminalv}
+AstFrame *frame1, *frame2;
+frame1 = astFrame( 1, "Domain=VELOCITY,Unit=km/h" );
+frame2 = astFrame( 1, "Domain=VELOCITY,Unit=m/s" );
+\end{terminalv}
+\normalsize
+
+By default, these Frames have passive Unit attributes, and so an attempt
+to find a Mapping between them would ignore the difference in their Unit
+attributes and return a unit Mapping. To avoid this, we indicate that we
+want these Frames to have \emph{active} Unit attributes, as follows:
+
+\small
+\begin{terminalv}
+astSetActiveUnit( frame1, 1 );
+astSetActiveUnit( frame2, 1 );
+\end{terminalv}
+\normalsize
+
+If we then find the Mapping between them as follows:
+
+\small
+\begin{terminalv}
+AstFrameSet *cvt;
+...
+cvt = astConvert( frame1, frame2, "" );
+\end{terminalv}
+\normalsize
+
+the Mapping contained within the \htmlref{FrameSet}{FrameSet} returned by
+astConvert
+will be a one-dimensional \htmlref{ZoomMap}{ZoomMap} which simply scales its input (a
+velocity in $km/h$) by a factor of 0.278 to create its output (a velocity
+in $m/s$).
+
+In fact we need not have set the Unit attribute active in ``frame1''
+since the behaviour of astConvert is determined by its ``to'' Frame
+(the second Frame parameter).
+
+\subsubsection{\label{ss:unitsyntax}The Syntax for Unit Strings}
+Conversion between units systems relies on the use of a specific syntax
+for the Unit attribute. If the value of the Unit attribute does not
+conform to this syntax, then an error will be reported if an attempt is
+made to use it to determine an inter-unit \htmlref{Mapping}{Mapping} (this will never happen
+if the Unit attribute is \emph{passive}).
+
+The adopted syntax is that described in FITS-WCS paper I "Representation
+of World Coordinate in FITS" by Greisen \& Calabretta. We distinguish
+here between ``basic'' units and ``derived'' units: derived units are
+defined in terms of other units (either derived or basic), whereas basic
+units have no such definitions. Derived units may be represented by their
+own \emph{symbol} (\emph{e.g.} ``Jy''---the Jansky) or by a
+\emph{mathematical expression} which combines other symbols and constants
+to form a definition of the unit (\emph{e.g.} ``km/s''---kilometres per
+second). Unit symbols may be prefixed by a string representing a standard
+multiple or sub-multiple.
+
+In addition to the unit symbols listed in FITS-WCS Paper I, any other
+arbitrary unit symbol may be used, with the proviso that it will not be
+possible to convert between Frames using such units. The exception to
+this is if both Frames refer to the same unknown unit string. For instance,
+an axis with unknown unit symbol "flop" \emph{could} be converted to an axis
+with  unit "Mflop" (Mega-flop).
+
+Unit symbols (optionally prefixed with a multiple or sub-multiple) can be
+combined together using a limited range of mathematical operators and
+functions, to produce new units. Such expressions may also contain
+parentheses and numerical constants (these may optionally use
+``scientific'' notation including an ``E'' character to represent the
+power of 10).
+
+The following tables list the symbols for the basic and derived units which
+may be included in a units string, the standard prefixes for multiples
+and sub-multiples, and the strings which may be used to represent
+mathematical operators and functions.
+
+\begin{table}[htbp]
+\begin{center}
+\begin{tabular}{|l|l|l|}
+\hline
+\multicolumn{3}{|c|}{{\large Basic units}} \\ \hline
+\multicolumn{1}{|c|}{Quantity} & \multicolumn{1}{|c|}{Symbol} &
+\multicolumn{1}{c|}{\htmlref{Full}{Full} Name} \\ \hline
+length              & m   & metre \\
+mass                & g   & gram \\
+time                & s   & second \\
+plane angle         & rad & radian \\
+solid angle         & sr  & steradian \\
+temperature         & K   & Kelvin \\
+electric current    & A   & Ampere \\
+amount of substance & mol & mole \\
+luminous intensity  & cd  & candela \\
+\hline
+\end{tabular}
+\end{center}
+\end{table}
+
+\begin{table}[htbp]
+\begin{center}
+\begin{small}
+\begin{tabular}{|l|l|l|l|}
+\hline
+\multicolumn{4}{|c|}{{\large Derived units}} \\ \hline
+\multicolumn{1}{|c|}{Quantity} & \multicolumn{1}{|c|}{Symbol} &
+\multicolumn{1}{c|}{Full Name} & \multicolumn{1}{c|}{Definition} \\ \hline
+area & barn & barn & 1.0E-28 m**2 \\
+area & pix & pixel & \\
+area & pixel & pixel & \\
+electric capacitance & F & Farad & C/V \\
+electric charge & C & Coulomb & A s \\
+electric conductance & S & Siemens & A/V \\
+electric potential & V & Volt & J/C \\
+electric resistance & Ohm & Ohm & V/A \\
+energy & J & Joule & N m \\
+energy & Ry & Rydberg & 13.605692 eV \\
+energy & eV & electron-Volt & 1.60217733E-19 J \\
+energy & erg & erg & 1.0E-7 J \\
+events & count & count & \\
+events & ct & count & \\
+events & ph & photon & \\
+events & photon & photon & \\
+flux density & Jy & Jansky & 1.0E-26 W /m**2 /Hz \\
+flux density & R & Rayleigh & 1.0E10/(4*PI) photon.m**-2 /s/sr \\
+flux density & mag & magnitude & \\
+force & N & Newton & kg m/s**2 \\
+frequency & Hz & Hertz & 1/s \\
+illuminance & lx & lux & lm/m**2 \\
+inductance & H & Henry & Wb/A \\
+length & AU & astronomical unit & 1.49598E11 m \\
+length & Angstrom & Angstrom & 1.0E-10 m \\
+length & lyr & light year & 9.460730E15 m \\
+length & pc & parsec & 3.0867E16 m \\
+length & solRad & solar radius & 6.9599E8 m \\
+luminosity & solLum & solar luminosity & 3.8268E26 W \\
+luminous flux & lm & lumen & cd sr \\
+magnetic field & G & Gauss & 1.0E-4 T \\
+magnetic flux & Wb & Weber & V s \\
+mass & solMass & solar mass & 1.9891E30 kg \\
+mass & u & unified atomic mass unit & 1.6605387E-27 kg \\
+magnetic flux density & T & Tesla & Wb/m**2 \\
+plane angle  & arcmin & arc-minute & 1/60 deg \\
+plane angle  & arcsec & arc-second & 1/3600 deg \\
+plane angle  & mas & milli-arcsecond & 1/3600000 deg \\
+plane angle & deg & degree & pi/180 rad \\
+power & W & Watt & J/s \\
+pressure, stress & Pa & Pascal & N/m**2 \\
+time  & a & year & 31557600 s \\
+time  & d & day & 86400 s \\
+time  & h & hour & 3600 s \\
+time  & yr & year & 31557600 s \\
+time  & min & minute & 60 s \\
+      & D & Debye & 1.0E-29/3 C.m \\
+\hline
+\end{tabular}
+\end{small}
+\end{center}
+\end{table}
+
+\begin{table}[htbp]
+\begin{center}
+\begin{tabular}{|lll|lll|}
+\hline
+\multicolumn{6}{|c|}{{\large Prefixes for multiples \&
+sub-multiples}} \\ \hline
+\multicolumn{1}{|c}{Sub-multiple} & \multicolumn{1}{c}{Name} &
+\multicolumn{1}{c|}{Prefix} &
+\multicolumn{1}{|c}{Sub-multiple} & \multicolumn{1}{c}{Name} &
+\multicolumn{1}{c|}{Prefix} \\ \hline
+$10^{-1}$ & deci & d & $10$ & deca & da \\
+$10^{-2}$ & centi & c & $10^{2}$ & hecto & h \\
+$10^{-3}$ & milli & m & $10^{3}$ & kilo & k \\
+$10^{-6}$ & micro & u & $10^{6}$ & mega & M \\
+$10^{-9}$ & nano & n & $10^{9}$ & giga & G \\
+$10^{-12}$ & pico & p & $10^{12}$ & tera & T \\
+$10^{-15}$ & femto & f & $10^{15}$ & peta & P \\
+$10^{-18}$ & atto & a & $10^{18}$ & exa & E \\
+$10^{-21}$ & zepto & z & $10^{21}$ & zetta & Z \\
+$10^{-24}$ & yocto & y & $10^{24}$ & yotta & Y \\
+\hline
+\end{tabular}
+\end{center}
+\end{table}
+
+\begin{table}[htbp]
+\begin{center}
+\begin{tabular}{|l|l|}
+\hline
+\multicolumn{2}{|c|}{{\large Mathematical operators \& functions}} \\
+\hline
+\multicolumn{1}{|c|}{String} & \multicolumn{1}{|c|}{Meaning} \\ \hline
+sym1 sym2           & multiplication (a space) \\
+sym1*sym2           & multiplication (an asterisk) \\
+sym1.sym2           & multiplication (a dot) \\
+sym1/sym2           & division \\
+sym1**y             & exponentiation ($y$ must be a numerical constant)\\
+sym1\verb+^+y       & exponentiation ($y$ must be a numerical constant)\\
+log(sym1)           & common logarithm \\
+ln(sym1)            & natural logarithm \\
+exp(sym1)           & exponential \\
+sqrt(sym1)          & square root \\
+\hline
+\end{tabular}
+\end{center}
+\end{table}
+
+\subsubsection{Side-effects of Changing the Unit attribute}
+If an \htmlref{Axis}{Axis} has an active Unit attribute, changing its value (either by
+setting a new value or by clearing it so that the default value is
+re-instated) may cause the Label and Symbol attributes to be changed
+accordingly. For instance, if an Axis has Unit, Label and Symbol of ``Hz'',
+``Frequency'' and ``nu'', then changing its Unit attribute to ``log(Hz)''
+will cause AST to change its Label and Symbol to ``log(Frequency)'' and
+``Log(nu)''. These changes are only made if the Unit attribute is active,
+and a \htmlref{Mapping}{Mapping} can be found from the old units to the new units. On the other
+ hand, changing the Unit from ``Hz'' to ``MHz'' would not cause any change
+to the Label or Symbol attributes.
+
+\cleardoublepage
+\section{\label{ss:skyframes}Celestial Coordinate Systems (SkyFrames)}
+
+A \htmlref{Frame}{Frame} which is specialised for representing coordinate systems on
+the celestial sphere is obviously of great importance in
+astronomy. The \htmlref{SkyFrame}{SkyFrame} is such a Frame. In this section we examine
+the additional properties and behaviour of a SkyFrame that distinguish
+it from a basic Frame (\secref{ss:frames}).
+
+\subsection{The SkyFrame Model}
+
+A \htmlref{SkyFrame}{SkyFrame} is, of course, a \htmlref{Frame}{Frame} (\secref{ss:frames}) and also a
+\htmlref{Mapping}{Mapping} (\secref{ss:mappings}), so it inherits all the properties and
+behaviour of these two ancestral classes.  When used as a Mapping, a
+SkyFrame implements a unit transformation, exactly like a basic Frame
+(\secref{ss:frameasmapping}) or a \htmlref{UnitMap}{UnitMap}, so this aspect of its
+behaviour is not of great importance.
+
+When used as a Frame, however, a SkyFrame represents a 2-dimensional
+\emph{spherical} coordinate system, in which the shortest distance
+between two points is a great circle.  A SkyFrame therefore always has
+exactly two axes which represent the longitude and latitude of a
+coordinate system residing on the celestial sphere. Many such
+coordinate systems can be represented by a SkyFrame, as we will see
+shortly.
+
+A SkyFrame can represent any of the commonly used celestial coordinate
+systems. Optionally, the origin of the longitude/latitude system can be
+moved to any specified point in the standard celestial system, allowing
+a SkyFrame to represent offsets from a specified sky position.
+
+When it is first created, a SkyFrame's axes are always in the order
+(longitude,~latitude) but this can be changed, if required, by using the
+\htmlref{astPermAxes}{astPermAxes} function (\secref{ss:permutingaxes}). The order of the axes
+can be determined at any time using the \htmlref{LatAxis}{LatAxis} and \htmlref{LonAxis}{LonAxis} attributes. A
+SkyFrame's coordinate values are always stored as angles in (double
+precision) radians, regardless of the setting of the Unit attribute
+\footnote{The units used for the internal floating-point representation of an
+axis value can be determined by examining the InternalUnit attribute of
+the Frame. For most Frames, the Unit and InternalUnit attributes will be
+equal, but InternalUnit is always set to ``\texttt{rad}'' for SkyFrames.}.
+
+\subsection{Creating a SkyFrame}
+
+The \htmlref{SkyFrame}{SkyFrame} constructor function is particularly simple and a
+SkyFrame with default attributes is created as follows:
+
+\small
+\begin{terminalv}
+#include "ast.h"
+AstSkyFrame *skyframe;
+
+...
+
+skyframe = astSkyFrame( "" );
+\end{terminalv}
+\normalsize
+
+Such a SkyFrame would represent the default celestial coordinate
+system which, at present, is the ICRS system (the default was "FK5(J2000)"
+in versions of AST prior to 3.0).
+
+\subsection{Specifying a Particular Celestial Coordinate System}
+
+For many purposes, the ICRS coordinate system is perfectly
+adequate. In order to support conversion between a variety of
+celestial coordinate systems, however, you can create SkyFrames that
+represent any of these.
+
+Selection of a particular coordinate system is performed simply by
+setting a value for the \htmlref{SkyFrame}{SkyFrame}'s (character string) \htmlref{System}{System}
+attribute. This setting is most conveniently done when the SkyFrame is
+created. For example, a SkyFrame representing the old FK4~(B1950.0)
+coordinate system would be created by:
+
+\small
+\begin{terminalv}
+skyframe = astSkyFrame( "System=FK4" );
+\end{terminalv}
+\normalsize
+
+Note that specifying ``System$=$FK4'' also changes the associated
+equinox (from J2000.0 to B1950.0). This is because the default value
+of the SkyFrame's \htmlref{Equinox}{Equinox} attribute (\secref{ss:equinoxitem}) depends
+on the System attribute setting.
+
+You may change the System value at any time, although this is not
+usually needed.  The values supported are set out in the attribute's
+description in \appref{ss:attributedescriptions} and include a variety
+of equatorial coordinate systems, together with ecliptic and galactic
+coordinates.
+
+General spherical coordinates are supported by specifying
+``System$=$unknown''. You should note, though, that no \htmlref{Mapping}{Mapping} can be
+created to convert between ``unknown'' coordinates and any of the other
+celestial coordinate systems (see \secref{ss:introducingconversion} ).
+
+\subsection{Attributes which Qualify Celestial Coordinate Systems}
+
+Many celestial coordinate systems have some additional free parameters
+which serve to identify a particular coordinate system from amongst a
+broader class of related coordinate systems. For example, the
+FK5~(J2010.0) system is distinguished from the FK5~(J2000.0)
+system by a different equinox---and the coordinates of a fixed
+astronomical source would have different values when expressed in
+these two systems.
+
+In AST, these free parameters are represented by additional \htmlref{SkyFrame}{SkyFrame}
+attributes, each of which has a default appropriate to
+(\emph{i.e.}\ defined by) the setting of the main \htmlref{System}{System}
+attribute. Each of these \emph{qualifying attributes} may, however, be
+assigned an explicit value so as to select a particular coordinate
+system. Note, it is usually best to assign explicit
+values whenever possible rather than relying on defaults. Attribute
+should only be left at their default value if you ``don't care'' what
+value is used. In certain circumstances (particularly, when aligning two
+Frames), a default value for an attribute may be replaced by the value
+from another similar \htmlref{Frame}{Frame}. Such value replacement can be prevented by
+assigning an explicit value to the attribute, rather than simply relying on
+the default.
+
+
+The main SkyFrame attributes which qualify the System attribute are:
+
+\begin{quote}
+\begin{description}
+
+\item[\label{ss:epochitem}\htmlref{Epoch}{Epoch}]\mbox{}\\
+This attribute is inherited from the Frame class. It gives the moment in
+time when the coordinates are correct for the astronomical source
+under study (usually the date of observation).
+
+\item[\label{ss:equinoxitem}\htmlref{Equinox}{Equinox}]\mbox{}\\
+This value is used to qualify celestial coordinate systems that are
+notionally based on the Earth's equator and/or the ecliptic (the plane
+of the Earth's orbit around the Sun). The position of either of these
+planes is difficult to specify precisely, so in practice a model
+\emph{mean} equator and/or ecliptic are used instead. These, together
+with the point on the sky that defines the coordinate origin (termed
+the \emph{mean equinox}) move with time according to some model which
+smoothes out the more rapid fluctuations. The SkyFrame class supports
+both the old FK4 model and the newer FK5 one.
+
+Coordinates expressed in any of these systems vary with time due to
+movement (by definition) of the coordinate system itself, and must
+therefore be qualified by a moment in time (the \emph{epoch of the mean
+equinox}, or ``equinox'' for short) which specifies the position of
+the model coordinate system on the sky. This is the role of the
+Equinox attribute.
+
+Note that it is quite valid and common to relate the position of a
+source to an equinox other than the date of observation. Usually a
+standard equinox such as J2000.0 is used, meaning that the coordinates
+are referred to axes defined by where the model mean equator and
+ecliptic would lie on the sky at the Julian epoch J2000.0.
+\end{description}
+\end{quote}
+
+For further details of these attributes you should consult their
+descriptions in \appref{ss:attributedescriptions} and for details of
+the System settings for which they are relevant, see the description
+of the System attribute (also in \appref{ss:attributedescriptions}).
+For the interested reader, an excellent overview of celestial
+coordinate systems can also be found in the documentation for the
+SLALIB library (\xref{SUN/67}{sun67}{}).
+
+The value of these qualifying attributes is most conveniently set at
+the same time as the System value, \emph{e.g.}\ when a SkyFrame is
+created. For instance:
+
+\small
+\begin{terminalv}
+skyframe = astSkyFrame( "System=Ecliptic, Equinox=J2005.5" );
+\end{terminalv}
+\normalsize
+
+would create a SkyFrame representing an ecliptic coordinate system
+referred to the mean equinox and ecliptic of Julian epoch J2005.5.
+
+Note that it does no harm to assign values to qualifying attributes
+which are not relevant to the main System value. Any such values are
+stored, but are not used unless the System value is later set so that
+they become relevant.
+
+\subsection{Using Default SkyFrame Attributes}
+
+The default values supplied for many \htmlref{SkyFrame}{SkyFrame} attributes will depend
+on the value of the SkyFrame's \htmlref{System}{System} attribute. In practice, this
+means that there is usually little need to specify many of these
+attributes explicitly unless you have some special requirement. This
+can be illustrated by using \htmlref{astShow}{astShow} to examine a SkyFrame, as follows:
+
+\small
+\begin{terminalv}
+astShow( astSkyFrame( "System=FK4-NO-E, Epoch=1958" ) );
+\end{terminalv}
+\normalsize
+
+The output from this might look like the following:
+
+\begin{terminalv}
+ Begin SkyFrame         # Description of celestial coordinate system
+#   Title = "FK4 equatorial coordinates; no E-terms; mean equinox B1950.0;
+epoch B1958.0"   # Title of coordinate system
+    Naxes = 2   # Number of coordinate axes
+#   Domain = "SKY"      # Coordinate system domain
+    Epoch = 1958        # Besselian epoch of observation
+#   Lbl1 = "Right ascension"    # Label for axis 1
+#   Lbl2 = "Declination"        # Label for axis 2
+    System = "FK4-NO-E"         # Coordinate system type
+#   Uni1 = "hh:mm:ss.s"         # Units for axis 1
+#   Uni2 = "ddd:mm:ss"  # Units for axis 2
+#   Dir1 = 0    # Plot axis 1 in reverse direction
+#   Bot2 = -1.5707963267949     # Lowest legal axis value
+#   Top2 = 1.5707963267949      # Highest legal axis value
+    Ax1 =       # Axis number 1
+       Begin SkyAxis    # Celestial coordinate axis
+       End SkyAxis
+    Ax2 =       # Axis number 2
+       Begin SkyAxis    # Celestial coordinate axis
+       End SkyAxis
+ IsA Frame      # Coordinate system description
+#   Eqnox = 1950        # Besselian epoch of mean equinox
+ End SkyFrame
+\end{terminalv}
+
+Note that the defaults (indicated by the ``\verb?#?'' comment
+character at the start of the line) for attributes such as the \htmlref{Title}{Title},
+axis Labels and Format specifiers are all set to values appropriate
+for the particular equatorial coordinate system that the SkyFrame
+represents.
+
+This means, for example, that if we were to use this SkyFrame to
+format a right ascension value stored in radians using \htmlref{astFormat}{astFormat}
+(\secref{ss:formattingaxisvalues}), it would automatically result in a
+string in sexagesimal notation (such as ``12:14:35.7'') suitable for
+display.  If we changed the value of the SkyFrame's Digits attribute
+(which is inherited from the \htmlref{Frame}{Frame} class), the number of digits
+appearing would also change accordingly.
+
+These choices would be appropriate for a System value of ``FK4-NO-E'',
+but if a different System value were set, the defaults would be
+correspondingly different. For example, ecliptic longitude is
+traditionally expressed in degrees, so setting ``System=ecliptic''
+would result in coordinate values being formatted as degrees by
+default.
+
+Of course, if you do not like any of these defaults, you may always
+over-ride them by setting explicit attribute values yourself.
+
+\subsection{\label{ss:formattingskyaxisvalues}Formatting Celestial Coordinates}
+
+SkyFrames use \htmlref{astFormat}{astFormat} for formatting coordinate values in the same
+way as other Frames (\secref{ss:formattingaxisvalues}). However, they
+offer a different set of formatting options more appropriate to
+celestial coordinates.
+
+The Digits attribute of a \htmlref{SkyFrame}{SkyFrame} behaves in essentially the same way
+as for a basic \htmlref{Frame}{Frame} (\secref{ss:formattingwithdigits}), so the
+precision with which celestial coordinates are displayed can also be
+adjusted in this way. However, the range of format specifiers that can
+be given for the \htmlref{Format(axis)}{Format(axis)} attribute, and the default format
+resulting from any particular Digits value, is different.
+
+The syntax of SkyFrame format specifiers is detailed under the
+description of the Format(axis) attribute in
+\appref{ss:attributedescriptions}.  Briefly, however, it allows
+celestial coordinates to be expressed either as angles or times and to
+include one or more of the fields:
+
+\begin{quote}
+\begin{itemize}
+\item degrees or hours
+\item arc-minutes or minutes
+\item arc-seconds or seconds
+\end{itemize}
+\end{quote}
+
+with a specified number of decimal places for the final field. A range
+of field separators is also available, as the following examples show:
+
+\begin{quote}
+\begin{center}
+\begin{tabular}{|l|l|}
+\hline
+\textbf{Format Specifier} & \textbf{Example Formatted Value}\\
+\hline \hline
+{\tt{d}} & {\tt{219}}\\
+{\tt{d.3}} & {\tt{219.123}}\\
+{\tt{dm}} & {\tt{219:05}}\\
+{\tt{dm.2}} & {\tt{219:05.44}}\\
+{\tt{dms}} & {\tt{219:05:42}}\\
+{\tt{hms.1}} & {\tt{15:44:13.8}}\\
+{\tt{bdms.2}} & {\tt{219 05 42.81}}\\
+{\tt{lhms.3}} & {\tt{15h44m13.88s}}\\
+{\tt{+zlhms}} & {\tt{+06h10m44s}}\\
+{\tt{ms.1}} & {\tt{13145:42.8}}\\
+{\tt{lmst.3}} & {\tt{876m22.854s}}\\
+{\tt{s.2}} & {\tt{788742.81}}\\
+\hline
+\end{tabular}
+\end{center}
+\end{quote}
+
+Note the following key points:
+
+\begin{itemize}
+\item The required fields are specified using characters chosen from
+either ``dms'' or ``hms'' according to whether the value is to be
+formatted as an angle (in degrees) or a time (in hours).
+
+\item If no degrees or hours field is required, the distinction
+between angle and time may be made by including ``t'' to request time.
+
+\item The number of decimal places (for the final field) is indicated
+using ``\texttt{.}'' followed by an integer. An asterisk can be used in
+place of an integer, in which case the number of decimal places is
+chosen so that the total number of digits in the formatted value is equal
+to the value of the Digits attribute.
+
+\item ``b'' causes fields to be separated by blanks, while ``l''
+causes them to be separated by the appropriate letters (the default
+being a colon).
+
+\item ``z'' causes padding with leading zeros.
+
+\item ``+'' cause a plus sign to be prefixed to positive values
+(negative values always have a minus sign).
+\end{itemize}
+
+The formatting performed by a SkyFrame is also influenced by the
+\htmlref{AsTime(axis)}{AsTime(axis)} attribute, which has a boolean (integer) value for each
+SkyFrame axis.  It determines whether the default format specifier for
+an axis will present values as angles (\emph{e.g.}\ in degrees) if it
+is zero, or as times (\emph{e.g.}\ in hours) if it is non-zero.
+
+The default AsTime value depends on the celestial coordinate system
+which the SkyFrame represents which, in turn, depends on its \htmlref{System}{System}
+attribute value. For example, equatorial longitude values (right
+ascension) are normally expressed in hours, whereas ecliptic
+longitudes are normally expressed in degrees, so their default AsTime
+values will reflect this difference.
+
+The value of the AsTime attribute may be set explicitly to over-ride
+these defaults if required, with the formatting precision being
+determined by the \htmlref{Digits/Digits(axis)}{Digits/Digits(axis)} value. Alternatively, the
+Format(axis) attribute may be set explicitly to specify both the
+format and precision required. Setting an explicit Format value always
+over-rides the effects of both the Digits and AsTime attributes (unless
+the Format value does not specify the required number of decimal places,
+in which case Digits is used to determine the default number of decimal
+places)
+
+\subsection{\label{ss:unformattingskyaxisvalues}Reading Formatted Celestial Coordinates}
+
+The process of converting formatted celestial coordinates, such as
+might be produced by the \htmlref{astFormat}{astFormat} function
+(\secref{ss:formattingskyaxisvalues}), into numerical (double)
+coordinate values is performed by using \htmlref{astUnformat}{astUnformat}
+(\secref{ss:unformattingaxisvalues}) and passing it a pointer to a
+\htmlref{SkyFrame}{SkyFrame}. The use of a SkyFrame means that the range of input formats
+accepted is appropriate to positions on the sky expressed as angles
+and/or times, while the returned value is in radians.
+
+The following describes the forms of celestial coordinate which are
+supported:
+
+\begin{itemize}
+\item You may supply an optional sign, followed by between one and
+three fields representing either degrees, arc-minutes, arc-seconds or
+hours, minutes, seconds (\emph{e.g.}\ ``$-$12~42~03'').
+
+\item Each field should consist of a sequence of one or more digits,
+which may include leading zeros. At most one field may contain a
+decimal point, in which case it is taken to be the final field
+(\emph{e.g.}\ decimal degrees might be given as ``124.707'', while
+degrees and decimal arc-minutes might be given as ``$-$13~33.8'').
+
+\item The first field given may take any value, allowing angles and
+times outside the conventional ranges to be represented. However,
+subsequent fields must have values of less than 60 (\emph{e.g.}
+``720~45~31'' is valid, whereas ``11~45~61'' is not).
+
+\item Fields may be separated by white space or by ``:'' (colon), but
+the choice of separator must be used consistently throughout the
+value. Additional white space may be present around fields and
+separators (\emph{e.g.}\ ``$-$~2:~04~:~7.1'').
+
+\item The following field identification characters may be used as
+separators to replace those above (or may be appended to the final
+field), in order to identify the field to which they are appended:
+
+\begin{quote}
+\begin{tabular}{lll}
+d & -- & degrees \\
+h & -- & hours \\
+m & -- & minutes (of arc or time) \\
+s & -- & seconds (of arc or time) \\
+\texttt{'} & -- & arc-minutes \\
+\texttt{"} & -- & arc-seconds
+\end{tabular}
+\end{quote}
+
+Either lower or upper case may be used.  Fields must be given in order
+of decreasing significance
+(\emph{e.g.}\ ``$-$11D~3\texttt{'}~14.4\texttt{"}'' or ``22h14m11.2s'').
+
+\item The presence of certain field identification characters
+indicates whether the value is to be interpreted as an angle or a time
+(with 24 hours corresponding to 360 degrees), as follows:
+
+\begin{quote}
+\begin{tabular}{lll}
+d & -- & angle \\
+\texttt{'} & -- & angle \\
+\texttt{"} & -- & angle \\
+h & -- & time
+\end{tabular}
+\end{quote}
+
+Incompatible angle/time identification characters may not be mixed
+(\emph{e.g.}\ ``10h14\texttt{'}3\texttt{"}'' is not valid).  The remaining
+field identification characters and separators do not specify a
+preference for an angle or a time and may be used with either.
+
+\item If no preference for an angle or a time is expressed anywhere
+within the value, then it is interpreted as an angle if the Format
+attribute string associated with the SkyFrame axis generates an angle
+and as a time otherwise.  This ensures that values produced by
+astFormat (\secref{ss:formattingskyaxisvalues}) are correctly
+interpreted by astUnformat.
+
+\item Fields may be omitted, in which case they default to zero. The
+remaining fields may be identified by using appropriate field
+identification characters (see above) and/or by adding extra colon
+separators (e.g. ``$-$05m13s'' is equivalent to ``$-$:05:13''). If a field
+is not identified explicitly, it is assumed that adjacent fields have
+been given, after taking account of any extra separator
+characters. For example:
+
+\begin{quote}
+\begin{tabular}{lll}
+10d & -- & degrees \\
+10d12 & -- & degrees and arc-minutes \\
+11:14\texttt{"} & -- & arc-minutes and arc-seconds \\
+9h13s & -- & hours and seconds of time \\
+:45:33 & -- & minutes and seconds (of arc or time) \\
+:55: & -- & minutes (of arc or time) \\
+::13 & -- & seconds (of arc or time) \\
+$-$6::2.5 & -- & degrees/hours and seconds (of arc or time) \\
+07m14 & -- & minutes and seconds (of arc or time) \\
+$-$8:14\texttt{'} & -- & degrees and arc-minutes \\
+$-$h3:14 & -- & minutes and seconds of time \\
+h:2.1 & -- & seconds of time
+\end{tabular}
+\end{quote}
+
+\item If fields are omitted in such a way that the remaining ones
+cannot be identified uniquely (e.g. ``01:02''), then the first field
+(either given explicitly or implied by an extra leading colon
+separator) is taken to be the most significant field that astFormat
+would produce when formatting a value (using the Format attribute
+associated with the SkyFrame axis). By default, this means that the
+first field will normally be interpreted as degrees or hours. However,
+if this does not result in consistent field identification, then the
+last field (either given explicitly or implied by an extra trailing
+colon separator) is taken to to be the least significant field that
+astFormat would produce.
+
+\end{itemize}
+
+This final convention is intended to ensure that values formatted by
+astFormat which contain less than three fields will be correctly
+interpreted if read back using astUnformat, even if they do not
+contain field identification characters.  However, it also affects
+other forms of input. For example, if the \htmlref{Format(axis)}{Format(axis)} string were set
+to ``mst.1'' (producing two fields representing minutes and seconds of
+time), then formatted input would be interpreted by astUnformat as
+follows:
+
+\begin{quote}
+\begin{tabular}{lll}
+12 13 & -- & minutes and seconds \\
+12 & -- & minutes \\
+:13 & -- & seconds \\
+$-$18: & -- & minutes \\
+12.8 & -- & minutes \\
+1 2 3 & -- & hours, minutes and seconds \\
+& & \\
+4\texttt{'} & -- & arc-minutes \\
+60::\texttt{"} & -- & degrees \\
+$-$23:\texttt{"} & -- & arc-minutes \\
+$-$33h & -- & hours
+\end{tabular}
+\end{quote}
+
+(in the last four cases, explicit field identification has been given
+which overrides the implicit identification).
+
+Alternatively, if the Format(axis) string were set to ``s.3''
+(producing only an arc-seconds field), then formatted input would be
+interpreted by astUnformat as follows:
+
+\begin{quote}
+\begin{tabular}{lll}
+12.8 & -- & arc-seconds \\
+12 13 & -- & arc-minutes and arc-seconds \\
+:12 & -- & arc-seconds \\
+13: & -- & arc-minutes \\
+1 2 3 & -- & degrees, arc-minutes and arc-seconds
+\end{tabular}
+\end{quote}
+
+In general, if you are preparing formatted input data containing
+celestial coordinates and wish to omit certain fields, then you are
+advised to identify clearly those that you do provide by using the
+appropriate field identification characters and/or extra colon
+separators. This prevents you depending on the implicit field
+identification described above which, in turn, depends on an
+appropriate Format(axis) string having been set.
+
+When writing software, it is also a good idea to set the Format(axis)
+string so that data input will be as simple as possible for the
+user. Unless some special effect is desired, this normally means that
+it should contain ``d'' or ``h'' to ensure that the first field
+entered by the user will be interpreted as degrees or hours, unless
+otherwise identified. This is the normal behaviour unless an explicit
+Format(axis) value has been set to override the default.
+
+\subsection{Representing Offsets from a Specified Sky Position}
+A \htmlref{SkyFrame}{SkyFrame} can be modified so that its longitude and latitude axes are
+referred to an origin at any specified sky position. Such a coordinate
+system is referred to as an ``offset'' coordinate system. First, the \htmlref{System}{System}
+attribute should be set to represent the celestial coordinate system in
+which the origin is to be specified. Then the SkyRef attribute should be
+set to hold the coordinates of the origin within the selected celestial
+coordinate system.
+
+By default, ``north'' in the new offset coordinate system is parallel to
+north in the original celestial coordinate system. However, the direction
+of north in the offset system can be controlled by assigning a value to
+the SkyRefP attribute. This attribute should be assigned the celestial
+coordinates of a point which is on the zero longitude meridian and which
+has non-zero latitude.
+
+By default, the position given by the SkyRef attribute is used as the
+origin of the new longitude/latitude system, but an option exists to use
+it as the north pole of the system instead. This option is controlled by
+the \htmlref{SkyRefIs}{SkyRefIs} attribute. The choice of value for SkyRefIs depends on what
+sort of offset coordinate system you want. Setting SkyRefIs to
+``Origin'' (the default) produces an offset coordinate system which is
+approximately Cartesian close to the specified position. Setting SkyRefIs
+to
+``Pole'' produces an offset coordinate system which is approximately Polar
+close to the specified position.
+
+\cleardoublepage
+\section{\xlabel{ss_specframes}\label{ss:specframes}Spectral Coordinate Systems (SpecFrames)}
+
+The \htmlref{SpecFrame}{SpecFrame} is a \htmlref{Frame}{Frame} which is specialised for representing coordinate
+systems which describe a position within an electro-magnetic spectrum.
+In this section we examine the additional properties and behaviour of a
+SpecFrame that distinguish it from a basic Frame (\secref{ss:frames}).
+
+\subsection{The SpecFrame Model}
+
+As for a \htmlref{SkyFrame}{SkyFrame}, a \htmlref{SpecFrame}{SpecFrame} is a \htmlref{Frame}{Frame} (\secref{ss:frames}) and also a
+\htmlref{Mapping}{Mapping} (\secref{ss:mappings}), so it inherits all the properties and
+behaviour of these two ancestral classes.  When used as a Mapping, a
+SpecFrame implements a unit transformation, exactly like a basic Frame
+(\secref{ss:frameasmapping}) or a \htmlref{UnitMap}{UnitMap}, so this aspect of its
+behaviour is not of great importance.
+
+When used as a Frame, however, a SpecFrame represents a wide range of
+different 1-dimensional coordinate system which can be used to describe
+positions within a spectrum. The options available largely mirror those
+described in the FITS-WCS paper III \emph{Representations of spectral
+coordinates in FITS} (Greisen, Valdes, Calabretta \& Allen).
+
+\subsection{Creating a SpecFrame}
+
+The \htmlref{SpecFrame}{SpecFrame} constructor function is particularly simple and a
+SpecFrame with default attributes is created as follows:
+
+\small
+\begin{terminalv}
+#include "ast.h"
+AstSpecFrame *specframe;
+
+...
+
+specframe = astSpecFrame( "" );
+\end{terminalv}
+\normalsize
+
+Such a SpecFrame would represent the default coordinate system which is
+heliocentric wavelength in metres (i.e. wavelength corrected to take into
+account the Doppler shift caused by the velocity of the observer around the
+sun).
+
+\subsection{Specifying a Particular Spectral Coordinate System}
+
+Selection of a particular coordinate system is performed simply by
+setting a value for the \htmlref{SpecFrame}{SpecFrame}'s (character string) \htmlref{System}{System}
+attribute. This setting is most conveniently done when the SpecFrame is
+created. For example, a SpecFrame representing Energy would be created by:
+
+\small
+\begin{terminalv}
+specframe = astSpecFrame( "System=Energy" );
+\end{terminalv}
+\normalsize
+
+Note that specifying ``System$=$Energy'' also changes the associated
+Unit (from metres to Joules). This is because the default value
+of the SpecFrame's Unit attribute depends on the System attribute setting.
+
+You may change the System value at any time, although this is not
+usually needed.  The values supported are set out in the attribute's
+description in \appref{ss:attributedescriptions} and include a variety
+of velocity systems, together with frequency, wavelength, energy,
+wave-number, \emph{etc}.
+
+\subsection{Attributes which Qualify Spectral Coordinate Systems}
+
+Many spectral coordinate systems have some additional free parameters
+which serve to identify a particular coordinate system from amongst a
+broader class of related coordinate systems. For example, the
+velocity systems are all parameterised by a rest frequency---the
+frequency which defines zero velocity, and all coordinate systems
+are qualified by a `standard of rest'' which indicates the rest frame to
+which the values refer.
+
+In AST, these free parameters are represented by additional \htmlref{SpecFrame}{SpecFrame}
+attributes, each of which has a default appropriate to
+(\emph{i.e.}\ defined by) the setting of the main \htmlref{System}{System}
+attribute. Each of these \emph{qualifying attributes} may, however, be
+assigned an explicit value so as to select a particular coordinate
+system. Note, it is usually best to assign explicit
+values whenever possible rather than relying on defaults. Attribute
+should only be left at their default value if you ``don't care'' what
+value is used. In certain circumstances (particularly, when aligning two
+Frames), a default value for an attribute may be replaced by the value
+from another similar \htmlref{Frame}{Frame}. Such value replacement can be prevented by
+assigning an explicit value to the attribute, rather than simply relying on
+the default.
+
+
+The main SpecFrame attributes which qualify the System attribute are:
+
+\begin{quote}
+\begin{description}
+
+\item[\htmlref{Epoch}{Epoch}]\mbox{}\\
+This attribute is inherited from the Frame class. It gives the moment in
+time when the coordinates are correct for the astronomical source
+under study (usually the date of observation). It is needed in order to
+calculate the Doppler shift produced by the velocity of the observer
+relative to the centre of the earth, and of the earth relative to the sun.
+
+\item[\htmlref{StdOfRest}{StdOfRest}]\mbox{}\\
+This specifies the rest frame in which the coordinates are correct.
+Transforming between different standards of rest involves taking account
+of the Doppler shift introduced by the relative motion of the two
+standards of rest.
+
+\item[\htmlref{RestFreq}{RestFreq}]\mbox{}\\
+Specifies the frequency which correspond to zero velocity. When setting a
+value for this attribute, the value may be supplied as a wavelength
+(including an indication of the units being used, ``nm'' ``Angstrom'',
+\emph{etc.}), which will be automatically be converted to a frequency.
+
+\item[\htmlref{RefRA}{RefRA}]\mbox{}\\
+Specifies the RA (FK5 J2000) of the source. This is used when converting
+between standards of rest. It specifies the direction along which the
+component of the relative velocity of the two standards of rest is taken.
+
+\item[\htmlref{RefDec}{RefDec}]\mbox{}\\
+Specifies the Dec (FK5 J2000) of the source. Used in conjunction with
+REFRA.
+
+\item[\htmlref{SourceVel}{SourceVel}]\mbox{}\\
+This defines the ``source'' standard of rest. This is a rest frame which
+is moving towards the position given by RefRA and RefDec, at a velocity
+given by SourceVel. The velocity is stored internally as a heliocentric
+velocity, but can be given in any of the other supported standards of rest.
+
+\end{description}
+\end{quote}
+
+For further details of these attributes you should consult their
+descriptions in \appref{ss:attributedescriptions} and for details of
+the System settings for which they are relevant, see the description
+of the System attribute (also in \appref{ss:attributedescriptions}).
+
+Note that it does no harm to assign values to qualifying attributes
+which are not relevant to the main System value. Any such values are
+stored, but are not used unless the System value is later set so that
+they become relevant.
+
+\subsection{Using Default SpecFrame Attributes}
+
+The default values supplied for many \htmlref{SpecFrame}{SpecFrame} attributes will depend
+on the value of the SpecFrame's \htmlref{System}{System} attribute. In practice, this
+means that there is usually little need to specify many of these
+attributes explicitly unless you have some special requirement. This
+can be illustrated by using \htmlref{astShow}{astShow} to examine a SpecFrame, as follows:
+
+\small
+\begin{terminalv}
+astShow( astSpecFrame( "System=Vopt, RestFreq=250 GHz" ) );
+\end{terminalv}
+\normalsize
+
+The output from this might look like the following:
+
+\begin{terminalv}
+ Begin SpecFrame        # Description of spectral coordinate system
+#   Title = "Optical velocity, rest frequency = 250 GHz"       # Title
+of coordinate system
+    Naxes = 1   # Number of coordinate axes
+#   Domain = "SPECTRUM"         # Coordinate system domain
+#   Epoch = 2000        # Julian epoch of observation
+#   Lbl1 = "Optical velocity"  # Label for axis 1
+    System = "VOPT"     # Coordinate system type
+#   Uni1 = "km/s"       # Units for axis 1
+    Ax1 =       # Axis number 1
+       Begin Axis       # Coordinate axis
+       End Axis
+ IsA Frame      # Coordinate system description
+#   SoR = "Heliocentric"        # Standard of rest
+    RstFrq = 250000000000       # Rest frequency (Hz)
+ End SpecFrame
+\end{terminalv}
+
+Note that the defaults (indicated by the ``\verb?#?'' comment
+character at the start of the line) for attributes such as the \htmlref{Title}{Title},
+axis Labels and Unit specifiers are all set to values appropriate
+for the particular velocity system that the SpecFrame represents.
+
+These choices would be appropriate for a System value of ``Vopt'',
+but if a different System value were set, the defaults would be
+correspondingly different. For example, by default frequency is measured in
+units of GHz, not $km/s$, so setting ``System=freq''
+would change the appropriate line above from:
+
+\begin{terminalv}
+#   Uni1 = "km/s"       # Units for axis 1
+\end{terminalv}
+
+to
+
+\begin{terminalv}
+#   Uni1 = "GHz"        # Units for axis 1
+\end{terminalv}
+
+Of course, if you do not like any of these defaults, you may always
+over-ride them by setting explicit attribute values yourself. For
+instance, you may choose to have your frequency axis expressed in ``kHz''
+rather than ``GHz''. To do this simply set the attribute value as follows:
+
+\small
+\begin{terminalv}
+astSetC( specframe, "Unit", "kHz" );
+\end{terminalv}
+\normalsize
+
+No error will be reported if you accidentally set an inappropriate Unit value
+(say "J" - Joules)---after all, AST cannot tell what you are about to do,
+and you \emph{may} be about to change the System value to ``Energy''.
+However, an error \emph{will} be reported if you attempt to find a
+conversion between two SpecFrames (for instance using
+\htmlref{astConvert}{astConvert}
+) if either SpecFrame has a Unit value which is inappropriate for its
+System value.
+
+SpecFrame attributes, like all other attributes, all have default
+value. However, be aware that for some attributes these default values
+can never be more than ``a legal numerical value'' and have no
+astronomical significance. For instance, the \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes
+(which give the source position) both have a default value of zero. So
+unless your source happens to be at that point (highly unlikely!) you will
+need to set new values. Likewise, the \htmlref{RestFreq}{RestFreq} (rest frequency) attribute
+has an arbitrary default value of 1.0E5 GHz. Some operations are not
+affected by inappropriate values for these attributes (for instance,
+converting from frequency to wavelength, changing axis units, \emph{etc}),
+but some are. For instance, converting from frequency to velocity
+requires a correct rest frequency, moving between different standards of
+rest requires a correct source position. The moral is, always set explicit
+values for as many attributes as possible.
+
+\subsection{\label{ss:creatingspectralcubes}Creating Spectral Cubes}
+You can use a \htmlref{SpecFrame}{SpecFrame} to describe the spectral axis in a data cube
+containing two spatial axes and a spectral axis. To do this you would
+create an appropriate SpecFrame, together with a 2-dimensional \htmlref{Frame}{Frame}
+(often a \htmlref{SkyFrame}{SkyFrame}) to describe the spatial axes. You would then combine
+these two Frames together into a single \htmlref{CmpFrame}{CmpFrame}.
+
+\small
+\begin{terminalv}
+AstSkyFrame *skyframe;
+AstSpecFrame *specframe;
+AstCmpFrame *cmpframe;
+...
+skyframe = astSkyFrame( "Epoch=J2002" );
+specframe = astSpecFrame( "System=Freq,StdOfRest=LSRK" );
+cmpframe = astCmpFrame( skyframe, specframe, "" );
+\end{terminalv}
+\normalsize
+
+In the resulting CmpFrame, axis 1 will be RA, axis 2 will be Dec and axis
+3 will be Frequency. If this is not the order you want, you can permute
+the axes using
+\htmlref{astPermAxes}{astPermAxes}.
+
+There is one potential problem with this approach if you are interested in
+unusually high accuracy. Conversion between different standards of rest
+involves taking account of the Doppler shift caused by the relative
+motion of the two standards of rest. At some point this involves finding
+the component of  the relative velocity in the direction of interest.
+For a SpecFrame, this direction is always given by the \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec}
+attributes, even if the SpecFrame is embedded within a CmpFrame as above.
+It would be more appropriate if this ``direction of interest'' was
+specified by the values passed into the CmpFrame on the RA and DEC axes,
+allowing each pixel within a data cube to have a slightly different
+correction for Doppler shift.
+
+Unfortunately, the SpecFrame class cannot do this (since it is purely a
+1-dimensional Frame), and so some small degree of error will be
+introduced when converting between standards of rest, the size of the
+error varying from pixel to pixel. It is hoped that at some point in the
+future a sub-class of CmpFrame (a SpecCubeFrame) will be added to AST which
+allows for this spatial variation in Doppler shift.
+
+The maximum velocity error introduced by this problem is of the order of
+$V*SIN(FOV)$, where $FOV$ is the angular field of view, and $V$ is the
+relative velocity of the two standards of rest. As an example, when
+correcting from the observers rest frame (i.e. the topocentric rest
+frame) to the kinematic local standard of rest the maximum value of $V$
+is about 20 $km/s$, so for 5 arc-minute field of view the maximum
+velocity error introduced by the correction will be about 0.03 $km/s$. As
+another example, the maximum error when correcting from the observers
+rest frame to the local group is about 5 $km/s$ over a 1 degree field of
+view.
+
+\subsection{\label{ss:handlingdualsidebandspectra}Handling Dual-Sideband Spectra}
+Dual sideband super-heterodyne receivers produce spectra in which each channel
+contains contributions from two different frequencies, referred to as the
+``upper sideband frequency'' and the ``lower sideband frequency''. In the
+rest frame of the observer (topocentric), these are related to each other as
+follows:
+
+\begin{quote}
+\begin{small}
+\begin{equation}
+\label{eqn:dsb}
+   f_{lsb} = 2.f_{LO} - f_{usb}
+\end{equation}
+\end{small}
+\end{quote}
+
+where $f_{LO}$ is a fixed frequency known as the ``local oscillator
+frequency''. In other words, the local oscillator frequency is always
+mid-way between any pair of corresponding upper and lower sideband
+frequencies\footnote{Note, this simple relationship only applies if all
+frequencies are topocentric.}. If you want to describe the spectral axis
+of such a spectrum using a \htmlref{SpecFrame}{SpecFrame} you must choose whether you want the
+SpecFrame to describe $f_{lsb}$ or $f_{usb}$ - a basic SpecFrame cannot
+describe both sidebands simultaneously. However, there is a sub-class of
+SpecFrame, called \htmlref{DSBSpecFrame}{DSBSpecFrame}, which overcomes this difficulty.
+
+A DSBSpecFrame has a \htmlref{SideBand}{SideBand} attribute which indicates if the
+DSBSpecFrame is currently being used to describe the upper or lower
+sideband spectral axis. The value of this attribute can be changed at any
+time. If you use the
+\htmlref{astConvert}{astConvert}
+function to find the \htmlref{Mapping}{Mapping} between two DSBSpecFrames, the setting for
+the two SideBand attributes will be taken into account. Thus, if you take
+a copy of a DSBSpecFrame, toggle its SideBand attribute, and then use
+astConvert
+to find a Mapping from the original to the modified copy, the resulting
+Mapping will be of the form of equation \ref{eqn:dsb} (if the
+DSBSpecFrame has its \htmlref{StdOfRest}{StdOfRest} attribute set to ``Topocentric'').
+
+In general, when finding a Mapping between two arbitrary DSBSpecFrames,
+the total Mapping is made of of three parts in series:
+
+\begin{enumerate}
+\item A Mapping which converts the first DSBSpecFrame into its upper
+sideband representation. If the DSBSpecFrame already represents its upper
+sideband, this Mapping will be a \htmlref{UnitMap}{UnitMap}.
+\item A Mapping which converts from the first to the second DSBSpecFrame,
+treating them as if they were both basic SpecFrames. This takes account of
+any difference in units, standard of rest, system, \emph{etc} between the
+two DSBSpecFrames.
+\item A Mapping which converts the second DSBSpecFrame from its upper
+sideband representation to its current sideband. If the DSBSpecFrame
+currently represents its upper sideband, this Mapping will be a UnitMap.
+\end{enumerate}
+
+If an attempt is made to find the Mapping between a DSBSpecFrame and a
+basic SpecFrame, then the DSBSpecFrame will be treated like a basic
+SpecFrame. In other words, the returned Mapping will not be affected by
+the setting of the SideBand attribute (or any of the other attributes
+specific to the DSBSpecFrame class).
+
+In practice, the local oscillator frequency for a dual sideband
+instrument may not be easily available to an observer. Instead, it is
+common practice to specify the spectral position of some central feature
+in the observation (commonly the centre of the instrument passband),
+together with an ``intermediate frequency''. Together, these two values
+allow the local oscillator frequency to be determined. The intermediate
+frequency is the difference between the topocentric frequency at the
+central spectral position and the topocentric frequency of the local
+oscillator. So:
+
+\begin{quote}
+\begin{small}
+\begin{equation}
+\label{eqn:dsb2}
+   f_{LO} = f_{central} + f_{if}
+\end{equation}
+\end{small}
+\end{quote}
+
+The DSBSpecFrame class uses the \htmlref{DSBCentre}{DSBCentre} attribute to specify the central
+spectral position ($f_{central}$), and the \htmlref{IF}{IF} attribute to specify the
+intermediate frequency ($f_{if}$). The DSBCentre value is given and returned
+in the spectral system described by the DSBSpecFrame (thus you do not need to
+calculate the corresponding topocentric frequency yourself - this will be
+done automatically by the DSBSpecFrame when you assign a new value to the
+DSBCentre attribute). The value assigned to the IF attribute should
+always be a topocentric frequency in units of Hz, however a negative
+value may be given to indicate that the DSBCentre value is in the upper
+sideband (that is, if $IF < 0$  then $f_{central} > f_{LO}$). A positive
+value for IF indicates that the DSBCentre value is in the lower sideband
+(that is, if $IF > 0$  then $f_{central} < f_{LO}$).
+
+
+\cleardoublepage
+\section{\xlabel{ss_timeframes}\label{ss:timeframes}Time Systems (TimeFrames)}
+
+The \htmlref{TimeFrame}{TimeFrame} is a \htmlref{Frame}{Frame} which is specialised for representing moments in
+time. In this section we examine the additional properties and behaviour of a
+TimeFrame that distinguish it from a basic Frame (\secref{ss:frames}).
+
+\subsection{The TimeFrame Model}
+
+As for a \htmlref{SkyFrame}{SkyFrame}, a \htmlref{TimeFrame}{TimeFrame} is a \htmlref{Frame}{Frame} (\secref{ss:frames}) and also a
+\htmlref{Mapping}{Mapping} (\secref{ss:mappings}), so it inherits all the properties and
+behaviour of these two ancestral classes.  When used as a Mapping, a
+TimeFrame implements a unit transformation, exactly like a basic Frame
+(\secref{ss:frameasmapping}) or a \htmlref{UnitMap}{UnitMap}, so this aspect of its
+behaviour is not of great importance.
+
+When used as a Frame, however, a TimeFrame represents a wide range of
+different 1-dimensional coordinate system which can be used to describe
+moments in time. Absolute times and relative (i.e. elapsed) times are
+supported (attribute \htmlref{TimeOrigin}{TimeOrigin}), as are a range of different time scales
+(attribute \htmlref{TimeScale}{TimeScale}). An absolute or relative value in any time scale can
+be represented in different forms such as Modified Julian Date, Julian \htmlref{Epoch}{Epoch},
+\emph{etc} (attribute \htmlref{System}{System}). AST extends the definition of these systems to
+allow them to be used with any unit of time (attribute Unit). The TimeFrame
+class also allows times to formatted as either a simple floating point value
+or as a Gregorian date and time of day (attribute Format).
+
+\subsection{Creating a TimeFrame}
+
+The \htmlref{TimeFrame}{TimeFrame} constructor function is particularly simple and a
+TimeFrame with default attributes is created as follows:
+
+\small
+\begin{terminalv}
+#include "ast.h"
+AstTimeFrame *timeframe;
+
+...
+
+timeframe = astTimeFrame( "" );
+\end{terminalv}
+\normalsize
+
+Such a TimeFrame would represent the default coordinate system which is
+Modified Julian Date (with the usual units of days) in the International
+Atomic Time (TAI) time scale.
+
+\subsection{Specifying a Particular Time System}
+By setting the \htmlref{System}{System} attribute appropriately, the \htmlref{TimeFrame}{TimeFrame} can represent
+Julian Date, Modified Julian Date, Julian \htmlref{Epoch}{Epoch} or Besselian Epoch (the
+time scale is specified by a separate attribute called \htmlref{TimeScale}{TimeScale}).
+
+Selection of a particular coordinate system is performed simply by
+setting a value for the TimeFrame's (character string) System
+attribute. This setting is most conveniently done when the TimeFrame is
+created. For example, a TimeFrame representing Julian Epoch would be created
+by:
+
+\small
+\begin{terminalv}
+timeframe = astTimeFrame( "System=JEPOCH" );
+\end{terminalv}
+\normalsize
+
+Note that specifying ``System$=$JEPOCH'' also changes the associated
+default Unit (from days to years). This is because the default value
+of the TimeFrame's Unit attribute depends on the System attribute setting.
+
+You may change the System value at any time, although this is not
+usually needed.  The values supported are set out in the attribute's
+description in \appref{ss:attributedescriptions}.
+
+\subsection{Attributes which Qualify Time Coordinate Systems}
+
+Time coordinate systems require some additional free parameters to identify
+a particular coordinate system from amongst a broader class of related
+coordinate systems. For example, all TimeFrames are qualified by the time
+scale (that is, the physical process used to define the flow of time),
+and some require the position of the observer's clock.
+
+In AST, these free parameters are represented by additional \htmlref{TimeFrame}{TimeFrame}
+attributes, each of which has a default appropriate to (\emph{i.e.}\ defined
+by) the setting of the main \htmlref{System}{System} attribute. Each of these \emph{qualifying
+attributes} may, however, be assigned an explicit value so as to select a
+particular coordinate system. Note, it is usually best to assign explicit
+values whenever possible rather than relying on defaults. Attribute
+should only be left at their default value if you ``don't care'' what
+value is used. In certain circumstances (particularly, when aligning two
+Frames), a default value for an attribute may be replaced by the value
+from another similar \htmlref{Frame}{Frame}. Such value replacement can be prevented by
+assigning an explicit value to the attribute, rather than simply relying on
+the default.
+
+The main TimeFrame attributes which qualify the System attribute are:
+
+\begin{quote}
+\begin{description}
+
+\item[\htmlref{TimeScale}{TimeScale}]\mbox{}\\
+This specifies the time scale.
+
+\item[\htmlref{LTOffset}{LTOffset}]\mbox{}\\
+This specifies the offset from Local Time to UTC in hours (time zones
+east of Greenwich have positive values). Note, AST uses the value as
+supplied without making any correction for daylight saving.
+
+\item[\htmlref{TimeOrigin}{TimeOrigin}]\mbox{}\\
+This specifies the zero point from which time values are measured, within
+the system specified by the System attribute. Thus, a value of zero (the
+default) indicates that time values represent absolute times. Non-zero
+values may be used to indicate that the TimeFrame represents elapsed time
+since the specified origin.
+
+\end{description}
+\end{quote}
+
+For further details of these attributes you should consult their
+descriptions in \appref{ss:attributedescriptions} and for details of
+the System settings for which they are relevant, see the description
+of the System attribute (also in \appref{ss:attributedescriptions}).
+
+Note that it does no harm to assign values to qualifying attributes
+which are not relevant to the main System or TimeScale value. Any such
+values are stored, but are not used unless the System and/or TimeScale
+value is later set so that they become relevant.
+
+\cleardoublepage
+\section{\label{ss:cmpframes}Compound Frames (CmpFrames)}
+
+We now turn to a rather special form of \htmlref{Mapping}{Mapping}, the \htmlref{CmpFrame}{CmpFrame}. The
+Frames we have considered so far have been atomic, in the sense that
+they represent pre-defined elementary physical domains. A CmpFrame,
+however, is a compound \htmlref{Frame}{Frame}. In essence, it is a structure for
+containing other Frames and its purpose is to allow those Frames
+to work together in various combinations while appearing as a single
+\htmlref{Object}{Object}. A CmpFrame's behaviour is therefore not pre-defined, but is
+determined by the other Frames it contains (its ``component'' Frames).
+
+As with compound Mappings, compound Frames can be nested within each
+other, forming arbitrarily complex Frames.
+
+\subsection{Creating a CmpFrame}
+A very common use for a \htmlref{CmpFrame}{CmpFrame} within astronomy is to represent a
+``spectral cube''. This is a 3-dimensional \htmlref{Frame}{Frame} in which one of the axes
+represents position within a spectrum, and the other two axes represent
+position on the sky (or some other spatial domain such as the focal plane
+of a telescope). As an example, we create such a CmpFrame in which axes
+1 and 2 represent Right Ascension and Declination (ICRS), and axis 3
+represents wavelength (these are the default coordinate Systems
+represented by a \htmlref{SkyFrame}{SkyFrame} and a \htmlref{SpecFrame}{SpecFrame} respectively):
+
+\small
+\begin{terminalv}
+AstSkyFrame *skyframe;
+AstSpecFrame *specframe;
+AstCmpFrame *cmpframe;
+...
+skyframe = astSkyFrame( "" );
+specframe = astSpecFrame( "" );
+cmpframe = astCmpFrame( skyframe, specframe, "" );
+\end{terminalv}
+\normalsize
+
+If it was desired to make RA and Dec correspond to axes 1 and 3, with
+axis 2 being the spectral axis, then the axes of the CmpFrame created
+above would need to be permuted as follows:
+
+\small
+\begin{terminalv}
+int perm[ 3 ];
+...
+
+perm[ 0 ] = 0;
+perm[ 1 ] = 2;
+perm[ 2 ] = 1;
+astPermAxes( cmpframe, perm );
+\end{terminalv}
+\normalsize
+
+\subsection{The Attributes of a CmpFrame}
+
+A \htmlref{CmpFrame}{CmpFrame} \emph{is a} \htmlref{Frame}{Frame} and so has all the attributes of a Frame.
+The default value for the \htmlref{Domain}{Domain} attribute for a CmpFrame is formed by
+concatenating the Domains of the two component Frames, separated by a
+minus sign (``-'').\footnote{If both component Frames have blank Domains,
+then the default Domain for the CmpFrame is the string ``CMP''.} The (fixed)
+value for its \htmlref{System}{System} attribute is ``Compound''.\footnote{Any attempt to
+change the System value of a CmpFrame is ignored.} A CmpFrame has no
+further attributes over and above those common to all Frames. However,
+attributes of the two component Frames can be accessed as if they were
+attributes of the CmpFrame, as described below.
+
+Frame attributes which are specific to individual axes (such as Label(2),
+Format(1), \emph{etc}) simply mirror the corresponding axes of the
+relevant component Frame. That is, if the ``Label(2)'' attribute of a
+CmpFrame is accessed, the CmpFrame will forward the access request to the
+component Frame which contains axis 2. Thus, default values for axis
+attributes will be the same as those provided by the component Frames.
+
+An axis index can optionally be appended to the name of Frames attributes
+which do not normally have such an index (System, Domain, \htmlref{Epoch}{Epoch}, \htmlref{Title}{Title},
+\emph{etc}). If this is done, the access request is forwarded to the
+component Frame containing the indicated axis. For instance, if a
+CmpFrame contains a \htmlref{SpecFrame}{SpecFrame} and a \htmlref{SkyFrame}{SkyFrame} in that order, and the axes
+have not been permuted, then getting the value of attribute ``System'' will
+return  ``Compound'' as mentioned above (that is, the System value of the
+CmpFrame as a whole), whereas getting the value of attribute
+``System(1)'' will return ``Spectral''(that is, the System value of the
+component Frame containing axis 1 --- the SpecFrame).
+
+This technique is not limited to attributes common to all Frames. For
+instance, the SkyFrame class defines an attribute called \htmlref{Equinox}{Equinox} which is
+not held by other classes of Frames. To set a value for the Equinox
+attribute of the SkyFrame contained within the above CmpFrame, assign the
+value to the ``Equinox(2)'' attribute of the CmpFrame. Since the SkyFrame
+defines both axes 2 and 3 of the CmpFrame, we could equivalently have set
+a value for ``Equinox(3)'' since this would also result in the attribute
+access being forwarded to the SkyFrame.
+
+Finally, if an attribute is not qualified by a axis index, attempts will
+be made to access it using each of the CmpFrame axes in turn. Using the
+above example of the spectral cube, if an attempt was made to get the
+value of attribute ``Equinox'' (with no axis index), each axis in turn
+would be used. Since axis 1 is contained within a SpecFrame, the first
+attempt would fail since the SpecFrame class does not have an Equinox
+attribute. However, the second attempt would succeed because axis 2 is
+contained within a SkyFrame which \emph{does} have an Equinox attribute. Thus
+the returned attribute value would be that obtained from the SkyFrame
+containing axis 2. When getting or testing an attribute value, the
+returned value is determined by the \emph{first} axis which recognises
+the attribute. When setting an attribute value, \emph{all} axes
+which recognises the attribute have the attribute value set to the given
+value. Likewise, when clearing an attribute value, all axes
+which recognises the attribute have the attribute value cleared.
+
+\cleardoublepage
+\section{\label{ss:introducingconversion}An Introduction to Coordinate System Conversions}
+
+In this section, we start to look at techniques for converting between
+different coordinate systems.  At this stage, the tools we have available
+are Frames (\secref{ss:frames}), SkyFrames (\secref{ss:skyframes}),
+SpecFrames (\secref{ss:specframes}), TimeFrames (\secref{ss:timeframes}) and
+various Mappings (\secref{ss:mappings}). These are sufficient to allow us to
+begin examining the problem, but more sophisticated approaches will also emerge
+later (\secref{ss:framesetconverting}).
+
+\subsection{\label{ss:convertingskyframes}Converting between Celestial Coordinate Systems}
+
+We begin by examining how to convert between two celestial coordinate
+systems represented by SkyFrames, as this is both an illuminating and
+practical example.  Consider the problem of converting celestial
+coordinates between:
+
+\begin{enumerate}
+\item The old FK4 system, with no E terms, a Besselian epoch of
+1958.0 and a Besselian equinox of 1960.0.
+
+\item An ecliptic coordinate system based on the mean equinox and
+ecliptic of Julian epoch 2010.5.
+\end{enumerate}
+
+This example is arbitrary but not completely unrealistic. Unless you
+already have expertise with such conversions, you are unlikely to find
+it straightforward.
+
+Using AST, we begin by creating two SkyFrames to represent these
+coordinate systems, as follows:
+
+\small
+\begin{terminalv}
+#include "ast.h"
+AstSkyFrame *skyframe1, *skyframe2;
+
+...
+
+skyframe1 = astSkyFrame( "System=FK4-NO-E, Epoch=B1958, Equinox=B1960" );
+skyframe2 = astSkyFrame( "System=Ecliptic, Equinox=J2010.5" );
+\end{terminalv}
+\normalsize
+
+Note how specifying the coordinate systems consists simply of
+initialising the attributes of each \htmlref{SkyFrame}{SkyFrame} appropriately.  The next
+step is to find a way of converting between these SkyFrames. This is
+done using \htmlref{astConvert}{astConvert}, as follows:
+
+\small
+\begin{terminalv}
+AstFrameSet *cvt;
+
+...
+
+cvt = astConvert( skyframe1, skyframe2, "" );
+if ( cvt == AST__NULL ) {
+   <conversion is not possible>
+} else {
+   <conversion is possible>
+}
+\end{terminalv}
+\normalsize
+
+The third argument of astConvert is not used here and should be an
+empty string.
+
+astConvert will return a null result, AST\_\_NULL (as defined in the
+``ast.h'' header file), if conversion is not possible. In this
+example, conversion is possible, so it will return a pointer to a new
+\htmlref{Object}{Object} that describes the conversion.
+
+The Object returned is called a \htmlref{FrameSet}{FrameSet}. We have not discussed
+FrameSets yet (\secref{ss:framesets}), but for the present purposes we
+can consider them simply as Objects that can behave both as Mappings
+and as Frames. It is the FrameSet's behaviour as a \htmlref{Mapping}{Mapping} in which we
+are mainly interested here, because the Mapping it implements is the
+one we require---\emph{i.e.}\ it converts between the two celestial
+coordinate systems (\secref{ss:framesetsfromconvert}).
+
+For example, if ``alpha1'' and ``delta1'' are two arrays containing
+the longitude and latitude, in radians, of N points on the sky in the
+original coordinate system (corresponding to ``skyframe1''), then they
+could be converted into the new coordinate system (represented by
+``skyframe2'') as follows:
+
+\small
+\begin{terminalv}
+#define N 10
+double alpha1[ N ], delta1[ N ];
+double alpha2[ N ], delta2[ N ];
+
+...
+
+astTran2( cvt, N, alpha1, delta1, 1, alpha2, delta2 );
+\end{terminalv}
+\normalsize
+
+The new coordinates are returned \emph{via} the ``alpha2'' and
+``delta2'' arrays.  To transform coordinates in the opposite
+direction, we simply invert the 5th (boolean int) argument to
+\htmlref{astTran2}{astTran2}, as follows:
+
+\small
+\begin{terminalv}
+astTran2( cvt, N, alpha2, delta2, 0, alpha1, delta1 );
+\end{terminalv}
+\normalsize
+
+The FrameSet returned by astConvert also contains information about
+the SkyFrames used in the conversion
+(\secref{ss:framesetsfromconvert}). As we mentioned above, a FrameSet
+may be used as a \htmlref{Frame}{Frame} and in this case it behaves like the
+``destination'' Frame used in the conversion (\emph{i.e.}\ like
+``skyframe2'').  We could therefore use the ``cvt'' FrameSet to
+calculate the distance between two points (with coordinates in
+radians) in the destination coordinate system, using \htmlref{astDistance}{astDistance}:
+
+\small
+\begin{terminalv}
+double distance, point1[ 2 ], point2[ 2 ];
+
+...
+
+distance = astDistance( cvt, point1, point2 );
+\end{terminalv}
+\normalsize
+
+and the result would be the same as if the ``skyframe2'' SkyFrame had
+been used.
+
+Another way to see how the FrameSet produced by astConvert retains
+information about the coordinate systems involved is to set its \htmlref{Report}{Report}
+attribute (inherited from the Mapping class) so that it displays the
+coordinates before and after conversion (\secref{ss:transforming}):
+
+\small
+\begin{terminalv}
+astSet( cvt, "Report=1" );
+astTran2( cvt, N, alpha1, delta1, 1, alpha2, delta2 );
+\end{terminalv}
+\normalsize
+
+The output from this might look like the following:
+
+\begin{terminalv}
+(2:06:03.0, 34:22:39) --> (42.1087, 20.2717)
+(2:08:20.6, 35:31:24) --> (43.0197, 21.1705)
+(2:10:38.1, 36:40:09) --> (43.9295, 22.0716)
+(2:12:55.6, 37:48:55) --> (44.8382, 22.9753)
+(2:15:13.1, 38:57:40) --> (45.7459, 23.8814)
+(2:17:30.6, 40:06:25) --> (46.6528, 24.7901)
+(2:19:48.1, 41:15:11) --> (47.5589, 25.7013)
+(2:22:05.6, 42:23:56) --> (48.4644, 26.6149)
+(2:24:23.1, 43:32:41) --> (49.3695, 27.5311)
+(2:26:40.6, 44:41:27) --> (50.2742, 28.4499)
+\end{terminalv}
+
+Here, we see that the input FK4 equatorial coordinate values (given in
+radians) have been formatted automatically in sexagesimal notation
+using the conventional hours for right ascension and degrees for
+declination. Conversely, the output ecliptic coordinates are shown in
+decimal degrees, as is conventional for ecliptic coordinates. Both are
+displayed using the default precision of 7 digits.\footnote{The
+leading digit is zero and is therefore not seen in this particular
+example.}
+
+In fact, the ``cvt'' FrameSet has access to all the information in the
+original SkyFrames which were passed to astConvert. If you had set a
+new Digits attribute value for either of these, the formatting above
+would reflect the different precision you requested by displaying a
+greater or smaller number of digits.
+
+
+\subsection{\label{ss:convertingspecframes}Converting between Spectral Coordinate Systems}
+The principles described in the previous section for converting between
+celestial coordinate systems also apply to the task of converting between
+spectral coordinate systems. As an example, let's look at how we might
+convert between frequency measured in $GHz$ as measured in the rest frame
+of the telescope, and radio velocity measured in $km/s$ measured with
+respect the kinematic Local Standard of Rest.
+
+First we create a default \htmlref{SpecFrame}{SpecFrame}, and then set its attributes to
+describe the required radio velocity system (this is slightly more
+convenient, given the relatively large number of attributes, than
+specifying the attribute values in a single string such as would be
+passed to the SpecFrame constructor). We then take a copy of this
+SpecFrame, and change the attribute values so that the copy describes the
+original frequency system (modifying a copy, rather than creating a new
+SpecFrame from scratch, avoids the need to specify the epoch, reference
+position, \emph{etc} a second time since they are all inherited by the copy):
+
+\small
+\begin{terminalv}
+#include "ast.h"
+AstSpecFrame *specframe1, *specframe2;
+
+...
+
+specframe1 = astSpecFrame( "" );
+astSet( specframe1, "System=vradio" );
+astSet( specframe1, "Unit=km/s" );
+astSet( specframe1, "Epoch=1996-Oct-2 12:13:56.985" );
+astSet( specframe1, "ObsLon=W155:28:18" );
+astSet( specframe1, "ObsLat=N19:49:34" );
+astSet( specframe1, "RefRA=18:14:50.6" );
+astSet( specframe1, "RefDec=-4:40:49" );
+astSet( specframe1, "RestFreq=230.538 GHz" );
+astSet( specframe1, "StdOfRest=LSRK" );
+
+specframe2 = astCopy( specframe1 );
+astSet( specframe1, "System=freq" );
+astSet( specframe1, "Unit=GHz" );
+astSet( specframe1, "StdOfRest=Topocentric" );
+
+\end{terminalv}
+\normalsize
+
+Note, the fact that a SpecFrame has only a single axis means that we were
+able to refer to the Unit attribute without an axis index. The other
+attributes are: the time of of observation (\htmlref{Epoch}{Epoch}), the geographical
+position of the telescope (\htmlref{ObsLat}{ObsLat} \& \htmlref{ObsLon}{ObsLon}), the position of the source
+on the sky (\htmlref{RefRA}{RefRA} \& \htmlref{RefDec}{RefDec}), the rest frequency (\htmlref{RestFreq}{RestFreq}) and the
+standard of rest (\htmlref{StdOfRest}{StdOfRest}).
+
+The next step is to find a way of converting between these SpecFrames. We
+use exactly the same code that we did in the previous section where we were
+converting between celestial coordinate systems:
+
+\small
+\begin{terminalv}
+AstFrameSet *cvt;
+
+...
+
+cvt = astConvert( specframe1, specframe2, "" );
+if ( cvt == AST__NULL ) {
+   <conversion is not possible>
+} else {
+   <conversion is possible>
+}
+\end{terminalv}
+\normalsize
+
+A before, this will give us a \htmlref{FrameSet}{FrameSet} (assuming conversion is possible,
+which should always be the case for our example), and we can use the
+FrameSet to convert between the two spectral coordinate systems. We use
+\htmlref{astTran1}{astTran1} in place of \htmlref{astTran2}{astTran2}
+since a SpecFrame has only one axis (unlike a \htmlref{SkyFrame}{SkyFrame} which has two).
+
+For example, if ``frq'' is an array containing the observed frequency, in
+GHz, of N spectral channels (describe by ``specframe1''), then they
+could be converted into the new coordinate system (represented by
+``specframe2'') as follows:
+
+\small
+\begin{terminalv}
+#define N 10
+double frq[ N ];
+double vel[ N ];
+
+...
+
+astTran1( cvt, N, frq, 1, vel );
+\end{terminalv}
+\normalsize
+
+The radio velocity values are returned in the ``vel'' array.
+
+
+\subsection{Converting between Time Coordinate Systems}
+All the principles outlined in the previous section about aligning
+spectral cocordinate systems (SpecFrames) can be applied directly to the
+problem of aligning time coordinate systems (TimeFrames).
+
+\subsection{\label{ss:convertingpermutedaxes}Handling SkyFrame Axis Permutations}
+
+We can illustrate an important point if we swap the axis order of
+either \htmlref{SkyFrame}{SkyFrame} in the example above (\secref{ss:convertingskyframes})
+before identifying the conversion. Let's assume we use \htmlref{astPermAxes}{astPermAxes}
+(\secref{ss:permutingaxes}) to do this to the second SkyFrame, before
+applying \htmlref{astConvert}{astConvert}, as follows:
+
+\small
+\begin{terminalv}
+int perm[ 2 ] = { 2, 1 };
+
+...
+
+astPermAxes( skyframe2, perm );
+cvt = astConvert( skyframe1, skyframe2, "" );
+\end{terminalv}
+\normalsize
+
+Now, the destination SkyFrame system no longer represents the
+coordinate system:
+
+\begin{quote}
+(ecliptic~longitude, ecliptic~latitude)
+\end{quote}
+
+but instead represents the transposed system:
+
+\begin{quote}
+(ecliptic~latitude, ecliptic~longitude)
+\end{quote}
+
+As a consequence, when we use the \htmlref{FrameSet}{FrameSet} returned by astConvert to
+apply a coordinate transformation, we obtain something like the
+following:
+
+\begin{terminalv}
+(2:06:03.0, 34:22:39) --> (20.2717, 42.1087)
+(2:08:20.6, 35:31:24) --> (21.1705, 43.0197)
+(2:10:38.1, 36:40:09) --> (22.0716, 43.9295)
+(2:12:55.6, 37:48:55) --> (22.9753, 44.8382)
+(2:15:13.1, 38:57:40) --> (23.8814, 45.7459)
+(2:17:30.6, 40:06:25) --> (24.7901, 46.6528)
+(2:19:48.1, 41:15:11) --> (25.7013, 47.5589)
+(2:22:05.6, 42:23:56) --> (26.6149, 48.4644)
+(2:24:23.1, 43:32:41) --> (27.5311, 49.3695)
+(2:26:40.6, 44:41:27) --> (28.4499, 50.2742)
+\end{terminalv}
+
+When compared to the original (\secref{ss:convertingskyframes}), the
+output coordinate order has been swapped to compensate for the
+different destination SkyFrame axis order.
+
+In all, there are four possible axis combinations, corresponding to two
+possible axis orders for each of the source and destination SkyFrames,
+and astConvert will convert correctly between any of these.
+The point to note is that a SkyFrame contains knowledge about how to
+convert to and from other SkyFrames. Since its two axes (longitude and
+latitude) are distinguishable, the conversion is able to take account
+of the axis order.
+
+If you need to identify the axes of a SkyFrame explicitly, taking into
+account any axis permutations, the \htmlref{LatAxis}{LatAxis} and \htmlref{LonAxis}{LonAxis} attributes can be
+used. These are read-only attributes which give the indices of the
+latitude and longitude axes respectively.
+
+\subsection{\label{ss:convertingframes}Converting Between Frames}
+
+Having seen how clever SkyFrames are (\secref{ss:convertingskyframes}
+and \secref{ss:convertingpermutedaxes}), we will next examine how dumb
+a basic \htmlref{Frame}{Frame} can be in comparison. For example, if we create two
+2-dimensional Frames and use \htmlref{astConvert}{astConvert} to derive a conversion between
+them, as follows:
+
+\small
+\begin{terminalv}
+AstFrame *frame1, *frame2;
+
+...
+
+frame1 = astFrame( 2, "" );
+frame2 = astFrame( 2, "" );
+cvt = astConvert( frame1, frame2, "" );
+\end{terminalv}
+\normalsize
+
+then the coordinate transformation which the ``cvt'' \htmlref{FrameSet}{FrameSet} performs
+will be as follows:
+
+\begin{terminalv}
+(1, 2) --> (1, 2)
+(2, 4) --> (2, 4)
+(3, 6) --> (3, 6)
+(4, 8) --> (4, 8)
+(5, 10) --> (5, 10)
+\end{terminalv}
+
+This is an identity transformation, exactly the same as a \htmlref{UnitMap}{UnitMap}
+(\secref{ss:unitmapexample}). Even if we permute the axis order of our
+Frames, as we did above (\secref{ss:convertingpermutedaxes}), we will
+fare no better. The conversion between our two basic Frames will
+always be an identity transformation.
+
+The reason for this is that, unlike a \htmlref{SkyFrame}{SkyFrame}, all basic Frames start
+life the same and have axes that are indistinguishable. Therefore,
+permuting their axes doesn't make them look any different---they still
+represent the same coordinate system.
+%Actually, this behaviour isn't as dumb as it seems and can actually be
+%very useful, as the following example illustrates.
+%
+%\subsection{Distinguishable and Indistinguishable Axes}
+%
+%c+
+%Imagine you have two Frames which represent the pixel coordinates of
+%two 2-dimensional images. Let's call their axes ``X'' and ``Y''.
+%Suppose you now transpose the second image and swap its Frame axes
+%(with \htmlref{astPermAxes}{astPermAxes}) to take account of this.
+%c-
+%f+
+%Imagine you have two Frames which represent the pixel coordinates of
+%two 2-dimensional images. Let's call their axes ``X'' and ``Y''.
+%Suppose you now transpose the second image and swap its Frame axes
+%(with astPermAxes) to take account of this.
+%f-
+%
+%Next, consider what happens if you want to subtract one image from the
+%other. If you have a ``subtract'' program that is intelligent and
+%tries to align the two images for you, one of two things could happen:
+%
+%\begin{enumerate}
+%c+
+%\item If the axes are distinguishable, when your program invokes
+%astConvert it will derive a transformation between the two images
+%which swaps the X and Y coordinates (corresponding to the transposition
+%you applied to the second image). However, in aligning X-with-X and
+%Y-with-Y, this will completely undo the effects of your transposition!
+%c-
+%f+
+%\item If the axes are distinguishable, when your program invokes
+%AST\_CONVERT it will derive a transformation between the two images
+%which swaps the X and Y coordinates (corresponding to the transposition
+%you applied to the second image). However, in aligning X-with-X and
+%Y-with-Y, this will completely undo the effects of your transposition!
+%f-
+%
+%\item If the axes are indistinguishable, the transformation between
+%the two images will always be an identity
+%(\secref{ss:convertingframes}). Therefore, your program will align
+%X-with-Y and Y-with-X, so that you see the effects of your earlier
+%transposition of the second image.
+%\end{enumerate}
+%
+%Clearly, if we are considering pixel coordinates, the latter behaviour
+%is preferable, since there would be no point in implementing an image
+%transposition program if we could never see the effects of it. This
+%indicates that a basic Frame, with is indistinguishable axes, is the
+%correct type of \htmlref{Object}{Object} to represent a pixel coordinate system, where
+%this behaviour is necessary.
+%
+%Conversely, the former behaviour would be more useful if the axes we
+%were considering were, say, wavelength (in nm) and slit position (in
+%mm). In this case, we would expect our ``subtract'' program to
+%subtract data at corresponding wavelengths and slit positions, not
+%just at corresponding pixels. This case requires distinguishable axes,
+%so that corresponding axes in the two images can be matched up, just
+%as happens with a SkyFrame (\secref{ss:convertingpermutedaxes}).
+%
+%Of course, there may also be intermediate cases, where some axes are
+%distinguishable and others aren't.
+
+\subsection{\label{ss:alignmentsystem}The Choice of Alignment System}
+
+In practice, when AST is asked to find a conversion between two Frames
+describing two different coordinate systems on a given physical domain,
+it uses an intermediate ``alignment'' system. Thus, when finding a
+conversion from system A to system B, AST first finds the \htmlref{Mapping}{Mapping} from
+system A to some alignment system, system C, and then finds the Mapping
+from this system C to the required system B. It finally concatenates
+these two Mappings to get the Mapping from system A to system B.
+
+One advantage of this is that it cuts down the number of conversion
+algorithms required. If there are $N$ different Systems which may be used
+to describe positions within the \htmlref{Domain}{Domain}, then this approach requires
+about $2*N$ conversion algorithms to be written. The alternative approach
+of going directly from system A to system B would require about $N*N$
+conversion algorithms.
+
+In addition, the use of an intermediate alignment system highlights the
+nature of the conversion process. What do we mean by saying that a
+Mapping ``converts a position in one coordinate system into the
+corresponding position in another''? In practice, it means that the input
+and output coordinates correspond to the same coordinates \emph{in some
+third coordinate system}. The choice of this third coordinate system, the
+``alignment'' system, can completely alter the nature of the Mapping. The
+\htmlref{Frame}{Frame} class has an attribute called \htmlref{AlignSystem}{AlignSystem} which can be used to
+specify the alignment system.
+
+As an example, consider the case of aligning two spectra calibrated in
+radio velocity, but each with a different rest frequency (each spectrum
+will be described by a \htmlref{SpecFrame}{SpecFrame}). Since the rest frequencies differ, a
+given velocity will correspond to different frequencies in the two
+spectra. So when we come to ``align'' these two spectra (that is, find a
+Mapping which converts positions in one SpecFrame to the corresponding
+positions in the other), we have the choice of aligning the frequencies
+or aligning the velocities. Different Mappings will be required to
+describe these two forms of alignment. If we set AlignSystem to ``Freq''
+then the returned Mapping will align the frequencies described by the two
+SpecFrames. On the other hand, if we set AlignSystem to ``Vradio''
+then the returned Mapping will align the velocities.
+
+Some choices of alignment system are redundant. For instance, in the
+above example, changing the alignment system from frequency to wavelength
+has no effect on the returned Mapping: if two spectra are aligned in
+frequency they will also be aligned in wavelength (assuming the speed of
+light doesn't change).
+
+The default value for AlignSystem depends on the class of Frame. For a
+SpecFrame, the default is wavelength (or equivalently, frequency)
+since this is the system in which observations are usually made. The
+SpecFrame class also has an attribute called \htmlref{AlignStdOfRest}{AlignStdOfRest} which
+allows the standard of rest of the alignment system to be specified.
+Similarly, the \htmlref{TimeFrame}{TimeFrame} class has an attribute called \htmlref{AlignTimeScale}{AlignTimeScale}
+which allows the time scale of the alignment system to be specified.
+Currently, the \htmlref{SkyFrame}{SkyFrame} uses ICRS as the default for AlignSystem, since
+this is a close approximation to an inertial frame of rest.
+
+\cleardoublepage
+\section{\label{ss:framesets}Coordinate System Networks (FrameSets)}
+
+We saw in \secref{ss:introducingconversion} how \htmlref{astConvert}{astConvert} could be
+used to find a \htmlref{Mapping}{Mapping} that inter-relates a pair of coordinate systems
+represented by Frames. There is a limitation to this, however, in that
+it can only be applied to coordinate systems that are inter-related by
+suitable conventions. In the case of celestial coordinates, the
+relevant conventions are standards set out by the International
+Astronomical Union, and others, that define what these coordinate
+systems mean. In practice, however, the relationships between many
+other coordinate systems are also of practical importance.
+
+Consider, for example, the focal plane of a telescope upon which an
+image of the sky is falling. We could measure positions in this focal
+plane in millimetres or, if there were a detector system such as a CCD
+present, we could count pixels. We could also use celestial
+coordinates of many different kinds. All of these systems are
+equivalent in their effectiveness at specifying positions in the focal
+plane, but some are more convenient than others for particular
+purposes.
+
+Although we could, in principle, convert between all of these focal
+plane coordinate systems, there is no pre-defined convention for doing
+so. This is because the conversions required depend on where the
+telescope is pointing and how the CCD is mounted in the focal
+plane. Clearly, knowledge about this cannot be built into the AST
+library and must be supplied in some other way. Note that this is
+exactly the same problem as we met in \secref{ss:framedomains} when
+discussing the \htmlref{Domain}{Domain} attribute---\emph{i.e.}\ coordinate systems that
+apply to different physical domains require that extra information be
+supplied before we can convert between them.
+
+What we need, therefore, is a general way to describe how coordinate
+systems are inter-related, so that when there is no convention already
+in place, we can define our own. We can then look forward to
+converting, say, from pixels into galactic coordinates and {\emph{vice
+versa.}  In AST, the \htmlref{FrameSet}{FrameSet} class provides this capability.
+
+\subsection{The FrameSet Model}
+
+Consider a coordinate system (call it number 1) which is represented
+by a \htmlref{Frame}{Frame} of some kind. Now consider a \htmlref{Mapping}{Mapping} which, when applied to
+the coordinates in system 1 yields coordinates in another system,
+number 2. The Mapping therefore inter-relates coordinate systems 1 and
+2.
+
+Now consider a second Mapping which inter-relates system 1 and a
+further coordinate system, number 3. If we wanted to convert
+coordinates between systems 2 and 3, we could do so by:
+
+\begin{enumerate}
+\item Applying our first Mapping in reverse, so as to convert between
+systems 2 and 1.
+
+\item Applying the second Mapping, as given, to convert between
+systems 1 and 3.
+\end{enumerate}
+
+We are not limited to three coordinate systems, of course. In fact, we
+could continue to introduce any number of further coordinate systems,
+so long as we have a suitable Mapping for each one which relates it to
+one of the Frames already present. Continuing in this way, we can
+build up a network in which Frames are inter-related by Mappings in
+such a way that there is always a way of converting between any pair
+of coordinate systems.
+
+The \htmlref{FrameSet}{FrameSet} (Figure~\ref{fig:frameset}) encapsulates these ideas.  It
+is a network composed of Frames and associated Mappings, in which
+there is always exactly one path, \emph{via} Mappings, between any
+pair of Frames.  Since we assemble FrameSets ourselves, they can be
+used to represent any coordinate systems we choose and to set up the
+particular relationships between them that we want.
+
+\subsection{\label{ss:creatingaframeset}Creating a FrameSet}
+
+Before we can create a \htmlref{FrameSet}{FrameSet}, we must have a \htmlref{Frame}{Frame} of some kind to
+put into it, so let's create a simple one:
+
+\small
+\begin{terminalv}
+#include "ast.h"
+AstFrame *frame1;
+
+...
+
+frame1 = astFrame( 2, "Domain=A" );
+\end{terminalv}
+\normalsize
+
+We have set this Frame's \htmlref{Domain}{Domain} attribute (\secref{ss:framedomains}) to
+A so that it will be distinct from the others we will be using. We can
+now create a new FrameSet containing just this Frame, as follows:
+
+\small
+\begin{terminalv}
+AstFrameSet *frameset;
+
+...
+
+frameset = astFrameSet( frame1, "" );
+\end{terminalv}
+\normalsize
+
+So far, however, this Frame isn't related to any others.
+
+\subsection{\label{ss:addingframes}Adding New Frames to a FrameSet}
+
+We can now add further Frames to the \htmlref{FrameSet}{FrameSet} created above
+(\secref{ss:creatingaframeset}). To do so, we must supply a new \htmlref{Frame}{Frame}
+and an associated \htmlref{Mapping}{Mapping} that relates it to any of the Frames that
+are already present (there is only one present so far).  To keep the
+example simple, we will just use a \htmlref{ZoomMap}{ZoomMap} that multiplies coordinates
+by 10. The required Objects are created as follows:
+
+\small
+\begin{terminalv}
+AstFrame *frame2;
+AstMapping *mapping12;
+
+...
+
+frame2 = astFrame( 2, "Domain=B" );
+mapping12 = astZoomMap( 2, 10.0, "" );
+\end{terminalv}
+\normalsize
+
+To add the new Frame into our FrameSet, we use the \htmlref{astAddFrame}{astAddFrame}
+function:
+
+\small
+\begin{terminalv}
+astAddFrame( frameset, 1, mapping12, frame2 );
+\end{terminalv}
+\normalsize
+
+Whenever a Frame is added to a FrameSet, it is assigned an integer
+index. This index starts with 1 for the initial Frame used to create
+the FrameSet (\secref{ss:creatingaframeset}) and increments by one
+every time a new Frame is added. This index is the primary way of
+identifying the Frames within a FrameSet.
+
+When a Frame is added, we also have to specify which of the existing
+ones the new Frame is related to. Here, we chose number 1, the only
+one present so far, and the new one we added became number 2.
+
+Note that a FrameSet does not make copies of the Frames and Mappings
+that you insert into it. Instead, it holds pointers to them. This
+means that if you retain the original pointers to these Objects and
+alter them, you will indirectly be altering the FrameSet's
+contents. You can, of course, always use \htmlref{astCopy}{astCopy}
+(\secref{ss:copyingobjects}) to make a separate copy of any \htmlref{Object}{Object} if
+you need to ensure its independence.
+
+We could also add a third Frame into our FrameSet, this time defining
+a coordinate system which is reached by multiplying the original
+coordinates (of ``frame1'') by 5:
+
+\small
+\begin{terminalv}
+astAddFrame( frameset, 1, astZoomMap( 2, 5.0, "" ), astFrame( 2, "Domain=C" ) );
+\end{terminalv}
+\normalsize
+
+Here, we have avoided storing unnecessary pointer values by using
+function invocations directly as arguments for astAddFrame. This
+assumes that we are using \htmlref{astBegin}{astBegin} and \htmlref{astEnd}{astEnd} (\secref{ss:contexts}) to
+ensure that Objects are correctly deleted when no longer required.
+
+   Our example FrameSet now contains three Frames and two Mappings with
+   the arrangement shown in Figure~\ref{fig:fsexample}.
+   \begin{figure}
+   \begin{center}
+   \includegraphics[width=0.7\textwidth]{sun211_figures/fsexample}
+   \caption[An example FrameSet.]{An example FrameSet, in which Frames~2 and 3 are related to
+   Frame~1 by multiplying its coordinates by factors of 10 and 5
+   respectively. The FrameSet's \htmlref{Base}{Base} attribute has the value 1 and its
+   \htmlref{Current}{Current} attribute has the value 3. The transformation performed when
+   the FrameSet is used as a Mapping (\emph{i.e.}\ from its base to
+   its current Frame) is shown in bold.}
+   \label{fig:fsexample}
+   \end{center}
+   \end{figure}
+   The total number of Frames is given by its read-only \htmlref{Nframe}{Nframe} attribute.
+
+\subsection{\label{ss:baseandcurrent}The Base and Current Frames}
+
+At all times, one of the Frames in a \htmlref{FrameSet}{FrameSet} is designated to be its
+\emph{base} \htmlref{Frame}{Frame} and one to be its \emph{current} Frame
+(Figure~\ref{fig:fsexample}). These Frames are identified by two
+integer FrameSet attributes, \htmlref{Base}{Base} and \htmlref{Current}{Current}, which hold the indices
+of the nominated Frames within the FrameSet.
+
+The existence of the base and current Frames reflects an important
+application of FrameSets, which is to attach coordinate systems to
+entities such as data arrays, data files, plotting surfaces (for
+graphics), \emph{etc.}  In this context, the base Frame represents the
+``native'' coordinate system of the attached entity---for example, the
+pixel coordinates of an image or the intrinsic coordinates of a
+plotting surface. The other Frames within the FrameSet represent
+alternative coordinate systems which may also be used to refer to
+positions within that entity.  The current Frame represents the
+particular coordinate system which is currently selected for use. For
+instance, if an image were being displayed, you would aim to label it
+with coordinates corresponding to the current Frame. In order to see a
+different coordinate system, a software user would arrange for a
+different Frame to be made current.
+
+The choice of base and current Frames may be changed at any time,
+simply by assigning new values to the FrameSet's Base and Current
+attributes. For example, to make the Frame with index 3 become the
+current Frame, you could use:
+
+\small
+\begin{terminalv}
+astSetI( frameset, "Current", 3 );
+\end{terminalv}
+\normalsize
+
+You can nominate the same Frame to be both the base and current Frame
+if you wish.
+\label{ss:baseandcurrentdefault}
+
+By default (\emph{i.e.}\ if the Base or Current attribute is un-set),
+the first Frame added to a FrameSet becomes its base Frame and the
+last one added becomes its current Frame.\footnote{Although this is
+reversed if the FrameSet's \htmlref{Invert}{Invert} attribute is non-zero.} Whenever a
+new Frame is added to a FrameSet, the Current attribute is modified so
+that the new Frame becomes the current one. This behaviour is
+reflected in the state of the example FrameSet in
+Figure~\ref{fig:fsexample}.
+
+\subsection{\label{ss:astbaseandastcurrent}Referring to the Base and Current Frames}
+
+It is often necessary to refer to the base and current Frames
+(\secref{ss:baseandcurrent}) within a \htmlref{FrameSet}{FrameSet}, but it can be
+cumbersome having to obtain their indices from the \htmlref{Base}{Base} and \htmlref{Current}{Current}
+attributes on each occasion. To make this easier, two macros,
+AST\_\_BASE and AST\_\_CURRENT, are defined in the ``ast.h'' header
+file and may be used to represent the indices of the base and current
+Frames respectively. They may be used whenever a \htmlref{Frame}{Frame} index is
+required.
+
+For example, when adding a new Frame to a FrameSet
+(\secref{ss:addingframes}), you could use the following to indicate
+that the new Frame is related to the existing current Frame, whatever
+its index happens to be:
+
+\small
+\begin{terminalv}
+AstFrame *frame;
+AstMapping *mapping;
+
+...
+
+astAddFrame( frameset, AST__CURRENT, mapping, frame );
+\end{terminalv}
+\normalsize
+
+Of course, the Frame you added would then become the new current
+Frame.
+
+\subsection{\label{ss:framesetasmapping}Using a FrameSet as a Mapping}
+
+The \htmlref{FrameSet}{FrameSet} class inherits properties and behaviour from the \htmlref{Frame}{Frame}
+class (\secref{ss:frames}) and, in turn, from the \htmlref{Mapping}{Mapping} class
+(\secref{ss:mappings}). Its behaviour when used as a Mapping is
+particularly important.
+
+Consider, for instance, passing a FrameSet pointer to a coordinate
+transformation function such as \htmlref{astTran2}{astTran2}:
+
+\small
+\begin{terminalv}
+#define N 10
+double xin[ N ], yin[ N ], xout[ N ], yout[ N ];
+
+...
+
+astTran2( frameset, N, xin, yin, 1, xout, yout );
+\end{terminalv}
+\normalsize
+
+The coordinate transformation applied by this FrameSet would be the
+one which converts between its base and current Frames. Using the
+FrameSet in Figure~\ref{fig:fsexample}, for example, the coordinates
+would be multiplied by a factor of 5.  If we instead requested the
+FrameSet's inverse transformation, we would be transforming from its
+current Frame to its base Frame, so our example FrameSet would then
+multiply by a factor of 0.2.
+
+Whenever the choice of base and current Frames changes, the
+transformations which a FrameSet performs when used as a Mapping also
+change to reflect this. The \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes may also change in
+consequence, because they are determined by the numbers of axes in the
+FrameSet's base and current Frames respectively. These numbers need
+not necessarily be equal, of course.
+
+Like any Mapping, a FrameSet may also be inverted by changing the
+boolean sense of its \htmlref{Invert}{Invert} attribute, \emph{e.g.}\ using \htmlref{astInvert}{astInvert}
+(\secref{ss:invertingmappings}). If this is happens, the values of the
+FrameSet's \htmlref{Base}{Base} and \htmlref{Current}{Current} attributes are interchanged, along with
+its Nin and Nout attributes, so that its base and current Frames swap
+places. When used as a Mapping, the FrameSet will therefore perform
+the inverse transformation to that which it performed previously.
+
+To summarise, a FrameSet may be used exactly like any other Mapping
+which inter-relates the coordinate systems described by its base and
+current Frames.
+
+\subsection{\label{ss:extractingamapping}Extracting a Mapping from a FrameSet}
+
+Although it is very convenient to use a \htmlref{FrameSet}{FrameSet} when a \htmlref{Mapping}{Mapping} is
+required (\secref{ss:framesetasmapping}), a FrameSet necessarily
+contains additional information and sometimes this might cause
+inefficiency or confusion.  For example, if you wanted to use a
+Mapping contained in one FrameSet and insert it into another, it would
+probably not be efficient to insert the whole of the first FrameSet
+into the second one, although it would work.
+
+In such a situation, the \htmlref{astGetMapping}{astGetMapping} function allows you to extract
+a Mapping from a FrameSet. You do this by specifying the two Frames
+which the Mapping should inter-relate using their indices within the
+FrameSet. For example:
+
+\small
+\begin{terminalv}
+map = astGetMapping( frameset, 2, 3 );
+\end{terminalv}
+\normalsize
+
+would return a pointer to a Mapping that converted between Frames~2
+and 3 in the FrameSet. Its inverse transformation would then convert
+in the opposite direction, \emph{i.e.}\ between Frames~3 and 2.  Note
+that this Mapping might not be independent of the Mappings contained
+within the FrameSet---\emph{i.e.}\ they may share sub-Objects---so
+\htmlref{astCopy}{astCopy} should be used to make a copy if you need to guarantee
+independence (\secref{ss:copyingobjects}).
+
+Very often, the Mapping returned by astGetMapping will be a compound
+Mapping, or \htmlref{CmpMap}{CmpMap} (\secref{ss:cmpmaps}). This reflects the fact that
+conversion between the two Frames may need to be done \emph{via} an
+intermediate coordinate system so that several stages may be involved.
+You can, however, easily simplify this Mapping (where this is possible)
+by using the \htmlref{astSimplify}{astSimplify} function (\secref{ss:simplifyingcmpmaps}) and
+this is recommended if you plan to use it for transforming a large
+amount of data.
+
+\subsection{\label{ss:framesetasframe}Using a FrameSet as a Frame}
+
+A \htmlref{FrameSet}{FrameSet} can also be used as a \htmlref{Frame}{Frame}, in which capacity it almost
+always behaves as if its current Frame had been used instead. For
+example, if you request the \htmlref{Title}{Title} attribute of a FrameSet using:
+
+\small
+\begin{terminalv}
+const char *title;
+
+...
+
+title = astGetC( frameset, "Title" );
+\end{terminalv}
+\normalsize
+
+the result will be the Title of the current Frame, or a suitable
+default if the current Frame's Title attribute is un-set. The same
+also applies to other attribute operations---\emph{i.e.}\ setting,
+clearing and testing attributes.  Most attributes shared by both
+Frames and FrameSets behave in this way, such as \htmlref{Naxes}{Naxes}, \htmlref{Label(axis)}{Label(axis)},
+\htmlref{Format(axis)}{Format(axis)}, \emph{etc.} There are, however, a few exceptions:
+
+\begin{quote}
+\begin{description}
+\item[\htmlref{Class}{Class}]\mbox{}\\
+Has the value ``FrameSet''.
+
+\item[\htmlref{ID}{ID}]\mbox{}\\
+Identifies the particular FrameSet (not its current Frame).
+
+\item[\htmlref{Nin}{Nin}]\mbox{}\\
+Equals the number of axes in the FrameSet's base Frame.
+
+\item[\htmlref{Invert}{Invert}]\mbox{}\\
+Is independent of any of the Objects within the FrameSet.
+
+\item[\htmlref{Nobject}{Nobject}]\mbox{}\\
+Counts the number of active FrameSets.
+
+\item[\htmlref{RefCount}{RefCount}]\mbox{}\\
+Counts the number of active pointers to the FrameSet (not to its
+current Frame).
+\end{description}
+\end{quote}
+
+Note that the set of attributes possessed by a FrameSet can vary,
+depending on the nature of its current Frame. For example, if the
+current Frame is a \htmlref{SkyFrame}{SkyFrame} (\secref{ss:skyframes}), then the FrameSet
+will acquire an \htmlref{Equinox}{Equinox} attribute from it which can be set, enquired,
+\emph{etc.}  However, if the current Frame is changed to be a basic
+Frame, which does not have an Equinox attribute, then this attribute
+will be absent from the FrameSet as well. Any attempt to reference it
+will then result in an error.
+
+\subsection{Extracting a Frame from a FrameSet}
+
+Although a \htmlref{FrameSet}{FrameSet} may be used in place of its current \htmlref{Frame}{Frame} in most
+situations, it is sometimes convenient to have direct access to a
+specified Frame within it. This may be obtained using the \htmlref{astGetFrame}{astGetFrame}
+function, as follows:
+
+\small
+\begin{terminalv}
+frame = astGetFrame( frameset, AST__BASE );
+\end{terminalv}
+\normalsize
+
+This would return a pointer (not a copy) to the base Frame within the
+FrameSet. Note the use of AST\_\_BASE
+(\secref{ss:astbaseandastcurrent}) as shorthand for the value of the
+FrameSet's \htmlref{Base}{Base} attribute, which gives the base Frame's index.
+
+\subsection{Removing a Frame from a FrameSet}
+
+Removing a \htmlref{Frame}{Frame} from a \htmlref{FrameSet}{FrameSet} is straightforward and is performed
+using the \htmlref{astRemoveFrame}{astRemoveFrame} function. You identify the Frame you wish to
+remove in the usual way, by giving its index within the FrameSet. For
+example, the following would remove the Frame with index 1:
+
+\small
+\begin{terminalv}
+astRemoveFrame( frameset, 1 );
+\end{terminalv}
+\normalsize
+
+The only restriction is that you cannot remove the last remaining
+Frame because a FrameSet must always contain at least one Frame.  When
+a Frame is removed, the Frames which follow it are re-numbered
+(\emph{i.e.}\ their indices are reduced by one) so as to preserve the
+sequence of consecutive Frame indices.  The FrameSet's \htmlref{Nframe}{Nframe}
+attribute is also decremented.
+
+If appropriate, astRemoveFrame will modify the FrameSet's \htmlref{Base}{Base} and/or
+\htmlref{Current}{Current} attributes so that they continue to identify the same Frames
+as previously. If either the base or current Frame is removed,
+however, the corresponding attribute will become un-set, so that it
+reverts to its default value (\secref{ss:baseandcurrentdefault}) and
+therefore identifies an alternative Frame.
+
+Note that it is quite permissible to remove any Frame from a FrameSet,
+even although other Frames may appear to depend on it. For example, in
+Figure~\ref{fig:fsexample}, if Frame~1 were removed, the correct
+relationship between Frames~2 and 3 would still be preserved, although
+they would be re-numbered as Frames~1 and 2.
+
+\cleardoublepage
+\section{\label{ss:fshigher}Higher Level Operations on FrameSets}
+
+\subsection{\label{ss:framesetsfromconvert}Creating FrameSets with astConvert}
+
+Before considering the important subject of using FrameSets to convert
+between coordinate systems (\secref{ss:framesetconverting}), let us
+return briefly to reconsider the output generated by \htmlref{astConvert}{astConvert}. We
+used this function earlier (\secref{ss:introducingconversion}), when
+converting between the coordinate systems represented by various kinds
+of \htmlref{Frame}{Frame}, and indicated that it returns a \htmlref{FrameSet}{FrameSet} to represent the
+coordinate conversion it identifies. We are now in a position to
+examine the structure of this FrameSet.
+
+Take our earlier example (\secref{ss:convertingskyframes}) of
+converting between the celestial coordinate systems represented by two
+SkyFrames:
+
+\small
+\begin{terminalv}
+#include "ast.h"
+AstFrameSet *cvt;
+AstSkyFrame *skyframe1, *skyframe2;
+
+...
+
+skyframe1 = astSkyFrame( "System=FK4-NO-E, Epoch=B1958, Equinox=B1960" );
+skyframe2 = astSkyFrame( "System=Ecliptic, Equinox=J2010.5" );
+
+cvt = astConvert( skyframe1, skyframe2, "" );
+\end{terminalv}
+\normalsize
+
+   This will produce a pointer, ``cvt'', to the FrameSet shown in
+   Figure~\ref{fig:fsconvert}.
+   \begin{figure}[bhtp]
+   \begin{center}
+   \includegraphics[width=0.7\textwidth]{sun211_figures/fsconvert}
+   \caption[FrameSet produced when converting between two SkyFrames.]{The FrameSet produced when astConvert is used to convert
+   between the coordinate systems represented by two SkyFrames. The
+   source \htmlref{SkyFrame}{SkyFrame} becomes the base Frame, while the destination SkyFrame
+   becomes the current Frame. The \htmlref{Mapping}{Mapping} between them implements the
+   required conversion.}
+   \label{fig:fsconvert}
+   \end{center}
+   \end{figure}
+
+As can be seen, this FrameSet contains just two Frames.  The source
+Frame supplied to astConvert becomes its base Frame, while the
+destination Frame becomes its current Frame. (The FrameSet, of course,
+simply holds pointers to these Frames, rather than making copies.) The
+Mapping which relates the base Frame to the current Frame is the one
+which implements the required conversion.
+
+As we noted earlier (\secref{ss:convertingskyframes}), the FrameSet
+returned by astConvert may be used both as a Mapping and as a Frame to
+perform most of the functions you are likely to need. However, the
+Mapping may be extracted for use on its own if necessary, using
+\htmlref{astGetMapping}{astGetMapping} (\secref{ss:extractingamapping}), for example:
+
+\small
+\begin{terminalv}
+AstMapping *mapping;
+
+...
+
+mapping = astGetMapping( cvt, AST__BASE, AST__CURRENT );
+\end{terminalv}
+\normalsize
+
+\subsection{\label{ss:framesetconverting}Converting between FrameSet Coordinate Systems}
+
+   We now consider the process of converting between the coordinate
+   systems represented by two FrameSets. This is a most important
+   operation, as a subsequent example (\secref{ss:registeringimages})
+   will show, and is illustrated in Figure~\ref{fig:fsalign}.
+   \begin{figure}
+   \begin{center}
+   \includegraphics[width=0.7\textwidth]{sun211_figures/fsalign}
+   \caption[Conversion between two FrameSets is performed by establishin a link between a pair of Frames, one from each FrameSet.]{Conversion
+   between two FrameSets is performed by establishing
+   a link between a pair of Frames, one from each \htmlref{FrameSet}{FrameSet}. If conversion
+   between these two Frames is possible, then a route for converting
+   between the current Frames of both FrameSets can also be found. In
+   practice, there may be many ways of pairing Frames to find the
+   ``missing link'', so the Frames' \htmlref{Domain}{Domain} attribute may be used to
+   narrow the choice.}
+   \label{fig:fsalign}
+   \end{center}
+   \end{figure}
+
+Recalling (\secref{ss:framesetasframe}) that a FrameSet will behave
+like its current \htmlref{Frame}{Frame} when necessary, conversion between two
+FrameSets is performed using \htmlref{astConvert}{astConvert}
+(\secref{ss:convertingskyframes}), but supplying pointers to FrameSets
+instead of Frames. The effect of this is to convert between the
+coordinate systems represented by the current Frames of each FrameSet:
+
+\small
+\begin{terminalv}
+AstFrameSet *frameseta, *framesetb;
+
+...
+
+cvt = astConvert( frameseta, framesetb, "SKY" );
+\end{terminalv}
+\normalsize
+
+When using FrameSets, we are presented with considerably more
+conversion options than when using Frames alone. This is because each
+current Frame is related to all the other Frames in its respective
+FrameSet. Therefore, if we can establish a link between any pair of
+Frames, one from each FrameSet, we can form a complete conversion path
+between the two current Frames (Figure~\ref{fig:fsalign}).
+
+This expanded range of options is, of course, precisely the
+intention. By connecting Frames together within a FrameSet, we have
+extended the range of coordinate systems that can be reached from any
+one of them.  We are therefore no longer restricted to converting
+between Frames with the same Domain value (\secref{ss:framedomains}),
+but can go \emph{via} a range of intermediate coordinate systems in
+order to make the connection we require. Transformation between
+different domains has therefore become possible because, in assembling
+the FrameSets, we provided the additional information needed to
+inter-relate them.
+
+It is important to appreciate, however, that the choice of ``missing
+link'' is crucial in determining the conversion that results.
+Although each FrameSet may be perfectly self-consistent internally,
+this does not mean that all conversion paths through the combined
+network of Mappings are equivalent. Quite the contrary in fact:
+everything depends on where the inter-connecting link between the two
+FrameSets is made.  In practice, there may be a large number of
+possible pairings of Frames and hence of possible links. Other factors
+must therefore be used to restrict the choice. These are:
+
+\begin{enumerate}
+\item Not every possible pairing of Frames is legitimate. For example,
+you cannot convert directly between a basic Frame and a \htmlref{SkyFrame}{SkyFrame} which
+belong to different classes, so such pairings will be ignored.
+
+\item In a similar way, you cannot convert directly between Frames
+with different Domain values (\secref{ss:framedomains}). If the Domain
+attribute is used consistently (typically only one Frame in each
+FrameSet will have a particular Domain value), then this further
+restricts the choice.
+
+\item The third argument of astConvert may then be used to specify
+explicitly which Domain value the paired Frames should have. You may
+also supply a comma-separated list of preferences here (see below).
+
+\item If the above steps fail to uniquely identify the link, then the
+first suitable pairing of Frames is used, so that any ambiguity is
+resolved by the order in which Frames are considered for pairing (see
+the description of the astConvert function in
+\appref{ss:functiondescriptions} for details of the search
+order).\footnote{If you find that how this ambiguity is resolved
+actually makes a difference to the conversion that results, then you
+have probably constructed a FrameSet which lacks internal
+self-consistency. For example, you might have two Frames representing
+indistinguishable coordinate systems but inter-related by a non-null
+\htmlref{Mapping}{Mapping}.}
+\end{enumerate}
+
+In the example above we supplied the string ``SKY'' as the third
+argument of astConvert. This constitutes a request that a pair of
+Frames with
+the Domain value SKY (\emph{i.e.}\ representing celestial coordinate
+systems) should be used to inter-relate the two FrameSets. Note that
+this does not specify which celestial coordinate system to use, but is
+a general request that the two FrameSets be inter-related using
+coordinates on the celestial sphere.
+
+Of course, it may be that this request cannot be met because there may
+not be a celestial coordinate system in both FrameSets. If this is
+likely to happen, we can supply a list of preferences, or a
+\emph{domain search path},
+as the third argument to astConvert, such as
+the following:
+
+\small
+\begin{terminalv}
+cvt = astConvert( frameseta, framesetb, "SKY,PIXEL,GRID," );
+\end{terminalv}
+\normalsize
+
+Now, if the two FrameSets cannot be inter-related using the SKY domain,
+astConvert will attempt to use the PIXEL domain instead. If this
+also fails, it will try the GRID domain. A blank field in the domain
+search path (here indicated by the final comma) allows any Domain
+value to be used. This can be employed as a last resort when all else
+has failed.
+
+If astConvert succeeds in identifying a conversion, it will return a
+pointer to a FrameSet (\secref{ss:framesetsfromconvert}) in which the
+source and destination Frames are inter-connected by the required
+Mapping. In this case, of course, these Frames will be the current
+Frames of the two FrameSets, but in all other respects the returned
+FrameSet is the same as when converting between Frames.
+
+Very importantly, however, astConvert may modify the FrameSets you are
+converting between. It does this, in order to indicate which pairing
+of Frames was used to inter-relate them, by changing the \htmlref{Base}{Base}
+attribute for each FrameSet so that the Frame used in the pairing
+becomes its base Frame (\secref{ss:baseandcurrent}).
+
+Finally, note that astConvert may also be used to convert between a
+FrameSet and a Frame, or \emph{vice versa}. If a pointer to a Frame is
+supplied for either the first or second argument, it will behave like
+a FrameSet containing only a single Frame.
+
+\subsection{\label{ss:registeringimages}Example---Registering Two Images}
+
+Consider two images which have been calibrated by attaching FrameSets
+to them, such that the base \htmlref{Frame}{Frame} of each \htmlref{FrameSet}{FrameSet} corresponds to the
+raw data grid coordinates of each image (the GRID domain of
+\secref{ss:domainconventions}). Suppose, also, that these FrameSets
+contain an unknown number of other Frames, representing alternative
+world coordinate systems.  What we wish to do is register these two
+images, such that we can transform from a position in the data grid of
+one into the corresponding position in the data grid of the other.
+This is a very practical example because images will typically be
+calibrated using FrameSets in precisely this way.
+
+The first step will probably involve making a copy of both FrameSets
+(using \htmlref{astCopy}{astCopy}---\secref{ss:copyingobjects}), since we will be
+modifying them. Let ``frameseta'' and ``framesetb'' be pointers to
+these copies. Since we want to convert between the base Frames of
+these FrameSets (\emph{i.e.}\ their data grid coordinates), the next
+step is to make these Frames current. This is simply done by inverting
+both FrameSets, which interchanges their base and current
+Frames. \htmlref{astInvert}{astInvert} will perform this task:
+
+\small
+\begin{terminalv}
+astInvert( frameseta );
+astInvert( framesetb );
+\end{terminalv}
+\normalsize
+
+To identify the required conversion, we now use \htmlref{astConvert}{astConvert}, supplying
+a suitable domain search path with which we would like our two images
+to be registered:
+
+\small
+\begin{terminalv}
+cvt = astConvert( frameseta, framesetb, "SKY,PIXEL,GRID" );
+if ( cvt == AST__NULL ) {
+   <no conversion was possible>
+} else {
+   <conversion was possible>
+}
+\end{terminalv}
+\normalsize
+
+The effects of this are:
+
+\begin{enumerate}
+\item astConvert first attempts to register the two images on the
+celestial sphere (\emph{i.e.}\ using the SKY domain). To do this, it
+searches for a celestial coordinate system, although not necessarily
+the same one, attached to each image.  If it finds a suitable pair of
+coordinate systems, it then registers the images by matching
+corresponding positions on the sky.
+
+\item If this fails, astConvert next tries to match positions in the
+PIXEL domain (\secref{ss:framedomains}). If it succeeds, the two
+images will then be registered so that their corresponding pixel
+positions correspond. If the PIXEL domain is offset from the data grid
+(as typically happens in data reduction systems which implement a
+``pixel origin''), then this will be correctly accounted for.
+
+\item If this also fails, the GRID domain is finally used. This will
+result in image registration by matching corresponding points in the
+data grids used by both images. This means they will be
+aligned so that the first element their data arrays correspond.
+
+\item If all of the above fail, astConvert will return the value
+AST\_\_NULL. Otherwise a pointer to a FrameSet will be returned.
+\end{enumerate}
+
+The resulting ``cvt'' FrameSet may then be used directly
+(\secref{ss:convertingskyframes}) to convert between positions in the
+data grid of the first image and corresponding positions in the data
+grid of the second image.
+
+To determine which domain was used to achieve registration,
+we can use the fact that the \htmlref{Base}{Base} attribute of each FrameSet is set by
+astConvert to indicate which intermediate Frames were used. We
+can therefore simply invert either FrameSet (to make its base Frame
+become the current one) and then enquire the \htmlref{Domain}{Domain} value:
+
+\small
+\begin{terminalv}
+const char *domain;
+
+...
+
+astInvert( frameseta );
+domain = astGetC( frameseta, "Domain" );
+\end{terminalv}
+\normalsize
+
+If conversion was successful, the result will be one of the strings
+``SKY'', ``PIXEL'' or ``GRID''.
+
+\subsection{\label{ss:remapframe}Re-Defining a FrameSet Coordinate System}
+
+As discussed earlier (\secref{ss:baseandcurrent}), an important
+application of a \htmlref{FrameSet}{FrameSet} is to allow coordinate system information to
+be attached to entities such as images in order to calibrate them. In
+addition, one of the main objectives of AST is to simplify the
+propagation of such information through successive stages of data
+processing, so that it remains consistent with the associated image
+data.
+
+In such a situation, the FrameSet's base \htmlref{Frame}{Frame} would correspond with
+the image's data grid coordinates and its other Frames (if any) with
+the various alternative world coordinate systems associated with the
+image.  If the data processing being performed does not change the
+relationship between the image's data grid coordinates and any of the
+associated world coordinate systems, then propagation of the WCS
+information is straightforward and simply involves copying the
+FrameSet associated with the image.
+
+If any of these relationships change, however, then corresponding
+changes must be made to the way Frames within the FrameSet are
+inter-related. By far the most common case occurs when the image
+undergoes some geometrical transformation resulting in ``re-gridding''
+on to another data grid, but the same principles can be applied to any
+re-definition of a coordinate system.
+
+To pursue the re-gridding example, we would need to modify our
+FrameSet to account for the fact that the image's data grid coordinate
+system (corresponding to the FrameSet's base Frame) has
+changed. Looking at the steps needed in detail, we might proceed as
+follows:
+
+\begin{enumerate}
+\item Create a \htmlref{Mapping}{Mapping} which represents the relationship between the
+original data grid coordinate system and the new one.
+
+\item Obtain a Frame to represent the new data grid coordinate system
+(we could re-use the original base Frame here, using \htmlref{astGetFrame}{astGetFrame} to
+obtain a pointer to it).
+
+\item Add the new Frame to the FrameSet, related to the original base
+Frame by the new Mapping. This Frame now represents the new data grid
+coordinate system and is correctly related to all the other Frames
+present.\footnote{This is because any transformation to or from this
+new Frame must go \emph{via} the base Frame representing the original
+data grid coordinate system, which we assume was correctly related to
+all the other Frames present.}
+
+\item Remove the original base Frame (representing the old data grid
+coordinate system).
+
+\item Make the new Frame the base Frame and restore the original
+current Frame.
+\end{enumerate}
+
+   The effect of these steps is to change the relationship between the
+   base Frame and all the other Frames present. It is as if a new Mapping
+   has been interposed between the Frame we want to alter and all the
+   other Frames within the FrameSet (Figure~\ref{fig:fsremap}).
+   \begin{figure}[hbtp]
+   \begin{center}
+   \includegraphics[width=0.7\textwidth]{sun211_figures/fsremap}
+\caption[Interposing a Mapping into a FrameSet]{The effect
+   of \htmlref{astRemapFrame}{astRemapFrame} is to interpose a Mapping between
+   a nominated Frame within a FrameSet and the remaining contents of the
+   FrameSet. This effectively ``re-defines'' the coordinate system
+   represented by the affected Frame. It may be used to compensate (say)
+   for geometrical changes made to an associated image. The
+   inter-relationships between all the other Frames within the FrameSet
+   remain unchanged.}
+   \label{fig:fsremap}
+   \end{center}
+   \end{figure}
+
+Performing the steps above is rather lengthy, however, so the
+astRemapFrame function is provided to perform all of these operations
+in one go. A practical example of its use is given below
+(\secref{ss:wcsprocessingexample}).
+
+\subsection{\label{ss:wcsprocessingexample}Example---Binning an Image}
+
+As an example of using \htmlref{astRemapFrame}{astRemapFrame}, consider a case where the pixels
+of a 2-dimensional image have been binned 2$\times$2, so as to reduce
+the image size by a factor of two in each dimension.  We must now
+modify the associated \htmlref{FrameSet}{FrameSet} to reflect this change to the
+image. Much the same process would be needed for any other geometrical
+change the image might undergo.
+
+We first set up a \htmlref{Mapping}{Mapping} (a \htmlref{WinMap}{WinMap} in this case) which relates the
+data grid coordinates in the original image to those in the new one:
+
+\small
+\begin{terminalv}
+AstWinMap *winmap;
+double ina[ 2 ] = { 0.5, 0.5 };
+double inb[ 2 ] = { 2.5, 2.5 };
+double outa[ 2 ] = { 0.5, 0.5 };
+double outb[ 2 ] = { 1.5, 1.5 };
+
+...
+
+winmap = astWinMap( 2, ina, inb, outa, outb, "" );
+\end{terminalv}
+\normalsize
+
+Here, we have simply set up arrays containing the data grid
+coordinates of the bottom left and top right corners of the first
+element in the output image (``outa'' and ``outb'') and the
+corresponding coordinates in the input image (``ina'' and
+``inb''). \htmlref{astWinMap}{astWinMap} then creates a WinMap which performs the required
+transformation. We do not need to know the size of the image.
+
+We can then pass this WinMap to astRemapFrame. This modifies the
+relationship between our FrameSet's base \htmlref{Frame}{Frame} and the other Frames in
+the FrameSet, so that the base Frame represents the data grid
+coordinate system of the new image rather than the old one:
+
+\small
+\begin{terminalv}
+AstFrameSet *frameset;
+
+...
+
+astRemapFrame( frameset, AST__BASE, winmap );
+\end{terminalv}
+\normalsize
+
+Any other coordinate systems described by the FrameSet, no matter how
+many of these there might be, are now correctly associated with the
+new image.
+
+\subsection{\label{ss:framesetintegrity}Maintaining the Integrity of FrameSets}
+
+When constructing a \htmlref{FrameSet}{FrameSet}, you are provided with a framework into
+which you can place any combination of Frames and Mappings that you
+wish. There are relatively few constraints on this process and no
+checks are performed to see whether the FrameSet you construct makes
+physical sense.  It is quite possible, for example, to construct a
+FrameSet containing two identical SkyFrames which are inter-related by
+a non-unit \htmlref{Mapping}{Mapping}. AST will not object if you do this, but it makes
+no sense, because applying a non-unit Mapping to any set of celestial
+coordinates cannot yield positions that are still in the original
+coordinate system.  If you use such a FrameSet to perform coordinate
+conversions, you are likely to get unpredictable results because the
+information in the FrameSet is corrupt.
+
+It is, of course, your responsibility as a programmer to ensure the
+validity of any information which you insert into a
+FrameSet. Normally, this is straightforward and simply consists of
+formulating your problem correctly (a diagram can often help to
+clarify how coordinate systems are inter-related) and writing the
+appropriate bug-free code to construct the FrameSet. However, once you
+start to modify an existing FrameSet, there are new opportunities for
+corrupting it!
+
+Consider, for example, a FrameSet whose current \htmlref{Frame}{Frame} is a
+\htmlref{SkyFrame}{SkyFrame}. We can set a new value for this SkyFrame's \htmlref{Equinox}{Equinox} attribute
+simply by using \htmlref{astSet}{astSet} on the FrameSet, as follows:
+
+\small
+\begin{terminalv}
+astSet( frameset, "Equinox=J2010" );
+\end{terminalv}
+\normalsize
+
+The effect of this will be to change the celestial coordinate system
+which the current Frame represents. You can see, however, that this
+has the potential to make the FrameSet corrupt unless corresponding
+changes are also made to the Mapping which relates this SkyFrame to
+the other Frames within the FrameSet. In fact, it is a general rule
+that any change to a FrameSet which affects its current Frame can
+potentially require corresponding changes to the FrameSet's Mappings
+in order to maintain its overall integrity.
+
+Fortunately, once you have stored valid information in a FrameSet, AST
+will look after these details for you automatically, so that the
+FrameSet's integrity is maintained. In the example above, it would do
+this by appropriately re-mapping the current Frame (as if
+\htmlref{astRemapFrame}{astRemapFrame} had been used---\secref{ss:remapframe}) in response to
+the use of astSet. One way of illustrating this process is as follows:
+
+\small
+\begin{terminalv}
+AstSkyFrame *skyframe;
+
+...
+
+skyframe = astSkyFrame( "" );
+frameSet = astFrameSet( skyframe );
+astAddFrame( frameset, 1, astUnitMap( 2, "" ), skyframe );
+\end{terminalv}
+\normalsize
+
+This constructs a trivial FrameSet whose base and current Frames are
+both the same SkyFrame connected by a \htmlref{UnitMap}{UnitMap}. You can think of this
+as a ``pipe'' connecting two coordinate systems. At present, these two
+systems represent identical ICRS coordinates, so the FrameSet
+implements a unit Mapping. We can change the coordinate system on the
+current end of this pipe as follows:
+
+\small
+\begin{terminalv}
+astSet( frameset, "System=Ecliptic, Equinox=J2010" );
+\end{terminalv}
+\normalsize
+
+and the Mapping which the FrameSet implements would change
+accordingly. To change the coordinate system on the base end of the
+pipe, we might use:
+
+\small
+\begin{terminalv}
+astInvert( frameset );
+astSet( frameset, "System=Galactic" );
+astInvert( frameset );
+\end{terminalv}
+\normalsize
+
+The FrameSet would then convert between galactic and ecliptic
+coordinates.
+
+Note that astSet is not the only function which has this effect:
+\htmlref{astClear}{astClear} behaves similarly, as also does \htmlref{astPermAxes}{astPermAxes}
+(\secref{ss:permutingaxes}). If you need to circumvent this mechanism
+for any reason, this can be done by going behind the scenes and
+obtaining a pointer directly to the Frame you wish to modify. Consider
+the following, for example:
+
+\small
+\begin{terminalv}
+skyframe = astGetFrame( frameset, AST__CURRENT );
+astSet( skyframe, "Equinox=J2010" );
+skyframe = astAnnul( skyframe );
+\end{terminalv}
+\normalsize
+
+Here, astSet is applied to the SkyFrame pointer rather than the
+FrameSet pointer, so the usual checks on FrameSet integrity do not
+occur. The SkyFrame's Equinox attribute will therefore be modified
+without any corresponding change to the FrameSet's Mappings.  In this
+case you must take responsibility yourself for maintaining the
+FrameSet's integrity, perhaps through appropriate use of
+astRemapFrame.
+
+\subsection{Merging FrameSets}
+
+   As well as adding individual Frames to a \htmlref{FrameSet}{FrameSet}
+   (\secref{ss:addingframes}), it is also possible to add complete sets of
+   inter-related Frames which are contained within another
+   FrameSet. This, of course, corresponds to the process of merging two
+   FrameSets (Figure~\ref{fig:fsmerge}).
+   \begin{figure}[hbtp]
+   \begin{center}
+   \includegraphics[width=0.7\textwidth]{sun211_figures/fsmerge}
+   \caption[Two FrameSets in the process of being merged.]{Two FrameSets in the process of being merged using
+   \htmlref{astAddFrame}{astAddFrame}. FrameSet~B is being added to FrameSet~A by supplying a
+   new \htmlref{Mapping}{Mapping} which inter-relates a nominated \htmlref{Frame}{Frame} in A (here number~1)
+   and the current Frame of B. In the merged FrameSet, the Frames
+   contributed by B will be re-numbered to become Frames~4, 5 and 6. The
+   base Frame will remain unchanged, but the current Frame of B becomes
+   the new current Frame. Note that FrameSet~B itself is not
+   altered by this process.}
+   \label{fig:fsmerge}
+   \end{center}
+   \end{figure}
+
+
+
+This process is performed by adding one FrameSet to another using
+astAddFrame, in much the same manner as when adding a new Frame to an
+existing FrameSet (\secref{ss:addingframes}). It is simply a matter of
+providing a FrameSet pointer, instead of a Frame pointer, for the 4th
+argument. In performing the merger you must, as usual, supply a
+Mapping, but in this case the Mapping should relate the current Frame
+of the FrameSet being added to one of the Frames already present. For
+example, you might perform the merger shown in
+Figure~\ref{fig:fsmerge} as follows:
+
+\small
+\begin{terminalv}
+AstMapping *mapping;
+
+...
+
+astAddFrame( frameseta, 1, mapping, framesetb );
+\end{terminalv}
+\normalsize
+
+The Frames acquired by ``frameseta'' from the FrameSet being added
+(``framesetb'') are re-numbered so that they retain their original
+order and follow on consecutively after the Frames that were already
+present, whose indices remain unchanged. The base Frame of
+``frameseta'' remains unchanged, but the current Frame of
+``framesetb'' becomes its new current Frame. All the
+inter-relationships between Frames in both FrameSets remain in place
+and are preserved in the merged FrameSet.
+
+Note that while this process modifies the first FrameSet
+(``frameseta''), it leaves the original contents of the one being
+added (``framesetb'') unchanged.
+
+%\cleardoublepage
+%\section{\label{ss:searching}TBW - Searching for Coordinate Systems}
+
+\cleardoublepage
+\section{\label{ss:channels}Saving and Restoring Objects (Channels)}
+
+Facilities are provided by the AST library for performing input and
+output (I/O) with any kind of \htmlref{Object}{Object}. This means it is possible
+to write any Object into various external representations for
+storage, and then to read these representations back in, so as to
+restore the original Object. Typically, an Object would be written by
+one program and read back in by another.
+
+We refer to ``external representations'' in the plural because AST is
+designed to function independently of any particular data storage
+system. This means that Objects may need converting into a number of
+different external representations in order to be compatible with
+(say) the astronomical data storage system in which they will reside.
+
+In this section, we discuss the basic I/O facilities which support
+external representations based on a textual format referred to as the AST
+``native format''. These are implemented using a new kind of Object---a
+\htmlref{Channel}{Channel}. We will examine later how to use other representations, based on
+an XML format or on the use of FITS headers, for storing Objects. These
+are implemented using more specialised forms of Channel called \htmlref{XmlChan}{XmlChan}
+(\secref{ss:xmlchan}) and \htmlref{FitsChan}{FitsChan} (\secref{ss:nativefits}).
+
+\subsection{The Channel Model}
+
+The best way to start thinking about a \htmlref{Channel}{Channel} is like a C file
+stream, and to think of the process of creating a Channel as that
+of opening a file and obtaining a FILE pointer.  Subsequently, you can
+read and write Objects \emph{via} the Channel.
+
+This analogy is not quite perfect, however, because a Channel has, in
+principle, two ``files'' attached to it. One is used when reading, and
+the other when writing. These are termed the Channel's \emph{source}
+and \emph{sink} respectively. In practice, the source and sink may
+both be the same, in which case the analogy with the C file stream is
+correct, but this need not always be so. It is not necessarily so with
+the basic Channel, as we will now see (\secref{ss:creatingachannel}).
+
+\subsection{\label{ss:creatingachannel}Creating a Channel}
+
+The process of creating a \htmlref{Channel}{Channel} is straightforward. As you
+might expect, it uses the constructor function \htmlref{astChannel}{astChannel}:
+
+\small
+\begin{terminalv}
+#include "ast.h"
+AstChannel *channel;
+
+...
+
+channel = astChannel( NULL, NULL, "" );
+\end{terminalv}
+\normalsize
+
+The first two arguments to astChannel specify the external source and
+sink that the Channel is to use. There arguments are pointers to C
+functions and we will examine their use in more detail later
+(\secref{ss:channelsource} and \secref{ss:channelsink}).
+
+In this very simple example we have supplied NULL pointers for both
+the source and sink functions. This requests the default behaviour,
+which means that textual input will be read from the program's
+standard input stream (typically, this means your keyboard) while
+textual output will go to the standard output stream (typically
+appearing on your screen). On UNIX systems, of course, either of these
+streams can easily be redirected to files. This default behaviour can be
+changed by assigning values to the Channel's \htmlref{SinkFile}{SinkFile} and/or \htmlref{SourceFile}{SourceFile}
+attributes. These attributes specify the paths to text files that are to
+be used in place of the standard input and output streams.
+
+\subsection{\label{ss:writingtoachannel}Writing Objects to a Channel}
+
+The process of saving Objects is very straightforward. You can
+simply write any \htmlref{Object}{Object} to a \htmlref{Channel}{Channel} using the \htmlref{astWrite}{astWrite}
+function, as follows:
+
+\small
+\begin{terminalv}
+int nobj;
+AstObject *object;
+
+...
+
+nobj = astWrite( channel, object );
+\end{terminalv}
+\normalsize
+
+The effect of this will be to produce a textual description of the
+Object which will appear, by default, on your program's standard
+output stream. Any class of Object may be converted into text in this
+way.
+
+astWrite returns a count of the number of Objects written. Usually,
+this will be one, unless the Object supplied cannot be
+represented. With a basic Channel all Objects can be represented, so a
+value of one will always be returned unless there has been an
+error. We will see later, however, that more specialised forms of
+Channel may impose restrictions on the kind of Object you can write
+(\secref{ss:foreignfitslimitations}). In such cases, astWrite may
+return zero to indicate that the Object was not acceptable.
+
+\subsection{\label{ss:readingfromachannel}Reading Objects from a Channel}
+
+Before discussing the format of the output produced above
+(\secref{ss:writingtoachannel}), let us consider how to read it back,
+so as to reconstruct the original \htmlref{Object}{Object}. Naturally, we would first
+need to save the output in a file. We can do that either by using the
+\htmlref{SinkFile}{SinkFile} attribute, or (on UNIX systems), by redirecting standard output
+to a file using a shell command like:
+
+\small
+\begin{terminalv}
+program1 >file
+\end{terminalv}
+\normalsize
+
+Within a subsequent program, we can read this Object back in by
+using the \htmlref{astRead}{astRead} function, having first created a suitable
+\htmlref{Channel}{Channel}:
+
+\small
+\begin{terminalv}
+object = astRead( channel );
+\end{terminalv}
+\normalsize
+
+By default, this function will read from the standard input stream
+(the default source for a basic Channel), so we would need to ensure
+that our second program reads its input from the file in which the
+Object description is stored. On UNIX systems, we could again use a
+shell redirection command such as:
+
+\small
+\begin{terminalv}
+program2 <file
+\end{terminalv}
+\normalsize
+
+Alternatively, we could have assigned a value to the SinkFile attribute
+before invoking
+astRead.
+
+\subsection{Saving and Restoring Multiple Objects}
+
+I/O operations performed on a basic \htmlref{Channel}{Channel} are sequential. This
+means that if you write more than one \htmlref{Object}{Object} to a Channel,
+each new Object's textual description is simply appended to the
+previous one. You can store any number of Objects in this way,
+subject only to the storage space you have available.
+
+After you read an Object back from a basic Channel, the
+Channel is ``positioned'' at the end of that Object's
+textual description. If you then perform another read, you will
+read the next Object's textual description and therefore
+retrieve the next Object.  This process may be repeated to read
+each Object in turn. When there are no more Objects to be
+read, \htmlref{astRead}{astRead} will return the value AST\_\_NULL to indicate an
+\emph{end-of-file}.
+
+\subsection{\label{ss:validatinginput}Validating Input}
+
+The pointer returned by \htmlref{astRead}{astRead} (\secref{ss:readingfromachannel}) could
+identify any class of \htmlref{Object}{Object}---this is determined entirely by the
+external data being read. If it is necessary to test for a particular
+class (say a \htmlref{Frame}{Frame}), this may be done as follows using the appropriate
+member of the \htmlref{astIsA$<$Class$>$}{astIsA$<$Class$>$} family of functions:
+
+\small
+\begin{terminalv}
+int ok;
+
+...
+
+ok = astIsAFrame( object );
+\end{terminalv}
+\normalsize
+
+Note, however, that this will accept any Frame, so would be equally
+happy with a basic Frame or a \htmlref{SkyFrame}{SkyFrame}.  An alternative validation
+strategy would be to obtain the value of the Object's \htmlref{Class}{Class} attribute
+and then test this character string, as follows:
+
+\small
+\begin{terminalv}
+#include <string.h>
+
+...
+
+ok = !strcmp( astGetC( object, "Class" ), "Frame" );
+\end{terminalv}
+\normalsize
+
+This would only accept a basic Frame and would reject a SkyFrame.
+
+\subsection{Storing an ID String with an Object}
+
+Occasionally, you may want to store a number of Objects and later
+retrieve them and use each for a different purpose. If the Objects are
+of the same class, you cannot use the \htmlref{Class}{Class} attribute to distinguish
+them when you read them back
+(\emph{c.f.}~\secref{ss:validatinginput}). Although relying on the
+order in which they are stored is a possible solution, this becomes
+complicated if some of the Objects are optional and may not always be
+present. It also makes extending your data format in future more
+difficult.
+
+To help with this, every AST \htmlref{Object}{Object} has an \htmlref{ID}{ID} attribute and an \htmlref{Ident}{Ident}
+attribute, both of which allows you, in effect, to attach a textual
+identification label to it. You simply set the ID or Ident attribute before
+writing the Object:
+
+\small
+\begin{terminalv}
+astSet( object, "ID=Calibration" );
+nobj = astWrite( channel, object );
+\end{terminalv}
+\normalsize
+
+You can then test its value after you read the Object back:
+
+\small
+\begin{terminalv}
+object = astRead( channel );
+if ( !strcmp( astGetC( object, "ID" ), "Calibration" ) ) {
+   <the Calibration Object has been read>
+} else {
+   <some other Object has been read>
+}
+\end{terminalv}
+\normalsize
+
+The only difference between the ID and Ident attributes is that the ID
+attribute is unique to a particular Object and is lost if, for example,
+you make a copy of the Object. The Ident attrubute, on the other hand, is
+transferred to the new Object when a copy is made. Consequently, it is
+safest to set the value of the ID attribute immediately before you
+perform the write.
+
+\subsection{\label{ss:textualoutputformat}The Textual Output Format}
+
+Let us now examine the format of the textual output produced by
+writing an \htmlref{Object}{Object} to a basic \htmlref{Channel}{Channel}
+(\secref{ss:writingtoachannel}). To give a concrete example, suppose
+the Object in question is a \htmlref{SkyFrame}{SkyFrame}, written out as follows:
+
+\small
+\begin{terminalv}
+AstSkyFrame *skyframe;
+
+...
+
+nobj = astWrite( channel, skyframe );
+\end{terminalv}
+\normalsize
+
+The output should then look like the following:
+
+\small
+\begin{terminalv}
+ Begin SkyFrame 	# Description of celestial coordinate system
+#   Title = "FK4 Equatorial Coordinates, no E-terms, Mean Equinox B1950.0, Epoch B1958.0" 	# Title of coordinate system
+    Naxes = 2 	# Number of coordinate axes
+#   Domain = "SKY" 	# Coordinate system domain
+#   Lbl1 = "Right Ascension" 	# Label for axis 1
+#   Lbl2 = "Declination" 	# Label for axis 2
+#   Uni1 = "hh:mm:ss.s" 	# Units for axis 1
+#   Uni2 = "ddd:mm:ss" 	# Units for axis 2
+#   Dir1 = 0 	# Plot axis 1 in reverse direction (hint)
+    Ax1 = 	# Axis number 1
+       Begin SkyAxis 	# Celestial coordinate axis
+       End SkyAxis
+    Ax2 = 	# Axis number 2
+       Begin SkyAxis 	# Celestial coordinate axis
+       End SkyAxis
+ IsA Frame 	# Coordinate system description
+    System = "FK4-NO-E" 	# Celestial coordinate system type
+    Epoch = 1958 	# Besselian epoch of observation
+#   Eqnox = 1950 	# Besselian epoch of mean equinox
+ End SkyFrame
+\end{terminalv}
+\normalsize
+
+You will notice that this output is designed both for a human reader,
+in that it is formatted, and also to be read back by a computer in
+order to reconstruct the SkyFrame. In fact, this is precisely the way
+that \htmlref{astShow}{astShow} works (\secref{ss:displayingobjects}), this function being
+roughly equivalent to the following use of a Channel:
+
+\small
+\begin{terminalv}
+channel = astChannel( NULL, NULL, "" );
+(void) astWrite( channel, object );
+channel = astAnnul( channel );
+\end{terminalv}
+\normalsize
+
+Some lines of the output start with a ``\verb?#?'' comment character,
+which turns the rest of the line into a comment. These lines will be
+ignored when read back in by \htmlref{astRead}{astRead}.  They typically contain default
+values, or values that can be derived in some way from the other data
+present, so that they do not actually need to be stored in order to
+reconstruct the original Object. They are provided purely for human
+information. The same comment character is also used to append
+explanatory comments to most output lines.
+
+It is not sensible to attempt a complete description of this output
+format because every class of Object is potentially different and each
+can define how its own data should be represented. However, there are
+some basic rules, which mean that the following common features will
+usually be present:
+
+\begin{enumerate}
+\item Each Object is delimited by matching ``Begin'' and ``End''
+lines, which also identify the class of Object involved.
+
+\item Within each Object description, data values are represented
+by a simple ``keyword~$=$~value'' syntax, with one value to a line.
+
+\item Lines beginning ``IsA'' are used to mark the divisions between
+data belonging to different levels in the class hierarchy
+(\appref{ss:classhierarchy}). Thus, ``IsA~\htmlref{Frame}{Frame}'' marks the end of data
+associated with the Frame class and the start of data associated with
+some derived class (a SkyFrame in the above example). ``IsA'' lines
+may be omitted if associated data values are absent and no confusion
+arises.
+
+\item Objects may contain other Objects as data. This is
+indicated by an absent value, with the description of the data
+Object following on subsequent lines.
+
+\item Indentation is used to clarify the overall structure.
+\end{enumerate}
+
+Beyond these general principles, the best guide to what a particular
+line of output represents will generally be the comment which
+accompanies it together with a general knowledge of the class of
+Object being described.
+
+\subsection{\label{ss:controllingchanneloutput}Controlling the Amount of Output}
+
+It is not always necessary for the output from \htmlref{astWrite}{astWrite}
+(\secref{ss:writingtoachannel}) to be human-readable, so a \htmlref{Channel}{Channel} has
+attributes that allow the amount of detail in the output to be
+controlled.
+
+The first of these is the integer attribute \htmlref{Full}{Full}, which controls the
+extent to which optional, commented out, output lines are produced. By
+default, Full is zero, and this results in the standard style of
+output (\secref{ss:textualoutputformat}) where default values that may
+be helpful to humans are included. To suppress these optional lines,
+Full should be set to $-$1. This is most conveniently done when the
+Channel is created, so that:
+
+\small
+\begin{terminalv}
+channel = astChannel( NULL, NULL, "Full=-1" );
+(void) astWrite( channel, skyframe );
+channel = astAnnul( channel );
+\end{terminalv}
+\normalsize
+
+would result in output containing only the essential information, such
+as:
+
+\small
+\begin{terminalv}
+ Begin SkyFrame 	# Description of celestial coordinate system
+    Naxes = 2 	# Number of coordinate axes
+    Ax1 = 	# Axis number 1
+       Begin SkyAxis 	# Celestial coordinate axis
+       End SkyAxis
+    Ax2 = 	# Axis number 2
+       Begin SkyAxis 	# Celestial coordinate axis
+       End SkyAxis
+ IsA Frame 	# Coordinate system description
+    System = "FK4-NO-E" 	# Celestial coordinate system type
+    Epoch = 1958 	# Besselian epoch of observation
+ End SkyFrame
+\end{terminalv}
+\normalsize
+
+In contrast, setting Full to $+$1 will result in additional output
+lines which will reveal every last detail of the \htmlref{Object}{Object}'s
+construction. Often this will be rather more than you want, especially
+for more complex Objects, but it can sometimes help when debugging
+programs. This is how a \htmlref{SkyFrame}{SkyFrame} appears at this level of detail:
+
+\small
+\begin{terminalv}
+ Begin SkyFrame 	# Description of celestial coordinate system
+#   RefCnt = 1 	# Count of active Object pointers
+#   Nobj = 1 	# Count of active Objects in same class
+ IsA Object 	# Astrometry Object
+#   Nin = 2 	# Number of input coordinates
+#   Nout = 2 	# Number of output coordinates
+#   Invert = 0 	# Mapping not inverted
+#   Fwd = 1 	# Forward transformation defined
+#   Inv = 1 	# Inverse transformation defined
+#   Report = 0 	# Don't report coordinate transformations
+ IsA Mapping 	# Mapping between coordinate systems
+#   Title = "FK4 Equatorial Coordinates, no E-terms, Mean Equinox B1950.0, Epoch B1958.0" 	# Title of coordinate system
+    Naxes = 2 	# Number of coordinate axes
+#   Domain = "SKY" 	# Coordinate system domain
+#   Lbl1 = "Right Ascension" 	# Label for axis 1
+#   Lbl2 = "Declination" 	# Label for axis 2
+#   Sym1 = "RA" 	# Symbol for axis 1
+#   Sym2 = "Dec" 	# Symbol for axis 2
+#   Uni1 = "hh:mm:ss.s" 	# Units for axis 1
+#   Uni2 = "ddd:mm:ss" 	# Units for axis 2
+#   Dig1 = 7 	# Individual precision for axis 1
+#   Dig2 = 7 	# Individual precision for axis 2
+#   Digits = 7 	# Default formatting precision
+#   Fmt1 = "hms.1" 	# Format specifier for axis 1
+#   Fmt2 = "dms" 	# Format specifier for axis 2
+#   Dir1 = 0 	# Plot axis 1 in reverse direction (hint)
+#   Dir2 = 1 	# Plot axis 2 in conventional direction (hint)
+#   Presrv = 0 	# Don't preserve target axes
+#   Permut = 1 	# Axes may be permuted to match
+#   MinAx = 2 	# Minimum number of axes to match
+#   MaxAx = 2 	# Maximum number of axes to match
+#   MchEnd = 0 	# Match initial target axes
+#   Prm1 = 1 	# Axis 1 not permuted
+#   Prm2 = 2 	# Axis 2 not permuted
+    Ax1 = 	# Axis number 1
+       Begin SkyAxis 	# Celestial coordinate axis
+#         RefCnt = 1 	# Count of active Object pointers
+#         Nobj = 2 	# Count of active Objects in same class
+       IsA Object 	# Astrometry Object
+#         Label = "Angle on Sky" 	# Axis Label
+#         Symbol = "delta" 	# Axis symbol
+#         Unit = "ddd:mm:ss" 	# Axis units
+#         Digits = 7 	# Default formatting precision
+#         Format = "dms" 	# Format specifier
+#         Dirn = 1 	# Plot in conventional direction
+       IsA Axis 	# Coordinate axis
+#         Format = "dms" 	# Format specifier
+#         IsLat = 0 	# Longitude axis (not latitude)
+#         AsTime = 0 	# Display values as angles (not times)
+       End SkyAxis
+    Ax2 = 	# Axis number 2
+       Begin SkyAxis 	# Celestial coordinate axis
+#         RefCnt = 1 	# Count of active Object pointers
+#         Nobj = 2 	# Count of active Objects in same class
+       IsA Object 	# Astrometry Object
+#         Label = "Angle on Sky" 	# Axis Label
+#         Symbol = "delta" 	# Axis symbol
+#         Unit = "ddd:mm:ss" 	# Axis units
+#         Digits = 7 	# Default formatting precision
+#         Format = "dms" 	# Format specifier
+#         Dirn = 1 	# Plot in conventional direction
+       IsA Axis 	# Coordinate axis
+#         Format = "dms" 	# Format specifier
+#         IsLat = 0 	# Longitude axis (not latitude)
+#         AsTime = 0 	# Display values as angles (not times)
+       End SkyAxis
+ IsA Frame 	# Coordinate system description
+    System = "FK4-NO-E" 	# Celestial coordinate system type
+    Epoch = 1958 	# Besselian epoch of observation
+#   Eqnox = 1950 	# Besselian epoch of mean equinox
+ End SkyFrame
+\end{terminalv}
+\normalsize
+
+\subsection{\label{ss:channelcommenting}Controlling Commenting}
+
+Another way of controlling output from a \htmlref{Channel}{Channel} is \emph{via} the
+boolean (integer) \htmlref{Comment}{Comment} attribute, which controls whether comments
+are appended to describe the purpose of each value. Comment has the
+value 1 by default but, if set to zero, will suppress these
+comments. This is normally appropriate only if you wish to minimise
+the amount of output, for example:
+
+\small
+\begin{terminalv}
+astSet( channel, "Full=-1, Comment=0" );
+nobj = astWrite( channel, skyframe );
+\end{terminalv}
+\normalsize
+
+might result in the following more compact output:
+
+\small
+\begin{terminalv}
+ Begin SkyFrame
+    Naxes = 2
+    Ax1 =
+       Begin SkyAxis
+       End SkyAxis
+    Ax2 =
+       Begin SkyAxis
+       End SkyAxis
+ IsA Frame
+    System = "FK4-NO-E"
+    Epoch = 1958
+ End SkyFrame
+\end{terminalv}
+\normalsize
+
+\subsection{Editing Textual Output}
+
+The safest advice about editing the textual output from \htmlref{astWrite}{astWrite} (or
+\htmlref{astShow}{astShow}) is ``don't!''---unless you know what you are doing.
+
+Having given that warning, however, it is sometimes possible to make
+changes to the text, or even to write entire \htmlref{Object}{Object} descriptions from
+scratch, and to read the results back in to construct new
+Objects. Normally, simple changes to numerical values are safest, but
+be aware that this is a back door method of creating Objects, so
+you are on your own! There are a number of potential pitfalls. In
+particular:
+
+\begin{itemize}
+\item \htmlref{astRead}{astRead} is intended for retrieving data written by astWrite and
+not for reading data input by humans. As such, the data validation
+provided is very limited and is certainly not foolproof. This makes it
+quite easy to construct Objects that are internally inconsistent by
+this means. In contrast, the normal programming interface incorporates
+numerous checks designed to make it impossible to construct invalid
+Objects. You should not necessarily think you have found a bug if your
+changes to an Object's textual description fail to produce the results
+you expected!
+
+\item In many instances the names associated with values in textual
+output will correspond with Object attributes. Sometimes, however,
+these names may differ from the attribute name. This is mainly because
+of length restrictions imposed by other common external formats, such
+as FITS headers. Some of the names used do not correspond with
+attributes at all.
+
+\item It is safest to change single numerical or string values.
+Beware of changing the size or shape of Objects (\emph{e.g.}\ the
+number of axes in a \htmlref{Frame}{Frame}). Often, these values must match others
+stored elsewhere within the Object and changing them in a haphazard
+fashion will not produce useful results.
+
+\item Be wary about un-commenting default values. Sometimes this will
+work, but often these values are derived from other Objects stored
+more deeply in the structure and the proper place to insert a new
+value is not where the default itself appears.
+\end{itemize}
+
+\subsection{\label{ss:mixingchanneltext}Mixing Objects with other Text}
+
+By default, when you use \htmlref{astRead}{astRead} to read from a basic \htmlref{Channel}{Channel}
+(\secref{ss:readingfromachannel}), it is assumed that you are reading a
+stream of text containing only AST Objects, which follow each other
+end-to-end. If any extraneous input data are encountered which do not
+appear to form part of the textual description of an \htmlref{Object}{Object}, then an
+error will result. In particular, the first input line must identify
+the start of an Object description, so you cannot start reading half
+way through an Object.
+
+Sometimes, however, you may want to store AST Object descriptions
+intermixed with other textual data. You can do this by setting the
+Channel's boolean (integer) \htmlref{Skip}{Skip} attribute to 1. This will cause every
+read to skip over extraneous data until the start of a new AST Object
+description, if any, is found. So long as your other data do not mimic
+the appearance of an AST Object description, the two sets of data can
+co-exist.
+
+For example, by setting Skip to 1, the following complete C program
+will read all the AST Objects whose descriptions appear in the source
+of this document, ignoring the other text. \htmlref{astShow}{astShow} is used to display
+those found:
+
+\small
+\begin{terminalv}
+#include "ast.h"
+main() {
+   AstChannel *channel;
+   AstObject *object;
+
+   channel = astChannel( NULL, NULL, "Skip=1" );
+   while ( ( object = astRead( channel ) ) != AST__NULL ) {
+      astShow( object );
+      object = astAnnul( object );
+   }
+   channel = astAnnul( channel );
+}
+\end{terminalv}
+\normalsize
+
+\subsection{\label{ss:channelsource}Reading Objects from Files}
+
+Thus far, we have only considered the default behaviour of a \htmlref{Channel}{Channel}
+in reading and writing Objects through a program's standard input and
+output streams. We will now consider how to access Objects stored in
+files more directly.
+
+The simple approach is to use the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes of
+the Channel. For instance, the following will read a pair of Objects from
+a text file called ``fred.txt'':
+
+\small
+\begin{terminalv}
+astSet( channel, "SourceFile=fred.txt" );
+obj1 = astRead( channel );
+obj2 = astRead( channel );
+astClear( channel, "SourceFile" );
+\end{terminalv}
+\normalsize
+
+Note, the act of clearing the attribute tells AST that no more Objects
+are to be read from the file and so the file is then closed. If the
+attribute is not cleared, the file will remain open and further Objects
+can be read from it. The file will always be closed when the Channel is
+deleted.
+
+This simple approach will normally be sufficient. However, because the
+AST library is designed to be used from more than one language, it has
+to be a little careful about reading and writing to files. This is due
+to incompatibilities that may exist between the file I/O facilities
+provided by different languages. If such incompatibilities prevent the
+above simple system being used, we need to adopt a system that off-loads
+all file I/O to external code.
+
+What this means in practice is that if the above simple approach cannot
+be used, you must instead provide some simple C
+functions that perform the actual transfer of data to and from files
+and similar external data stores. The functions you provide are
+supplied as the source and/or sink function arguments to \htmlref{astChannel}{astChannel}
+when you create a Channel (\secref{ss:creatingachannel}). An example is
+the best way to illustrate this.
+
+Consider the following simple function called Source. It reads a
+single line of text from a C input stream and returns a pointer to it,
+or NULL if there is no more input:
+
+\small
+\begin{terminalv}
+#include <stdio.h>
+#define LEN 200
+static FILE *input_stream;
+
+const char *Source( void ) {
+   static char buffer[ LEN + 2 ];
+   return fgets( buffer, LEN + 2, input_stream );
+}
+\end{terminalv}
+\normalsize
+
+Note that the input stream is a static variable which we will also
+access from our main program. This might look something like this
+(omitting error checking for brevity):
+
+\small
+\begin{terminalv}
+/* Open the input file. */
+input_stream = fopen( "infile.ast", "r" );
+
+/* Create a Channel and read an Object from it. */
+channel = astChannel( Source, NULL, "" );
+object = astRead( channel );
+
+...
+
+/* Annul the Channel and close the file when done. */
+channel = astAnnul( channel );
+(void) fclose( input_stream );
+\end{terminalv}
+\normalsize
+
+Here, we first open the required input file, saving the resulting FILE
+pointer. We then pass a pointer to our Source function as the first
+argument to astChannel when creating a new Channel. When we read
+an \htmlref{Object}{Object} from this Channel with \htmlref{astRead}{astRead}, the Source
+function will be called to obtain the textual data from the file, the
+end-of-file being detected when this function returns NULL.
+
+Note, if a value is set for the SourceFile attribute,
+the astRead function will ignore any source function
+specified when the Channel was created.
+
+\subsection{\label{ss:channelsink}Writing Objects to Files}
+
+As for reading, writing Objects to files can be done in two different ways.
+Again, the simple approach is to use the \htmlref{SinkFile}{SinkFile} attribute of the \htmlref{Channel}{Channel}.
+For instance, the following will write a pair of Objects to a text file
+called ``fred.txt'':
+
+\small
+\begin{terminalv}
+astSet( channel, "SinkFile=fred.txt" );
+nobj = astWrite( channel, object1 );
+nobj = astWrite( channel, object2 );
+astClear( channel, "SinkFile" );
+\end{terminalv}
+\normalsize
+
+Note, the act of clearing the attribute tells AST that no more output
+will be written to the file and so the file is then closed. If the
+attribute is not cleared, the file will remain open and further Objects
+can be written to it. The file will always be closed when the Channel is
+deleted.
+
+If the details of the language's I/O system on the computer you are using
+means that the above approach cannot be used, then we can write a Sink function,
+that writes a line of output text to a file, and use it in basically the same
+way as the Source function in the previous section (\secref{ss:channelsource}):
+
+\small
+\begin{terminalv}
+static FILE *output_stream;
+
+void Sink( const char *line ) {
+   (void) fprintf( output_stream, "%s\n", line );
+}
+\end{terminalv}
+\normalsize
+
+Note that we must supply the final newline character ourselves.
+
+In this case, our main program would supply a pointer to this Sink
+function as the second argument to \htmlref{astChannel}{astChannel}, as follows:
+
+\small
+\begin{terminalv}
+/* Open the output file. */
+output_stream = fopen( "outfile.ast", "w" );
+
+/* Create a Channel and write an Object to it. */
+channel = astChannel( Source, Sink, "" );
+nobj = astWrite( channel, object );
+
+   ...
+
+/* Annul the Channel and close the file when done. */
+channel = astAnnul( channel );
+(void) fclose( output_stream );
+\end{terminalv}
+\normalsize
+
+Note that we can specify a source and/or a sink function for the
+Channel, and that these may use either the same file, or different
+files according to whether we are reading or writing. AST has no
+knowledge of the underlying file system, nor of file positioning. It
+just reads and writes sequentially. If you wish, for example, to
+reposition a file at the beginning in between reads and writes, then
+this can be done directly (and completely independently of AST) using
+standard C functions.
+
+If an error occurs in your source or sink function, you can
+communicate this to the AST library by setting its error status to any
+error value using \htmlref{astSetStatus}{astSetStatus} (\secref{ss:errordetection}). This will
+immediately terminate the read or write operation.
+
+Note, if a value is set for the SinkFile attribute,
+the \htmlref{astWrite}{astWrite} function will ignore any sink function
+specified when the Channel was created.
+
+\subsection{\label{ss:otherplaces}Reading and Writing Objects to other Places}
+
+It should be obvious from the above (\secref{ss:channelsource} and
+\secref{ss:channelsink}) that a \htmlref{Channel}{Channel}'s source and sink functions
+provide a flexible means of intercepting textual data that describes
+AST Objects as it flows in and out of your program. In fact, you might
+like to regard a Channel simply as a filter for converting AST Objects
+to and from a stream of text which is then handled by your source and
+sink functions, where the real I/O occurs.
+
+This gives you the ability to store AST Objects in virtually any data
+system, so long as you can convert a stream of text into something
+that can be stored (it need no longer be text) and retrieve it
+again. There is generally no need to retain comments.  Other
+possibilities, such as inter-process and network communication, could
+also be implemented \emph{via} source and sink functions in basically
+the same way.
+
+\cleardoublepage
+\section{\label{ss:nativefits}Storing AST Objects in FITS Headers (FitsChans)}
+
+A FITS header is a sequence of 80-character strings, formatted
+according to particular rules defined by the Flexible Image Transport
+\htmlref{System}{System}
+(FITS). \htmladdnormallinkfoot{FITS}{http://fits.gsfc.nasa.gov/}
+is a widely-used standard for data interchange in astronomy and has
+also been adopted as a data processing format in some astronomical
+data reduction systems.  The individual 80-character strings in a FITS
+header are usually called \emph{cards} or \emph{header cards} (for
+entirely anachronistic reasons).
+
+A sequence of FITS cards appears as a header at the start of every
+FITS data file, and sometimes also at other points within it, and is
+used to provide ancillary information which qualifies or describes the
+main array of data stored in the file. As such, FITS headers are prime
+territory for storing information about the coordinate systems
+associated with data held in FITS files.
+
+In this section, we will examine how to store information in FITS
+headers directly in the form of AST Objects---a process which is
+supported by a specialised class of \htmlref{Channel}{Channel} called a \htmlref{FitsChan}{FitsChan}. Our
+discussion here will turn out to be a transitional step that
+emphasises the similarities between a FitsChan and a Channel
+(\secref{ss:channels}). At the same time, it will prepare us for the
+next section (\secref{ss:foreignfits}), where we will examine how to
+use a FitsChan to tackle some of the more difficult problems that FITS
+headers can present.
+
+\subsection{\label{ss:nativeencoding}The Native FITS Encoding}
+
+As it turns out, we are not the first to have thought of storing WCS
+information in FITS headers. In fact, the original FITS standard (1981
+vintage) defined a set of header keywords for this purpose which have
+been widely used, although they have proved too limited for many
+practical purposes.
+
+At the time of writing, a number of different ways of using FITS
+headers for storing WCS information are in use, most (although not
+all) based on the original standard. We will refer to these
+alternative ways of storing the information as FITS \emph{encodings}
+but will defer a discussion of their advantages and limitations until
+the next section (\secref{ss:foreignfits}).
+
+Here, we will examine how to store AST Objects directly in FITS
+headers. In effect, this defines a new encoding, which we will term
+the \emph{native encoding}. This is a special kind of encoding,
+because not only does it allow us to associate conventional
+WCS calibration information with FITS data, but it also allows any other
+information that can be expressed in terms of AST Objects to be stored
+as well.  In fact, the native encoding provides us with facilities
+roughly analogous to those of the \htmlref{Channel}{Channel}
+(\secref{ss:channels})---\emph{i.e.}\ a lossless way of
+transferring AST Objects from program to program---but based on FITS
+headers instead of free-format text.
+
+\subsection{The FitsChan Model}
+
+I/O between AST Objects and FITS headers is supported by a specialised
+form of \htmlref{Channel}{Channel} called a \htmlref{FitsChan}{FitsChan}. A FitsChan contains a buffer which
+may hold any number, including zero, of FITS header cards. This buffer
+forms a workspace in which you can assemble FITS cards and manipulate
+them before writing them out to a file.
+
+By default, when a FitsChan is first created, it contains no cards and
+there are five ways of inserting cards into it:
+
+\begin{enumerate}
+\item You may add cards yourself, one at a time, using \htmlref{astPutFits}{astPutFits}
+(\secref{ss:addingfitscards}).
+
+\item You may add cards yourself, supplying all cards concatenated into a
+single string, using \htmlref{astPutCards}{astPutCards}
+(\secref{ss:addingmulticards}).
+
+\item You may write an AST \htmlref{Object}{Object} to the FitsChan (using \htmlref{astWrite}{astWrite}),
+which will have the effect of creating new cards within the FitsChan
+which describe the Object (\secref{ss:writingnativefits}).
+
+\item You may assign a value to the \htmlref{SourceFile}{SourceFile} attribute of the FitsChan.
+The value should be the path to a text file holding a set of FITS header
+cards, one per line. When the SourceFile value is set (using
+astSetC or \htmlref{astSet}{astSet}),
+the file is opened and the headers copied from it into the FitsChan.
+The file is then immediately closed.
+
+\item You may specify a source function which reads data from some
+external store of FITS cards, just like the source associated with a
+basic Channel (\secref{ss:channelsource}). If you supply a source
+function, it will be called when the FitsChan is created in order to
+fill it with an initial set of cards (\secref{ss:fitssourceandsink}).
+\end{enumerate}
+
+There are also four ways of removing cards from a FitsChan:
+
+\begin{enumerate}
+\item You may delete cards yourself, one at a time, using \htmlref{astDelFits}{astDelFits}
+(\secref{ss:findingandchangingfits}).
+
+\item You may read an AST Object from the FitsChan (using \htmlref{astRead}{astRead}),
+which will have the effect of removing those cards from the FitsChan
+which describe the Object (\secref{ss:readingnativefits}).
+
+\item You may assign a value to the FitsChan's \htmlref{SinkFile}{SinkFile} attribute. When
+the FitsChan is deleted, any remaining headers are written out to a text
+file with path equal to the value of the SinkFile attribute.
+
+\item Alternatively, you may specify a sink function which writes data to some
+external store of FITS cards, just like the sink associated with a
+basic Channel (\secref{ss:channelsink}). If you supply a sink function,
+it will be called when the FitsChan is deleted in order to write out
+any FITS cards that remain in it (\secref{ss:fitssourceandsink}). Note,
+the sink function is not called if the SinkFile attribute has been set.
+\end{enumerate}
+
+Note, in particular, that reading an AST Object from a FitsChan is
+\emph{destructive}. That is, it deletes the FITS cards that describe the
+Object. The reason for this is explained in
+\secref{ss:destructiveread}.
+
+In addition to the above, you may also read individual cards from a
+FitsChan using the function \htmlref{astFindFits}{astFindFits} (which is not
+destructive). This is the main means of writing out FITS cards if you
+have not supplied a sink function.  astFindFits also provides a means
+of searching for particular FITS cards (by keyword, for example) and
+there are other facilities for overwriting cards when required
+(\secref{ss:findingandchangingfits}).
+
+\subsection{\label{ss:creatingafitschan}Creating a FitsChan}
+
+The \htmlref{FitsChan}{FitsChan} constructor function, \htmlref{astFitsChan}{astFitsChan}, is straightforward to
+use:
+
+\small
+\begin{terminalv}
+#include "ast.h"
+AstFitsChan *fitschan;
+
+...
+
+fitschan = astFitsChan( NULL, NULL, "Encoding=NATIVE" );
+\end{terminalv}
+\normalsize
+
+Here, we have omitted any source or sink functions by supplying NULL
+pointers for the first two arguments.
+We have also initialised the FitsChan's \htmlref{Encoding}{Encoding} attribute to
+NATIVE. This indicates that we will be using the native encoding
+(\secref{ss:nativeencoding}) to store and retrieve Objects. If this
+was left unspecified, the default would depend on the FitsChan's
+contents. An attempt is made to use whatever encoding appears to have
+been used previously. For an empty FitsChan, the default is NATIVE,
+but it does no harm to be sure.
+
+\subsection{\label{ss:addressingfitscards}Addressing Cards in a FitsChan}
+
+Because a \htmlref{FitsChan}{FitsChan} contains an ordered sequence of header cards, a
+mechanism is needed for addressing them. This allows you to specify
+where new cards are to be added, for example, or which card is to be
+deleted.
+
+This role is filled by the FitsChan's integer \htmlref{Card}{Card} attribute, which
+gives the index of the \emph{current card} in the FitsChan.  You can
+nominate any card you like to be current, simply by setting a new
+value for the Card attribute, for example:
+
+\small
+\begin{terminalv}
+int icard;
+
+...
+
+astSetI( fitschan, "Card", icard )
+\end{terminalv}
+\normalsize
+
+where ``icard'' contains the index of the card on which you wish to
+operate next.  Some functions will update the Card attribute as a
+means of advancing through the sequence of cards, when reading them
+for example, or to indicate which card matches a search criterion.
+
+The default value for Card is one, which is the index of the first
+card. This means that you can ``rewind'' a FitsChan to access its
+first card by clearing the Card attribute:
+
+\small
+\begin{terminalv}
+astClear( fitschan, "Card" );
+\end{terminalv}
+\normalsize
+
+The total number of cards in a FitsChan is given by the integer \htmlref{Ncard}{Ncard}
+attribute. This is a read-only attribute whose value is automatically
+updated as you add or remove cards. It means you can address all the
+cards in sequence using a loop such as the following:
+
+\small
+\begin{terminalv}
+int ncard;
+
+...
+
+ncard = astGetI( fitschan, "Ncard" );
+for ( icard = 1; icard <= ncard; icard++ ) {
+   astSetI( fitschan, "Card", icard );
+   <access the current card>
+}
+\end{terminalv}
+\normalsize
+
+However, it is usually possible to write slightly tidier loops based
+on the \htmlref{astFindFits}{astFindFits} function described later
+(\secref{ss:extractingfitscards} and
+\secref{ss:findingandchangingfits}).
+
+If you set the Card attribute to a value larger than Ncard, the
+FitsChan is regarded as being positioned at its \emph{end-of-file}. In
+this case there is no current card and an attempt to obtain a value
+for the Card attribute will always return the value Ncard~$+$~1. When
+a FitsChan is empty, it is always at the end-of-file.
+
+\subsection{\label{ss:writingnativefits}Writing Native Objects to a FitsChan}
+
+Having created an empty \htmlref{FitsChan}{FitsChan} (\secref{ss:creatingafitschan}), you
+can write any AST \htmlref{Object}{Object} to it in the native encoding using the
+\htmlref{astWrite}{astWrite} function. Let us assume we are writing a
+\htmlref{SkyFrame}{SkyFrame},\footnote{More probably, you would want to write a \htmlref{FrameSet}{FrameSet},
+but for purposes of illustration a SkyFrame contains a more manageable
+amount of data.} as follows:
+
+\small
+\begin{terminalv}
+AstSkyFrame *skyframe;
+int nobj;
+
+...
+
+nobj = astWrite( fitschan, skyframe );
+\end{terminalv}
+\normalsize
+
+Since we have selected the native encoding
+(\secref{ss:nativeencoding}), there are no restrictions on the class
+of Object we may write, so astWrite should always return a value of
+one, unless an error occurs. Unlike a basic \htmlref{Channel}{Channel}
+(\secref{ss:writingtoachannel}), this write operation will not produce
+any output from our program. The FITS headers produced are simply
+stored inside the FitsChan.
+
+After this write operation, the \htmlref{Ncard}{Ncard} attribute will be updated to
+reflect the number of new cards added to the FitsChan and the \htmlref{Card}{Card}
+attribute will point at the card immediately after the last one
+written. Since our FitsChan was initially empty, the Card attribute
+will, in this example, point at the end-of-file
+(\secref{ss:addressingfitscards}).
+
+The FITS standard imposes a limit of 68 characters on the length of
+strings which may be stored in a single header card. Sometimes, a
+description of an AST Object involves the use of strings which exceed
+this limit (\emph{e.g.}\ a \htmlref{Frame}{Frame} title can be of arbitrary length). If
+this occurs, the long string will be split over two or more header cards.
+Each ``continuation'' card will have the keyword \texttt{CONTINUE} in
+columns 1 to 8, and will contain a space in column 9 (instead of the
+usual equals sign). An ampersand (``\texttt{\&}'') is appended to the end of
+each of the strings (except the last one) to indicate that the string is
+continued on the next card.
+
+Note, this splitting of long strings over several cards only occurs when
+writing AST Objects to a FitsChan using the astWrite function and the
+\emph{native} encoding. If a long string is stored in a FitsChan using
+(for instance) the \htmlref{astPutFits}{astPutFits} or \htmlref{astPutCards}{astPutCards} function, it will simply be truncated.
+
+
+\subsection{\label{ss:extractingfitscards}Extracting Individual Cards from a FitsChan}
+
+To examine the contents of the \htmlref{FitsChan}{FitsChan} after writing the \htmlref{SkyFrame}{SkyFrame}
+above (\secref{ss:writingnativefits}), we must write a simple loop to
+extract each card in turn and print it out. We must also remember to
+rewind the FitsChan first, \emph{e.g.}\ using \htmlref{astClear}{astClear}. The following
+loop would do:
+
+\small
+\begin{terminalv}
+#include <stdio.h>
+char card[ 81 ];
+
+...
+
+astClear( fitschan, "Card" );
+while ( astFindFits( fitschan, "%f", card, 1 ) ) (void) printf( "%s\n", card );
+\end{terminalv}
+\normalsize
+
+Here, we have used the \htmlref{astFindFits}{astFindFits} function to find a FITS card by
+keyword. It is given a keyword template of ``\%f'', which matches any
+FITS keyword, so it always finds the current card, which it
+returns. Its fourth argument is set to 1, to indicate that the \htmlref{Card}{Card}
+attribute should be incremented afterwards so that the following card
+will be found the next time around the loop. astFindFits returns zero
+when it reaches the end-of-file and this terminates the loop.
+
+If we were storing the FITS headers in an output FITS file instead of
+printing them out, we might use a loop like this but replace
+``printf'' with a suitable data storage operation. This would only be
+necessary if we had not provided a sink function for the FitsChan
+(\secref{ss:fitssourceandsink}).
+
+\subsection{The Native FitsChan Output Format}
+
+If we print out the FITS header cards describing the \htmlref{SkyFrame}{SkyFrame} we wrote
+earlier (\secref{ss:writingnativefits}), we should obtain something
+like the following:
+
+\small
+\begin{terminalv}
+COMMENT AST ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ AST
+COMMENT AST            Beginning of AST data for SkyFrame object             AST
+COMMENT AST ................................................................ AST
+BEGAST_A= 'SkyFrame'           / Description of celestial coordinate system
+NAXES_A =                    2 / Number of coordinate axes
+AX1_A   = '        '           / Axis number 1
+BEGAST_B= 'SkyAxis '           / Celestial coordinate axis
+ENDAST_A= 'SkyAxis '           / End of object definition
+AX2_A   = '        '           / Axis number 2
+BEGAST_C= 'SkyAxis '           / Celestial coordinate axis
+ENDAST_B= 'SkyAxis '           / End of object definition
+ISA_A   = 'Frame   '           / Coordinate system description
+SYSTEM_A= 'FK4-NO-E'           / Celestial coordinate system type
+EPOCH_A =               1958.0 / Besselian epoch of observation
+ENDAST_C= 'SkyFrame'           / End of object definition
+COMMENT AST ................................................................ AST
+COMMENT AST               End of AST data for SkyFrame object                AST
+COMMENT AST ---------------------------------------------------------------- AST
+\end{terminalv}
+\normalsize
+
+As you can see, this resembles the information that would be written
+to a basic \htmlref{Channel}{Channel} to describe the same SkyFrame
+(\secref{ss:textualoutputformat}), except that it has been formatted
+into 80-character header cards according to FITS conventions.
+
+There are also a number of other differences worth noting:
+
+\begin{enumerate}
+\item There is no unnecessary information about default values
+provided for the benefit of the human reader. This is because the \htmlref{Full}{Full}
+attribute for a \htmlref{FitsChan}{FitsChan} defaults to $-$1, thus suppressing this
+information (\emph{c.f.}~\secref{ss:controllingchanneloutput}). You
+can restore the information if you wish by setting Full to 0 or $+$1,
+in which case additional COMMENT cards will be generated to hold it.
+
+\item The information is not indented, because FITS does not allow
+this. However, if you change the Full attribute to 0 or $+$1, comments
+will be included that are intended to help break up the sequence of
+headers and highlight its structure. This will probably only be of use
+if you are attempting to track down a problem by examining the FITS
+cards produced in detail.
+
+\item The FITS keywords which appear to the left of the ``$=$'' signs
+have additional characters (``\_A'', ``\_B'', \emph{etc.}) appended to
+them. This is done in order to make each keyword unique.
+\end{enumerate}
+
+This last point is worth further comment and is necessary because the
+FITS standard only allows for certain keywords (such as COMMENT and
+HISTORY) to appear more than once. \htmlref{astWrite}{astWrite} therefore appends an
+arbitrary sequence of two characters to each new keyword it generates
+in order to ensure that it does not duplicate any already present in
+the FitsChan.
+
+The main risk from not following this convention is that some software
+might ignore (say) all but the last occurrence of a keyword before
+passing the FITS headers on. Such an event is unlikely, but would
+obviously destroy the information present, so astWrite enforces the
+uniqueness of the keywords it uses. The extra characters added are
+ignored when the information is read back.
+
+As with a basic Channel, you can also suppress the comments produced
+in a FitsChan by setting the boolean (integer) \htmlref{Comment}{Comment} attribute to
+zero (\secref{ss:channelcommenting}). However, FITS headers are
+traditionally generously commented, so this is not recommended.
+
+\subsection{\label{ss:addingfitscards}Adding Individual Cards to a FitsChan}
+
+To insert individual cards into a \htmlref{FitsChan}{FitsChan}, prior to reading them back
+as Objects for example, you should use the \htmlref{astPutFits}{astPutFits} function. You
+can insert a card in front of the current one as follows:
+
+\small
+\begin{terminalv}
+astPutFits( fitschan, card, 0 );
+\end{terminalv}
+\normalsize
+
+where the third argument of zero indicates that the current card
+should not be overwritten. Note that facilities are not provided by
+AST for formatting the card contents.
+
+After inserting a card, the FitsChan's \htmlref{Card}{Card} attribute points at the
+original Card, or at the end-of-file if the FitsChan was originally
+empty. Entering a sequence of cards is therefore straightforward. If
+``cards'' is an array of pointers to strings containing FITS header
+cards and ``ncards'' is the number of cards, then a loop such as the
+following will insert the cards in sequence into a FitsChan:
+
+\small
+\begin{terminalv}
+#define MAXCARD 100
+char *cards[ MAXCARD ];
+int ncard;
+
+...
+
+for ( icard = 0; icard < ncard; icard++ ) astPutFits( fitschan, cards[ icard ], 0 );
+\end{terminalv}
+\normalsize
+
+The string containing a card need not be null terminated if it is at
+least 80 characters long (we have not allocated space for the strings
+themselves in this brief example).
+
+Note that astPutFits enforces the validity of a FitsChan by rejecting
+any cards which do not adhere to the FITS standard. If any such cards
+are detected, an error will result.
+
+\subsection{\label{ss:addingmulticards}Adding Concatenated Cards to a FitsChan}
+
+If you have all your cards concatenated together into a single long string,
+each occupying 80 characters (with no delimiters), you can insert them
+into a \htmlref{FitsChan}{FitsChan} in a single call using
+\htmlref{astPutCards}{astPutCards}.
+This call first empties the supplied FitsChan of any existing cards, then
+inserts the new cards, and finally rewinds the FitsChan so that a
+subsequent call to
+\htmlref{astRead}{astRead}
+will start reading from the first supplied card. The
+astPutCards function uses \htmlref{astPutFits}{astPutFits}
+internally to interpret and store each individual card, and so the
+caveats in \secref{ss:addingfitscards} should be read.
+
+For instance, if you are using the CFITSIO library for access to FITS
+files, you can use the CFITSIO fits\_hdr2str function to obtain a string suitable
+for passing to astPutCards:
+
+\small
+\begin{terminalv}
+
+
+if( !fits_hdr2str( fptr, 0, NULL, 0, &header, &nkeys, &status ) )
+   fitschan = astFitsChan( NULL, NULL, "" );
+   astPutCards( fitschan, header );
+   header = free( header );
+   wcsinfo = astRead( fitschan );
+
+   ...
+}
+\end{terminalv}
+\normalsize
+
+
+
+\subsection{\label{ss:readingnativefits}Reading Native Objects From a FitsChan}
+
+Once you have stored a FITS header description of an \htmlref{Object}{Object} in a
+\htmlref{FitsChan}{FitsChan} using the native encoding (\secref{ss:writingnativefits}),
+you can read it back using \htmlref{astRead}{astRead} in much the same way as with a
+basic \htmlref{Channel}{Channel} (\secref{ss:readingfromachannel}). Similar comments
+about validating the Object you read also apply
+(\secref{ss:validatinginput}).  If you have just written to the
+FitsChan, you must remember to rewind it first:
+
+\small
+\begin{terminalv}
+AstObject *object;
+
+...
+
+astClear( fitschan, "Card" );
+object = astRead( fitschan );
+\end{terminalv}
+\normalsize
+
+An important feature of a FitsChan is that read operations are
+destructive. This means that if an Object description is found, it
+will be consumed by astRead which will remove all the cards involved,
+including associated COMMENT cards, from the FitsChan. Thus, if you
+write an Object to a FitsChan, rewind, and read the same Object back,
+you should end up with the original FitsChan contents.  If you need to
+circumvent this behaviour for any reason, it is a simple matter to
+make a copy of a FitsChan using \htmlref{astCopy}{astCopy}
+(\secref{ss:copyingobjects}). If you then read from the copy, the
+original FitsChan will remain untouched.
+
+After a read completes, the FitsChan's \htmlref{Card}{Card} attribute identifies the
+card immediately following the last card read, or the end-of-file of
+there are no more cards.
+
+Since the \emph{native} encoding is being used, any long strings involved
+in the object description will have been split into two or more adjacent
+contuation cards when the Object was stored in the header using function
+\htmlref{astWrite}{astWrite}. The astRead function reverses this process by concatenating any
+such adjacent continuation cards to re-create the original long string.
+
+
+\subsection{Saving and Restoring Multiple Objects in a FitsChan}
+
+When using the native FITS encoding, multiple Objects may be stored
+and all I/O operations are sequential.  This means that you can simply
+write a sequence of Objects to a \htmlref{FitsChan}{FitsChan}. After each write operation,
+the \htmlref{Card}{Card} attribute will be updated so that the next write appends the
+next \htmlref{Object}{Object} description to the previous one.
+
+If you then rewind the FitsChan, you can read the Objects back in the
+original order. Reading them back will, of course, remove their
+descriptions from the FitsChan (\secref{ss:readingnativefits}) but the
+behaviour of the Card attribute is such that successive reads will
+simply return each Object in sequence.
+
+The only thing that may require care, given that a FitsChan can always
+be addressed randomly by setting its Card attribute, is to avoid
+writing one Object on top of another. For obvious reasons, the Object
+descriptions in a FitsChan must remain separate if they are to make
+sense when read back.
+
+\subsection{Mixing Native Objects with Other FITS Cards}
+
+Of course, any real FITS header will contain other information besides
+AST Objects, if only the mandatory FITS cards that must accompany all
+FITS data. When FITS headers are read in from a real dataset,
+therefore, any native AST \htmlref{Object}{Object} descriptions will be inter-mixed with
+many other cards.
+
+Because this is the normal state of affairs, the boolean (integer)
+\htmlref{Skip}{Skip} attribute for a \htmlref{FitsChan}{FitsChan} defaults to one. This means that when
+you read an Object From a FitsChan, any irrelevant cards will simply
+be skipped over until the start of the next Object description, if
+any, is found. If you start reading part way through an Object
+description, no error will result. The remainder of the description
+will simply be skipped.
+
+Setting Skip to zero will change this behaviour to resemble that of a
+basic \htmlref{Channel}{Channel} (\secref{ss:mixingchanneltext}), where extraneous data
+are not permitted by default, but this will probably rarely be useful.
+
+\subsection{\label{ss:findingandchangingfits}Finding and Changing Cards in a FitsChan}
+
+You can search for, and retrieve, particular cards in a \htmlref{FitsChan}{FitsChan} by
+keyword, using the function \htmlref{astFindFits}{astFindFits}. This performs a search,
+starting at the current card, until it finds a card whose keyword
+matches the template you supply, or the end-of-file is reached.
+
+If a suitable card is found, astFindFits optionally returns the card's
+contents and then sets the FitsChan's \htmlref{Card}{Card} attribute either to
+identify the card found, or the one following it. The way you want the
+Card attribute to be set is indicated by the final boolean (int)
+argument to astFindFits. A value of one is returned to indicate
+success.  If a suitable card cannot be found, astFindFits returns a
+value of zero to indicate failure and sets the FitsChan's Card
+attribute to the end-of-file.
+
+Requesting that the Card attribute be set to indicate the card that
+astFindFits finds is useful if you want to replace that card with a
+new one, as in this example:
+
+\small
+\begin{terminalv}
+char newcard[ 81 ];
+
+...
+
+(void) astFindFits( fitschan, "AIRMASS", NULL, 0 );
+astPutFits( fitschan, newcard, 1 );
+\end{terminalv}
+\normalsize
+
+Here, astFindFits is used to search for a card with the keyword
+AIRMASS, with a NULL pointer being given to indicate that we do not
+want the card's contents returned. If the card is found, \htmlref{astPutFits}{astPutFits}
+then overwrites it with a new card.  Otherwise, the Card attribute
+ends up pointing at the end-of-file and the new card is simply
+appended to the end of the FitsChan.
+
+A similar approach can be used to delete selected cards from a
+FitsChan using \htmlref{astDelFits}{astDelFits}, which deletes the current card:
+
+\small
+\begin{terminalv}
+if ( astFindFits( fitschan, "BSCALE", NULL, 0 ) ) astDelFits( fitschan );
+\end{terminalv}
+\normalsize
+
+This deletes the first card, if any, with the BSCALE keyword.
+
+Requesting that astFindFits increments the Card attribute to identify
+the card following the one found is more useful when writing loops.
+For example, the following loop extracts each card whose keyword
+matches the template ``CD\%6d'' (that is, ``CD'' followed by six
+decimal digits):
+
+\small
+\begin{terminalv}
+while ( astFindFits( fitschan, "CD%6d", card, 1 ) {
+   <process the card's contents>
+}
+\end{terminalv}
+\normalsize
+
+For further details of keyword templates, see the description of
+astFindFits in \appref{ss:functiondescriptions}.
+
+\subsection{\label{ss:fitssourceandsink}Source and Sink Functions for FitsChans}
+
+The use of source and sink functions with a \htmlref{FitsChan}{FitsChan} is optional. This
+is because you can always arrange to explicitly fill a FitsChan with
+FITS cards (\secref{ss:addingfitscards} and \secref{ss:addingmulticards})
+and you can also extract any
+cards that remain and write them out yourself
+(\secref{ss:extractingfitscards}) before you delete the FitsChan.
+
+If you choose to use these functions, however, they behave in a very
+similar manner to those used by a \htmlref{Channel}{Channel} (\secref{ss:channelsource}
+and \secref{ss:channelsink}). You supply pointers to these functions,
+as arguments to the constructor function \htmlref{astFitsChan}{astFitsChan} when you create
+the FitsChan (\secref{ss:creatingafitschan}). The source function is
+invoked implicitly at this point to fill the FitsChan with FITS cards
+and the FitsChan is then rewound, so that the first card becomes
+current. The sink function is automatically invoked later, when the
+FitsChan is deleted, in order to write out any cards that remain in
+it.
+
+The only real difference between the source and sink functions for a
+FitsChan and a basic Channel is that FITS cards are limited in length
+to 80~characters, so the choice of buffer size is simplified.  The
+``Source'' and ``Sink'' functions in \secref{ss:channelsource} and
+\secref{ss:channelsink} could therefore be used to access FITS headers
+stored in text files simply by changing LEN to be 80.  If you were not
+accessing a text file, however, appropriate changes to the I/O
+statements would be needed since the separating newline characters
+would be absent. The details obviously depend on the format of the
+file you are handling, which need not necessarily be a true FITS file.
+
+
+\cleardoublepage
+\section{\label{ss:foreignfits}Using Foreign FITS Encodings}
+
+We saw in the previous section (\secref{ss:nativefits}) how to store
+and retrieve any kind of AST \htmlref{Object}{Object} in a FITS header by using a
+\htmlref{FitsChan}{FitsChan}. To achieve this, we set the FitsChan's \htmlref{Encoding}{Encoding} attribute to
+NATIVE. However, the Objects we wrote could then only be read back by
+other programs that use AST.
+
+In practice, we will also encounter FITS headers containing WCS
+information written by other software systems.  We will probably also
+need to write FITS headers in a format that can be understood by these
+systems. Indeed, this interchange of data is one of the main reasons
+for the existence of FITS, so in this section we will examine how to
+accommodate these requirements.
+
+\subsection{\label{ss:foreignencodings}The Foreign FITS Encodings}
+
+As mentioned previously (\secref{ss:nativeencoding}), there are a
+number of conventions currently in use for storing WCS information in
+FITS headers, which we call \emph{encodings}. Here, we are concerned
+with those encodings defined by software systems other than AST, which
+we term \emph{foreign encodings}.
+
+Currently, AST supports six foreign encodings, which may be selected
+by setting the \htmlref{Encoding}{Encoding} attribute of a \htmlref{FitsChan}{FitsChan} to one of the
+following (character string) values:
+
+\begin{quote}
+\begin{description}
+\item[DSS]\mbox{}\\
+This encoding stores WCS information using the convention developed at
+the Space Telescope Science Institute for the Digitised Sky Survey
+(DSS) astrometric plate calibrations.  DSS images which use this
+convention are widely available and it is understood by a number of
+important and well-established astronomy applications.
+
+However, the calibration model used (based on a polynomial fit) is not
+easily applicable to other types of data and creating the polynomial
+coefficients needed to calibrate your own images can prove
+difficult. For this reason, the DSS encoding is probably best viewed
+as a ``read-only'' format. It is possible, however, to read in WCS
+information using this encoding and then to write it back out again,
+so long as only minor changes have been made.
+
+\item[FITS-WCS]\mbox{}\\
+This encoding is very important because it is based on a new FITS standard
+which should, for the first time, address the problem of celestial coordinate
+systems in a proper manner, by considerably extending the original FITS
+standard.
+
+The conventions used are described in a series of papers by
+E.W.\,Greisen, M.\,Calabretta, \emph{et. al.}, often referred to as the
+``FITS-WCS papers''. They are described at
+\url{http://fits.gsfc.nasa.gov/fits_wcs.html}. Now that the first two papers
+in this series have been agreed, this encoding should be understood by any
+FITS-WCS compliant software and it is likely to be adopted widely for FITS
+data in future.  For details of the coverage of these conventions provided
+by the FitsChan class, see \appref{ss:fitswcscoverage}.
+
+\item[FITS-IRAF]\mbox{}\\
+This encoding is based on the conventions described in the document
+``World Coordinate Systems Representations Within the FITS Format'' by R.J.
+Hanisch and D.G. Wells, 1988.\footnote{Available by ftp from
+fits.cv.nrao.edu /fits/documents/wcs/wcs88.ps.Z} It is employed
+by the IRAF data analysis facility, so its use will facilitate data
+exchange with IRAF. This encoding is in effect a sub-set of the current
+FITS-WCS encoding.
+
+\item[FITS-PC]\mbox{}\\
+This encoding is based on a previous version of the proposed new FITS WCS
+standard which used \texttt{PCjjjjiii} and \texttt{CDELTj} keywords to describe
+axis rotation and scaling. Versions of AST prior to V1.5 used this scheme
+for the FITS-WCS encoding. As of V1.5, FITS-WCS uses \texttt{CDi\_j}
+keywords instead.\footnote{There are many other differences between the
+previous and the current FITS-WCS encodings. The keywords to describe
+axis rotation and scaling is used purely as a label to identify the
+scheme.} The FITS-PC encoding is included in AST V1.5 only to allow
+FITS-WCS data created with previous versions to be read. It should not,
+in general, be used to create new data sets.
+
+\item[FITS-AIPS]\mbox{}\\
+This encoding is based on the conventions described in the document
+``Non-linear Coordinate Systems in AIPS'' by Eric W. Greisen (revised 9th
+September, 1994).\footnote{Available by ftp from fits.cv.nrao.edu
+/fits/documents/wcs/aips27.ps.Z} It is currently employed by the AIPS
+data analysis facility, so its use will facilitate data exchange with
+AIPS. This encoding uses \texttt{CROTAi} and \texttt{CDELTi} keywords to
+describe axis rotation and scaling.
+
+\item[FITS-AIPS++]\mbox{}\\
+Encodes coordinate system information in FITS
+header cards using the conventions used by the AIPS++ project.
+This is an extension of FITS-AIPS which includes some of the
+features of FITS-PC and FITS-IRAF.
+\end{description}
+\end{quote}
+
+For more detail about the above encodings, see the description of the
+Encoding attribute in \appref{ss:attributedescriptions}.
+
+\subsection{\label{ss:foreignfitslimitations}Limitations of Foreign Encodings}
+
+The foreign encodings available for storing WCS information in FITS
+headers have a number of limitations when compared with the native
+encoding of AST Objects (\secref{ss:nativefits}). The main ones are:
+
+\begin{enumerate}
+\item Only one class of AST \htmlref{Object}{Object}, the \htmlref{FrameSet}{FrameSet}, may be represented
+using a foreign FITS encoding. This should not come as a surprise,
+because the purpose of storing WCS information in FITS headers is to
+attach coordinate systems to an associated array of data. Since the
+FrameSet is the AST Object designed for the same purpose
+(\secref{ss:baseandcurrent}), there is a natural correspondence.
+
+The way in which a FrameSet is translated to and from the foreign
+encoding also follows from this correspondence. The FrameSet's base
+\htmlref{Frame}{Frame} identifies the data grid coordinates of the associated FITS
+data. These are the same as FITS pixel coordinates, in which the first
+pixel (in 2 dimensions) has coordinates (1,1) at its
+centre. Similarly, the current Frame of the FrameSet identifies the
+FITS world coordinate system associated with the data.
+
+\item You may store a representation of only a single FrameSet in any
+individual set of FITS header cards (\emph{i.e.}\ in a single
+\htmlref{FitsChan}{FitsChan}) at one time. If you attempt to store more than one, you may
+over-write the previous one or generate an invalid representation of
+your WCS information.
+
+This is mainly a consequence of the use of fixed FITS keywords by
+foreign encodings and the fact that you cannot, in general, have
+multiple FITS cards with the same keyword.
+
+\item In general, it will not be possible to store every possible
+FrameSet that you might construct. Depending on the encoding, only
+certain FrameSets that conform to particular restrictions can be
+represented and, even then, some of their information may be lost. See
+the description of the \htmlref{Encoding}{Encoding} attribute in
+\appref{ss:attributedescriptions} for more details of these
+limitations.
+\end{enumerate}
+
+It should be understood that using foreign encodings to read and write
+information held in AST Objects is essentially a process of converting
+the data format. As such, it potentially suffers from the same
+problems faced by all such processes, \emph{i.e.}\ differences between
+the AST data model and that of the foreign encoding may cause some
+information to be lost.  Because the AST model is extremely flexible,
+however, any data loss can largely be eliminated when reading.
+Instead, this effect manifests itself in the form of the above
+encoding-dependent restrictions on the kind of AST Objects which may
+be written.
+
+One of the aims of the AST library, of course, is to insulate you from
+the details of these foreign encodings and the restrictions they
+impose. We will see shortly, therefore, how AST provides a mechanism
+for determining whether your WCS information satisfies the necessary
+conditions and allows you to make an automatic choice of which
+encoding to use.
+
+\subsection{\label{ss:identifyingfitsencoding}Identifying Foreign Encodings on Input}
+
+Let us now examine the practicalities of extracting WCS information
+from a set of FITS header cards which have been written by some other
+software system. We will pretend that our program does not know which
+encoding has been used for the WCS information and must discover this
+for itself. In order to have a concrete example, however, we will use
+the following set of cards. These use the FITS-AIPS encoding and
+contain a typical mix of other FITS cards which are irrelevant to the
+WCS information in which we are interested:
+
+\small
+\begin{terminalv}
+SIMPLE  =                    T / Written by IDL:  30-Jul-1997 05:35:42.00
+BITPIX  =                  -32 / Bits per pixel.
+NAXIS   =                    2 / Number of dimensions
+NAXIS1  =                  300 / Length of x axis.
+NAXIS2  =                  300 / Length of y axis.
+CTYPE1  = 'GLON-ZEA'           / X-axis type
+CTYPE2  = 'GLAT-ZEA'           / Y-axis type
+CRVAL1  =           -149.56866 / Reference pixel value
+CRVAL2  =           -19.758201 / Reference pixel value
+CRPIX1  =              150.500 / Reference pixel
+CRPIX2  =              150.500 / Reference pixel
+CDELT1  =             -1.20000 / Degrees/pixel
+CDELT2  =              1.20000 / Degrees/pixel
+CROTA1  =              0.00000 / Rotation in degrees.
+SURVEY  = 'COBE DIRBE'
+BUNITS  = 'MJy/sr  '           /
+ORIGIN  = 'CDAC    '           / Cosmology Data Analysis Center
+TELESCOP= 'COBE    '           / COsmic Background Explorer satellite
+INSTRUME= 'DIRBE   '           / COBE instrument [DIRBE, DMR, FIRAS]
+PIXRESOL=                    9 / Quad tree pixel resolution [6, 9]
+DATE    = '27/09/94'           / FITS file creation date (dd/mm/yy)
+DATE-MAP= '16/09/94'           / Date of original file creation (dd/mm/yy)
+COMMENT     COBE specific keywords
+DATE-BEG= '08/12/89'           / date of initial data represented (dd/mm/yy)
+DATE-END= '25/09/90'           / date of final data represented   (dd/mm/yy)
+\end{terminalv}
+\normalsize
+
+The first step is to create a \htmlref{FitsChan}{FitsChan} and insert these cards into
+it. If ``cards'' is an array of pointers to character strings holding
+the header cards and ``ncards'' is the number of cards, this could be
+done as follows:
+
+\small
+\begin{terminalv}
+#include "ast.h"
+#define MAXCARD 100
+AstFitsChan *fitschan;
+char *cards[ MAXCARD ];
+int icard, ncard;
+
+...
+
+fitschan = astFitsChan( NULL, NULL, "" );
+for ( icard = 0; icard < ncard; icard++ ) astPutFits( fitschan, cards[ icard ], 0 );
+\end{terminalv}
+\normalsize
+
+Note that we have not initialised the \htmlref{Encoding}{Encoding} attribute of the
+FitsChan as we did in \secref{ss:creatingafitschan} when we wanted to
+use the native encoding. This is because we are pretending not to know
+which encoding to use and want AST to determine this for us. By
+leaving the Encoding attribute un-set, its default value will adjust
+to whichever encoding AST considers to be most appropriate, according
+to the FITS header cards present. For details of how this choice is
+made, see the description of the Encoding attribute in
+\appref{ss:attributedescriptions}.
+
+This approach has the obvious advantages of making our program simpler
+and more flexible and of freeing us from having to know about the
+different encodings available. As a bonus, it also means that the
+program will be able to read any new encodings that AST may support in
+future, without needing to be changed.
+
+At this point, we could enquire the default value of the Encoding
+attribute, which indicates which encoding AST intends to use, as
+follows:
+
+\small
+\begin{terminalv}
+const char *encode;
+
+...
+
+
+encode = astGetC( fitschan, "Encoding" );
+\end{terminalv}
+\normalsize
+
+The result of this enquiry would be the string ``FITS-AIPS''.  Note
+that we could also have set the FitsChan's Encoding attribute
+explicitly, such as when creating it:
+
+\small
+\begin{terminalv}
+fitschan = astFitsChan( NULL, NULL, "Encoding=FITS-AIPS" );
+\end{terminalv}
+\normalsize
+
+If we tried to read information using this encoding
+(\secref{ss:readingforeignfits}), but failed, we could then change the
+encoding and try again.  This would allow our program to take control
+of how the optimum choice of encoding is arrived at. However, it would
+also involve using explicit knowledge of the encodings available and
+this is best avoided if possible.
+
+\subsection{\label{ss:readingforeignfits}Reading Foreign WCS Information from a FITS Header}
+
+Having stored a set of FITS header cards in a \htmlref{FitsChan}{FitsChan} and determined
+how the WCS information is encoded
+(\secref{ss:identifyingfitsencoding}), the next step is to read an AST
+\htmlref{Object}{Object} from the FitsChan using \htmlref{astRead}{astRead}. We must also remember to
+rewind the FitsChan first, if necessary, such as by clearing its \htmlref{Card}{Card}
+attribute, which defaults to 1:
+
+\small
+\begin{terminalv}
+AstObject *wcsinfo;
+
+...
+
+astClear( fitschan, "Card" );
+wcsinfo = astRead( fitschan );
+\end{terminalv}
+\normalsize
+
+If the pointer returned by astRead is not equal to AST\_\_NULL, then
+an Object has been read successfully. Otherwise, there was either no
+information to read or the choice of FITS encoding
+(\secref{ss:identifyingfitsencoding}) was inappropriate.
+
+At this point you might like to indulge in a little data validation
+along the lines described in \secref{ss:validatinginput}, for example:
+
+\small
+\begin{terminalv}
+if ( !strcmp( astGetC( wcsinfo, "Class" ), "FrameSet" ) ) {
+   <the Object is a FrameSet, so use it>
+} else {
+   <something unexpected was read>
+}
+\end{terminalv}
+\normalsize
+
+If a foreign encoding has definitely been used, then the Object will
+automatically be a \htmlref{FrameSet}{FrameSet} (\secref{ss:foreignfitslimitations}), so
+this stage can be omitted. However, if the native encoding
+(\secref{ss:nativeencoding}) might have been employed, which is a
+possibility if you accept the FitsChan's default \htmlref{Encoding}{Encoding} value, then
+any class of Object might have been read and a quick check would be
+worthwhile.
+
+If you used \htmlref{astShow}{astShow} (\secref{ss:displayingobjects}) to examine the
+FrameSet which results from reading our example FITS header
+(\secref{ss:identifyingfitsencoding}), you would find that its base
+\htmlref{Frame}{Frame} describes the image's pixel coordinate system and that its
+current Frame is a \htmlref{SkyFrame}{SkyFrame} representing galactic coordinates. These
+two Frames are inter-related by a \htmlref{Mapping}{Mapping} (actually a \htmlref{CmpMap}{CmpMap}) which
+incorporates the effects of various rotations, scalings and a
+``zenithal equal area'' sky projection, so that each pixel of the FITS
+image is mapped on to a corresponding sky position in galactic
+coordinates.
+
+Because this FrameSet may be used both as a Mapping
+(\secref{ss:framesetasmapping}) and as a Frame
+(\secref{ss:framesetasframe}), it may be employed directly to perform
+many useful operations without any need to decompose it into its
+component parts. These include:
+
+\begin{itemize}
+\item Transforming data grid (FITS pixel) coordinates into galactic
+coordinates and \emph{vice versa} (\secref{ss:framesetasmapping}).
+
+\item Formatting coordinate values (either pixel or galactic
+coordinates) ready for display to a user
+(\secref{ss:formattingaxisvalues} and \secref{ss:normalising}).
+
+\item Enquiring about axis labels (or other axis
+information---\secref{ss:frameattributes}) which might be used, for
+example, to label columns of coordinates in a table
+(\secref{ss:frameaxisattributes}).
+
+\item Aligning the image with another image from which a similar
+FrameSet has been obtained (\secref{ss:registeringimages}).
+
+\item Creating a \htmlref{Plot}{Plot} (\secref{ss:plots}), which can be used to overlay
+a variety of graphical information (including a coordinate
+grid---Figure~\ref{fig:gridplot}) on the displayed image.
+
+\item Generating a new FrameSet which reflects any geometrical
+processing you perform on the associated image data
+(\secref{ss:wcsprocessingexample}). This new FrameSet could then be
+written out as FITS headers to describe the modified image
+(\secref{ss:writingforeignfits}).
+\end{itemize}
+
+If the FrameSet contains other Frames (apart from the base and current
+Frames), then you would also have access to information about other
+coordinate systems associated with the image.
+
+\subsection{\label{ss:destructiveread}Removing WCS Information from FITS Headers---the Destructive Read}
+
+It is instructive at this point to examine the contents of a \htmlref{FitsChan}{FitsChan}
+after we have read a \htmlref{FrameSet}{FrameSet} from it
+(\secref{ss:readingforeignfits}). The following would rewind our
+FitsChan and display its contents:
+
+\small
+\begin{terminalv}
+#include <stdio.h>
+char card[ 81 ];
+
+...
+
+astClear( fitschan, "Card" );
+while ( astFindFits( fitschan, "%f", card, 1 ) ) (void) printf( "%s\n", card );
+\end{terminalv}
+\normalsize
+
+The output, if we started with the example FITS header in
+\secref{ss:identifyingfitsencoding}, might look like this:
+
+\small
+\begin{terminalv}
+SIMPLE  =                    T /  Written by IDL:  30-Jul-1997 05:35:42.00
+BITPIX  =                  -32 /  Bits per pixel.
+NAXIS   =                    2 /  Number of dimensions
+NAXIS1  =                  300 /  Length of x axis.
+NAXIS2  =                  300 /  Length of y axis.
+SURVEY  = 'COBE DIRBE'
+BUNITS  = 'MJy/sr  '
+ORIGIN  = 'CDAC    '           /  Cosmology Data Analysis Center
+TELESCOP= 'COBE    '           /  COsmic Background Explorer satellite
+INSTRUME= 'DIRBE   '           /  COBE instrument [DIRBE, DMR, FIRAS]
+PIXRESOL=                    9 /  Quad tree pixel resolution [6, 9]
+DATE    = '27/09/94'           /  FITS file creation date (dd/mm/yy)
+DATE-MAP= '16/09/94'           /  Date of original file creation (dd/mm/yy)
+COMMENT     COBE specific keywords
+DATE-BEG= '08/12/89'           /  date of initial data represented (dd/mm/yy)
+DATE-END= '25/09/90'           /  date of final data represented   (dd/mm/yy)
+\end{terminalv}
+\normalsize
+
+Comparing this with the original, you can see that all the FITS cards
+that represent WCS information have been removed. They have
+effectively been ``sucked out'' of the FitsChan by the destructive
+read that \htmlref{astRead}{astRead} performs and converted into an equivalent
+FrameSet. AST remembers where they were stored, however, so that if we
+later write WCS information back into the FitsChan
+(\secref{ss:writingforeignfits}) they will, as far as possible, go
+back into their original locations. This helps to preserve the overall
+layout of the FITS header.
+
+You can now see why astRead performs destructive reads. It is a
+mechanism for removing WCS information from a FITS header while
+insulating you, as a programmer, from the details of the encoding
+being used. It means you can ensure that all relevant header cards
+have been removed, giving you a clean slate, without having to know
+which FITS keywords any particular encoding uses.
+
+Clearing this WCS information out of a FITS header is particularly
+important when considering how to write new WCS information back after
+processing (\secref{ss:writingforeignfits}). If any relevant FITS
+cards are left over from the input dataset and find their way into the
+new processed header, they could interfere with the new information
+being written.\footnote{This can happen if a particular keyword is
+present in the input header but is not used in the output header
+(whether particular keywords are used can depend on the WCS
+information being stored). In such a case, the original value would
+not be over-written by a new output value, so would remain erroneously
+present.} The destructive read mechanism ensures that this doesn't
+happen.
+
+\subsection{\label{ss:propagatingwcsinformation}Propagating WCS Information through Data Processing Steps}
+
+One of the purposes of AST is to make it feasible to propagate WCS
+information through successive stages of data processing, so that it
+remains consistent with the associated image data. As far as possible,
+this should happen regardless of the FITS encoding used to store the
+original WCS information.
+
+If the data processing being performed does not change the
+relationship between image pixel and world coordinates (whatever these
+may be), then propagation of the WCS information is
+straightforward. You can simply copy the FITS header from input to
+output.
+
+If this relationship changes, however, then the WCS information must
+be processed alongside the image data and a new FITS header generated
+to represent it. In this case, the sequence of operations within your
+program would probably be as follows:
+
+\begin{enumerate}
+\item Read the image data and associated FITS header from the input
+dataset, putting the header cards into a \htmlref{FitsChan}{FitsChan}
+(\secref{ss:identifyingfitsencoding}).
+
+\item Read an AST \htmlref{Object}{Object}, a \htmlref{FrameSet}{FrameSet}, from the FitsChan (typically
+using a foreign FITS encoding---\secref{ss:readingforeignfits}).
+
+\item Process the image data and modify the FrameSet accordingly
+(\emph{e.g.}~\secref{ss:wcsprocessingexample}).
+
+\item Write the FrameSet back into the FitsChan
+(\secref{ss:writingforeignfits}).
+
+\item Perform any other modification of FITS header cards your program
+may require.
+
+\item Write the FitsChan contents (\emph{i.e.}\ processed header
+cards) and image data to the output dataset.
+\end{enumerate}
+
+In stage (2), the original WCS information will be removed from the
+FitsChan by a destructive read. Later, in stage (4), new WCS
+information is written to replace it. This is the process which we
+consider next (\secref{ss:writingforeignfits}).
+
+\subsection{\label{ss:writingforeignfits}Writing Foreign WCS Information to a FITS Header}
+
+Before we can write processed WCS information held in a \htmlref{FrameSet}{FrameSet} back
+into a \htmlref{FitsChan}{FitsChan} in preparation for output, we must select the FITS
+encoding to use.  Unfortunately, we cannot simply depend on the
+default value of the \htmlref{Encoding}{Encoding} attribute, as we did when reading the
+input information (\secref{ss:identifyingfitsencoding}), because the
+destructive action of reading the WCS data
+(\secref{ss:destructiveread}) will have altered the FitsChan's
+contents. This, in turn, will have changed the choice of default
+encoding, probably causing it to revert to NATIVE.
+
+We will return to the question of the optimum choice of encoding
+below.  For now, let's assume that we want to use the same encoding
+for output as we used for input. Since we enquired what that was
+before we read the input WCS data from the FitsChan
+(\secref{ss:identifyingfitsencoding}), we can now set that value
+explicitly. We can also set the FitsChan's \htmlref{Card}{Card} attribute back to 1 at
+the same time (because the write will fail if the FitsChan is not
+rewound). \htmlref{astWrite}{astWrite} can then be used to write the output WCS
+information into the FitsChan:
+
+\small
+\begin{terminalv}
+int nobj;
+
+...
+
+astSet( fitschan, "Card=1, Encoding=%s", encode );
+nobj = astWrite( fitschan, wcsinfo );
+\end{terminalv}
+\normalsize
+
+The value returned by astWrite (assigned to ``nobj'') indicates how
+many Objects were written. This will either be 1 or zero. A value of
+zero is used to indicate that the information could not be encoded in
+the form you requested. If this happens, nothing will have been
+written.
+
+If your choice of encoding proves inadequate, the probable reason is
+that the changes you have made to the FrameSet have caused it to
+depart from the data model which the encoding assumes.  AST knows
+about the data model used by each encoding and will attempt to
+simplify the FrameSet you provide so as to fit into that model, thus
+relieving you of the need to understand the details and limitations of
+each encoding yourself.\footnote{Storing values in the FitsChan for
+FITS headers NAXIS1, NAXIS2, \emph{etc.} (the grid dimensions in pixels),
+before invoking
+astWrite
+can sometimes help to produce a successful write.} When this attempt fails,
+however, you must consider what alternative encoding to use.
+
+Ideally, you would probably want to try a sequence of alternative
+encodings, using an approach such as the following:
+
+\small
+\begin{terminalv}
+/* 1. */
+astSet( fitschan, "Card=1, Encoding=FITS-IRAF" );
+if ( !astWrite( fitschan, wcsinfo ) ) {
+
+/* 2. */
+   astSetC( fitschan, "Encoding", encode );
+   if ( !astWrite( fitschan, wcsinfo ) ) {
+
+/* 3. */
+      astSet( fitschan, "Encoding=NATIVE" );
+      (void) astWrite( fitschan, wcsinfo );
+   }
+}
+\end{terminalv}
+\normalsize
+
+That is:
+
+\begin{enumerate}
+\item Start by trying the FITS-WCS encoding, on the grounds that FITS
+should provide a universal interchange standard in which all WCS
+information should be expressed if possible.
+
+\item If that fails, then try the original encoding used for the input
+WCS information, on the grounds that you are at least not making the
+information any harder for others to read than it originally was.
+
+\item If that also fails, then you are probably trying to store fairly
+complex information for which you need the native encoding. Only other
+AST programs will then be able to read this information, but these are
+probably the only programs that will be able to do anything sensible
+with it anyway.
+\end{enumerate}
+
+An alternative approach might be to encode the WCS information in several
+ways, since this gives the maximum chance that other software will be
+able to read it. This approach is only possible if there is no
+significant conflict between the FITS keywords used by the different
+encodings\footnote{In practice, this means you should avoid mixing
+FITS-IRAF, FITS-WCS, FITS-AIPS, FITS-AIPS++ and FITS-PC encodings since they share
+many keywords.}.  Adopting this approach would simply require multiple
+calls to astWrite, rewinding the FitsChan and changing its Encoding value
+before each one.
+
+Unfortunately, however, there is a drawback to duplicating WCS
+information in the FITS header in this way, because any program which
+modifies one version of this information and simply copies the
+remainder of the header will risk producing two inconsistent sets of
+information. This could obviously be confusing to subsequent
+software. Whether you consider this a worthwhile risk probably depends
+on the use to which you expect your data to be put.
+
+\cleardoublepage
+\section{\label{ss:xmlchan}Storing AST Objects as XML (XmlChan)}
+
+\htmladdnormallinkfoot{XML}{http://www.w3.org/XML/}
+is fast becoming the standard format for passing structured data around
+the internet, and much general purpose software has been written for
+tasks such as the parsing, editing, display and transformation of XML
+data. The \htmlref{XmlChan}{XmlChan} class (a specialised form of \htmlref{Channel}{Channel}) provides
+facilities for storing AST objects externally in the form of XML documents,
+thus allowing such software to be used.
+
+The primary XML format used by the XmlChan class is a fairly close
+transliteration of the AST native format produced by the basic Channel
+class. Currently, there is no DTD or schema defining the structure of data
+produced in this format by an XmlChan. The following is a native AST
+representation of a simple 1-D \htmlref{Frame}{Frame} (including comments and with the \htmlref{Full}{Full}
+attribute set to zero so that some default attribute values are included
+as extra comments):
+
+\small
+\begin{terminalv}
+ Begin Frame    # Coordinate system description
+#   Title = "1-d coordinate system"     # Title of coordinate system
+    Naxes = 1   # Number of coordinate axes
+    Domain = "SCREEN"   # Coordinate system domain
+#   Lbl1 = "Axis 1"     # Label for axis 1
+#   Uni1 = "cm"         # Units for axis 1
+    Ax1 =       # Axis number 1
+       Begin Axis       # Coordinate axis
+          Unit = "cm"   # Axis units
+       End Axis
+ End Frame
+\end{terminalv}
+\normalsize
+
+The corresponding XmlChan output would look like:
+
+\small
+\begin{terminalv}
+ <Frame xmlns="http://www.starlink.ac.uk/ast/xml/"
+        desc="Coordinate system description">
+    <_attribute name="Title" quoted="true" value="1-d coordinate system"
+                desc="Title of coordinate system" default="true"/>
+    <_attribute name="Naxes" value="1" desc="Number of coordinate axes"/>
+    <_attribute name="Domain" quoted="true" value="SCREEN"
+                desc="Coordinate system domain"/>
+    <_attribute name="Lbl1" quoted="true" value="Axis 1"
+                desc="Label for axis 1" default="true"/>
+    <_attribute name="Uni1" quoted="true" value="cm"
+                desc="Units for axis 1" default="true"/>
+    <Axis label="Ax1" desc="Coordinate axis">
+       <!--Axis number 1-->
+       <_attribute name="Unit" quoted="true" value="cm" desc="Axis units"/>
+    </Axis>
+ </Frame>
+\end{terminalv}
+\normalsize
+
+
+Notes:
+
+\begin{enumerate}
+\item The AST class name is used as the name for an XML element which contain
+a description of an AST object.
+
+\item AST attributes are described by XML elements with the name
+``\_attribute''. Unfortunately, the word ``attribute'' is also used by XML
+to refer to a ``name=value'' pair within an element start tag. So for
+instance, the ``\htmlref{Title}{Title}'' attribute of the AST Frame object is described
+within an XML element with name ``\_attribute'' in which the XML attribute
+``name'' has the value ``Title'', and the XML attribute ``value'' has the
+value ``1-d coordinate system''. The moral is always to be clear clear
+about the context (AST or XML) in which the word \emph{attribute} is being
+used!
+
+\item The XML includes comments both as XML attributes with the name ``desc'',
+and as separate comment tags.
+
+\item Elements which describe default values are identified by the fact
+that they have an XML attribute called ``default'' set to the value
+``true''. These elements are ignored when being read back into an XmlChan.
+
+\item The outer-most XML element of an AST object will set the default
+namespace to \verb+http://www.starlink.ac.uk/ast/xml/+ which will be
+inherited by all nested elements.
+
+\end{enumerate}
+
+
+The XmlChan class changes the default value for the \htmlref{Comment}{Comment} and Full
+attributes (inherited from the base Channel class) to zero and -1,
+resulting in terse output by default. With the default values for these
+attributes, the above XML is reduced to the following:
+
+\small
+\begin{terminalv}
+ <Frame xmlns="http://www.starlink.ac.uk/ast/xml/">
+    <_attribute name="Naxes" value="1"/>
+    <_attribute name="Domain" quoted="true" value="SCREEN"/>
+    <Axis label="Ax1">
+       <_attribute name="Unit" quoted="true" value="cm"/>
+    </Axis>
+ </Frame>
+\end{terminalv}
+\normalsize
+
+
+The XmlChan class uses the \htmlref{Skip}{Skip} attributes very similarly to the Channel
+class. If Skip is zero (the default) then an error will be reported if the text
+supplied by the source function does not begin with an AST \htmlref{Object}{Object}. If
+Skip is non-zero, then initial text is skipped over without error until
+the start of an AST object is found. this allows an AST object to be
+located within a larger XML document.
+
+\subsection{Reading IVOA Space-Time-Coordinates XML (STC-X) Descriptions}
+The \htmlref{XmlChan}{XmlChan} class also provides support for reading (but not writing) XML
+documents which use a restricted subset of an early draft (V1.20) of the
+IVOA Space-Time-Coordinates XML (STC-X) system. The version of STC-X
+finally adopted by the IVOA differs in several significant respects from
+V1.20, and so the STC-X support currently provided by AST is mainly of
+historical interest. Note, AST also supports the alternative ``STC-S''
+linear string description of the STC model (see \secref{ss:stcschans}).
+
+STC-X V1.20 is documented at
+\url{http://www.ivoa.net/Documents/WD/STC/STC-20050225.html}, and the current
+version is documented at
+\url{http://www.ivoa.net/Documents/latest/STC-X.html}.
+
+When an STC-X document is read using an XmlChan, the read operation
+produces an AST \htmlref{Object}{Object} of the \htmlref{Stc}{Stc} class, which is itself a subclass of
+\htmlref{Region}{Region}. Specifically, each such Object will be an instance of
+\htmlref{StcSearchLocation}{StcSearchLocation}, \htmlref{StcResourceProfile}{StcResourceProfile}, \htmlref{StcCatalogEntryLocation}{StcCatalogEntryLocation} or
+\htmlref{StcObsDataLocation}{StcObsDataLocation}. See the description of the XmlChan class and the
+\htmlref{XmlFormat}{XmlFormat} attribute for further details.
+
+\cleardoublepage
+\section{\label{ss:stcschans}Reading and writing STC-S descriptions (StcsChans)}
+
+The \htmlref{StcsChan}{StcsChan} class provides facilities for reading and writing
+IVOA ``STC-S'' descriptions. STC-S (see
+\url{http://www.ivoa.net/Documents/latest/STC-S.html}) is a linear string
+syntax that allows simple specification of the STC metadata describing a
+region in an astronomical coordinate system. AST supports a
+subset of the STC-S specification, allowing an STC-S description of a
+region within an AST-supported astronomical coordinate system to be converted
+into an equivalent AST \htmlref{Region}{Region} object, and vice-versa. For further
+details, see the full description of the StcsChan class in
+\appref{ss:classdescriptions}.
+
+
+\cleardoublepage
+\section{\label{ss:intramaps}Creating Your Own Private Mappings (IntraMaps)}
+
+\subsection{The Need for Extensibility}
+
+However many \htmlref{Mapping}{Mapping} classes are provided by AST, sooner or later you
+will want to transform coordinates in some way that has not been
+foreseen. You might want to plot a graph in some novel curvilinear
+coordinate system (perhaps you already have a WCS system in your
+software and just want to use AST for its graphical capabilities).
+Alternatively, you might need to calibrate a complex dataset (like an
+objective prism plate) where each position must be converted to world
+coordinates with reference to calibration data under the control of an
+elaborate algorithm.
+
+In such cases, it is clear that the basic pre-formed components
+provided by AST for building Mappings are just not enough. What you
+need is access to a programming language. However, if you write your
+own software to transform coordinate values, then it must be made
+available in the form of an AST class (from which you can create
+Objects) before it can be used in conjunction with other AST
+facilities.
+
+At this point you might consider writing your own AST class, but this
+is not recommended. Not only would the internal conventions used by
+AST take some time to master, but you might also find yourself having
+to change your software whenever a new version of AST was
+released. Fortunately, there is a much easier route provided by the
+\htmlref{IntraMap}{IntraMap} class.
+
+\subsection{The IntraMap Model}
+
+To allow you to write your own Mappings, AST provides a special kind
+of \htmlref{Mapping}{Mapping} called an \htmlref{IntraMap}{IntraMap}. An IntraMap is a sort of ``wrapper''
+for a coordinate transformation function written in C. You write this
+function yourself and then register it with AST. This, in effect,
+creates a new class from which you can create Mappings
+(\emph{i.e.}\ IntraMaps) which will transform coordinates in whatever
+way your transformation function specifies.
+
+Because IntraMaps are Mappings, they may be used in the same way as
+any other Mapping. For instance, they may be combined in series or
+parallel with other Mappings using a \htmlref{CmpMap}{CmpMap} (\secref{ss:cmpmaps}),
+they may be inverted (\secref{ss:invertingmappings}), you may enquire
+about their attributes (\secref{ss:gettingattributes}), they may be
+inserted into FrameSets (\secref{ss:framesets}), \emph{etc.} They do,
+however, have some important limitations of which you should be aware
+before we go on to consider how to create them.
+
+\subsection{\label{ss:intramaplimitations}Limitations of IntraMaps}
+
+By now, you might be wondering why any other kind of \htmlref{Mapping}{Mapping} is
+required at all. After all, why not simply write your own coordinate
+transformation functions in C, wrap them up in IntraMaps and do away
+with all the other Mapping classes in AST?
+
+The reason is not too hard to find. Any transformation function you
+write is created solely by you, so it is a private extension which
+does not form a permanent part of AST. If you use it to calibrate some
+data and then pass that data to someone else, who has only the
+standard version of AST, then they will not be able to interpret it.
+
+Thus, while an \htmlref{IntraMap}{IntraMap} is fine for use by you and your collaborators
+(who we assume have access to the same transformation functions), it
+does not address the need for universal data exchange like other AST
+Mappings do. This is where the ``Intra'' in the class name
+``IntraMap'' comes from, implying private or internal usage.
+
+For this reason, it is unwise to store IntraMaps in datasets, unless
+they will be used solely for communication between collaborating items
+of software which share conventions about their use.  A private
+database describing coordinate systems on a graphics device might be
+an example where IntraMaps would be suitable, because the data would
+probably never be accessed by anyone else's software. Restricting
+IntraMap usage to within a single program (\emph{i.e.} never writing
+it out) is, of course, completely safe.
+
+If, by accident, an IntraMap should happen to escape as part of a
+dataset, then the unsuspecting recipient is likely to receive an error
+message when they attempt to read the data. However, AST will
+associate details of the IntraMap's transformation function and its
+author (if provided) with the data, so that the recipient can make an
+intelligent enquiry to obtain the necessary software if this proves
+essential.
+
+\subsection{\label{ss:transformationfunctions}Writing a Transformation Function}
+
+The first stage in creating an \htmlref{IntraMap}{IntraMap} is to write the coordinate
+transformation function. This should have a calling interface like the
+\htmlref{astTranP}{astTranP} function provided by AST (\emph{q.v.}). Here is a simple
+example of a suitable transformation function which transforms
+coordinates by squaring them:
+\xlabel{SqrTran}
+
+\small
+\begin{terminalv}
+#include "ast.h"
+#include <math.h>
+
+void SqrTran( AstMapping *this, int npoint, int ncoord_in,
+              const double *ptr_in[], int forward, int ncoord_out,
+              double *ptr_out[] ) {
+   int point, coord;
+   double x;
+
+/* Forward transformation. */
+   if ( forward ) {
+      for ( point = 0; point < npoint; point++ ) {
+         for ( coord = 0; coord < ncoord_in; coord++ ) {
+            x = ptr_in[ coord ][ point ];
+            ptr_out[ coord ][ point ] = ( x == AST__BAD ) ? AST__BAD : x * x;
+         }
+      }
+
+/* Inverse transformation. */
+   } else {
+      for ( point = 0; point < npoint; point++ ) {
+         for ( coord = 0; coord < ncoord_in; coord++ ) {
+            x = ptr_in[ coord ][ point ];
+            ptr_out[ coord ][ point ] =
+               ( x < 0.0 || x == AST__BAD ) ? AST__BAD : sqrt( x );
+         }
+      }
+   }
+}
+\end{terminalv}
+\normalsize
+
+As you can see, the function comes in two halves which implement the
+forward and inverse coordinate transformations. The number of points
+to be transformed (``npoint'') and the numbers of input and output
+coordinates per point (``ncoord\_in'' and ``ncoord\_out''---in this
+case both are assumed equal) are passed to the function. A pair of
+loops then accesses all the coordinate values.  Note that it is
+legitimate to omit one or other of the forward/inverse transformations
+and simply not to implement it, if it will not be required. It is also
+permissible to require that the numbers of input and output
+coordinates be fixed (\emph{e.g.}\ at 2), or to write the function so
+that it can handle arbitrary dimensionality, as here.
+
+Before using an incoming coordinate, the function must first check
+that it is not set to the value AST\_\_BAD, which indicates missing
+data (\secref{ss:badcoordinates}). If it is, the same value is also
+assigned to any affected output coordinates. The value AST\_\_BAD is
+also generated if any coordinates cannot be transformed. In this
+example, this can happen with the inverse transformation if negative
+values are encountered, so that the square root cannot be taken.
+
+There are very few restrictions on what a coordinate transformation
+function may do. For example, it may freely perform I/O to access any
+external data needed, it may invoke other AST facilities (but beware
+of unwanted recursion), \emph{etc.} Typically, you may also want to
+pass information to it \emph{via}\ global variables. Remember,
+however, that whatever facilities the transformation function requires
+must be available in every program which uses it.
+
+Generally, it is not a good idea to retain context information within
+a transformation function. That is, it should transform each set of
+coordinates as a single point and retain no memory of the points it
+has transformed before. This is in order to conform with the AST model
+of a \htmlref{Mapping}{Mapping}.
+
+If an error occurs within a transformation function, it should use the
+\htmlref{astSetStatus}{astSetStatus} function (\secref{ss:errordetection}) to set the AST
+status to an error value before returning. This will alert AST to the
+error, causing it to abort the current operation. The error value
+AST\_\_ITFER is available for this purpose, but other values may also
+be used (\emph{e.g.}\ if you wish to distinguish different types of
+error).
+
+\subsection{\label{ss:registeringintramaps}Registering a Transformation Function}
+
+Having written your coordinate transformation function, the next step
+is to register it with AST. Registration is performed using
+\htmlref{astIntraReg}{astIntraReg}, as follows:
+
+\small
+\begin{terminalv}
+void SqrTran( AstMapping *, int, int, const double *[], int, int, double *[] );
+
+const char *author, *contact, *purpose;
+
+...
+
+purpose = "Square each coordinate value";
+author =  "R.F. Warren-Smith & D.S. Berry";
+contact = "http://www.starlink.ac.uk/cgi-bin/htxserver/sun211.htx/?xref_SqrTran";
+
+astIntraReg( "SqrTran", 2, 2, SqrTran, 0, purpose, author, contact );
+\end{terminalv}
+\normalsize
+
+Note that you should also provide a function prototype to describe the
+transformation function (the implementation of the function itself
+would suffice, of course).
+
+The first argument to astIntraReg is a name by which the
+transformation function will be known. This will be used when we come
+to create an \htmlref{IntraMap}{IntraMap} and is case sensitive. We recommend that you use
+the actual function name here and make this sufficiently unusual that
+it is unlikely to clash with any other functions in most people's
+software.
+
+The next two arguments specify the number of input and output
+coordinates which the transformation function will handle. These
+correspond with the \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes of the IntraMap we will
+create. Here, we have set them both to 2, which means that we will
+only be able to create IntraMaps with 2 input and 2 output coordinates
+(despite the fact that the transformation function can actually handle
+other dimensionalities). We will see later
+(\secref{ss:variableintramapcoordinates}) how to remove this
+restriction.
+
+The fourth argument should contain a set of flags which describe the
+transformation function in a little more detail. We will return to
+this shortly (\secref{ss:restrictedintramaps} \&
+\secref{ss:simplifyingintramaps}). For now, we supply a value of zero.
+
+The remaining arguments are character strings which document the
+transformation function, mainly for the benefit of anyone who is
+unfortunate enough to encounter a reference to it in their data which
+they cannot interpret. As explained above
+(\secref{ss:intramaplimitations}), you should try and avoid this, but
+accidents will happen, so you should always provide strings containing
+the following:
+
+\begin{enumerate}
+\item A short description of what the transformation function is for.
+\item The name of the author.
+\item Contact details, such as an e-mail or WWW address.
+\end{enumerate}
+
+The idea is that anyone finding an IntraMap in their data, but lacking
+the necessary transformation function, should be able to contact the
+author and make a sensible enquiry in order to obtain it. If you
+expect many enquiries, you may like to set up a World Wide Web page
+and use that instead (in the example above, we use the WWW address of
+the relevant part of this document).
+
+\subsection{Creating an IntraMap}
+
+Once a transformation function has been registered, creating an
+\htmlref{IntraMap}{IntraMap} from it is simple:
+
+\small
+\begin{terminalv}
+AstIntraMap *intramap;
+
+...
+
+intramap = astIntraMap( "SqrTran", 2, 2, "" );
+\end{terminalv}
+\normalsize
+
+We simply use the \htmlref{astIntraMap}{astIntraMap} constructor function and pass it the
+name of the transformation function to use. This name is the same
+(case sensitive) one that we associated with the function when we
+registered it using \htmlref{astIntraReg}{astIntraReg} (\secref{ss:registeringintramaps}).
+
+You can, of course, register any number of transformation functions
+and select which one to use whenever you create an IntraMap. You can
+also create any number of independent IntraMaps using each
+transformation function. In this sense, each transformation function
+you register effectively creates a new ``sub-class'' of IntraMap, from
+which you can create Objects just like any other class. However, an
+error will occur if you attempt to use a transformation function that
+has not yet been registered.
+
+The second and third arguments to astIntraMap are the numbers of input
+and output coordinates. These define the \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes for
+the IntraMap that is created and they must match the corresponding
+numbers given when the transformation function was registered.
+
+The final argument is the usual attribute initialisation string. You
+may set attribute values for an IntraMap in exactly the same way as
+for any other \htmlref{Mapping}{Mapping} (\secref{ss:settingattributes}, and also see
+\secref{ss:intraflag}).
+
+\subsection{\label{ss:restrictedintramaps}Restricted Implementations of Transformation Functions}
+
+You may not always want to use both the forward and inverse
+transformations when you create an \htmlref{IntraMap}{IntraMap}, so it is possible to omit
+either from the underlying coordinate transformation
+function. Consider the following, for example:
+
+\small
+\begin{terminalv}
+void Poly3Tran( AstMapping *this, int npoint, int ncoord_in,
+                const double *ptr_in[], int forward, int ncoord_out,
+                double *ptr_out[] ) {
+   double x;
+   int point;
+
+/* Forward transformation. */
+   for ( point = 0; point < npoint; point++ ) {
+      x = ptr_in[ 0 ][ point ];
+      ptr_out[ 0 ][ point ] = ( x == AST__BAD ) ? AST__BAD :
+         6.18 + x * ( 0.12 + x * ( -0.003 + x * 0.0000101 ) );
+   }
+}
+\end{terminalv}
+\normalsize
+
+This implements a 1-dimensional cubic polynomial transformation. Since
+this is somewhat awkward to invert, however, we have only implemented
+the forward transformation.  When registering the function, this is
+indicated via the ``flags'' argument to \htmlref{astIntraReg}{astIntraReg}, as follows:
+
+\small
+\begin{terminalv}
+void Poly3Tran( AstMapping *, int, int, const double *[], int, int, double *[] );
+
+...
+
+astIntraReg( "Poly3Tran", 1, 1, Poly3Tran, AST__NOINV,
+             purpose, author, contact );
+\end{terminalv}
+\normalsize
+
+Here, the fifth argument has been set to the flag value AST\_\_NOINV
+to indicate the lack of an inverse. If the forward transformation were
+absent, we would use AST\_\_NOFOR instead. Flag values for this
+argument may be combined using a bitwise OR if necessary.
+
+\subsection{\label{ss:variableintramapcoordinates}Variable Numbers of Coordinates}
+
+In our earlier examples, we have used a fixed number of input and
+output coordinates when registering a coordinate transformation
+function. It is not necessary to impose this restriction, however, if
+the transformation function can cope with a variable number of
+coordinates (as with the example in
+\secref{ss:transformationfunctions}). We indicate the acceptability of
+a variable number when registering the transformation function by
+supplying the value AST\_\_ANY for the number of input and/or output
+coordinates, as follows:
+
+\small
+\begin{terminalv}
+astIntraReg( "SqrTran", AST__ANY, AST__ANY, SqrTran, 0,
+             purpose, author, contact );
+\end{terminalv}
+\normalsize
+
+The result is that an \htmlref{IntraMap}{IntraMap} may now be created with any number of
+input and output coordinates. For example:
+
+\small
+\begin{terminalv}
+AstIntraMap *intramap1, *intramap2;
+
+...
+
+intramap1 = astIntraMap( "SqrTran", 1, 1, "" );
+intramap2 = astIntraMap( "SqrTran", 3, 3, "Invert=1" );
+\end{terminalv}
+\normalsize
+
+It is possible to fix either the number of input or output coordinates
+(by supplying an explicit number to \htmlref{astIntraReg}{astIntraReg}), but more subtle
+restrictions on the number of coordinates, such as requiring that \htmlref{Nin}{Nin}
+and \htmlref{Nout}{Nout} be equal, are not supported. This means that:
+
+\small
+\begin{terminalv}
+intramap = astIntraMap( "SqrTran", 1, 2, "" );
+\end{terminalv}
+\normalsize
+
+will be accepted without error, although the transformation function
+cannot actually handle such a combination sensibly. If this is
+important, it would be worth adding a check within the transformation
+function itself, so that the error would be detected when it came to
+be used.
+
+\subsection{\label{ss:intraflag}Adapting a Transformation Function to Individual IntraMaps}
+
+In the examples given so far, our coordinate transformation functions
+have not made use of the ``this'' pointer passed to them (which
+identifies the \htmlref{IntraMap}{IntraMap} whose transformation we are implementing). In
+practice, this will often be the case. However, the presence of the
+``this'' pointer allows the transformation function to invoke any
+other AST function on the IntraMap, and this permits enquiries about
+its attributes. The transformation function's behaviour can therefore
+be modified according to any attribute values which are set. This
+turns out to be a useful thing to do, so each IntraMap has a special
+\htmlref{IntraFlag}{IntraFlag} attribute reserved for exactly this purpose.
+
+Consider, for instance, the case where the transformation function has
+access to several alternative sets of internally-stored data which it
+may apply to perform its transformation. Rather than implement many
+different versions of the transformation function, you may switch
+between them by setting a value for the IntraFlag attribute when you
+create an instance of an IntraMap, for example:
+
+\small
+\begin{terminalv}
+intramap1 = astIntraMap( "MyTran", 2, 2, "IntraFlag=A" );
+intramap2 = astIntraMap( "MyTran", 2, 2, "IntraFlag=B" );
+\end{terminalv}
+\normalsize
+
+The transformation function may then enquire the value of the IntraFlag
+attribute (\emph{e.g.}\ using astGetC and passing it the ``this''
+pointer) and use whichever dataset is required for that particular
+IntraMap.
+
+This approach is particularly useful when the number of possible
+transformations is unbounded or not known in advance, in which case
+the IntraFlag attribute may be used to hold numerical values encoded
+as part of a character string (effectively using them as data for the
+IntraMap). It is also superior to the use of a global switch for
+communication (\emph{e.g.}\ setting an index to select the ``current''
+data before using the IntraMap), because it continues to work when
+several IntraMaps are embedded within a more complex compound \htmlref{Mapping}{Mapping},
+when you may have no control over the order in which they are used.
+
+\subsection{\xlabel{MaxTran}\label{ss:simplifyingintramaps}Simplifying IntraMaps}
+
+A notable disadvantage of IntraMaps is that they are ``black boxes''
+as far as AST is concerned. This means that they have limited ability
+to participate in the simplification of compound Mappings performed,
+\emph{e.g.}, by \htmlref{astSimplify}{astSimplify} (\secref{ss:simplifyingcmpmaps}), because
+AST cannot know how they interact with other Mappings. In reality, of
+course, they will often implement such specialised coordinate
+transformations that the simplification possibilities will be rather
+limited anyway.
+
+One important simplification, however, is the ability of a \htmlref{Mapping}{Mapping} to
+cancel with its own inverse to yield a unit Mapping (a \htmlref{UnitMap}{UnitMap}). This
+is important because Mappings are frequently used to relate a dataset
+to some external standard (a celestial coordinate system, for
+example). When inter-relating two similar datasets calibrated using
+the same standard, part of the Mapping often cancels, because it is
+applied first in one direction and then the other, effectively
+eliminating the reference to the standard. This is often a useful
+simplification and can lead to greater efficiency.
+
+Many transformations have this property of cancelling with their own
+inverse, but not necessarily all. Consider the following
+transformation function, for example:
+
+\small
+\begin{terminalv}
+void MaxTran( AstMapping *this, int npoint, int ncoord_in,
+              const double *ptr_in[], int forward, int ncoord_out,
+              double *ptr_out[] ) {
+   double hi, x;
+   int coord, point;
+
+/* Forward transformation. */
+   if ( forward ) {
+      for ( point = 0; point < npoint; point++ ) {
+         hi = AST__BAD;
+         for ( coord = 0; coord < ncoord_in; coord++ ) {
+            x = ptr_in[ coord ][ point ];
+            if ( x != AST__BAD ) {
+               if ( x > hi || hi == AST__BAD ) hi = x;
+            }
+         }
+         ptr_out[ 0 ][ point ] = hi;
+      }
+
+/* Inverse transformation. */
+   } else {
+      for ( coord = 0; coord < ncoord_out; coord++ ) {
+         for ( point = 0; point < npoint; point++ ) {
+            ptr_out[ coord ][ point ] = ptr_in[ 0 ][ point ];
+         }
+      }
+   }
+}
+\end{terminalv}
+\normalsize
+
+This function takes any number of input coordinates and returns a
+single output coordinate which is the maximum value of the input
+coordinates. Its inverse (actually a ``pseudo-inverse'') sets all the
+input coordinates to the value of the output
+coordinate.\footnote{Remember that ``ptr\_in'' identifies the original
+``output'' coordinates when applying the inverse transformation and
+``ptr\_out'' identifies the original ``input'' coordinates.}
+
+If this function is applied in the forward direction and then in the
+inverse direction, it does \textbf{not} in general restore the original
+coordinate values. However, if applied in the inverse direction and
+then the forward direction, it does. Hence, replacing the sequence of
+operations with an equivalent UnitMap is possible in the latter case,
+but not in the former.
+
+To distinguish these possibilities, two flag values are provided for
+use with \htmlref{astIntraReg}{astIntraReg} to indicate what simplification (if any) is
+possible. For example, to register the above transformation function,
+we might use:
+
+\small
+\begin{terminalv}
+void MaxTran( AstMapping *, int, int, const double *[], int, int, double *[] );
+
+...
+
+astIntraReg( "MaxTran", AST__ANY, 1, MaxTran, AST__SIMPIF,
+             purpose, author, contact );
+\end{terminalv}
+\normalsize
+
+Here, the flag value AST\_\_SIMPIF supplied for the fifth argument
+indicates that simplification is possible if the transformation is
+applied in the inverse direction followed by the forward direction. To
+indicate the complementary case, the flag AST\_\_SIMPFI would be used
+instead. If both simplifications are possible (as with the SqrTran
+function in \secref{ss:transformationfunctions}), then we would use
+the bitwise OR of both values.
+
+In practice, some judgement is usually necessary when deciding whether
+to allow simplification. For example, seen in one light our SqrTran
+function (\secref{ss:transformationfunctions}) does not cancel with
+its own inverse, because squaring a coordinate value and then taking
+its square root can change the original value, if this was
+negative. Therefore, replacing this combination with a UnitMap will
+change the behaviour of a compound Mapping and should not be
+allowed. Seen in another light, however, where the coordinates being
+processed are intrinsically all positive, it is a permissible and
+probably useful simplification.
+
+If such distinctions are ever important in practice, it is simple to
+register the same transformation function twice with different flag
+values (use a separate name for each) and then use whichever is
+appropriate when creating an \htmlref{IntraMap}{IntraMap}.
+
+\subsection{\label{ss:readingandwritingintramaps}Writing and Reading IntraMaps}
+
+It is most important to realise that when you write an \htmlref{IntraMap}{IntraMap} to a
+\htmlref{Channel}{Channel} (\secref{ss:writingtoachannel}), the transformation function
+which it uses is not stored with it. To do so is impossible, because
+the function has been compiled and loaded into memory ready for
+execution before AST gets to see it. However, AST does store the name
+associated with the transformation function and various details about
+the IntraMap itself.
+
+
+This means that any program attempting to read the IntraMap
+(\secref{ss:readingfromachannel}) cannot make use of it unless it also
+has independent access to the original transformation function. If it
+does not have access to this function, an error will occur at the
+point where the IntraMap is read and the associated error message will
+direct the user to the author of the transformation function for more
+information.
+
+However, if the necessary transformation function is available, and
+has been registered before the read operation takes place, then AST is
+able to re-create the original IntraMap and will do so. Registration
+of the transformation function must, of course, use the same name
+(and, in fact, be identical in most particulars) as was used in the
+original program which wrote the data.
+
+This means that a set of co-operating programs which all have access
+to the same set of transformation functions and register them in
+identical fashion (see \secref{ss:intramaplibrary} for how this can
+best be achieved) can freely exchange data that contain IntraMaps. The
+need to avoid exporting such data to unsuspecting third parties
+(\secref{ss:intramaplimitations}) must, however, be re-iterated.
+
+\subsection{\label{ss:intramaplibrary}Managing Transformation Functions in Libraries}
+
+If you are developing a large suite of data reduction software, you
+may have a need to use IntraMaps at various points within it. Very
+probably this will occur in unrelated modules which are compiled
+separately and then stored in a library. Since the transformation
+functions required must be registered before they can be used, this
+makes it difficult to decide where to perform this registration,
+especially since any particular data reduction program may use an
+arbitrary subset of the modules in your library.
+
+To assist with this problem, AST allows you to perform the same
+registration of a transformation function any number of times, so long
+as it is performed using an identical invocation of \htmlref{astIntraReg}{astIntraReg} on
+each occasion (\emph{i.e.}\ all of its arguments must be
+identical). This means you do not have to keep track of whether a
+particular function has already been registered but could, in fact,
+register it on each occasion immediately before it is required
+(wherever that may be). In order that all registrations are identical,
+however, it is recommended that you group them all together into a
+single function, perhaps as follows:
+
+\small
+\begin{terminalv}
+void MyTrans( void ) {
+
+   ...
+
+   astIntraReg( "MaxTran", AST__ANY, 1, MaxTran, AST__SIMPIF,
+                purpose, author, contact );
+
+   ...
+
+   astIntraReg( "Poly3Tran", 1, 1, Poly3Tran, AST__NOINV,
+                purpose, author, contact );
+
+   ...
+
+   astIntraReg( "SqrTran", 2, 2, SqrTran, 0,
+                purpose, author, contact );
+}
+\end{terminalv}
+\normalsize
+
+You can then simply invoke this function wherever necessary. It is, in
+fact, particularly important to register all relevant transformation
+functions in this way before you attempt to read an \htmlref{Object}{Object} that might
+be (or contain) an \htmlref{IntraMap}{IntraMap}
+(\secref{ss:readingandwritingintramaps}). This is because you may not
+know in advance which of these transformation functions the IntraMap
+will use, so they must all be available in order to avoid an error.
+
+\cleardoublepage
+\section{\label{ss:plots}Producing Graphical Output (Plots)}
+
+Graphical output from AST is performed though an \htmlref{Object}{Object} called a \htmlref{Plot}{Plot},
+which is a specialised form of \htmlref{FrameSet}{FrameSet}. A Plot does not represent the
+graphical content itself, but is a route through which plotting
+operations, such as drawing lines and curves, are conveyed on to a
+plotting surface to appear as visible graphics.
+
+\subsection{The Plot Model}
+
+When a \htmlref{Plot}{Plot} is created, it is initialised by providing a \htmlref{FrameSet}{FrameSet} whose
+base \htmlref{Frame}{Frame} (as specified by its \htmlref{Base}{Base} attribute) is mapped linearly or
+logarithmically (as specified by the LogPlot attribues) on to a
+\emph{plotting area}. This is a rectangular region in the graphical
+coordinate space of the underlying graphics system and becomes the new
+base Frame of the Plot. In effect, the Plot becomes attached to the
+plotting surface, in rather the same way that a basic FrameSet might be
+attached to (say) an image.
+
+The current Frame of the Plot (derived from the current Frame of the
+FrameSet supplied) is used to represent a \emph{physical coordinate
+system}. This is the system in which plotting operations are
+performed by your program.  Every plotting operation is then
+transformed through the \htmlref{Mapping}{Mapping} which inter-relates the Plot's current
+and base Frames in order to appear on the plotting surface.
+
+An example may help here. Suppose we start with a FrameSet whose base
+Frame describes the pixel coordinates of an image and whose current
+Frame describes a celestial (equatorial) coordinate system. Let us
+assume that these two Frames are inter-related by a Mapping within the
+FrameSet which represents a particular sky projection.
+
+When a Plot is created from this FrameSet, we specify how the pixel
+coordinates (the base Frame) maps on to the plotting surface. This
+simply corresponds to telling the Plot where we have previously
+plotted the image data. If we now use the Plot to plot a line with
+latitude zero in our physical coordinate system, as given by the
+current Frame, this line would appear as a curve (the equator) on the
+plotting surface, correctly registered with the image.
+
+There are a number of plotting functions provided, which all work in a
+similar way. Plotting operations are transformed through the Mapping
+which the Plot represents before they appear on the plotting
+surface.\footnote{Like any FrameSet, a Plot can be used as a
+Mapping. In this case it is the inverse transformation which is used
+when plotting (\emph{i.e.}\ that which transforms between the current
+and base Frames).}  It is possible to draw symbols, lines, axes,
+entire grids and more in this way.
+
+%\subsection{TBW---Creating a Plot}
+
+\subsection{Plotting Symbols}
+
+The simplest form of plotting is to draw symbols (termed
+\emph{markers}) at a set of points. This is performed by \htmlref{astMark}{astMark},
+which is supplied with a set of physical coordinates at which to place
+the markers:
+
+\small
+\begin{terminalv}
+#include "ast.h"
+#define NCOORD 2
+#define NMARK 10
+double in[ NCOORD ][ NMARK ];
+int type;
+
+...
+
+astMark( plot, NMARK, NCOORD, NMARK, in, type );
+\end{terminalv}
+\normalsize
+
+Here, NMARK specifies how many markers to plot and NCOORD specifies
+how many coordinates are being supplied for each
+point.\footnote{Remember, the physical coordinate space need not
+necessarily be 2-dimensional, even if the plotting surface is.} The
+array ``in'' supplies the coordinates and the integer ``type''
+specifies which type of marker to plot.
+
+\subsection{\label{ss:plottinggeodesics}Plotting Geodesic Curves}
+
+There is no \htmlref{Plot}{Plot} routine to draw a straight line, because any straight
+line in physical coordinates can potentially turn into a curve in
+graphical coordinates. We therefore start by considering how to draw
+geodesic curves.  These are curves which trace the path of shortest
+distance between two points in physical coordinates
+ and are the basic drawing element in a Plot.
+
+In many instances, the geodesic will, in fact, be a straight line, but
+this depends on the Plot's current \htmlref{Frame}{Frame}. If this represents a
+celestial coordinate system, for instance, it will be a great circle
+(corresponding with the behaviour of the \htmlref{astDistance}{astDistance} function which
+defines the metric of the physical coordinate space).  The geodesic
+will, of course, be transformed into graphics coordinates before being
+plotted. A geodesic curve is plotted using \htmlref{astCurve}{astCurve} as follows:
+
+\small
+\begin{terminalv}
+double start[ NCOORD ], finish[ NCOORD ];
+
+...
+
+astCurve( plot, start, finish );
+\end{terminalv}
+\normalsize
+
+Here, ``start'' and ``finish'' are arrays containing the starting and
+finishing coordinates of the curve. The \htmlref{astOffset}{astOffset} and astDistance
+functions can often be useful for computing these
+(\secref{ss:distanceandoffset}).
+
+If you need to draw a series of curves end-to-end (when drawing a
+contour line, for example), then a more efficient alternative is to
+use \htmlref{astPolyCurve}{astPolyCurve}. This has the same effect as a sequence of
+invocations of astCurve, but allows you to supply a whole set of
+points at one time. astPolyCurve then joins them, in sequence, using
+geodesic curves:
+
+\small
+\begin{terminalv}
+#define NPOINT 100
+double coords[ NCOORD ][ NPOINT ];
+
+...
+
+astPolyCurve( plot, NPOINT, NCOORD, NPOINT, coords );
+\end{terminalv}
+\normalsize
+
+Here, NPOINT specifies how many points are to be joined and NCOORD
+specifies how many coordinates are being supplied for each point.  The
+array ``coords'' supplies the coordinates of the points in the Plot's
+physical coordinate system.
+
+\subsection{Plotting Curves Parallel to Axes}
+
+As there is no \htmlref{Plot}{Plot} function to draw a ``straight line'', drawing axes
+and grid lines to represent coordinate systems requires a slightly
+different approach. The problem is that for some coordinate systems,
+these grid lines will not be geodesics, so \htmlref{astCurve}{astCurve} and \htmlref{astPolyCurve}{astPolyCurve}
+(\secref{ss:plottinggeodesics}) cannot easily be used (you would have
+to resort to approximating grid lines by many small elements). Lines
+of constant celestial latitude provide an example of this, with the
+exception of the equator which is a geodesic.
+
+The \htmlref{astGridLine}{astGridLine} function allows these curves to be drawn, as follows:
+
+\small
+\begin{terminalv}
+int axis;
+double length;
+
+...
+
+astGridLine( plot, axis, start, length );
+\end{terminalv}
+\normalsize
+
+Here, ``axis'' specifies which physical coordinate axis we wish to
+draw parallel to. The ``start'' array contains the coordinates of the
+start of the curve and ``length'' specifies the distance to draw along
+the axis in physical coordinate space.
+
+\subsection{\label{ss:plottinggeneralizedcurves}Plotting Generalized Curves}
+We have seen how geodesic curves and grid lines can be drawn. The \htmlref{Plot}{Plot}
+class includes another method,
+\htmlref{astGenCurve}{astGenCurve},
+which allows curves of \emph{any} form to be drawn. The caller supplies a
+\htmlref{Mapping}{Mapping} which maps offset along the curve\footnote{normalized so that the
+start of the curve is at offset 0.0 and the end of the curve is at offset
+1.0 - offset need not be linearly related to distance.} into the
+corresponding position in the current \htmlref{Frame}{Frame} of the Plot.
+astGenCurve,
+then takes care of Mapping these positions into graphics coordinates. The
+choice of exactly which positions along the curve are to be used to
+define the curve is also made by
+astGenCurve,
+using an adaptive algorithm which concentrates points around areas where
+the curve is bending sharply or is discontinuous in graphics coordinates.
+
+The \htmlref{IntraMap}{IntraMap} class may be of particular use in this context since it allows
+you to code your own Mappings to do any transformation you choose.
+
+
+\subsection{\label{ss:clipping}Clipping}
+
+Like many graphics systems, a \htmlref{Plot}{Plot} allows you to \emph{clip} the graphics
+you produce. This means that plotting is restricted to certain regions
+of the plotting surface so that anything drawn outside these regions
+will not appear.  All Plots automatically clip at the edges of the
+plotting area specified when the Plot is created. This means that
+graphics are ultimately restricted to the rectangular region of
+plotting space to which you have attached the Plot.
+
+In addition to this, you may also specify lower and upper limits on
+each axis at which clipping should occur. This permits you to further
+restrict the plotting region. Moreover, you may attach these clipping
+limits to \emph{any} of the Frames in the Plot. This allows you to
+place restrictions on where plotting will take place in either the
+physical coordinate system, the graphical coordinate system, or in any
+other coordinate system which is described by a \htmlref{Frame}{Frame} within the Plot.
+
+For example, you could plot using equatorial coordinates and set up
+clipping limits in galactic coordinates. In general, you could set up
+arbitrary clipping regions by adding a new Frame to a Plot (in which
+clipping will be performed) and inter-relating this to the other
+Frames in a suitable way.
+
+Clipping limits are defined using the \htmlref{astClip}{astClip} function, as follows:
+
+\small
+\begin{terminalv}
+#define NAXES 2
+int iframe;
+double lbnd[ NAXES ], ubnd[ NAXES ];
+
+...
+astClip( plot, iframe, lbnd, ubnd);
+\end{terminalv}
+\normalsize
+
+Here, the ``iframe'' value gives the index of the Frame within the
+Plot to which clipping is to be applied, while ``lbnd'' and ``ubnd''
+give the limits on each axis of the selected Frame (NAXES is the
+number of axes in this Frame).
+
+You can remove clipping by giving a value of AST\_\_NOFRAME for ``iframe''.
+
+\subsection{Using a Plot as a Mapping}
+
+All Plots are also Mappings (just like the FrameSets from which they
+are derived), so can be used to transform coordinates.
+
+Like FrameSets, the forward transformation of a \htmlref{Plot}{Plot} will convert
+coordinates between the base and current Frames (\emph{i.e.}\ between
+graphical and physical coordinates). This would be useful if you were
+(say) reading a cursor position in graphical coordinates and needed to
+convert this into physical coordinates for display.
+
+Conversely, a Plot's inverse transformation converts between its
+current and base Frames (\emph{i.e.}\ from physical coordinates to
+graphical coordinates). This transformation is applied automatically
+whenever plotting operations are carried out by AST functions. It may
+also be useful to apply it directly, however, if you wish to perform
+additional plotting operations (\emph{e.g.}\ those provided by the
+native graphics system) at positions specified in physical
+coordinates.
+
+There is, however, one important difference between using a \htmlref{FrameSet}{FrameSet}
+and a Plot to transform coordinates, and this is that clipping may be
+applied by a Plot (if it has been enabled using
+\htmlref{astClip}{astClip}---\secref{ss:clipping}). Any point which lies within the
+clipped region of a Plot will, when transformed, yield coordinates
+with the value AST\_\_BAD. If you wish to avoid this clipping, you
+should extract the relevant \htmlref{Mapping}{Mapping} from the Plot (using
+\htmlref{astGetMapping}{astGetMapping}) and use this, instead of the Plot, to transform the
+coordinates.
+
+\subsection{Using a Plot as a Frame}
+
+Every \htmlref{Plot}{Plot} is also a \htmlref{Frame}{Frame}, so can be used to obtain the values of
+Frame attributes such as a \htmlref{Title}{Title}, axis Labels, axis Units,
+\emph{etc.}, which are typically used when displaying data and/or
+coordinates. These attributes are, as for any \htmlref{FrameSet}{FrameSet}, derived from
+the current Frame of the Plot (\secref{ss:framesetasframe}). They are
+also used automatically when using the Plot to plot coordinate axes
+and coordinate grids (\emph{e.g.}\ for labelling
+them---\secref{ss:plottingagrid}).
+
+Because the current Frame of a Plot represents physical coordinates,
+any Frame operation applied to the Plot will effectively be working in
+this coordinate system. For example, the \htmlref{astDistance}{astDistance} and \htmlref{astOffset}{astOffset}
+functions will compute distances and offsets in physical coordinate
+space, while \htmlref{astFormat}{astFormat} and \htmlref{astNorm}{astNorm} will format physical coordinates in
+an appropriate way for display.
+
+\subsection{\label{ss:validphysicalcoordinates}Regions of Valid Physical Coordinates}
+
+When points in physical coordinate space are transformed by a \htmlref{Plot}{Plot}
+into graphics coordinates for plotting, they may not always yield
+valid coordinates, irrespective of any clipping being applied
+(\secref{ss:clipping}). To indicate this, the resulting coordinate
+values will be set to the value AST\_\_BAD
+(\secref{ss:badcoordinates}).
+
+There are a number of reasons why this may occur, but typically it
+will be because physical coordinates only map on to a subset of the
+graphics coordinate space. This situation is commonly encountered with
+all-sky projections where, typically, the celestial sphere appears,
+when plotted, as a distorted shape (\emph{e.g.}\ an ellipse) which
+does not entirely fill the graphics space. In some cases, there may
+even be multiple regions of valid and invalid physical coordinates.
+
+When plotting is performed \emph{via} a Plot, graphical output will
+only appear in the regions of valid physical coordinates. Nothing will
+appear where invalid coordinates occur. Such output is effectively
+clipped. If you wish to plot in these areas, you must change
+coordinate system and use, say, graphical coordinates to address the
+plotting surface directly.
+
+\subsection{Plotting Borders}
+
+The \htmlref{astBorder}{astBorder} function is provided to draw a (line) border around your
+graphical output. With most graphics systems, this would simply be a
+rectangular box around the plotting area. With a \htmlref{Plot}{Plot}, however, this
+boundary follows the edge of each region containing valid, unclipped
+physical coordinates (\secref{ss:validphysicalcoordinates}).
+
+This means, for example, that if you were plotting an all-sky
+projection, this boundary would outline the perimeter of the celestial
+sphere when projected on to your plotting surface. Of course, if there
+is no clipping and all physical coordinates are valid, then you will
+get the traditional rectangular box. astBorder requires only
+a pointer to the Plot:
+
+\small
+\begin{terminalv}
+int holes;
+
+...
+
+holes = astBorder( plot );
+\end{terminalv}
+\normalsize
+
+It returns a boolean (integer) value to indicate if any invalid or
+clipped physical coordinates were found within the plotting area. If
+they were, it will draw around the valid unclipped regions and return
+a value of one.  Otherwise, it will draw a simple rectangular border
+and return zero.
+
+\subsection{Plotting Text}
+
+Using a \htmlref{Plot}{Plot} to draw text involves supplying a string of text to be
+displayed and a position in physical coordinates where the text is to
+appear. The position is transformed into graphical coordinates to
+determine where the text should appear on the plotting surface. You
+must also provide a 2-element ``up'' vector which gives the upward
+direction of the text in graphical coordinates. This allows text to be
+drawn at any angle.
+
+Plotting is performed by \htmlref{astText}{astText}, for example:
+
+\small
+\begin{terminalv}
+char text[ 21 ];
+double pos[ NCOORD ];
+float up[ 2 ] = { 0.0f, 1.0f };
+
+...
+
+astText( plot, text, pos, up, "TL" );
+\end{terminalv}
+\normalsize
+
+Here, ``text'' contains the string to be drawn, ``pos'' is an array of
+physical coordinates and ``up'' specifies the upward vector. In this
+case, the text will be drawn horizontally. The final argument
+specifies the text justification, here indicating that the top left
+corner of the text should appear at the position given.
+
+Further control over the appearance of the text is possible by setting
+values for various Plot attributes, for example Colour, Font and Size.
+Sub-strings within the displayed text can be given different appearances,
+or turned into super-scripts or sub-scripts, by the inclusion of escape
+sequences (see section~\secref{ss:escapes}) within the supplied text string.
+
+\subsection{\label{ss:plottingagrid}Plotting a Grid}
+
+The most comprehensive plotting function available is \htmlref{astGrid}{astGrid}, which
+can be used to draw labelled coordinate axes and, optionally, to
+overlay coordinate grids on the plotting area
+(Figure~\ref{fig:gridplot}). The routine is straightforward to use,
+simply requiring a pointer to the \htmlref{Plot}{Plot}:
+
+\small
+\begin{terminalv}
+astGrid( plot );
+\end{terminalv}
+\normalsize
+
+It will draw both linear and curvilinear axes and grids, as required
+by the particular Plot. The appearance of the output can be modified
+in a wide variety of ways by setting various Plot attributes.
+The Label attributes of the current \htmlref{Frame}{Frame} are displayed as the axis
+labels in the grid, and the \htmlref{Title}{Title} attribute as the plot title. Sub-strings
+within these strings can be given different appearances, or turned into
+super-scripts or sub-scripts, by the inclusion of escape sequences (see
+section~\secref{ss:escapes}) within the Label attributes.
+
+\subsection{\label{ss:escapes}Controlling the Appearance of Sub-strings}
+Normally, each string of characters displayed using a \htmlref{Plot}{Plot} will be
+plotted so that all characters in the string have the same font size,
+colour, \emph{etc.}, specified by the appropriate attributes of the
+Plot. However, it is possible to include \emph{escape sequences} within
+the text to modify the appearance of sub-strings. \htmlref{Escape}{Escape} sequences can be
+used to change, colour, font, size, width, to introduce extra horizontal
+space between characters, and to change the base line of characters (thus
+allowing super-scripts and sub-scripts to be created). See the entry for
+the Escape attribute in \appref{ss:attributedescriptions} for details.
+
+As an example, if the character string ``\verb+10\%^50+\%s70+0.5+'' is
+plotted, it will be displayed as ``$10^{0.5}$'' - that is, with a
+super-scripted exponent. The exponent text will be 70\% of the size of
+normal text (as determined by the Size attribute), and its baseline will
+be raised by 50\% of the height of a normal character.
+
+Such escape sequences can be used in the strings assigned to textual
+attributes of the Plot (such as the axis Labels), and may also be
+included in strings plotted using
+\htmlref{astText}{astText}.
+
+The Format attribute for the \htmlref{SkyAxis}{SkyAxis} class includes the ``g'' option
+which will cause escape sequences to be included when formatting
+celestial positions so that super-script characters are used as
+delimiters for the various fields (a super-script ``h'' for hours, ``m''
+for minutes, \emph{etc}).
+
+Note, the facility for interpreting escape sequences is only available if
+the graphics wrapper functions which provide the interface to the
+underlying graphics system support all the functions included in the
+\verb+grf.h+ file as of AST V3.2. Older grf interfaces may need to be
+extended by the addition of new functions before escape sequences can be
+interpretted.
+
+\subsection{\label{ss:logaxes}Producing Logarithmic Axes}
+In certain situations you may wish for one or both of the plotted axes to
+be displayed logarithmically rather than linearly. For instance, you may
+wish to do this when using a \htmlref{Plot}{Plot} to represent a spectrum of, say, flux
+against frequency. In this case, you can cause the frequency axis to be drawn
+logarithmically simply by setting the boolean LogPlot attribute for the
+frequency axis to a non-zero value. This causes several things to happen:
+
+\begin{enumerate}
+
+\item The \htmlref{Mapping}{Mapping} between the base \htmlref{Frame}{Frame} of the Plot (which represents
+the underlying graphics world coordinate system) and the base Frame of
+the \htmlref{FrameSet}{FrameSet} supplied when the Plot was created, is modified. By
+default, this mapping is linear on both axes, but setting LogPlot non-zero
+for an axis causes the Mapping to be modified so that it is logarithmic
+on the specified axis. This is only possible if the displayed section of
+the axis does not include the value zero (otherwise the attempt to set
+a new value for LogPlot is ignored,and it retains its default value of
+zero).
+
+\item The major tick marks drawn as part of the annotated coordinate grid
+are spaced logarithmically rather than linearly. That is, major axis
+values are chosen so that there is a constant ratio between adjacent
+tick mark values. This ratio is constrained to be a power of ten. The
+minor tick marks are drawn at linearly distributed points between the
+adjoining major tick values. Thus if a pair of adjacent major tick values
+are drawn at axis values 10.0 and 100.0, minor ticks will be placed at
+20.0, 30.0, 40.0, 50.0, 60.0, 70.0, 80.0 and 90.0 (note only 8 minor tick
+marks are drawn).
+
+\item If possible, numerical axis labels are shown as powers of ten.
+This depends on the facilities implemented by the graphics wrapper
+functions (see the next section). Extra functions were introduced to this
+set of wrapper functions at AST V3.2 which enable super-scripts and
+sub-scripts to be produced. Some older wrappers may not yet have
+implemented these functiosn and this will result in axis labels being
+drawn in usual scientific or decimal notation.
+
+\end{enumerate}
+
+Whilst the LogPlot attribute can be used to control all three of the above
+facilities, it is possible to control them individually as well. The
+LogTicks and LogLabel attributes control the behaviour specified in items
+2 and 3 above, but the default values for these attributes depend on the
+setting of the LogPlot attribute. This means that setting LogPlot
+non-zero will swicth all three facilites on, so long as zero values have
+not been assigned explicitly to LogTicks or LogLabel.
+
+
+\subsection{\label{ss:choosingagraphicspackage}Choosing a Graphics Package}
+The \htmlref{Plot}{Plot} class itself does not include any code for actually drawing on a
+graphics device. Instead, it requires a set of functions to be provided
+which it uses to draw the required graphics. These include functions
+to draw a straight line, draw a text string, \emph{etc}. You may choose
+to provide functions from your favorite graphics package, or you can even
+write your own! To accomodate variations in the calling interfaces of
+different graphics packages, AST defines a standard interface for these
+routines. If this interface differs from the interface provided by your
+graphics package (which in general it will), then you must write a set of
+\emph{wrapper functions}, which provide the interface expected by AST but
+which then call functions from your graphics package to provide the
+required functionality. AST comes with wrapper functions suitable for
+the PGPLOT graphics package (see \xref{SUN/15}{sun15}{}).
+
+There are two ways of indicating which wrapper functions are to be used by
+the Plot class:
+\begin{enumerate}
+
+\item A file containing C functions with pre-defined names can be written
+and linked with the application using options of the \htmlref{ast\_link}{ast\_link} command.
+(see \secref{ss:howtobuild} and \appref{ss:commanddescriptions}). AST is
+distributed with such a file (called \texttt{grf\_pgplot.c}) which calls PGPLOT
+functions to implement the required functionality. This file can be used
+as a template for writing your own.
+
+\item The
+\htmlref{astGrfSet}{astGrfSet}
+method of the Plot class can be used to ``register''
+wrapper functions at run-time. This allows an application to switch
+between graphics systems if required. Graphics functions registered in
+this way do not need to have the pre-defined names used in the link-time
+method described above.
+
+\end{enumerate}
+
+For details of the interfaces of the wrapper routines, see
+either the \texttt{grf\_pgplot.c} file included in the AST source
+distribution, or the reference documentation for the astGrfSet method.
+
+\cleardoublepage
+\section{Compiling and Linking Software that Uses AST}
+
+A small number of UNIX commands are provided by AST to assist with the
+process of building software. A description of these can be found in
+\appref{ss:commanddescriptions} and their use is discussed here.  Note
+that in order to access these commands, the appropriate directory
+(normally ``/star/bin'') should be on your PATH.\footnote{If you have
+not installed AST in the usual location, then substitute the
+appropriate directory in place of ``/star'' wherever it occurs.}
+
+\subsection{\label{ss:accessingheaderfile}Accessing the ``ast.h'' Header File}
+
+The ``ast.h'' header file defines the external interface to the AST library,
+including all constants, function prototypes, macros, \emph{etc.}. This file
+should be located using the usual compiler options for finding C
+include files, for instance:
+
+\small
+\begin{terminalv}
+cc prog.c -I/star/include -o prog
+\end{terminalv}
+\normalsize
+
+This is preferable to specifying the file's absolute name within your
+software.
+
+\subsection{\label{ss:linking}Linking with AST Facilities}
+
+C programs which use AST facilities may be linked by including
+execution of the command ``\htmlref{ast\_link}{ast\_link}'' on the compiler command
+line. Thus, to compile and link a program called ``prog'', the
+following might be used:
+
+\small
+\begin{terminalv}
+cc prog.c -L/star/lib `ast_link` -o prog
+\end{terminalv}
+\normalsize
+
+Note the use of backward quote characters, which cause the
+``ast\_link'' command to be executed and its result substituted into
+the compiler command. An alternative is to save the output from
+``ast\_link'' in (say) a shell variable and use this instead. You may
+find this a little faster if you are building software repeatedly
+during development.
+
+Programs which use AST can also be linked in a number of other ways,
+depending on the facilities they require. In the example above, we
+have used the default method which assumes that the program will not
+be generating graphical output, so that no graphics libraries need be
+linked. If you need other facilities, then various switches can be
+applied to the ``ast\_link'' command in order to control the linking
+process.
+
+For example, if you were producing graphical output using the PGPLOT
+graphics package, you could link with the AST/PGPLOT interface by
+using the ``$-$pgplot'' switch with ``ast\_link'', as
+follows:\footnote{Use the ``$-$pgp'' option instead if you wish to use
+the Starlink version of PGPLOT which uses GKS to generate its output.}
+
+\small
+\begin{terminalv}
+cc prog.c -L/star/lib `ast_link -pgplot` -o prog
+\end{terminalv}
+\normalsize
+
+See the ``ast\_link'' command description in
+\appref{ss:commanddescriptions} for details of the options available.
+
+\subsection{Building ADAM Applications that Use AST}
+
+Users of Starlink's \xref{ADAM}{sg4}{} programming environment
+\latex{(SG/4)} on UNIX should use the
+``\xref{alink}{sun144}{ADAM_link_scripts}'' command
+(\xref{SUN/144}{sun144}{}) to compile and link applications and can
+access the AST library by including execution of the command
+``\htmlref{ast\_link\_adam}{ast\_link\_adam}'' on the command line, as follows:
+
+\begin{small}
+\begin{terminalv}
+alink adamprog.c `ast_link_adam`
+\end{terminalv}
+\end{small}
+
+Note the use of backward quote characters.
+
+By default, AST error messages produced by applications built in this
+way will be delivered \emph{via} the Starlink EMS Error Message
+Service (\xref{SSN/4}{ssn4}{}) so that error handling by AST is
+consistent with the \xref{\emph{inherited
+status}}{sun104}{inherited_status} error handling normally used in
+Starlink software.
+
+Switches may be given to the ``ast\_link\_adam'' command (in a similar
+way to ``\htmlref{ast\_link}{ast\_link}''---\secref{ss:linking}) in order to link with
+additional AST-related facilities, such as a graphics interface. See
+the ``ast\_link\_adam'' command description in
+\appref{ss:commanddescriptions} for details of the options available.
+
+\appendix
+\cleardoublepage
+\section{\label{ss:classhierarchy}The AST Class Hierarchy}
+The following table shows the hierarchy of classes in the AST library.
+For a description of each class, you should consult
+\appref{ss:classdescriptions}.
+
+\small
+\begin{terminalv}
+Object             - Base class for all AST Objects
+   Axis            - Store axis information
+      SkyAxis      - Store celestial axis information
+   Channel         - Basic (textual) I/O channel
+      FitsChan     - I/O Channel using FITS header cards
+      XmlChan      - I/O Channel using XML
+      StcsChan     - I/O Channel using IVOA STC-S descriptions
+   KeyMap          - Store a set of key/value pairs
+      Table        - Store a 2-dimensional table of values
+   Mapping         - Inter-relate two coordinate systems
+      CmpMap       - Compound Mapping
+      DssMap       - Map points using Digitised Sky Survey plate solution
+      Frame        - Coordinate system description
+         CmpFrame  - Compound Frame
+            SpecFluxFrame - Observed value versus spectral position
+         FluxFrame - Observed value at a given fixed spectral position
+         FrameSet  - Set of inter-related coordinate systems
+            Plot   - Provide facilities for 2D graphical output
+               Plot3D - Provide facilities for 3D graphical output
+         Region    - Specify areas within a coordinate system
+            Box    - A box region with sides parallel to the axes of a Frame
+            Circle - A circular or spherical region within a Frame
+            CmpRegion  - A combination of two regions within a single Frame
+            Ellipse    - An elliptical region within a 2-dimensional Frame
+            Interval   - Intervals on one or more axes of a Frame.
+            NullRegion - A boundless region within a Frame
+            PointList  - A collection of points in a Frame
+            Polygon    - A polygonal region within a 2-dimensional Frame
+            Prism  - An extrusion of a Region into orthogonal dimensions
+            Stc    - Represents an generic instance of an IVOA STC-X description
+               StcResourceProfile - Represents an an IVOA STC-X ResourceProfile
+               StcSearchLocation  - Represents an an IVOA STC-X SearchLocation
+               StcCatalogEntryLocation - Represents an an IVOA STC-X CatalogEntryLocation
+               StcObsDataLocation - Represents an an IVOA STC-X ObsDataLocation
+         SkyFrame  - Celestial coordinate system description
+         SpecFrame - Spectral coordinate system description
+            DSBSpecFrame - Dual sideband spectral coordinate system description
+         TimeFrame - Time coordinate system description
+      GrismMap     - Models the spectral dispersion produced by a grism
+      IntraMap     - Map points using a private transformation function
+      LutMap       - Transform 1-dimensional coordinates using a lookup table
+      MathMap      - Transform coordinates using mathematical expressions
+      MatrixMap    - Map positions by multiplying them by a matrix
+      NormMap      - Normalise coordinates using a supplied Frame
+      PcdMap       - Apply 2-dimensional pincushion/barrel distortion
+      PermMap      - Coordinate permutation Mapping
+      PolyMap      - General N-dimensional polynomial Mapping
+        ChebyMap   - N-dimensional Chebyshev polynomial Mapping
+      RateMap      - Calculates an element of a Mapping's Jacobian matrix
+      SelectorMap  - Locates positions within a set of Regions
+      ShiftMap     - Shifts each axis by a constant amount
+      SlaMap       - Sequence of celestial coordinate conversions
+      SpecMap      - Sequence of spectral coordinate conversions
+      SphMap       - Map 3-d Cartesian to 2-d spherical coordinates
+      SwitchMap    - Encapuslates a set of alternate Mappings
+      TimeMap      - Sequence of time coordinate conversions
+      TranMap      - Combine fwd. and inv. transformations from two Mappings
+      UnitMap      - Unit (null) Mapping
+      UnitNormMap  - Converts a vector to a unit vector plus length
+      WcsMap       - Implement a FITS-WCS sky projection
+      WinMap       - Match windows by scaling and shifting each axis
+      ZoomMap      - Zoom coordinates about the origin
+\end{terminalv}
+\normalsize
+
+\cleardoublepage
+\section{\label{ss:functiondescriptions}AST Function Descriptions}
+\small
+\sstroutine{
+   astSet
+}{
+   Set attribute values for an Object
+}{
+   \sstdescription{
+      This function assigns a set of attribute values to an \htmlref{Object}{Object},
+      over-riding any previous values. The attributes and their new
+      values are specified via a character string, which should
+      contain a comma-separated list of the form:
+
+         \texttt{"} attribute\_1 = value\_1, attribute\_2 = value\_2, ... \texttt{"}
+
+      where \texttt{"} attribute\_n\texttt{"}  specifies an attribute name, and the value
+      to the right of each \texttt{"} =\texttt{"}  sign should be a suitable textual
+      representation of the value to be assigned. This value will be
+      interpreted according to the attribute\texttt{'} s data type.
+
+      The string supplied may also contain \texttt{"} printf\texttt{"} -style format
+      specifiers, identified by \texttt{"} \%\texttt{"}  signs in the usual way. If
+      present, these will be substituted by values supplied as
+      additional optional arguments (using the normal \texttt{"} printf\texttt{"}  rules)
+      before the string is used.
+   }
+   \sstsynopsis{
+      void astSet( AstObject $*$this, const char $*$settings, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Object.
+      }
+      \sstsubsection{
+         settings
+      }{
+         Pointer to a null-terminated character string containing a
+         comma-separated list of attribute settings in the form described
+         above.
+      }
+      \sstsubsection{
+         ...
+      }{
+         Optional additional arguments which supply values to be
+         substituted for any \texttt{"} printf\texttt{"} -style format specifiers that
+         appear in the \texttt{"} settings\texttt{"}  string.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         This function applies to all Objects.
+      }
+   }
+   \sstexamples{
+      \sstexamplesubsection{
+         astSet( map, \texttt{"} \htmlref{Report}{Report} = 1, \htmlref{Zoom}{Zoom} = 25.0\texttt{"}  );
+      }{
+         Sets the Report attribute for Object \texttt{"} map\texttt{"}  to the value 1 and
+         the Zoom attribute to 25.0.
+      }
+      \sstexamplesubsection{
+         astSet( frame, \texttt{"} Label( \%d ) =Offset along axis \%d\texttt{"} , axis, axis );
+      }{
+         Sets the \htmlref{Label(axis)}{Label(axis)} attribute for Object \texttt{"} frame\texttt{"}  to a
+         suitable string, where the axis number is obtained from
+         \texttt{"} axis\texttt{"} , a variable of type int.
+      }
+      \sstexamplesubsection{
+         astSet( frame, \texttt{"} \htmlref{Title}{Title} =\%s\texttt{"} , mystring );
+      }{
+         Sets the Title attribute for Object \texttt{"} frame\texttt{"}  to the contents of
+         the string \texttt{"} mystring\texttt{"} .
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Attribute names are not case sensitive and may be surrounded
+         by white space.
+
+         \sstitem
+          White space may also surround attribute values, where it will
+         generally be ignored (except for string-valued attributes where
+         it is significant and forms part of the value to be assigned).
+
+         \sstitem
+          To include a literal comma in the value assigned to an attribute,
+         the whole attribute value should be enclosed in quotation markes.
+         Alternatively, you can use \texttt{"} \%s\texttt{"}  format and supply the value as a
+         separate additional argument to astSet (or use the astSetC
+         function instead).
+
+         \sstitem
+          The same procedure may be adopted if \texttt{"} \%\texttt{"}  signs are to be included
+         and are not to be interpreted as format specifiers (alternatively,
+         the \texttt{"} printf\texttt{"}  convention of writing \texttt{"} \%\%\texttt{"}  may be used).
+
+         \sstitem
+          An error will result if an attempt is made to set a value for
+         a read-only attribute.
+      }
+   }
+}
+\sstroutine{
+   astActiveObjects
+}{
+   Return pointers for all active Objects
+}{
+   \sstdescription{
+      This function returns a \htmlref{KeyMap}{KeyMap} holding currently active AST \htmlref{Object}{Object}
+      pointers. Each entry in the KeyMap will have a key that is an AST
+      class name such as \texttt{"} \htmlref{FrameSet}{FrameSet}\texttt{"} , \texttt{"} \htmlref{SkyFrame}{SkyFrame}\texttt{"} , \texttt{"} \htmlref{ZoomMap}{ZoomMap}\texttt{"} , etc. The
+      value of the entry will be a 1-dimensional list of pointers for
+      objects of the same class. Note, the returned pointers should NOT
+      be annulled when they are no longer needed.
+
+      The pointers to return in the KeyMap may be restricted either by
+      class or by context level using the function arguments.
+   }
+   \sstsynopsis{
+      AstKeyMap $*$astActiveObjects( const char $*$class, int subclass,
+                                   int current )
+   }
+   \sstparameters{
+      \sstsubsection{
+         class
+      }{
+         If NULL, then the returned KeyMap will contain pointers ofr
+         Objects of all classes. If not NULL, then \texttt{"} class\texttt{"}  should be a
+         pointer to a null-terminated string holding the name of an AST
+         class. The returned KeyMap will contain pointers only for the
+         specified class. See also \texttt{"} subclass\texttt{"} .
+      }
+      \sstsubsection{
+         subclass
+      }{
+         A Boolean flag indicating if all subclasses of the class
+         specified by \texttt{"} class\texttt{"}  should be included in the returned KeyMap.
+         If zero, then subclass objects are not returned. Otherwise they
+         are returned. The supplied \texttt{"} subclass\texttt{"}  value is ignored if
+         \texttt{"} class\texttt{"}  is NULL.
+      }
+      \sstsubsection{
+         current
+      }{
+         A Boolean flag indicating if the returned list of pointers
+         should be restricted to pointers issued within the current AST
+         object context (see \htmlref{astBegin}{astBegin} and \htmlref{astEnd}{astEnd}).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astActiveObjects()
+      }{
+         A pointer to a new KeyMap holding the required object pointers.
+         They KeyMap pointer should be annulled when it is no longer
+         needed, but the object pointers within the KeyMap should not be
+         annulled. A NULL pointer is returned if an error has occurred
+         prior to calling this function.
+
+         The values stored in the KeyMap should be accessed as generic C
+         pointers using the KeyMap \texttt{"} P\texttt{"}  data type (e.g. using function
+         astMapGetlemP etc).
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This function will only return objects locked by the currently
+         executing thread.
+
+         \sstitem
+          The KeyMap pointer returned by this function is not included in the
+         list of active objects stored in the KeyMap.
+
+         \sstitem
+          Objects that were created using the Fortran interface will have a
+         null \texttt{"} file\texttt{"}  value and will have a routine name equal to the upper case
+         Fortran routine that issued the pointer (e.g. \texttt{"} AST\_CLONE\texttt{"} , \texttt{"} AST\_FRAME\texttt{"} ,
+         etc).
+      }
+   }
+}
+\sstroutine{
+   astAddColumn
+}{
+   Add a new column definition to a table
+}{
+   \sstdescription{
+      Adds the definition of a new column to the supplied table. Initially,
+      the column is empty. Values may be added subsequently using the
+      methods of the \htmlref{KeyMap}{KeyMap} class.
+   }
+   \sstsynopsis{
+      void astAddColumn( AstTable $*$this, const char $*$name, int type, int ndim,
+                         int $*$dims, const char $*$unit )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the \htmlref{Table}{Table}.
+      }
+      \sstsubsection{
+         name
+      }{
+         The column name. Trailing spaces are ignored (all other spaces
+         are significant). The supplied string is converted to upper case.
+      }
+      \sstsubsection{
+         type
+      }{
+         The data type associated with the column. See \texttt{"} Applicability:\texttt{"}
+         below.
+      }
+      \sstsubsection{
+         ndim
+      }{
+         The number of dimensions spanned by the values stored in a single
+         cell of the column. Zero if the column holds scalar values.
+      }
+      \sstsubsection{
+         dims
+      }{
+         An array holding the the lengths of each of the axes spanned by
+         the values stored in a single cell of the column. Ignored if the
+         column holds scalara values.
+      }
+      \sstsubsection{
+         unit
+      }{
+         A string specifying the units of the column. Supply a blank
+         string if the column is unitless.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Table
+      }{
+         Tables can hold columns with any of the following data types -
+         AST\_\_INTTYPE (for integer), AST\_\_SINTTYPE (for
+         short int),
+         AST\_\_BYTETYPE (for
+         unsigned bytes - i.e. unsigned chars),
+         AST\_\_DOUBLETYPE (for double
+         precision floating point), AST\_\_FLOATTYPE (for single
+         precision floating point), AST\_\_STRINGTYPE (for character string),
+         AST\_\_OBJECTTYPE (for AST \htmlref{Object}{Object} pointer), AST\_\_POINTERTYPE (for
+         arbitrary C pointer) or AST\_\_UNDEFTYPE (for undefined values
+         created by
+         \htmlref{astMapPutU}{astMapPutU}).
+      }
+      \sstsubsection{
+         \htmlref{FitsTable}{FitsTable}
+      }{
+         FitsTables can hold columns with any of the following data types -
+         AST\_\_INTTYPE (for integer), AST\_\_SINTTYPE (for
+         short int),
+         AST\_\_BYTETYPE (for
+         unsigned bytes - i.e. unsigned chars),
+         AST\_\_DOUBLETYPE (for double
+         precision floating point), AST\_\_FLOATTYPE (for single
+         precision floating point), AST\_\_STRINGTYPE (for character string).
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This
+         function
+         returns without action if a column already exists in the Table
+         with the supplied name and properties. However an error is
+         reported if any of the properties differ.
+      }
+   }
+}
+\sstroutine{
+   astAddFrame
+}{
+   Add a Frame to a FrameSet to define a new coordinate system
+}{
+   \sstdescription{
+      This function adds a new \htmlref{Frame}{Frame} and an associated \htmlref{Mapping}{Mapping} to a
+      \htmlref{FrameSet}{FrameSet} so as to define a new coordinate system, derived from
+      one which already exists within the FrameSet. The new Frame then
+      becomes the FrameSet\texttt{'} s current Frame.
+
+      This function
+      may also be used to merge two FrameSets, or to append extra axes
+      to every Frame in a FrameSet.
+   }
+   \sstsynopsis{
+      void astAddFrame( AstFrameSet $*$this, int iframe, AstMapping $*$map,
+                        AstFrame $*$frame )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FrameSet.
+      }
+      \sstsubsection{
+         iframe
+      }{
+         The index of the Frame within the FrameSet which describes
+         the coordinate system upon which the new one is to be based.
+         This value should lie in the range from 1 to the number of
+         Frames already in the FrameSet (as given by its \htmlref{Nframe}{Nframe}
+         attribute). As a special case, AST\_\_ALLFRAMES may be supplied,
+         in which case the axes defined by the supplied Frame are appended
+         to every Frame in the FrameSet (see the Notes section for details).
+      }
+      \sstsubsection{
+         map
+      }{
+         Pointer to a Mapping which describes how to convert
+         coordinates from the old coordinate system (described by the
+         Frame with index \texttt{"} iframe\texttt{"} ) into coordinates in the new
+         system. The Mapping\texttt{'} s forward transformation should perform
+         this conversion, and its inverse transformation should
+         convert in the opposite direction. The supplied Mapping is ignored
+         if parameter \texttt{"} iframe\texttt{"} is equal to AST\_\_ALLFRAMES.
+      }
+      \sstsubsection{
+         frame
+      }{
+         Pointer to a Frame that describes the new coordinate system.
+         Any class of Frame may be supplied (including Regions and
+         FrameSets).
+
+         This function may also be used to merge two FrameSets by
+         supplying a pointer to a second FrameSet for this parameter
+         (see the Notes section for details).
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Deep copies of the supplied
+         \texttt{"} mapping\texttt{"}  and \texttt{"} frame\texttt{"}
+         objects are stored within the modified FrameSet. So any changes made
+         to the FrameSet after calling this method will have no effect on the
+         supplied Mapping and Frame objects.
+
+         \sstitem
+          A value of AST\_\_BASE or AST\_\_CURRENT may be given for the
+         \texttt{"} iframe\texttt{"}  parameter to specify the base Frame or the current
+         Frame respectively.
+
+         \sstitem
+          This function sets the value of the \htmlref{Current}{Current} attribute for the
+         FrameSet so that the new Frame subsequently becomes the current
+         Frame.
+
+         \sstitem
+          The number of input coordinate values accepted by the supplied
+         Mapping (its \htmlref{Nin}{Nin} attribute) must match the number of axes in the
+         Frame identified by the \texttt{"} iframe\texttt{"}  parameter. Similarly, the
+         number of output coordinate values generated by this Mapping
+         (its \htmlref{Nout}{Nout} attribute) must match the number of axes in the new
+         Frame.
+
+         \sstitem
+          As a special case, if a pointer to a FrameSet is given for the
+         \texttt{"} frame\texttt{"}  parameter, this is treated as a request to merge a pair of
+         FrameSets.  This is done by appending all the new Frames (in the
+         \texttt{"} frame\texttt{"}  FrameSet) to the original FrameSet, while preserving
+         their order and retaining all the inter-relationships
+         (i.e. Mappings) between them. The two sets of Frames are
+         inter-related within the merged FrameSet by using the Mapping
+         supplied. This should convert between the Frame identified by
+         the \texttt{"} iframe\texttt{"}  parameter (in the original FrameSet) and the current
+         Frame of the \texttt{"} frame\texttt{"}  FrameSet. This latter Frame becomes the
+         current Frame in the merged FrameSet.
+
+         \sstitem
+          As another special case, if a value of AST\_\_ALLFRAMES is supplied
+         for parameter
+         \texttt{"} iframe\texttt{"} ,
+         then the supplied Mapping is ignored, and the axes defined by the
+         supplied Frame are appended to each Frame in the FrameSet. In detail,
+         each Frame in the FrameSet is replaced by a \htmlref{CmpFrame}{CmpFrame} containing the
+         original Frame and the Frame specified by parameter
+         \texttt{"} frame\texttt{"} .
+         In addition, each Mapping in the FrameSet is replaced by a \htmlref{CmpMap}{CmpMap}
+         containing the original Mapping and a \htmlref{UnitMap}{UnitMap} in parallel. The Nin and
+         Nout attributes of the UnitMap are set equal to the number of axes
+         in the supplied Frame. Each new CmpMap is simplified using
+         \htmlref{astSimplify}{astSimplify}
+         before being stored in the FrameSet.
+      }
+   }
+}
+\sstroutine{
+   astAddParameter
+}{
+   Add a new global parameter definition to a table
+}{
+   \sstdescription{
+      Adds the definition of a new global parameter to the supplied
+      table. Note, this does not store a value for the parameter. To get
+      or set the parameter value, the methods of the paremt \htmlref{KeyMap}{KeyMap} class
+      should be used, using the name of the parameter as the key.
+   }
+   \sstsynopsis{
+      void astAddParameter( AstTable $*$this, const char $*$name )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the \htmlref{Table}{Table}.
+      }
+      \sstsubsection{
+         name
+      }{
+         The parameter name. Trailing spaces are ignored (all other spaces
+         are significant). The supplied string is converted to upper case.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Unlike columns, the definition of a parameter does not specify its type,
+         size or dimensionality.
+      }
+   }
+}
+\sstroutine{
+   astAddVariant
+}{
+   Store a new variant Mapping for the current Frame in a FrameSet
+}{
+   \sstdescription{
+      This function
+      allows a new variant \htmlref{Mapping}{Mapping} to be stored with the current \htmlref{Frame}{Frame}
+      in a \htmlref{FrameSet}{FrameSet}. See the \texttt{"} \htmlref{Variant}{Variant}\texttt{"}  attribute for more details. It can
+      also be used to rename the currently selected variant Mapping.
+   }
+   \sstsynopsis{
+      void astAddVariant( AstFrameSet $*$this, AstMapping $*$map,
+                          const char $*$name )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FrameSet.
+      }
+      \sstsubsection{
+         map
+      }{
+         Pointer to a Mapping which describes how to convert
+         coordinates from the current Frame to the new variant of the
+         current Frame. If
+         NULL
+         is supplied, then the name associated with the currently selected
+         variant of the current Frame is set to the value supplied for
+         \texttt{"} name\texttt{"} , but no new variant is added.
+      }
+      \sstsubsection{
+         name
+      }{
+         The name to associate with the new variant Mapping (or the currently
+         selected variant Mapping if
+         \texttt{"} map\texttt{"}  is NULL).
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The newly added Variant becomes the current variant on exit (this is
+         equivalent to setting the Variant attribute to the value supplied for
+         \texttt{"} name).
+
+         \sstitem
+          An error is reported if a variant with the supplied name already
+         exists in the current Frame.
+
+         \sstitem
+          An error is reported if the current Frame is a mirror for the
+         variant Mappings in another Frame. This is only the case if the
+         \htmlref{astMirrorVariants}{astMirrorVariants} function
+         has been called to make the current Frame act as a mirror.
+      }
+   }
+}
+\sstroutine{
+   astAngle
+}{
+   Calculate the angle subtended by two points at a third point
+}{
+   \sstdescription{
+      This function
+      finds the angle at point B between the line joining points A and B,
+      and the line joining points C and B. These lines will in fact be
+      geodesic curves appropriate to the \htmlref{Frame}{Frame} in use. For instance, in
+      \htmlref{SkyFrame}{SkyFrame}, they will be great circles.
+   }
+   \sstsynopsis{
+      double astAngle( AstFrame $*$this, const double a[], const double b[],
+                       const double c[] )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Frame.
+      }
+      \sstsubsection{
+         a
+      }{
+         An array of double, with one element for each Frame axis
+         (\htmlref{Naxes}{Naxes} attribute) containing the coordinates of the first point.
+      }
+      \sstsubsection{
+         b
+      }{
+         An array of double, with one element for each Frame axis
+         (Naxes attribute) containing the coordinates of the second point.
+      }
+      \sstsubsection{
+         c
+      }{
+         An array of double, with one element for each Frame axis
+         (Naxes attribute) containing the coordinates of the third point.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astAngle
+      }{
+         The angle in radians, from the line AB to the line CB. If the
+         Frame is 2-dimensional, it will be in the range \$$\backslash$pm $\backslash$pi\$,
+         and positive rotation is in the same sense as rotation from
+         the positive direction of axis 2 to the positive direction of
+         axis 1. If the Frame has more than 2 axes, a positive value will
+         always be returned in the range zero to \$$\backslash$pi\$.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A value of AST\_\_BAD will also be returned if points A and B are
+         co-incident, or if points B and C are co-incident.
+
+         \sstitem
+          A value of AST\_\_BAD will also be returned if this function is
+         invoked with the AST error status set, or if it should fail for
+         any reason.
+      }
+   }
+}
+\sstroutine{
+   astAnnul
+}{
+   Annul a pointer to an Object
+}{
+   \sstdescription{
+      This function annuls a pointer to an \htmlref{Object}{Object} so that it is no
+      longer recognised as a valid pointer by the AST library. Any
+      resources associated with the pointer are released and made
+      available for re-use.
+
+      This function also decrements the Object\texttt{'} s \htmlref{RefCount}{RefCount} attribute by
+      one. If this attribute reaches zero (which happens when the last
+      pointer to the Object is annulled), then the Object is deleted.
+   }
+   \sstsynopsis{
+      AstObject $*$astAnnul( AstObject $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         The Object pointer to be annulled.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         This function applies to all Objects.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astAnnul()
+      }{
+         A null Object pointer (AST\_\_NULL) is always returned.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This function will attempt to annul the pointer even if the
+         Object is not currently locked by the calling thread (see \htmlref{astLock}{astLock}).
+
+         \sstitem
+          This function attempts to execute even if the AST error
+         status is set
+         on entry, although no further error report will be
+         made if it subsequently fails under these circumstances. In
+         particular, it will fail if the pointer suppled is not valid,
+         but this will only be reported if the error status is clear on
+         entry.
+      }
+   }
+}
+\sstroutine{
+   astAxAngle
+}{
+   Returns the angle from an axis, to a line through two points
+}{
+   \sstdescription{
+      This function
+      finds the angle, as seen from point A, between the positive
+      direction of a specified axis, and the geodesic curve joining point
+      A to point B.
+   }
+   \sstsynopsis{
+      double astAxAngle( AstFrame $*$this, const double a[], const double b[], int axis )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the \htmlref{Frame}{Frame}.
+      }
+      \sstsubsection{
+         a
+      }{
+         An array of double, with one element for each Frame axis
+         (\htmlref{Naxes}{Naxes} attribute) containing the coordinates of the first point.
+      }
+      \sstsubsection{
+         b
+      }{
+         An array of double, with one element for each Frame axis
+         (Naxes attribute) containing the coordinates of the second point.
+      }
+      \sstsubsection{
+         axis
+      }{
+         The number of the Frame axis from which the angle is to be
+         measured (axis numbering starts at 1 for the first axis).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astAxAngle
+      }{
+         The angle in radians, from the positive direction of the
+         specified axis, to the line AB. If the Frame is 2-dimensional,
+         it will be in the range [-PI/2,$+$PI/2], and positive rotation is in
+         the same sense as rotation from the positive direction of axis 2
+         to the positive direction of axis 1. If the Frame has more than 2
+         axes, a positive value will always be returned in the range zero
+         to PI.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The geodesic curve used by this function is the path of
+         shortest distance between two points, as defined by the
+         \htmlref{astDistance}{astDistance} function.
+
+         \sstitem
+          This function will return \texttt{"} bad\texttt{"}  coordinate values (AST\_\_BAD)
+         if any of the input coordinates has this value, or if the require
+         position angle is undefined.
+      }
+   }
+}
+\sstroutine{
+   astAxDistance
+}{
+   Find the distance between two axis values
+}{
+   \sstdescription{
+      This function returns a signed value representing the axis increment
+      from axis value v1 to axis value v2.
+
+      For a simple \htmlref{Frame}{Frame}, this is a trivial operation returning the
+      difference between the two axis values. But for other derived classes
+      of Frame (such as a \htmlref{SkyFrame}{SkyFrame}) this is not the case.
+   }
+   \sstsynopsis{
+      double astAxDistance( AstFrame $*$this, int axis, double v1, double v2 )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Frame.
+      }
+      \sstsubsection{
+         axis
+      }{
+         The index of the axis to which the supplied values refer. The
+         first axis has index 1.
+      }
+      \sstsubsection{
+         v1
+      }{
+         The first axis value.
+      }
+      \sstsubsection{
+         v2
+      }{
+         The second axis value.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astAxDistance
+      }{
+         The distance from the first to the second axis value.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This function will return a \texttt{"} bad\texttt{"}  result value (AST\_\_BAD) if
+         any of the input values has this value.
+
+         \sstitem
+          A \texttt{"} bad\texttt{"}  value will also be returned if this function is
+         invoked with the AST error status set, or if it should fail for
+         any reason.
+      }
+   }
+}
+\sstroutine{
+   astAxNorm
+}{
+   Normalise an array of axis values
+}{
+   \sstdescription{
+      This function
+      modifies a supplied array of axis values so that they are normalised
+      in the manner indicated by
+      parameter \texttt{"} oper\texttt{"} .
+
+      No normalisation is possible for a simple \htmlref{Frame}{Frame} and so the supplied
+      values are returned unchanged. However, this may not be the case for
+      specialised sub-classes of Frame. For instance, a \htmlref{SkyFrame}{SkyFrame} has a
+      discontinuity at zero longitude and so a longitude value can be
+      expressed in the range [-Pi,$+$PI] or the range [0,2$*$PI]. See the
+      \texttt{"} Applicability:\texttt{"}  section below for details.
+   }
+   \sstsynopsis{
+      void astAxNorm( AstFrame $*$this, int axis, int oper, int nval,
+                      double $*$values, int $*$status )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Frame.
+      }
+      \sstsubsection{
+         axis
+      }{
+         The index of the axis to which the supplied values refer. The
+         first axis has index 1.
+      }
+      \sstsubsection{
+         oper
+      }{
+         Indicates the type of normalisation to be applied. If zero is
+         supplied, the normalisation will be the same as that performed by
+         function \htmlref{astNorm}{astNorm}.
+         If 1 is supplied, the normalisation will be chosen automatically
+         so that the resulting list has the smallest range.
+      }
+      \sstsubsection{
+         nval
+      }{
+         The number of points in the values array.
+      }
+      \sstsubsection{
+         values
+      }{
+         On entry, the axis values to be normalised. Modified on exit to
+         hold the normalised values.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         SkyFrame
+      }{
+         If \texttt{"} oper\texttt{"}
+         is 0, longitude values are returned in the range [0,2$*$PI].
+         If \texttt{"} oper\texttt{"}
+         is 1, longitude values are returned in either the range
+         [0,2$*$PI] or [-PI,PI]. The choice is made so that that the
+         resulting list has the smallest range. Latitude values are
+         always returned in the range [-PI,PI].
+      }
+      \sstsubsection{
+         All other classes of Frame
+      }{
+         The supplied axis values are returned unchanged.
+      }
+   }
+}
+\sstroutine{
+   astAxOffset
+}{
+   Add an increment onto a supplied axis value
+}{
+   \sstdescription{
+      This function returns an axis value formed by adding a signed axis
+      increment onto a supplied axis value.
+
+      For a simple \htmlref{Frame}{Frame}, this is a trivial operation returning the
+      sum of the two supplied values. But for other derived classes
+      of Frame (such as a \htmlref{SkyFrame}{SkyFrame}) this is not the case.
+   }
+   \sstsynopsis{
+      double astAxOffset( AstFrame $*$this, int axis, double v1, double dist )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Frame.
+      }
+      \sstsubsection{
+         axis
+      }{
+         The index of the axis to which the supplied values refer. The
+         first axis has index 1.
+      }
+      \sstsubsection{
+         v1
+      }{
+         The original axis value.
+      }
+      \sstsubsection{
+         dist
+      }{
+         The axis increment to add to the original axis value.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astAxOffset
+      }{
+         The incremented axis value.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This function will return a \texttt{"} bad\texttt{"}  result value (AST\_\_BAD) if
+         any of the input values has this value.
+
+         \sstitem
+          A \texttt{"} bad\texttt{"}  value will also be returned if this function is
+         invoked with the AST error status set, or if it should fail for
+         any reason.
+      }
+   }
+}
+\sstroutine{
+   astBBuf
+}{
+   Begin a new graphical buffering context
+}{
+   \sstdescription{
+      This function
+      starts a new graphics buffering context. A matching call to the
+      function \htmlref{astEBuf}{astEBuf}
+      should be used to end the context.
+   }
+   \sstsynopsis{
+      void astBBuf( AstPlot $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the \htmlref{Plot}{Plot}.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The nature of the buffering is determined by the underlying
+         graphics system (as defined by the current grf module). Each call
+         to this function
+         to this function
+         simply invokes the astGBBuf function in the grf module.
+      }
+   }
+}
+\sstroutine{
+   astBegin
+}{
+   Begin a new AST context
+}{
+   \sstdescription{
+      This macro invokes a function to begin a new AST context.
+      Any \htmlref{Object}{Object} pointers
+      created within this context will be annulled when it is later
+      ended using \htmlref{astEnd}{astEnd} (just as if \htmlref{astAnnul}{astAnnul} had been invoked),
+      unless they have first been exported using \htmlref{astExport}{astExport} or rendered
+      exempt using \htmlref{astExempt}{astExempt}. If
+      annulling a pointer causes an Object\texttt{'} s \htmlref{RefCount}{RefCount} attribute to
+      fall to zero (which happens when the last pointer to it is
+      annulled), then the Object will be deleted.
+   }
+   \sstsynopsis{
+      void astBegin
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         This macro applies to all Objects.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          astBegin attempts to execute even if the AST error status
+         is set on entry.
+
+         \sstitem
+          Contexts delimited by astBegin and astEnd may be nested to any
+         depth.
+      }
+   }
+}
+\sstroutine{
+   astBorder
+}{
+   Draw a border around valid regions of a Plot
+}{
+   \sstdescription{
+      This function draws a (line) border around regions of the
+      plotting area of a \htmlref{Plot}{Plot} which correspond to valid, unclipped
+      physical coordinates. For example, when plotting using an
+      all-sky map projection, this function could be used to draw the
+      boundary of the celestial sphere when it is projected on to the
+      plotting surface.
+
+      If the entire plotting area contains valid, unclipped physical
+      coordinates, then the boundary will just be a rectangular box
+      around the edges of the plotting area.
+
+      If the Plot is a \htmlref{Plot3D}{Plot3D}, this method is applied individually to
+      each of the three 2D Plots encapsulated within the Plot3D (each of
+      these Plots corresponds to a single 2D plane in the 3D graphics
+      system). In addition, if the entire plotting volume has valid
+      coordinates in the 3D current \htmlref{Frame}{Frame} of the Plot3D, then additional
+      lines are drawn along the edges of the 3D plotting volume so that
+      the entire plotting volume is enclosed within a cuboid grid.
+   }
+   \sstsynopsis{
+      int astBorder( AstPlot $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Plot.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astBorder()
+      }{
+         Zero is returned if the plotting space is completely filled by
+         valid, unclipped physical coordinates (so that only a
+         rectangular box was drawn around the edge). Otherwise, one is
+         returned.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A value of zero will be returned if this function is invoked
+         with the AST error status set, or if it should fail for any
+         reason.
+
+         \sstitem
+          An error results if either the current Frame or the base Frame
+         of the Plot is not 2-dimensional or (for a Plot3D) 3-dimensional.
+
+         \sstitem
+          An error also results if the transformation between the base
+         and current Frames of the Plot is not defined (i.e. the Plot\texttt{'} s
+         \htmlref{TranForward}{TranForward} attribute is zero).
+      }
+   }
+}
+\sstroutine{
+   astBoundingBox
+}{
+   Return a bounding box for previously drawn graphics
+}{
+   \sstdescription{
+      This function returns the bounds of a box which just encompasess the
+      graphics produced by the previous call to any of the \htmlref{Plot}{Plot} methods
+      which produce graphical output. If no such previous call has yet
+      been made, or if the call failed for any reason, then the bounding box
+      returned by this function is undefined.
+   }
+   \sstsynopsis{
+      void astBoundingBox( AstPlot $*$this, float lbnd[2], float ubnd[2] )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Plot.
+      }
+      \sstsubsection{
+         lbnd
+      }{
+         A two element array in which is returned the lower limits of the
+         bounding box on each of the two axes of the graphics coordinate
+         system (the base \htmlref{Frame}{Frame} of the Plot).
+      }
+      \sstsubsection{
+         ubnd
+      }{
+         A two element array in which is returned the upper limits of the
+         bounding box on each of the two axes of the graphics coordinate
+         system (the base Frame of the Plot).
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          An error results if the base Frame of the Plot is not
+         2-dimensional.
+      }
+   }
+}
+\sstroutine{
+   astBox
+}{
+   Create a Box
+}{
+   \sstdescription{
+      This function creates a new \htmlref{Box}{Box} and optionally initialises its
+      attributes.
+
+      The Box class implements a \htmlref{Region}{Region} which represents a box with sides
+      parallel to the axes of a \htmlref{Frame}{Frame} (i.e. an area which encloses a given
+      range of values on each axis). A Box is similar to an \htmlref{Interval}{Interval}, the
+      only real difference being that the Interval class allows some axis
+      limits to be unspecified. Note, a Box will only look like a box if
+      the Frame geometry is approximately flat. For instance, a Box centred
+      close to a pole in a \htmlref{SkyFrame}{SkyFrame} will look more like a fan than a box
+      (the \htmlref{Polygon}{Polygon} class can be used to create a box-like region close to a
+      pole).
+   }
+   \sstsynopsis{
+      AstBox $*$astBox( AstFrame $*$frame, int form, const double point1[],
+                      const double point2[], AstRegion $*$unc,
+                      const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         frame
+      }{
+         A pointer to the Frame in which the region is defined. A deep
+         copy is taken of the supplied Frame. This means that any
+         subsequent changes made to the Frame using the supplied pointer
+         will have no effect the Region.
+      }
+      \sstsubsection{
+         form
+      }{
+         Indicates how the box is described by the remaining parameters.
+         A value of zero indicates that the box is specified by a centre
+         position and a corner position. A value of one indicates that the
+         box is specified by a two opposite corner positions.
+      }
+      \sstsubsection{
+         point1
+      }{
+         An array of double, with one element for each Frame axis
+         (\htmlref{Naxes}{Naxes} attribute). If
+         \texttt{"} form\texttt{"}
+         is zero, this array should contain the coordinates at the centre of
+         the box.
+         If \texttt{"} form\texttt{"}
+         is one, it should contain the coordinates at the corner of the box
+         which is diagonally opposite the corner specified by
+         \texttt{"} point2\texttt{"} .
+      }
+      \sstsubsection{
+         point2
+      }{
+         An array of double, with one element for each Frame axis
+         (Naxes attribute) containing the coordinates at any corner of the
+         box.
+      }
+      \sstsubsection{
+         unc
+      }{
+         An optional pointer to an existing Region which specifies the
+         uncertainties associated with the boundary of the Box being created.
+         The uncertainty in any point on the boundary of the Box is found by
+         shifting the supplied \texttt{"} uncertainty\texttt{"}  Region so that it is centred at
+         the boundary point being considered. The area covered by the
+         shifted uncertainty Region then represents the uncertainty in the
+         boundary position. The uncertainty is assumed to be the same for
+         all points.
+
+         If supplied, the uncertainty Region must be of a class for which
+         all instances are centro-symetric (e.g. Box, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.)
+         or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep
+         copy of the supplied Region will be taken, so subsequent changes to
+         the uncertainty Region using the supplied pointer will have no
+         effect on the created Box. Alternatively,
+         a NULL \htmlref{Object}{Object} pointer
+         may be supplied, in which case a default uncertainty is used
+         equivalent to a box 1.0E-6 of the size of the Box being created.
+
+         The uncertainty Region has two uses: 1) when the
+         \htmlref{astOverlap}{astOverlap}
+         function compares two Regions for equality the uncertainty
+         Region is used to determine the tolerance on the comparison, and 2)
+         when a Region is mapped into a different coordinate system and
+         subsequently simplified (using
+         \htmlref{astSimplify}{astSimplify}),
+         the uncertainties are used to determine if the transformed boundary
+         can be accurately represented by a specific shape of Region.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new Box. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astBox()
+      }{
+         A pointer to the new Box.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null Object pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      Status Handling
+   }{
+      The protected interface to this function includes an extra
+      parameter at the end of the parameter list descirbed above. This
+      parameter is a pointer to the integer inherited status
+      variable: \texttt{"} int $*$status\texttt{"} .
+   }
+}
+\sstroutine{
+   astChannel
+}{
+   Create a Channel
+}{
+   \sstdescription{
+      This function creates a new \htmlref{Channel}{Channel} and optionally initialises
+      its attributes.
+
+      A Channel implements low-level input/output for the AST library.
+      Writing an \htmlref{Object}{Object} to a Channel (using \htmlref{astWrite}{astWrite}) will generate a
+      textual representation of that Object, and reading from a
+      Channel (using \htmlref{astRead}{astRead}) will create a new Object from its
+      textual representation.
+
+      Normally, when you use a Channel, you should provide \texttt{"} source\texttt{"}
+      and \texttt{"} sink\texttt{"}  functions which connect it to an external data store
+      by reading and writing the resulting text. By default, however,
+      a Channel will read from standard input and write to standard
+      output. Alternatively, a Channel can be told to read or write from
+      specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes,
+      in which case no sink or source function need be supplied.
+   }
+   \sstsynopsis{
+      AstChannel $*$astChannel( const char $*$($*$ source)( void ),
+                              void ($*$ sink)( const char $*$ ),
+                              const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         source
+      }{
+         Pointer to a source function that takes no arguments and
+         returns a pointer to a null-terminated string.  If no value
+         has been set for the SourceFile attribute, this function
+         will be used by the Channel to obtain lines of input text. On
+         each invocation, it should return a pointer to the next input
+         line read from some external data store, and a NULL pointer
+         when there are no more lines to read.
+
+         If \texttt{"} source\texttt{"}  is NULL and no value has been set for the SourceFile
+         attribute, the Channel will read from standard input instead.
+      }
+      \sstsubsection{
+         sink
+      }{
+         Pointer to a sink function that takes a pointer to a
+         null-terminated string as an argument and returns void.
+         If no value has been set for the SinkFile attribute, this
+         function will be used by the Channel to deliver lines of
+         output text. On each invocation, it should deliver the
+         contents of the string supplied to some external data store.
+
+         If \texttt{"} sink\texttt{"}  is NULL, and no value has been set for the SinkFile
+         attribute, the Channel will write to standard output instead.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new Channel. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astChannel()
+      }{
+         A pointer to the new Channel.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Application code can pass arbitrary data (such as file
+         descriptors, etc) to source and sink functions using the
+         \htmlref{astPutChannelData}{astPutChannelData} function. The source or sink function should use
+         the \htmlref{astChannelData}{astChannelData} macro to retrieve this data.
+
+         \sstitem
+          A null Object pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astChannelData
+}{
+   Return a pointer to user-supplied data stored with a Channel
+}{
+   \sstdescription{
+      This macro is intended to be used within the source or sink
+      functions associated with a \htmlref{Channel}{Channel}. It returns any pointer
+      previously stored in the Channel (that is, the Channel that has
+      invoked the source or sink function) using \htmlref{astPutChannelData}{astPutChannelData}.
+
+      This mechanism is a thread-safe alternative to passing file
+      descriptors, etc, via static global variables.
+   }
+   \sstsynopsis{
+      void $*$astChannelData
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Channel
+      }{
+         This macro applies to all Channels.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astChannelData
+      }{
+         The pointer previously stored with the Channel using
+         astPutChannelData. A NULL pointer will be returned if no such
+         pointer has been stored with the Channel.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This routine is not available in the Fortran 77 interface to
+         the AST library.
+      }
+   }
+}
+\sstroutine{
+   astChebyDomain
+}{
+   Returns the bounding box of the domain of a ChebyMap
+}{
+   \sstdescription{
+      This function
+      returns the upper and lower limits of the box defining the domain
+      of either the forward or inverse transformation of a \htmlref{ChebyMap}{ChebyMap}. These
+      are the values that were supplied when the ChebyMap was created.
+   }
+   \sstsynopsis{
+      void astChebyDomain( AstChebyMap $*$this, int forward, double $*$lbnd,
+                           double $*$ubnd )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the ChebyMap.
+      }
+      \sstsubsection{
+         forward
+      }{
+         A non-zero
+         value indicates that the domain of the ChebyMap\texttt{'} s
+         forward transformation is to be returned, while a zero
+         value indicates that the domain of the inverse transformation
+         should be returned.
+      }
+      \sstsubsection{
+         lbnd
+      }{
+         Pointer to an
+         array in which to return the lower axis bounds of the ChebyMap
+         domain. The number of elements should be at least equal to the
+         number of ChebyMap inputs (if
+         \texttt{"} forward\texttt{"}  is non-zero), or outputs (if \texttt{"} forward\texttt{"}  is zero).
+      }
+      \sstsubsection{
+         ubnd
+      }{
+         Pointer to an
+         array in which to return the upper axis bounds of the ChebyMap
+         domain. The number of elements should be at least equal to the
+         number of ChebyMap inputs (if
+         \texttt{"} forward\texttt{"}  is non-zero), or outputs (if \texttt{"} forward\texttt{"}  is zero).
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If the requested transformation is undefined (i.e. no
+         transformation coefficients were specified when the ChebyMap was
+         created), this method returns a box determined using the
+         \htmlref{astMapBox}{astMapBox}
+         method on the opposite transformation, if the opposite
+         transformation is defined.
+
+         \sstitem
+          If the above procedure fails to determine a bounding box, the supplied
+         arrays are filled with AST\_\_BAD values but no error is reported.
+      }
+   }
+}
+\sstroutine{
+   astChebyMap
+}{
+   Create a ChebyMap
+}{
+   \sstdescription{
+      This function creates a new \htmlref{ChebyMap}{ChebyMap} and optionally initialises
+      its attributes.
+
+      A ChebyMap is a form of \htmlref{Mapping}{Mapping} which performs a Chebyshev polynomial
+      transformation.  Each output coordinate is a linear combination of
+      Chebyshev polynomials of the first kind, of order zero up to a
+      specified maximum order, evaluated at the input coordinates. The
+      coefficients to be used in the linear combination are specified
+      separately for each output coordinate.
+
+      For a 1-dimensional ChebyMap, the forward transformation is defined
+      as follows:
+
+         f(x) = c0.T0(x\texttt{'} ) $+$ c1.T1(x\texttt{'} ) $+$ c2.T2(x\texttt{'} ) $+$ ...
+
+      where:
+      \sstitemlist{
+
+         \sstitem
+             Tn(x\texttt{'} ) is the nth Chebyshev polynomial of the first kind:
+
+         \sstitem
+                  T0(x\texttt{'} ) = 1
+
+         \sstitem
+                  T1(x\texttt{'} ) = x\texttt{'}
+
+         \sstitem
+                  Tn$+$1(x\texttt{'} ) = 2.x\texttt{'} .Tn(x\texttt{'} ) $+$ Tn-1(x\texttt{'} )
+
+         \sstitem
+             x\texttt{'}  is the inpux axis value, x, offset and scaled to the range
+              [-1, 1] as x ranges over a specified bounding box, given when the
+              ChebyMap is created. The input positions, x,  supplied to the
+              forward transformation must fall within the bounding box - bad
+              axis values (AST\_\_BAD) are generated for points outside the
+              bounding box.
+
+      }
+      For an N-dimensional ChebyMap, the forward transformation is a
+      generalisation of the above form. Each output axis value is the sum
+      of \texttt{"} ncoeff\texttt{"}
+      terms, where each term is the product of a single coefficient
+      value and N factors of the form Tn(x\texttt{'} \_i), where \texttt{"} x\texttt{'} \_i\texttt{"}  is the
+      normalised value of the i\texttt{'} th input axis value.
+
+      The forward and inverse transformations are defined independantly
+      by separate sets of coefficients, supplied when the ChebyMap is
+      created. If no coefficients are supplied to define the inverse
+      transformation, the
+      \htmlref{astPolyTran}{astPolyTran}
+      method of the parent \htmlref{PolyMap}{PolyMap} class can instead be used to create an
+      inverse transformation. The inverse transformation so generated
+      will be a Chebyshev polynomial with coefficients chosen to minimise
+      the residuals left by a round trip (forward transformation followed
+      by inverse transformation).
+   }
+   \sstsynopsis{
+      AstChebyMap $*$astChebyMap( int nin, int nout, int ncoeff\_f, const double coeff\_f[],
+                                int ncoeff\_i, const double coeff\_i[],
+                                const double lbnd\_f[], const double ubnd\_f[],
+                                const double lbnd\_i[], const double ubnd\_i[],
+                                const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         nin
+      }{
+         The number of input coordinates.
+      }
+      \sstsubsection{
+         nout
+      }{
+         The number of output coordinates.
+      }
+      \sstsubsection{
+         ncoeff\_f
+      }{
+         The number of non-zero coefficients necessary to define the
+         forward transformation of the ChebyMap. If zero is supplied, the
+         forward transformation will be undefined.
+      }
+      \sstsubsection{
+         coeff\_f
+      }{
+         An array containing
+         \texttt{"} ncoeff\_f$*$( 2 $+$ nin )\texttt{"}  elements. Each group of \texttt{"} 2 $+$ nin\texttt{"}
+         adjacent elements describe a single coefficient of the forward
+         transformation. Within each such group, the first element is the
+         coefficient value; the next element is the integer index of the
+         ChebyMap output which uses the coefficient within its defining
+         expression (the first output has index 1); the remaining elements
+         of the group give the integer powers to use with each input
+         coordinate value (powers must not be negative, and floating
+         point values are rounded to the nearest integer).
+         If \texttt{"} ncoeff\_f\texttt{"}  is zero, a NULL pointer may be supplied for \texttt{"} coeff\_f\texttt{"} .
+
+         For instance, if the ChebyMap has 3 inputs and 2 outputs, each group
+         consisting of 5 elements, A groups such as \texttt{"} (1.2, 2.0, 1.0, 3.0, 0.0)\texttt{"}
+         describes a coefficient with value 1.2 which is used within the
+         definition of output 2. The output value is incremented by the
+         product of the coefficient value, the value of the Chebyshev
+         polynomial of power 1 evaluated at input coordinate 1, and the
+         value of the Chebyshev polynomial of power 3 evaluated at input
+         coordinate 2. Input coordinate 3 is not used since its power is
+         specified as zero. As another example, the group \texttt{"} (-1.0, 1.0,
+         0.0, 0.0, 0.0 )\texttt{"}  adds a constant value -1.0 onto output 1 (it is
+         a constant value since the power for every input axis is given as
+         zero).
+
+         Each final output coordinate value is the sum of the \texttt{"} ncoeff\_f\texttt{"}  terms
+         described by the \texttt{"} ncoeff\_f\texttt{"}  groups within the supplied array.
+      }
+      \sstsubsection{
+         ncoeff\_i
+      }{
+         The number of non-zero coefficients necessary to define the
+         inverse transformation of the ChebyMap. If zero is supplied, the
+         inverse transformation will be undefined.
+      }
+      \sstsubsection{
+         coeff\_i
+      }{
+         An array containing
+         \texttt{"} ncoeff\_i$*$( 2 $+$ nout )\texttt{"}  elements. Each group of \texttt{"} 2 $+$ nout\texttt{"}
+         adjacent elements describe a single coefficient of the inverse
+         transformation, using the same schame as \texttt{"} coeff\_f\texttt{"} ,
+         except that \texttt{"} inputs\texttt{"}  and \texttt{"} outputs\texttt{"}  are transposed.
+         If \texttt{"} ncoeff\_i\texttt{"}  is zero, a NULL pointer may be supplied for \texttt{"} coeff\_i\texttt{"} .
+      }
+      \sstsubsection{
+         lbnd\_f
+      }{
+         An array containing the lower bounds of the input bounding box within
+         which the ChebyMap is defined. This argument is not used or
+         accessed if
+         ncoeff\_f is zero, and so a NULL pointer may be supplied.
+         If supplied, the array should contain
+         \texttt{"} nin\texttt{"}  elements.
+      }
+      \sstsubsection{
+         ubnd\_f
+      }{
+         An array containing the upper bounds of the input bounding box within
+         which the ChebyMap is defined. This argument is not used or
+         accessed if
+         ncoeff\_f is zero, and so a NULL pointer may be supplied.
+         If supplied, the array should contain
+         \texttt{"} nin\texttt{"}  elements.
+      }
+      \sstsubsection{
+         lbnd\_i
+      }{
+         An array containing the lower bounds of the output bounding box within
+         which the ChebyMap is defined. This argument is not used or
+         accessed if
+         ncoeff\_i is zero, and so a NULL pointer may be supplied.
+         If supplied, the array should contain
+         \texttt{"} nout\texttt{"}  elements.
+      }
+      \sstsubsection{
+         ubnd\_i
+      }{
+         An array containing the upper bounds of the output bounding box within
+         which the ChebyMap is defined. This argument is not used or
+         accessed if
+         ncoeff\_i is zero, and so a NULL pointer may be supplied.
+         If supplied, the array should contain
+         \texttt{"} nout\texttt{"}  elements.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new ChebyMap. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astChebyMap()
+      }{
+         A pointer to the new ChebyMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astCircle
+}{
+   Create a Circle
+}{
+   \sstdescription{
+      This function creates a new \htmlref{Circle}{Circle} and optionally initialises its
+      attributes.
+
+      A Circle is a \htmlref{Region}{Region} which represents a circle or sphere within the
+      supplied \htmlref{Frame}{Frame}.
+   }
+   \sstsynopsis{
+      AstCircle $*$astCircle( AstFrame $*$frame, int form, const double centre[],
+                            const double point[], AstRegion $*$unc,
+                            const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         frame
+      }{
+         A pointer to the Frame in which the region is defined. A deep
+         copy is taken of the supplied Frame. This means that any
+         subsequent changes made to the Frame using the supplied pointer
+         will have no effect the Region.
+      }
+      \sstsubsection{
+         form
+      }{
+         Indicates how the circle is described by the remaining parameters.
+         A value of zero indicates that the circle is specified by a
+         centre position and a position on the circumference. A value of one
+         indicates that the circle is specified by a centre position and a
+         scalar radius.
+      }
+      \sstsubsection{
+         centre
+      }{
+         An array of double, with one element for each Frame axis
+         (\htmlref{Naxes}{Naxes} attribute) containing the coordinates at the centre of
+         the circle or sphere.
+      }
+      \sstsubsection{
+         point
+      }{
+         If \texttt{"} form\texttt{"}
+         is zero, then this array should have one element for each Frame
+         axis (Naxes attribute), and should be supplied holding the
+         coordinates at a point on the circumference of the circle or sphere.
+         If \texttt{"} form\texttt{"}
+         is one, then this array should have one element only which should
+         be supplied holding the scalar radius of the circle or sphere,
+         as a geodesic distance within the Frame.
+      }
+      \sstsubsection{
+         unc
+      }{
+         An optional pointer to an existing Region which specifies the
+         uncertainties associated with the boundary of the Circle being created.
+         The uncertainty in any point on the boundary of the Circle is found by
+         shifting the supplied \texttt{"} uncertainty\texttt{"}  Region so that it is centred at
+         the boundary point being considered. The area covered by the
+         shifted uncertainty Region then represents the uncertainty in the
+         boundary position. The uncertainty is assumed to be the same for
+         all points.
+
+         If supplied, the uncertainty Region must be of a class for which
+         all instances are centro-symetric (e.g. \htmlref{Box}{Box}, Circle, \htmlref{Ellipse}{Ellipse}, etc.)
+         or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep
+         copy of the supplied Region will be taken, so subsequent changes to
+         the uncertainty Region using the supplied pointer will have no
+         effect on the created Circle. Alternatively,
+         a NULL \htmlref{Object}{Object} pointer
+         may be supplied, in which case a default uncertainty is used
+         equivalent to a box 1.0E-6 of the size of the Circle being created.
+
+         The uncertainty Region has two uses: 1) when the
+         \htmlref{astOverlap}{astOverlap}
+         function compares two Regions for equality the uncertainty
+         Region is used to determine the tolerance on the comparison, and 2)
+         when a Region is mapped into a different coordinate system and
+         subsequently simplified (using
+         \htmlref{astSimplify}{astSimplify}),
+         the uncertainties are used to determine if the transformed boundary
+         can be accurately represented by a specific shape of Region.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new Circle. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astCircle()
+      }{
+         A pointer to the new Circle.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null Object pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astCirclePars
+}{
+   Returns the geometric parameters of an Circle
+}{
+   \sstdescription{
+      This function
+      returns the geometric parameters describing the supplied \htmlref{Circle}{Circle}.
+   }
+   \sstsynopsis{
+      void astCirclePars( AstCircle $*$this, double $*$centre, double $*$radius,
+                          double $*$p1 )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the \htmlref{Region}{Region}.
+      }
+      \sstsubsection{
+         centre
+      }{
+         Pointer to an array
+         in which to return the coordinates of the Circle centre.
+         The length of this array should be no less than the number of
+         axes in the associated coordinate system.
+      }
+      \sstsubsection{
+         radius
+      }{
+         Returned holding the radius of the Circle, as an geodesic
+         distance in the associated coordinate system.
+      }
+      \sstsubsection{
+         p1
+      }{
+         Pointer to an array
+         in which to return the coordinates of a point on the
+         circumference of the Circle. The length of this array should be
+         no less than the number of axes in the associated coordinate system.
+         A NULL pointer can be supplied if the circumference position is
+         not needed.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If the coordinate system represented by the Circle has been
+         changed since it was first created, the returned parameters refer
+         to the new (changed) coordinate system, rather than the original
+         coordinate system. Note however that if the transformation from
+         original to new coordinate system is non-linear, the shape
+         represented by the supplied Circle object may not be an accurate
+         circle.
+      }
+   }
+}
+\sstroutine{
+   astClear
+}{
+   Clear attribute values for an Object
+}{
+   \sstdescription{
+      This function clears the values of a specified set of attributes
+      for an \htmlref{Object}{Object}. Clearing an attribute cancels any value that has
+      previously been explicitly set for it, so that the standard
+      default attribute value will subsequently be used instead. This
+      also causes the \htmlref{astTest}{astTest} function to return the value zero for
+      the attribute, indicating that no value has been set.
+   }
+   \sstsynopsis{
+      void astClear( AstObject $*$this, const char $*$attrib )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Object.
+      }
+      \sstsubsection{
+         attrib
+      }{
+         Pointer to a null-terminated character string containing a
+         comma-separated list of the names of the attributes to be cleared.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         This function applies to all Objects.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Attribute names are not case sensitive and may be surrounded
+         by white space.
+
+         \sstitem
+          It does no harm to clear an attribute whose value has not been
+         set.
+
+         \sstitem
+          An error will result if an attempt is made to clear the value
+         of a read-only attribute.
+      }
+   }
+}
+\sstroutine{
+   astClearStatus
+}{
+   Clear the AST error status
+}{
+   \sstdescription{
+      This macro resets the AST error status to an OK value,
+      indicating that an error condition (if any) has been cleared.
+   }
+   \sstsynopsis{
+      void astClearStatus
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If the AST error status is set to an error value (after an
+         error), most AST functions will not execute and will simply
+         return without action. Using astClearStatus will restore normal
+         behaviour.
+      }
+   }
+}
+\sstroutine{
+   astClip
+}{
+   Set up or remove clipping for a Plot
+}{
+   \sstdescription{
+      This function defines regions of a \htmlref{Plot}{Plot} which are to be clipped.
+      Any subsequent graphical output created using the Plot will then
+      be visible only within the unclipped regions of the plotting
+      area. See also the \htmlref{Clip}{Clip} attribute.
+   }
+   \sstsynopsis{
+      void astClip( AstPlot $*$this, int iframe, const double lbnd[],
+                    const double ubnd[] )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Plot.
+      }
+      \sstsubsection{
+         iframe
+      }{
+         The index of the \htmlref{Frame}{Frame} within the Plot to which the clipping
+         limits supplied in \texttt{"} lbnd\texttt{"}  and \texttt{"} ubnd\texttt{"}  (below) refer. Clipping
+         may be applied to any of the coordinate systems associated
+         with a Plot (as defined by the Frames it contains), so this
+         index may take any value from 1 to the number of Frames in
+         the Plot (\htmlref{Nframe}{Nframe} attribute). In addition, the values
+         AST\_\_BASE and AST\_\_CURRENT may be used to specify the base
+         and current Frames respectively.
+
+         For example, a value of AST\_\_CURRENT causes clipping to be
+         performed in physical coordinates, while a value of AST\_\_BASE
+         would clip in graphical coordinates. Clipping may also be
+         removed completely by giving a value of AST\_\_NOFRAME. In this
+         case any clipping bounds supplied (below) are ignored.
+      }
+      \sstsubsection{
+         lbnd
+      }{
+         An array with one element for each axis of the clipping Frame
+         (identified by the index \texttt{"} iframe\texttt{"} ). This should contain the
+         lower bound, on each axis, of the region which is to remain
+         visible (unclipped).
+      }
+      \sstsubsection{
+         ubnd
+      }{
+         An array with one element for each axis of the clipping Frame
+         (identified by the index \texttt{"} iframe\texttt{"} ). This should contain the
+         upper bound, on each axis, of the region which is to remain
+         visible (unclipped).
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Only one clipping Frame may be active at a time. This function
+         will deactivate any previously-established clipping Frame before
+         setting up new clipping limits.
+
+         \sstitem
+          The clipping produced by this function is in addition to that
+         specified by the Clip attribute which occurs at the edges of the
+         plotting area
+         established when the Plot is created (see \htmlref{astPlot}{astPlot}). The
+         underlying graphics system may also impose further clipping.
+
+         \sstitem
+          When testing a graphical position for clipping, it is first
+         transformed into the clipping Frame. The resulting coordinate on
+         each axis is then checked against the clipping limits (given by
+         \texttt{"} lbnd\texttt{"}  and \texttt{"} ubnd\texttt{"} ). By default, a position is clipped if any
+         coordinate lies outside these limits. However, if a non-zero
+         value is assigned to the Plot\texttt{'} s \htmlref{ClipOp}{ClipOp} attribute, then a
+         position is only clipped if the coordinates on all axes lie
+         outside their clipping limits.
+
+         \sstitem
+          If the lower clipping limit exceeds the upper limit for any
+         axis, then the sense of clipping for that axis is reversed (so
+         that coordinate values lying between the limits are clipped
+         instead of those lying outside the limits). To produce a \texttt{"} hole\texttt{"}
+         in a coordinate space (that is, an internal region where nothing
+         is plotted), you should supply all the bounds in reversed order,
+         and set the ClipOp attribute for the Plot to a non-zero value.
+
+         \sstitem
+          Either clipping limit may be set to the value AST\_\_BAD, which
+         is equivalent to setting it to infinity (or minus infinity for a
+         lower bound) so that it is not used.
+
+         \sstitem
+          If a graphical position results in any bad coordinate values
+         (AST\_\_BAD) when transformed into the clipping Frame, then it is
+         treated (for the purposes of producing graphical output) as if
+         it were clipped.
+
+         \sstitem
+          When a Plot is used as a \htmlref{Mapping}{Mapping} to transform points
+         (e.g. using \htmlref{astTran2}{astTran2}), any clipped output points are assigned
+         coordinate values of AST\_\_BAD.
+
+         \sstitem
+          An error results if the base Frame of the Plot is not
+         2-dimensional.
+      }
+   }
+}
+\sstroutine{
+   astClone
+}{
+   Clone (duplicate) an Object pointer
+}{
+   \sstdescription{
+      This function returns a duplicate pointer to an existing
+      \htmlref{Object}{Object}. It also increments the Object\texttt{'} s \htmlref{RefCount}{RefCount} attribute to
+      keep track of how many pointers have been issued.
+
+      Note that this function is NOT equivalent to an assignment
+      statement, as in general the two pointers will not have the same
+      value.
+   }
+   \sstsynopsis{
+      AstObject $*$astClone( AstObject $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Original pointer to the Object.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         This function applies to all Objects.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astClone()
+      }{
+         A duplicate pointer to the same Object.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null Object pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astCmpFrame
+}{
+   Create a CmpFrame
+}{
+   \sstdescription{
+      This function creates a new \htmlref{CmpFrame}{CmpFrame} and optionally initialises
+      its attributes.
+
+      A CmpFrame is a compound \htmlref{Frame}{Frame} which allows two component Frames
+      (of any class) to be merged together to form a more complex
+      Frame. The axes of the two component Frames then appear together
+      in the resulting CmpFrame (those of the first Frame, followed by
+      those of the second Frame).
+
+      Since a CmpFrame is itself a Frame, it can be used as a
+      component in forming further CmpFrames. Frames of arbitrary
+      complexity may be built from simple individual Frames in this
+      way.
+
+      Also since a Frame is a \htmlref{Mapping}{Mapping}, a CmpFrame can also be used as a
+      Mapping. Normally, a CmpFrame is simply equivalent to a \htmlref{UnitMap}{UnitMap},
+      but if either of the component Frames within a CmpFrame is a \htmlref{Region}{Region}
+      (a sub-class of Frame), then the CmpFrame will use the Region as a
+      Mapping when transforming values for axes described by the Region.
+      Thus input axis values corresponding to positions which are outside the
+      Region will result in bad output axis values.
+   }
+   \sstsynopsis{
+      AstCmpFrame $*$astCmpFrame( AstFrame $*$frame1, AstFrame $*$frame2,
+                                const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         frame1
+      }{
+         Pointer to the first component Frame.
+      }
+      \sstsubsection{
+         frame2
+      }{
+         Pointer to the second component Frame.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new CmpFrame. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astCmpFrame()
+      }{
+         A pointer to the new CmpFrame.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      Status Handling
+   }{
+      The protected interface to this function includes an extra
+      parameter at the end of the parameter list descirbed above. This
+      parameter is a pointer to the integer inherited status
+      variable: \texttt{"} int $*$status\texttt{"} .
+   }
+}
+\sstroutine{
+   astCmpMap
+}{
+   Create a CmpMap
+}{
+   \sstdescription{
+      This function creates a new \htmlref{CmpMap}{CmpMap} and optionally initialises
+      its attributes.
+
+      A CmpMap is a compound \htmlref{Mapping}{Mapping} which allows two component
+      Mappings (of any class) to be connected together to form a more
+      complex Mapping. This connection may either be \texttt{"} in series\texttt{"}
+      (where the first Mapping is used to transform the coordinates of
+      each point and the second mapping is then applied to the
+      result), or \texttt{"} in parallel\texttt{"}  (where one Mapping transforms the
+      earlier coordinates for each point and the second Mapping
+      simultaneously transforms the later coordinates).
+
+      Since a CmpMap is itself a Mapping, it can be used as a
+      component in forming further CmpMaps. Mappings of arbitrary
+      complexity may be built from simple individual Mappings in this
+      way.
+   }
+   \sstsynopsis{
+      AstCmpMap $*$astCmpMap( AstMapping $*$map1, AstMapping $*$map2, int series,
+                            const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         map1
+      }{
+         Pointer to the first component Mapping.
+      }
+      \sstsubsection{
+         map2
+      }{
+         Pointer to the second component Mapping.
+      }
+      \sstsubsection{
+         series
+      }{
+         If a non-zero value is given for this parameter, the two
+         component Mappings will be connected in series. A zero
+         value requests that they are connected in parallel.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new CmpMap. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astCmpMap()
+      }{
+         A pointer to the new CmpMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If the component Mappings are connected in series, then using
+         the resulting CmpMap to transform coordinates will cause the
+         first Mapping to be applied, followed by the second Mapping. If
+         the inverse CmpMap transformation is requested, the two
+         component Mappings will be applied in both the reverse order and
+         the reverse direction.
+
+         \sstitem
+          When connecting two component Mappings in series, the number
+         of output coordinates generated by the first Mapping (its \htmlref{Nout}{Nout}
+         attribute) must equal the number of input coordinates accepted
+         by the second Mapping (its \htmlref{Nin}{Nin} attribute).
+
+         \sstitem
+          If the component Mappings of a CmpMap are connected in
+         parallel, then the first Mapping will be used to transform the
+         earlier input coordinates for each point (and to produce the
+         earlier output coordinates) and the second Mapping will be used
+         simultaneously to transform the remaining input coordinates (to
+         produce the remaining output coordinates for each point). If the
+         inverse transformation is requested, each Mapping will still be
+         applied to the same coordinates, but in the reverse direction.
+
+         \sstitem
+          When connecting two component Mappings in parallel, there is
+         no restriction on the number of input and output coordinates for
+         each Mapping.
+
+         \sstitem
+          Note that the component Mappings supplied are not copied by
+         astCmpMap (the new CmpMap simply retains a reference to
+         them). They may continue to be used for other purposes, but
+         should not be deleted. If a CmpMap containing a copy of its
+         component Mappings is required, then a copy of the CmpMap should
+         be made using \htmlref{astCopy}{astCopy}.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astCmpRegion
+}{
+   Create a CmpRegion
+}{
+   \sstdescription{
+      This function creates a new \htmlref{CmpRegion}{CmpRegion} and optionally initialises
+      its attributes.
+
+      A CmpRegion is a \htmlref{Region}{Region} which allows two component
+      Regions (of any class) to be combined to form a more complex
+      Region. This combination may be performed a boolean AND, OR
+      or XOR (exclusive OR) operator. If the AND operator is
+      used, then a position is inside the CmpRegion only if it is
+      inside both of its two component Regions. If the OR operator is
+      used, then a position is inside the CmpRegion if it is inside
+      either (or both) of its two component Regions. If the XOR operator
+      is used, then a position is inside the CmpRegion if it is inside
+      one but not both of its two component Regions. Other operators can
+      be formed by negating one or both component Regions before using
+      them to construct a new CmpRegion.
+
+      The two component Region need not refer to the same coordinate
+      \htmlref{Frame}{Frame}, but it must be possible for the
+      \htmlref{astConvert}{astConvert}
+      function to determine a \htmlref{Mapping}{Mapping} between them (an error will be
+      reported otherwise when the CmpRegion is created). For instance,
+      a CmpRegion may combine a Region defined within an ICRS \htmlref{SkyFrame}{SkyFrame}
+      with a Region defined within a Galactic SkyFrame. This is
+      acceptable because the SkyFrame class knows how to convert between
+      these two systems, and consequently the
+      astConvert
+      function will also be able to convert between them. In such cases,
+      the second component Region will be mapped into the coordinate Frame
+      of the first component Region, and the Frame represented by the
+      CmpRegion as a whole will be the Frame of the first component Region.
+
+      Since a CmpRegion is itself a Region, it can be used as a
+      component in forming further CmpRegions. Regions of arbitrary
+      complexity may be built from simple individual Regions in this
+      way.
+   }
+   \sstsynopsis{
+      AstCmpRegion $*$astCmpRegion( AstRegion $*$region1, AstRegion $*$region2,
+                                  int oper, const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         region1
+      }{
+         Pointer to the first component Region.
+      }
+      \sstsubsection{
+         region2
+      }{
+         Pointer to the second component Region. This Region will be
+         transformed into the coordinate Frame of the first region before
+         use. An error will be reported if this is not possible.
+      }
+      \sstsubsection{
+         oper
+      }{
+         The boolean operator with which to combine the two Regions. This
+         must be one of the symbolic constants AST\_\_AND, AST\_\_OR or AST\_\_XOR.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new CmpRegion. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astCmpRegion()
+      }{
+         A pointer to the new CmpRegion.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If one of the supplied Regions has an associated uncertainty,
+         that uncertainty will also be used for the returned CmpRegion.
+         If both supplied Regions have associated uncertainties, the
+         uncertainty associated with the first Region will be used for the
+         returned CmpRegion.
+
+         \sstitem
+          Deep copies are taken of the supplied Regions. This means that
+         any subsequent changes made to the component Regions using the
+         supplied pointers will have no effect on the CmpRegion.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astColumnName
+}{
+   Get the name of the column at a given index within the Table
+}{
+   \sstdescription{
+      This function returns a string holding the name of the column with
+      the given index within the \htmlref{Table}{Table}.
+
+      This function is intended primarily as a means of iterating round all
+      the columns in a Table. For this purpose, the number of columns in
+      the Table is given by the \htmlref{Ncolumn}{Ncolumn} attribute of the Table. This function
+      could then be called in a loop, with the index value going from
+      zero to one less than Ncolumn.
+
+      Note, the index associated with a column decreases monotonically with
+      the age of the column: the oldest Column in the Table will have index
+      one, and the Column added most recently to the Table will have the
+      largest index.
+   }
+   \sstsynopsis{
+      const char $*$astColumnName( AstTable $*$this, int index )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Table.
+      }
+      \sstsubsection{
+         index
+      }{
+         The index into the list of columns. The first column has index
+         one, and the last has index \texttt{"} Ncolumn\texttt{"} .
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astColumnName()
+      }{
+         A pointer to a null-terminated string containing the
+         upper case column name.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The returned pointer is guaranteed to remain valid and the
+         string to which it points will not be over-written for a total
+         of 50 successive invocations of this function. After this, the
+         memory containing the string may be re-used, so a copy of the
+         string should be made if it is needed for longer than this.
+
+         \sstitem
+          A NULL pointer will be returned if this function is invoked
+         with the AST error status set, or if it should fail for any
+         reason.
+      }
+   }
+}
+\sstroutine{
+   astColumnNull
+}{
+   Get or set the null value for an integer column of a FITS table
+}{
+   \sstdescription{
+      This function allows a null value to be stored with a named
+      integer-valued column in a \htmlref{FitsTable}{FitsTable}. The supplied null value is
+      assigned to the TNULLn keyword in the FITS header associated with
+      the FitsTable. A value in the named column is then considered to be
+      null if 1) it equals the null value supplied to this function, or
+      2) no value has yet been stored in the cell.
+
+      As well as setting a new null value, this function also returns the
+      previous null value. If no null value has been set previously, a
+      default value will be returned. This default will be an integer
+      value that does not currently occur anywhere within the named column.
+      If no such value can be found, what happens depends on whether the
+      column contains any cells in which no values have yet been stored.
+      If so, an error will be reported. Otherwise (i.e. if there are no
+      null values in the column), an arbitrary value of zero will be
+      returned as the function value, and no TNULLn keyword will be
+      stored in the FITS header.
+
+      A flag is returned indicating if the returned null value was set
+      explicitly by a previous call to this function, or is a default
+      value.
+
+      A second flag is returned indicating if the named column contains
+      any null values (i.e. values equal to the supplied null value, or
+      cells to which no value has yet been assigned).
+   }
+   \sstsynopsis{
+      int astColumnNull( AstFitsTable $*$this, const char $*$column, int set,
+                         int newval, int $*$wasset, int $*$hasnull )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the \htmlref{Table}{Table}.
+      }
+      \sstsubsection{
+         column
+      }{
+         The character string holding the name of the column. Trailing
+         spaces are ignored.
+      }
+      \sstsubsection{
+         set
+      }{
+         If non-zero, the value supplied for parameter \texttt{"} newval\texttt{"}
+         will be stored as the current null value, replacing any value
+         set by a previous call to this function.
+         If zero, the value supplied for parameter \texttt{"} newval\texttt{"}
+         is ignored and the current null value is left unchanged.
+      }
+      \sstsubsection{
+         newval
+      }{
+         The new null value to use. Ignored if
+         \texttt{"} set\texttt{"}  is zero.
+         An error will be reported if the supplied value is outside the
+         range of values that can be stored in the integer data type
+         associated with the column.
+      }
+      \sstsubsection{
+         wasset
+      }{
+         Pointer to an int that will be returned non-zero
+         if the returned null value was set previously via an
+         earlier invocation of this function.
+         Zero
+         is returned otherwise. If the named column does not exist, or an
+         error occurs, a value of
+         zero is returned.
+      }
+      \sstsubsection{
+         hasnull
+      }{
+         Pointer to an int that will be returned non-zero
+         if and only if the named column currently contains any values
+         equal to the null value on exit (i.e.
+         \texttt{"} newval\texttt{"}  if \texttt{"} set\texttt{"}  is non-zero,
+         or the returned function value otherwise), or contains any empty
+         cells. If the named column does not exist, or an error occurs, a
+         value of
+         zero is returned.
+         If a NULL pointer is supplied for \texttt{"} hasnull\texttt{"} , no check on the
+         presence of null values will be performed.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astColumnNull()
+      }{
+         The null value that was in use on entry to this function. If a
+         null value has been set by a previous invocation of this
+         function, it will be returned. Otherwise, if
+         \texttt{"} set\texttt{"}  is non-zero, the supplied \texttt{"} newval\texttt{"}
+         value is returned. Otherwise, a default value is chosen (if
+         possible) that does not currently occur in the named column. If
+         all available values are in use in the column, an error is
+         reported if and only if the column contains any empty cells.
+         Otherwise, a value of zero is returned. A value of zero is also
+         returned if the named column does not exist, or an error occurs.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The FITS binary table definition allows only integer-valued
+         columns to have an associated null value. This routine will return
+         without action if the column is not integer-valued.
+      }
+   }
+}
+\sstroutine{
+   astColumnShape
+}{
+   Returns the shape of the values in a named column
+}{
+   \sstdescription{
+      This function
+      returns the number of dimensions spaned by each value in a named
+      column of a \htmlref{Table}{Table}, together with the length of each dimension.
+      These are the values supplied when the column was created using
+      \htmlref{astAddColumn}{astAddColumn}.
+   }
+   \sstsynopsis{
+      void astColumnShape( AstTable $*$this, const char $*$column, int mxdim,
+                           int $*$ndim, int $*$dims )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Table.
+      }
+      \sstsubsection{
+         column
+      }{
+         The character string holding the upper case name of the column. Trailing
+         spaces are ignored.
+      }
+      \sstsubsection{
+         mxdim
+      }{
+         The length of the
+         \texttt{"} dims\texttt{"}  array.
+      }
+      \sstsubsection{
+         ndim
+      }{
+         Pointer to an int in which to return the
+         number of dimensions spanned by values in the named column.
+         This will be zero if the column contains scalar values.
+      }
+      \sstsubsection{
+         dims
+      }{
+         Pointer to an
+         array in which to return the length of each dimension. Any
+         excess trailing elements will be filled with the value 1.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          No error is reported if the requested column cannot be found in the
+         given Table. A value of zero is returned for
+         \texttt{"} ndim\texttt{"}  and the supplied values in \texttt{"} dims\texttt{"}
+         are left unchanged.
+
+         \sstitem
+          A value of zero is returned for
+         \texttt{"} ndim\texttt{"}
+         if an error occurs.
+      }
+   }
+}
+\sstroutine{
+   astColumnSize
+}{
+   Get the number of bytes needed to hold a full column of data
+}{
+   \sstdescription{
+      This function returns the number of bytes of memory that must be
+      allocated prior to retrieving the data from a column using
+      \htmlref{astGetColumnData}{astGetColumnData}.
+   }
+   \sstsynopsis{
+      size\_t astColumnSize( AstFitsTable $*$this, const char $*$column,
+                            int $*$hasnull )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the \htmlref{Table}{Table}.
+      }
+      \sstsubsection{
+         column
+      }{
+         The character string holding the name of the column. Trailing
+         spaces are ignored.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         \htmlref{astColumnNull}{astColumnNull}()
+      }{
+         The number of bytes required to store the column data.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          An error will be reported if the named column does not exist in
+         the \htmlref{FitsTable}{FitsTable}.
+
+         \sstitem
+          Zero will be returned as the function value in an error occurs.
+      }
+   }
+}
+\sstroutine{
+   astConvert
+}{
+   Determine how to convert between two coordinate systems
+}{
+   \sstdescription{
+      This function compares two Frames and determines whether it is
+      possible to convert between the coordinate systems which they
+      represent. If conversion is possible, it returns a \htmlref{FrameSet}{FrameSet}
+      which describes the conversion and which may be used (as a
+      \htmlref{Mapping}{Mapping}) to transform coordinate values in either direction.
+
+      The same function may also be used to determine how to convert
+      between two FrameSets (or between a \htmlref{Frame}{Frame} and a FrameSet, or
+      vice versa). This mode is intended for use when (for example)
+      two images have been calibrated by attaching a FrameSet to each.
+      astConvert might then be used to search for a
+      celestial coordinate system that both images have in common, and
+      the result could then be used to convert between the pixel
+      coordinates of both images -- having effectively used their
+      celestial coordinate systems to align them.
+
+      When using FrameSets, there may be more than one possible
+      intermediate coordinate system in which to perform the
+      conversion (for instance, two FrameSets might both have
+      celestial coordinates, detector coordinates, pixel coordinates,
+      etc.). A comma-separated list of coordinate system domains may
+      therefore be given which defines a priority order to use when
+      selecting the intermediate coordinate system.  The path used for
+      conversion must go via an intermediate coordinate system whose
+      \htmlref{Domain}{Domain} attribute matches one of the domains given. If conversion
+      cannot be achieved using the first domain, the next one is
+      considered, and so on, until success is achieved.
+   }
+   \sstsynopsis{
+      AstFrameSet $*$astConvert( AstFrame $*$from, AstFrame $*$to,
+                               const char $*$domainlist )
+   }
+   \sstparameters{
+      \sstsubsection{
+         from
+      }{
+         Pointer to a Frame which represents the \texttt{"} source\texttt{"}  coordinate
+         system.  This is the coordinate system in which you already
+         have coordinates available.
+
+         If a FrameSet is given, its current Frame (as determined by
+         its \htmlref{Current}{Current} attribute) is taken to describe the source
+         coordinate system. Note that the \htmlref{Base}{Base} attribute of this
+         FrameSet may be modified by this function to indicate which
+         intermediate coordinate system was used (see under
+         \texttt{"} FrameSets\texttt{"}  in the \texttt{"} Applicability\texttt{"}  section for details).
+      }
+      \sstsubsection{
+         to
+      }{
+         Pointer to a Frame which represents the \texttt{"} destination\texttt{"}
+         coordinate system. This is the coordinate system into which
+         you wish to convert your coordinates.
+
+         If a FrameSet is given, its current Frame (as determined by
+         its Current attribute) is taken to describe the destination
+         coordinate system. Note that the Base attribute of this
+         FrameSet may be modified by this function to indicate which
+         intermediate coordinate system was used (see under
+         \texttt{"} FrameSets\texttt{"}  in the \texttt{"} Applicability\texttt{"}  section for details).
+      }
+      \sstsubsection{
+         domainlist
+      }{
+         Pointer to a null-terminated character string containing a
+         comma-separated list of Frame domains. This may be used to
+         define a priority order for the different intermediate
+         coordinate systems that might be used to perform the
+         conversion.
+
+         The function will first try to obtain a conversion by making
+         use only of an intermediate coordinate system whose Domain
+         attribute matches the first domain in this list. If this
+         fails, the second domain in the list will be used, and so on,
+         until conversion is achieved. A blank domain (e.g. two
+         consecutive commas) indicates that all coordinate systems
+         should be considered, regardless of their domains.
+
+         This list is case-insensitive and all white space is ignored.
+         If you do not wish to restrict the domain in this way,
+         you should supply an empty string. This is normally
+         appropriate if either of the source or destination coordinate
+         systems are described by Frames (rather than FrameSets),
+         since there is then usually only one possible choice of
+         intermediate coordinate system.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{DSBSpecFrame}{DSBSpecFrame}
+      }{
+         If the \htmlref{AlignSideBand}{AlignSideBand} attribute is non-zero, alignment occurs in the
+         upper sideband expressed within the spectral system and standard of
+         rest given by attributes \htmlref{AlignSystem}{AlignSystem} and \htmlref{AlignStdOfRest}{AlignStdOfRest}. If
+         AlignSideBand is zero, the two DSBSpecFrames are aligned as if
+         they were simple SpecFrames (i.e. the \htmlref{SideBand}{SideBand} is ignored).
+      }
+      \sstsubsection{
+         Frame
+      }{
+         This function applies to all Frames. Alignment occurs within the
+         coordinate system given by attribute AlignSystem.
+      }
+      \sstsubsection{
+         FrameSet
+      }{
+         If either of the \texttt{"} from\texttt{"}  or \texttt{"} to\texttt{"}  parameters is a pointer to a
+         FrameSet, then astConvert will attempt to convert from the
+         coordinate system described by the current Frame of the \texttt{"} from\texttt{"}
+         FrameSet to that described by the current Frame of the \texttt{"} to\texttt{"}
+         FrameSet.
+
+         To achieve this, it will consider all of the Frames within
+         each FrameSet as a possible way of reaching an intermediate
+         coordinate system that can be used for the conversion. There
+         is then the possibility that more than one conversion path
+         may exist and, unless the choice is sufficiently restricted
+         by the \texttt{"} domainlist\texttt{"}  string, the sequence in which the Frames
+         are considered can be important. In this case, the search
+         for a conversion path proceeds as follows:
+         \sstitemlist{
+
+            \sstitem
+             Each field in the \texttt{"} domainlist\texttt{"}  string is considered in turn.
+
+            \sstitem
+             The Frames within each FrameSet are considered in a
+            specific order: (1) the base Frame is always considered
+            first, (2) after this come all the other Frames in
+            Frame-index order (but omitting the base and current Frames),
+            (3) the current Frame is always considered last.  However, if
+            either FrameSet\texttt{'} s \htmlref{Invert}{Invert} attribute is set to a non-zero value
+            (so that the FrameSet is inverted), then its Frames are
+            considered in reverse order. (Note that this still means that
+            the base Frame is considered first and the current Frame
+            last, because the Invert value will also cause these Frames
+            to swap places.)
+
+            \sstitem
+             All source Frames are first considered (in the appropriate
+            order) for conversion to the first destination Frame. If no
+            suitable intermediate coordinate system emerges, they are
+            then considered again for conversion to the second
+            destination Frame (in the appropriate order), and so on.
+
+            \sstitem
+             Generally, the first suitable intermediate coordinate
+            system found is used. However, the overall Mapping between
+            the source and destination coordinate systems is also
+            examined.  Preference is given to cases where both the
+            forward and inverse transformations are defined (as indicated
+            by the \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse} attributes). If only one
+            transformation is defined, the forward one is preferred.
+
+            \sstitem
+             If the domain of the intermediate coordinate system matches
+            the current \texttt{"} domainlist\texttt{"}  field, the conversion path is
+            accepted. Otherwise, the next \texttt{"} domainlist\texttt{"}  field is considered
+            and the process repeated.
+
+         }
+         If conversion is possible, the Base attributes of the two
+         FrameSets will be modified on exit to identify the Frames
+         used to access the intermediate coordinate system which was
+         finally accepted.
+
+         Note that it is possible to force a particular Frame within a
+         FrameSet to be used as the basis for the intermediate
+         coordinate system, if it is suitable, by (a) focussing
+         attention on
+         it by specifying its domain in the \texttt{"} domainlist\texttt{"}  string, or (b)
+         making it the base Frame, since this is always considered
+         first.
+      }
+      \sstsubsection{
+         \htmlref{SpecFrame}{SpecFrame}
+      }{
+         Alignment occurs within the spectral system and standard of rest
+         given by attributes AlignSystem and AlignStdOfRest.
+      }
+      \sstsubsection{
+         \htmlref{TimeFrame}{TimeFrame}
+      }{
+         Alignment occurs within the time system and time scale given by
+         attributes AlignSystem and \htmlref{AlignTimeScale}{AlignTimeScale}.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astConvert()
+      }{
+         If the requested coordinate conversion is possible, the
+         function returns a pointer to a FrameSet which describes the
+         conversion. Otherwise, a null \htmlref{Object}{Object} pointer (AST\_\_NULL) is
+         returned without error.
+
+         If a FrameSet is returned, it will contain two Frames. Frame
+         number 1 (its base Frame) will describe the source coordinate
+         system, corresponding to the \texttt{"} from\texttt{"}  parameter. Frame number 2
+         (its current Frame) will describe the destination coordinate
+         system, corresponding to the \texttt{"} to\texttt{"}  parameter. The Mapping
+         which inter-relates these two Frames will perform the
+         required conversion between their respective coordinate
+         systems.
+
+         Note that a FrameSet may be used both as a Mapping and as a
+         Frame.  If the result is used as a Mapping (e.g. with
+         \htmlref{astTran2}{astTran2}), then it provides a means of converting coordinates
+         from the source to the destination coordinate system (or
+         vice versa if its inverse transformation is selected). If it
+         is used as a Frame, its attributes will describe the
+         destination coordinate system.
+      }
+   }
+   \sstexamples{
+      \sstexamplesubsection{
+         cvt = astConvert( a, b, \texttt{"} \texttt{"}  );
+      }{
+         Attempts to convert between the coordinate systems represented
+         by \texttt{"} a\texttt{"}  and \texttt{"} b\texttt{"}  (assumed to be Frames). If successful, a FrameSet
+         is returned via the \texttt{"} cvt\texttt{"}  pointer which may be used to apply the
+         conversion to sets of coordinates (e.g. using astTran2).
+      }
+      \sstexamplesubsection{
+         cvt = astConvert( \htmlref{astSkyFrame}{astSkyFrame}(\texttt{"} \texttt{"} ), astSkyFrame(\texttt{"} \htmlref{Equinox}{Equinox}=2005\texttt{"} ), \texttt{"} \texttt{"}  );
+      }{
+         Creates a FrameSet which describes precession in the default
+         FK5 celestial coordinate system between equinoxes J2000 (also
+         the default) and J2005. The returned \texttt{"} cvt\texttt{"}  pointer may then
+         be passed to astTran2 to apply this precession correction to
+         any number of coordinate values given in radians.
+
+         Note that the returned FrameSet also contains information
+         about how to format coordinate values. This means that
+         setting its \htmlref{Report}{Report} attribute to 1 is a simple way to obtain
+         printed output (formatted in sexagesimal notation) to show
+         the coordinate values before and after conversion.
+      }
+      \sstexamplesubsection{
+         cvt = astConvert( a, b, \texttt{"} sky,detector,\texttt{"}  );
+      }{
+         Attempts to convert between the coordinate systems
+         represented by the current Frames of \texttt{"} a\texttt{"}  and \texttt{"} b\texttt{"}
+         (now assumed to be FrameSets), via the intermediate \texttt{"} SKY\texttt{"}
+         coordinate system.  This, by default, is the Domain
+         associated with a celestial coordinate system represented by
+         a \htmlref{SkyFrame}{SkyFrame}.
+
+         If this fails (for example, because either FrameSet lacks
+         celestial coordinate information), then the user-defined
+         \texttt{"} DETECTOR\texttt{"}  coordinate system is used instead. If this also
+         fails, then all other possible ways of achieving conversion
+         are considered before giving up.
+
+         The returned pointer \texttt{"} cvt\texttt{"}  indicates whether conversion was
+         possible and will have the value AST\_\_NULL if it was not. If
+         conversion was possible, \texttt{"} cvt\texttt{"}  will point at a new FrameSet
+         describing the conversion.
+
+         The Base attributes of the two FrameSets
+         will be set by astConvert to indicate which of their Frames was
+         used for the intermediate coordinate system. This means that
+         you can subsequently determine which coordinate system was
+         used by enquiring the Domain attribute of either base Frame.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The Mapping represented by the returned FrameSet results in
+         alignment taking place in the coordinate system specified by the
+         AlignSystem attribute of the \texttt{"} to\texttt{"}  Frame. See the description of the
+         AlignSystem attribute for further details.
+
+         \sstitem
+          When aligning (say) two images, which have been calibrated by
+         attaching FrameSets to them, it is usually necessary to convert
+         between the base Frames (representing \texttt{"} native\texttt{"}  pixel
+         coordinates) of both FrameSets. This may be achieved by
+         inverting the FrameSets (e.g. using \htmlref{astInvert}{astInvert}) so as to
+         interchange their base and current Frames before using
+         astConvert.
+
+         \sstitem
+          A null Object pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astConvex$<$X$>$
+}{
+   Create a new Polygon representing the convex hull of a 2D data grid
+}{
+   \sstdescription{
+      This is a set of functions that create the shortest \htmlref{Polygon}{Polygon} that
+      encloses all pixels with a specified value within a gridded
+      2-dimensional data array (e.g. an image).
+
+      A basic 2-dimensional \htmlref{Frame}{Frame} is used to represent the pixel coordinate
+      system in the returned Polygon. The \htmlref{Domain}{Domain} attribute is set to
+      \texttt{"} PIXEL\texttt{"} , the \htmlref{Title}{Title} attribute is set to \texttt{"} Pixel coordinates\texttt{"} , and the
+      Unit attribute for each axis is set to \texttt{"} pixel\texttt{"} . All other
+      attributes are left unset. The nature of the pixel coordinate system
+      is determined by parameter
+      \texttt{"} starpix\texttt{"} .
+
+      You should use a function which matches the numerical type of the
+      data you are processing by replacing $<$X$>$ in the generic function
+      name
+      astConvex$<$X$>$
+      by an appropriate 1- or 2-character type code. For example, if you
+      are procesing data with type
+      \texttt{"} float\texttt{"} , you should use the function astConvexF
+      (see the \texttt{"} Data Type Codes\texttt{"}  section below for the codes appropriate to
+      other numerical types).
+   }
+   \sstsynopsis{
+      AstPolygon $*$astConvex$<$X$>$( $<$Xtype$>$ value, int oper, const $<$Xtype$>$ array[],
+                                 const int lbnd[2], const int ubnd[2], int starpix )
+   }
+   \sstparameters{
+      \sstsubsection{
+         value
+      }{
+         A data value that specifies the pixels to be included within the
+         convex hull.
+      }
+      \sstsubsection{
+         oper
+      }{
+         Indicates how the
+         \texttt{"} value\texttt{"}
+         parameter is used to select the required pixels. It can
+         have any of the following values:
+         \sstitemlist{
+
+            \sstitem
+             AST\_\_LT: include pixels with value less than \texttt{"} value\texttt{"} .
+
+            \sstitem
+             AST\_\_LE: include pixels with value less than or equal to \texttt{"} value\texttt{"} .
+
+            \sstitem
+             AST\_\_EQ: include pixels with value equal to \texttt{"} value\texttt{"} .
+
+            \sstitem
+             AST\_\_NE: include pixels with value not equal to \texttt{"} value\texttt{"} .
+
+            \sstitem
+             AST\_\_GE: include pixels with value greater than or equal to \texttt{"} value\texttt{"} .
+
+            \sstitem
+             AST\_\_GT: include pixels with value greater than \texttt{"} value\texttt{"} .
+         }
+      }
+      \sstsubsection{
+         array
+      }{
+         Pointer to a
+         2-dimensional array containing the data to be processed.  The
+         numerical type of this array should match the 1- or
+         2-character type code appended to the function name (e.g. if
+         you are using astConvexF, the type of each array element
+         should be \texttt{"} float\texttt{"} ).
+
+         The storage order of data within this array should be such
+         that the index of the first grid dimension varies most
+         rapidly and that of the second dimension least rapidly
+         (i.e. Fortran array indexing is used).
+      }
+      \sstsubsection{
+         lbnd
+      }{
+         Pointer to an array of two integers
+         containing the coordinates of the centre of the first pixel
+         in the input grid along each dimension.
+      }
+      \sstsubsection{
+         ubnd
+      }{
+         Pointer to an array of two integers
+         containing the coordinates of the centre of the last pixel in
+         the input grid along each dimension.
+
+         Note that \texttt{"} lbnd\texttt{"}  and \texttt{"} ubnd\texttt{"}  together define the shape
+         and size of the input grid, its extent along a particular
+         (j\texttt{'} th) dimension being ubnd[j]-lbnd[j]$+$1 (assuming the
+         index \texttt{"} j\texttt{"}  to be zero-based). They also define
+         the input grid\texttt{'} s coordinate system, each pixel having unit
+         extent along each dimension with integral coordinate values
+         at its centre or upper corner, as selected by parameter
+         \texttt{"} starpix\texttt{"} .
+      }
+      \sstsubsection{
+         starpix
+      }{
+         A flag indicating the nature of the pixel coordinate system used
+         to describe the vertex positions in the returned Polygon. If
+         non-zero,
+         the standard Starlink definition of pixel coordinate is used in
+         which a pixel with integer index I spans a range of pixel coordinate
+         from (I-1) to I (i.e. pixel corners have integral pixel coordinates).
+         If zero,
+         the definition of pixel coordinate used by other AST functions
+         such as astResample, astMask,
+         etc., is used. In this definition, a pixel with integer index I
+         spans a range of pixel coordinate from (I-0.5) to (I$+$0.5) (i.e.
+         pixel centres have integral pixel coordinates).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astConvex$<$X$>$()
+      }{
+         A pointer to the required Polygon.
+         NULL
+         is returned without error if the array contains no pixels that
+         satisfy the criterion specified by
+         \texttt{"} value\texttt{"}  and \texttt{"} oper\texttt{"} .
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          NULL
+         will be returned if this function is invoked with the global
+         error status set, or if it should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      Data Type Codes
+   }{
+      To select the appropriate masking function, you should
+      replace $<$X$>$ in the generic function name astConvex$<$X$>$ with a
+      1- or 2-character data type code, so as to match the numerical
+      type $<$Xtype$>$ of the data you are processing, as follows:
+      \sstitemlist{
+
+         \sstitem
+          D: double
+
+         \sstitem
+          F: float
+
+         \sstitem
+          L: long int
+
+         \sstitem
+          UL: unsigned long int
+
+         \sstitem
+          I: int
+
+         \sstitem
+          UI: unsigned int
+
+         \sstitem
+          S: short int
+
+         \sstitem
+          US: unsigned short int
+
+         \sstitem
+          B: byte (signed char)
+
+         \sstitem
+          UB: unsigned byte (unsigned char)
+
+      }
+      For example, astConvexD would be used to process \texttt{"} double\texttt{"}
+      data, while astConvexS would be used to process \texttt{"} short int\texttt{"}
+      data, etc.
+   }
+}
+\sstroutine{
+   astCopy
+}{
+   Copy an Object
+}{
+   \sstdescription{
+      This function creates a copy of an \htmlref{Object}{Object} and returns a pointer
+      to the resulting new Object. It makes a \texttt{"} deep\texttt{"}  copy, which
+      contains no references to any other Object (i.e. if the original
+      Object contains references to other Objects, then the actual
+      data are copied, not simply the references). This means that
+      modifications may safely be made to the copy without indirectly
+      affecting any other Object.
+   }
+   \sstsynopsis{
+      AstObject $*$astCopy( const AstObject $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Object to be copied.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         This function applies to all Objects.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astCopy()
+      }{
+         Pointer to the new Object.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null Object pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astCreatedAt
+}{
+   Return the routine, file and line number at which an Object was
+   created
+}{
+   \sstdescription{
+      This function returns pointers to two strings containing the
+      name of the routine or function within which the object was created
+      and the name of the source file containing that routine. It also
+      returns the number of the line within the file at which the object
+      was created. It is intended for use in debugging memory leaks etc.
+
+      Precisely, the information returned identifies the point at which
+      the \htmlref{Object}{Object}\texttt{'} s public identifier (i.e. the supplied pointer) was
+      first issued. This may not correspond to the actual creation of the
+      Object if the object is contained within some higher level Object.
+      For instance, if the \htmlref{astGetFrame}{astGetFrame} method is used to get a pointer to
+      a \htmlref{Frame}{Frame} within a \htmlref{FrameSet}{FrameSet}, the information returned by this
+      function if supplied with the Frame pointer would identify the call
+      to astGetFrame, rather than the line at which the FrameSet created
+      its internal copy of the Frame. Likewise, if this function is used
+      to get information from an Object pointer returned by \htmlref{astClone}{astClone}, the
+      information will describe the call to astClone, not the call that
+      created the original Object.
+   }
+   \sstsynopsis{
+      void astCreatedAt( AstObject $*$this, const char $*$$*$routine,
+                         const char $*$$*$file, int $*$line )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Object.
+      }
+      \sstsubsection{
+         routine
+      }{
+         Address of a pointer to a null terminated C string in which to
+         return the routine name (the string will reside in static memory).
+         The pointer will be set to NULL on exit if no routine name is
+         available.
+      }
+      \sstsubsection{
+         file
+      }{
+         Address of a pointer to a null terminated C string in which to
+         return the file name (the string will reside in static memory).
+         The pointer will be set to NULL on exit if no file name is
+         available.
+      }
+      \sstsubsection{
+         line
+      }{
+         Address of an int in which to store the line number in the file.
+         A line number of zero is returned if no line number is available.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          NULL pointers and a line number of zero are returned if an error
+         has already occurred prior to calling this function.
+      }
+   }
+}
+\sstroutine{
+   astCurrentTime
+}{
+   Return the current system time
+}{
+   \sstdescription{
+      This function
+      returns the current system time, represented in the form specified
+      by the supplied \htmlref{TimeFrame}{TimeFrame}. That is, the returned floating point
+      value should be interpreted using the attribute values of the
+      TimeFrame. This includes \htmlref{System}{System}, \htmlref{TimeOrigin}{TimeOrigin}, \htmlref{LTOffset}{LTOffset}, \htmlref{TimeScale}{TimeScale},
+      and Unit.
+   }
+   \sstsynopsis{
+      double astCurrentTime( AstTimeFrame $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the TimeFrame.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astCurrentTime()
+      }{
+         A TimeFrame axis value representing the current system time.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Values of AST\_\_BAD will be returned if this function is
+         invoked with the AST error status set, or if it should fail for
+         any reason.
+
+         \sstitem
+          It is assumes that the system time (returned by the C time()
+         function) follows the POSIX standard, representing a continuous
+         monotonic increasing count of SI seconds since the epoch 00:00:00
+         UTC 1 January 1970 AD (equivalent to TAI with a constant offset).
+         Resolution is one second.
+
+         \sstitem
+          An error will be reported if the TimeFrame has a TimeScale value
+         which cannot be converted to TAI (e.g. \texttt{"} angular\texttt{"}  systems such as
+         UT1, GMST, LMST and LAST).
+
+         \sstitem
+          Any inaccuracy in the system clock will be reflected in the value
+         returned by this function.
+      }
+   }
+}
+\sstroutine{
+   astCurve
+}{
+   Draw a geodesic curve
+}{
+   \sstdescription{
+      This function draws a geodesic curve between two points in the
+      physical coordinate system of a \htmlref{Plot}{Plot}.  The curve drawn is the
+      path of shortest distance joining the two points (as defined by
+      the \htmlref{astDistance}{astDistance} function for the current \htmlref{Frame}{Frame} of the Plot).
+      For example, if the current Frame is a basic Frame, then the
+      curve joining the two points will be a straight line in physical
+      coordinate space.  If the current Frame is more specialised and
+      describes, for instance, a sky coordinate system, then the
+      geodesic curve would be a great circle in physical coordinate
+      space passing through the two sky positions given.
+
+      Note that the geodesic curve is transformed into graphical
+      coordinate space for plotting, so that a straight line in
+      physical coordinates may result in a curved line being drawn if
+      the \htmlref{Mapping}{Mapping} involved is non-linear. Any discontinuities in the
+      Mapping between physical and graphical coordinates are
+      catered for, as is any clipping established using \htmlref{astClip}{astClip}.
+
+      If you need to draw many geodesic curves end-to-end, then the
+      \htmlref{astPolyCurve}{astPolyCurve} function is equivalent to repeatedly using
+      astCurve, but will usually be more efficient.
+
+      If you need to draw curves which are not geodesics, see \htmlref{astGenCurve}{astGenCurve}
+      or \htmlref{astGridLine}{astGridLine}.
+   }
+   \sstsynopsis{
+      void astCurve( AstPlot $*$this, const double start[],
+                                    const double finish[] )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Plot.
+      }
+      \sstsubsection{
+         start
+      }{
+         An array, with one element for each axis of the Plot, giving
+         the physical coordinates of the first point on the geodesic
+         curve.
+      }
+      \sstsubsection{
+         finish
+      }{
+         An array, with one element for each axis of the Plot, giving
+         the physical coordinates of the second point on the geodesic
+         curve.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          No curve is drawn if either of the \texttt{"} start\texttt{"}  or \texttt{"} finish\texttt{"}  arrays
+         contains any coordinates with the value AST\_\_BAD.
+
+         \sstitem
+          An error results if the base Frame of the Plot is not 2-dimensional.
+
+         \sstitem
+          An error also results if the transformation between the
+         current and base Frames of the Plot is not defined (i.e. the
+         Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero).
+      }
+   }
+}
+\sstroutine{
+   astDSBSpecFrame
+}{
+   Create a DSBSpecFrame
+}{
+   \sstdescription{
+      This function creates a new \htmlref{DSBSpecFrame}{DSBSpecFrame} and optionally initialises its
+      attributes.
+
+      A DSBSpecFrame is a specialised form of \htmlref{SpecFrame}{SpecFrame} which represents
+      positions in a spectrum obtained using a dual sideband instrument.
+      Such an instrument produces a spectrum in which each point contains
+      contributions from two distinctly different frequencies, one from
+      the \texttt{"} lower side band\texttt{"}  (LSB) and one from the \texttt{"} upper side band\texttt{"}  (USB).
+      Corresponding LSB and USB frequencies are connected by the fact
+      that they are an equal distance on either side of a fixed central
+      frequency known as the \texttt{"} Local Oscillator\texttt{"}  (LO) frequency.
+
+      When quoting a position within such a spectrum, it is necessary to
+      indicate whether the quoted position is the USB position or the
+      corresponding LSB position. The \htmlref{SideBand}{SideBand} attribute provides this
+      indication. Another option that the SideBand attribute provides is
+      to represent a spectral position by its topocentric offset from the
+      LO frequency.
+
+      In practice, the LO frequency is specified by giving the distance
+      from the LO frequency to some \texttt{"} central\texttt{"}  spectral position. Typically
+      this central position is that of some interesting spectral feature.
+      The distance from this central position to the LO frequency is known
+      as the \texttt{"} intermediate frequency\texttt{"}  (\htmlref{IF}{IF}). The value supplied for IF can
+      be a signed value in order to indicate whether the LO frequency is
+      above or below the central position.
+   }
+   \sstsynopsis{
+      AstDSBSpecFrame $*$astDSBSpecFrame( const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new DSBSpecFrame. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astDSBSpecFrame()
+      }{
+         A pointer to the new DSBSpecFrame.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astDecompose
+}{
+   Decompose a Mapping into two component Mappings
+}{
+   \sstdescription{
+      This function returns pointers to two Mappings which, when applied
+      either in series or parallel, are equivalent to the supplied \htmlref{Mapping}{Mapping}.
+
+      Since the \htmlref{Frame}{Frame} class inherits from the Mapping class, Frames can
+      be considered as special types of Mappings and so this method can
+      be used to decompose either CmpMaps or CmpFrames.
+   }
+   \sstsynopsis{
+      void astDecompose( AstMapping $*$this, AstMapping $*$$*$map1,
+                         AstMapping $*$$*$map2, int $*$series, int $*$invert1,
+                         int $*$invert2  )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Mapping.
+      }
+      \sstsubsection{
+         map1
+      }{
+         Address of a location to receive a pointer to first component
+         Mapping.
+      }
+      \sstsubsection{
+         map2
+      }{
+         Address of a location to receive a pointer to second component
+         Mapping.
+      }
+      \sstsubsection{
+         series
+      }{
+         Address of a location to receive a value indicating if the
+         component Mappings are applied in series or parallel. A non-zero
+         value means that the supplied Mapping is equivalent to applying map1
+         followed by map2 in series. A zero value means that the supplied
+         Mapping is equivalent to applying map1 to the lower numbered axes
+         and map2 to the higher numbered axes, in parallel.
+      }
+      \sstsubsection{
+         invert1
+      }{
+         The value of the \htmlref{Invert}{Invert} attribute to be used with map1.
+      }
+      \sstsubsection{
+         invert2
+      }{
+         The value of the Invert attribute to be used with map2.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{CmpMap}{CmpMap}
+      }{
+         If the supplied Mapping is a CmpMap, then map1 and map2 will be
+         returned holding pointers to the component Mappings used to
+         create the CmpMap, either in series or parallel. Note, changing
+         the Invert attribute of either of the component Mappings using
+         the returned pointers will have no effect on the supplied CmpMap.
+         This is because the CmpMap remembers and uses the original settings
+         of the Invert attributes (that is, the values of the Invert
+         attributes when the CmpMap was first created). These are the
+         Invert values which are returned in invert1 and invert2.
+      }
+      \sstsubsection{
+         \htmlref{TranMap}{TranMap}
+      }{
+         If the supplied Mapping is a TranMap, then map1 and map2 will be
+         returned holding pointers to the forward and inverse Mappings
+         represented by the TranMap (zero will be returned for
+         series).
+         Note, changing the Invert attribute of
+         either of the component Mappings using the returned pointers will
+         have no effect on the supplied TranMap. This is because the TranMap
+         remembers and uses the original settings of the Invert attributes
+         (that is, the values of the Invert attributes when the TranMap was
+         first created). These are the
+         Invert values which are returned in invert1 and invert2.
+      }
+      \sstsubsection{
+         Mapping
+      }{
+         For any class of Mapping other than a CmpMap, map1 will be
+         returned holding a clone of the supplied Mapping pointer, and map2
+         will be returned holding a NULL pointer. Invert1 will be returned
+         holding the current value of the Invert attribute for the supplied
+         Mapping, and invert2 will be returned holding zero.
+      }
+      \sstsubsection{
+         \htmlref{CmpFrame}{CmpFrame}
+      }{
+         If the supplied Mapping is a CmpFrame, then map1 and map2 will be
+         returned holding pointers to the component Frames used to
+         create the CmpFrame. The component Frames are considered to be in
+         applied in parallel.
+      }
+      \sstsubsection{
+         Frame
+      }{
+         For any class of Frame other than a CmpFrame, map1 will be
+         returned holding a clone of the supplied Frame pointer, and map2
+         will be returned holding a NULL pointer.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The returned Invert values should be used in preference to the
+         current values of the Invert attribute in map1 and map2. This is
+         because the attributes may have changed value since the Mappings
+         were combined.
+
+         \sstitem
+          Any changes made to the component Mappings using the returned
+         pointers will be reflected in the supplied Mapping.
+      }
+   }
+}
+\sstroutine{
+   astDelFits
+}{
+   Delete the current FITS card in a FitsChan
+}{
+   \sstdescription{
+      This function deletes the current FITS card from a \htmlref{FitsChan}{FitsChan}. The
+      current card may be selected using the \htmlref{Card}{Card} attribute (if its index
+      is known) or by using \htmlref{astFindFits}{astFindFits} (if only the FITS keyword is
+      known).
+
+      After deletion, the following card becomes the current card.
+   }
+   \sstsynopsis{
+      void astDelFits( AstFitsChan $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FitsChan.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This function returns without action if the FitsChan is
+         initially positioned at the \texttt{"} end-of-file\texttt{"}  (i.e. if the Card
+         attribute exceeds the number of cards in the FitsChan).
+
+         \sstitem
+          If there are no subsequent cards in the FitsChan, then the
+         Card attribute is left pointing at the \texttt{"} end-of-file\texttt{"}  after
+         deletion (i.e. is set to one more than the number of cards in
+         the FitsChan).
+      }
+   }
+}
+\sstroutine{
+   astDelete
+}{
+   Delete an Object
+}{
+   \sstdescription{
+      This function deletes an \htmlref{Object}{Object}, freeing all resources
+      associated with it and rendering any remaining pointers to the
+      Object invalid.
+
+      Note that deletion is unconditional, regardless of whether other
+      pointers to the Object are still in use (possibly within other
+      Objects). A safer approach is to defer deletion, until all
+      references to an Object have expired, by using \htmlref{astBegin}{astBegin}/\htmlref{astEnd}{astEnd}
+      (together with \htmlref{astClone}{astClone} and \htmlref{astAnnul}{astAnnul} if necessary).
+   }
+   \sstsynopsis{
+      AstObject $*$astDelete( AstObject $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Object to be deleted.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         This function applies to all Objects.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astDelete()
+      }{
+         A null Object pointer (AST\_\_NULL) is always returned.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This function attempts to execute even if the AST error status
+         is set
+         on entry, although no further error report will be
+         made if it subsequently fails under these circumstances.
+      }
+   }
+}
+\sstroutine{
+   astDistance
+}{
+   Calculate the distance between two points in a Frame
+}{
+   \sstdescription{
+      This function finds the distance between two points whose \htmlref{Frame}{Frame}
+      coordinates are given. The distance calculated is that along
+      the geodesic curve that joins the two points.
+
+      For example, in a basic Frame, the distance calculated will be
+      the Cartesian distance along the straight line joining the two
+      points. For a more specialised Frame describing a sky coordinate
+      system, however, it would be the distance along the great circle
+      passing through two sky positions.
+   }
+   \sstsynopsis{
+      double astDistance( AstFrame $*$this,
+                          const double point1[], const double point2[] )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Frame.
+      }
+      \sstsubsection{
+         point1
+      }{
+         An array of double, with one element for each Frame axis
+         (\htmlref{Naxes}{Naxes} attribute) containing the coordinates of the first point.
+      }
+      \sstsubsection{
+         point2
+      }{
+         An array of double, with one element for each Frame axis
+         containing the coordinates of the second point.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astDistance
+      }{
+         The distance between the two points.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This function will return a \texttt{"} bad\texttt{"}  result value (AST\_\_BAD) if
+         any of the input coordinates has this value.
+
+         \sstitem
+          A \texttt{"} bad\texttt{"}  value will also be returned if this function is
+         invoked with the AST error status set, or if it should fail for
+         any reason.
+      }
+   }
+}
+\sstroutine{
+   astDownsize
+}{
+   Reduce the number of vertices in a Polygon
+}{
+   \sstdescription{
+      This function returns a pointer to a new \htmlref{Polygon}{Polygon} that contains a
+      subset of the vertices in the supplied Polygon. The subset is
+      chosen so that the returned Polygon is a good approximation to
+      the supplied Polygon, within the limits specified by the supplied
+      parameter values. That is, the density of points in the returned
+      Polygon is greater at points where the curvature of the boundary of
+      the supplied Polygon is greater.
+   }
+   \sstsynopsis{
+      AstPolygon $*$astDownsize( AstPolygon $*$this, double maxerr, int maxvert )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Polygon.
+      }
+      \sstsubsection{
+         maxerr
+      }{
+         The maximum allowed discrepancy between the supplied and
+         returned Polygons, expressed as a geodesic distance within the
+         Polygon\texttt{'} s coordinate frame. If this is zero or less, the
+         returned Polygon will have the number of vertices specified by
+         maxvert.
+      }
+      \sstsubsection{
+         maxvert
+      }{
+         The maximum allowed number of vertices in the returned Polygon.
+         If this is less than 3, the number of vertices in the returned
+         Polygon will be the minimum needed to achieve the maximum
+         discrepancy specified by
+         maxerr.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astDownsize()
+      }{
+         Pointer to the new Polygon.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astEBuf
+}{
+   End the current graphical buffering context
+}{
+   \sstdescription{
+      This function
+      ends the current graphics buffering context. It should match a
+      corresponding call to the
+      \htmlref{astBBuf}{astBBuf} function.
+   }
+   \sstsynopsis{
+      void astEBuf( AstPlot $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the \htmlref{Plot}{Plot}.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The nature of the buffering is determined by the underlying
+         graphics system (as defined by the current grf module). Each call
+         to this function
+         simply invokes the astGEBuf function in the grf module.
+      }
+   }
+}
+\sstroutine{
+   astEllipse
+}{
+   Create a Ellipse
+}{
+   \sstdescription{
+      This function creates a new \htmlref{Ellipse}{Ellipse} and optionally initialises its
+      attributes.
+
+      A Ellipse is a \htmlref{Region}{Region} which represents a elliptical area within the
+      supplied 2-dimensional \htmlref{Frame}{Frame}.
+   }
+   \sstsynopsis{
+      AstEllipse $*$astEllipse( AstFrame $*$frame, int form, const double centre[2],
+                              const double point1[2], const double point2[2],
+                              AstRegion $*$unc, const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         frame
+      }{
+         A pointer to the Frame in which the region is defined. It must
+         have exactly 2 axes. A deep copy is taken of the supplied Frame.
+         This means that any subsequent changes made to the Frame using the
+         supplied pointer will have no effect the Region.
+      }
+      \sstsubsection{
+         form
+      }{
+         Indicates how the ellipse is described by the remaining parameters.
+         A value of zero indicates that the ellipse is specified by a
+         centre position and two positions on the circumference. A value of
+         one indicates that the ellipse is specified by its centre position,
+         the half-lengths of its two axes, and the orientation of its first
+         axis.
+      }
+      \sstsubsection{
+         centre
+      }{
+         An array of 2 doubles,
+         containing the coordinates at the centre of
+         the ellipse.
+      }
+      \sstsubsection{
+         point1
+      }{
+         An array of 2 doubles. If \texttt{"} form\texttt{"}
+         is zero, this array should contain the coordinates of one of the four
+         points where an axis of the ellipse crosses the circumference of the
+         ellipse.
+         If \texttt{"} form\texttt{"}
+         is one, it should contain the lengths of semi-major and
+         semi-minor axes of the ellipse, given as geodesic distances
+         within the Frame.
+      }
+      \sstsubsection{
+         point2
+      }{
+         An array of 2 doubles. If \texttt{"} form\texttt{"}
+         is zero, this array should containing the coordinates at some other
+         point on the circumference of the ellipse, distinct from
+         \texttt{"} point1\texttt{"} . If \texttt{"} form\texttt{"}
+         is one, the first element of this array should hold the angle
+         between the second axis of the Frame and the first ellipse axis
+         (i.e. the ellipse axis which is specified first in the
+         \texttt{"} point1\texttt{"}
+         array), and the second element will be ignored. The angle should be
+         given in radians, measured positive in the same sense as rotation
+         from the positive direction of the second Frame axis to the positive
+         direction of the first Frame axis.
+      }
+      \sstsubsection{
+         unc
+      }{
+         An optional pointer to an existing Region which specifies the
+         uncertainties associated with the boundary of the Ellipse being created.
+         The uncertainty in any point on the boundary of the Ellipse is found by
+         shifting the supplied \texttt{"} uncertainty\texttt{"}  Region so that it is centred at
+         the boundary point being considered. The area covered by the
+         shifted uncertainty Region then represents the uncertainty in the
+         boundary position. The uncertainty is assumed to be the same for
+         all points.
+
+         If supplied, the uncertainty Region must be of a class for which
+         all instances are centro-symetric (e.g. \htmlref{Box}{Box}, \htmlref{Circle}{Circle}, Ellipse, etc.)
+         or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep
+         copy of the supplied Region will be taken, so subsequent changes to
+         the uncertainty Region using the supplied pointer will have no
+         effect on the created Ellipse. Alternatively,
+         a NULL \htmlref{Object}{Object} pointer
+         may be supplied, in which case a default uncertainty is used
+         equivalent to a box 1.0E-6 of the size of the Ellipse being created.
+
+         The uncertainty Region has two uses: 1) when the
+         \htmlref{astOverlap}{astOverlap}
+         function compares two Regions for equality the uncertainty
+         Region is used to determine the tolerance on the comparison, and 2)
+         when a Region is mapped into a different coordinate system and
+         subsequently simplified (using
+         \htmlref{astSimplify}{astSimplify}),
+         the uncertainties are used to determine if the transformed boundary
+         can be accurately represented by a specific shape of Region.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new Ellipse. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astEllipse()
+      }{
+         A pointer to the new Ellipse.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null Object pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astEllipsePars
+}{
+   Returns the geometric parameters of an Ellipse
+}{
+   \sstdescription{
+      This function
+      returns the geometric parameters describing the supplied ellipse.
+   }
+   \sstsynopsis{
+      void astEllipsePars( AstEllipse $*$this, double centre[2], double $*$a,
+                           double $*$b, double $*$angle, double p1[2], double p2[2] )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the \htmlref{Region}{Region}.
+      }
+      \sstsubsection{
+         centre
+      }{
+         The coordinates of the \htmlref{Ellipse}{Ellipse} centre are returned in this arrays.
+      }
+      \sstsubsection{
+         a
+      }{
+         Returned holding the half-length of the first axis of the
+         ellipse.
+      }
+      \sstsubsection{
+         b
+      }{
+         Returned holding the half-length of the second axis of the
+         ellipse.
+      }
+      \sstsubsection{
+         angle
+      }{
+         If the coordinate system in which the Ellipse is defined has
+         axes (X,Y), then
+         \texttt{"} $*$angle\texttt{"}
+         is returned holding the angle from the positive direction of
+         the Y axis to the first axis of the ellipse, in radians.
+         Positive rotation is in the same sense as rotation from the
+         positive direction of Y to the positive direction of X.
+      }
+      \sstsubsection{
+         p1
+      }{
+         An array in which to return the coordinates at one of the two ends
+         of the first axis  of the ellipse.
+         A NULL pointer can be supplied if these coordinates are not needed.
+      }
+      \sstsubsection{
+         p2
+      }{
+         An array in which to return the coordinates at one of the two ends
+         of the second axis  of the ellipse.
+         A NULL pointer can be supplied if these coordinates are not needed.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If the coordinate system represented by the Ellipse has been
+         changed since it was first created, the returned parameters refer
+         to the new (changed) coordinate system, rather than the original
+         coordinate system. Note however that if the transformation from
+         original to new coordinate system is non-linear, the shape
+         represented by the supplied Ellipse object may not be an accurate
+         ellipse.
+
+         \sstitem
+          Values of AST\_\_BAD are returned for the parameters without error
+         if the ellipse is degenerate or undefined.
+      }
+   }
+}
+\sstroutine{
+   astEmptyFits
+}{
+   Delete all cards in a FitsChan
+}{
+   \sstdescription{
+      This function
+      deletes all cards and associated information from a \htmlref{FitsChan}{FitsChan}.
+   }
+   \sstsynopsis{
+      void astEmptyFits( AstFitsChan $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FitsChan.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This method simply deletes the cards currently in the FitsChan.
+         Unlike \htmlref{astWriteFits}{astWriteFits},
+         they are not first written out to the sink function or sink file.
+
+         \sstitem
+          Any Tables or warnings stored in the FitsChan are also deleted.
+
+         \sstitem
+          This method attempt to execute even if an error has occurred
+         previously.
+      }
+   }
+}
+\sstroutine{
+   astEnd
+}{
+   End an AST context
+}{
+   \sstdescription{
+      This macro invokes a function to end an AST context which was
+      begun with a matching invocation of \htmlref{astBegin}{astBegin}. Any \htmlref{Object}{Object}
+      pointers created within this context will be annulled (just as
+      if \htmlref{astAnnul}{astAnnul} had been invoked) and will cease to be valid
+      afterwards, unless they have previously been exported using
+      \htmlref{astExport}{astExport} or rendered exempt using \htmlref{astExempt}{astExempt}.
+      If annulling a pointer causes an Object\texttt{'} s \htmlref{RefCount}{RefCount} attribute to
+      fall to zero (which happens when the last pointer to it is
+      annulled), then the Object will be deleted.
+   }
+   \sstsynopsis{
+      void astEnd
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         This macro applies to all Objects.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          astEnd attempts to execute even if the AST error status is set.
+
+         \sstitem
+          Contexts delimited by astBegin and astEnd may be nested to any
+         depth.
+      }
+   }
+}
+\sstroutine{
+   astEscapes
+}{
+   Control whether graphical escape sequences are included in strings
+}{
+   \sstdescription{
+      The \htmlref{Plot}{Plot} class defines a set of escape sequences which can be
+      included within a text string in order to control the appearance of
+      sub-strings within the text. See the \htmlref{Escape}{Escape} attribute for a
+      description of these escape sequences. It is usually inappropriate
+      for AST to return strings containing such escape sequences when
+      called by application code. For instance, an application which
+      displays the value of the \htmlref{Title}{Title} attribute of a \htmlref{Frame}{Frame} usually does
+      not want the displayed string to include potentially long escape
+      sequences which a human read would have difficuly interpreting.
+      Therefore the default behaviour is for AST to strip out such escape
+      sequences when called by application code. This default behaviour
+      can be changed using this function.
+   }
+   \sstsynopsis{
+      int astEscapes( int new\_value )
+   }
+   \sstparameters{
+      \sstsubsection{
+         new\_value
+      }{
+         A flag which indicates if escapes sequences should be included
+         in returned strings. If zero is supplied, escape sequences will
+         be stripped out of all strings returned by any AST function. If
+         a positive value is supplied, then any escape sequences will be
+         retained in the value returned to the caller. If a negative
+         value is supplied, the current value of the flag will be left
+         unchanged.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{Object}{Object}
+      }{
+         This macro applies to all Objects.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astEscapes
+      }{
+         The value of the flag on entry to this function.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This function also controls whether the
+         \htmlref{astStripEscapes}{astStripEscapes}
+         function removes escape sequences from the supplied string, or
+         returns the supplied string without change.
+
+         \sstitem
+          This function attempts to execute even if an error has already
+         occurred.
+      }
+   }
+}
+\sstroutine{
+   astExempt
+}{
+   Exempt an Object pointer from AST context handling
+}{
+   \sstdescription{
+      This function exempts an \htmlref{Object}{Object} pointer from AST context
+      handling, as implemented by \htmlref{astBegin}{astBegin} and \htmlref{astEnd}{astEnd}. This means that
+      the pointer will not be affected when astEnd is invoked and will
+      remain active until the end of the program, or until explicitly
+      annulled using \htmlref{astAnnul}{astAnnul}.
+
+      If possible, you should avoid using this function when writing
+      applications. It is provided mainly for developers of other
+      libraries, who may wish to retain references to AST Objects in
+      internal data structures, and who therefore need to avoid the
+      effects of astBegin and astEnd.
+   }
+   \sstsynopsis{
+      void astExempt( AstObject $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Object pointer to be exempted from context handling.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         This function applies to all Objects.
+      }
+   }
+}
+\sstroutine{
+   astExport
+}{
+   Export an Object pointer to an outer context
+}{
+   \sstdescription{
+      This function exports an \htmlref{Object}{Object} pointer from the current AST context
+      into the context that encloses the current one. This means that
+      the pointer will no longer be annulled when the current context
+      is ended (with \htmlref{astEnd}{astEnd}), but only when the next outer context (if
+      any) ends.
+   }
+   \sstsynopsis{
+      void astExport( AstObject $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Object pointer to be exported.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         This function applies to all Objects.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          It is only sensible to apply this function to pointers that
+         have been created within (or exported to) the current context
+         and have not been rendered exempt using \htmlref{astExempt}{astExempt}.
+         Applying it to an unsuitable Object pointer has no effect.
+      }
+   }
+}
+\sstroutine{
+   astFindFits
+}{
+   Find a FITS card in a FitsChan by keyword
+}{
+   \sstdescription{
+      This function searches for a card in a \htmlref{FitsChan}{FitsChan} by keyword. The
+      search commences at the current card (identified by the \htmlref{Card}{Card}
+      attribute) and ends when a card is found whose FITS keyword
+      matches the template supplied, or when the last card in the
+      FitsChan has been searched.
+
+      If the search is successful (i.e. a card is found which matches
+      the template), the contents of the card are (optionally)
+      returned and the Card attribute is adjusted to identify the card
+      found or, if required, the one following it. If the search is
+      not successful, the function returns zero and the Card attribute
+      is set to the \texttt{"} end-of-file\texttt{"} .
+   }
+   \sstsynopsis{
+      int astFindFits( AstFitsChan $*$this, const char $*$name, char card[ 81 ],
+                       int inc )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FitsChan.
+      }
+      \sstsubsection{
+         name
+      }{
+         Pointer to a null-terminated character string containing a
+         template for the keyword to be found. In the simplest case,
+         this should simply be the keyword name (the search is case
+         insensitive and trailing spaces are ignored). However, this
+         template may also contain \texttt{"} field specifiers\texttt{"}  which are
+         capable of matching a range of characters (see the \texttt{"} Keyword
+         Templates\texttt{"}  section for details). In this case, the first card
+         with a keyword which matches the template will be found. To
+         find the next FITS card regardless of its keyword, you should
+         use the template \texttt{"} \%f\texttt{"} .
+      }
+      \sstsubsection{
+         card
+      }{
+         An array of at least 81 characters (to allow room for a
+         terminating null)
+         in which the FITS card which is found will be returned.  If
+         the search is not successful (or a NULL pointer is given), a
+         card will not be returned.
+      }
+      \sstsubsection{
+         inc
+      }{
+         If this value is zero (and the search is successful), the
+         FitsChan\texttt{'} s Card attribute will be set to the index of the card
+         that was found. If it is non-zero, however, the Card
+         attribute will be incremented to identify the card which
+         follows the one found.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astFindFits()
+      }{
+         One if the search was successful, otherwise zero.
+      }
+   }
+   \sstexamples{
+      \sstexamplesubsection{
+         result = astFindFits( fitschan, \texttt{"} \%f\texttt{"} , card, 1 );
+      }{
+         Returns the current card in a FitsChan and advances the Card
+         attribute to identify the card that follows (the \texttt{"} \%f\texttt{"}
+         template matches any keyword).
+      }
+      \sstexamplesubsection{
+         result = astFindFits( fitschan, \texttt{"} BITPIX\texttt{"} , card, 1 );
+      }{
+         Searches a FitsChan for a FITS card with the \texttt{"} BITPIX\texttt{"}  keyword
+         and returns that card. The Card attribute is then incremented
+         to identify the card that follows it.
+      }
+      \sstexamplesubsection{
+         result = astFindFits( fitschan, \texttt{"} COMMENT\texttt{"} , NULL, 0 );
+      }{
+         Sets the Card attribute of a FitsChan to identify the next
+         COMMENT card (if any). The card itself is not returned.
+      }
+      \sstexamplesubsection{
+         result = astFindFits( fitschan, \texttt{"} CRVAL\%1d\texttt{"} , card, 1 );
+      }{
+         Searches a FitsChan for the next card with a keyword of the
+         form \texttt{"} CRVALi\texttt{"}  (for example, any of the keywords \texttt{"} CRVAL1\texttt{"} ,
+         \texttt{"} CRVAL2\texttt{"}  or \texttt{"} CRVAL3\texttt{"}  would be matched). The card found (if
+         any) is returned, and the Card attribute is then incremented
+         to identify the following card (ready to search for another
+         keyword with the same form, perhaps).
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The search always starts with the current card, as identified
+         by the Card attribute. To ensure you search the entire contents
+         of a FitsChan, you should first clear the Card attribute (using
+         \htmlref{astClear}{astClear}). This effectively \texttt{"} rewinds\texttt{"}  the FitsChan.
+
+         \sstitem
+          If a search is unsuccessful, the Card attribute is set to the
+         \texttt{"} end-of-file\texttt{"}  (i.e. to one more than the number of cards in the
+         FitsChan). No error occurs.
+
+         \sstitem
+          A value of zero will be returned if this function is invoked
+         with the AST error status set, or if it should fail for any
+         reason.
+      }
+   }
+   \sstdiytopic{
+      Keyword Templates
+   }{
+      The templates used to match FITS keywords are normally composed
+      of literal characters, which must match the keyword exactly
+      (apart from case). However, a template may also contain \texttt{"} field
+      specifiers\texttt{"}  which can match a range of possible characters. This
+      allows you to search for keywords that contain (for example)
+      numbers, where the digits comprising the number are not known in
+      advance.
+
+      A field specifier starts with a \texttt{"} \%\texttt{"}  character. This is followed
+      by an optional single digit (0 to 9) specifying a field
+      width. Finally, there is a single character which specifies the
+
+      type of character to be matched, as follows:
+
+      \sstitemlist{
+
+         \sstitem
+          \texttt{"} c\texttt{"} : matches all upper case letters,
+
+         \sstitem
+          \texttt{"} d\texttt{"} : matches all decimal digits,
+
+         \sstitem
+          \texttt{"} f\texttt{"} : matches all characters which are permitted within a FITS
+         keyword (upper case letters, digits, underscores and hyphens).
+
+      }
+      If the field width is omitted, the field specifier matches one
+      or more characters. If the field width is zero, it matches zero
+      or more characters. Otherwise, it matches exactly the number of
+
+      characters specified. In addition to this:
+
+      \sstitemlist{
+
+         \sstitem
+          The template \texttt{"} \%f\texttt{"}  will match a blank FITS keyword consisting
+         of 8 spaces (as well as matching all other keywords).
+
+         \sstitem
+          A template consisting of 8 spaces will match a blank keyword
+         (only).
+
+      }
+      For example:
+
+      \sstitemlist{
+
+         \sstitem
+          The template \texttt{"} BitPix\texttt{"}  will match the keyword \texttt{"} BITPIX\texttt{"}  only.
+
+         \sstitem
+          The template \texttt{"} crpix\%1d\texttt{"}  will match keywords consisting of
+         \texttt{"} CRPIX\texttt{"}  followed by one decimal digit.
+
+         \sstitem
+          The template \texttt{"} P\%c\texttt{"}  will match any keyword starting with \texttt{"} P\texttt{"}
+         and followed by one or more letters.
+
+         \sstitem
+          The template \texttt{"} E\%0f\texttt{"}  will match any keyword beginning with \texttt{"} E\texttt{"} .
+
+         \sstitem
+          The template \texttt{"} \%f\texttt{"}  will match any keyword at all (including a
+         blank one).
+      }
+   }
+}
+\sstroutine{
+   astFindFrame
+}{
+   Find a coordinate system with specified characteristics
+}{
+   \sstdescription{
+      This function uses a \texttt{"} template\texttt{"}  \htmlref{Frame}{Frame} to search another Frame
+      (or \htmlref{FrameSet}{FrameSet}) to identify a coordinate system which has a
+      specified set of characteristics. If a suitable coordinate
+      system can be found, the function returns a pointer to a
+      FrameSet which describes the required coordinate system and how
+      to convert coordinates to and from it.
+
+      This function is provided to help answer general questions about
+      coordinate systems, such as typically arise when coordinate
+      information is imported into a program as part of an initially
+      unknown dataset. For example:
+      \sstitemlist{
+
+         \sstitem
+          Is there a wavelength scale?
+
+         \sstitem
+          Is there a 2-dimensional coordinate system?
+
+         \sstitem
+          Is there a celestial coordinate system?
+
+         \sstitem
+          Can I plot the data in ecliptic coordinates?
+
+      }
+      You can also use this function as a means of reconciling a
+      user\texttt{'} s preference for a particular coordinate system (for
+      example, what type of axes to draw) with what is actually
+      possible given the coordinate information available.
+
+      To perform a search, you supply a \texttt{"} target\texttt{"}  Frame (or FrameSet)
+      which represents the set of coordinate systems to be searched.
+      If a basic Frame is given as the target, this set of coordinate
+      systems consists of the one described by this Frame, plus all
+      other \texttt{"} virtual\texttt{"}  coordinate systems which can potentially be
+      reached from it by applying built-in conversions (for example,
+      any of the celestial coordinate conversions known to the AST
+      library would constitute a \texttt{"} built-in\texttt{"}  conversion). If a FrameSet
+      is given as the target, the set of coordinate systems to be
+      searched consists of the union of those represented by all the
+      individual Frames within it.
+
+      To select from this large set of possible coordinate systems,
+      you supply a \texttt{"} template\texttt{"}  Frame which is an instance of the type
+      of Frame you are looking for. Effectively, you then ask the
+      function to \texttt{"} find a coordinate system that looks like this\texttt{"} .
+
+      You can make your request more or less specific by setting
+      attribute values for the template Frame. If a particular
+      attribute is set in the template, then the function will only
+      find coordinate systems which have exactly the same value for
+      that attribute.  If you leave a template attribute un-set,
+      however, then the function has discretion about the value the
+      attribute should have in any coordinate system it finds. The
+      attribute will then take its value from one of the actual
+      (rather than virtual) coordinate systems in the target. If the
+      target is a FrameSet, its \htmlref{Current}{Current} attribute will be modified to
+      indicate which of its Frames was used for this purpose.
+
+      The result of this process is a coordinate system represented by
+      a hybrid Frame which acquires some attributes from the template
+      (but only if they were set) and the remainder from the
+      target. This represents the \texttt{"} best compromise\texttt{"}  between what you
+      asked for and what was available. A \htmlref{Mapping}{Mapping} is then generated
+      which converts from the target coordinate system to this hybrid
+      one, and the returned FrameSet encapsulates all of this
+      information.
+   }
+   \sstsynopsis{
+      AstFrameSet $*$astFindFrame( AstFrame $*$target, AstFrame $*$template,
+                                 const char $*$domainlist )
+   }
+   \sstparameters{
+      \sstsubsection{
+         target
+      }{
+         Pointer to the target Frame (or FrameSet).
+
+         Note that if a FrameSet is supplied (and a suitable
+         coordinate system is found), then its Current attribute will
+         be modified to indicate which Frame was used to obtain
+         attribute values which were not specified by the template.
+         This Frame will, in some sense, represent the \texttt{"} closest\texttt{"}
+         non-virtual coordinate system to the one you requested.
+      }
+      \sstsubsection{
+         template
+      }{
+         Pointer to the template Frame, which should be an instance of
+         the type of Frame you wish to find. If you wanted to find a
+         Frame describing a celestial coordinate system, for example,
+         then you might use a \htmlref{SkyFrame}{SkyFrame} here. See the \texttt{"} Examples\texttt{"}
+         section for more ideas.
+      }
+      \sstsubsection{
+         domainlist
+      }{
+         Pointer to a null-terminated character string containing a
+         comma-separated list of Frame domains. This may be used to
+         establish a priority order for the different types of
+         coordinate system that might be found.
+
+         The function will first try to find a suitable coordinate
+         system whose \htmlref{Domain}{Domain} attribute equals the first domain in this
+         list. If this fails, the second domain in the list will be
+         used, and so on, until a result is obtained. A blank domain
+         (e.g. two consecutive commas) indicates that any coordinate
+         system is acceptable (subject to the template) regardless of
+         its domain.
+
+         This list is case-insensitive and all white space is ignored.
+         If you do not wish to restrict the domain in this way,
+         you should supply an empty string.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Frame
+      }{
+         This function applies to all Frames.
+      }
+      \sstsubsection{
+         FrameSet
+      }{
+         If the target is a FrameSet, the possibility exists that
+         several of the Frames within it might be matched by the
+         template.  Unless the choice is sufficiently restricted by
+         the \texttt{"} domainlist\texttt{"}  string, the sequence in which Frames are
+         searched can then become important. In this case, the search
+         proceeds as follows:
+         \sstitemlist{
+
+            \sstitem
+             Each field in the \texttt{"} domainlist\texttt{"}  string is considered in turn.
+
+            \sstitem
+             An attempt is made to match the template to each of the
+            target\texttt{'} s Frames in the order: (1) the current Frame, (2) the
+            base Frame, (3) each remaining Frame in the order of being
+            added to the target FrameSet.
+
+            \sstitem
+             Generally, the first match found is used. However, the
+            Mapping between the target coordinate system and the
+            resulting Frame is also examined. Preference is given to
+            cases where both the forward and inverse transformations are
+            defined (as indicated by the \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse}
+            attributes). If only one transformation is defined, the
+            forward one is preferred.
+
+            \sstitem
+             If a match is found and the domain of the resulting Frame also
+            matches the current \texttt{"} domainlist\texttt{"}  field, it is
+            accepted. Otherwise, the next \texttt{"} domainlist\texttt{"}  field is considered
+            and the process repeated.
+
+         }
+         If a suitable coordinate system is found, the Current
+         attribute of the target FrameSet will be modified on exit to
+         identify the Frame whose match with the target was eventually
+         accepted.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astFindFrame()
+      }{
+         If the search is successful, the function returns a pointer
+         to a FrameSet which contains the Frame found and a
+         description of how to convert to (and from) the coordinate
+         system it represents. Otherwise, a null \htmlref{Object}{Object} pointer
+         (AST\_\_NULL) is returned without error.
+
+         If a FrameSet is returned, it will contain two Frames. Frame
+         number 1 (its base Frame) represents the target coordinate
+         system and will be the same as the (base Frame of the)
+         target. Frame number 2 (its current Frame) will be a Frame
+         representing the coordinate system which the function
+         found. The Mapping which inter-relates these two Frames will
+         describe how to convert between their respective coordinate
+         systems.
+
+         Note that a FrameSet may be used both as a Mapping and as a
+         Frame. If the result is used as a Mapping (e.g. with
+         \htmlref{astTran2}{astTran2}), then it provides a means of converting coordinates
+         from the target coordinate system into the new coordinate
+         system that was found (and vice versa if its inverse
+         transformation is selected). If it is used as a Frame, its
+         attributes will describe the new coordinate system.
+      }
+   }
+   \sstexamples{
+      \sstexamplesubsection{
+         result = astFindFrame( target, \htmlref{astFrame}{astFrame}( 3, \texttt{"} \texttt{"}  ), \texttt{"} \texttt{"}  );
+      }{
+         Searches for a 3-dimensional coordinate system in the target
+         Frame (or FrameSet). No attributes have been set in the
+         template Frame (created by astFrame), so no restriction has
+         been placed on the required coordinate system, other than
+         that it should have 3 dimensions. The first suitable Frame
+         found will be returned as part of the \texttt{"} result\texttt{"}  FrameSet.
+      }
+      \sstexamplesubsection{
+         result = astFindFrame( target, \htmlref{astSkyFrame}{astSkyFrame}( \texttt{"} \texttt{"}  ), \texttt{"} \texttt{"}  );
+      }{
+         Searches for a celestial coordinate system in the target
+         Frame (or FrameSet). The type of celestial coordinate system
+         is unspecified, so astFindFrame will return the first one
+         found as part of the \texttt{"} result\texttt{"}  FrameSet. If the target is
+         a FrameSet, then its Current attribute will be updated to
+         identify the Frame that was used.
+
+         If no celestial coordinate system can be found, a value of
+         AST\_\_NULL will be returned without error.
+      }
+      \sstexamplesubsection{
+         result = astFindFrame( target, astSkyFrame( \texttt{"} \htmlref{MaxAxes}{MaxAxes}=100\texttt{"}  ), \texttt{"} \texttt{"}  );
+      }{
+         This is like the last example, except that in the event of the
+         target being a \htmlref{CmpFrame}{CmpFrame}, the component Frames encapsulated by the
+         CmpFrame will be searched for a SkyFrame. If found, the returned
+         Mapping will included a \htmlref{PermMap}{PermMap} which selects the required axes
+         from the target CmpFrame.
+
+         This is acomplished by setting the MaxAxes attribute of the
+         template SkyFrame to a large number (larger than or equal to the
+         number of axes in the target CmpFrame). This allows the SkyFrame
+         to be used as a match for Frames containing from 2 to 100 axes.
+      }
+      \sstexamplesubsection{
+         result = astFindFrame( target, astSkyFrame( \texttt{"} \htmlref{System}{System}=FK5\texttt{"}  ), \texttt{"} \texttt{"}  );
+      }{
+         Searches for an equatorial (FK5) coordinate system in the
+         target. The \htmlref{Equinox}{Equinox} value for the coordinate system has not
+         been specified, so will be obtained from the target. If the
+         target is a FrameSet, its Current attribute will be updated
+         to indicate which SkyFrame was used to obtain this value.
+      }
+      \sstexamplesubsection{
+         result = astFindFrame( target, astFrame( 2, \texttt{"} \texttt{"}  ), \texttt{"} sky,pixel,\texttt{"}  );
+      }{
+         Searches for a 2-dimensional coordinate system in the
+         target. Initially, a search is made for a suitable coordinate
+         system whose Domain attribute has the value \texttt{"} SKY\texttt{"} . If this
+         search fails, a search is then made for one with the domain
+         \texttt{"} PIXEL\texttt{"} . If this also fails, then any 2-dimensional
+         coordinate system is returned as part of the \texttt{"} result\texttt{"}
+         FrameSet.
+
+         Only if no 2-dimensional coordinate systems can be reached by
+         applying built-in conversions to any of the Frames in the
+         target will a value of AST\_\_NULL be returned.
+      }
+      \sstexamplesubsection{
+         result = astFindFrame( target, astFrame( 1, \texttt{"} Domain=WAVELENGTH\texttt{"}  ), \texttt{"} \texttt{"}  );
+      }{
+         Searches for any 1-dimensional coordinate system in the
+         target which has the domain \texttt{"} WAVELENGTH\texttt{"} .
+      }
+      \sstexamplesubsection{
+         result = astFindFrame( target, astFrame( 1, \texttt{"} \texttt{"}  ), \texttt{"} wavelength\texttt{"}  );
+      }{
+         This example has exactly the same effect as that above. It
+         illustrates the equivalence of the template\texttt{'} s Domain attribute
+         and the fields in the \texttt{"} domainlist\texttt{"}  string.
+      }
+      \sstexamplesubsection{
+         result = astFindFrame( target, astFrame( 1, \texttt{"} MaxAxes=3\texttt{"}  ), \texttt{"} \texttt{"}  );
+      }{
+         This is a more advanced example which will search for any
+         coordinate system in the target having 1, 2 or 3
+         dimensions. The Frame returned (as part of the \texttt{"} result\texttt{"}
+         FrameSet) will always be 1-dimensional, but will be related
+         to the coordinate system that was found by a suitable Mapping
+         (e.g. a PermMap) which simply extracts the first axis.
+
+         If we had wanted a Frame representing the actual (1, 2 or
+         3-dimensional) coordinate system found, we could set the
+         \htmlref{PreserveAxes}{PreserveAxes} attribute to a non-zero value in the template.
+      }
+      \sstexamplesubsection{
+         result = astFindFrame( target, astSkyFrame( \texttt{"} \htmlref{Permute}{Permute}=0\texttt{"}  ), \texttt{"} \texttt{"}  );
+      }{
+         Searches for any celestial coordinate system in the target,
+         but only finds one if its axes are in the conventional
+         (longitude,latitude) order and have not been permuted
+         (e.g. with \htmlref{astPermAxes}{astPermAxes}).
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The Mapping represented by the returned FrameSet results in
+         alignment taking place in the coordinate system specified by the
+         \htmlref{AlignSystem}{AlignSystem} attribute of the \texttt{"} template\texttt{"}  Frame. See the description
+         of the AlignSystem attribute for further details.
+
+         \sstitem
+          Beware of setting the Domain attribute of the template and then
+         using a \texttt{"} domainlist\texttt{"}  string which does not include the template\texttt{'} s domain
+         (or a blank field). If you do so, no coordinate system will be
+         found.
+
+         \sstitem
+          A null Object pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      More on Using Templates
+   }{
+      A Frame (describing a coordinate system) will be found by this
+      function if (a) it is \texttt{"} matched\texttt{"}  by the template you supply, and
+      (b) the value of its Domain attribute appears in the \texttt{"} domainlist\texttt{"}
+      string (except that a blank field in this string permits any
+      domain). A successful match by the template depends on a number
+      of criteria, as outlined below:
+      \sstitemlist{
+
+         \sstitem
+          In general, a template will only match another Frame which
+         belongs to the same class as the template, or to a derived (more
+         specialised) class. For example, a SkyFrame template will match
+         any other SkyFrame, but will not match a basic
+         Frame. Conversely, a basic Frame template will match any class
+         of Frame.
+
+         \sstitem
+          The exception to this is that a Frame of any class can be used to
+         match a CmpFrame, if that CmpFrame contains a Frame of the same
+         class as the template. Note however, the MaxAxes and \htmlref{MinAxes}{MinAxes}
+         attributes of the template must be set to suitable values to allow
+         it to match the CmpFrame. That is, the MinAxes attribute must be
+         less than or equal to the number of axes in the target, and the MaxAxes
+         attribute must be greater than or equal to the number of axes in
+         the target.
+
+         \sstitem
+          If using a CmpFrame as a template frame, the MinAxes and MaxAxes
+         for the template are determined by the MinAxes and MaxAxes values of
+         the component Frames within the template. So if you want a template
+         CmpFrame to be able to match Frames with different numbers of axes,
+         then you must set the MaxAxes and/or MinAxes attributes in the component
+         template Frames, before combining them together into the template
+         CmpFrame.
+
+         \sstitem
+          If a template has a value set for any of its main attributes, then
+         it will only match Frames which have an identical value for that
+         attribute (or which can be transformed, using a built-in
+         conversion, so that they have the required value for that
+         attribute). If any attribute in the template is un-set, however,
+         then Frames are matched regardless of the value they may have
+         for that attribute. You may therefore make a template more or
+         less specific by choosing the attributes for which you set
+         values. This requirement does not apply to \texttt{'} descriptive\texttt{'}  attributes
+         such as titles, labels, symbols, etc.
+
+         \sstitem
+          An important application of this principle involves the Domain
+         attribute. Setting the Domain attribute of the template has the
+         effect of restricting the search to a particular type of Frame
+         (with the domain you specify).  Conversely, if the Domain
+         attribute is not set in the template, then the domain of the
+         Frame found is not relevant, so all Frames are searched.  Note
+         that the
+         \texttt{"} domainlist\texttt{"}  string provides an alternative way of restricting the
+         search in the same manner, but is a more convenient interface if
+         you wish to search automatically for another domain if the first
+         search fails.
+
+         \sstitem
+          Normally, a template will only match a Frame which has the
+         same number of axes as itself. However, for some classes of
+         template, this default behaviour may be changed by means of the
+         MinAxes, MaxAxes and \htmlref{MatchEnd}{MatchEnd} attributes. In addition, the
+         behaviour of a template may be influenced by its Permute and
+         PreserveAxes attributes, which control whether it matches Frames
+         whose axes have been permuted, and whether this permutation is
+         retained in the Frame which is returned (as opposed to returning
+         the axes in the order specified in the template, which is the
+         default behaviour). You should consult the descriptions of these
+         attributes for details of this more advanced use of templates.
+      }
+   }
+}
+\sstroutine{
+   astFitsChan
+}{
+   Create a FitsChan
+}{
+   \sstdescription{
+      This function creates a new \htmlref{FitsChan}{FitsChan} and optionally initialises
+      its attributes.
+
+      A FitsChan is a specialised form of \htmlref{Channel}{Channel} which supports I/O
+      operations involving the use of FITS (Flexible Image Transport
+      \htmlref{System}{System}) header cards. Writing an \htmlref{Object}{Object} to a FitsChan (using
+      \htmlref{astWrite}{astWrite}) will, if the Object is suitable, generate a
+      description of that Object composed of FITS header cards, and
+      reading from a FitsChan will create a new Object from its FITS
+      header card description.
+
+      While a FitsChan is active, it represents a buffer which may
+      contain zero or more 80-character \texttt{"} header cards\texttt{"}  conforming to
+      FITS conventions. Any sequence of FITS-conforming header cards
+      may be stored, apart from the \texttt{"} END\texttt{"}  card whose existence is
+      merely implied.  The cards may be accessed in any order by using
+      the FitsChan\texttt{'} s integer \htmlref{Card}{Card} attribute, which identifies a \texttt{"} current\texttt{"}
+      card, to which subsequent operations apply. Searches
+      based on keyword may be performed (using \htmlref{astFindFits}{astFindFits}), new
+      cards may be inserted (\htmlref{astPutFits}{astPutFits}, \htmlref{astPutCards}{astPutCards}, \htmlref{astSetFits$<$X$>$}{astSetFits$<$X$>$}) and
+      existing ones may be deleted (\htmlref{astDelFits}{astDelFits}) or changed (astSetFits$<$X$>$).
+
+      When you create a FitsChan, you have the option of specifying
+      \texttt{"} source\texttt{"}  and \texttt{"} sink\texttt{"}  functions which connect it to external data
+      stores by reading and writing FITS header cards. If you provide
+      a source function, it is used to fill the FitsChan with header cards
+      when it is accessed for the first time. If you do not provide a
+      source function, the FitsChan remains empty until you explicitly enter
+      data into it (e.g. using astPutFits, astPutCards, astWrite
+      or by using the \htmlref{SourceFile}{SourceFile} attribute to specifying a text file from
+      which headers should be read). When the FitsChan is deleted, any
+      remaining header cards in the FitsChan can be saved in either of
+      two ways: 1) by specifying a value for the \htmlref{SinkFile}{SinkFile} attribute (the
+      name of a text file to which header cards should be written), or 2)
+      by providing a sink function (used to to deliver header cards to an
+      external data store). If you do not provide a sink function or a
+      value for SinkFile, any header cards remaining when the FitsChan
+      is deleted will be lost, so you should arrange to extract them
+      first if necessary
+      (e.g. using astFindFits or \htmlref{astRead}{astRead}).
+
+      Coordinate system information may be described using FITS header
+      cards using several different conventions, termed
+      \texttt{"} encodings\texttt{"} . When an AST Object is written to (or read from) a
+      FitsChan, the value of the FitsChan\texttt{'} s \htmlref{Encoding}{Encoding} attribute
+      determines how the Object is converted to (or from) a
+      description involving FITS header cards. In general, different
+      encodings will result in different sets of header cards to
+      describe the same Object. Examples of encodings include the DSS
+      encoding (based on conventions used by the STScI Digitised Sky
+      Survey data), the FITS-WCS encoding (based on a proposed FITS
+      standard) and the NATIVE encoding (a near loss-less way of
+      storing AST Objects in FITS headers).
+
+      The available encodings differ in the range of Objects they can
+      represent, in the number of Object descriptions that can coexist
+      in the same FitsChan, and in their accessibility to other
+      (external) astronomy applications (see the Encoding attribute
+      for details). Encodings are not necessarily mutually exclusive
+      and it may sometimes be possible to describe the same Object in
+      several ways within a particular set of FITS header cards by
+      using several different encodings.
+
+      The detailed behaviour of astRead and astWrite, when used with
+      a FitsChan, depends on the encoding in use. In general, however,
+      all use of astRead is destructive, so that FITS header cards
+      are consumed in the process of reading an Object, and are
+      removed from the FitsChan (this deletion can be prevented for
+      specific cards by calling the
+      \htmlref{astRetainFits}{astRetainFits} function).
+
+      If the encoding in use allows only a single Object description
+      to be stored in a FitsChan (e.g. the DSS, FITS-WCS and FITS-IRAF
+      encodings), then write operations using astWrite will
+      over-write any existing Object description using that
+      encoding. Otherwise (e.g. the NATIVE encoding), multiple Object
+      descriptions are written sequentially and may later be read
+      back in the same sequence.
+   }
+   \sstsynopsis{
+      AstFitsChan $*$astFitsChan( const char $*$($*$ source)( void ),
+                                void ($*$ sink)( const char $*$ ),
+                                const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         source
+      }{
+         Pointer to a source function which takes no arguments and
+         returns a pointer to a null-terminated string. This function
+         will be used by the FitsChan to obtain input FITS header
+         cards. On each invocation, it should read the next input card
+         from some external source (such as a FITS file), and return a
+         pointer to the (null-terminated) contents of the card. It
+         should return a NULL pointer when there are no more cards to
+         be read.
+
+         If \texttt{"} source\texttt{"}  is NULL, the FitsChan will remain empty until
+         cards are explicitly stored in it (e.g. using astPutCards,
+         astPutFits or via the SourceFile attribute).
+      }
+      \sstsubsection{
+         sink
+      }{
+         Pointer to a sink function that takes a pointer to a
+         null-terminated string as an argument and returns void.  If
+         no value has been set for the SinkFile attribute, this
+         function will be used by the FitsChan to deliver any FITS
+         header cards it contains when it is finally deleted. On
+         each invocation, it should deliver the contents of the character
+         string passed to it as a FITS header card to some external
+         data store (such as a FITS file).
+
+         If \texttt{"} sink\texttt{"}  is NULL,
+         and no value has been set for the SinkFile attribute, the
+         contents of the FitsChan will be lost when it is deleted.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new FitsChan. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+
+         Note, the FITSCHAN\_OPTIONS environment variable may be used
+         to specify default options for all newly created FitsChans.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astFitsChan()
+      }{
+         A pointer to the new FitsChan.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          No FITS \texttt{"} END\texttt{"}  card will be written via the sink function. You
+         should add this card yourself after the FitsChan has been
+         deleted.
+
+         \sstitem
+          A null Object pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      Status Handling
+   }{
+      The protected interface to this function includes an extra
+      parameter at the end of the parameter list descirbed above. This
+      parameter is a pointer to the integer inherited status
+      variable: \texttt{"} int $*$status\texttt{"} .
+   }
+}
+\sstroutine{
+   astFitsTable
+}{
+   Create a FitsTable
+}{
+   \sstdescription{
+      This function creates a new \htmlref{FitsTable}{FitsTable} and optionally initialises
+      its attributes.
+
+      The FitsTable class is a representation of a FITS binary table. It
+      inherits from the \htmlref{Table}{Table} class. The parent Table is used to hold the
+      binary data of the main table, and a \htmlref{FitsChan}{FitsChan} is used to hold the FITS
+      header. Note, there is no provision for binary data following the main
+      table (such data is referred to as a \texttt{"} heap\texttt{"}  in the FITS standard).
+
+      Note - it is not recommended to use the FitsTable class to store
+      very large tables.
+   }
+   \sstsynopsis{
+      AstFitsTable $*$astFitsTable( AstFitsChan $*$header, const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         header
+      }{
+         Pointer to an optional FitsChan containing headers to be stored
+         in the FitsTable.
+         NULL
+         may be supplied if the new FitsTable is to be left empty. If
+         supplied, and if the headers describe columns of a FITS binary
+         table, then equivalent (empty) columns are added to the FitsTable.
+         Each column has the same index in the FitsTable that it has in
+         the supplied header.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new FitsTable. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astFitsTable()
+      }{
+         A pointer to the new FitsTable.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      Status Handling
+   }{
+      The protected interface to this function includes an extra
+      parameter at the end of the parameter list described above. This
+      parameter is a pointer to the integer inherited status
+      variable: \texttt{"} int $*$status\texttt{"} .
+   }
+}
+\sstroutine{
+   astFluxFrame
+}{
+   Create a FluxFrame
+}{
+   \sstdescription{
+      This function creates a new \htmlref{FluxFrame}{FluxFrame} and optionally initialises
+      its attributes.
+
+      A FluxFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which
+      represents various systems used to represent the signal level in an
+      observation. The particular coordinate system to be used is specified
+      by setting the FluxFrame\texttt{'} s \htmlref{System}{System} attribute qualified, as necessary, by
+      other attributes such as the units, etc (see the description of the
+      System attribute for details).
+
+      All flux values are assumed to be measured at the same frequency or
+      wavelength (as given by the \htmlref{SpecVal}{SpecVal} attribute). Thus this class is
+      more appropriate for use with images rather than spectra.
+   }
+   \sstsynopsis{
+      AstFluxFrame $*$astFluxFrame( double specval, AstSpecFrame $*$specfrm,
+                                  const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         specval
+      }{
+         The spectral value to which the flux values refer, given in the
+         spectral coordinate system specified by
+         \texttt{"} specfrm\texttt{"} . The value supplied for the \texttt{"} specval\texttt{"}
+         parameter becomes the default value for the SpecVal attribute.
+         A value of AST\_\_BAD may be supplied if the spectral position is
+         unknown, but this may result in it not being possible for the
+         \htmlref{astConvert}{astConvert}
+         function to determine a \htmlref{Mapping}{Mapping} between the new FluxFrame and
+         some other FluxFrame.
+      }
+      \sstsubsection{
+         specfrm
+      }{
+         A pointer to a \htmlref{SpecFrame}{SpecFrame} describing the spectral coordinate system
+         in which the
+         \texttt{"} specval\texttt{"}
+         parameter is given. A deep copy of this object is taken, so any
+         subsequent changes to the SpecFrame using the supplied pointer will
+         have no effect on the new FluxFrame.
+         A NULL pointer can be supplied if AST\_\_BAD is supplied for \texttt{"} specval\texttt{"} .
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new FluxFrame. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+         If no initialisation is required, a zero-length string may be
+         supplied.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astFluxFrame()
+      }{
+         A pointer to the new FluxFrame.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          When conversion between two FluxFrames is requested (as when
+         supplying FluxFrames to astConvert),
+         account will be taken of the nature of the flux coordinate systems
+         they represent, together with any qualifying attribute values, including
+         the \htmlref{AlignSystem}{AlignSystem} attribute. The results will therefore fully reflect the
+         relationship between positions measured in the two systems. In addition,
+         any difference in the Unit attributes of the two systems will also be
+         taken into account.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astFormat
+}{
+   Format a coordinate value for a Frame axis
+}{
+   \sstdescription{
+      This function returns a pointer to a string containing the
+      formatted (character) version of a coordinate value for a \htmlref{Frame}{Frame}
+      axis. The formatting applied is determined by the Frame\texttt{'} s
+      attributes and, in particular, by any Format attribute string
+      that has been set for the axis. A suitable default format (based
+      on the Digits attribute value) will be applied if necessary.
+   }
+   \sstsynopsis{
+      const char $*$astFormat( AstFrame $*$this, int axis, double value )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Frame.
+      }
+      \sstsubsection{
+         axis
+      }{
+         The number of the Frame axis for which formatting is to be
+         performed (axis numbering starts at 1 for the first axis).
+      }
+      \sstsubsection{
+         value
+      }{
+         The coordinate value to be formatted.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astFormat()
+      }{
+         A pointer to a null-terminated string containing the formatted
+         value.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The returned pointer is guaranteed to remain valid and the
+         string to which it points will not be over-written for a total
+         of 50 successive invocations of this function. After this, the
+         memory containing the string may be re-used, so a copy of the
+         string should be made if it is needed for longer than this.
+
+         \sstitem
+          A formatted value may be converted back into a numerical (double)
+         value using \htmlref{astUnformat}{astUnformat}.
+
+         \sstitem
+          A NULL pointer will be returned if this function is invoked
+         with the AST error status set, or if it should fail for any
+         reason.
+      }
+   }
+}
+\sstroutine{
+   astFrame
+}{
+   Create a Frame
+}{
+   \sstdescription{
+      This function creates a new \htmlref{Frame}{Frame} and optionally initialises its
+      attributes.
+
+      A Frame is used to represent a coordinate system. It does this
+      in rather the same way that a frame around a graph describes the
+      coordinate space in which data are plotted. Consequently, a
+      Frame has a \htmlref{Title}{Title} (string) attribute, which describes the
+      coordinate space, and contains axes which in turn hold
+      information such as Label and Units strings which are used for
+      labelling (e.g.) graphical output. In general, however, the
+      number of axes is not restricted to two.
+
+      Functions are available for converting Frame coordinate values
+      into a form suitable for display, and also for calculating
+      distances and offsets between positions within the Frame.
+
+      Frames may also contain knowledge of how to transform to and
+      from related coordinate systems.
+   }
+   \sstsynopsis{
+      AstFrame $*$astFrame( int naxes, const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         naxes
+      }{
+         The number of Frame axes (i.e. the number of dimensions of
+         the coordinate space which the Frame describes).
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new Frame. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+         If no initialisation is required, a zero-length string may be
+         supplied.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astFrame()
+      }{
+         A pointer to the new Frame.
+      }
+   }
+   \sstexamples{
+      \sstexamplesubsection{
+         frame = astFrame( 2, \texttt{"} Title=Energy Spectrum: \htmlref{Plot}{Plot} \%d\texttt{"} , n );
+      }{
+         Creates a new 2-dimensional Frame and initialises its Title
+         attribute to the string \texttt{"} Energy Spectrum: Plot $<$n$>$\texttt{"} , where
+         $<$n$>$ takes the value of the int variable \texttt{"} n\texttt{"} .
+      }
+      \sstexamplesubsection{
+         frame = astFrame( 2, \texttt{"} Label(1)=Energy, Label(2)=Response\texttt{"}  );
+      }{
+         Creates a new 2-dimensional Frame and initialises its axis
+         Label attributes to suitable string values.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astFrameSet
+}{
+   Create a FrameSet
+}{
+   \sstdescription{
+      This function creates a new \htmlref{FrameSet}{FrameSet} and optionally initialises
+      its attributes.
+
+      A FrameSet consists of a set of one or more Frames (which
+      describe coordinate systems), connected together by Mappings
+      (which describe how the coordinate systems are inter-related). A
+      FrameSet makes it possible to obtain a \htmlref{Mapping}{Mapping} between any pair
+      of these Frames (i.e. to convert between any of the coordinate
+      systems which it describes).  The individual Frames are
+      identified within the FrameSet by an integer index, with Frames
+      being numbered consecutively from one as they are added to the
+      FrameSet.
+
+      Every FrameSet has a \texttt{"} base\texttt{"}  \htmlref{Frame}{Frame} and a \texttt{"} current\texttt{"}  Frame (which
+      are allowed to be the same). Any of the Frames may be nominated
+      to hold these positions, and the choice is determined by the
+      values of the FrameSet\texttt{'} s \htmlref{Base}{Base} and \htmlref{Current}{Current} attributes, which hold
+      the indices of the relevant Frames.  By default, the first Frame
+      added to a FrameSet is its base Frame, and the last one added is
+      its current Frame.
+
+      The base Frame describes the \texttt{"} native\texttt{"}  coordinate system of
+      whatever the FrameSet is used to calibrate (e.g. the pixel
+      coordinates of an image) and the current Frame describes the
+      \texttt{"} apparent\texttt{"}  coordinate system in which it should be viewed
+      (e.g. displayed, etc.). Any further Frames represent a library
+      of alternative coordinate systems, which may be selected by
+      making them current.
+
+      When a FrameSet is used in a context that requires a Frame,
+      (e.g. obtaining its \htmlref{Title}{Title} value, or number of axes), the current
+      Frame is used. A FrameSet may therefore be used in place of its
+      current Frame in most situations.
+
+      When a FrameSet is used in a context that requires a Mapping,
+      the Mapping used is the one between its base Frame and its
+      current Frame. Thus, a FrameSet may be used to convert \texttt{"} native\texttt{"}
+      coordinates into \texttt{"} apparent\texttt{"}  ones, and vice versa. Like any
+      Mapping, a FrameSet may also be inverted (see \htmlref{astInvert}{astInvert}), which
+      has the effect of interchanging its base and current Frames and
+      hence of reversing the Mapping between them.
+
+      Regions may be added into a FrameSet (since a \htmlref{Region}{Region} is a type of
+      Frame), either explicitly or as components within CmpFrames. In this
+      case the Mapping between a pair of Frames within a FrameSet will
+      include the effects of the clipping produced by any Regions included
+      in the path between the Frames.
+   }
+   \sstsynopsis{
+      AstFrameSet $*$astFrameSet( AstFrame $*$frame, const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         frame
+      }{
+         Pointer to the first Frame to be inserted into the
+         FrameSet. This initially becomes both the base and the
+         current Frame. (Further Frames may be added using the
+         \htmlref{astAddFrame}{astAddFrame} function.)
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new FrameSet. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+         If no initialisation is required, a zero-length string may be
+         supplied.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astFrameSet()
+      }{
+         A pointer to the new FrameSet.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If a pointer to an existing FrameSet is given for the \texttt{"} frame\texttt{"}
+         parameter, then the new FrameSet will (as a special case) be
+         initialised to contain the same Frames and Mappings, and to have
+         the same attribute values, as the one supplied. This process is
+         similar to making a copy of a FrameSet (see \htmlref{astCopy}{astCopy}), except
+         that the Frames and Mappings contained in the original are not
+         themselves copied, but are shared by both FrameSets.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astFromString
+}{
+   Re-create an Object from an in-memory serialisation
+}{
+   \sstdescription{
+      This function returns a pointer to a new \htmlref{Object}{Object} created from the
+      supplied text string, which should have been created by \htmlref{astToString}{astToString}.
+   }
+   \sstsynopsis{
+      AstObject $*$astFromString( const char $*$string )
+   }
+   \sstparameters{
+      \sstsubsection{
+         string
+      }{
+         Pointer to a text string holding an Object serialisation created
+         previously by astToString.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astFromString()
+      }{
+         Pointer to a new Object created from the supplied serialisation,
+         or NULL if the serialisation was invalid, or an error occurred.
+      }
+   }
+}
+\sstroutine{
+   astGenCurve
+}{
+   Draw a generalized curve
+}{
+   \sstdescription{
+      This function draws a general user-defined curve defined by the
+      supplied \htmlref{Mapping}{Mapping}. Note that the curve is transformed into graphical
+      coordinate space for plotting, so that a straight line in
+      physical coordinates may result in a curved line being drawn if
+      the Mapping involved is non-linear. Any discontinuities in the
+      Mapping between physical and graphical coordinates are
+      catered for, as is any clipping established using \htmlref{astClip}{astClip}.
+
+      If you need to draw simple straight lines (geodesics), \htmlref{astCurve}{astCurve}
+      or \htmlref{astPolyCurve}{astPolyCurve} will usually be easier to use and faster.
+   }
+   \sstsynopsis{
+      void astGenCurve( AstPlot $*$this, astMapping $*$map )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the \htmlref{Plot}{Plot}.
+      }
+      \sstsubsection{
+         map
+      }{
+         Pointer to a Mapping. This Mapping should have 1 input
+         coordinate representing offset along the required curve,
+         normalized so that the start of the curve is at offset 0.0,
+         and the end of the curve is at offset 1.0. Note, this offset
+         does not need to be linearly related to distance along the curve.
+         The number of output coordinates should equal the number of axes
+         in the current \htmlref{Frame}{Frame} of the Plot. The Mapping should map a
+         specified offset along the curve, into the corresponding
+         coordinates in the current Frame of the Plot. The inverse
+         transformation need not be defined.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          An error results if the base Frame of the Plot is not 2-dimensional.
+
+         \sstitem
+          An error also results if the transformation between the
+         current and base Frames of the Plot is not defined (i.e. the
+         Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero).
+      }
+   }
+}
+\sstroutine{
+   astGet$<$X$>$
+}{
+   Get an attribute value for an Object
+}{
+   \sstdescription{
+      This is a family of functions which return a specified attribute
+      value for an \htmlref{Object}{Object} using one of several different data
+      types. The type is selected by replacing $<$X$>$ in the function name
+      by C, D, F, I or L, to obtain a result in const char$*$ (i.e. string),
+      double, float, int, or long format, respectively.
+
+      If possible, the attribute value is converted to the type you
+      request. If conversion is not possible, an error will result.
+   }
+   \sstsynopsis{
+      $<$X$>$type astGet$<$X$>$( AstObject $*$this, const char $*$attrib )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Object.
+      }
+      \sstsubsection{
+         attrib
+      }{
+         Pointer to a null-terminated string containing the name of
+         the attribute whose value is required.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         These functions apply to all Objects.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astGet$<$X$>$()
+      }{
+         The attribute value, in the data type corresponding to $<$X$>$ (or,
+         in the case of astGetC, a pointer to a constant null-terminated
+         character string containing this value).
+      }
+   }
+   \sstexamples{
+      \sstexamplesubsection{
+         printf( \texttt{"} \htmlref{RefCount}{RefCount} = \%d$\backslash$n\texttt{"} , astGetI( z, \texttt{"} RefCount\texttt{"}  ) );
+      }{
+         Prints the RefCount attribute value for Object \texttt{"} z\texttt{"}  as an int.
+      }
+      \sstexamplesubsection{
+         title = astGetC( axis, \texttt{"} \htmlref{Title}{Title}\texttt{"}  );
+      }{
+         Obtains a pointer to a null-terminated character string containing
+         the Title attribute of Object \texttt{"} axis\texttt{"} .
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Attribute names are not case sensitive and may be surrounded
+         by white space.
+
+         \sstitem
+          An appropriate \texttt{"} null\texttt{"}  value will be returned if this function
+         is invoked with the AST error status set, or if it should
+         fail for any reason. This null value is zero for numeric
+         values and NULL for pointer values.
+
+         \sstitem
+          The pointer returned by astGetC is guaranteed to remain valid
+         and the string to which it points will not be over-written for a
+         total of 50 successive invocations of this function. After this,
+         the memory containing the string may be re-used, so a copy of
+         the string should be made if it is needed for longer than this.
+      }
+   }
+}
+\sstroutine{
+   astGetActiveUnit
+}{
+   Determines how the Unit attribute will be used
+}{
+   \sstdescription{
+      This function
+      returns the current value of the ActiveUnit flag for a \htmlref{Frame}{Frame}. See
+      the description of the \htmlref{astSetActiveUnit}{astSetActiveUnit} function
+      for a description of the ActiveUnit flag.
+   }
+   \sstsynopsis{
+      int astGetActiveUnit( AstFrame $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Frame.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astGetActiveUnit
+      }{
+         The current value of the ActiveUnit flag.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A zero value will be returned if this function is
+         invoked with the AST error status set, or if it should fail for
+         any reason.
+      }
+   }
+}
+\sstroutine{
+   astGetColumnData
+}{
+   Retrieve all the data values stored in a column
+}{
+   \sstdescription{
+      This function
+      copies all data values from a named column into a supplied buffer
+   }
+   \sstsynopsis{
+      void astGetColumnData( AstFitsTable $*$this, const char $*$column,
+                             float fnull, double dnull, size\_t mxsize,
+                             void $*$coldata, int $*$nelem )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the \htmlref{FitsTable}{FitsTable}.
+      }
+      \sstsubsection{
+         column
+      }{
+         The character string holding the name of the column. Trailing
+         spaces are ignored.
+      }
+      \sstsubsection{
+         fnull
+      }{
+         The value to return in
+         \texttt{"} coldata\texttt{"}
+         for any cells for which no value has been stored in the
+         FitsTable. Ignored if the column\texttt{'} s data type is not
+         AST\_\_FLOATTYPE. Supplying
+         AST\_\_NANF
+         will cause a single precision IEEE NaN value to be used.
+      }
+      \sstsubsection{
+         dnull
+      }{
+         The value to return in
+         \texttt{"} coldata\texttt{"}
+         for any cells for which no value has been stored in the
+         FitsTable. Ignored if the column\texttt{'} s data type is not
+         AST\_\_DOUBLETYPE. Supplying AST\_\_NAN will cause a double precision
+         IEEE NaN value to be used.
+      }
+      \sstsubsection{
+         mxsize
+      }{
+         The size of the
+         \texttt{"} coldata\texttt{"}
+         array, in bytes. The amount of memory needed to hold the data
+         from a column may be determined using
+         \htmlref{astColumnSize}{astColumnSize}.
+         If the supplied array is too small to hold all the column data,
+         trailing column values will be omitted from the returned array,
+         but no error will be reported.
+      }
+      \sstsubsection{
+         coldata
+      }{
+         A pointer to an
+         area of memory in which to return the data
+         values currently stored in the column. The values are stored in
+         row order. If the column holds non-scalar values, the elements
+         of each value are stored in \texttt{"} Fortran\texttt{"}  order. No data type
+         conversion is performed - the data type of each returned value
+         is the data type associated with the column when the column was
+         added to the table. If the column holds strings, the returned
+         strings will be null terminated. Any excess room at the end of
+         the array will be left unchanged.
+      }
+      \sstsubsection{
+         nelem
+      }{
+         The number of elements returned in the
+         \texttt{"} coldata\texttt{"}
+         array. This is the product of the number of rows returned and
+         the number of elements in each column value.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The \texttt{"} fnull\texttt{"}  and \texttt{"} dnull\texttt{"}  parameters
+         specify the value to be returned for any empty cells within columns
+         holding floating point values. For columns holding integer values,
+         the value returned for empty cells is the value returned by the
+         astColumNull function.
+         For columns holding string values, the ASCII NULL character is returned
+         for empty cells.
+      }
+   }
+}
+\sstroutine{
+   astGetFits$<$X$>$
+}{
+   Get a named keyword value from a FitsChan
+}{
+   \sstdescription{
+      This is a family of functions which gets a value for a named keyword,
+      or the value of the current card, from a \htmlref{FitsChan}{FitsChan} using one of several
+      different data types. The data type of the returned value is selected
+      by replacing $<$X$>$ in the function name by one of the following strings
+      representing the recognised FITS data types:
+
+      \sstitemlist{
+
+         \sstitem
+          CF - Complex floating point values.
+
+         \sstitem
+          CI - Complex integer values.
+
+         \sstitem
+          F  - Floating point values.
+
+         \sstitem
+          I  - Integer values.
+
+         \sstitem
+          L  - Logical (i.e. boolean) values.
+
+         \sstitem
+          S  - String values.
+
+         \sstitem
+          CN - A \texttt{"} CONTINUE\texttt{"}  value, these are treated like string values, but
+                are encoded without an equals sign.
+
+      }
+      The data type of the \texttt{"} value\texttt{"}
+      parameter
+
+      depends on $<$X$>$ as follows:
+
+      \sstitemlist{
+
+         \sstitem
+          CF - \texttt{"} double $*$\texttt{"}  (a pointer to a 2 element array to hold the real and
+                imaginary parts of the complex value).
+
+         \sstitem
+          CI - \texttt{"} int $*$\texttt{"}  (a pointer to a 2 element array to hold the real and
+                imaginary parts of the complex value).
+
+         \sstitem
+          F  - \texttt{"} double $*$\texttt{"} .
+
+         \sstitem
+          I  - \texttt{"} int $*$\texttt{"} .
+
+         \sstitem
+          L  - \texttt{"} int $*$\texttt{"} .
+
+         \sstitem
+          S  - \texttt{"} char $*$$*$\texttt{"}  (a pointer to a static \texttt{"} char\texttt{"}  array is returned at the
+                location given by the \texttt{"} value\texttt{"}  parameter, Note, the stored string
+                may change on subsequent invocations of astGetFitsS so a
+                permanent copy should be taken of the string if necessary).
+
+         \sstitem
+          CN - Like\texttt{"} S\texttt{"} .
+      }
+   }
+   \sstsynopsis{
+      int astGetFits$<$X$>$( AstFitsChan $*$this, const char $*$name, $<$X$>$type $*$value )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FitsChan.
+      }
+      \sstsubsection{
+         name
+      }{
+         Pointer to a null-terminated character string
+         containing the FITS keyword name. This may be a complete FITS
+         header card, in which case the keyword to use is extracted from
+         it. No more than 80 characters are read from this string. If
+         NULL
+         is supplied, the value of the current card is returned.
+      }
+      \sstsubsection{
+         value
+      }{
+         A pointer to a
+         buffer to receive the keyword value. The data type depends on $<$X$>$
+         as described above. The conents of the buffer on entry are left
+         unchanged if the keyword is not found.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astGetFits$<$X$>$$<$X$>$()
+      }{
+         A value of zero
+         is returned if the keyword was not found in the FitsChan (no error
+         is reported). Otherwise, a value of
+         one
+         is returned.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If a name is supplied, the card following the current card is
+         checked first. If this is not the required card, then the rest of the
+         FitsChan is searched, starting with the first card added to the
+         FitsChan. Therefore cards should be accessed in the order they are
+         stored in the FitsChan (if possible) as this will minimise the time
+         spent searching for cards.
+
+         \sstitem
+          If the requested card is found, it becomes the current card,
+         otherwise the current card is left pointing at the \texttt{"} end-of-file\texttt{"} .
+
+         \sstitem
+          If the stored keyword value is not of the requested type, it is
+         converted into the requested type.
+
+         \sstitem
+          If the keyword is found in the FitsChan, but has no associated
+         value, an error is reported. If necessary, the
+         \htmlref{astTestFits}{astTestFits}
+         function can be used to determine if the keyword has a defined
+         value in the FitsChan prior to calling this function.
+
+         \sstitem
+          An error will be reported if the keyword name does not conform
+         to FITS requirements.
+
+         \sstitem
+          Zero
+
+         \sstitem
+          .FALSE.
+         is returned as the function value if an error has already occurred,
+         or if this function should fail for any reason.
+
+         \sstitem
+          The FITS standard says that string keyword values should be
+         padded with trailing spaces if they are shorter than 8 characters.
+         For this reason, trailing spaces are removed from the string
+         returned by
+         astGetFitsS
+         if the original string (including any trailing spaces) contains 8
+         or fewer characters. Trailing spaces are not removed from longer
+         strings.
+      }
+   }
+}
+\sstroutine{
+   astGetFrame
+}{
+   Obtain a pointer to a specified Frame in a FrameSet
+}{
+   \sstdescription{
+      This function returns a pointer to a specified \htmlref{Frame}{Frame} in a
+      \htmlref{FrameSet}{FrameSet}.
+   }
+   \sstsynopsis{
+      AstFrame $*$astGetFrame( AstFrameSet $*$this, int iframe )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FrameSet.
+      }
+      \sstsubsection{
+         iframe
+      }{
+         The index of the required Frame within the FrameSet.  This
+         value should lie in the range from 1 to the number of Frames
+         in the FrameSet (as given by its \htmlref{Nframe}{Nframe} attribute).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astGetFrame()
+      }{
+         A pointer to the requested Frame.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A value of AST\_\_BASE or AST\_\_CURRENT may be given for the
+         \texttt{"} iframe\texttt{"}  parameter to specify the base Frame or the current
+         Frame respectively.
+
+         \sstitem
+          This function increments the \htmlref{RefCount}{RefCount} attribute of the
+         selected Frame by one.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astGetGrfContext
+}{
+   Return the KeyMap that describes a Plot\texttt{'} s graphics context
+}{
+   \sstdescription{
+      This function
+      returns a reference to a \htmlref{KeyMap}{KeyMap} that will be passed to any drawing
+      functions registered using \htmlref{astGrfSet}{astGrfSet}.
+      This KeyMap can be used by an application to pass information to
+      the drawing functions
+      about the context in which they are being called. The contents of
+      the KeyMap are never accessed byt the \htmlref{Plot}{Plot} class itself.
+   }
+   \sstsynopsis{
+      AstKeyMap $*$astGetGrfContext( AstPlot $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Plot.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astGetGrfContext()
+      }{
+         A pointer to the graphics context KeyMap. The returned pointer
+         should be annulled when it is no longer needed.
+      }
+   }
+}
+\sstroutine{
+   astGetMapping
+}{
+   Obtain a Mapping that converts between two Frames in a FrameSet
+}{
+   \sstdescription{
+      This function returns a pointer to a \htmlref{Mapping}{Mapping} that will convert
+      coordinates between the coordinate systems represented by two
+      Frames in a \htmlref{FrameSet}{FrameSet}.
+   }
+   \sstsynopsis{
+      AstMapping $*$astGetMapping( AstFrameSet $*$this, int iframe1, int iframe2 )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FrameSet.
+      }
+      \sstsubsection{
+         iframe1
+      }{
+         The index of the first \htmlref{Frame}{Frame} in the FrameSet. This Frame describes
+         the coordinate system for the \texttt{"} input\texttt{"}  end of the Mapping.
+      }
+      \sstsubsection{
+         iframe2
+      }{
+         The index of the second Frame in the FrameSet. This Frame
+         describes the coordinate system for the \texttt{"} output\texttt{"}  end of the
+         Mapping.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astGetMapping()
+      }{
+         Pointer to a Mapping whose forward transformation converts
+         coordinates from the first coordinate system to the second
+         one, and whose inverse transformation converts coordinates in
+         the opposite direction.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The returned Mapping will include the clipping effect of any
+         Regions which occur on the path between the two supplied Frames
+         (this includes the two supplied Frames themselves).
+
+         \sstitem
+          The values given for the \texttt{"} iframe1\texttt{"}  and \texttt{"} iframe2\texttt{"}  parameters
+         should lie in the range from 1 to the number of Frames in the
+         FrameSet (as given by its \htmlref{Nframe}{Nframe} attribute). A value of
+         AST\_\_BASE or AST\_\_CURRENT may also be given to identify the
+         FrameSet\texttt{'} s base Frame or current Frame respectively.  It is
+         permissible for both these parameters to have the same value, in
+         which case a unit Mapping (\htmlref{UnitMap}{UnitMap}) is returned.
+
+         \sstitem
+          It should always be possible to generate the Mapping
+         requested, but this does necessarily guarantee that it will be
+         able to perform the required coordinate conversion. If
+         necessary, the \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse} attributes of the
+         returned Mapping should be inspected to determine if the
+         required transformation is available.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astGetRefPos
+}{
+   Return the reference position in a specified celestial coordinate system
+}{
+   \sstdescription{
+      This function
+      returns the reference position (specified by attributes \htmlref{RefRA}{RefRA} and
+      \htmlref{RefDec}{RefDec}) converted to the celestial coordinate system represented by
+      a supplied \htmlref{SkyFrame}{SkyFrame}. The celestial longitude and latitude values
+      are returned in radians.
+   }
+   \sstsynopsis{
+      void astGetRefPos( AstSpecFrame $*$this, AstSkyFrame $*$frm, double $*$lon,
+                         double $*$lat )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the \htmlref{SpecFrame}{SpecFrame}.
+      }
+      \sstsubsection{
+         frm
+      }{
+         Pointer to the SkyFrame which defines the required celestial
+         coordinate system.
+         If NULL
+         is supplied, then the longitude and latitude values are returned
+         as FK5 J2000 RA and Dec values.
+      }
+      \sstsubsection{
+         lon
+      }{
+         A pointer to a double in which to store the
+         longitude of the reference point, in the coordinate system
+         represented by the supplied SkyFrame (radians).
+      }
+      \sstsubsection{
+         lat
+      }{
+         A pointer to a double in which to store the
+         latitude of the reference point, in the coordinate system
+         represented by the supplied SkyFrame (radians).
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Values of AST\_\_BAD will be returned if this function is
+         invoked with the AST error status set, or if it should fail for
+         any reason.
+      }
+   }
+}
+\sstroutine{
+   astGetRegionBounds
+}{
+   Returns the bounding box of Region
+}{
+   \sstdescription{
+      This function
+      returns the upper and lower limits of a box which just encompasses
+      the supplied \htmlref{Region}{Region}. The limits are returned as axis values within
+      the \htmlref{Frame}{Frame} represented by the Region. The value of the \htmlref{Negated}{Negated}
+      attribute is ignored (i.e. it is assumed that the Region has not
+      been negated).
+   }
+   \sstsynopsis{
+      void astGetRegionBounds( AstRegion $*$this, double $*$lbnd, double $*$ubnd )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Region.
+      }
+      \sstsubsection{
+         lbnd
+      }{
+         Pointer to an
+         array in which to return the lower axis bounds covered by the Region.
+         It should have at least as many elements as there are axes in the
+         Region. If an axis has no lower limit, the returned value will
+         be the largest possible negative value.
+      }
+      \sstsubsection{
+         ubnd
+      }{
+         Pointer to an
+         array in which to return the upper axis bounds covered by the Region.
+         It should have at least as many elements as there are axes in the
+         Region. If an axis has no upper limit, the returned value will
+         be the largest possible positive value.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The value of the Negated attribute is ignored (i.e. it is assumed that
+         the Region has not been negated).
+
+         \sstitem
+          If an axis has no extent on an axis then the lower limit will be
+         returned larger than the upper limit. Note, this is different to an
+         axis which has a constant value (in which case both lower and upper
+         limit will be returned set to the constant value).
+
+         \sstitem
+          If the bounds on an axis cannot be determined, AST\_\_BAD is returned for
+         both upper and lower bounds
+      }
+   }
+}
+\sstroutine{
+   astGetRegionFrame
+}{
+   Obtain a pointer to the encapsulated Frame within a Region
+}{
+   \sstdescription{
+      This function returns a pointer to the \htmlref{Frame}{Frame} represented by a
+      \htmlref{Region}{Region}.
+   }
+   \sstsynopsis{
+      AstFrame $*$astGetRegionFrame( AstRegion $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Region.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astGetRegionFrame()
+      }{
+         A pointer to a deep copy of the Frame represented by the Region.
+         Using this pointer to modify the Frame will have no effect on
+         the Region. To modify the Region, use the Region pointer directly.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astGetRegionFrameSet
+}{
+   Obtain a pointer to the encapsulated FrameSet within a Region
+}{
+   \sstdescription{
+      This function returns a pointer to the \htmlref{FrameSet}{FrameSet} encapsulated by a
+      \htmlref{Region}{Region}. The base \htmlref{Frame}{Frame} is the Frame in which the box was originally
+      defined, and the current Frame is the Frame into which the Region
+      is currently mapped (i.e. it will be the same as the Frame returned
+      by \htmlref{astGetRegionFrame}{astGetRegionFrame}).
+   }
+   \sstsynopsis{
+      AstFrame $*$astGetRegionFrameSet( AstRegion $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Region.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astGetRegionFrameSet()
+      }{
+         A pointer to a deep copy of the FrameSet represented by the Region.
+         Using this pointer to modify the FrameSet will have no effect on
+         the Region.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astGetRegionMesh
+}{
+   Return a mesh of points covering the surface or volume of a Region
+}{
+   \sstdescription{
+      This function
+      returns the axis values at a mesh of points either covering the
+      surface (i.e. boundary) of the supplied \htmlref{Region}{Region}, or filling the
+      interior (i.e. volume) of the Region. The number of points in
+      the mesh is approximately equal to the \htmlref{MeshSize}{MeshSize} attribute.
+   }
+   \sstsynopsis{
+      void astGetRegionMesh( AstRegion $*$this, int surface, int maxpoint,
+                             int maxcoord, int $*$npoint, double $*$points )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Region.
+      }
+      \sstsubsection{
+         surface
+      }{
+         If non-zero,
+         the returned points will cover the surface or the Region.
+         Otherwise, they will fill the interior of the Region.
+      }
+      \sstsubsection{
+         maxpoint
+      }{
+         If zero, the number of points in the mesh is returned in
+         \texttt{"} $*$npoint\texttt{"} ,
+         but no axis values are returned and all other parameters are ignored.
+         If not zero, the supplied value should be the length of the
+         second dimension of the \texttt{"} points\texttt{"}
+         array. An error is reported if the number of points in the mesh
+         exceeds this number.
+      }
+      \sstsubsection{
+         maxcoord
+      }{
+         The length of the
+         first dimension of the \texttt{"} points\texttt{"}  array.
+         An error is reported if the number of axes in the supplied Region
+         exceeds this number.
+      }
+      \sstsubsection{
+         npoint
+      }{
+         A pointer to an integer in which to return the
+         number of points in the returned mesh.
+      }
+      \sstsubsection{
+         points
+      }{
+         The address of the first element in a 2-dimensional array of
+         shape \texttt{"} [maxcoord][maxpoint]\texttt{"} , in which to return the coordinate
+         values at the mesh positions. These are stored such that the
+         value of coordinate number \texttt{"} coord\texttt{"}  for point number \texttt{"} point\texttt{"}  is
+         found in element \texttt{"} points[coord][point]\texttt{"} .
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          An error is reported if the Region is unbounded.
+
+         \sstitem
+          If the coordinate system represented by the Region has been
+         changed since it was first created, the returned axis values refer
+         to the new (changed) coordinate system, rather than the original
+         coordinate system. Note however that if the transformation from
+         original to new coordinate system is non-linear, the shape within
+         the new coordinate system may be distorted, and so may not match
+         that implied by the name of the Region subclass (\htmlref{Circle}{Circle}, \htmlref{Box}{Box}, etc).
+      }
+   }
+}
+\sstroutine{
+   astGetRegionPoints
+}{
+   Returns the positions that define the given Region
+}{
+   \sstdescription{
+      This function
+      returns the axis values at the points that define the supplied
+      \htmlref{Region}{Region}. The particular meaning of these points will depend on the
+      type of class supplied, as listed below under \texttt{"} Applicability:\texttt{"} .
+   }
+   \sstsynopsis{
+      void astGetRegionPoints( AstRegion $*$this, int maxpoint, int maxcoord,
+                               int $*$npoint, double $*$points )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Region.
+      }
+      \sstsubsection{
+         maxpoint
+      }{
+         If zero, the number of points needed to define the Region is
+         returned in
+         \texttt{"} $*$npoint\texttt{"} ,
+         but no axis values are returned and all other parameters are ignored.
+         If not zero, the supplied value should be the length of the
+         second dimension of the \texttt{"} points\texttt{"}
+         array. An error is reported if the number of points needed to define
+         the Region exceeds this number.
+      }
+      \sstsubsection{
+         maxcoord
+      }{
+         The length of the
+         first dimension of the \texttt{"} points\texttt{"}  array.
+         An error is reported if the number of axes in the supplied Region
+         exceeds this number.
+      }
+      \sstsubsection{
+         npoint
+      }{
+         A pointer to an integer in which to return the
+         number of points defining the Region.
+      }
+      \sstsubsection{
+         points
+      }{
+         The address of the first element in a 2-dimensional array of
+         shape \texttt{"} [maxcoord][maxpoint]\texttt{"} , in which to return
+         the coordinate values at the positions that define the Region.
+         These are stored such that the value of coordinate number
+         \texttt{"} coord\texttt{"}  for point number \texttt{"} point\texttt{"}  is found in element
+         \texttt{"} points[coord][point]\texttt{"} .
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Region
+      }{
+         All Regions have this attribute.
+      }
+      \sstsubsection{
+         \htmlref{Box}{Box}
+      }{
+         The first returned position is the Box centre, and the second is
+         a Box corner.
+      }
+      \sstsubsection{
+         \htmlref{Circle}{Circle}
+      }{
+         The first returned position is the Circle centre, and the second is
+         a point on the circumference.
+      }
+      \sstsubsection{
+         \htmlref{CmpRegion}{CmpRegion}
+      }{
+         Returns a value of zero for
+         \texttt{"} $*$npoint\texttt{"}
+         and leaves the supplied array contents unchanged. To find the
+         points defining a CmpRegion, use this method on the component
+         Regions, which can be accessed by invoking
+         \htmlref{astDecompose}{astDecompose}
+         on the CmpRegion.
+      }
+      \sstsubsection{
+         \htmlref{Ellipse}{Ellipse}
+      }{
+         The first returned position is the Ellipse centre. The second is
+         the end of one of the axes of the ellipse. The third is some
+         other point on the circumference of the ellipse, distinct from
+         the second point.
+      }
+      \sstsubsection{
+         \htmlref{Interval}{Interval}
+      }{
+         The first point corresponds to the lower bounds position, and
+         the second point corresponds to the upper bounds position. These
+         are reversed to indicate an extcluded interval rather than an
+         included interval. See the Interval constructor for more
+         information.
+      }
+      \sstsubsection{
+         \htmlref{NullRegion}{NullRegion}
+      }{
+         Returns a value of zero for
+         \texttt{"} $*$npoint\texttt{"}
+         and leaves the supplied array contents unchanged.
+      }
+      \sstsubsection{
+         \htmlref{PointList}{PointList}
+      }{
+         The positions returned are those that were supplied when the
+         PointList was constructed.
+      }
+      \sstsubsection{
+         \htmlref{Polygon}{Polygon}
+      }{
+         The positions returned are the vertex positions that were supplied
+         when the Polygon was constructed.
+      }
+      \sstsubsection{
+         \htmlref{Prism}{Prism}
+      }{
+         Returns a value of zero for
+         \texttt{"} $*$npoint\texttt{"}
+         and leaves the supplied array contents unchanged. To find the
+         points defining a Prism, use this method on the component
+         Regions, which can be accessed by invoking
+         astDecompose
+         on the CmpRegion.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If the coordinate system represented by the Region has been
+         changed since it was first created, the returned axis values refer
+         to the new (changed) coordinate system, rather than the original
+         coordinate system. Note however that if the transformation from
+         original to new coordinate system is non-linear, the shape within
+         the new coordinate system may be distorted, and so may not match
+         that implied by the name of the Region subclass (Circle, Box, etc).
+      }
+   }
+}
+\sstroutine{
+   astGetStcCoord
+}{
+   Return information about an AstroCoords element stored in an Stc
+}{
+   \sstdescription{
+      When any sub-class of \htmlref{Stc}{Stc} is created, the constructor function
+      allows one or more AstroCoords elements to be stored within the Stc.
+      This function allows any one of these AstroCoords elements to be
+      retrieved. The format of the returned information is the same as
+      that used to pass the original information to the Stc constructor.
+      That is, the information is returned in a \htmlref{KeyMap}{KeyMap} structure
+      containing elements with one or more of the keys given by symbolic
+      constants AST\_\_STCNAME, AST\_\_STCVALUE, AST\_\_STCERROR, AST\_\_STCRES,
+      AST\_\_STCSIZE and AST\_\_STCPIXSZ.
+
+      If the coordinate system represented by the Stc has been changed
+      since it was created (for instance, by changing its \htmlref{System}{System}
+      attribute), then the sizes and positions in the returned KeyMap
+      will reflect the change in coordinate system.
+   }
+   \sstsynopsis{
+      AstKeyMap $*$astGetStcCoord( AstStc $*$this, int icoord )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Stc.
+      }
+      \sstsubsection{
+         icoord
+      }{
+         The index of the AstroCoords element required. The first has index
+         one. The number of AstroCoords elements in the Stc can be found using
+         function astGetStcNcoord.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astGetStcCoord()
+      }{
+         A pointer to a new KeyMap containing the required information.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astGetStcNCoord
+}{
+   Return the number of AstroCoords elements stored in an Stc
+}{
+   \sstdescription{
+      This function returns the number of AstroCoords elements stored in
+      an \htmlref{Stc}{Stc}.
+   }
+   \sstsynopsis{
+      int astGetStcNCoord( AstStc $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Stc.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astGetStcNCoord()
+      }{
+         The number of  AstroCoords elements stored in the Stc.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Zero will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astGetStcRegion
+}{
+   Obtain a copy of the encapsulated Region within a Stc
+}{
+   \sstdescription{
+      This function returns a pointer to a deep copy of the \htmlref{Region}{Region}
+      supplied when the \htmlref{Stc}{Stc} was created.
+   }
+   \sstsynopsis{
+      AstRegion $*$astGetStcRegion( AstStc $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Stc.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astGetStcRegion()
+      }{
+         A pointer to a deep copy of the Region encapsulated within the
+         supplied Stc.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astGetTableHeader
+}{
+   Get the FITS headers from a FitsTable
+}{
+   \sstdescription{
+      This function returns a pointer to a \htmlref{FitsChan}{FitsChan} holding copies of
+      the FITS headers associated with a \htmlref{FitsTable}{FitsTable}.
+   }
+   \sstsynopsis{
+      AstFitsChan $*$astGetTableHeader( AstFitsTable $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FitsTable.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astGetTableHeader()
+      }{
+         A pointer to a deep copy of the FitsChan stored within the
+         FitsTable.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The returned pointer should be annulled using
+         \htmlref{astAnnul}{astAnnul}
+         when it is no longer needed.
+
+         \sstitem
+          Changing the contents of the returned FitsChan will have no effect
+         on the FitsTable. To modify the FitsTable, the modified FitsChan must
+         be stored in the FitsTable using
+         \htmlref{astPutTableHeader}{astPutTableHeader}.
+      }
+   }
+}
+\sstroutine{
+   astGetTables
+}{
+   Retrieve any FitsTables currently in a FitsChan
+}{
+   \sstdescription{
+      If the supplied \htmlref{FitsChan}{FitsChan} currently contains any tables, then this
+      function returns a pointer to a \htmlref{KeyMap}{KeyMap}. Each entry in the KeyMap
+      is a pointer to a \htmlref{FitsTable}{FitsTable} holding the data for a FITS binary
+      table. The key used to access each entry is the FITS extension
+      name in which the table should be stored.
+
+      Tables can be present in a FitsChan as a result either of using the
+      \htmlref{astPutTable}{astPutTable} (or \htmlref{astPutTables}{astPutTables})
+      method to store existing tables in the FitsChan, or of using the
+      \htmlref{astWrite}{astWrite}
+      method to write a \htmlref{FrameSet}{FrameSet} to the FitsChan. For the later case, if
+      the FitsChan \texttt{"} \htmlref{TabOK}{TabOK}\texttt{"}  attribute is positive and the FrameSet requires
+      a look-up table to describe one or more axes, then the \texttt{"} -TAB\texttt{"}
+      algorithm code described in FITS-WCS paper III is used and the table
+      values are stored in the FitsChan in the form of a FitsTable object
+      (see the documentation for the \texttt{"} TabOK\texttt{"}  attribute).
+   }
+   \sstsynopsis{
+      AstKeyMap $*$astGetTables( AstFitsChan $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FitsChan.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astGetTables()
+      }{
+         A pointer to a deep copy of the KeyMap holding the tables currently
+         in the FitsChan, or
+         NULL
+         if the FitsChan does not contain any tables. The returned
+         pointer should be annulled using
+         \htmlref{astAnnul}{astAnnul}
+         when no longer needed.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astGetUnc
+}{
+   Obtain uncertainty information from a Region
+}{
+   \sstdescription{
+      This function returns a \htmlref{Region}{Region} which represents the uncertainty
+      associated with positions within the supplied Region. See
+      \htmlref{astSetUnc}{astSetUnc}
+      for more information about Region uncertainties and their use.
+   }
+   \sstsynopsis{
+      AstRegion $*$astGetUnc( AstRegion $*$this, int def )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Region.
+      }
+      \sstsubsection{
+         def
+      }{
+         Controls what is returned if no uncertainty information has been
+         associated explicitly with the supplied Region. If
+         a non-zero value
+         is supplied, then the default uncertainty Region used internally
+         within AST is returned (see \texttt{"} Applicability\texttt{"}  below). If
+         zero is supplied, then NULL
+         will be returned (without error).
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{CmpRegion}{CmpRegion}
+      }{
+         The default uncertainty for a CmpRegion is taken from one of the
+         two component Regions. If the first component Region has a
+         non-default uncertainty, then it is used as the default uncertainty
+         for the parent CmpRegion. Otherwise, if the second component Region
+         has a non-default uncertainty, then it is used as the default
+         uncertainty for the parent CmpRegion. If neither of the
+         component Regions has non-default uncertainty, then the default
+         uncertainty for the CmpRegion is 1.0E-6 of the bounding box of
+         the CmpRegion.
+      }
+      \sstsubsection{
+         \htmlref{Prism}{Prism}
+      }{
+         The default uncertainty for a Prism is formed by combining the
+         uncertainties from the two component Regions. If a component
+         Region does not have a non-default uncertainty, then its default
+         uncertainty will be used to form the default uncertainty of the
+         parent Prism.
+      }
+      \sstsubsection{
+         Region
+      }{
+         For other classes of Region, the default uncertainty is 1.0E-6
+         of the bounding box of the Region. If the bounding box has zero
+         width on any axis, then the uncertainty will be 1.0E-6 of the
+         axis value.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astGetUnc()
+      }{
+         A pointer to a Region describing the uncertainty in the supplied
+         Region.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If uncertainty information is associated with a Region, and the
+         coordinate system described by the Region is subsequently changed
+         (e.g. by changing the value of its \htmlref{System}{System} attribute, or using the
+         \htmlref{astMapRegion}{astMapRegion}
+         function), then the uncertainty information returned by this function
+         will be modified so that it refers to the coordinate system currently
+         described by the supplied Region.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astGrfPop
+}{
+   Restore previously saved graphics functions used by a Plot
+}{
+   \sstdescription{
+      This function restores a snapshot of the graphics functions
+      stored previously by calling \htmlref{astGrfPush}{astGrfPush}. The restored graphics
+      functions become the current graphics functions used by the \htmlref{Plot}{Plot}.
+
+      The astGrfPush and astGrfPop functions are intended for situations
+      where it is necessary to make temporary changes to the graphics
+      functions used by the Plot. The current functions should first be
+      saved by calling astGrfPush. New functions should then be registered
+      using \htmlref{astGrfSet}{astGrfSet}. The required graphics should then be produced.
+      Finally, astGrfPop should be called to restore the original graphics
+      functions.
+   }
+   \sstsynopsis{
+      void astGrfPop( AstPlot $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Plot.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This function returns without action if there are no snapshots to
+         restore. No error is reported in this case.
+      }
+   }
+}
+\sstroutine{
+   astGrfPush
+}{
+   Save the current graphics functions used by a Plot
+}{
+   \sstdescription{
+      This function takes a snapshot of the graphics functions which are
+      currently registered with the supplied \htmlref{Plot}{Plot}, and saves the snapshot
+      on a first-in-last-out stack within the Plot. The snapshot can be
+      restored later using function
+      \htmlref{astGrfPop}{astGrfPop}.
+
+      The astGrfPush and astGrfPop functions are intended for situations
+      where it is necessary to make temporary changes to the graphics
+      functions used by the Plot. The current functions should first be
+      saved by calling astGrfPush. New functions should then be registered
+      using \htmlref{astGrfSet}{astGrfSet}. The required graphics should then be produced.
+      Finally, astGrfPop should be called to restore the original graphics
+      functions.
+   }
+   \sstsynopsis{
+      void astGrfPush( AstPlot $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Plot.
+      }
+   }
+}
+\sstroutine{
+   astGrfSet
+}{
+   Register a graphics function for use by a Plot
+}{
+   \sstdescription{
+      This function can be used to select the underlying graphics
+      functions to be used when the supplied \htmlref{Plot}{Plot} produces graphical output.
+      If this function is not called prior to producing graphical
+      output, then the underlying graphics functions selected at
+      link-time (using the \htmlref{ast\_link}{ast\_link} command) will be used. To use
+      alternative graphics functions, call this function before
+      the graphical output is created, specifying the graphics
+      functions to be used. This will register the function for future
+      use, but the function will not actually be used until the \htmlref{Grf}{Grf}
+      attribute is given a non-zero value.
+   }
+   \sstsynopsis{
+      void astGrfSet( AstPlot $*$this, const char $*$name, AstGrfFun fun )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Plot.
+      }
+      \sstsubsection{
+         name
+      }{
+         A name indicating the graphics function to be replaced.
+         Various graphics functions are used by the
+         Plot class, and any combination of them may be supplied by calling
+         this function once for each function to be replaced. If any of the
+         graphics functions are not replaced in this way, the
+         corresponding functions in the graphics interface selected at
+         link-time (using the ast\_link command) are used. The allowed
+         names are:
+
+         \sstitemlist{
+
+            \sstitem
+             Attr -  Enquire or set a graphics attribute value
+
+            \sstitem
+             BBuf - Start a new graphics buffering context
+
+            \sstitem
+             Cap -  Inquire a capability
+
+            \sstitem
+             EBuf - End the current graphics buffering context
+
+            \sstitem
+             Flush - Flush all pending graphics to the output device
+
+            \sstitem
+             Line - Draw a polyline (i.e. a set of connected lines)
+
+            \sstitem
+             Mark -  Draw a set of markers
+
+            \sstitem
+             Qch -  Return the character height in world coordinates
+
+            \sstitem
+             Scales -  Get the axis scales
+
+            \sstitem
+             Text - Draw a character string
+
+            \sstitem
+             TxExt -  Get the extent of a character string
+
+         }
+         The string is case insensitive. For details of the interface
+         required for each, see the sections below.
+      }
+      \sstsubsection{
+         fun
+      }{
+         A Pointer to the function to be used to provide the
+         functionality indicated by parameter name. The interface for
+         each function is described below, but the function pointer should
+         be cast to a type of AstGrfFun when calling astGrfSet.
+
+         Once a function has been provided, a null pointer can be supplied
+         in a subsequent call to astGrfSet to reset the function to the
+         corresponding function in the graphics interface selected at
+         link-time.
+      }
+   }
+   \sstdiytopic{
+      Function Interfaces
+   }{
+      All the functions listed below (except for \texttt{"} Cap\texttt{"} ) should return an
+      integer value of 0 if an error occurs, and 1 otherwise. All x and y
+      values refer
+      to \texttt{"} graphics cordinates\texttt{"}  as defined by the graphbox parameter of
+      the \htmlref{astPlot}{astPlot} call which created the Plot.
+
+      The first parameter (\texttt{"} grfcon\texttt{"} )
+      for each function is an AST \htmlref{KeyMap}{KeyMap} pointer that can be used by the
+      called function to establish the context in which it is being called.
+      The contents of the KeyMap are determined by the calling
+      application, which should obtain a pointer to the KeyMap using the
+      \htmlref{astGetGrfContext}{astGetGrfContext} function,
+      and then store any necessary information in the KeyMap using the
+      methods of the KeyMap class. Note, the functions listed below
+      should never annul or delete the supplied KeyMap pointer.
+   }
+   \sstdiytopic{
+      Attr
+   }{
+      The \texttt{"} Attr\texttt{"}  function returns the current value of a specified graphics
+      attribute, and optionally establishes a new value. The supplied
+      value is converted to an integer value if necessary before use.
+      It requires the following interface:
+
+      int Attr( AstObject $*$grfcon, int attr, double value, double $*$old\_value, int prim )
+
+      \sstitemlist{
+
+         \sstitem
+          grfcon -
+           A KeyMap containing information passed from the calling application.
+
+         \sstitem
+          attr - An integer value identifying the required attribute.
+           The following symbolic values are defined in grf.h:
+           GRF\_\_STYLE (Line style),
+           GRF\_\_WIDTH (Line width),
+           GRF\_\_SIZE (Character and marker size scale factor),
+           GRF\_\_FONT (Character font),
+           GRF\_\_COLOUR (Colour index).
+
+         \sstitem
+          value -
+           A new value to store for the attribute. If this is AST\_\_BAD
+           no value is stored.
+
+         \sstitem
+          old\_value - A pointer to a double in which to return
+           the attribute value.
+           If this is NULL, no value is returned.
+
+         \sstitem
+          prim -
+           The sort of graphics primitive to be drawn with the new attribute.
+           Identified by the following values defined in grf.h:
+           GRF\_\_LINE,
+           GRF\_\_MARK,
+           GRF\_\_TEXT.
+      }
+   }
+   \sstdiytopic{
+      BBuf
+   }{
+      The \texttt{"} BBuf\texttt{"}  function should start a new graphics buffering context.
+      A matching call to the function \texttt{"} EBuf\texttt{"}  should be used to end the
+      context. The nature of the buffering is determined by the underlying
+      graphics system.
+
+      int BBuf( AstObject $*$grfcon )
+
+      \sstitemlist{
+
+         \sstitem
+          grfcon -
+           A KeyMap containing information passed from the calling application.
+      }
+   }
+   \sstdiytopic{
+      Cap
+   }{
+      The \texttt{"} Cap\texttt{"}  function is called to determine if the grf module has a
+      given capability, as indicated by the \texttt{"} cap\texttt{"}  argument:
+
+      int Cap( AstObject $*$grfcon, int cap, int value )
+
+      \sstitemlist{
+
+         \sstitem
+          grfcon -
+           A KeyMap containing information passed from the calling application.
+
+         \sstitem
+          cap -
+            The capability being inquired about. This will be one of the
+            following constants defined in grf.h:
+
+      }
+         GRF\_\_SCALES: This function should return a non-zero value if the
+         \texttt{"} Scales\texttt{"}  function is implemented, and zero otherwise. The supplied
+         \texttt{"} value\texttt{"}  argument should be ignored.
+
+         GRF\_\_MJUST: This function should return a non-zero value if
+         the \texttt{"} Text\texttt{"}  and \texttt{"} TxExt\texttt{"}  functions recognise \texttt{"} M\texttt{"}  as a
+         character in the justification string. If the first character of
+         a justification string is \texttt{"} M\texttt{"} , then the text should be justified
+         with the given reference point at the bottom of the bounding box.
+         This is different to \texttt{"} B\texttt{"}  justification, which requests that the
+         reference point be put on the baseline of the text, since some
+         characters hang down below the baseline. If the \texttt{"} Text\texttt{"}  or
+         \texttt{"} TxExt\texttt{"}  function cannot differentiate between \texttt{"} M\texttt{"}  and \texttt{"} B\texttt{"} ,
+         then this function should return zero, in which case \texttt{"} M\texttt{"}
+         justification will never be requested by Plot. The supplied
+         \texttt{"} value\texttt{"}  argument should be ignored.
+
+         GRF\_\_ESC: This function should return a non-zero value if the
+         \texttt{"} Text\texttt{"}  and \texttt{"} TxExt\texttt{"}  functions can recognise and interpret
+         graphics escape sequences within the supplied string (see
+         attribute \htmlref{Escape}{Escape}). Zero should be returned if escape sequences
+         cannot be interpreted (in which case the Plot class will interpret
+         them itself if needed). The supplied \texttt{"} value\texttt{"}  argument should be
+         ignored only if escape sequences cannot be interpreted by \texttt{"} Text\texttt{"}  and
+         \texttt{"} TxExt\texttt{"} . Otherwise, \texttt{"} value\texttt{"}  indicates whether \texttt{"} Text\texttt{"}  and \texttt{"} TxExt\texttt{"}
+         should interpret escape sequences in subsequent calls. If \texttt{"} value\texttt{"}  is
+         non-zero then escape sequences should be interpreted by \texttt{"} Text\texttt{"}  and
+         \texttt{"} TxExt\texttt{"} . Otherwise, they should be drawn as literal text.
+
+      \sstitemlist{
+
+         \sstitem
+          value -
+            The use of this parameter depends on the value of \texttt{"} cap\texttt{"}  as
+            described above.
+
+         \sstitem
+          Returned Function Value:
+            The value returned by the function depends on the value of \texttt{"} cap\texttt{"}
+            as described above. Zero should be returned if the supplied
+            capability is not recognised.
+      }
+   }
+   \sstdiytopic{
+      EBuf
+   }{
+      The \texttt{"} EBuf\texttt{"}  function should end the current graphics buffering
+      context. See the description of \texttt{"} BBuf\texttt{"}  above for further details.
+      It requires the following interface:
+
+      int EBuf( AstObject $*$grfcon )
+
+      \sstitemlist{
+
+         \sstitem
+          grfcon -
+           A KeyMap containing information passed from the calling application.
+      }
+   }
+   \sstdiytopic{
+      Flush
+   }{
+      The \texttt{"} Flush\texttt{"}  function ensures that the display device is up-to-date,
+      by flushing any pending graphics to the output device. It
+      requires the following interface:
+
+      int Flush( AstObject $*$grfcon )
+
+      \sstitemlist{
+
+         \sstitem
+          grfcon -
+           A KeyMap containing information passed from the calling application.
+      }
+   }
+   \sstdiytopic{
+      Line
+   }{
+      The \texttt{"} Line\texttt{"}  function displays lines joining the given positions and
+      requires the following interface:
+
+      int Line( AstObject $*$grfcon, int n, const float $*$x, const float $*$y )
+
+      \sstitemlist{
+
+         \sstitem
+          grfcon -
+           A KeyMap containing information passed from the calling application.
+
+         \sstitem
+          n - The number of positions to be joined together.
+
+         \sstitem
+          x - A pointer to an array holding the \texttt{"} n\texttt{"}  x values.
+
+         \sstitem
+          y - A pointer to an array holding the \texttt{"} n\texttt{"}  y values.
+      }
+   }
+   \sstdiytopic{
+      Mark
+   }{
+      The \texttt{"} Mark\texttt{"}  function displays markers at the given positions. It
+      requires the following interface:
+
+      int Mark( AstObject $*$grfcon, int n, const float $*$x, const float $*$y, int type )
+
+      \sstitemlist{
+
+         \sstitem
+          grfcon -
+           A KeyMap containing information passed from the calling application.
+
+         \sstitem
+          n - The number of positions to be marked.
+
+         \sstitem
+          x - A pointer to an array holding the \texttt{"} n\texttt{"}  x values.
+
+         \sstitem
+          y - A pointer to an array holding the \texttt{"} n\texttt{"}  y values.
+
+         \sstitem
+          type - An integer which can be used to indicate the type of marker
+           symbol required.
+      }
+   }
+   \sstdiytopic{
+      Qch
+   }{
+      The \texttt{"} Qch\texttt{"}  function returns the heights of characters drawn vertically
+      and horizontally in graphics coordinates. It requires the following
+      interface:
+
+      int Qch( AstObject $*$grfcon, float $*$chv, float $*$chh )
+
+      \sstitemlist{
+
+         \sstitem
+          grfcon -
+           A KeyMap containing information passed from the calling application.
+
+         \sstitem
+          chv - A pointer to the float which is to receive the height of
+         characters drawn with a vertical baseline. This will be an
+         increment in the X axis.
+
+         \sstitem
+          chh - A pointer to the float which is to receive the height of
+         characters drawn with a horizontal baseline. This will be an
+         increment in the Y axis.
+      }
+   }
+   \sstdiytopic{
+      Scales
+   }{
+      The \texttt{"} Scales\texttt{"}  function returns two values (one for each axis) which
+      scale increments on the corresponding axis into a \texttt{"} normal\texttt{"}  coordinate
+      system in which: 1) the axes have equal scale in terms of (for instance)
+      millimetres per unit distance, 2) X values increase from left to
+      right, and 3) Y values increase from bottom to top. It requires the
+      following interface:
+
+      int Scales( AstObject $*$grfcon, float $*$alpha, float $*$beta )
+
+      \sstitemlist{
+
+         \sstitem
+          grfcon -
+           A KeyMap containing information passed from the calling application.
+
+         \sstitem
+          alpha - A pointer to the float which is to receive the
+         scale for the X axis (i.e. Xnorm = alpha$*$Xworld).
+
+         \sstitem
+          beta - A pointer to the float which is to receive the
+         scale for the Y axis (i.e. Ynorm = beta$*$Yworld).
+      }
+   }
+   \sstdiytopic{
+      Text
+   }{
+      The \texttt{"} Text\texttt{"}  function displays a character string at a given
+      position using a specified justification and up-vector. It
+      requires the following interface:
+
+      int Text( AstObject $*$grfcon, const char $*$text, float x, float y, const char $*$just,
+                float upx, float upy )
+
+      \sstitemlist{
+
+         \sstitem
+          grfcon -
+           A KeyMap containing information passed from the calling application.
+
+         \sstitem
+          text - Pointer to a null-terminated character string to be displayed.
+
+         \sstitem
+          x - The reference x coordinate.
+
+         \sstitem
+          y - The reference y coordinate.
+
+         \sstitem
+          just - A character string which specifies the location within the
+            text string which is to be placed at the reference position
+            given by x and y. The first character may be \texttt{'} T\texttt{'}  for \texttt{"} top\texttt{"} ,
+            \texttt{'} C\texttt{'}  for \texttt{"} centre\texttt{"} , or \texttt{'} B\texttt{'}  for \texttt{"} bottom\texttt{"} , and specifies the
+            vertical location of the reference position. Note, \texttt{"} bottom\texttt{"}
+            corresponds to the base-line of normal text. Some characters
+            (eg \texttt{"} y\texttt{"} , \texttt{"} g\texttt{"} , \texttt{"} p\texttt{"} , etc) descend below the base-line. The second
+            character may be \texttt{'} L\texttt{'}  for \texttt{"} left\texttt{"} , \texttt{'} C\texttt{'}  for \texttt{"} centre\texttt{"} , or \texttt{'} R\texttt{'}
+            for \texttt{"} right\texttt{"} , and specifies the horizontal location of the
+            reference position. If the string has less than 2 characters
+            then \texttt{'} C\texttt{'}  is used for the missing characters.
+
+         \sstitem
+          upx - The x component of the up-vector for the text.
+            If necessary the supplied value should be negated
+            to ensure that positive values always refer to displacements from
+            left to right on the screen.
+
+         \sstitem
+          upy - The y component of the up-vector for the text.
+            If necessary the supplied value should be negated
+            to ensure that positive values always refer to displacements from
+            bottom to top on the screen.
+      }
+   }
+   \sstdiytopic{
+      TxExt
+   }{
+      The \texttt{"} TxExt\texttt{"}  function returns the corners of a box which would enclose
+      the supplied character string if it were displayed using the
+      Text function described above. The returned box includes any leading
+      or trailing spaces. It requires the following interface:
+
+      int TxExt( AstObject $*$grfcon, const char $*$text, float x, float y, const char $*$just,
+                 float upx, float upy, float $*$xb, float $*$yb )
+
+      \sstitemlist{
+
+         \sstitem
+          grfcon -
+           A KeyMap containing information passed from the calling application.
+
+         \sstitem
+          text - Pointer to a null-terminated character string to be displayed.
+
+         \sstitem
+          x - The reference x coordinate.
+
+         \sstitem
+          y - The reference y coordinate.
+
+         \sstitem
+          just - A character string which specifies the location within the
+            text string which is to be placed at the reference position
+            given by x and y. See \texttt{"} Text\texttt{"}  above.
+
+         \sstitem
+          upx - The x component of the up-vector for the text.
+            See \texttt{"} Text\texttt{"}  above.
+
+         \sstitem
+          upy - The y component of the up-vector for the text.
+            See \texttt{"} Text\texttt{"}  above.
+
+         \sstitem
+          xb - An array of 4 elements in which to return the x coordinate of
+            each corner of the bounding box.
+
+         \sstitem
+          yb - An array of 4 elements in which to return the y coordinate of
+            each corner of the bounding box.
+      }
+   }
+}
+\sstroutine{
+   astGrid
+}{
+   Draw a set of labelled coordinate axes
+}{
+   \sstdescription{
+      This function draws a complete annotated set of
+      coordinate axes for a \htmlref{Plot}{Plot} with (optionally) a coordinate grid
+      superimposed. Details of the axes and grid can be controlled by
+      setting values for the various attributes defined by the Plot
+      class (q.v.).
+   }
+   \sstsynopsis{
+      void astGrid( AstPlot $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Plot.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If the supplied Plot is a \htmlref{Plot3D}{Plot3D}, the axes will be annotated
+         using three 2-dimensional Plots, one for each 2D plane in the 3D
+         current coordinate system. The plots will be \texttt{"} pasted\texttt{"}  onto 3 faces
+         of the cuboid graphics volume specified when the Plot3D was
+         constructed. The faces to be used can be controlled by the \texttt{"} \htmlref{RootCorner}{RootCorner}\texttt{"}
+         attribute.
+
+         \sstitem
+          An error results if either the current \htmlref{Frame}{Frame} or the base Frame
+         of the Plot is not 2-dimensional or (for a Plot3D) 3-dimensional.
+
+         \sstitem
+          An error also results if the transformation between the base
+         and current Frames of the Plot is not defined in either
+         direction (i.e. the Plot\texttt{'} s \htmlref{TranForward}{TranForward} or \htmlref{TranInverse}{TranInverse} attribute
+         is zero).
+      }
+   }
+}
+\sstroutine{
+   astGridLine
+}{
+   Draw a grid line (or axis) for a Plot
+}{
+   \sstdescription{
+      This function draws a curve in the physical coordinate system of
+      a \htmlref{Plot}{Plot} by varying only one of the coordinates along the length
+      of the curve. It is intended for drawing coordinate axes,
+      coordinate grids, and tick marks on axes (but note that these
+      are also available via the more comprehensive \htmlref{astGrid}{astGrid} function).
+
+      The curve is transformed into graphical coordinate space for
+      plotting, so that a straight line in physical coordinates may
+      result in a curved line being drawn if the \htmlref{Mapping}{Mapping} involved is
+      non-linear. Any discontinuities in the Mapping between physical
+      and graphical coordinates are catered for, as is any
+      clipping established using \htmlref{astClip}{astClip}.
+   }
+   \sstsynopsis{
+      void astGridLine( AstPlot $*$this, int axis, const double start[],
+                        double length )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Plot.
+      }
+      \sstsubsection{
+         axis
+      }{
+         The index of the Plot axis whose physical coordinate value is
+         to be varied along the length of the curve (all other
+         coordinates will remain fixed). This value should lie in the
+         range from 1 to the number of Plot axes (\htmlref{Naxes}{Naxes} attribute).
+      }
+      \sstsubsection{
+         start
+      }{
+         An array, with one element for each axis of the Plot, giving
+         the physical coordinates of the start of the curve.
+      }
+      \sstsubsection{
+         length
+      }{
+         The length of curve to be drawn, given as an increment along
+         the selected physical axis. This may be positive or negative.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          No curve is drawn if the \texttt{"} start\texttt{"}  array contains any
+         coordinates with the value AST\_\_BAD, nor if \texttt{"} length\texttt{"}  has this value.
+
+         \sstitem
+          An error results if the base \htmlref{Frame}{Frame} of the Plot is not 2-dimensional.
+
+         \sstitem
+          An error also results if the transformation between the
+         current and base Frames of the Plot is not defined (i.e. the
+         Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero).
+      }
+   }
+}
+\sstroutine{
+   astGrismMap
+}{
+   Create a GrismMap
+}{
+   \sstdescription{
+      This function creates a new \htmlref{GrismMap}{GrismMap} and optionally initialises
+      its attributes.
+
+      A GrismMap is a specialised form of \htmlref{Mapping}{Mapping} which transforms
+      1-dimensional coordinates using the spectral dispersion equation
+      described in FITS-WCS paper III \texttt{"} Representation of spectral
+      coordinates in FITS\texttt{"} . This describes the dispersion produced by
+      gratings, prisms and grisms.
+
+      When initially created, the forward transformation of a GrismMap
+      transforms input \texttt{"} grism parameter\texttt{"}  values into output wavelength
+      values. The \texttt{"} grism parameter\texttt{"}  is a dimensionless value which is
+      linearly related to position on the detector. It is defined in FITS-WCS
+      paper III as \texttt{"} the offset on the detector from the point of intersection
+      of the camera axis, measured in units of the effective local length\texttt{"} .
+      The units in which wavelength values are expected or returned is
+      determined by the values supplied for the \htmlref{GrismWaveR}{GrismWaveR}, \htmlref{GrismNRP}{GrismNRP} and
+      \htmlref{GrismG}{GrismG} attribute: whatever units are used for these attributes will
+      also be used for the wavelength values.
+   }
+   \sstsynopsis{
+      AstGrismMap $*$astGrismMap( const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new GrismMap. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astGrismMap()
+      }{
+         A pointer to the new GrismMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astHasAttribute
+}{
+   Test if an Object has a named attribute
+}{
+   \sstdescription{
+      This function returns a boolean result (0 or 1) to indicate
+      whether the supplied \htmlref{Object}{Object} has an attribute with the supplied name.
+   }
+   \sstsynopsis{
+      int astHasAttribute( AstObject $*$this, const char $*$attrib )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the first Object.
+      }
+      \sstsubsection{
+         attrib
+      }{
+         Pointer to a string holding the
+         name of the attribute to be tested.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         This function applies to all Objects.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astHasAttribute()
+      }{
+         One if the Object has the named attribute, otherwise zero.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A value of zero will be returned if this function is invoked
+         with the AST error status set, or if it should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astHasColumn
+}{
+   Returns a flag indicating if a column is present in a Table
+}{
+   \sstdescription{
+      This function
+      returns a flag indicating if a named column exists in a \htmlref{Table}{Table}, for
+      instance, by having been added to to the Table using
+      \htmlref{astAddColumn}{astAddColumn}.
+   }
+   \sstsynopsis{
+      int astHasColumn( AstTable $*$this, const char $*$column )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Table.
+      }
+      \sstsubsection{
+         column
+      }{
+         The character string holding the upper case name of the column. Trailing
+         spaces are ignored.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A value of
+         zero
+         is returned for if an error occurs.
+      }
+   }
+}
+\sstroutine{
+   astHasParameter
+}{
+   Returns a flag indicating if a named global parameter is present in a Table
+}{
+   \sstdescription{
+      This function
+      returns a flag indicating if a named parameter exists in a \htmlref{Table}{Table}, for
+      instance, by having been added to to the Table using
+      \htmlref{astAddParameter}{astAddParameter}.
+   }
+   \sstsynopsis{
+      int astHasParameter( AstTable $*$this, const char $*$parameter )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Table.
+      }
+      \sstsubsection{
+         parameter
+      }{
+         The character string holding the upper case name of the parameter. Trailing
+         spaces are ignored.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A value of
+         zero
+         is returned for if an error occurs.
+      }
+   }
+}
+\sstroutine{
+   astImport
+}{
+   Import an Object pointer to the current context
+}{
+   \sstdescription{
+      This function
+      imports an \htmlref{Object}{Object} pointer that was created in a higher or lower
+      level context, into the current AST context.
+      This means that the pointer will be annulled when the current context
+      is ended (with \htmlref{astEnd}{astEnd}).
+   }
+   \sstsynopsis{
+      void astImport( AstObject $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Object pointer to be imported.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         This function applies to all Objects.
+      }
+   }
+}
+\sstroutine{
+   astIntersect
+}{
+   Find the point of intersection between two geodesic curves
+}{
+   \sstdescription{
+      This function
+      finds the coordinate values at the point of intersection between
+      two geodesic curves. Each curve is specified by two points on
+      the curve.  It can only be used with 2-dimensional Frames.
+
+      For example, in a basic \htmlref{Frame}{Frame}, it will find the point of
+      intersection between two straight lines. But for a \htmlref{SkyFrame}{SkyFrame} it
+      will find an intersection of two great circles.
+   }
+   \sstsynopsis{
+      void astIntersect( AstFrame $*$this, const double a1[2],
+                         const double a2[2], const double b1[2],
+                         const double b2[2], double cross[2] )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Frame.
+      }
+      \sstsubsection{
+         a1
+      }{
+         An array of double, with one element for each Frame axis
+         (\htmlref{Naxes}{Naxes} attribute). This should contain the coordinates of the
+         first point on the first geodesic curve.
+      }
+      \sstsubsection{
+         a2
+      }{
+         An array of double, with one element for each Frame axis
+         (Naxes attribute). This should contain the coordinates of a
+         second point on the first geodesic curve. It should not be
+         co-incident with the first point.
+      }
+      \sstsubsection{
+         b1
+      }{
+         An array of double, with one element for each Frame axis
+         (Naxes attribute). This should contain the coordinates of the
+         first point on the second geodesic curve.
+      }
+      \sstsubsection{
+         b2
+      }{
+         An array of double, with one element for each Frame axis
+         (Naxes attribute). This should contain the coordinates of a
+         second point on the second geodesic curve. It should not be
+         co-incident with the first point.
+      }
+      \sstsubsection{
+         cross
+      }{
+         An array of double, with one element for each Frame axis
+         in which the coordinates of the required intersection will
+         be returned.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          For SkyFrames each curve will be a great circle, and in general
+         each pair of curves will intersect at two diametrically opposite
+         points on the sky. The returned position is the one which is
+         closest to point
+         \texttt{"} a1\texttt{"} .
+
+         \sstitem
+          This function will return \texttt{"} bad\texttt{"}  coordinate values (AST\_\_BAD)
+         if any of the input coordinates has this value, or if the two
+         points defining either geodesic are co-incident, or if the two
+         curves do not intersect.
+
+         \sstitem
+          The geodesic curve used by this function is the path of
+         shortest distance between two points, as defined by the
+         \htmlref{astDistance}{astDistance} function.
+
+         \sstitem
+          An error will be reported if the Frame is not 2-dimensional.
+      }
+   }
+}
+\sstroutine{
+   astInterval
+}{
+   Create a Interval
+}{
+   \sstdescription{
+      This function creates a new \htmlref{Interval}{Interval} and optionally initialises its
+      attributes.
+
+      A Interval is a \htmlref{Region}{Region} which represents upper and/or lower limits on
+      one or more axes of a \htmlref{Frame}{Frame}. For a point to be within the region
+      represented by the Interval, the point must satisfy all the
+      restrictions placed on all the axes. The point is outside the region
+      if it fails to satisfy any one of the restrictions. Each axis may have
+      either an upper limit, a lower limit, both or neither. If both limits
+      are supplied but are in reverse order (so that the lower limit is
+      greater than the upper limit), then the interval is an excluded
+      interval, rather than an included interval.
+
+      At least one axis limit must be supplied.
+
+      Note, The Interval class makes no allowances for cyclic nature of
+      some coordinate systems (such as \htmlref{SkyFrame}{SkyFrame} coordinates). A \htmlref{Box}{Box}
+      should usually be used in these cases since this requires the user
+      to think about suitable upper and lower limits,
+   }
+   \sstsynopsis{
+      AstInterval $*$astInterval( AstFrame $*$frame, const double lbnd[],
+                                const double ubnd[], AstRegion $*$unc,
+                                const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         frame
+      }{
+         A pointer to the Frame in which the region is defined. A deep
+         copy is taken of the supplied Frame. This means that any
+         subsequent changes made to the Frame using the supplied pointer
+         will have no effect the Region.
+      }
+      \sstsubsection{
+         lbnd
+      }{
+         An array of double, with one element for each Frame axis
+         (\htmlref{Naxes}{Naxes} attribute) containing the lower limits on each axis.
+         Set a value to AST\_\_BAD to indicate that the axis has no lower
+         limit.
+      }
+      \sstsubsection{
+         ubnd
+      }{
+         An array of double, with one element for each Frame axis
+         (Naxes attribute) containing the upper limits on each axis.
+         Set a value to AST\_\_BAD to indicate that the axis has no upper
+         limit.
+      }
+      \sstsubsection{
+         unc
+      }{
+         An optional pointer to an existing Region which specifies the
+         uncertainties associated with the boundary of the Interval being created.
+         The uncertainty in any point on the boundary of the Interval is found by
+         shifting the supplied \texttt{"} uncertainty\texttt{"}  Region so that it is centred at
+         the boundary point being considered. The area covered by the
+         shifted uncertainty Region then represents the uncertainty in the
+         boundary position. The uncertainty is assumed to be the same for
+         all points.
+
+         If supplied, the uncertainty Region must be of a class for which
+         all instances are centro-symetric (e.g. Box, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.)
+         or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep
+         copy of the supplied Region will be taken, so subsequent changes to
+         the uncertainty Region using the supplied pointer will have no
+         effect on the created Interval. Alternatively,
+         a NULL \htmlref{Object}{Object} pointer
+         may be supplied, in which case a default uncertainty is used
+         equivalent to a box 1.0E-6 of the size of the Interval being created.
+
+         The uncertainty Region has two uses: 1) when the
+         \htmlref{astOverlap}{astOverlap}
+         function compares two Regions for equality the uncertainty
+         Region is used to determine the tolerance on the comparison, and 2)
+         when a Region is mapped into a different coordinate system and
+         subsequently simplified (using
+         \htmlref{astSimplify}{astSimplify}),
+         the uncertainties are used to determine if the transformed boundary
+         can be accurately represented by a specific shape of Region.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new Interval. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astInterval()
+      }{
+         A pointer to the new Interval.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null Object pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      Status Handling
+   }{
+      The protected interface to this function includes an extra
+      parameter at the end of the parameter list descirbed above. This
+      parameter is a pointer to the integer inherited status
+      variable: \texttt{"} int $*$status\texttt{"} .
+   }
+}
+\sstroutine{
+   astIntraMap
+}{
+   Create an IntraMap
+}{
+   \sstdescription{
+      This function creates a new \htmlref{IntraMap}{IntraMap} and optionally initialises
+      its attributes.
+
+      An IntraMap is a specialised form of \htmlref{Mapping}{Mapping} which encapsulates
+      a privately-defined coordinate transformation function
+      (e.g. written in C) so that it may be used like any other AST
+      Mapping. This allows you to create Mappings that perform any
+      conceivable coordinate transformation.
+
+      However, an IntraMap is intended for use within a single program
+      or a private suite of software, where all programs have access
+      to the same coordinate transformation functions (i.e. can be
+      linked against them). IntraMaps should not normally be stored in
+      datasets which may be exported for processing by other software,
+      since that software will not have the necessary transformation
+      functions available, resulting in an error.
+
+      You must register any coordinate transformation functions to be
+      used using \htmlref{astIntraReg}{astIntraReg} before creating an IntraMap.
+   }
+   \sstsynopsis{
+      AstIntraMap $*$astIntraMap( const char $*$name, int nin, int nout,
+                                const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         name
+      }{
+         Pointer to a null-terminated string containing the name of
+         the transformation function to use (which should previously
+         have been registered using astIntraReg). This name is case
+         sensitive. All white space will be removed before use.
+      }
+      \sstsubsection{
+         nin
+      }{
+         The number of input coordinates. This must be compatible with
+         the number of input coordinates accepted by the
+         transformation function (as specified when this function was
+         registered using astIntraReg).
+      }
+      \sstsubsection{
+         nout
+      }{
+         The number of output coordinates. This must be compatible
+         with the number of output coordinates produced by the
+         transformation function (as specified when this function was
+         registered using astIntraReg).
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new IntraMap. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astIntraMap()
+      }{
+         A pointer to the new IntraMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astIntraReg
+}{
+   Register a transformation function for use by an IntraMap
+}{
+   \sstdescription{
+      This function registers a privately-defined coordinate
+      transformation function written in C so that it may be used to
+      create an \htmlref{IntraMap}{IntraMap}. An IntraMap is a specialised form of \htmlref{Mapping}{Mapping}
+      which encapsulates the C function so that it may be used like
+      any other AST Mapping. This allows you to create Mappings that
+      perform any conceivable coordinate transformation.
+
+      Registration of relevant transformation functions is required
+      before using the \htmlref{astIntraMap}{astIntraMap} constructor function to create an
+      IntraMap or reading an external representation of an IntraMap
+      from a \htmlref{Channel}{Channel}.
+   }
+   \sstsynopsis{
+      astIntraReg( const char $*$name, int nin, int nout,
+                   void ($*$ tran)( AstMapping $*$, int, int, const double $*$[],
+                                  int, int, double $*$[] ),
+                   unsigned int flags, const char $*$purpose, const char $*$author,
+                   const char $*$contact )
+   }
+   \sstparameters{
+      \sstsubsection{
+         name
+      }{
+         Pointer to a null-terminated string containing a unique name
+         to be associated with the transformation function in order to
+         identify it. This name is case sensitive. All white space
+         will be removed before use.
+      }
+      \sstsubsection{
+         nin
+      }{
+         The number of input coordinates accepted by the
+         transformation function (i.e. the number of dimensions of the
+         space in which the input points reside). A value of AST\_\_ANY
+         may be given if the function is able to accommodate a
+         variable number of input coordinates.
+      }
+      \sstsubsection{
+         nout
+      }{
+         The number of output coordinates produced by the
+         transformation function (i.e. the number of dimensions of the
+         space in which the output points reside). A value of AST\_\_ANY
+         may be given if the function is able to produce a variable
+         number of output coordinates.
+      }
+      \sstsubsection{
+         tran
+      }{
+         Pointer to the transformation function to be registered.
+         This function should perform whatever coordinate
+         transformations are required and should have an interface
+         like \htmlref{astTranP}{astTranP} (q.v.).
+      }
+      \sstsubsection{
+         flags
+      }{
+         This value may be used to supply a set of flags which
+         describe the transformation function and which may affect the
+         behaviour of any IntraMap which uses it.  Often, a value of
+         zero will be given here, but you may also supply the bitwise
+         OR of a set of flags as described in the \texttt{"} Transformation
+         Flags\texttt{"}  section (below).
+      }
+      \sstsubsection{
+         purpose
+      }{
+         Pointer to a null-terminated string containing a short (one
+         line) textual comment to describe the purpose of the
+         transformation function.
+      }
+      \sstsubsection{
+         author
+      }{
+         Pointer to a null-terminated string containing the name of
+         the author of the transformation function.
+      }
+      \sstsubsection{
+         contact
+      }{
+         Pointer to a null-terminated string containing contact
+         details for the author of the transformation function
+         (e.g. an e-mail or WWW address). If any IntraMap which uses
+         this transformation function is exported as part of a dataset
+         to an external user who does not have access to the function,
+         then these contact details should allow them to obtain the
+         necessary code.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Beware that an external representation of an IntraMap (created
+         by writing it to a Channel) will not include the coordinate
+         transformation function which it uses, so will only refer to the
+         function by its name (as assigned using astIntraReg).
+         Consequently, the external representation cannot be utilised by
+         another program unless that program has also registered the same
+         transformation function with the same name using an identical
+         invocation of astIntraReg. If no such registration has been
+         performed, then attempting to read the external representation
+         will result in an error.
+
+         \sstitem
+          You may use astIntraReg to register a transformation function
+         with the same name more than once, but only if the arguments
+         supplied are identical on each occasion (i.e there is no way of
+         changing things once a function has been successfully registered
+         under a given name, and attempting to do so will result in an
+         error). This feature simply allows registration to be performed
+         independently, but consistently, at several places within your
+         program, without having to check whether it has already been
+         done.
+
+         \sstitem
+          If an error occurs in the transformation function, this may be
+         indicated by setting the AST error status to an error value
+         (using \htmlref{astSetStatus}{astSetStatus}) before it returns.  This will immediately
+         terminate the current AST operation.  The error value AST\_\_ITFER
+         is available for this purpose, but other values may also be used
+         (e.g. if you wish to distinguish different types of error).
+      }
+   }
+   \sstdiytopic{
+      Transformation Flags
+   }{
+      The following flags are defined in the ``ast.h\texttt{'} \texttt{'}  header file and
+      allow you to provide further information about the nature of the
+      transformation function. Having selected the set of flags which
+      apply, you should supply the bitwise OR of their values as the
+      ``flags\texttt{'} \texttt{'}  argument to astIntraReg.
+
+      \sstitemlist{
+
+         \sstitem
+          AST\_\_NOFWD: If this flag is set, it indicates that the
+         transformation function does not implement a forward coordinate
+         transformation. In this case, any IntraMap which uses it will
+         have a \htmlref{TranForward}{TranForward} attribute value of zero and the
+         transformation function itself will not be invoked with its
+         ``forward\texttt{'} \texttt{'}  argument set to a non-zero value.  By default, it is
+         assumed that a forward transformation is provided.
+
+         \sstitem
+          AST\_\_NOINV: If this flag is set, it indicates that the
+         transformation function does not implement an inverse coordinate
+         transformation. In this case, any IntraMap which uses it will
+         have a \htmlref{TranInverse}{TranInverse} attribute value of zero and the
+         transformation function itself will not be invoked with its
+         ``forward\texttt{'} \texttt{'}  argument set to zero.  By default, it is assumed
+         that an inverse transformation is provided.
+
+         \sstitem
+          AST\_\_SIMPFI: You may set this flag if applying the
+         transformation function\texttt{'} s forward coordinate transformation,
+         followed immediately by the matching inverse transformation,
+         should always restore the original set of coordinates. It
+         indicates that AST may replace such a sequence of operations by
+         an identity Mapping (a \htmlref{UnitMap}{UnitMap}) if it is encountered while
+         simplifying a compound Mapping (e.g. using \htmlref{astSimplify}{astSimplify}).  It is
+         not necessary that both transformations have actually been
+         implemented.
+
+         \sstitem
+          AST\_\_SIMPIF: You may set this flag if applying the
+         transformation function\texttt{'} s inverse coordinate transformation,
+         followed immediately by the matching forward transformation,
+         should always restore the original set of coordinates. It
+         indicates that AST may replace such a sequence of operations by
+         an identity Mapping (a UnitMap) if it is encountered while
+         simplifying a compound Mapping (e.g. using astSimplify).  It is
+         not necessary that both transformations have actually been
+         implemented.
+      }
+   }
+}
+\sstroutine{
+   astInvert
+}{
+   Invert a Mapping
+}{
+   \sstdescription{
+      This function inverts a \htmlref{Mapping}{Mapping} by reversing the boolean sense
+      of its \htmlref{Invert}{Invert} attribute. If this attribute is zero (the
+      default), the Mapping will transform coordinates in the way
+      specified when it was created. If it is non-zero, the input and
+      output coordinates will be inter-changed so that the direction
+      of the Mapping is reversed. This will cause it to display the
+      inverse of its original behaviour.
+   }
+   \sstsynopsis{
+      void astInvert( AstMapping $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Mapping.
+      }
+   }
+}
+\sstroutine{
+   astIsA$<$Class$>$
+}{
+   Test membership of a class by an Object
+}{
+   \sstdescription{
+      This is a family of functions which test whether an \htmlref{Object}{Object} is a
+      member of the class called $<$\htmlref{Class}{Class}$>$, or of any class derived from
+      it.
+   }
+   \sstsynopsis{
+      int astIsA$<$Class$>$( const Ast$<$Class$>$ $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Object.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         These functions apply to all Objects.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astIsA$<$Class$>$()
+      }{
+         One if the Object belongs to the class called $<$Class$>$ (or to a
+         class derived from it), otherwise zero.
+      }
+   }
+   \sstexamples{
+      \sstexamplesubsection{
+         member = astIsAFrame( obj );
+      }{
+         Tests whether Object \texttt{"} obj\texttt{"}  is a member of the \htmlref{Frame}{Frame} class, or
+         of any class derived from a Frame.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Every AST class provides a function (astIsA$<$Class$>$) of this
+         form, where $<$Class$>$ should be replaced by the class name.
+
+         \sstitem
+          This function attempts to execute even if the AST error status
+         is set
+         on entry, although no further error report will be made
+         if it subsequently fails under these circumstances.
+
+         \sstitem
+          A value of zero will be returned if this function should fail
+         for any reason. In particular, it will fail if the pointer
+         supplied does not identify an Object of any sort.
+      }
+   }
+}
+\sstroutine{
+   astKeyMap
+}{
+   Create a KeyMap
+}{
+   \sstdescription{
+      This function creates a new empty \htmlref{KeyMap}{KeyMap} and optionally initialises its
+      attributes. Entries can then be added to the KeyMap using the
+      \htmlref{astMapPut0$<$X$>$}{astMapPut0$<$X$>$} and \htmlref{astMapPut1$<$X$>$}{astMapPut1$<$X$>$} functions.
+
+      The KeyMap class is used to store a set of values with associated keys
+      which identify the values. The keys are strings. These may be case
+      sensitive or insensitive as selected by the \htmlref{KeyCase}{KeyCase} attribute, and
+      trailing spaces are ignored. The value associated with a key can be
+      integer (signed 4 and 2 byte, or unsigned 1 byte), floating point
+      (single or double precision),
+      void pointer,
+      character string or AST \htmlref{Object}{Object} pointer. Each
+      value can be a scalar or a one-dimensional vector. A KeyMap is
+      conceptually similar to a \htmlref{Mapping}{Mapping} in that a KeyMap transforms an
+      input into an output - the input is the key, and the output is the
+      value associated with the key. However, this is only a conceptual
+      similarity, and it should be noted that the KeyMap class inherits from
+      the Object class rather than the Mapping class. The methods of the
+      Mapping class cannot be used with a KeyMap.
+   }
+   \sstsynopsis{
+      AstKeyMap $*$astKeyMap( const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new KeyMap. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astKeyMap()
+      }{
+         A pointer to the new KeyMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null Object pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      Status Handling
+   }{
+      The protected interface to this function includes an extra
+      parameter at the end of the parameter list descirbed above. This
+      parameter is a pointer to the integer inherited status
+      variable: \texttt{"} int $*$status\texttt{"} .
+   }
+}
+\sstroutine{
+   astLinearApprox
+}{
+   Obtain a linear approximation to a Mapping, if appropriate
+}{
+   \sstdescription{
+      This function tests the forward coordinate transformation
+      implemented by a \htmlref{Mapping}{Mapping} over a given range of input coordinates. If
+      the transformation is found to be linear to a specified level of
+      accuracy, then an array of fit coefficients is returned. These
+      may be used to implement a linear approximation to the Mapping\texttt{'} s
+      forward transformation within the specified range of output coordinates.
+      If the transformation is not sufficiently linear, no coefficients
+      are returned.
+   }
+   \sstsynopsis{
+      int astLinearApprox( AstMapping $*$this, const double $*$lbnd,
+                           const double $*$ubnd, double tol, double $*$fit )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Mapping.
+      }
+      \sstsubsection{
+         lbnd
+      }{
+         Pointer to an array of doubles
+         containing the lower bounds of a box defined within the input
+         coordinate system of the Mapping. The number of elements in this
+         array should equal the value of the Mapping\texttt{'} s \htmlref{Nin}{Nin} attribute. This
+         box should specify the region over which linearity is required.
+      }
+      \sstsubsection{
+         ubnd
+      }{
+         Pointer to an array of doubles
+         containing the upper bounds of the box specifying the region over
+         which linearity is required.
+      }
+      \sstsubsection{
+         tol
+      }{
+         The maximum permitted deviation from linearity, expressed as
+         a positive Cartesian displacement in the output coordinate
+         space of the Mapping. If a linear fit to the forward
+         transformation of the Mapping deviates from the true transformation
+         by more than this amount at any point which is tested, then no fit
+         coefficients will be returned.
+      }
+      \sstsubsection{
+         fit
+      }{
+         Pointer to an array of doubles
+         in which to return the co-efficients of the linear
+         approximation to the specified transformation. This array should
+         have at least \texttt{"} ( Nin $+$ 1 ) $*$ \htmlref{Nout}{Nout}\texttt{"} , elements. The first Nout elements
+         hold the constant offsets for the transformation outputs. The
+         remaining elements hold the gradients. So if the Mapping has 2 inputs
+         and 3 outputs the linear approximation to the forward transformation
+         is:
+
+            X\_out = fit[0] $+$ fit[3]$*$X\_in $+$ fit[4]$*$Y\_in
+
+            Y\_out = fit[1] $+$ fit[5]$*$X\_in $+$ fit[6]$*$Y\_in
+
+            Z\_out = fit[2] $+$ fit[7]$*$X\_in $+$ fit[8]$*$Y\_in
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astLinearApprox()
+      }{
+         If the forward transformation is sufficiently linear,
+         a non-zero value is returned. Otherwise zero is returned
+         and the fit co-efficients are set to AST\_\_BAD.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This function fits the Mapping\texttt{'} s forward transformation. To fit
+         the inverse transformation, the Mapping should be inverted using
+         \htmlref{astInvert}{astInvert}
+         before invoking this function.
+
+         \sstitem
+          If a Mapping output is found to have a bad value (AST\_\_BAD) at
+         one or more of the test points used in the linearity test, then all
+         the values in the returned fit that correspond to that output are
+         set to AST\_\_BAD. However, this does not affect the linearity tests
+         on the other Mapping outputs - if they are all found to be linear
+         then usable coefficients will be returned for them in the fit, and
+         the function will return a
+         non-zero value.
+         Consequently, it may be necessary to check that the values in the
+         returned fit are not AST\_\_BAD before using them. If all Mapping
+         outputs generate bad values, then
+         zero is returned as the function value.
+
+         \sstitem
+          A value of zero
+         will be returned if this function is invoked
+         with the global error status set, or if it should fail for any
+         reason.
+      }
+   }
+}
+\sstroutine{
+   astLock
+}{
+   Lock an Object for exclusive use by the calling thread
+}{
+   \sstdescription{
+      The thread-safe public interface to AST is designed so that an
+      error is reported if any thread attempts to use an \htmlref{Object}{Object} that it
+      has not previously locked for its own exclusive use using this
+      function. When an Object is created, it is initially locked by the
+      thread that creates it, so newly created objects do not need to be
+      explicitly locked. However, if an Object pointer is passed to
+      another thread, the original thread must first unlock it (using
+      \htmlref{astUnlock}{astUnlock}) and the new thread must then lock it (using astLock)
+      before the new thread can use the Object.
+
+      The \texttt{"} wait\texttt{"}  parameter determines what happens if the supplied Object
+      is curently locked by another thread when this function is invoked.
+   }
+   \sstsynopsis{
+      void astLock( AstObject $*$this, int wait )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Object to be locked.
+      }
+      \sstsubsection{
+         wait
+      }{
+         If the Object is curently locked by another thread then this
+         function will either report an error or block. If a non-zero value
+         is supplied for \texttt{"} wait\texttt{"} , the calling thread waits until the object
+         is available for it to use. Otherwise, an error is reported and
+         the function returns immediately without locking the Object.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         This function applies to all Objects.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The \htmlref{astAnnul}{astAnnul} function is exceptional in that it can be used on
+         pointers for Objects that are not currently locked by the calling
+         thread. All other AST functions will report an error.
+
+         \sstitem
+          The Locked object will belong to the current AST context.
+
+         \sstitem
+          This function returns without action if the Object is already
+         locked by the calling thread.
+
+         \sstitem
+          If simultaneous use of the same object is required by two or more
+         threads, \htmlref{astCopy}{astCopy} should be used to to produce a deep copy of
+         the Object for each thread. Each copy should then be unlocked by
+         the parent thread (i.e. the thread that created the copy), and then
+         locked by the child thread (i.e. the thread that wants to use the
+         copy).
+
+         \sstitem
+          This function is only available in the C interface.
+
+         \sstitem
+          This function returns without action if the AST library has
+         been built without POSIX thread support (i.e. the \texttt{"} -with-pthreads\texttt{"}
+         option was not specified when running the \texttt{"} configure\texttt{"}  script).
+      }
+   }
+}
+\sstroutine{
+   astLutMap
+}{
+   Create a LutMap
+}{
+   \sstdescription{
+      This function creates a new \htmlref{LutMap}{LutMap} and optionally initialises
+      its attributes.
+
+      A LutMap is a specialised form of \htmlref{Mapping}{Mapping} which transforms
+      1-dimensional coordinates by using linear interpolation in a
+      lookup table.  Each input coordinate value is first scaled to
+      give the index of an entry in the table by subtracting a
+      starting value (the input coordinate corresponding to the first
+      table entry) and dividing by an increment (the difference in
+      input coordinate value between adjacent table entries).
+
+      The resulting index will usually contain a fractional part, so
+      the output coordinate value is then generated by interpolating
+      linearly between the appropriate entries in the table. If the
+      index lies outside the range of the table, linear extrapolation
+      is used based on the two nearest entries (i.e. the two entries
+      at the start or end of the table, as appropriate).
+
+      If the lookup table entries increase or decrease monotonically,
+      then the inverse transformation may also be performed.
+   }
+   \sstsynopsis{
+      AstLutMap $*$astLutMap( int nlut, const double lut[],
+                            double start, double inc,
+                            const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         nlut
+      }{
+         The number of entries in the lookup table. This value must be
+         at least 2.
+      }
+      \sstsubsection{
+         lut
+      }{
+         An array containing the \texttt{"} nlut\texttt{"}
+         lookup table entries.
+      }
+      \sstsubsection{
+         start
+      }{
+         The input coordinate value which corresponds to the first lookup
+         table entry.
+      }
+      \sstsubsection{
+         inc
+      }{
+         The lookup table spacing (the increment in input coordinate
+         value between successive lookup table entries). This value
+         may be positive or negative, but must not be zero.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new LutMap. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astLutMap()
+      }{
+         A pointer to the new LutMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If the entries in the lookup table either increase or decrease
+         monotonically, then the new LutMap\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute will
+         have a value of one, indicating that the inverse transformation
+         can be performed. Otherwise, it will have a value of zero, so
+         that any attempt to use the inverse transformation will result
+         in an error.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      Status Handling
+   }{
+      The protected interface to this function includes an extra
+      parameter at the end of the parameter list descirbed above. This
+      parameter is a pointer to the integer inherited status
+      variable: \texttt{"} int $*$status\texttt{"} .
+   }
+}
+\sstroutine{
+   astMapBox
+}{
+   Find a bounding box for a Mapping
+}{
+   \sstdescription{
+      This function allows you to find the \texttt{"} bounding box\texttt{"}  which just
+      encloses another box after it has been transformed by a \htmlref{Mapping}{Mapping}
+      (using either its forward or inverse transformation). A typical
+      use might be to calculate the size of an image after being
+      transformed by a Mapping.
+
+      The function works on one dimension at a time. When supplied
+      with the lower and upper bounds of a rectangular region (box) of
+      input coordinate space, it finds the lowest and highest values
+      taken by a nominated output coordinate within that
+      region. Optionally, it also returns the input coordinates where
+      these bounding values are attained. It should be used repeatedly
+      to obtain the extent of the bounding box in more than one
+      dimension.
+   }
+   \sstsynopsis{
+      void astMapBox( AstMapping $*$this,
+                      const double lbnd\_in[], const double ubnd\_in[],
+                      int forward, int coord\_out,
+                      double $*$lbnd\_out, double $*$ubnd\_out,
+                      double xl[], double xu[] );
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Mapping.
+      }
+      \sstsubsection{
+         lbnd\_in
+      }{
+         Pointer to an array of double, with one element for each
+         Mapping input coordinate. This should contain the lower bound
+         of the input box in each input dimension.
+      }
+      \sstsubsection{
+         ubnd\_in
+      }{
+         Pointer to an array of double, with one element for each
+         Mapping input coordinate. This should contain the upper bound
+         of the input box in each input dimension.
+
+         Note that it is permissible for the upper bound to be less
+         than the corresponding lower bound, as the values will simply
+         be swapped before use.
+      }
+      \sstsubsection{
+         forward
+      }{
+         If this value is non-zero, then the Mapping\texttt{'} s forward
+         transformation will be used to transform the input
+         box. Otherwise, its inverse transformation will be used.
+
+         (If the inverse transformation is selected, then references
+         to \texttt{"} input\texttt{"}  and \texttt{"} output\texttt{"}  coordinates in this description
+         should be transposed. For example, the size of the \texttt{"} lbnd\_in\texttt{"}
+         and \texttt{"} ubnd\_in\texttt{"}  arrays should match the number of output
+         coordinates, as given by the Mapping\texttt{'} s \htmlref{Nout}{Nout}
+         attribute. Similarly, the \texttt{"} coord\_out\texttt{"}  parameter, below,
+         should nominate one of the Mapping\texttt{'} s input coordinates.)
+      }
+      \sstsubsection{
+         coord\_out
+      }{
+         The index of the output coordinate for which the lower and
+         upper bounds are required. This value should be at least one,
+         and no larger than the number of Mapping output coordinates.
+      }
+      \sstsubsection{
+         lbnd\_out
+      }{
+         Pointer to a double in which to return the lowest value taken
+         by the nominated output coordinate within the specified
+         region of input coordinate space.
+      }
+      \sstsubsection{
+         ubnd\_out
+      }{
+         Pointer to a double in which to return the highest value
+         taken by the nominated output coordinate within the specified
+         region of input coordinate space.
+      }
+      \sstsubsection{
+         xl
+      }{
+         An optional pointer to an array of double, with one element
+         for each Mapping input coordinate. If given, this array will
+         be filled with the coordinates of an input point (although
+         not necessarily a unique one) for which the nominated output
+         coordinate attains the lower bound value returned in
+         \texttt{"} $*$lbnd\_out\texttt{"} .
+
+         If these coordinates are not required, a NULL pointer may be
+         supplied.
+      }
+      \sstsubsection{
+         xu
+      }{
+         An optional pointer to an array of double, with one element
+         for each Mapping input coordinate. If given, this array will
+         be filled with the coordinates of an input point (although
+         not necessarily a unique one) for which the nominated output
+         coordinate attains the upper bound value returned in
+         \texttt{"} $*$ubnd\_out\texttt{"} .
+
+         If these coordinates are not required, a NULL pointer may be
+         supplied.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Any input points which are transformed by the Mapping to give
+         output coordinates containing the value AST\_\_BAD are regarded as
+         invalid and are ignored. They will make no contribution to
+         determining the output bounds, even although the nominated
+         output coordinate might still have a valid value at such points.
+
+         \sstitem
+          An error will occur if the required output bounds cannot be
+         found. Typically, this might happen if all the input points
+         which the function considers turn out to be invalid (see
+         above). The number of points considered before generating such
+         an error is quite large, so this is unlikely to occur by
+         accident unless valid points are restricted to a very small
+         subset of the input coordinate space.
+
+         \sstitem
+          The values returned via \texttt{"} lbnd\_out\texttt{"} , \texttt{"} ubnd\_out\texttt{"} , \texttt{"} xl\texttt{"}  and \texttt{"} xu\texttt{"}
+         will be set to the value AST\_\_BAD if this function should fail
+         for any reason. Their initial values on entry will not be
+         altered if the function is invoked with the AST error status
+         set.
+      }
+   }
+}
+\sstroutine{
+   astMapCopy
+}{
+   Copy entries from one KeyMap into another
+}{
+   \sstdescription{
+      This function
+      copies all entries from one \htmlref{KeyMap}{KeyMap} into another.
+   }
+   \sstsynopsis{
+      void astMapCopy( AstKeyMap $*$this, AstKeyMap $*$that )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the destination KeyMap.
+      }
+      \sstsubsection{
+         that
+      }{
+         Pointer to the source KeyMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Entries from the source KeyMap will replace any existing entries in
+         the destination KeyMap that have the same key.
+
+         \sstitem
+          The one exception to the above rule is that if a source entry
+         contains a scalar KeyMap entry, and the destination contains a
+         scalar KeyMap entry with the same key, then the source KeyMap entry
+         will be copied into the destination KeyMap entry using this function,
+         rather than simply replacing the destination KeyMap entry.
+
+         \sstitem
+          If the destination entry has a non-zero value for its \htmlref{MapLocked}{MapLocked}
+         attribute, then an error will be reported if the source KeyMap
+         contains any keys that do not already exist within the destination
+         KeyMap.
+      }
+   }
+}
+\sstroutine{
+   astMapDefined
+}{
+   Check if a KeyMap contains a defined value for a key
+}{
+   \sstdescription{
+      This function checks to see if a \htmlref{KeyMap}{KeyMap} contains a defined value for
+      a given key. If the key is present in the KeyMap but has an
+      undefined value it returns
+      zero (unlike \htmlref{astMapHasKey}{astMapHasKey} which would return non-zero).
+   }
+   \sstsynopsis{
+      int astMapDefined( AstKeyMap $*$this, const char $*$key );
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the KeyMap.
+      }
+      \sstsubsection{
+         key
+      }{
+         The character string identifying the value to be retrieved. Trailing
+         spaces are ignored. The supplied string is converted to upper
+         case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astMapDefined()
+      }{
+         A non-zero value
+         is returned if the requested key name is present in the KeyMap
+         and has a defined value.
+      }
+   }
+}
+\sstroutine{
+   astMapGet0$<$X$>$
+}{
+   Get a scalar value from a KeyMap
+}{
+   \sstdescription{
+      This is a set of functions for retrieving a scalar value from a \htmlref{KeyMap}{KeyMap}.
+      You should replace $<$X$>$ in the generic function name
+      astMapGet0$<$X$>$
+      by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"}
+      section below for the code appropriate to each supported data type).
+      The stored value is converted to the data type indiced by $<$X$>$
+      before being returned (an error is reported if it is not possible to
+      convert the stored value to the requested data type).
+   }
+   \sstsynopsis{
+      int astMapGet0$<$X$>$( AstKeyMap $*$this, const char $*$key, $<$X$>$type $*$value );
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the KeyMap.
+      }
+      \sstsubsection{
+         key
+      }{
+         The character string identifying the value to be retrieved. Trailing
+         spaces are ignored. The supplied string is converted to upper
+         case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
+      }
+      \sstsubsection{
+         value
+      }{
+         A pointer to a buffer in which to return the requested value.
+         If the requested key is not found, or if it is found but has an
+         undefined value (see
+         \htmlref{astMapPutU}{astMapPutU}),
+         then the contents of the
+         buffer on entry to this function will be unchanged on exit.
+         For pointer types (\texttt{"} A\texttt{"}  and \texttt{"} C\texttt{"} ), the buffer should be a suitable
+         pointer, and the address of this pointer should be supplied as the
+         \texttt{"} value\texttt{"}  parameter.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astMapGet0$<$X$>$()
+      }{
+         A non-zero value
+         is returned if the requested key name was found, and does not have
+         an undefined value (see
+         astMapPutU). Zero
+         is returned otherwise.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          No error is reported if the requested key cannot be found in the
+         given KeyMap, but a
+         zero
+         value will be returned as the function value. The supplied buffer
+         will be returned unchanged.
+
+         \sstitem
+          If the stored value is a vector value, then the first value in
+         the vector will be returned.
+
+         \sstitem
+          A string pointer returned by astMapGet0C is guaranteed to remain valid
+         and the string to which it points will not be over-written for a
+         total of 50 successive invocations of this function. After this,
+         the memory containing the string may be re-used, so a copy of
+         the string should be made if it is needed for longer than this. The
+         calling code should never attempt to free the returned pointer
+         (for instance, using \htmlref{astFree}{astFree}).
+
+         \sstitem
+          If the returned value is an AST \htmlref{Object}{Object} pointer, the Object\texttt{'} s reference
+         count is incremented by this call. Any subsequent changes made to
+         the Object using the returned pointer will be reflected in any
+         any other active pointers for the Object. The returned pointer
+         should be annulled using
+         \htmlref{astAnnul}{astAnnul}
+         when it is no longer needed.
+      }
+   }
+   \sstdiytopic{
+      Data Type Codes
+   }{
+      To select the appropriate
+      function, you should replace $<$X$>$ in the generic function name astMapGet0$<$X$>$
+      with a 1-character data type code, so as to match the data type $<$X$>$type
+      of the data you are processing, as follows:
+      \sstitemlist{
+
+         \sstitem
+          F: float
+
+         \sstitem
+          D: double
+
+         \sstitem
+          I: int
+
+         \sstitem
+          C: \texttt{"} const\texttt{"}  pointer to null terminated character string
+
+         \sstitem
+          A: Pointer to AstObject
+
+         \sstitem
+          P: Generic \texttt{"} void $*$\texttt{"}  pointer
+
+         \sstitem
+          S: short int
+
+         \sstitem
+          B: Unsigned byte (i.e. word)
+
+      }
+      For example, astMapGet0D would be used to get a \texttt{"} double\texttt{"}  value,
+      while astMapGet0I would be used to get an \texttt{"} int\texttt{"} , etc.
+   }
+}
+\sstroutine{
+   astMapGet1$<$X$>$
+}{
+   Get a vector value from a KeyMap
+}{
+   \sstdescription{
+      This is a set of functions for retrieving a vector value from a \htmlref{KeyMap}{KeyMap}.
+      You should replace $<$X$>$ in the generic function name
+      astMapGet1$<$X$>$
+      by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"}
+      section below for the code appropriate to each supported data type).
+      The stored value is converted to the data type indiced by $<$X$>$
+      before being returned (an error is reported if it is not possible to
+      convert the stored value to the requested data type).
+      Note, the astMapGet1C function has an extra parameter \texttt{"} l\texttt{"}  which
+      specifies the maximum length of each string to be stored in the
+      \texttt{"} value\texttt{"}  buffer (see the \texttt{"} astMapGet1C\texttt{"}  section below).
+   }
+   \sstsynopsis{
+      int astMapGet1$<$X$>$( AstKeyMap $*$this, const char $*$key, int mxval,
+                         int $*$nval, $<$X$>$type $*$value )
+      int astMapGet1C( AstKeyMap $*$this, const char $*$key, int l, int mxval,
+                       int $*$nval, const char $*$value )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the KeyMap.
+      }
+      \sstsubsection{
+         key
+      }{
+         The character string identifying the value to be retrieved. Trailing
+         spaces are ignored.
+         The supplied string is converted to upper case before use if the
+         \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
+      }
+      \sstsubsection{
+         mxval
+      }{
+         The number of elements in the
+         \texttt{"} value\texttt{"}  array.
+      }
+      \sstsubsection{
+         nval
+      }{
+         The address of an integer in which to put the
+         number of elements stored in the
+         \texttt{"} value\texttt{"}  array.
+         Any unused elements of the array are left unchanged.
+      }
+      \sstsubsection{
+         value
+      }{
+         A pointer to an array in which to return the requested values.
+         If the requested key is not found, or if it is found but has an
+         undefined value (see
+         \htmlref{astMapPutU}{astMapPutU}),
+         then the contents of the
+         buffer on entry to this function will be unchanged on exit.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astMapGet1$<$X$>$()
+      }{
+         A non-zero value
+         is returned if the requested key name was found, and does not have
+         an undefined value (see
+         astMapPutU). Zero
+         is returned otherwise.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          No error is reported if the requested key cannot be found in the
+         given KeyMap, but a
+         zero
+         value will be returned as the function value. The supplied array
+         will be returned unchanged.
+
+         \sstitem
+          If the stored value is a scalar value, then the value will be
+         returned in the first element of the supplied array, and
+         \texttt{"} nval\texttt{"}
+         will be returned set to 1.
+      }
+   }
+   \sstdiytopic{
+      astMapGet1C
+   }{
+      The \texttt{"} value\texttt{"}  buffer supplied to the astMapGet1C function should be a
+      pointer to a character array with \texttt{"} mxval$*$l\texttt{"}  elements, where \texttt{"} l\texttt{"}  is
+      the maximum length of a string to be returned. The value of \texttt{"} l\texttt{"}
+      should be supplied as an extra parameter following \texttt{"} key\texttt{"}  when
+      invoking astMapGet1C, and should include space for a terminating
+      null character.
+   }
+   \sstdiytopic{
+      Data Type Codes
+   }{
+      To select the appropriate
+      function, you should replace $<$X$>$ in the generic function name astMapGet1$<$X$>$
+      with a 1-character data type code, so as to match the data type $<$X$>$type
+      of the data you are processing, as follows:
+      \sstitemlist{
+
+         \sstitem
+          D: double
+
+         \sstitem
+          F: float
+
+         \sstitem
+          I: int
+
+         \sstitem
+          C: \texttt{"} const\texttt{"}  pointer to null terminated character string
+
+         \sstitem
+          A: Pointer to AstObject
+
+         \sstitem
+          P: Generic \texttt{"} void $*$\texttt{"}  pointer
+
+         \sstitem
+          S: short int
+
+         \sstitem
+          B: Unsigned byte (i.e. char)
+
+      }
+      For example, astMapGet1D would be used to get \texttt{"} double\texttt{"}  values, while
+      astMapGet1I would be used to get \texttt{"} int\texttt{"}  values, etc. For D or I, the
+      supplied \texttt{"} value\texttt{"}  parameter should be a pointer to an array of doubles
+      or ints, with \texttt{"} mxval\texttt{"}  elements. For C, the supplied \texttt{"} value\texttt{"}  parameter
+      should be a pointer to a character string with \texttt{"} mxval$*$l\texttt{"}  elements.
+      For A, the supplied \texttt{"} value\texttt{"}  parameter should be a pointer to an
+      array of AstObject pointers.
+   }
+}
+\sstroutine{
+   astMapGetC
+}{
+   Get a scalar or vector value from a KeyMap as a single string
+}{
+   \sstdescription{
+      This function gets a named value from a \htmlref{KeyMap}{KeyMap} as a single string.
+      For scalar values it is equivalent to
+      astMapGet0C.
+      If the value is a vector, the returned string is a comma-separated
+      list of the vector elements, enclosed in parentheses.
+   }
+   \sstsynopsis{
+      int astMapGetC( AstKeyMap $*$this, const char $*$key, const char $*$$*$value );
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the KeyMap.
+      }
+      \sstsubsection{
+         key
+      }{
+         The character string identifying the value to be retrieved. Trailing
+         spaces are ignored. The supplied string is converted to upper
+         case before use if the \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
+      }
+      \sstsubsection{
+         value
+      }{
+         Address at which to return a pointer to the required string value.
+         If the requested key is not found, or if it is found but has an
+         undefined value (see
+         \htmlref{astMapPutU}{astMapPutU}), then the contents of the supplied pointer
+         are unchanged on exit.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astMapGetC()
+      }{
+         A non-zero value
+         is returned if the requested key name was found, and does not have
+         an undefined value (see
+         astMapPutU). Zero
+         is returned otherwise.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          No error is reported if the requested key cannot be found in the
+         given KeyMap, but a
+         zero
+         value will be returned as the function value. The supplied buffer
+         will be returned unchanged.
+
+         \sstitem
+          The string pointer returned by astMapGetC is guaranteed to remain valid
+         and the string to which it points will not be over-written for a
+         total of 50 successive invocations of this function. After this,
+         the memory containing the string may be re-used, so a copy of
+         the string should be made if it is needed for longer than this. The
+         calling code should never attempt to free the returned pointer
+         (for instance, using \htmlref{astFree}{astFree}).
+      }
+   }
+}
+\sstroutine{
+   astMapGetElem$<$X$>$
+}{
+   Get a single element of a vector value from a KeyMap
+}{
+   \sstdescription{
+      This is a set of functions for retrieving a single element of a vector
+      value from a \htmlref{KeyMap}{KeyMap}. You should replace $<$X$>$ in the generic function name
+      astMapGetElem$<$X$>$
+      by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"}
+      section below for the code appropriate to each supported data type).
+      The stored value is converted to the data type indiced by $<$X$>$
+      before being returned (an error is reported if it is not possible to
+      convert the stored value to the requested data type).
+      Note, the astMapGetElemC function has an extra parameter \texttt{"} l\texttt{"}  which
+      specifies the maximum length of the string to be stored in the
+      \texttt{"} value\texttt{"}  buffer (see the \texttt{"} astMapGetElemC\texttt{"}  section below).
+   }
+   \sstsynopsis{
+      int astMapGetElem$<$X$>$( AstKeyMap $*$this, const char $*$key, int elem,
+                            $<$X$>$type $*$value )
+      int astMapGetElemC( AstKeyMap $*$this, const char $*$key, int l, int elem,
+                          char $*$value )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the KeyMap.
+      }
+      \sstsubsection{
+         key
+      }{
+         The character string identifying the value to be retrieved. Trailing
+         spaces are ignored.
+         The supplied string is converted to upper case before use if the
+         \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
+      }
+      \sstsubsection{
+         elem
+      }{
+         The index of the required vector element, starting at
+         zero.
+         An error will be reported if the value is outside the range of
+         the vector.
+      }
+      \sstsubsection{
+         value
+      }{
+         A pointer to a buffer in which to return the requested value.
+         If the requested key is not found, or if it is found but has an
+         undefined value (see
+         \htmlref{astMapPutU}{astMapPutU}),
+         then the contents of the
+         buffer on entry to this function will be unchanged on exit.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astMapGetElem$<$X$>$()
+      }{
+         A non-zero value
+         is returned if the requested key name was found, and does not have
+         an undefined value (see
+         astMapPutU). Zero
+         is returned otherwise.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          No error is reported if the requested key cannot be found in the
+         given KeyMap, or if it has an undefined value, but a
+         zero
+         value will be returned as the function value.
+      }
+   }
+   \sstdiytopic{
+      astMapGetElemC
+   }{
+      The \texttt{"} value\texttt{"}  buffer supplied to the astMapGetElemC function should be a
+      pointer to a character array with \texttt{"} l\texttt{"}  elements, where \texttt{"} l\texttt{"}  is the
+      maximum length of the string to be returned. The value of \texttt{"} l\texttt{"}
+      should be supplied as an extra parameter following \texttt{"} key\texttt{"}  when
+      invoking astMapGetElemC, and should include space for a terminating
+      null character.
+   }
+   \sstdiytopic{
+      Data Type Codes
+   }{
+      To select the appropriate
+      function, you should replace $<$X$>$ in the generic function name
+      astMapGetElem$<$X$>$
+      with a 1-character data type code, so as to match the data type $<$X$>$type
+      of the data you are processing, as follows:
+      \sstitemlist{
+
+         \sstitem
+          D: double
+
+         \sstitem
+          F: float
+
+         \sstitem
+          I: int
+
+         \sstitem
+          C: \texttt{"} const\texttt{"}  pointer to null terminated character string
+
+         \sstitem
+          A: Pointer to AstObject
+
+         \sstitem
+          P: Generic \texttt{"} void $*$\texttt{"}  pointer
+
+         \sstitem
+          S: short int
+
+         \sstitem
+          B: Unsigned byte (i.e. char)
+
+      }
+      For example, astMapGetElemD would be used to get a \texttt{"} double\texttt{"}  value, while
+      astMapGetElemI would be used to get an \texttt{"} int\texttt{"}  value, etc. For D or I, the
+      supplied \texttt{"} value\texttt{"}  parameter should be a pointer to a double or int. For
+      C, the supplied \texttt{"} value\texttt{"}  parameter should be a pointer to a character
+      string with \texttt{"} l\texttt{"}  elements. For A, the supplied \texttt{"} value\texttt{"}  parameter should
+      be a pointer to an AstObject pointer.
+   }
+}
+\sstroutine{
+   astMapHasKey
+}{
+   Check if an entry with a given key exists in a KeyMap
+}{
+   \sstdescription{
+      This function returns a flag indicating if the \htmlref{KeyMap}{KeyMap} contains an
+      entry with the given key.
+   }
+   \sstsynopsis{
+      int astMapHasKey( AstKeyMap $*$this, const char $*$key )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the KeyMap.
+      }
+      \sstsubsection{
+         key
+      }{
+         The character string identifying the KeyMap entry. Trailing spaces are
+         ignored.
+         The supplied string is converted to upper case before use if the
+         \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astMapHasKey()
+      }{
+         Non-zero if the key was found, and zero otherwise.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A non-zero function value
+         is returned if the key exists but has an undefined value (that is,
+         the returned value does not depend on whether the entry has a
+         defined value or not). See also
+         \htmlref{astMapDefined}{astMapDefined}, which returns zero in such a case.
+
+         \sstitem
+          A function value of
+         zero
+         will be returned if an error has already occurred, or if this
+         function should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astMapKey
+}{
+   Get the key at a given index within the KeyMap
+}{
+   \sstdescription{
+      This function returns a string holding the key for the entry with
+      the given index within the \htmlref{KeyMap}{KeyMap}.
+
+      This function is intended primarily as a means of iterating round all
+      the elements in a KeyMap. For this purpose, the number of entries in
+      the KeyMap should first be found using
+      \htmlref{astMapSize}{astMapSize}
+      and this function should then be called in a loop, with the index
+      value going from
+      zero to one less than the size of the KeyMap.
+      The index associated with a given entry is determined by the \htmlref{SortBy}{SortBy}
+      attribute.
+   }
+   \sstsynopsis{
+      const char $*$astMapKey( AstKeyMap $*$this, int index )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the KeyMap.
+      }
+      \sstsubsection{
+         index
+      }{
+         The index into the KeyMap. The first entry has index
+         zero, and the last has index \texttt{"} size-1\texttt{"} , where \texttt{"} size\texttt{"}  is the value
+         returned by the astMapSize function.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astMapKey()
+      }{
+         A pointer to a null-terminated string containing the key.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The returned pointer is guaranteed to remain valid and the
+         string to which it points will not be over-written for a total
+         of 50 successive invocations of this function. After this, the
+         memory containing the string may be re-used, so a copy of the
+         string should be made if it is needed for longer than this.
+
+         \sstitem
+          A NULL pointer will be returned if this function is invoked
+         with the AST error status set, or if it should fail for any
+         reason.
+      }
+   }
+}
+\sstroutine{
+   astMapLenC
+}{
+   Get the number of characters in a character entry in a KeyMap
+}{
+   \sstdescription{
+      This function returns the minimum length that a character variable
+      must have in order to be able to store a specified entry in
+      the supplied \htmlref{KeyMap}{KeyMap}. If the named entry is a vector entry, then the
+      returned value is the length of the longest element of the vector
+      value.
+   }
+   \sstsynopsis{
+      int astMapLenC( AstKeyMap $*$this, const char $*$key )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the KeyMap.
+      }
+      \sstsubsection{
+         key
+      }{
+         The character string identifying the KeyMap entry. Trailing
+         spaces are ignored.
+         The supplied string is converted to upper case before use if the
+         \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astMapLenC()
+      }{
+         The length (i.e. number of characters) of the longest formatted
+         value associated with the named entry.
+         This does not include the trailing null character.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A function value of zero will be returned without error if the
+         named entry cannot be formatted as a character string.
+
+         \sstitem
+          A function value of zero will be returned if an error has already
+         occurred, or if this function should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astMapLength
+}{
+   Get the vector length of an entry in a KeyMap
+}{
+   \sstdescription{
+      This function returns the vector length of a named entry in a \htmlref{KeyMap}{KeyMap},
+      (that is, how many values are associated with the entry).
+   }
+   \sstsynopsis{
+      int astMapLength( AstKeyMap $*$this, const char $*$key )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the KeyMap.
+      }
+      \sstsubsection{
+         key
+      }{
+         The character string identifying the KeyMap entry. Trailing
+         spaces are ignored.
+         The supplied string is converted to upper case before use if the
+         \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astMapLength()
+      }{
+         The length of the entry. One for a scalar, greater than one for
+         a vector. A value of zero is returned if the KeyMap does not
+         contain the named entry.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A function value of zero will be returned if an error has already
+         occurred, or if this function should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astMapPut0$<$X$>$
+}{
+   Add a scalar value to a KeyMap
+}{
+   \sstdescription{
+      This is a set of functions
+      for adding scalar values to a \htmlref{KeyMap}{KeyMap}. You should use a
+      function
+      which matches the data type of the data you wish to add to the KeyMap
+      by replacing $<$X$>$ in the generic
+      function name astMapPut0$<$X$>$
+      by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"}
+      section below for the code appropriate to each supported data type).
+   }
+   \sstsynopsis{
+      void astMapPut0$<$X$>$( AstKeyMap $*$this, const char $*$key, $<$X$>$type value,
+                          const char $*$comment );
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the KeyMap in which to store the supplied value.
+      }
+      \sstsubsection{
+         key
+      }{
+         A character string to be stored with the value, which can later
+         be used to identify the value. Trailing spaces are ignored.
+         The supplied string is converted to upper case before use if the
+         \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
+      }
+      \sstsubsection{
+         value
+      }{
+         The value to be stored. The data type of this value should match the
+         1-character type code appended to the
+         function name (e.g. if you are using astMapPut0A, the type of this
+         value should be \texttt{"} pointer to AstObject\texttt{"} ).
+      }
+      \sstsubsection{
+         comment
+      }{
+         A pointer to a null-terminated comment string to be stored with the
+         value. A NULL pointer may be supplied, in which case no comment is
+         stored.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If the supplied key is already in use in the KeyMap, the new value
+         will replace the old value.
+
+         \sstitem
+          If the stored value is an AST \htmlref{Object}{Object} pointer, the Object\texttt{'} s reference
+         count is incremented by this call. Any subsequent changes made to
+         the Object using the returned pointer will be reflected in any
+         any other active pointers for the Object, including any obtained
+         later using
+         astMapget0A.
+         The reference count for the Object will be decremented when the
+         KeyMap is destroyed, or the entry is removed or over-written with a
+         different pointer.
+      }
+   }
+   \sstdiytopic{
+      Data Type Codes
+   }{
+      To select the appropriate
+      function, you should replace $<$X$>$ in the generic function name astMapPut0$<$X$>$
+      with a 1-character data type code, so as to match the data type $<$X$>$type
+      of the data you are processing, as follows:
+      \sstitemlist{
+
+         \sstitem
+          D: double
+
+         \sstitem
+          F: float
+
+         \sstitem
+          I: int
+
+         \sstitem
+          C: \texttt{"} const\texttt{"}  pointer to null terminated character string
+
+         \sstitem
+          A: Pointer to AstObject
+
+         \sstitem
+          P: Generic \texttt{"} void $*$\texttt{"}  pointer
+
+         \sstitem
+          S: short int
+
+         \sstitem
+          B: unsigned byte (i.e. unsigned char)
+
+      }
+      For example, astMapPut0D would be used to store a \texttt{"} double\texttt{"}  value,
+      while astMapPut0I would be used to store an \texttt{"} int\texttt{"} , etc.
+
+      Note that KeyMaps containing generic \texttt{"} void $*$\texttt{"}  pointers cannot be
+      written out using \htmlref{astShow}{astShow} or \htmlref{astWrite}{astWrite}. An error will be reported if
+      this is attempted.
+   }
+}
+\sstroutine{
+   astMapPut1$<$X$>$
+}{
+   Add a vector value to a KeyMap
+}{
+   \sstdescription{
+      This is a set of functions
+      for adding vector values to a \htmlref{KeyMap}{KeyMap}. You should use a
+      function
+      which matches the data type of the data you wish to add to the KeyMap
+      by replacing $<$X$>$ in the generic
+      function name astMapPut1$<$X$>$
+      by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"}
+      section below for the code appropriate to each supported data type).
+   }
+   \sstsynopsis{
+      void astMapPut1$<$X$>$( AstKeyMap $*$this, const char $*$key, int size,
+                          const $<$X$>$type value[], const char $*$comment );
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the KeyMap in which to store the supplied values.
+      }
+      \sstsubsection{
+         key
+      }{
+         A character string to be stored with the values, which can later
+         be used to identify the values. Trailing spaces are ignored.
+         The supplied string is converted to upper case before use if the
+         \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
+      }
+      \sstsubsection{
+         size
+      }{
+         The number of elements in the supplied array of values.
+      }
+      \sstsubsection{
+         value
+      }{
+         The array of values to be stored. The data type of this value should
+         match the 1-character type code appended to the
+         function name (e.g. if you are using astMapPut1A, the type of this
+         value should be \texttt{"} array of pointers to AstObject\texttt{"} ).
+      }
+      \sstsubsection{
+         comment
+      }{
+         A pointer to a null-terminated comment string to be stored with the
+         values. A NULL pointer may be supplied, in which case no comment is
+         stored.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If the supplied key is already in use in the KeyMap, the new values
+         will replace the old values.
+      }
+   }
+   \sstdiytopic{
+      Data Type Codes
+   }{
+      To select the appropriate
+      function, you should replace $<$X$>$ in the generic function name astMapPut1$<$X$>$
+      with a 1-character data type code, so as to match the data type $<$X$>$type
+      of the data you are processing, as follows:
+      \sstitemlist{
+
+         \sstitem
+          D: double
+
+         \sstitem
+          F: float
+
+         \sstitem
+          I: int
+
+         \sstitem
+          C: \texttt{"} const\texttt{"}  pointer to null terminated character string
+
+         \sstitem
+          A: Pointer to AstObject
+
+         \sstitem
+          P: Generic \texttt{"} void $*$\texttt{"}  pointer
+
+         \sstitem
+          S: short int
+
+         \sstitem
+          B: Unsigned byte (i.e. char)
+
+      }
+      For example, astMapPut1D would be used to store \texttt{"} double\texttt{"}  values,
+      while astMapPut1I would be used to store \texttt{"} int\texttt{"} , etc.
+
+      Note that KeyMaps containing generic \texttt{"} void $*$\texttt{"}  pointers cannot be
+      written out using \htmlref{astShow}{astShow} or \htmlref{astWrite}{astWrite}. An error will be reported if
+      this is attempted.
+   }
+}
+\sstroutine{
+   astMapPutElem$<$X$>$
+}{
+   Put a value into an element of a vector value in a KeyMap
+}{
+   \sstdescription{
+      This is a set of functions for storing a value in a single element of
+      a vector value in a \htmlref{KeyMap}{KeyMap}. You should replace $<$X$>$ in the generic
+      function name
+      astMapPutElem$<$X$>$
+      by an appropriate 1-character type code (see the \texttt{"} Data Type Codes\texttt{"}
+      section below for the code appropriate to each supported data type).
+      The supplied value is converted from the data type indicated by $<$X$>$
+      to the data type of the KeyMap entry before being stored (an error
+      is reported if it is not possible to convert the value to the
+      required data type).
+   }
+   \sstsynopsis{
+      void astMapPutElem$<$X$>$( AstKeyMap $*$this, const char $*$key, int elem,
+                             $<$X$>$type value )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the KeyMap.
+      }
+      \sstsubsection{
+         key
+      }{
+         The character string identifying the value to be retrieved. Trailing
+         spaces are ignored.
+         The supplied string is converted to upper case before use if the
+         \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
+      }
+      \sstsubsection{
+         elem
+      }{
+         The index of the vector element to modify, starting at
+         zero.
+      }
+      \sstsubsection{
+         value
+      }{
+         The value to store.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         KeyMap
+      }{
+         If the
+         \texttt{"} elem\texttt{"}
+         index is outside the range of the vector, the length of
+         the vector will be increased by one element and the supplied
+         value will be stored at the end of the vector in the new element.
+      }
+      \sstsubsection{
+         \htmlref{Table}{Table}
+      }{
+         If the
+         \texttt{"} elem\texttt{"}
+         index is outside the range of the vector, an error will be
+         reported. The number of elements in each cell of a column is
+         specified when the column is created using
+         \htmlref{astAddColumn}{astAddColumn}.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If the entry originally holds a scalar value, it will be treated
+         like a vector entry of length 1.
+
+         \sstitem
+          If the specified key cannot be found in the given KeyMap, or is
+         found but has an undefined value, a new
+         vector entry with the given name, and data type implied by $<$X$>$, is
+         created and the supplied value is stored in its first entry.
+      }
+   }
+   \sstdiytopic{
+      Data Type Codes
+   }{
+      To select the appropriate
+      function, you should replace $<$X$>$ in the generic function name
+      astMapPutElem$<$X$>$
+      with a 1-character data type code, so as to match the data type $<$X$>$type
+      of the data you are processing, as follows:
+      \sstitemlist{
+
+         \sstitem
+          D: double
+
+         \sstitem
+          F: float
+
+         \sstitem
+          I: int
+
+         \sstitem
+          C: \texttt{"} const\texttt{"}  pointer to null terminated character string
+
+         \sstitem
+          A: Pointer to AstObject
+
+         \sstitem
+          P: Generic \texttt{"} void $*$\texttt{"}  pointer
+
+         \sstitem
+          S: short int
+
+         \sstitem
+          B: Unsigned byte (i.e. char)
+
+      }
+      For example, astMapPutElemD would be used to put a \texttt{"} double\texttt{"}  value, while
+      astMapPutElemI would be used to put an \texttt{"} int\texttt{"}  value, etc. For D or I, the
+      supplied \texttt{"} value\texttt{"}  parameter should be a double or int. For
+      C, the supplied \texttt{"} value\texttt{"}  parameter should be a pointer to a character
+      string. For A, the supplied \texttt{"} value\texttt{"}  parameter should be an AstObject
+      pointer.
+   }
+}
+\sstroutine{
+   astMapPutU
+}{
+   Add an entry to a KeyMap with an undefined value
+}{
+   \sstdescription{
+      This function
+      adds a new entry to a \htmlref{KeyMap}{KeyMap}, but no value is stored with the
+      entry. The entry therefore has a special data type represented by
+      symbolic constant AST\_\_UNDEFTYPE.
+
+      An example use is to add entries with undefined values to a KeyMap
+      prior to locking them with the \htmlref{MapLocked}{MapLocked} attribute. Such entries
+      can act as placeholders for values that can be added to the KeyMap
+      later.
+   }
+   \sstsynopsis{
+      void astMapPutU( AstKeyMap $*$this, const char $*$key, const char $*$comment );
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the KeyMap in which to store the supplied value.
+      }
+      \sstsubsection{
+         key
+      }{
+         A character string to be stored with the value, which can later
+         be used to identify the value. Trailing spaces are ignored.
+         The supplied string is converted to upper case before use if the
+         \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
+      }
+      \sstsubsection{
+         comment
+      }{
+         A pointer to a null-terminated comment string to be stored with the
+         value. A NULL pointer may be supplied, in which case no comment is
+         stored.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If the supplied key is already in use in the KeyMap, the value
+         associated with the key will be removed.
+      }
+   }
+}
+\sstroutine{
+   astMapRegion
+}{
+   Transform a Region into a new Frame using a given Mapping
+}{
+   \sstdescription{
+      This function returns a pointer to a new \htmlref{Region}{Region} which corresponds to
+      supplied Region described by some other specified coordinate system. A
+      \htmlref{Mapping}{Mapping} is supplied which transforms positions between the old and new
+      coordinate systems. The new Region may not be of the same class as
+      the original region.
+   }
+   \sstsynopsis{
+      AstRegion $*$astMapRegion( AstRegion $*$this, AstMapping $*$map,
+                               AstFrame $*$frame )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Region.
+      }
+      \sstsubsection{
+         map
+      }{
+         Pointer to a Mapping which transforms positions from the
+         coordinate system represented by the supplied Region to the
+         coordinate system specified by
+         \texttt{"} frame\texttt{"} .
+         The supplied Mapping should define both forward and inverse
+         transformations, and these transformations should form a genuine
+         inverse pair. That is, transforming a position using the forward
+         transformation and then using the inverse transformation should
+         produce the original input position. Some Mapping classes (such
+         as \htmlref{PermMap}{PermMap}, \htmlref{MathMap}{MathMap}, \htmlref{SphMap}{SphMap}) can result in Mappings for which this
+         is not true.
+      }
+      \sstsubsection{
+         frame
+      }{
+         Pointer to a \htmlref{Frame}{Frame} describing the coordinate system in which
+         the new Region is required.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astMapRegion()
+      }{
+         A pointer to a new Region. This Region will represent the area
+         within the coordinate system specified by
+         \texttt{"} frame\texttt{"}
+         which corresponds to the supplied Region.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The uncertainty associated with the supplied Region is modified
+         using the supplied Mapping.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astMapRemove
+}{
+   Removed a named entry from a KeyMap
+}{
+   \sstdescription{
+      This function
+      removes a named entry from a \htmlref{KeyMap}{KeyMap}. It returns without action if the
+      KeyMap does not contain the specified key.
+   }
+   \sstsynopsis{
+      void astMapRemove( AstKeyMap $*$this, const char $*$key )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the KeyMap.
+      }
+      \sstsubsection{
+         key
+      }{
+         The character string identifying the value to be retrieved. Trailing
+         spaces are ignored.
+         The supplied string is converted to upper case before use if the
+         \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
+      }
+   }
+}
+\sstroutine{
+   astMapRename
+}{
+   Rename an existing KeyMap entry
+}{
+   \sstdescription{
+      This function
+      associated a new key with an existing entry in a \htmlref{KeyMap}{KeyMap}. It returns
+      without action if the oldkey does not exist in the KeyMap.
+   }
+   \sstsynopsis{
+      void astMapRename( AstKeyMap $*$this, const char $*$oldkey, const char $*$newkey )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the KeyMap.
+      }
+      \sstsubsection{
+         oldkey
+      }{
+         The character string identifying the entry to be renamed. Trailing
+         spaces are ignored.
+         The supplied string is converted to upper case before use if the
+         \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
+      }
+      \sstsubsection{
+         newkey
+      }{
+         The new character string to associated with the renamed entry.
+         Trailing spaces are ignored.
+         The supplied string is converted to upper case before use if the
+         KeyCase attribute is currently set to zero.
+      }
+   }
+}
+\sstroutine{
+   astMapSize
+}{
+   Get the number of entries in a KeyMap
+}{
+   \sstdescription{
+      This function returns the number of entries in a \htmlref{KeyMap}{KeyMap}.
+   }
+   \sstsynopsis{
+      int astMapSize( AstKeyMap $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the KeyMap.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astMapSize()
+      }{
+         The number of entries in the KeyMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A function value of zero will be returned if an error has already
+         occurred, or if this function should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astMapSplit
+}{
+   Split a Mapping up into parallel component Mappings
+}{
+   \sstdescription{
+      This function
+      creates a new \htmlref{Mapping}{Mapping} which connects specified inputs within a
+      supplied Mapping to the corresponding outputs of the supplied Mapping.
+      This is only possible if the specified inputs correspond to some
+      subset of the Mapping outputs. That is, there must exist a subset of
+      the Mapping outputs for which each output depends only on the selected
+      Mapping inputs, and not on any of the inputs which have not been
+      selected. Also, any output which is not in this subset must not depend
+      on any of the selected inputs. If these conditions are not met by the
+      supplied Mapping, then
+      a NULL
+      Mapping pointer is returned.
+   }
+   \sstsynopsis{
+      void astMapSplit( AstMapping $*$this, int nin, const int $*$in, int $*$out,
+                        AstMapping $*$$*$map )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Mapping to be split.
+      }
+      \sstsubsection{
+         nin
+      }{
+         The number of inputs to pick from \texttt{"} this\texttt{"} .
+      }
+      \sstsubsection{
+         in
+      }{
+         Pointer to an
+         array holding the indices within the supplied Mapping of the inputs
+         which are to be picked from the Mapping.
+         This array should have \texttt{"} nin\texttt{"}  elements.
+         If \texttt{"} \htmlref{Nin}{Nin}\texttt{"}  is the number of inputs of the supplied Mapping, then each
+         element should have a value in the range 1 to Nin.
+      }
+      \sstsubsection{
+         out
+      }{
+         Pointer to an
+         array in which to return the indices of the outputs of the supplied
+         Mapping which are fed by the picked inputs. A value of one is
+         used to refer to the first Mapping output. The supplied array should
+         have a length at least equal to the number of outputs in the
+         supplied Mapping. The number of values stored in the array on
+         exit will equal the number of outputs in the returned Mapping.
+         The i\texttt{'} th element in the returned array holds the index within
+         the supplied Mapping which corresponds to the i\texttt{'} th output of
+         the returned Mapping.
+      }
+      \sstsubsection{
+         map
+      }{
+         Address of a location at which to return a pointer to the
+         returned Mapping. This Mapping will have
+         \texttt{"} nin\texttt{"}  inputs (the number of outputs may be different to \texttt{"} nin\texttt{"} ). NULL
+         is returned if the supplied Mapping has no subset of outputs which
+         depend only on the selected inputs. The returned Mapping is a
+         deep copy of the required parts of the supplied Mapping.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If this
+         function
+         is invoked with the global error status set, or if it should fail for
+         any reason, then
+         a NULL value
+         will be returned for
+         the \texttt{"} map\texttt{"}  pointer.
+      }
+   }
+}
+\sstroutine{
+   astMapType
+}{
+   Get the data type of an entry in a KeyMap
+}{
+   \sstdescription{
+      This function returns a value indicating the data type of a
+      named entry in a \htmlref{KeyMap}{KeyMap}. This is the data type which was used when the
+      entry was added to the KeyMap.
+   }
+   \sstsynopsis{
+      int astMapType( AstKeyMap $*$this, const char $*$key )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the KeyMap.
+      }
+      \sstsubsection{
+         key
+      }{
+         The character string identifying the KeyMap entry. Trailing
+         spaces are ignored.
+         The supplied string is converted to upper case before use if the
+         \htmlref{KeyCase}{KeyCase} attribute is currently set to zero.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astMapType()
+      }{
+         One of AST\_\_INTTYPE (for integer), AST\_\_SINTTYPE (for
+         short int),
+         AST\_\_BYTETYPE (for unsigned bytes
+         \sstitemlist{
+
+            \sstitem
+             i.e. unsigned chars
+            ) AST\_\_DOUBLETYPE (for double
+            precision floating point), AST\_\_FLOATTYPE (for single
+            precision floating point), AST\_\_STRINGTYPE (for character string),
+            AST\_\_OBJECTTYPE (for AST \htmlref{Object}{Object} pointer), AST\_\_POINTERTYPE (for
+            arbitrary C pointer) or AST\_\_UNDEFTYPE (for undefined values
+            created by
+            \htmlref{astMapPutU}{astMapPutU}).
+            AST\_\_BADTYPE is returned if the supplied key is not found in the KeyMap.
+         }
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A function value of AST\_\_BADTYPE will be returned if an error has
+         already occurred, or if this function should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astMark
+}{
+   Draw a set of markers for a Plot
+}{
+   \sstdescription{
+      This function draws a set of markers (symbols) at positions
+      specified in the physical coordinate system of a \htmlref{Plot}{Plot}. The
+      positions are transformed into graphical coordinates to
+      determine where the markers should appear within the plotting
+      area.
+   }
+   \sstsynopsis{
+      void astMark( AstPlot $*$this, int nmark, int ncoord, int indim,
+                    const double $*$in, int type )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Plot.
+      }
+      \sstsubsection{
+         nmark
+      }{
+         The number of markers to draw. This may be zero, in which
+         case nothing will be drawn.
+      }
+      \sstsubsection{
+         ncoord
+      }{
+         The number of coordinates being supplied for each mark
+         (i.e. the number of axes in the current \htmlref{Frame}{Frame} of the Plot, as
+         given by its \htmlref{Naxes}{Naxes} attribute).
+      }
+      \sstsubsection{
+         indim
+      }{
+         The number of elements along the second dimension of the \texttt{"} in\texttt{"}
+         array (which contains the marker coordinates). This value is
+         required so that the coordinate values can be correctly
+         located if they do not entirely fill this array. The value
+         given should not be less than \texttt{"} nmark\texttt{"} .
+      }
+      \sstsubsection{
+         in
+      }{
+         The address of the first element of a 2-dimensional array of
+         shape \texttt{"} [ncoord][indim]\texttt{"}  giving the
+         physical coordinates of the points where markers are to be
+         drawn. These should be stored such that the value of
+         coordinate number \texttt{"} coord\texttt{"}  for input mark number \texttt{"} mark\texttt{"}  is
+         found in element \texttt{"} in[coord][mark]\texttt{"} .
+      }
+      \sstsubsection{
+         type
+      }{
+         A value specifying the type (e.g. shape) of marker to be
+         drawn. The set of values which may be used (and the shapes
+         that will result) is determined by the underlying graphics
+         system.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Markers are not drawn at positions which have any coordinate
+         equal to the value AST\_\_BAD (or where the transformation into
+         graphical coordinates yields coordinates containing the value
+         AST\_\_BAD).
+
+         \sstitem
+          If any marker position is clipped (see \htmlref{astClip}{astClip}), then the
+         entire marker is not drawn.
+
+         \sstitem
+          An error results if the base Frame of the Plot is not 2-dimensional.
+
+         \sstitem
+          An error also results if the transformation between the
+         current and base Frames of the Plot is not defined (i.e. the
+         Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero).
+      }
+   }
+}
+\sstroutine{
+   astMask$<$X$>$
+}{
+   Mask a region of a data grid
+}{
+   \sstdescription{
+      This is a set of functions for masking out regions within gridded data
+      (e.g. an image). The functions modifies a given data grid by
+      assigning a specified value to all samples which are inside (or outside
+      if \texttt{"} inside\texttt{"}  is zero)
+      the specified \htmlref{Region}{Region}.
+
+      You should use a masking function which matches the numerical
+      type of the data you are processing by replacing $<$X$>$ in
+      the generic function name astMask$<$X$>$ by an appropriate 1- or
+      2-character type code. For example, if you are masking data
+      with type \texttt{"} float\texttt{"} , you should use the function astMaskF (see
+      the \texttt{"} Data Type Codes\texttt{"}  section below for the codes appropriate to
+      other numerical types).
+   }
+   \sstsynopsis{
+      int astMask$<$X$>$( AstRegion $*$this, AstMapping $*$map, int inside, int ndim,
+                      const int lbnd[], const int ubnd[], $<$Xtype$>$ in[],
+                      $<$Xtype$>$ val )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to a Region.
+      }
+      \sstsubsection{
+         map
+      }{
+         Pointer to a \htmlref{Mapping}{Mapping}. The forward transformation should map
+         positions in the coordinate system of the supplied Region
+         into pixel coordinates as defined by the
+         \texttt{"} lbnd\texttt{"}  and \texttt{"} ubnd\texttt{"}  parameters. A NULL pointer
+         can be supplied if the coordinate system of the supplied Region
+         corresponds to pixel coordinates. This is equivalent to
+         supplying a \htmlref{UnitMap}{UnitMap}.
+
+         The number of inputs for this Mapping (as given by its \htmlref{Nin}{Nin} attribute)
+         should match the number of axes in the supplied Region (as given
+         by the \htmlref{Naxes}{Naxes} attribute of the Region).
+         The number of outputs for the Mapping (as given by its \htmlref{Nout}{Nout} attribute)
+         should match the number of
+         grid dimensions given by the value of \texttt{"} ndim\texttt{"}
+         below.
+      }
+      \sstsubsection{
+         inside
+      }{
+         A boolean value which indicates which pixel are to be masked. If
+         a non-zero value
+         is supplied, then all grid pixels with centres inside the supplied
+         Region are assigned the value given by
+         \texttt{"} val\texttt{"} ,
+         and all other pixels are left unchanged. If
+         zero
+         is supplied, then all grid pixels with centres not inside the supplied
+         Region are assigned the value given by
+         \texttt{"} val\texttt{"} ,
+         and all other pixels are left unchanged. Note, the \htmlref{Negated}{Negated}
+         attribute of the Region is used to determine which pixel are
+         inside the Region and which are outside. So the inside of a Region
+         which has not been negated is the same as the outside of the
+         corresponding negated Region.
+
+         For types of Region such as \htmlref{PointList}{PointList} which have zero volume,
+         pixel centres will rarely fall exactly within the Region. For
+         this reason, the inclusion criterion is changed for zero-volume
+         Regions so that pixels are included (or excluded) if any part of
+         the Region passes through the pixel. For a PointList, this means
+         that pixels are included (or excluded) if they contain at least
+         one of the points listed in the PointList.
+      }
+      \sstsubsection{
+         ndim
+      }{
+         The number of dimensions in the input grid. This should be at
+         least one.
+      }
+      \sstsubsection{
+         lbnd
+      }{
+         Pointer to an array of integers, with \texttt{"} ndim\texttt{"}  elements,
+         containing the coordinates of the centre of the first pixel
+         in the input grid along each dimension.
+      }
+      \sstsubsection{
+         ubnd
+      }{
+         Pointer to an array of integers, with \texttt{"} ndim\texttt{"}  elements,
+         containing the coordinates of the centre of the last pixel in
+         the input grid along each dimension.
+
+         Note that \texttt{"} lbnd\texttt{"}  and \texttt{"} ubnd\texttt{"}  together define the shape
+         and size of the input grid, its extent along a particular
+         (j\texttt{'} th) dimension being ubnd[j]-lbnd[j]$+$1 (assuming the
+         index \texttt{"} j\texttt{"}  to be zero-based). They also define
+         the input grid\texttt{'} s coordinate system, each pixel having unit
+         extent along each dimension with integral coordinate values
+         at its centre.
+      }
+      \sstsubsection{
+         in
+      }{
+         Pointer to an array, with one element for each pixel in the
+         input grid, containing the data to be masked.  The
+         numerical type of this array should match the 1- or
+         2-character type code appended to the function name (e.g. if
+         you are using astMaskF, the type of each array element
+         should be \texttt{"} float\texttt{"} ).
+
+         The storage order of data within this array should be such
+         that the index of the first grid dimension varies most
+         rapidly and that of the final dimension least rapidly
+         (i.e. Fortran array indexing is used).
+
+         On exit, the samples specified by
+         \texttt{"} inside\texttt{"}  are set to the value of \texttt{"} val\texttt{"} .
+         All other samples are left unchanged.
+      }
+      \sstsubsection{
+         val
+      }{
+         This argument should have the same type as the elements of
+         the \texttt{"} in\texttt{"}  array. It specifies the value used to flag the
+         masked data (see
+         \texttt{"} inside\texttt{"} ).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astMask$<$X$>$()
+      }{
+         The number of pixels to which a value of
+         \texttt{"} badval\texttt{"}
+         has been assigned.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A value of zero will be returned if this function is invoked
+         with the global error status set, or if it should fail for any
+         reason.
+
+         \sstitem
+          An error will be reported if the overlap of the Region and
+         the array cannot be determined.
+      }
+   }
+   \sstdiytopic{
+      Data Type Codes
+   }{
+      To select the appropriate masking function, you should
+      replace $<$X$>$ in the generic function name astMask$<$X$>$ with a
+      1- or 2-character data type code, so as to match the numerical
+      type $<$Xtype$>$ of the data you are processing, as follows:
+      \sstitemlist{
+
+         \sstitem
+          D: double
+
+         \sstitem
+          F: float
+
+         \sstitem
+          L: long int
+
+         \sstitem
+          UL: unsigned long int
+
+         \sstitem
+          I: int
+
+         \sstitem
+          UI: unsigned int
+
+         \sstitem
+          S: short int
+
+         \sstitem
+          US: unsigned short int
+
+         \sstitem
+          B: byte (signed char)
+
+         \sstitem
+          UB: unsigned byte (unsigned char)
+
+      }
+      For example, astMaskD would be used to process \texttt{"} double\texttt{"}
+      data, while astMaskS would be used to process \texttt{"} short int\texttt{"}
+      data, etc.
+   }
+}
+\sstroutine{
+   astMatchAxes
+}{
+   Find any corresponding axes in two Frames
+}{
+   \sstdescription{
+      This function looks for corresponding axes within two supplied
+      Frames. An array of integers is returned that contains an element
+      for each axis in the second supplied \htmlref{Frame}{Frame}. An element in this array
+      will be set to zero if the associated axis within the second Frame
+      has no corresponding axis within the first Frame. Otherwise, it
+      will be set to the index (a non-zero positive integer) of the
+      corresponding axis within the first supplied Frame.
+   }
+   \sstsynopsis{
+      void astMatchAxes( AstFrame $*$frm1, AstFrame $*$frm2, int $*$axes )
+   }
+   \sstparameters{
+      \sstsubsection{
+         frm1
+      }{
+         Pointer to the first Frame.
+      }
+      \sstsubsection{
+         frm2
+      }{
+         Pointer to the second Frame.
+      }
+      \sstsubsection{
+         axes
+      }{
+         Pointer to an
+         integer array in which to return the indices of the axes (within
+         the first Frame) that correspond to each axis within the second
+         Frame. \htmlref{Axis}{Axis} indices start at 1. A value of zero will be stored
+         in the returned array for each axis in the second Frame that has
+         no corresponding axis in the first Frame.
+
+         The number of elements in this array must be greater than or
+         equal to the number of axes in the second Frame.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Frame
+      }{
+         This function applies to all Frames.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Corresponding axes are identified by the fact that a \htmlref{Mapping}{Mapping} can
+         be found between them using
+         \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}.
+         Thus, \texttt{"} corresponding axes\texttt{"}  are not necessarily identical. For
+         instance, \htmlref{SkyFrame}{SkyFrame} axes in two Frames will match even if they
+         describe different celestial coordinate systems
+      }
+   }
+}
+\sstroutine{
+   astMathMap
+}{
+   Create a MathMap
+}{
+   \sstdescription{
+      This function creates a new \htmlref{MathMap}{MathMap} and optionally initialises its
+      attributes.
+
+      A MathMap is a \htmlref{Mapping}{Mapping} which allows you to specify a set of forward
+      and/or inverse transformation functions using arithmetic operations
+      and mathematical functions similar to those available in C. The
+      MathMap interprets these functions at run-time, whenever its forward
+      or inverse transformation is required. Because the functions are not
+      compiled in the normal sense (unlike an \htmlref{IntraMap}{IntraMap}), they may be used to
+      describe coordinate transformations in a transportable manner. A
+      MathMap therefore provides a flexible way of defining new types of
+      Mapping whose descriptions may be stored as part of a dataset and
+      interpreted by other programs.
+   }
+   \sstsynopsis{
+      AstMathMap $*$astMathMap( int nin, int nout,
+                              int nfwd, const char $*$fwd[],
+                              int ninv, const char $*$inv[],
+                              const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         nin
+      }{
+         Number of input variables for the MathMap. This determines the
+         value of its \htmlref{Nin}{Nin} attribute.
+      }
+      \sstsubsection{
+         nout
+      }{
+         Number of output variables for the MathMap. This determines the
+         value of its \htmlref{Nout}{Nout} attribute.
+      }
+      \sstsubsection{
+         nfwd
+      }{
+         The number of forward transformation functions being supplied.
+         This must be at least equal to \texttt{"} nout\texttt{"} , but may be increased to
+         accommodate any additional expressions which define intermediate
+         variables for the forward transformation (see the \texttt{"} Calculating
+         Intermediate Values\texttt{"}  section below).
+      }
+      \sstsubsection{
+         fwd
+      }{
+         An array (with \texttt{"} nfwd\texttt{"}  elements) of pointers to null terminated strings
+         which contain the expressions defining the forward transformation.
+         The syntax of these expressions is described below.
+      }
+      \sstsubsection{
+         ninv
+      }{
+         The number of inverse transformation functions being supplied.
+         This must be at least equal to \texttt{"} nin\texttt{"} , but may be increased to
+         accommodate any additional expressions which define intermediate
+         variables for the inverse transformation (see the \texttt{"} Calculating
+         Intermediate Values\texttt{"}  section below).
+      }
+      \sstsubsection{
+         inv
+      }{
+         An array (with \texttt{"} ninv\texttt{"}  elements) of pointers to null terminated strings
+         which contain the expressions defining the inverse transformation.
+         The syntax of these expressions is described below.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new MathMap. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+         If no initialisation is required, a zero-length string may be
+         supplied.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astMathMap()
+      }{
+         A pointer to the new MathMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The sequence of numbers produced by the random number functions
+         available within a MathMap is normally unpredictable and different for
+         each MathMap. However, this behaviour may be controlled by means of
+         the MathMap\texttt{'} s \htmlref{Seed}{Seed} attribute.
+
+         \sstitem
+          Normally, compound Mappings (CmpMaps) which involve MathMaps will
+         not be subject to simplification (e.g. using \htmlref{astSimplify}{astSimplify}) because AST
+         cannot know how different MathMaps will interact. However, in the
+         special case where a MathMap occurs in series with its own inverse,
+         then simplification may be possible. Whether simplification does, in
+         fact, occur under these circumstances is controlled by the MathMap\texttt{'} s
+         \htmlref{SimpFI}{SimpFI} and \htmlref{SimpIF}{SimpIF} attributes.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      Defining Transformation Functions
+   }{
+      A MathMap\texttt{'} s transformation functions are supplied as a set of
+      expressions in an array of character strings. Normally you would
+      supply the same number of expressions for the forward transformation,
+      via the \texttt{"} fwd\texttt{"}  parameter, as there are output variables (given by the
+      MathMap\texttt{'} s Nout attribute). For instance, if Nout is 2 you might use:
+      \sstitemlist{
+
+         \sstitem
+          \texttt{"} r = sqrt( x $*$ x $+$ y $*$ y )\texttt{"}
+
+         \sstitem
+          \texttt{"} theta = atan2( y, x )\texttt{"}
+
+      }
+      which defines a transformation from Cartesian to polar
+      coordinates. Here, the variables that appear on the left of each
+      expression (\texttt{"} r\texttt{"}  and \texttt{"} theta\texttt{"} ) provide names for the output variables
+      and those that appear on the right (\texttt{"} x\texttt{"}  and \texttt{"} y\texttt{"} ) are references to
+      input variables.
+
+      To complement this, you must also supply expressions for the inverse
+      transformation via the \texttt{"} inv\texttt{"}  parameter.  In this case, the number of
+      expressions given would normally match the number of MathMap input
+      coordinates (given by the Nin attribute).  If Nin is 2, you might use:
+      \sstitemlist{
+
+         \sstitem
+          \texttt{"} x = r $*$ cos( theta )\texttt{"}
+
+         \sstitem
+          \texttt{"} y = r $*$ sin( theta )\texttt{"}
+
+      }
+      which expresses the transformation from polar to Cartesian
+      coordinates. Note that here the input variables (\texttt{"} x\texttt{"}  and \texttt{"} y\texttt{"} ) are
+      named on the left of each expression, and the output variables (\texttt{"} r\texttt{"}
+      and \texttt{"} theta\texttt{"} ) are referenced on the right.
+
+      Normally, you cannot refer to a variable on the right of an expression
+      unless it is named on the left of an expression in the complementary
+      set of functions. Therefore both sets of functions (forward and
+      inverse) must be formulated using the same consistent set of variable
+      names. This means that if you wish to leave one of the transformations
+      undefined, you must supply dummy expressions which simply name each of
+      the output (or input) variables.  For example, you might use:
+      \sstitemlist{
+
+         \sstitem
+          \texttt{"} x\texttt{"}
+
+         \sstitem
+          \texttt{"} y\texttt{"}
+
+      }
+      for the inverse transformation above, which serves to name the input
+      variables but without defining an inverse transformation.
+   }
+   \sstdiytopic{
+      Calculating Intermediate Values
+   }{
+      It is sometimes useful to calculate intermediate values and then to
+      use these in the final expressions for the output (or input)
+      variables. This may be done by supplying additional expressions for
+      the forward (or inverse) transformation functions. For instance, the
+      following array of five expressions describes 2-dimensional pin-cushion
+      distortion:
+      \sstitemlist{
+
+         \sstitem
+          \texttt{"} r = sqrt( xin $*$ xin $+$ yin $*$ yin )\texttt{"}
+
+         \sstitem
+          \texttt{"} rout = r $*$ ( 1 $+$ 0.1 $*$ r $*$ r )\texttt{"}
+
+         \sstitem
+          \texttt{"} theta = atan2( yin, xin )\texttt{"}
+
+         \sstitem
+          \texttt{"} xout = rout $*$ cos( theta )\texttt{"}
+
+         \sstitem
+          \texttt{"} yout = rout $*$ sin( theta )\texttt{"}
+
+      }
+      Here, we first calculate three intermediate results (\texttt{"} r\texttt{"} , \texttt{"} rout\texttt{"}
+      and \texttt{"} theta\texttt{"} ) and then use these to calculate the final results (\texttt{"} xout\texttt{"}
+      and \texttt{"} yout\texttt{"} ). The MathMap knows that only the final two results
+      constitute values for the output variables because its Nout attribute
+      is set to 2. You may define as many intermediate variables in this
+      way as you choose. Having defined a variable, you may then refer to it
+      on the right of any subsequent expressions.
+
+      Note that when defining the inverse transformation you may only refer
+      to the output variables \texttt{"} xout\texttt{"}  and \texttt{"} yout\texttt{"} .  The intermediate variables
+      \texttt{"} r\texttt{"} , \texttt{"} rout\texttt{"}  and \texttt{"} theta\texttt{"}  (above) are private to the forward
+      transformation and may not be referenced by the inverse
+      transformation. The inverse transformation may, however, define its
+      own private intermediate variables.
+   }
+   \sstdiytopic{
+      Expression Syntax
+   }{
+      The expressions given for the forward and inverse transformations
+      closely follow the syntax of the C programming language (with some
+      extensions for compatibility with Fortran). They may contain
+      references to variables and literal constants, together with
+      arithmetic, boolean, relational and bitwise operators, and function
+      invocations. A set of symbolic constants is also available. Each of
+      these is described in detail below. Parentheses may be used to
+      over-ride the normal order of evaluation. There is no built-in limit
+      to the length of expressions and they are insensitive to case or the
+      presence of additional white space.
+   }
+   \sstdiytopic{
+      Variables
+   }{
+      Variable names must begin with an alphabetic character and may contain
+      only alphabetic characters, digits, and the underscore character
+      \texttt{"} \_\texttt{"} . There is no built-in limit to the length of variable names.
+   }
+   \sstdiytopic{
+      Literal Constants
+   }{
+      Literal constants, such as \texttt{"} 0\texttt{"} , \texttt{"} 1\texttt{"} , \texttt{"} 0.007\texttt{"}  or \texttt{"} 2.505e-16\texttt{"}  may appear
+      in expressions, with the decimal point and exponent being optional (a
+      \texttt{"} D\texttt{"}  may also be used as an exponent character for compatibility with
+      Fortran). A unary minus \texttt{"} -\texttt{"}  may be used as a prefix.
+   }
+   \sstdiytopic{
+      Arithmetic Precision
+   }{
+      All arithmetic is floating point, performed in double precision.
+   }
+   \sstdiytopic{
+      Propagation of Missing Data
+   }{
+      Unless indicated otherwise, if any argument of a function or operator
+      has the value AST\_\_BAD (indicating missing data), then the result of
+      that function or operation is also AST\_\_BAD, so that such values are
+      propagated automatically through all operations performed by MathMap
+      transformations.  The special value AST\_\_BAD can be represented in
+      expressions by the symbolic constant \texttt{"} $<$bad$>$\texttt{"} .
+
+      A $<$bad$>$ result (i.e. equal to AST\_\_BAD) is also produced in response
+      to any numerical error (such as division by zero or numerical
+      overflow), or if an invalid argument value is provided to a function
+      or operator.
+   }
+   \sstdiytopic{
+      Arithmetic Operators
+   }{
+      The following arithmetic operators are available:
+      \sstitemlist{
+
+         \sstitem
+          x1 $+$ x2: Sum of \texttt{"} x1\texttt{"}  and \texttt{"} x2\texttt{"} .
+
+         \sstitem
+          x1 - x2: Difference of \texttt{"} x1\texttt{"}  and \texttt{"} x2\texttt{"} .
+
+         \sstitem
+          x1 $*$ x2: Product of \texttt{"} x1\texttt{"}  and \texttt{"} x1\texttt{"} .
+
+         \sstitem
+          x1 / x2: Ratio of \texttt{"} x1\texttt{"}  and \texttt{"} x2\texttt{"} .
+
+         \sstitem
+          x1 $*$$*$ x2: \texttt{"} x1\texttt{"}  raised to the power of \texttt{"} x2\texttt{"} .
+
+         \sstitem
+          $+$ x: Unary plus, has no effect on its argument.
+
+         \sstitem
+          - x: Unary minus, negates its argument.
+      }
+   }
+   \sstdiytopic{
+      Boolean Operators
+   }{
+      Boolean values are represented using zero to indicate false and
+      non-zero to indicate true. In addition, the value AST\_\_BAD is taken to
+      mean \texttt{"} unknown\texttt{"} . The values returned by boolean operators may therefore
+      be 0, 1 or AST\_\_BAD. Where appropriate, \texttt{"} tri-state\texttt{"}  logic is
+      implemented. For example, \texttt{"} a$|$$|$b\texttt{"}  may evaluate to 1 if \texttt{"} a\texttt{"}  is non-zero,
+      even if \texttt{"} b\texttt{"}  has the value AST\_\_BAD. This is because the result of the
+      operation would not be affected by the value of \texttt{"} b\texttt{"} , so long as \texttt{"} a\texttt{"}  is
+      non-zero.
+
+      The following boolean operators are available:
+      \sstitemlist{
+
+         \sstitem
+          x1 \&\& x2: Boolean AND between \texttt{"} x1\texttt{"}  and \texttt{"} x2\texttt{"} , returning 1 if both \texttt{"} x1\texttt{"}
+         and \texttt{"} x2\texttt{"}  are non-zero, and 0 otherwise. This operator implements
+         tri-state logic. (The synonym \texttt{"} .and.\texttt{"}  is also provided for compatibility
+         with Fortran.)
+
+         \sstitem
+          x1 $|$$|$ x2: Boolean OR between \texttt{"} x1\texttt{"}  and \texttt{"} x2\texttt{"} , returning 1 if either \texttt{"} x1\texttt{"}
+         or \texttt{"} x2\texttt{"}  are non-zero, and 0 otherwise. This operator implements
+         tri-state logic. (The synonym \texttt{"} .or.\texttt{"}  is also provided for compatibility
+         with Fortran.)
+
+         \sstitem
+          x1 $\wedge$$\wedge$ x2: Boolean exclusive OR (XOR) between \texttt{"} x1\texttt{"}  and \texttt{"} x2\texttt{"} , returning
+         1 if exactly one of \texttt{"} x1\texttt{"}  and \texttt{"} x2\texttt{"}  is non-zero, and 0 otherwise. Tri-state
+         logic is not used with this operator. (The synonyms \texttt{"} .neqv.\texttt{"}  and \texttt{"} .xor.\texttt{"}
+         are also provided for compatibility with Fortran, although the second
+         of these is not standard.)
+
+         \sstitem
+          x1 .eqv. x2: This is provided only for compatibility with Fortran
+         and tests whether the boolean states of \texttt{"} x1\texttt{"}  and \texttt{"} x2\texttt{"}  (i.e. true/false)
+         are equal. It is the negative of the exclusive OR (XOR) function.
+         Tri-state logic is not used with this operator.
+
+         \sstitem
+          ! x: Boolean unary NOT operation, returning 1 if \texttt{"} x\texttt{"}  is zero, and
+         0 otherwise. (The synonym \texttt{"} .not.\texttt{"}  is also provided for compatibility
+         with Fortran.)
+      }
+   }
+   \sstdiytopic{
+      Relational Operators
+   }{
+      Relational operators return the boolean result (0 or 1) of comparing
+      the values of two floating point values for equality or inequality. The
+      value AST\_\_BAD may also be returned if either argument is $<$bad$>$.
+
+      The following relational operators are available:
+      \sstitemlist{
+
+         \sstitem
+          x1 == x2: Tests whether \texttt{"} x1\texttt{"}  equals \texttt{"} x1\texttt{"} . (The synonym \texttt{"} .eq.\texttt{"}  is
+         also provided for compatibility with Fortran.)
+
+         \sstitem
+          x1 != x2: Tests whether \texttt{"} x1\texttt{"}  is unequal to \texttt{"} x2\texttt{"} . (The synonym \texttt{"} .ne.\texttt{"}
+         is also provided for compatibility with Fortran.)
+
+         \sstitem
+          x1 $>$ x2: Tests whether \texttt{"} x1\texttt{"}  is greater than \texttt{"} x2\texttt{"} . (The synonym
+         \texttt{"} .gt.\texttt{"}  is also provided for compatibility with Fortran.)
+
+         \sstitem
+          x1 $>$= x2: Tests whether \texttt{"} x1\texttt{"}  is greater than or equal to \texttt{"} x2\texttt{"} . (The
+         synonym \texttt{"} .ge.\texttt{"}   is also provided for compatibility with Fortran.)
+
+         \sstitem
+          x1 $<$ x2: Tests whether \texttt{"} x1\texttt{"}  is less than \texttt{"} x2\texttt{"} . (The synonym \texttt{"} .lt.\texttt{"}
+         is also provided for compatibility with Fortran.)
+
+         \sstitem
+          x1 $<$= x2: Tests whether \texttt{"} x1\texttt{"}  is less than or equal to \texttt{"} x2\texttt{"} . (The
+         synonym \texttt{"} .le.\texttt{"}  is also provided for compatibility with Fortran.)
+
+      }
+      Note that relational operators cannot usefully be used to compare
+      values with the $<$bad$>$ value (representing missing data), because the
+      result is always $<$bad$>$. The isbad() function should be used instead.
+   }
+   \sstdiytopic{
+      Bitwise Operators
+   }{
+      The bitwise operators provided by C are often useful when operating on
+      raw data (e.g. from instruments), so they are also provided for use in
+      MathMap expressions. In this case, however, the values on which they
+      operate are floating point values rather than pure integers. In order
+      to produce results which match the pure integer case, the operands are
+      regarded as fixed point binary numbers (i.e. with the binary
+      equivalent of a decimal point) with negative numbers represented using
+      twos-complement notation. For integer values, the resulting bit
+      pattern corresponds to that of the equivalent signed integer (digits
+      to the right of the point being zero). Operations on the bits
+      representing the fractional part are also possible, however.
+
+      The following bitwise operators are available:
+      \sstitemlist{
+
+         \sstitem
+          x1 $>$$>$ x2: Rightward bit shift. The integer value of \texttt{"} x2\texttt{"}  is taken
+         (rounding towards zero) and the bits representing \texttt{"} x1\texttt{"}  are then
+         shifted this number of places to the right (or to the left if the
+         number of places is negative). This is equivalent to dividing \texttt{"} x1\texttt{"}  by
+         the corresponding power of 2.
+
+         \sstitem
+          x1 $<$$<$ x2: Leftward bit shift. The integer value of \texttt{"} x2\texttt{"}  is taken
+         (rounding towards zero), and the bits representing \texttt{"} x1\texttt{"}  are then
+         shifted this number of places to the left (or to the right if the
+         number of places is negative). This is equivalent to multiplying \texttt{"} x1\texttt{"}
+         by the corresponding power of 2.
+
+         \sstitem
+          x1 \& x2: Bitwise AND between the bits of \texttt{"} x1\texttt{"}  and those of \texttt{"} x2\texttt{"}
+         (equivalent to a boolean AND applied at each bit position in turn).
+
+         \sstitem
+          x1 $|$ x2: Bitwise OR between the bits of \texttt{"} x1\texttt{"}  and those of \texttt{"} x2\texttt{"}
+         (equivalent to a boolean OR applied at each bit position in turn).
+
+         \sstitem
+          x1 $\wedge$ x2: Bitwise exclusive OR (XOR) between the bits of \texttt{"} x1\texttt{"}  and
+         those of \texttt{"} x2\texttt{"}  (equivalent to a boolean XOR applied at each bit
+         position in turn).
+
+      }
+      Note that no bit inversion operator (\texttt{"} $\sim$\texttt{"}  in C) is provided. This is
+      because inverting the bits of a twos-complement fixed point binary
+      number is equivalent to simply negating it. This differs from the
+      pure integer case because bits to the right of the binary point are
+      also inverted. To invert only those bits to the left of the binary
+      point, use a bitwise exclusive OR with the value -1 (i.e. \texttt{"} x$\wedge$-1\texttt{"} ).
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The following functions are available:
+      \sstitemlist{
+
+         \sstitem
+          abs(x): Absolute value of \texttt{"} x\texttt{"}  (sign removal), same as fabs(x).
+
+         \sstitem
+          acos(x): Inverse cosine of \texttt{"} x\texttt{"} , in radians.
+
+         \sstitem
+          acosd(x): Inverse cosine of \texttt{"} x\texttt{"} , in degrees.
+
+         \sstitem
+          acosh(x): Inverse hyperbolic cosine of \texttt{"} x\texttt{"} .
+
+         \sstitem
+          acoth(x): Inverse hyperbolic cotangent of \texttt{"} x\texttt{"} .
+
+         \sstitem
+          acsch(x): Inverse hyperbolic cosecant of \texttt{"} x\texttt{"} .
+
+         \sstitem
+          aint(x): Integer part of \texttt{"} x\texttt{"}  (round towards zero), same as int(x).
+
+         \sstitem
+          asech(x): Inverse hyperbolic secant of \texttt{"} x\texttt{"} .
+
+         \sstitem
+          asin(x): Inverse sine of \texttt{"} x\texttt{"} , in radians.
+
+         \sstitem
+          asind(x): Inverse sine of \texttt{"} x\texttt{"} , in degrees.
+
+         \sstitem
+          asinh(x): Inverse hyperbolic sine of \texttt{"} x\texttt{"} .
+
+         \sstitem
+          atan(x): Inverse tangent of \texttt{"} x\texttt{"} , in radians.
+
+         \sstitem
+          atand(x): Inverse tangent of \texttt{"} x\texttt{"} , in degrees.
+
+         \sstitem
+          atanh(x): Inverse hyperbolic tangent of \texttt{"} x\texttt{"} .
+
+         \sstitem
+          atan2(x1, x2): Inverse tangent of \texttt{"} x1/x2\texttt{"} , in radians.
+
+         \sstitem
+          atan2d(x1, x2): Inverse tangent of \texttt{"} x1/x2\texttt{"} , in degrees.
+
+         \sstitem
+          ceil(x): Smallest integer value not less then \texttt{"} x\texttt{"}  (round towards
+           plus infinity).
+
+         \sstitem
+          cos(x): Cosine of \texttt{"} x\texttt{"}  in radians.
+
+         \sstitem
+          cosd(x): Cosine of \texttt{"} x\texttt{"}  in degrees.
+
+         \sstitem
+          cosh(x): Hyperbolic cosine of \texttt{"} x\texttt{"} .
+
+         \sstitem
+          coth(x): Hyperbolic cotangent of \texttt{"} x\texttt{"} .
+
+         \sstitem
+          csch(x): Hyperbolic cosecant of \texttt{"} x\texttt{"} .
+
+         \sstitem
+          dim(x1, x2): Returns \texttt{"} x1-x2\texttt{"}  if \texttt{"} x1\texttt{"}  is greater than \texttt{"} x2\texttt{"} , otherwise 0.
+
+         \sstitem
+          exp(x): Exponential function of \texttt{"} x\texttt{"} .
+
+         \sstitem
+          fabs(x): Absolute value of \texttt{"} x\texttt{"}  (sign removal), same as abs(x).
+
+         \sstitem
+          floor(x): Largest integer not greater than \texttt{"} x\texttt{"}  (round towards
+           minus infinity).
+
+         \sstitem
+          fmod(x1, x2): Remainder when \texttt{"} x1\texttt{"}  is divided by \texttt{"} x2\texttt{"} , same as
+           mod(x1, x2).
+
+         \sstitem
+          gauss(x1, x2): Random sample from a Gaussian distribution with mean
+           \texttt{"} x1\texttt{"}  and standard deviation \texttt{"} x2\texttt{"} .
+
+         \sstitem
+          int(x): Integer part of \texttt{"} x\texttt{"}  (round towards zero), same as aint(x).
+
+         \sstitem
+          isbad(x): Returns 1 if \texttt{"} x\texttt{"}  has the $<$bad$>$ value (AST\_\_BAD), otherwise 0.
+
+         \sstitem
+          log(x): Natural logarithm of \texttt{"} x\texttt{"} .
+
+         \sstitem
+          log10(x): Logarithm of \texttt{"} x\texttt{"}  to base 10.
+
+         \sstitem
+          max(x1, x2, ...): Maximum of two or more values.
+
+         \sstitem
+          min(x1, x2, ...): Minimum of two or more values.
+
+         \sstitem
+          mod(x1, x2): Remainder when \texttt{"} x1\texttt{"}  is divided by \texttt{"} x2\texttt{"} , same as
+           fmod(x1, x2).
+
+         \sstitem
+          nint(x): Nearest integer to \texttt{"} x\texttt{"}  (round to nearest).
+
+         \sstitem
+          poisson(x): Random integer-valued sample from a Poisson
+           distribution with mean \texttt{"} x\texttt{"} .
+
+         \sstitem
+          pow(x1, x2): \texttt{"} x1\texttt{"}  raised to the power of \texttt{"} x2\texttt{"} .
+
+         \sstitem
+          qif(x1, x2, x3): Returns \texttt{"} x2\texttt{"}  if \texttt{"} x1\texttt{"}  is true, and \texttt{"} x3\texttt{"}  otherwise.
+
+         \sstitem
+          rand(x1, x2): Random sample from a uniform distribution in the
+           range \texttt{"} x1\texttt{"}  to \texttt{"} x2\texttt{"}  inclusive.
+
+         \sstitem
+          sech(x): Hyperbolic secant of \texttt{"} x\texttt{"} .
+
+         \sstitem
+          sign(x1, x2): Absolute value of \texttt{"} x1\texttt{"}  with the sign of \texttt{"} x2\texttt{"}
+           (transfer of sign).
+
+         \sstitem
+          sin(x): Sine of \texttt{"} x\texttt{"}  in radians.
+
+         \sstitem
+          sinc(x): Sinc function of \texttt{"} x\texttt{"}  [= \texttt{"} sin(x)/x\texttt{"} ].
+
+         \sstitem
+          sind(x): Sine of \texttt{"} x\texttt{"}  in degrees.
+
+         \sstitem
+          sinh(x): Hyperbolic sine of \texttt{"} x\texttt{"} .
+
+         \sstitem
+          sqr(x): Square of \texttt{"} x\texttt{"}  (= \texttt{"} x$*$x\texttt{"} ).
+
+         \sstitem
+          sqrt(x): Square root of \texttt{"} x\texttt{"} .
+
+         \sstitem
+          tan(x): Tangent of \texttt{"} x\texttt{"}  in radians.
+
+         \sstitem
+          tand(x): Tangent of \texttt{"} x\texttt{"}  in degrees.
+
+         \sstitem
+          tanh(x): Hyperbolic tangent of \texttt{"} x\texttt{"} .
+      }
+   }
+   \sstdiytopic{
+      Symbolic Constants
+   }{
+      The following symbolic constants are available (the enclosing \texttt{"} $<$$>$\texttt{"}
+      brackets must be included):
+      \sstitemlist{
+
+         \sstitem
+          $<$bad$>$: The \texttt{"} bad\texttt{"}  value (AST\_\_BAD) used to flag missing data. Note
+         that you cannot usefully compare values with this constant because the
+         result is always $<$bad$>$. The isbad() function should be used instead.
+
+         \sstitem
+          $<$dig$>$: Number of decimal digits of precision available in a
+         floating point (double) value.
+
+         \sstitem
+          $<$e$>$: \htmlref{Base}{Base} of natural logarithms.
+
+         \sstitem
+          $<$epsilon$>$: Smallest positive number such that 1.0$+$$<$epsilon$>$ is
+         distinguishable from unity.
+
+         \sstitem
+          $<$mant\_dig$>$: The number of base $<$radix$>$ digits stored in the
+         mantissa of a floating point (double) value.
+
+         \sstitem
+          $<$max$>$: Maximum representable floating point (double) value.
+
+         \sstitem
+          $<$max\_10\_exp$>$: Maximum integer such that 10 raised to that power
+         can be represented as a floating point (double) value.
+
+         \sstitem
+          $<$max\_exp$>$: Maximum integer such that $<$radix$>$ raised to that
+         power minus 1 can be represented as a floating point (double) value.
+
+         \sstitem
+          $<$min$>$: Smallest positive number which can be represented as a
+         normalised floating point (double) value.
+
+         \sstitem
+          $<$min\_10\_exp$>$: Minimum negative integer such that 10 raised to that
+         power can be represented as a normalised floating point (double) value.
+
+         \sstitem
+          $<$min\_exp$>$: Minimum negative integer such that $<$radix$>$ raised to
+         that power minus 1 can be represented as a normalised floating point
+         (double) value.
+
+         \sstitem
+          $<$pi$>$: Ratio of the circumference of a circle to its diameter.
+
+         \sstitem
+          $<$radix$>$: The radix (number base) used to represent the mantissa of
+         floating point (double) values.
+
+         \sstitem
+          $<$rounds$>$: The mode used for rounding floating point results after
+         addition. Possible values include: -1 (indeterminate), 0 (toward
+         zero), 1 (to nearest), 2 (toward plus infinity) and 3 (toward minus
+         infinity). Other values indicate machine-dependent behaviour.
+      }
+   }
+   \sstdiytopic{
+      Evaluation Precedence and Associativity
+   }{
+      Items appearing in expressions are evaluated in the following order
+      (highest precedence first):
+      \sstitemlist{
+
+         \sstitem
+          Constants and variables
+
+         \sstitem
+          Function arguments and parenthesised expressions
+
+         \sstitem
+          Function invocations
+
+         \sstitem
+          Unary $+$ - ! .not.
+
+         \sstitem
+          $*$$*$
+
+         \sstitem
+          $*$ /
+
+         \sstitem
+          $+$ -
+
+         \sstitem
+          $<$$<$ $>$$>$
+
+         \sstitem
+          $<$ .lt. $<$= .le. $>$ .gt. $>$= .ge.
+
+         \sstitem
+          == .eq. != .ne.
+
+         \sstitem
+          \&
+
+         \sstitem
+          $\wedge$
+
+         \sstitem
+          $|$
+
+         \sstitem
+          \&\& .and.
+
+         \sstitem
+          $\wedge$$\wedge$
+
+         \sstitem
+          $|$$|$ .or
+
+         \sstitem
+          .eqv. .neqv. .xor.
+
+      }
+      All operators associate from left-to-right, except for unary $+$,
+      unary -, !, .not. and $*$$*$ which associate from right-to-left.
+   }
+}
+\sstroutine{
+   astMatrixMap
+}{
+   Create a MatrixMap
+}{
+   \sstdescription{
+      This function creates a new \htmlref{MatrixMap}{MatrixMap} and optionally initialises
+      its attributes.
+
+      A MatrixMap is a form of \htmlref{Mapping}{Mapping} which performs a general linear
+      transformation.  Each set of input coordinates, regarded as a
+      column-vector, are pre-multiplied by a matrix (whose elements
+      are specified when the MatrixMap is created) to give a new
+      column-vector containing the output coordinates. If appropriate,
+      the inverse transformation may also be performed.
+   }
+   \sstsynopsis{
+      AstMatrixMap $*$astMatrixMap( int nin, int nout, int form,
+                                  const double matrix[],
+                                  const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         nin
+      }{
+         The number of input coordinates, which determines the number
+         of columns in the matrix.
+      }
+      \sstsubsection{
+         nout
+      }{
+         The number of output coordinates, which determines the number
+         of rows in the matrix.
+      }
+      \sstsubsection{
+         form
+      }{
+         An integer which indicates the form in which the matrix
+         elements will be supplied.
+
+         A value of zero indicates that a full \texttt{"} nout\texttt{"}  x \texttt{"} nin\texttt{"}  matrix
+         of values will be supplied via the \texttt{"} matrix\texttt{"}  parameter
+         (below). In this case, the elements should be given in row
+         order (the elements of the first row, followed by the
+         elements of the second row, etc.).
+
+         A value of 1 indicates that only the diagonal elements of the
+         matrix will be supplied, and that all others should be
+         zero. In this case, the elements of \texttt{"} matrix\texttt{"}  should contain
+         only the diagonal elements, stored consecutively.
+
+         A value of 2 indicates that a \texttt{"} unit\texttt{"}  matrix is required,
+         whose diagonal elements are set to unity (with all other
+         elements zero).  In this case, the \texttt{"} matrix\texttt{"}  parameter is
+         ignored and a NULL pointer may be supplied.
+      }
+      \sstsubsection{
+         matrix
+      }{
+         The array of matrix elements to be used, stored according to
+         the value of \texttt{"} form\texttt{"} .
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new MatrixMap. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astMatrixMap()
+      }{
+         A pointer to the new MatrixMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          In general, a MatrixMap\texttt{'} s forward transformation will always
+         be available (as indicated by its \htmlref{TranForward}{TranForward} attribute), but
+         its inverse transformation (\htmlref{TranInverse}{TranInverse} attribute) will only be
+         available if the associated matrix is square and non-singular.
+
+         \sstitem
+          As an exception to this, the inverse transformation is always
+         available if a unit or diagonal matrix is specified. In this
+         case, if the matrix is not square, one or more of the input
+         coordinate values may not be recoverable from a set of output
+         coordinates. Any coordinates affected in this way will simply be
+         set to the value zero.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      Status Handling
+   }{
+      The protected interface to this function includes an extra
+      parameter at the end of the parameter list descirbed above. This
+      parameter is a pointer to the integer inherited status
+      variable: \texttt{"} int $*$status\texttt{"} .
+   }
+}
+\sstroutine{
+   astMirrorVariants
+}{
+   Make the current Frame mirror the variant Mappings in another Frame
+}{
+   \sstdescription{
+      This function
+      indicates that all access to the \htmlref{Variant}{Variant} attribute of the current
+      \htmlref{Frame}{Frame} should should be forwarded to some other nominated Frame in
+      the \htmlref{FrameSet}{FrameSet}. For instance, if a value is set subsequently for the
+      Variant attribute of the current Frame, the current Frame will be left
+      unchanged and the setting is instead applied to the nominated Frame.
+      Likewise, if the value of the Variant attribute is requested, the
+      value returned is the value stored for the nominated Frame rather
+      than the current Frame itself.
+
+      This provides a mechanism for propagating the effects of variant
+      Mappings around a FrameSet. If a new Frame is added to a FrameSet
+      by connecting it to an pre-existing Frame that has two or more variant
+      Mappings, then it may be appropriate to set the new Frame so that it
+      mirrors the variants Mappings of the pre-existing Frame. If this is
+      done, then it will be possible to select a specific variant \htmlref{Mapping}{Mapping}
+      using either the pre-existing Frame or the new Frame.
+   }
+   \sstsynopsis{
+      void astMirrorVariants( AstFrameSet $*$this, int iframe )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FrameSet.
+      }
+      \sstsubsection{
+         iframe
+      }{
+         The index of the Frame within the FrameSet which is to be
+         mirrored by the current Frame. This value should lie in the range
+         from 1 to the number of Frames in the FrameSet (as given by its
+         \htmlref{Nframe}{Nframe} attribute). If AST\_\_NOFRAME is supplied (or the current
+         Frame is specified), then any mirroring established by a previous
+         call to this
+         function
+         is disabled.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Mirrors can be chained. That is, if Frame B is set to be a mirror
+         of Frame A, and Frame C is set to be a mirror of Frame B, then
+         Frame C will act as a mirror of Frame A.
+
+         \sstitem
+          Variant Mappings cannot be added to the current Frame if it is
+         mirroring another Frame. So calls to the
+         \htmlref{astAddVariant}{astAddVariant} function
+         will cause an error to be reported if the current Frame is
+         mirroring another Frame.
+
+         \sstitem
+          A value of AST\_\_BASE may be given for the
+         \texttt{"} iframe\texttt{"}  parameter
+         to specify the base Frame.
+
+         \sstitem
+          Any variant Mappings explicitly added to the current Frame using
+         astAddVariant
+         will be ignored if the current Frame is mirroring another Frame.
+      }
+   }
+}
+\sstroutine{
+   astNegate
+}{
+   Negate the area represented by a Region
+}{
+   \sstdescription{
+      This function negates the area represented by a \htmlref{Region}{Region}. That is,
+      points which were previously inside the region will then be
+      outside, and points which were outside will be inside. This is
+      acomplished by toggling the state of the \htmlref{Negated}{Negated} attribute for
+      the supplied region.
+   }
+   \sstsynopsis{
+      void astNegate( AstRegion $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Region.
+      }
+   }
+}
+\sstroutine{
+   astNorm
+}{
+   Normalise a set of Frame coordinates
+}{
+   \sstdescription{
+      This function normalises a set of \htmlref{Frame}{Frame} coordinate values which
+      might be unsuitable for display (e.g. may lie outside the
+      expected range) into a set of acceptable values suitable for
+      display.
+   }
+   \sstsynopsis{
+      void astNorm( AstFrame $*$this, double value[] )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Frame.
+      }
+      \sstsubsection{
+         value
+      }{
+         An array of double, with one element for each Frame axis
+         (\htmlref{Naxes}{Naxes} attribute). Initially, this should contain a set of
+         coordinate values representing a point in the space which the
+         Frame describes. If these values lie outside the expected
+         range for the Frame, they will be replaced with more
+         acceptable (normalised) values. Otherwise, they will be
+         returned unchanged.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          For some classes of Frame, whose coordinate values are not
+         constrained, this function will never modify the values
+         supplied. However, for Frames whose axes represent cyclic
+         quantities (such as angles or positions on the sky), coordinates
+         will typically be wrapped into an appropriate standard range,
+         such as zero to 2$*$pi.
+
+         \sstitem
+          The \htmlref{NormMap}{NormMap} class is a \htmlref{Mapping}{Mapping} which can be used to normalise a
+         set of points using the
+         astNorm function
+         of a specified Frame.
+
+         \sstitem
+          It is intended to be possible to put any set of coordinates
+         into a form suitable for display by using this function to
+         normalise them, followed by appropriate formatting
+         (using \htmlref{astFormat}{astFormat}).
+      }
+   }
+}
+\sstroutine{
+   astNormMap
+}{
+   Create a NormMap
+}{
+   \sstdescription{
+      This function creates a new \htmlref{NormMap}{NormMap} and optionally initialises its
+      attributes.
+
+      A NormMap is a \htmlref{Mapping}{Mapping} which normalises coordinate values using the
+      \htmlref{astNorm}{astNorm} function
+      of the supplied \htmlref{Frame}{Frame}. The number of inputs and outputs of a NormMap
+      are both equal to the number of axes in the supplied Frame.
+
+      The forward and inverse transformation of a NormMap are both
+      defined but are identical (that is, they do not form a real inverse
+      pair in that the inverse transformation does not undo the
+      normalisation, instead it reapplies it). However, the
+      \htmlref{astSimplify}{astSimplify}
+      function will replace neighbouring pairs of forward and inverse
+      NormMaps by a single \htmlref{UnitMap}{UnitMap} (so long as the Frames encapsulated by
+      the two NormMaps are equal - i.e. have the same class and the same
+      attribute values). This means, for instance, that if a \htmlref{CmpMap}{CmpMap} contains
+      a NormMap, the CmpMap will still cancel with its own inverse.
+   }
+   \sstsynopsis{
+      AstNormMap $*$astNormMap( AstFrame $*$frame, const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         frame
+      }{
+         A pointer to the Frame which is to be used to normalise the
+         supplied axis values.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new NormMap. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astNormMap()
+      }{
+         A pointer to the new NormMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      Status Handling
+   }{
+      The protected interface to this function includes an extra
+      parameter at the end of the parameter list descirbed above. This
+      parameter is a pointer to the integer inherited status
+      variable: \texttt{"} int $*$status\texttt{"} .
+   }
+}
+\sstroutine{
+   astNullRegion
+}{
+   Create a NullRegion
+}{
+   \sstdescription{
+      This function creates a new \htmlref{NullRegion}{NullRegion} and optionally initialises its
+      attributes.
+
+      A NullRegion is a \htmlref{Region}{Region} with no bounds. If the \htmlref{Negated}{Negated} attribute of a
+      NullRegion is false, the NullRegion represents a Region containing no
+      points. If the Negated attribute of a NullRegion is true, the NullRegion
+      represents an infinite Region containing all points within the
+      coordinate system.
+   }
+   \sstsynopsis{
+      AstNullRegion $*$astNullRegion( AstFrame $*$frame, AstRegion $*$unc, const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         frame
+      }{
+         A pointer to the \htmlref{Frame}{Frame} in which the region is defined. A deep
+         copy is taken of the supplied Frame. This means that any
+         subsequent changes made to the Frame using the supplied pointer
+         will have no effect the Region.
+      }
+      \sstsubsection{
+         unc
+      }{
+         An optional pointer to an existing Region which specifies the
+         uncertainties associated with positions in the supplied Frame.
+         The uncertainty in any point in the Frame is found by shifting the
+         supplied \texttt{"} uncertainty\texttt{"}  Region so that it is centred at the point
+         being considered. The area covered by the shifted uncertainty
+         Region then represents the uncertainty in the position. The
+         uncertainty is assumed to be the same for all points.
+
+         If supplied, the uncertainty Region must be of a class for which
+         all instances are centro-symetric (e.g. \htmlref{Box}{Box}, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.)
+         or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep
+         copy of the supplied Region will be taken, so subsequent changes to
+         the uncertainty Region using the supplied pointer will have no
+         effect on the created NullRegion. Alternatively,
+         a NULL \htmlref{Object}{Object} pointer
+         may be supplied, in which case a default uncertainty of zero is
+         used.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new NullRegion. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astNullRegion()
+      }{
+         A pointer to the new NullRegion.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null Object pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astOK
+}{
+   Test whether AST functions have been successful
+}{
+   \sstdescription{
+      This macro returns a boolean value (0 or 1) to indicate if
+      preceding AST functions have completed successfully
+      (i.e. without setting the AST error status). If the error status
+      is set to an error value, a value of zero is returned, otherwise
+      the result is one.
+   }
+   \sstsynopsis{
+      int astOK
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astOK
+      }{
+         One if the AST error status is OK, otherwise zero.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If the AST error status is set to an error value (after an
+         error), most AST functions will not execute and will simply
+         return without action. To clear the error status and restore
+         normal behaviour, use \htmlref{astClearStatus}{astClearStatus}.
+      }
+   }
+}
+\sstroutine{
+   astOffset
+}{
+   Calculate an offset along a geodesic curve
+}{
+   \sstdescription{
+      This function finds the \htmlref{Frame}{Frame} coordinate values of a point which
+      is offset a specified distance along the geodesic curve between
+      two other points.
+
+      For example, in a basic Frame, this offset will be along the
+      straight line joining two points. For a more specialised Frame
+      describing a sky coordinate system, however, it would be along
+      the great circle passing through two sky positions.
+   }
+   \sstsynopsis{
+      void astOffset( AstFrame $*$this,
+                      const double point1[], const double point2[],
+                      double offset, double point3[] )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Frame.
+      }
+      \sstsubsection{
+         point1
+      }{
+         An array of double, with one element for each Frame axis
+         (\htmlref{Naxes}{Naxes} attribute). This should contain the coordinates of the
+         point marking the start of the geodesic curve.
+      }
+      \sstsubsection{
+         point2
+      }{
+         An array of double, with one element for each Frame axis
+         This should contain the coordinates of the point marking the
+         end of the geodesic curve.
+      }
+      \sstsubsection{
+         offset
+      }{
+         The required offset from the first point along the geodesic
+         curve. If this is positive, it will be towards the second
+         point. If it is negative, it will be in the opposite
+         direction. This offset need not imply a position lying
+         between the two points given, as the curve will be
+         extrapolated if necessary.
+      }
+      \sstsubsection{
+         point3
+      }{
+         An array of double, with one element for each Frame axis
+         in which the coordinates of the required point will be returned.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The geodesic curve used by this function is the path of
+         shortest distance between two points, as defined by the
+         \htmlref{astDistance}{astDistance} function.
+
+         \sstitem
+          This function will return \texttt{"} bad\texttt{"}  coordinate values (AST\_\_BAD)
+         if any of the input coordinates has this value.
+
+         \sstitem
+          \texttt{"} Bad\texttt{"}  coordinate values will also be returned if the two
+         points supplied are coincident (or otherwise fail to uniquely
+         specify a geodesic curve) but the requested offset is non-zero.
+      }
+   }
+}
+\sstroutine{
+   astOffset2
+}{
+   Calculate an offset along a geodesic curve in a 2D Frame
+}{
+   \sstdescription{
+      This function finds the \htmlref{Frame}{Frame} coordinate values of a point which
+      is offset a specified distance along the geodesic curve at a
+      given angle from a specified starting point. It can only be
+      used with 2-dimensional Frames.
+
+      For example, in a basic Frame, this offset will be along the
+      straight line joining two points. For a more specialised Frame
+      describing a sky coordinate system, however, it would be along
+      the great circle passing through two sky positions.
+   }
+   \sstsynopsis{
+      double astOffset2( AstFrame $*$this, const double point1[2], double angle,
+                         double offset, double point2[2] );
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Frame.
+      }
+      \sstsubsection{
+         point1
+      }{
+         An array of double, with one element for each Frame axis
+         (\htmlref{Naxes}{Naxes} attribute). This should contain the coordinates of the
+         point marking the start of the geodesic curve.
+      }
+      \sstsubsection{
+         angle
+      }{
+         The angle (in radians) from the positive direction of the second
+         axis, to the direction of the required position, as seen from
+         the starting position. Positive rotation is in the sense of
+         rotation from the positive direction of axis 2 to the positive
+         direction of axis 1.
+      }
+      \sstsubsection{
+         offset
+      }{
+         The required offset from the first point along the geodesic
+         curve. If this is positive, it will be in the direction of the
+         given angle. If it is negative, it will be in the opposite
+         direction.
+      }
+      \sstsubsection{
+         point2
+      }{
+         An array of double, with one element for each Frame axis
+         in which the coordinates of the required point will be returned.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astOffset2
+      }{
+         The direction of the geodesic curve at the end point. That is, the
+         angle (in radians) between the positive direction of the second
+         axis and the continuation of the geodesic curve at the requested
+         end point. Positive rotation is in the sense of rotation from
+         the positive direction of axis 2 to the positive direction of axis
+         1.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The geodesic curve used by this function is the path of
+         shortest distance between two points, as defined by the
+         \htmlref{astDistance}{astDistance} function.
+
+         \sstitem
+          An error will be reported if the Frame is not 2-dimensional.
+
+         \sstitem
+          This function will return \texttt{"} bad\texttt{"}  coordinate values (AST\_\_BAD)
+         if any of the input coordinates has this value.
+      }
+   }
+}
+\sstroutine{
+   astOutline$<$X$>$
+}{
+   Create a new Polygon outling values in a 2D data grid
+}{
+   \sstdescription{
+      This is a set of functions that create a \htmlref{Polygon}{Polygon} enclosing a single
+      contiguous set of pixels that have a specified value within a gridded
+      2-dimensional data array (e.g. an image).
+
+      A basic 2-dimensional \htmlref{Frame}{Frame} is used to represent the pixel coordinate
+      system in the returned Polygon. The \htmlref{Domain}{Domain} attribute is set to
+      \texttt{"} PIXEL\texttt{"} , the \htmlref{Title}{Title} attribute is set to \texttt{"} Pixel coordinates\texttt{"} , and the
+      Unit attribute for each axis is set to \texttt{"} pixel\texttt{"} . All other
+      attributes are left unset. The nature of the pixel coordinate system
+      is determined by parameter
+      \texttt{"} starpix\texttt{"} .
+
+      The
+      \texttt{"} maxerr\texttt{"}  and \texttt{"} maxvert\texttt{"}
+      parameters can be used to control how accurately the returned
+      Polygon represents the required region in the data array. The
+      number of vertices in the returned Polygon will be the minimum
+      needed to achieve the required accuracy.
+
+      You should use a function which matches the numerical type of the
+      data you are processing by replacing $<$X$>$ in the generic function
+      name
+      astOutline$<$X$>$
+      by an appropriate 1- or 2-character type code. For example, if you
+      are procesing data with type
+      \texttt{"} float\texttt{"} , you should use the function astOutlineF
+      (see the \texttt{"} Data Type Codes\texttt{"}  section below for the codes appropriate to
+      other numerical types).
+   }
+   \sstsynopsis{
+      AstPolygon $*$astOutline$<$X$>$( $<$Xtype$>$ value, int oper, const $<$Xtype$>$ array[],
+                                 const int lbnd[2], const int ubnd[2], double maxerr,
+                                 int maxvert, const int inside[2], int starpix )
+   }
+   \sstparameters{
+      \sstsubsection{
+         value
+      }{
+         A data value that specifies the pixels to be outlined.
+      }
+      \sstsubsection{
+         oper
+      }{
+         Indicates how the
+         \texttt{"} value\texttt{"}
+         parameter is used to select the outlined pixels. It can
+         have any of the following values:
+         \sstitemlist{
+
+            \sstitem
+             AST\_\_LT: outline pixels with value less than \texttt{"} value\texttt{"} .
+
+            \sstitem
+             AST\_\_LE: outline pixels with value less than or equal to \texttt{"} value\texttt{"} .
+
+            \sstitem
+             AST\_\_EQ: outline pixels with value equal to \texttt{"} value\texttt{"} .
+
+            \sstitem
+             AST\_\_NE: outline pixels with value not equal to \texttt{"} value\texttt{"} .
+
+            \sstitem
+             AST\_\_GE: outline pixels with value greater than or equal to \texttt{"} value\texttt{"} .
+
+            \sstitem
+             AST\_\_GT: outline pixels with value greater than \texttt{"} value\texttt{"} .
+         }
+      }
+      \sstsubsection{
+         array
+      }{
+         Pointer to a
+         2-dimensional array containing the data to be processed.  The
+         numerical type of this array should match the 1- or
+         2-character type code appended to the function name (e.g. if
+         you are using astOutlineF, the type of each array element
+         should be \texttt{"} float\texttt{"} ).
+
+         The storage order of data within this array should be such
+         that the index of the first grid dimension varies most
+         rapidly and that of the second dimension least rapidly
+         (i.e. Fortran array indexing is used).
+      }
+      \sstsubsection{
+         lbnd
+      }{
+         Pointer to an array of two integers
+         containing the pixel index of the first pixel in the input grid
+         along each dimension.
+      }
+      \sstsubsection{
+         ubnd
+      }{
+         Pointer to an array of two integers
+         containing the pixel index of the last pixel in the input grid
+         along each dimension.
+
+         Note that \texttt{"} lbnd\texttt{"}  and \texttt{"} ubnd\texttt{"}  together define the shape
+         and size of the input pixel grid, its extent along a particular
+         (j\texttt{'} th) dimension being ubnd[j]-lbnd[j]$+$1 pixels.
+         For FITS images,
+         the lbnd values will be 1 and the ubnd
+         values will be equal to the NAXISi header values. Other
+         data systems, such as the Starlink NDF system, allow an
+         arbitrary pixel origin to be used (i.e. lbnd
+         is not necessarily 1).
+
+         These bounds also define the input grid\texttt{'} s floating point coordinate
+         system, each pixel having unit extent along each dimension with
+         integral coordinate values at its centre or upper corner, as selected
+         by parameter
+         \texttt{"} starpix\texttt{"} .
+      }
+      \sstsubsection{
+         maxerr
+      }{
+         Together with
+         \texttt{"} maxvert\texttt{"} ,
+         this determines how accurately the returned Polygon represents
+         the required region of the data array. It gives the target
+         discrepancy between the returned Polygon and the accurate outline
+         in the data array, expressed as a number of pixels. Insignificant
+         vertices are removed from the accurate outline, one by one, until
+         the number of vertices remaining in the returned Polygon equals
+         \texttt{"} maxvert\texttt{"} ,
+         or the largest discrepancy between the accurate outline and the
+         returned Polygon is greater than
+         \texttt{"} maxerr\texttt{"} . If \texttt{"} maxerr\texttt{"}
+         is zero or less, its value is ignored and the returned Polygon will
+         have the number of vertices specified by
+         \texttt{"} maxvert\texttt{"} .
+      }
+      \sstsubsection{
+         maxvert
+      }{
+         Together with
+         \texttt{"} maxerr\texttt{"} ,
+         this determines how accurately the returned Polygon represents
+         the required region of the data array. It gives the maximum
+         allowed number of vertices in the returned Polygon. Insignificant
+         vertices are removed from the accurate outline, one by one, until
+         the number of vertices remaining in the returned Polygon equals
+         \texttt{"} maxvert\texttt{"} ,
+         or the largest discrepancy between the accurate outline and the
+         returned Polygon is greater than
+         \texttt{"} maxerr\texttt{"} . If \texttt{"} maxvert\texttt{"}
+         is less than 3, its value is ignored and the number of vertices in
+         the returned Polygon will be the minimum needed to ensure that the
+         discrepancy between the accurate outline and the returned
+         Polygon is less than
+         \texttt{"} maxerr\texttt{"} .
+      }
+      \sstsubsection{
+         inside
+      }{
+         Pointer to an array of two integers
+         containing the pixel indices of a pixel known to be inside the
+         required region. This is needed because the supplied data
+         array may contain several disjoint areas of pixels that satisfy
+         the criterion specified by
+         \texttt{"} value\texttt{"}  and \texttt{"} oper\texttt{"} .
+         In such cases, the area described by the returned Polygon will
+         be the one that contains the pixel specified by
+         \texttt{"} inside\texttt{"} .
+         If the specified pixel is outside the bounds given by
+         \texttt{"} lbnd\texttt{"}  and \texttt{"} ubnd\texttt{"} ,
+         or has a value that does not meet the criterion specified by
+         \texttt{"} value\texttt{"}  and \texttt{"} oper\texttt{"} ,
+         then this function will search for a suitable pixel. The search
+         starts at the central pixel and proceeds in a spiral manner until
+         a pixel is found that meets the specified crierion.
+      }
+      \sstsubsection{
+         starpix
+      }{
+         A flag indicating the nature of the pixel coordinate system used
+         to describe the vertex positions in the returned Polygon. If
+         non-zero,
+         the standard Starlink definition of pixel coordinate is used in
+         which a pixel with integer index I spans a range of pixel coordinate
+         from (I-1) to I (i.e. pixel corners have integral pixel coordinates).
+         If zero,
+         the definition of pixel coordinate used by other AST functions
+         such as astResample, astMask,
+         etc., is used. In this definition, a pixel with integer index I
+         spans a range of pixel coordinate from (I-0.5) to (I$+$0.5) (i.e.
+         pixel centres have integral pixel coordinates).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astOutline$<$X$>$()
+      }{
+         A pointer to the required Polygon.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This function proceeds by first finding a very accurate polygon,
+         and then removing insignificant vertices from this fine polygon
+         using
+         \htmlref{astDownsize}{astDownsize}.
+
+         \sstitem
+          The returned Polygon is the outer boundary of the contiguous set
+         of pixels that includes ths specified \texttt{"} inside\texttt{"}  point, and satisfy
+         the specified value requirement. This set of pixels may potentially
+         include \texttt{"} holes\texttt{"}  where the pixel values fail to meet the specified
+         value requirement. Such holes will be ignored by this function.
+
+         \sstitem
+          NULL
+         will be returned if this function is invoked with the global
+         error status set, or if it should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      Data Type Codes
+   }{
+      To select the appropriate masking function, you should
+      replace $<$X$>$ in the generic function name astOutline$<$X$>$ with a
+      1- or 2-character data type code, so as to match the numerical
+      type $<$Xtype$>$ of the data you are processing, as follows:
+      \sstitemlist{
+
+         \sstitem
+          D: double
+
+         \sstitem
+          F: float
+
+         \sstitem
+          L: long int
+
+         \sstitem
+          UL: unsigned long int
+
+         \sstitem
+          I: int
+
+         \sstitem
+          UI: unsigned int
+
+         \sstitem
+          S: short int
+
+         \sstitem
+          US: unsigned short int
+
+         \sstitem
+          B: byte (signed char)
+
+         \sstitem
+          UB: unsigned byte (unsigned char)
+
+      }
+      For example, astOutlineD would be used to process \texttt{"} double\texttt{"}
+      data, while astOutlineS would be used to process \texttt{"} short int\texttt{"}
+      data, etc.
+   }
+}
+\sstroutine{
+   astOverlap
+}{
+   Test if two regions overlap each other
+}{
+   \sstdescription{
+      This function returns an integer value indicating if the two
+      supplied Regions overlap. The two Regions are converted to a commnon
+      coordinate system before performing the check. If this conversion is
+      not possible (for instance because the two Regions represent areas in
+      different domains), then the check cannot be performed and a zero value
+      is returned to indicate this.
+   }
+   \sstsynopsis{
+      int astOverlap( AstRegion $*$this, AstRegion $*$that )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the first \htmlref{Region}{Region}.
+      }
+      \sstsubsection{
+         that
+      }{
+         Pointer to the second Region.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astOverlap()
+      }{
+         A value indicating if there is any overlap between the two Regions.
+         Possible values are:
+
+         0 - The check could not be performed because the second Region
+             could not be mapped into the coordinate system of the first
+             Region.
+
+         1 - There is no overlap between the two Regions.
+
+         2 - The first Region is completely inside the second Region.
+
+         3 - The second Region is completely inside the first Region.
+
+         4 - There is partial overlap between the two Regions.
+
+         5 - The Regions are identical to within their uncertainties.
+
+         6 - The second Region is the exact negation of the first Region
+             to within their uncertainties.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The returned values 5 and 6 do not check the value of the \htmlref{Closed}{Closed}
+         attribute in the two Regions.
+
+         \sstitem
+          A value of zero will be returned if this function is invoked with the
+         AST error status set, or if it should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astParameterName
+}{
+   Get the name of the global parameter at a given index within the Table
+}{
+   \sstdescription{
+      This function returns a string holding the name of the global parameter with
+      the given index within the \htmlref{Table}{Table}.
+
+      This function is intended primarily as a means of iterating round all
+      the parameters in a Table. For this purpose, the number of parameters in
+      the Table is given by the \htmlref{Nparameter}{Nparameter} attribute of the Table. This function
+      could then be called in a loop, with the index value going from
+      zero to one less than Nparameter.
+
+      Note, the index associated with a parameter decreases monotonically with
+      the age of the parameter: the oldest Parameter in the Table will have index
+      one, and the Parameter added most recently to the Table will have the
+      largest index.
+   }
+   \sstsynopsis{
+      const char $*$astParameterName( AstTable $*$this, int index )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Table.
+      }
+      \sstsubsection{
+         index
+      }{
+         The index into the list of parameters. The first parameter has index
+         one, and the last has index \texttt{"} Nparameter\texttt{"} .
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astParameterName()
+      }{
+         A pointer to a null-terminated string containing the
+         upper case parameter name.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The returned pointer is guaranteed to remain valid and the
+         string to which it points will not be over-written for a total
+         of 50 successive invocations of this function. After this, the
+         memory containing the string may be re-used, so a copy of the
+         string should be made if it is needed for longer than this.
+
+         \sstitem
+          A NULL pointer will be returned if this function is invoked
+         with the AST error status set, or if it should fail for any
+         reason.
+      }
+   }
+}
+\sstroutine{
+   astPcdMap
+}{
+   Create a PcdMap
+}{
+   \sstdescription{
+      This function creates a new \htmlref{PcdMap}{PcdMap} and optionally initialises its
+      attributes.
+
+      A PcdMap is a non-linear \htmlref{Mapping}{Mapping} which transforms 2-dimensional
+      positions to correct for the radial distortion introduced by some
+      cameras and telescopes. This can take the form either of pincushion
+      or barrel distortion, and is characterized by a single distortion
+      coefficient.
+
+      A PcdMap is specified by giving this distortion coefficient and the
+      coordinates of the centre of the radial distortion. The forward
+      transformation of a PcdMap applies the distortion:
+
+         RD = R $*$ ( 1 $+$ C $*$ R $*$ R )
+
+      where R is the undistorted radial distance from the distortion
+      centre (specified by attribute PcdCen), RD is the radial distance
+      from the same centre in the presence of distortion, and C is the
+      distortion coefficient (given by attribute \htmlref{Disco}{Disco}).
+
+      The inverse transformation of a PcdMap removes the distortion
+      produced by the forward transformation. The expression used to derive
+      R from RD is an approximate inverse of the expression above, obtained
+      from two iterations of the Newton-Raphson method. The mismatch between
+      the forward and inverse expressions is negligible for astrometric
+      applications (to reach 1 milliarcsec at the edge of the Anglo-Australian
+      Telescope triplet or a Schmidt field would require field diameters of
+      2.4 and 42 degrees respectively).
+
+      If a PcdMap is inverted (e.g. using \htmlref{astInvert}{astInvert}) then the roles of the
+      forward and inverse transformations are reversed; the forward
+      transformation will remove the distortion, and the inverse
+      transformation will apply it.
+   }
+   \sstsynopsis{
+      AstPcdMap $*$astPcdMap( double disco, const double pcdcen[2],
+                            const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         disco
+      }{
+         The distortion coefficient. Negative values give barrel
+         distortion, positive values give pincushion distortion, and
+         zero gives no distortion.
+      }
+      \sstsubsection{
+         pcdcen
+      }{
+         A 2-element array containing the coordinates of the centre of the
+         distortion.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new PcdMap. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astPcdMap()
+      }{
+         A pointer to the new PcdMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      Status Handling
+   }{
+      The protected interface to this function includes an extra
+      parameter at the end of the parameter list descirbed above. This
+      parameter is a pointer to the integer inherited status
+      variable: \texttt{"} int $*$status\texttt{"} .
+   }
+}
+\sstroutine{
+   astPermAxes
+}{
+   Permute the axis order in a Frame
+}{
+   \sstdescription{
+      This function permutes the order in which a \htmlref{Frame}{Frame}\texttt{'} s axes occur.
+   }
+   \sstsynopsis{
+      void astPermAxes( AstFrame $*$this, const int perm[] )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Frame.
+      }
+      \sstsubsection{
+         perm
+      }{
+         An array with one element for each axis of the Frame (\htmlref{Naxes}{Naxes}
+         attribute). This should list the axes in their new order,
+         using the original axis numbering (which starts at 1 for the
+         first axis).
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Only genuine permutations of the axis order are permitted, so
+         each axis must be referenced exactly once in the \texttt{"} perm\texttt{"}  array.
+
+         \sstitem
+          If successive axis permutations are applied to a Frame, then
+         the effects are cumulative.
+      }
+   }
+}
+\sstroutine{
+   astPermMap
+}{
+   Create a PermMap
+}{
+   \sstdescription{
+      This function creates a new \htmlref{PermMap}{PermMap} and optionally initialises its
+      attributes.
+
+      A PermMap is a \htmlref{Mapping}{Mapping} which permutes the order of coordinates,
+      and possibly also changes the number of coordinates, between its
+      input and output.
+
+      In addition to permuting the coordinate order, a PermMap may
+      also assign constant values to coordinates. This is useful when
+      the number of coordinates is being increased as it allows fixed
+      values to be assigned to any new ones.
+   }
+   \sstsynopsis{
+      AstPermMap $*$astPermMap( int nin, const int inperm[], int nout,
+                              const int outperm[], double constant[],
+                              const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         nin
+      }{
+         The number of input coordinates.
+      }
+      \sstsubsection{
+         inperm
+      }{
+         An optional array with \texttt{"} nin\texttt{"}  elements which, for each input
+         coordinate, should contain the number of the output
+         coordinate whose value is to be used (note that this array
+         therefore defines the inverse coordinate transformation).
+         Coordinates are numbered starting from 1.
+
+         For details of additional special values that may be used in
+         this array, see the description of the \texttt{"} constant\texttt{"}  parameter.
+
+         If a NULL pointer is supplied instead of an array, each input
+         coordinate will obtain its value from the corresponding
+         output coordinate (or will be assigned the value AST\_\_BAD if
+         there is no corresponding output coordinate).
+      }
+      \sstsubsection{
+         nout
+      }{
+         The number of output coordinates.
+      }
+      \sstsubsection{
+         outperm
+      }{
+         An optional array with \texttt{"} nout\texttt{"}  elements which, for each output
+         coordinate, should contain the number of the input coordinate
+         whose value is to be used (note that this array therefore
+         defines the forward coordinate transformation).  Coordinates
+         are numbered starting from 1.
+
+         For details of additional special values that may be used in
+         this array, see the description of the \texttt{"} constant\texttt{"}  parameter.
+
+         If a NULL pointer is supplied instead of an array, each output
+         coordinate will obtain its value from the corresponding
+         input coordinate (or will be assigned the value AST\_\_BAD if
+         there is no corresponding input coordinate).
+      }
+      \sstsubsection{
+         constant
+      }{
+         An optional array containing values which may be assigned to
+         input and/or output coordinates instead of deriving them
+         from other coordinate values. If either of the \texttt{"} inperm\texttt{"}  or
+         \texttt{"} outperm\texttt{"}  arrays contains a negative value, it is used to
+         address this \texttt{"} constant\texttt{"}  array (such that -1 addresses the
+         first element, -2 addresses the second element, etc.) and the
+         value obtained is used as the corresponding coordinate value.
+
+         Care should be taken to ensure that locations lying outside
+         the extent of this array are not accidentally addressed. The
+         array is not used if the \texttt{"} inperm\texttt{"}  and \texttt{"} outperm\texttt{"}  arrays do not
+         contain negative values.
+
+         If a NULL pointer is supplied instead of an array, the
+         behaviour is as if the array were of infinite length and
+         filled with the value AST\_\_BAD.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new PermMap. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astPermMap()
+      }{
+         A pointer to the new PermMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If either of the \texttt{"} inperm\texttt{"}  or \texttt{"} outperm\texttt{"}  arrays contains a
+         zero value (or a positive value which does not identify a valid
+         output/input coordinate, as appropriate), then the value
+         AST\_\_BAD is assigned as the new coordinate value.
+
+         \sstitem
+          This function does not attempt to ensure that the forward and
+         inverse transformations performed by the PermMap are
+         self-consistent in any way. You are therefore free to supply
+         coordinate permutation arrays that achieve whatever effect is
+         desired.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astPickAxes
+}{
+   Create a new Frame by picking axes from an existing one
+}{
+   \sstdescription{
+      This function creates a new \htmlref{Frame}{Frame} whose axes are copied from an
+      existing Frame along with other Frame attributes, such as its
+      \htmlref{Title}{Title}. Any number (zero or more) of the original Frame\texttt{'} s axes
+      may be copied, in any order, and additional axes with default
+      attributes may also be included in the new Frame.
+
+      Optionally, a \htmlref{Mapping}{Mapping} that converts between the coordinate
+      systems described by the two Frames will also be returned.
+   }
+   \sstsynopsis{
+      AstFrame $*$astPickAxes( AstFrame $*$this, int naxes, const int axes[],
+                             AstMapping $*$$*$map )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the original Frame.
+      }
+      \sstsubsection{
+         naxes
+      }{
+         The number of axes required in the new Frame.
+      }
+      \sstsubsection{
+         axes
+      }{
+         An array, with \texttt{"} naxes\texttt{"}  elements, which lists the axes to be
+         copied. These should be given in the order required in the
+         new Frame, using the axis numbering in the original Frame
+         (which starts at 1 for the first axis). Axes may be selected
+         in any order, but each may only be used once.  If additional
+         (default) axes are also to be included, the corresponding
+         elements of this array should be set to zero.
+      }
+      \sstsubsection{
+         map
+      }{
+         Address of a location in which to return a pointer to a new
+         Mapping. This will be a \htmlref{PermMap}{PermMap} (or a \htmlref{UnitMap}{UnitMap} as a special
+         case) that describes the axis permutation that has taken
+         place between the original and new Frames. The Mapping\texttt{'} s
+         forward transformation will convert coordinates from the
+         original Frame into the new one, and vice versa.
+
+         If this Mapping is not required, a NULL value may be supplied
+         for this parameter.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Frame
+      }{
+         This function applies to all Frames. The class of Frame returned
+         may differ from that of the original Frame, depending on which
+         axes are selected. For example, if a single axis is picked from a
+         \htmlref{SkyFrame}{SkyFrame} (which must always have two axes) then the resulting
+         Frame cannot be a valid SkyFrame, so will revert to the parent
+         class (Frame) instead.
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         Using this function on a FrameSet is identical to using it on
+         the current Frame in the FrameSet. The returned Frame will not
+         be a FrameSet.
+      }
+      \sstsubsection{
+         \htmlref{Region}{Region}
+      }{
+         If this function is used on a Region, an attempt is made to
+         retain the bounds information on the selected axes. If
+         succesful, the returned Frame will be a Region of some class.
+         Otherwise, the returned Frame is obtained by calling this
+         function on the Frame represented by the supplied Region (the
+         returned Frame will then not be a Region). In order to be
+         succesful, the selected axes in the Region must be independent
+         of the others. For instance, a \htmlref{Box}{Box} can be split in this way but
+         a \htmlref{Circle}{Circle} cannot. Another requirement for success is that no
+         default axes are added (that is, the
+         \texttt{"} axes\texttt{"}
+         array must not contain any zero values.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astPickAxes()
+      }{
+         A pointer to the new Frame.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The new Frame will contain a \texttt{"} deep\texttt{"}  copy (c.f. \htmlref{astCopy}{astCopy}) of all
+         the data selected from the original Frame. Modifying any aspect
+         of the new Frame will therefore not affect the original one.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astPlot
+}{
+   Create a Plot
+}{
+   \sstdescription{
+      This function creates a new \htmlref{Plot}{Plot} and optionally initialises its
+      attributes.
+
+      A Plot is a specialised form of \htmlref{FrameSet}{FrameSet}, in which the base
+      \htmlref{Frame}{Frame} describes a \texttt{"} graphical\texttt{"}  coordinate system and is
+      associated with a rectangular plotting area in the underlying
+      graphics system. This plotting area is where graphical output
+      appears. It is defined when the Plot is created.
+
+      The current Frame of a Plot describes a \texttt{"} physical\texttt{"}  coordinate
+      system, which is the coordinate system in which plotting
+      operations are specified. The results of each plotting operation
+      are automatically transformed into graphical coordinates so as
+      to appear in the plotting area (subject to any clipping which
+      may be in effect).
+
+      Because the \htmlref{Mapping}{Mapping} between physical and graphical coordinates
+      may often be non-linear, or even discontinuous, most plotting
+      does not result in simple straight lines. The basic plotting
+      element is therefore not a straight line, but a geodesic curve
+      (see \htmlref{astCurve}{astCurve}). A Plot also provides facilities for drawing
+      markers or symbols (\htmlref{astMark}{astMark}), text (\htmlref{astText}{astText}) and grid lines
+      (\htmlref{astGridLine}{astGridLine}). It is also possible to draw curvilinear axes with
+      optional coordinate grids (\htmlref{astGrid}{astGrid}).
+      A range of Plot attributes is available to allow precise control
+      over the appearance of graphical output produced by these
+      functions.
+
+      You may select different physical coordinate systems in which to
+      plot (including the native graphical coordinate system itself)
+      by selecting different Frames as the current Frame of a Plot,
+      using its \htmlref{Current}{Current} attribute.  You may also set up clipping (see
+      \htmlref{astClip}{astClip}) to limit the extent of any plotting you perform, and
+      this may be done in any of the coordinate systems associated
+      with the Plot, not necessarily the one you are plotting in.
+
+      Like any FrameSet, a Plot may also be used as a Frame. In this
+      case, it behaves like its current Frame, which describes the
+      physical coordinate system.
+
+      When used as a Mapping, a Plot describes the inter-relation
+      between graphical coordinates (its base Frame) and physical
+      coordinates (its current Frame).  It differs from a normal
+      FrameSet, however, in that an attempt to transform points which
+      lie in clipped areas of the Plot will result in bad coordinate
+      values (AST\_\_BAD).
+   }
+   \sstsynopsis{
+      AstPlot $*$astPlot( AstFrame $*$frame, const float graphbox[ 4 ],
+                        const double basebox[ 4 ], const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         frame
+      }{
+         Pointer to a Frame describing the physical coordinate system
+         in which to plot. A pointer to a FrameSet may also be given,
+         in which case its current Frame will be used to define the
+         physical coordinate system and its base Frame will be mapped
+         on to graphical coordinates (see below).
+
+         If a null \htmlref{Object}{Object} pointer (AST\_\_NULL) is given, a default
+         2-dimensional Frame will be used to describe the physical
+         coordinate system. Labels, etc. may then be attached to this
+         by setting the appropriate Frame attributes
+         (e.g. \htmlref{Label(axis)}{Label(axis)}) for the Plot.
+      }
+      \sstsubsection{
+         graphbox
+      }{
+         An array giving the position and extent of the plotting area
+         (on the plotting surface of the underlying graphics system)
+         in which graphical output is to appear. This must be
+         specified using graphical coordinates appropriate to the
+         underlying graphics system.
+
+         The first pair of values should give the coordinates of the
+         bottom left corner of the plotting area and the second pair
+         should give the coordinates of the top right corner. The
+         coordinate on the horizontal axis should be given first in
+         each pair. Note that the order in which these points are
+         given is important because it defines up, down, left and
+         right for subsequent graphical operations.
+      }
+      \sstsubsection{
+         basebox
+      }{
+         An array giving the coordinates of two points in the supplied
+         Frame (or in the base Frame if a FrameSet was supplied) which
+         correspond to the bottom left and top right corners of the
+         plotting area, as specified above. This range of coordinates
+         will be mapped linearly on to the plotting area. The
+         coordinates should be given in the same order as above.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new Plot. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+         If no initialisation is required, a zero-length string may be
+         supplied.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astPlot()
+      }{
+         A pointer to the new Plot.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The base Frame of the returned Plot will be a new Frame which
+         is created by this function to represent the coordinate system
+         of the underlying graphics system (graphical coordinates). It is
+         given a Frame index of 1 within the Plot. The choice of base
+         Frame (\htmlref{Base}{Base} attribute) should not, in general, be changed once a
+         Plot has been created (although you could use this as a way of
+         moving the plotting area around on the plotting surface).
+
+         \sstitem
+          If a Frame is supplied (via the \texttt{"} frame\texttt{"}  pointer), then it
+         becomes the current Frame of the new Plot and is given a Frame
+         index of 2.
+
+         \sstitem
+          If a FrameSet is supplied (via the \texttt{"} frame\texttt{"}  pointer), then
+         all the Frames within this FrameSet become part of the new Plot
+         (where their Frame indices are increased by 1), with the
+         FrameSet\texttt{'} s current Frame becoming the current Frame of the Plot.
+
+         \sstitem
+          If a null Object pointer (AST\_\_NULL) is supplied (via the
+         \texttt{"} frame\texttt{"}  pointer), then the returned Plot will contain two
+         Frames, both created by this function. The base Frame will
+         describe graphics coordinates (as above) and the current Frame
+         will be a basic Frame with no attributes set (this will
+         therefore give default values for such things as the Plot \htmlref{Title}{Title}
+         and the Label on each axis). Physical coordinates will be mapped
+         linearly on to graphical coordinates.
+
+         \sstitem
+          An error will result if the Frame supplied (or the base Frame
+         if a FrameSet was supplied) is not 2-dimensional.
+
+         \sstitem
+          A null Object pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astPlot3D
+}{
+   Create a Plot3D
+}{
+   \sstdescription{
+      This function creates a new \htmlref{Plot3D}{Plot3D} and optionally initialises
+      its attributes.
+
+      A Plot3D is a specialised form of \htmlref{Plot}{Plot} that provides facilities
+      for producing 3D graphical output.
+   }
+   \sstsynopsis{
+      AstPlot3D $*$astPlot3D( AstFrame $*$frame, const float graphbox[ 6 ],
+                            const double basebox[ 6 ], const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         frame
+      }{
+         Pointer to a \htmlref{Frame}{Frame} describing the physical coordinate system
+         in which to plot. A pointer to a \htmlref{FrameSet}{FrameSet} may also be given,
+         in which case its current Frame will be used to define the
+         physical coordinate system and its base Frame will be mapped
+         on to graphical coordinates (see below).
+
+         If a null \htmlref{Object}{Object} pointer (AST\_\_NULL) is given, a default
+         3-dimensional Frame will be used to describe the physical
+         coordinate system. Labels, etc. may then be attached to this
+         by setting the appropriate Frame attributes
+         (e.g. \htmlref{Label(axis)}{Label(axis)}) for the Plot.
+      }
+      \sstsubsection{
+         graphbox
+      }{
+         An array giving the position and extent of the plotting volume
+         (within the plotting space of the underlying graphics system)
+         in which graphical output is to appear. This must be
+         specified using graphical coordinates appropriate to the
+         underlying graphics system.
+
+         The first triple of values should give the coordinates of the
+         bottom left corner of the plotting volume and the second triple
+         should give the coordinates of the top right corner. The
+         coordinate on the horizontal axis should be given first in
+         each pair. Note that the order in which these points are
+         given is important because it defines up, down, left and
+         right for subsequent graphical operations.
+      }
+      \sstsubsection{
+         basebox
+      }{
+         An array giving the coordinates of two points in the supplied
+         Frame (or in the base Frame if a FrameSet was supplied) which
+         correspond to the bottom left and top right corners of the
+         plotting volume, as specified above. This range of coordinates
+         will be mapped linearly on to the plotting area. The
+         coordinates should be given in the same order as above.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new Plot3D. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+         If no initialisation is required, a zero-length string may be
+         supplied.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astPlot3D()
+      }{
+         A pointer to the new Plot3D.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The base Frame of the returned Plot3D will be a new Frame which
+         is created by this function to represent the coordinate system
+         of the underlying graphics system (graphical coordinates). It is
+         given a Frame index of 1 within the Plot3D. The choice of base
+         Frame (\htmlref{Base}{Base} attribute) should not, in general, be changed once a
+         Plot3D has been created (although you could use this as a way of
+         moving the plotting area around on the plotting surface).
+
+         \sstitem
+          If a Frame is supplied (via the \texttt{"} frame\texttt{"}  pointer), then it
+         becomes the current Frame of the new Plot3D and is given a Frame
+         index of 2.
+
+         \sstitem
+          If a FrameSet is supplied (via the \texttt{"} frame\texttt{"}  pointer), then
+         all the Frames within this FrameSet become part of the new Plot3D
+         (where their Frame indices are increased by 1), with the
+         FrameSet\texttt{'} s current Frame becoming the current Frame of the Plot3D.
+
+         \sstitem
+          At least one of the three axes of the current Frame must be
+         independent of the other two current Frame axes.
+
+         \sstitem
+          If a null Object pointer (AST\_\_NULL) is supplied (via the
+         \texttt{"} frame\texttt{"}  pointer), then the returned Plot3D will contain two
+         Frames, both created by this function. The base Frame will
+         describe graphics coordinates (as above) and the current Frame
+         will be a basic Frame with no attributes set (this will
+         therefore give default values for such things as the Plot3D \htmlref{Title}{Title}
+         and the Label on each axis). Physical coordinates will be mapped
+         linearly on to graphical coordinates.
+
+         \sstitem
+          An error will result if the Frame supplied (or the base Frame
+         if a FrameSet was supplied) is not 3-dimensional.
+
+         \sstitem
+          A null Object pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astPointList
+}{
+   Create a PointList
+}{
+   \sstdescription{
+      This function creates a new \htmlref{PointList}{PointList} object and optionally initialises
+      its attributes.
+
+      A PointList object is a specialised type of \htmlref{Region}{Region} which represents a
+      collection of points in a coordinate \htmlref{Frame}{Frame}.
+   }
+   \sstsynopsis{
+      AstPointList $*$astPointList( AstFrame $*$frame, int npnt, int ncoord, int dim,
+                                  const double $*$points, AstRegion $*$unc,
+                                  const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         frame
+      }{
+         A pointer to the Frame in which the region is defined. A deep
+         copy is taken of the supplied Frame. This means that any
+         subsequent changes made to the Frame using the supplied pointer
+         will have no effect the Region.
+      }
+      \sstsubsection{
+         npnt
+      }{
+         The number of points in the Region.
+      }
+      \sstsubsection{
+         ncoord
+      }{
+         The number of coordinates being supplied for each point. This
+         must equal the number of axes in the supplied Frame, given by
+         its \htmlref{Naxes}{Naxes} attribute.
+      }
+      \sstsubsection{
+         dim
+      }{
+         The number of elements along the second dimension of the \texttt{"} points\texttt{"}
+         array (which contains the point coordinates). This value is
+         required so that the coordinate values can be correctly
+         located if they do not entirely fill this array. The value
+         given should not be less than \texttt{"} npnt\texttt{"} .
+      }
+      \sstsubsection{
+         points
+      }{
+         The address of the first element of a 2-dimensional array of
+         shape \texttt{"} [ncoord][dim]\texttt{"}  giving the physical coordinates of the
+         points. These should be stored such that the value of coordinate
+         number \texttt{"} coord\texttt{"}  for point number \texttt{"} pnt\texttt{"}  is found in element
+         \texttt{"} in[coord][pnt]\texttt{"} .
+      }
+      \sstsubsection{
+         unc
+      }{
+         An optional pointer to an existing Region which specifies the uncertainties
+         associated with each point in the PointList being created. The
+         uncertainty at any point in the PointList is found by shifting the
+         supplied \texttt{"} uncertainty\texttt{"}  Region so that it is centred at the point
+         being considered. The area covered by the shifted uncertainty Region
+         then represents the uncertainty in the position. The uncertainty is
+         assumed to be the same for all points.
+
+         If supplied, the uncertainty Region must be of a class for which
+         all instances are centro-symetric (e.g. \htmlref{Box}{Box}, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.)
+         or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep
+         copy of the supplied Region will be taken, so subsequent changes to
+         the uncertainty Region using the supplied pointer will have no
+         effect on the created Box. Alternatively,
+         a NULL \htmlref{Object}{Object} pointer
+         may be supplied, in which case a default uncertainty is used
+         equivalent to a box 1.0E-6 of the size of the bounding box of the
+         PointList being created.
+
+         The uncertainty Region has two uses: 1) when the
+         \htmlref{astOverlap}{astOverlap}
+         function compares two Regions for equality the uncertainty
+         Region is used to determine the tolerance on the comparison, and 2)
+         when a Region is mapped into a different coordinate system and
+         subsequently simplified (using
+         \htmlref{astSimplify}{astSimplify}),
+         the uncertainties are used to determine if the transformed boundary
+         can be accurately represented by a specific shape of Region.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new PointList. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astPointList()
+      }{
+         A pointer to the new PointList.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null Object pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      Status Handling
+   }{
+      The protected interface to this function includes an extra
+      parameter at the end of the parameter list descirbed above. This
+      parameter is a pointer to the integer inherited status
+      variable: \texttt{"} int $*$status\texttt{"} .
+   }
+}
+\sstroutine{
+   astPolyCoeffs
+}{
+   Retrieve the coefficient values used by a PolyMap
+}{
+   \sstdescription{
+      This function returns the coefficient values used by either the
+      forward or inverse transformation of a \htmlref{PolyMap}{PolyMap}, in the same form
+      that they are supplied to the PolyMap constructor.
+
+      Usually, you should call this method first with
+      \texttt{"} nel\texttt{"}
+      set to zero to determine the number of coefficients used by the
+      PolyMap. This allows you to allocate an array of the correct size to
+      hold all coefficient data. You should then call this method a
+      second time to get the coefficient data.
+   }
+   \sstsynopsis{
+      void astPolyCoeffs( AstPolyMap $*$this, int forward, int nel, double $*$coeffs,
+                          int $*$ncoeff )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the original \htmlref{Mapping}{Mapping}.
+      }
+      \sstsubsection{
+         forward
+      }{
+         If non-zero,
+         the coefficients of the forward PolyMap transformation are
+         returned. Otherwise the inverse transformation coefficients are
+         returned.
+      }
+      \sstsubsection{
+         nel
+      }{
+         The length of the supplied
+         \texttt{"} coeffs\texttt{"}
+         array. It should be at least \texttt{"} ncoeff$*$( nin $+$ 2 )\texttt{"}  if
+         \texttt{"} foward\texttt{"}  is non-zero,
+         and \texttt{"} ncoeff$*$( nout $+$ 2 )\texttt{"}  otherwise, where \texttt{"} ncoeff\texttt{"}  is the
+         number of coefficients to be returned. If a value of zero
+         is supplied, no coefficient values are returned, but the
+         number of coefficients used by the transformation is still
+         returned in
+         \texttt{"} ncoeff\texttt{"} .
+      }
+      \sstsubsection{
+         coeffs
+      }{
+         An array in which to return the coefficients used by the
+         requested transformation of the PolyMap. Ignored if
+         \texttt{"} nel\texttt{"}  is zero.
+         The coefficient data is returned in the form in which it is
+         supplied to the PolyMap constructor. That is, each group of
+         \texttt{"} 2 $+$ nin\texttt{"}  or \texttt{"} 2 $+$ nout\texttt{"}  adjacent elements describe a single
+         coefficient of the forward or inverse transformation. See the
+         PolyMap constructor documentation for further details.
+
+         If the supplied array is too short to hold all the coefficients,
+         trailing coefficients are excluded. If the supplied array is
+         longer than needed to hold all the coefficients, trailing
+         elements are filled with zeros.
+      }
+      \sstsubsection{
+         ncoeff
+      }{
+         The number of coefficients used by the requested transformation.
+         A value of zero is returned if the transformation does not
+         have any defining polynomials. A value is returned for this argument
+         even if
+         \texttt{"} nel\texttt{"}  is zero.
+      }
+   }
+}
+\sstroutine{
+   astPolyCurve
+}{
+   Draw a series of connected geodesic curves
+}{
+   \sstdescription{
+      This function joins a series of points specified in the physical
+      coordinate system of a \htmlref{Plot}{Plot} by drawing a sequence of geodesic
+      curves.  It is equivalent to making repeated use of the \htmlref{astCurve}{astCurve}
+      function (q.v.), except that astPolyCurve will generally be more
+      efficient when drawing many geodesic curves end-to-end. A
+      typical application of this might be in drawing contour lines.
+
+      As with astCurve, full account is taken of the \htmlref{Mapping}{Mapping} between
+      physical and graphical coordinate systems. This includes any
+      discontinuities and clipping established using \htmlref{astClip}{astClip}.
+   }
+   \sstsynopsis{
+      void astPolyCurve( AstPlot $*$this, int npoint, int ncoord, int indim,
+                         const double $*$in )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Plot.
+      }
+      \sstsubsection{
+         npoint
+      }{
+         The number of points between which geodesic curves are to be drawn.
+      }
+      \sstsubsection{
+         ncoord
+      }{
+         The number of coordinates being supplied for each point (i.e.
+         the number of axes in the current \htmlref{Frame}{Frame} of the Plot, as given
+         by its \htmlref{Naxes}{Naxes} attribute).
+      }
+      \sstsubsection{
+         indim
+      }{
+         The number of elements along the second dimension of the \texttt{"} in\texttt{"}
+         array (which contains the input coordinates). This value is
+         required so that the coordinate values can be correctly
+         located if they do not entirely fill this array. The value
+         given should not be less than \texttt{"} npoint\texttt{"} .
+      }
+      \sstsubsection{
+         in
+      }{
+         The address of the first element in a 2-dimensional array of shape
+         \texttt{"} [ncoord][indim]\texttt{"}  giving the
+         physical coordinates of the points which are to be joined in
+         sequence by geodesic curves. These should be stored such that
+         the value of coordinate number \texttt{"} coord\texttt{"}  for point number
+         \texttt{"} point\texttt{"}  is found in element \texttt{"} in[coord][point]\texttt{"} .
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          No curve is drawn on either side of any point which has any
+         coordinate equal to the value AST\_\_BAD.
+
+         \sstitem
+          An error results if the base Frame of the Plot is not
+         2-dimensional.
+
+         \sstitem
+          An error also results if the transformation between the
+         current and base Frames of the Plot is not defined (i.e. the
+         Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero).
+      }
+   }
+}
+\sstroutine{
+   astPolyMap
+}{
+   Create a PolyMap
+}{
+   \sstdescription{
+      This function creates a new \htmlref{PolyMap}{PolyMap} and optionally initialises
+      its attributes.
+
+      A PolyMap is a form of \htmlref{Mapping}{Mapping} which performs a general polynomial
+      transformation.  Each output coordinate is a polynomial function of
+      all the input coordinates. The coefficients are specified separately
+      for each output coordinate. The forward and inverse transformations
+      are defined independantly by separate sets of coefficients. If no
+      inverse transformation is supplied, the default behaviour is to use
+      an iterative method to evaluate the inverse based only on the forward
+      transformation (see attribute \htmlref{IterInverse}{IterInverse}).
+   }
+   \sstsynopsis{
+      AstPolyMap $*$astPolyMap( int nin, int nout, int ncoeff\_f, const double coeff\_f[],
+                              int ncoeff\_i, const double coeff\_i[],
+                              const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         nin
+      }{
+         The number of input coordinates.
+      }
+      \sstsubsection{
+         nout
+      }{
+         The number of output coordinates.
+      }
+      \sstsubsection{
+         ncoeff\_f
+      }{
+         The number of non-zero coefficients necessary to define the
+         forward transformation of the PolyMap. If zero is supplied, the
+         forward transformation will be undefined.
+      }
+      \sstsubsection{
+         coeff\_f
+      }{
+         An array containing
+         \texttt{"} ncoeff\_f$*$( 2 $+$ nin )\texttt{"}  elements. Each group of \texttt{"} 2 $+$ nin\texttt{"}
+         adjacent elements describe a single coefficient of the forward
+         transformation. Within each such group, the first element is the
+         coefficient value; the next element is the integer index of the
+         PolyMap output which uses the coefficient within its defining
+         polynomial (the first output has index 1); the remaining elements
+         of the group give the integer powers to use with each input
+         coordinate value (powers must not be negative, and floating
+         point values are rounded to the nearest integer).
+         If \texttt{"} ncoeff\_f\texttt{"}  is zero, a NULL pointer may be supplied for \texttt{"} coeff\_f\texttt{"} .
+
+         For instance, if the PolyMap has 3 inputs and 2 outputs, each group
+         consisting of 5 elements, A groups such as \texttt{"} (1.2, 2.0, 1.0, 3.0, 0.0)\texttt{"}
+         describes a coefficient with value 1.2 which is used within the
+         definition of output 2. The output value is incremented by the
+         product of the coefficient value, the value of input coordinate
+         1 raised to the power 1, and the value of input coordinate 2 raised
+         to the power 3. Input coordinate 3 is not used since its power is
+         specified as zero. As another example, the group \texttt{"} (-1.0, 1.0,
+         0.0, 0.0, 0.0 )\texttt{"}  describes adds a constant value -1.0 onto
+         output 1 (it is a constant value since the power for every input
+         axis is given as zero).
+
+         Each final output coordinate value is the sum of the \texttt{"} ncoeff\_f\texttt{"}  terms
+         described by the \texttt{"} ncoeff\_f\texttt{"}  groups within the supplied array.
+      }
+      \sstsubsection{
+         ncoeff\_i
+      }{
+         The number of non-zero coefficients necessary to define the
+         inverse transformation of the PolyMap. If zero is supplied, the
+         default behaviour is to use an iterative method to evaluate the
+         inverse based only on the forward transformation (see attribute
+         IterInverse).
+      }
+      \sstsubsection{
+         coeff\_i
+      }{
+         An array containing
+         \texttt{"} ncoeff\_i$*$( 2 $+$ nout )\texttt{"}  elements. Each group of \texttt{"} 2 $+$ nout\texttt{"}
+         adjacent elements describe a single coefficient of the inverse
+         transformation, using the same schame as \texttt{"} coeff\_f\texttt{"} ,
+         except that \texttt{"} inputs\texttt{"}  and \texttt{"} outputs\texttt{"}  are transposed.
+         If \texttt{"} ncoeff\_i\texttt{"}  is zero, a NULL pointer may be supplied for \texttt{"} coeff\_i\texttt{"} .
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new PolyMap. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astPolyMap()
+      }{
+         A pointer to the new PolyMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astPolyTran
+}{
+   Fit a PolyMap inverse or forward transformation
+}{
+   \sstdescription{
+      This function creates a new \htmlref{PolyMap}{PolyMap} which is a copy of the supplied
+      PolyMap, in which a specified transformation (forward or inverse)
+      has been replaced by a new polynomial transformation. The
+      coefficients of the new transformation are estimated by sampling
+      the other transformation and performing a least squares polynomial
+      fit in the opposite direction to the sampled positions and values.
+
+      This method can only be used on (1-input,1-output) or (2-input,2-output)
+      PolyMaps.
+
+      The transformation to create is specified by the
+      \texttt{"} forward\texttt{"}  parameter.
+      In what follows \texttt{"} X\texttt{"}  refers to the inputs of the PolyMap, and \texttt{"} Y\texttt{"}  to
+      the outputs of the PolyMap. The forward transformation transforms
+      input values (X) into output values (Y), and the inverse transformation
+      transforms output values (Y) into input values (X). Within a PolyMap,
+      each transformation is represented by an independent set of
+      polynomials, P\_f or P\_i: Y=P\_f(X) for the forward transformation and
+      X=P\_i(Y) for the inverse transformation.
+
+      The \texttt{"} forward\texttt{"}
+      parameter specifies the transformation to be replaced. If it is
+      non-zero,
+      a new forward transformation is created
+      by first finding the input values (X) using the inverse transformation
+      (which must be available) at a regular grid of points (Y) covering a
+      rectangular region of the PolyMap\texttt{'} s output space. The coefficients of
+      the required forward polynomial, Y=P\_f(X), are chosen in order to
+      minimise the sum of the squared residuals between the sampled values
+      of Y and P\_f(X).
+
+      If \texttt{"} forward\texttt{"}  is zero (probably the most likely case),
+      a new inverse transformation is created by
+      first finding the output values (Y) using the forward transformation
+      (which must be available) at a regular grid of points (X) covering a
+      rectangular region of the PolyMap\texttt{'} s input space. The coefficients of
+      the required inverse polynomial, X=P\_i(Y), are chosen in order to
+      minimise the sum of the squared residuals between the sampled values
+      of X and P\_i(Y).
+
+      This fitting process is performed repeatedly with increasing
+      polynomial orders (starting with linear) until the target
+      accuracy is achieved, or a specified maximum order is reached. If
+      the target accuracy cannot be achieved even with this maximum-order
+      polynomial, the best fitting maximum-order polynomial is returned so
+      long as its accuracy is better than
+      \texttt{"} maxacc\texttt{"} .
+      If it is not, a NULL pointer is returned but no error is reported.
+   }
+   \sstsynopsis{
+      AstPolyMap $*$astPolyTran( AstPolyMap $*$this, int forward, double acc,
+                               double maxacc, int maxorder, const double $*$lbnd,
+                               const double $*$ubnd )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the original \htmlref{Mapping}{Mapping}.
+      }
+      \sstsubsection{
+         forward
+      }{
+         If non-zero,
+         the forward PolyMap transformation is replaced. Otherwise the
+         inverse transformation is replaced.
+      }
+      \sstsubsection{
+         acc
+      }{
+         The target accuracy, expressed as a geodesic distance within
+         the PolyMap\texttt{'} s input space (if
+         \texttt{"} forward\texttt{"}  is zero)  or output space (if \texttt{"} forward\texttt{"}  is non-zero).
+      }
+      \sstsubsection{
+         maxacc
+      }{
+         The maximum allowed accuracy for an acceptable polynomial,
+         expressed as a geodesic distance within the PolyMap\texttt{'} s input
+         space (if
+         \texttt{"} forward\texttt{"}  is zero)  or output space (if \texttt{"} forward\texttt{"}  is non-zero).
+      }
+      \sstsubsection{
+         maxorder
+      }{
+         The maximum allowed polynomial order. This is one more than the
+         maximum power of either input axis. So for instance, a value of
+         3 refers to a quadratic polynomial. Note, cross terms with total
+         powers greater than or equal to
+         maxorder
+         are not inlcuded in the fit. So the maximum number of terms in
+         each of the fitted polynomials is
+         maxorder$*$(maxorder$+$1)/2.
+      }
+      \sstsubsection{
+         lbnd
+      }{
+         Pointer to an
+         array holding the lower bounds of a rectangular region within
+         the PolyMap\texttt{'} s input space (if
+         \texttt{"} forward\texttt{"}  is zero)  or output space (if \texttt{"} forward\texttt{"}  is non-zero).
+         The new polynomial will be evaluated over this rectangle. The
+         length of this array should equal the value of the PolyMap\texttt{'} s \htmlref{Nin}{Nin}
+         or \htmlref{Nout}{Nout} attribute, depending on
+         \texttt{"} forward\texttt{"} .
+      }
+      \sstsubsection{
+         ubnd
+      }{
+         Pointer to an
+         array holding the upper bounds of a rectangular region within
+         the PolyMap\texttt{'} s input space (if
+         \texttt{"} forward\texttt{"}  is zero)  or output space (if \texttt{"} forward\texttt{"}  is non-zero).
+         The new polynomial will be evaluated over this rectangle.  The
+         length of this array should equal the value of the PolyMap\texttt{'} s Nin
+         or Nout attribute, depending on
+         \texttt{"} forward\texttt{"} .
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         PolyMap
+      }{
+         All PolyMaps have this method.
+      }
+      \sstsubsection{
+         \htmlref{ChebyMap}{ChebyMap}
+      }{
+         The ChebyMap implementation of this method allows
+         NULL pointers to be supplied for \texttt{"} lbnd\texttt{"}  and/or \texttt{"} ubnd\texttt{"} ,
+         in which case the corresponding bounds supplied when the ChebyMap
+         was created are used.
+         The returned PolyMap will be a ChebyMap, and the new transformation
+         will be defined as a weighted sum of Chebyshev functions of the
+         first kind.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astPolyTran()
+      }{
+         A pointer to the new PolyMap.
+         A NULL pointer
+         will be returned if the fit fails to achieve the accuracy
+         specified by
+         \texttt{"} maxacc\texttt{"} ,
+         but no error will be reported.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This function can only be used on 1D or 2D PolyMaps which have
+         the same number of inputs and outputs.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astPolygon
+}{
+   Create a Polygon
+}{
+   \sstdescription{
+      This function creates a new \htmlref{Polygon}{Polygon} object and optionally initialises
+      its attributes.
+
+      The Polygon class implements a polygonal area, defined by a
+      collection of vertices, within a 2-dimensional \htmlref{Frame}{Frame}. The vertices
+      are connected together by geodesic curves within the encapsulated Frame.
+      For instance, if the encapsulated Frame is a simple Frame then the
+      geodesics will be straight lines, but if the Frame is a \htmlref{SkyFrame}{SkyFrame} then
+      the geodesics will be great circles. Note, the vertices must be
+      supplied in an order such that the inside of the polygon is to the
+      left of the boundary as the vertices are traversed. Supplying them
+      in the reverse order will effectively negate the polygon.
+
+      Within a SkyFrame, neighbouring vertices are always joined using the
+      shortest path. Thus if an edge of 180 degrees or more in length is
+      required, it should be split into section each of which is less
+      than 180 degrees. The closed path joining all the vertices in order
+      will divide the celestial sphere into two disjoint regions. The
+      inside of the polygon is the region which is circled in an
+      anti-clockwise manner (when viewed from the inside of the celestial
+      sphere) when moving through the list of vertices in the order in
+      which they were supplied when the Polygon was created (i.e. the
+      inside is to the left of the boundary when moving through the
+      vertices in the order supplied).
+   }
+   \sstsynopsis{
+      AstPolygon $*$astPolygon( AstFrame $*$frame, int npnt, int dim,
+                              const double $*$points, AstRegion $*$unc,
+                              const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         frame
+      }{
+         A pointer to the Frame in which the region is defined. It must
+         have exactly 2 axes. A deep copy is taken of the supplied Frame.
+         This means that any subsequent changes made to the Frame using the
+         supplied pointer will have no effect the \htmlref{Region}{Region}.
+      }
+      \sstsubsection{
+         npnt
+      }{
+         The number of points in the Region.
+      }
+      \sstsubsection{
+         dim
+      }{
+         The number of elements along the second dimension of the \texttt{"} points\texttt{"}
+         array (which contains the point coordinates). This value is
+         required so that the coordinate values can be correctly
+         located if they do not entirely fill this array. The value
+         given should not be less than \texttt{"} npnt\texttt{"} .
+      }
+      \sstsubsection{
+         points
+      }{
+         The address of the first element of a 2-dimensional array of
+         shape \texttt{"} [2][dim]\texttt{"}  giving the physical coordinates of the vertices.
+         These should be stored such that the value of coordinate
+         number \texttt{"} coord\texttt{"}  for point number \texttt{"} pnt\texttt{"}  is found in element
+         \texttt{"} in[coord][pnt]\texttt{"} .
+      }
+      \sstsubsection{
+         unc
+      }{
+         An optional pointer to an existing Region which specifies the
+         uncertainties associated with the boundary of the Polygon being created.
+         The uncertainty in any point on the boundary of the Polygon is found by
+         shifting the supplied \texttt{"} uncertainty\texttt{"}  Region so that it is centred at
+         the boundary point being considered. The area covered by the
+         shifted uncertainty Region then represents the uncertainty in the
+         boundary position. The uncertainty is assumed to be the same for
+         all points.
+
+         If supplied, the uncertainty Region must be of a class for which
+         all instances are centro-symetric (e.g. \htmlref{Box}{Box}, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse}, etc.)
+         or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions. A deep
+         copy of the supplied Region will be taken, so subsequent changes to
+         the uncertainty Region using the supplied pointer will have no
+         effect on the created Polygon. Alternatively,
+         a NULL \htmlref{Object}{Object} pointer
+         may be supplied, in which case a default uncertainty is used
+         equivalent to a box 1.0E-6 of the size of the Polygon being created.
+
+         The uncertainty Region has two uses: 1) when the
+         \htmlref{astOverlap}{astOverlap}
+         function compares two Regions for equality the uncertainty
+         Region is used to determine the tolerance on the comparison, and 2)
+         when a Region is mapped into a different coordinate system and
+         subsequently simplified (using
+         \htmlref{astSimplify}{astSimplify}),
+         the uncertainties are used to determine if the transformed boundary
+         can be accurately represented by a specific shape of Region.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new Polygon. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astPolygon()
+      }{
+         A pointer to the new Polygon.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null Object pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      Status Handling
+   }{
+      The protected interface to this function includes an extra
+      parameter at the end of the parameter list descirbed above. This
+      parameter is a pointer to the integer inherited status
+      variable: \texttt{"} int $*$status\texttt{"} .
+   }
+}
+\sstroutine{
+   astPrism
+}{
+   Create a Prism
+}{
+   \sstdescription{
+      This function creates a new \htmlref{Prism}{Prism} and optionally initialises
+      its attributes.
+
+      A Prism is a \htmlref{Region}{Region} which represents an extrusion of an existing Region
+      into one or more orthogonal dimensions (specified by another Region).
+      If the Region to be extruded has N axes, and the Region defining the
+      extrusion has M axes, then the resulting Prism will have (M$+$N) axes.
+      A point is inside the Prism if the first N axis values correspond to
+      a point inside the Region being extruded, and the remaining M axis
+      values correspond to a point inside the Region defining the extrusion.
+
+      As an example, a cylinder can be represented by extruding an existing
+      \htmlref{Circle}{Circle}, using an \htmlref{Interval}{Interval} to define the extrusion. Ih this case, the
+      Interval would have a single axis and would specify the upper and
+      lower limits of the cylinder along its length.
+   }
+   \sstsynopsis{
+      AstPrism $*$astPrism( AstRegion $*$region1, AstRegion $*$region2,
+                          const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         region1
+      }{
+         Pointer to the Region to be extruded.
+      }
+      \sstsubsection{
+         region2
+      }{
+         Pointer to the Region defining the extent of the extrusion.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new Prism. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astPrism()
+      }{
+         A pointer to the new Prism.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Deep copies are taken of the supplied Regions. This means that
+         any subsequent changes made to the component Regions using the
+         supplied pointers will have no effect on the Prism.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astPurgeRows
+}{
+   Remove all empty rows from a table
+}{
+   \sstdescription{
+      This function removes all empty rows from the \htmlref{Table}{Table}, renaming
+      the key associated with each table cell accordingly.
+   }
+   \sstsynopsis{
+      void astPurgeRows( AstTable $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Table.
+      }
+   }
+}
+\sstroutine{
+   astPurgeWCS
+}{
+   Delete all cards in the FitsChan describing WCS information
+}{
+   \sstdescription{
+      This function
+      deletes all cards in a \htmlref{FitsChan}{FitsChan} that relate to any of the recognised
+      WCS encodings. On exit, the current card is the first remaining card
+      in the FitsChan.
+   }
+   \sstsynopsis{
+      void astPurgeWCS( AstFitsChan $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FitsChan.
+      }
+   }
+}
+\sstroutine{
+   astPutCards
+}{
+   Store a set of FITS header cards in a FitsChan
+}{
+   \sstdescription{
+      This function
+      stores a set of FITS header cards in a \htmlref{FitsChan}{FitsChan}. The cards are
+      supplied concatenated together into a single character string.
+      Any existing cards in the FitsChan are removed before the new cards
+      are added. The FitsChan is \texttt{"} re-wound\texttt{"}  on exit by clearing its \htmlref{Card}{Card}
+      attribute. This means that a subsequent invocation of
+      \htmlref{astRead}{astRead}
+      can be made immediately without the need to re-wind the FitsChan
+      first.
+   }
+   \sstsynopsis{
+      void astPutCards( AstFitsChan $*$this, const char $*$cards )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FitsChan.
+      }
+      \sstsubsection{
+         cards
+      }{
+         Pointer to a null-terminated character string
+         containing the FITS cards to be stored. Each individual card
+         should occupy 80 characters in this string, and there should be
+         no delimiters, new lines, etc, between adjacent cards. The final
+         card may be less than 80 characters long.
+         This is the format produced by the fits\_hdr2str function in the
+         CFITSIO library.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          An error will result if the supplied string contains any cards
+         which cannot be interpreted.
+      }
+   }
+}
+\sstroutine{
+   astPutChannelData
+}{
+   Store arbitrary data to be passed to a source or sink function
+}{
+   \sstdescription{
+      This function stores a supplied arbitrary pointer in the \htmlref{Channel}{Channel}.
+      When a source or sink function is invoked by the Channel, the
+      invoked function can use the \htmlref{astChannelData}{astChannelData} macro to retrieve the
+      pointer. This provides a thread-safe alternative to passing file
+      descriptors, etc, via global static variables.
+   }
+   \sstsynopsis{
+      void astPutChannelData( AstChannel $*$this, void $*$data )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Channel.
+      }
+      \sstsubsection{
+         data
+      }{
+         A pointer to be made available to the source and sink functions
+         via the astChannelData macro. May be NULL.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Channel
+      }{
+         All Channels have this function.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This routine is not available in the Fortran 77 interface to
+         the AST library.
+      }
+   }
+}
+\sstroutine{
+   astPutColumnData
+}{
+   Store new data values for all rows of a column
+}{
+   \sstdescription{
+      This function
+      copies data values from a supplied buffer into a named column. The
+      first element in the buffer becomes the first element in the first
+      row of the column. If the buffer does not completely fill the
+      column, then any trailing rows are filled with null values.
+   }
+   \sstsynopsis{
+      void astPutColumnData( AstFitsTable $*$this, const char $*$column,
+                             int clen, size\_t size, void $*$coldata )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the \htmlref{FitsTable}{FitsTable}.
+      }
+      \sstsubsection{
+         column
+      }{
+         The character string holding the name of the column. Trailing
+         spaces are ignored.
+      }
+      \sstsubsection{
+         clen
+      }{
+         If the column holds character strings, then this must be set to
+         the length of each fixed length string in the supplied array.
+         This is often determined by the appropriate TFORMn keyword in
+         the binary table header. The supplied value is ignored if the
+         column does not hold character data.
+      }
+      \sstsubsection{
+         size
+      }{
+         The size of the
+         \texttt{"} coldata\texttt{"}
+         array, in bytes. This should be an integer multiple of the
+         number of bytes needed to hold the full vector value stored in a
+         single cell of the column. An error is reported if this is not
+         the case.
+      }
+      \sstsubsection{
+         coldata
+      }{
+         A pointer to an
+         area of memory holding the data to copy into the column. The values
+         should be stored in row order. If the column holds non-scalar values,
+         the elements of each value should be stored in \texttt{"} Fortran\texttt{"}  order. No
+         data type conversion is performed.
+      }
+   }
+}
+\sstroutine{
+   astPutFits
+}{
+   Store a FITS header card in a FitsChan
+}{
+   \sstdescription{
+      This function stores a FITS header card in a \htmlref{FitsChan}{FitsChan}. The card
+      is either inserted before the current card (identified by the
+      \htmlref{Card}{Card} attribute), or over-writes the current card, as required.
+   }
+   \sstsynopsis{
+      void astPutFits( AstFitsChan $*$this, const char card[ 80 ],
+                       int overwrite )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FitsChan.
+      }
+      \sstsubsection{
+         card
+      }{
+         Pointer to a possibly null-terminated character string
+         containing the FITS card to be stored. No more than 80
+         characters will be used from this string (or fewer if a null
+         occurs earlier).
+      }
+      \sstsubsection{
+         overwrite
+      }{
+         If this value is zero, the new card is inserted in front of
+         the current card in the FitsChan (as identified by the
+         initial value of the Card attribute). If it is non-zero, the
+         new card replaces the current card. In either case, the Card
+         attribute is then incremented by one so that it subsequently
+         identifies the card following the one stored.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If the Card attribute initially points at the \texttt{"} end-of-file\texttt{"}
+         (i.e. exceeds the number of cards in the FitsChan), then the new
+         card is appended as the last card in the FitsChan.
+
+         \sstitem
+          An error will result if the supplied string cannot be interpreted
+         as a FITS header card.
+      }
+   }
+}
+\sstroutine{
+   astPutTable
+}{
+   Store a single FitsTable in a FitsChan
+}{
+   \sstdescription{
+      This function
+      allows a representation of a single FITS binary table to be
+      stored in a \htmlref{FitsChan}{FitsChan}. For instance, this may provide the coordinate
+      look-up tables needed subequently when reading FITS-WCS headers
+      for axes described using the \texttt{"} -TAB\texttt{"}  algorithm. Since, in general,
+      the calling application may not know which tables will be needed -
+      if any - prior to calling
+      \htmlref{astRead}{astRead}, the astTablesSource function
+      provides an alternative mechanism in which a caller-supplied
+      function is invoked to store a named table in the FitsChan.
+   }
+   \sstsynopsis{
+      void astPutTable( AstFitsChan $*$this, AstFitsTable $*$table,
+                        const char $*$extnam )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FitsChan.
+      }
+      \sstsubsection{
+         table
+      }{
+         Pointer to a \htmlref{FitsTable}{FitsTable} to be added to the FitsChan. If a FitsTable
+         with the associated extension name already exists in the FitsChan,
+         it is replaced with the new one. A deep copy of the FitsTable is
+         stored in the FitsChan, so any subsequent changes made to the
+         FitsTable will have no effect on the behaviour of the FitsChan.
+      }
+      \sstsubsection{
+         extnam
+      }{
+         The name of the FITS extension associated with the table.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Tables stored in the FitsChan may be retrieved using
+         \htmlref{astGetTables}{astGetTables}.
+
+         \sstitem
+          The \htmlref{astPutTables}{astPutTables} method can add multiple FitsTables in a single call.
+      }
+   }
+}
+\sstroutine{
+   astPutTableHeader
+}{
+   Store new FITS headers in a FitsTable
+}{
+   \sstdescription{
+      This function
+      stores new FITS headers in the supplied \htmlref{FitsTable}{FitsTable}. Any existing
+      headers are first deleted.
+   }
+   \sstsynopsis{
+      void astPutTableHeader( AstFitsTable $*$this, AstFitsChan $*$header )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FitsTable.
+      }
+      \sstsubsection{
+         header
+      }{
+         Pointer to a \htmlref{FitsChan}{FitsChan} holding the headers for the FitsTable.
+         A deep copy of the supplied FitsChan is stored in the FitsTable,
+         replacing the current FitsChan in the Fitstable. Keywords that
+         are fixed either by the properties of the \htmlref{Table}{Table}, or by the FITS
+         standard, are removed from the copy (see \texttt{"} Notes:\texttt{"}  below).
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The attributes of the supplied FitsChan, together with any source
+         and sink functions associated with the FitsChan, are copied to the
+         FitsTable.
+
+         \sstitem
+          Values for the following keywords are generated automatically by
+         the FitsTable (any values for these keywords in the supplied
+         FitsChan will be ignored): \texttt{"} XTENSION\texttt{"} , \texttt{"} BITPIX\texttt{"} , \texttt{"} NAXIS\texttt{"} , \texttt{"} NAXIS1\texttt{"} ,
+         \texttt{"} NAXIS2\texttt{"} , \texttt{"} PCOUNT\texttt{"} , \texttt{"} GCOUNT\texttt{"} , \texttt{"} TFIELDS\texttt{"} , \texttt{"} TFORM\%d\texttt{"} , \texttt{"} TTYPE\%d\texttt{"} ,
+         \texttt{"} TNULL\%d\texttt{"} , \texttt{"} THEAP\texttt{"} , \texttt{"} TDIM\%d\texttt{"} .
+      }
+   }
+}
+\sstroutine{
+   astPutTables
+}{
+   Store one or more FitsTables in a FitsChan
+}{
+   \sstdescription{
+      This function
+      allows representations of one or more FITS binary tables to be
+      stored in a \htmlref{FitsChan}{FitsChan}. For instance, these may provide the coordinate
+      look-up tables needed subequently when reading FITS-WCS headers
+      for axes described using the \texttt{"} -TAB\texttt{"}  algorithm. Since, in general,
+      the calling application may not know which tables will be needed -
+      if any - prior to calling
+      \htmlref{astRead}{astRead}, the astTablesSource function
+      provides an alternative mechanism in which a caller-supplied
+      function is invoked to store a named table in the FitsChan.
+   }
+   \sstsynopsis{
+      void astPutTables( AstFitsChan $*$this, AstKeyMap $*$tables )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FitsChan.
+      }
+      \sstsubsection{
+         tables
+      }{
+         Pointer to a \htmlref{KeyMap}{KeyMap} holding the tables that are to be added
+         to the FitsChan. Each entry should hold a scalar value which is a
+         pointer to a \htmlref{FitsTable}{FitsTable} to be added to the FitsChan. Any unusable
+         entries are ignored. The key associated with each entry should be
+         the name of the FITS binary extension from which the table was
+         read. If a FitsTable with the associated key already exists in the
+         FitsChan, it is replaced with the new one. A deep copy of each
+         usable FitsTable is stored in the FitsChan, so any subsequent
+         changes made to the FitsTables will have no effect on the
+         behaviour of the FitsChan.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Tables stored in the FitsChan may be retrieved using
+         \htmlref{astGetTables}{astGetTables}.
+
+         \sstitem
+          The tables in the supplied KeyMap are added to any tables already
+         in the FitsChan.
+
+         \sstitem
+          The \htmlref{astPutTable}{astPutTable}
+         method provides a simpler means of adding a single table to a FitsChan.
+      }
+   }
+}
+\sstroutine{
+   astQuadApprox
+}{
+   Obtain a quadratic approximation to a 2D Mapping
+}{
+   \sstdescription{
+      This function returns the co-efficients of a quadratic fit to the
+      supplied \htmlref{Mapping}{Mapping} over the input area specified by
+      \texttt{"} lbnd\texttt{"}  and \texttt{"} ubnd\texttt{"} .
+      The Mapping must have 2 inputs, but may have any number of outputs.
+      The i\texttt{'} th Mapping output is modelled as a quadratic function of the
+      2 inputs (x,y):
+
+      output\_i = a\_i\_0 $+$ a\_i\_1$*$x $+$ a\_i\_2$*$y $+$ a\_i\_3$*$x$*$y $+$ a\_i\_4$*$x$*$x $+$
+                 a\_i\_5$*$y$*$y
+
+      The \texttt{"} fit\texttt{"}
+      array is returned holding the values of the co-efficients a\_0\_0,
+      a\_0\_1, etc.
+   }
+   \sstsynopsis{
+      int QuadApprox( AstMapping $*$this,  const double lbnd[2],
+                      const double ubnd[2], int nx, int ny, double $*$fit,
+                      double $*$rms )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Mapping.
+      }
+      \sstsubsection{
+         lbnd
+      }{
+         Pointer to an array of doubles
+         containing the lower bounds of a box defined within the input
+         coordinate system of the Mapping. The number of elements in this
+         array should equal the value of the Mapping\texttt{'} s \htmlref{Nin}{Nin} attribute. This
+         box should specify the region over which the fit is to be
+         performed.
+      }
+      \sstsubsection{
+         ubnd
+      }{
+         Pointer to an array of doubles
+         containing the upper bounds of the box specifying the region over
+         which the fit is to be performed.
+      }
+      \sstsubsection{
+         nx
+      }{
+         The number of points to place along the first Mapping input. The
+         first point is at
+         \texttt{"} lbnd[0]\texttt{"}  and the last is at \texttt{"} ubnd[0]\texttt{"} .
+         If a value less than three is supplied a value of three will be used.
+      }
+      \sstsubsection{
+         ny
+      }{
+         The number of points to place along the second Mapping input. The
+         first point is at
+         \texttt{"} lbnd[1]\texttt{"}  and the last is at \texttt{"} ubnd[1]\texttt{"} .
+         If a value less than three is supplied a value of three will be used.
+      }
+      \sstsubsection{
+         fit
+      }{
+         Pointer to an array of doubles
+         in which to return the co-efficients of the quadratic
+         approximation to the specified transformation. This array should
+         have at least \texttt{"} 6$*$\htmlref{Nout}{Nout}\texttt{"} , elements. The first 6 elements hold the
+         fit to the first Mapping output. The next 6 elements hold the
+         fit to the second Mapping output, etc. So if the Mapping has 2
+         inputs and 2 outputs the quadratic approximation to the forward
+         transformation is:
+
+            X\_out = fit[0] $+$ fit[1]$*$X\_in $+$ fit[2]$*$Y\_in $+$ fit[3]$*$X\_in$*$Y\_in $+$
+                    fit[4]$*$X\_in$*$X\_in $+$ fit[5]$*$Y\_in$*$Y\_in
+            Y\_out = fit[6] $+$ fit[7]$*$X\_in $+$ fit[8]$*$Y\_in $+$ fit[9]$*$X\_in$*$Y\_in $+$
+                    fit[10]$*$X\_in$*$X\_in $+$ fit[11]$*$Y\_in$*$Y\_in
+      }
+      \sstsubsection{
+         rms
+      }{
+         Pointer to a double in which to return the
+         RMS residual between the fit and the Mapping, summed over all
+         Mapping outputs.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astQuadApprox()
+      }{
+         If a quadratic approximation was created,
+         a non-zero value is returned. Otherwise zero is returned
+         and the fit co-efficients are set to AST\_\_BAD.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This function fits the Mapping\texttt{'} s forward transformation. To fit
+         the inverse transformation, the Mapping should be inverted using
+         \htmlref{astInvert}{astInvert}
+         before invoking this function.
+
+         \sstitem
+          A value of zero
+         will be returned if this function is invoked
+         with the global error status set, or if it should fail for any
+         reason.
+      }
+   }
+}
+\sstroutine{
+   astRate
+}{
+   Calculate the rate of change of a Mapping output
+}{
+   \sstdescription{
+      This function
+      evaluates the rate of change of a specified output of the supplied
+      \htmlref{Mapping}{Mapping} with respect to a specified input, at a specified input
+      position.
+
+      The result is estimated by interpolating the function using a
+      fourth order polynomial in the neighbourhood of the specified
+      position. The size of the neighbourhood used is chosen to minimise
+      the RMS residual per unit length between the interpolating
+      polynomial and the supplied Mapping function. This method produces
+      good accuracy but can involve evaluating the Mapping 100 or more
+      times.
+   }
+   \sstsynopsis{
+      double astRate( AstMapping $*$this, double $*$at, int ax1, int ax2 )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Mapping to be applied.
+      }
+      \sstsubsection{
+         at
+      }{
+         The address of an
+         array holding the axis values at the position at which the rate
+         of change is to be evaluated. The number of elements in this
+         array should equal the number of inputs to the Mapping.
+      }
+      \sstsubsection{
+         ax1
+      }{
+         The index of the Mapping output for which the rate of change is to
+         be found (output numbering starts at 1 for the first output).
+      }
+      \sstsubsection{
+         ax2
+      }{
+         The index of the Mapping input which is to be varied in order to
+         find the rate of change (input numbering starts at 1 for the first
+         input).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astRate()
+      }{
+         The rate of change of Mapping output \texttt{"} ax1\texttt{"}  with respect to input
+         \texttt{"} ax2\texttt{"} , evaluated at \texttt{"} at\texttt{"} , or AST\_\_BAD if the value cannot be
+         calculated.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A value of AST\_\_BAD will be returned if this function is invoked
+         with the global error status set, or if it should fail for any
+         reason.
+      }
+   }
+}
+\sstroutine{
+   astRateMap
+}{
+   Create a RateMap
+}{
+   \sstdescription{
+      This function creates a new \htmlref{RateMap}{RateMap} and optionally initialises
+      its attributes.
+
+      A RateMap is a \htmlref{Mapping}{Mapping} which represents a single element of the
+      Jacobian matrix of another Mapping. The Mapping for which the
+      Jacobian is required is specified when the new RateMap is created,
+      and is referred to as the \texttt{"} encapsulated Mapping\texttt{"}  below.
+
+      The number of inputs to a RateMap is the same as the number of inputs
+      to its encapsulated Mapping. The number of outputs from a RateMap
+      is always one. This one output equals the rate of change of a
+      specified output of the encapsulated Mapping with respect to a
+      specified input of the encapsulated Mapping (the input and output
+      to use are specified when the RateMap is created).
+
+      A RateMap which has not been inverted does not define an inverse
+      transformation. If a RateMap has been inverted then it will define
+      an inverse transformation but not a forward transformation.
+   }
+   \sstsynopsis{
+      AstRateMap $*$astRateMap( AstMapping $*$map, int ax1, int ax2,
+                              const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         map
+      }{
+         Pointer to the encapsulated Mapping.
+      }
+      \sstsubsection{
+         ax1
+      }{
+         Index of the output from the encapsulated Mapping for which the
+         rate of change is required. This corresponds to the delta
+         quantity forming the numerator of the required element of the
+         Jacobian matrix. The first axis has index 1.
+      }
+      \sstsubsection{
+         ax2
+      }{
+         Index of the input to the encapsulated Mapping which is to be
+         varied. This corresponds to the delta quantity forming the
+         denominator of the required element of the Jacobian matrix.
+         The first axis has index 1.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new RateMap. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astRateMap()
+      }{
+         A pointer to the new RateMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The forward transformation of the encapsulated Mapping must be
+         defined.
+
+         \sstitem
+          Note that the component Mappings supplied are not copied by
+         astRateMap (the new RateMap simply retains a reference to
+         them). They may continue to be used for other purposes, but
+         should not be deleted. If a RateMap containing a copy of its
+         component Mappings is required, then a copy of the RateMap should
+         be made using \htmlref{astCopy}{astCopy}.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astRead
+}{
+   Read an Object from a Channel
+}{
+   \sstdescription{
+      This function reads the next \htmlref{Object}{Object} from a \htmlref{Channel}{Channel} and returns a
+      pointer to the new Object.
+   }
+   \sstsynopsis{
+      AstObject $*$astRead( AstChannel $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Channel.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{FitsChan}{FitsChan}
+      }{
+         All successful use of astRead on a FitsChan is destructive, so that
+         FITS header cards are consumed in the process of reading an Object,
+         and are removed from the FitsChan (this deletion can be prevented
+         for specific cards by calling the FitsChan
+         \htmlref{astRetainFits}{astRetainFits} function).
+         An unsuccessful call of
+         astRead
+         (for instance, caused by the FitsChan not containing the necessary
+         FITS headers cards needed to create an Object) results in the
+         contents of the FitsChan being left unchanged.
+      }
+      \sstsubsection{
+         \htmlref{StcsChan}{StcsChan}
+      }{
+         The AST Object returned by a successful use of
+         astRead
+         on an StcsChan, will be either a \htmlref{Region}{Region} or a \htmlref{KeyMap}{KeyMap}, depending
+         on the values of the \htmlref{StcsArea}{StcsArea}, \htmlref{StcsCoords}{StcsCoords} and \htmlref{StcsProps}{StcsProps}
+         attributes. See the documentation for these attributes for further
+         information.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astRead()
+      }{
+         A pointer to the new Object. The class to which this will
+         belong is determined by the input data, so is not known in
+         advance.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null Object pointer (AST\_\_NULL) will be returned, without
+         error, if the Channel contains no further Objects to be read.
+
+         \sstitem
+          A null Object pointer will also be returned if this function
+         is invoked with the AST error status set, or if it should fail
+         for any reason.
+      }
+   }
+}
+\sstroutine{
+   astReadFits
+}{
+   Read cards into a FitsChan from the source function
+}{
+   \sstdescription{
+      This function
+      reads cards from the source function that was specified when the
+      \htmlref{FitsChan}{FitsChan} was created, and stores them in the FitsChan. This
+      normally happens once-only, when the FitsChan is accessed for the
+      first time.
+      This function
+      provides a means of forcing a re-read of the external source, and
+      may be useful if (say) new cards have been deposited into the
+      external source. Any newcards read from the source are appended to
+      the end of the current contents of the FitsChan.
+   }
+   \sstsynopsis{
+      void astReadFits( AstFitsChan $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FitsChan.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This function returns without action if no source function was
+         specified when the FitsChan was created.
+
+         \sstitem
+          The \htmlref{SourceFile}{SourceFile} attribute is ignored by this
+         function.
+         New cards are read from the source file whenever a new value is
+         assigned to the SourceFile attribute.
+      }
+   }
+}
+\sstroutine{
+   astRebin$<$X$>$
+}{
+   Rebin a region of a data grid
+}{
+   \sstdescription{
+      This is a set of functions for rebinning gridded data (e.g. an
+      image) under the control of a geometrical transformation, which
+      is specified by a \htmlref{Mapping}{Mapping}.  The functions operate on a pair of
+      data grids (input and output), each of which may have any number
+      of dimensions. Rebinning may be restricted to a specified
+      region of the input grid. An associated grid of error estimates
+      associated with the input data may also be supplied (in the form
+      of variance values), so as to produce error estimates for the
+      rebined output data. Propagation of missing data (bad pixels)
+      is supported.
+
+      Note, if you will be rebining a sequence of input arrays and then
+      co-adding them into a single array, the alternative
+      \htmlref{astRebinSeq$<$X$>$}{astRebinSeq$<$X$>$} functions
+      will in general be more efficient.
+
+      You should use a rebinning function which matches the numerical
+      type of the data you are processing by replacing $<$X$>$ in
+      the generic function name astRebin$<$X$>$ by an appropriate 1- or
+      2-character type code. For example, if you are rebinning data
+      with type \texttt{"} float\texttt{"} , you should use the function astRebinF (see
+      the \texttt{"} Data Type Codes\texttt{"}  section below for the codes appropriate to
+      other numerical types).
+
+      Rebinning of the grid of input data is performed by transforming
+      the coordinates of the centre of each input grid element (or pixel)
+      into the coordinate system of the output grid. The input pixel
+      value is then divided up and assigned to the output pixels in the
+      neighbourhood of the central output coordinates. A choice of
+      schemes are provided for determining how each input pixel value is
+      divided up between the output pixels. In general, each output pixel
+      may be assigned values from more than one input pixel. All
+      contributions to a given output pixel are summed to produce the
+      final output pixel value. Output pixels can be set to the supplied
+      bad value if they receive contributions from an insufficient number
+      of input pixels. This is controlled by the
+      \texttt{"} wlim\texttt{"}  parameter.
+
+      Input pixel coordinates are transformed into the coordinate
+      system of the output grid using the forward transformation of the
+      Mapping which is supplied. This means that geometrical features
+      in the input data are subjected to the Mapping\texttt{'} s forward
+      transformation as they are transferred from the input to the
+      output grid.
+
+      In practice, transforming the coordinates of every pixel of a
+      large data grid can be time-consuming, especially if the Mapping
+      involves complicated functions, such as sky projections. To
+      improve performance, it is therefore possible to approximate
+      non-linear Mappings by a set of linear transformations which are
+      applied piece-wise to separate sub-regions of the data. This
+      approximation process is applied automatically by an adaptive
+      algorithm, under control of an accuracy criterion which
+      expresses the maximum tolerable geometrical distortion which may
+      be introduced, as a fraction of a pixel.
+
+      This algorithm first attempts to approximate the Mapping with a
+      linear transformation applied over the whole region of the
+      input grid which is being used. If this proves to be
+      insufficiently accurate, the input region is sub-divided into
+      two along its largest dimension and the process is repeated
+      within each of the resulting sub-regions. This process of
+      sub-division continues until a sufficiently good linear
+      approximation is found, or the region to which it is being
+      applied becomes too small (in which case the original Mapping is
+      used directly).
+   }
+   \sstsynopsis{
+      void astRebin$<$X$>$( AstMapping $*$this, double wlim, int ndim\_in,
+                       const int lbnd\_in[], const int ubnd\_in[],
+                       const $<$Xtype$>$ in[], const $<$Xtype$>$ in\_var[],
+                       int spread, const double params[], int flags,
+                       double tol, int maxpix,
+                       $<$Xtype$>$ badval, int ndim\_out,
+                       const int lbnd\_out[], const int ubnd\_out[],
+                       const int lbnd[], const int ubnd[],
+                       $<$Xtype$>$ out[], $<$Xtype$>$ out\_var[] );
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to a Mapping, whose forward transformation will be
+         used to transform the coordinates of pixels in the input
+         grid into the coordinate system of the output grid.
+
+         The number of input coordinates used by this Mapping (as
+         given by its \htmlref{Nin}{Nin} attribute) should match the number of input
+         grid dimensions given by the value of \texttt{"} ndim\_in\texttt{"}
+         below. Similarly, the number of output coordinates (\htmlref{Nout}{Nout}
+         attribute) should match the number of output grid dimensions
+         given by \texttt{"} ndim\_out\texttt{"} .
+      }
+      \sstsubsection{
+         wlim
+      }{
+         Gives the required number of input pixel values which must contribute
+         to an output pixel in order for the output pixel value to be
+         considered valid. If the sum of the input pixel weights contributing
+         to an output pixel is less than the supplied
+         \texttt{"} wlim\texttt{"}
+         value, then the output pixel value is returned set to the
+         supplied bad value.
+      }
+      \sstsubsection{
+         ndim\_in
+      }{
+         The number of dimensions in the input grid. This should be at
+         least one.
+      }
+      \sstsubsection{
+         lbnd\_in
+      }{
+         Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"}  elements,
+         containing the coordinates of the centre of the first pixel
+         in the input grid along each dimension.
+      }
+      \sstsubsection{
+         ubnd\_in
+      }{
+         Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"}  elements,
+         containing the coordinates of the centre of the last pixel in
+         the input grid along each dimension.
+
+         Note that \texttt{"} lbnd\_in\texttt{"}  and \texttt{"} ubnd\_in\texttt{"}  together define the shape
+         and size of the input grid, its extent along a particular
+         (j\texttt{'} th) dimension being ubnd\_in[j]-lbnd\_in[j]$+$1 (assuming the
+         index \texttt{"} j\texttt{"}  to be zero-based). They also define
+         the input grid\texttt{'} s coordinate system, each pixel having unit
+         extent along each dimension with integral coordinate values
+         at its centre.
+      }
+      \sstsubsection{
+         in
+      }{
+         Pointer to an array, with one element for each pixel in the
+         input grid, containing the input data to be rebined.  The
+         numerical type of this array should match the 1- or
+         2-character type code appended to the function name (e.g. if
+         you are using astRebinF, the type of each array element
+         should be \texttt{"} float\texttt{"} ).
+
+         The storage order of data within this array should be such
+         that the index of the first grid dimension varies most
+         rapidly and that of the final dimension least rapidly
+         (i.e. Fortran array indexing is used).
+      }
+      \sstsubsection{
+         in\_var
+      }{
+         An optional pointer to a second array with the same size and
+         type as the \texttt{"} in\texttt{"}  array. If given, this should contain a set
+         of non-negative values which represent estimates of the
+         statistical variance associated with each element of the \texttt{"} in\texttt{"}
+         array. If this array is supplied (together with the
+         corresponding \texttt{"} out\_var\texttt{"}  array), then estimates of the
+         variance of the rebined output data will be calculated.
+
+         If no input variance estimates are being provided, a NULL
+         pointer should be given.
+      }
+      \sstsubsection{
+         spread
+      }{
+         This parameter specifies the scheme to be used for dividing
+         each input data value up amongst the corresponding output pixels.
+         It may be used to select
+         from a set of pre-defined schemes by supplying one of the
+         values described in the \texttt{"} Pixel Spreading Schemes\texttt{"}
+         section below.  If a value of zero is supplied, then the
+         default linear spreading scheme is used (equivalent to
+         supplying the value AST\_\_LINEAR).
+      }
+      \sstsubsection{
+         params
+      }{
+         An optional pointer to an array of double which should contain
+         any additional parameter values required by the pixel
+         spreading scheme. If such parameters are required, this
+         will be noted in the \texttt{"} Pixel Spreading Schemes\texttt{"}
+         section below.
+
+         If no additional parameters are required, this array is not
+         used and a NULL pointer may be given.
+      }
+      \sstsubsection{
+         flags
+      }{
+         The bitwise OR of a set of flag values which may be used to
+         provide additional control over the rebinning operation. See
+         the \texttt{"} Control Flags\texttt{"}  section below for a description of the
+         options available.  If no flag values are to be set, a value
+         of zero should be given.
+      }
+      \sstsubsection{
+         tol
+      }{
+         The maximum tolerable geometrical distortion which may be
+         introduced as a result of approximating non-linear Mappings
+         by a set of piece-wise linear transformations. This should be
+         expressed as a displacement in pixels in the output grid\texttt{'} s
+         coordinate system.
+
+         If piece-wise linear approximation is not required, a value
+         of zero may be given. This will ensure that the Mapping is
+         used without any approximation, but may increase execution
+         time.
+
+         If the value is too high, discontinuities between the linear
+         approximations used in adjacent panel will be higher, and may
+         cause the edges of the panel to be visible when viewing the output
+         image at high contrast. If this is a problem, reduce the
+         tolerance value used.
+      }
+      \sstsubsection{
+         maxpix
+      }{
+         A value which specifies an initial scale size (in pixels) for
+         the adaptive algorithm which approximates non-linear Mappings
+         with piece-wise linear transformations. Normally, this should
+         be a large value (larger than any dimension of the region of
+         the input grid being used). In this case, a first attempt to
+         approximate the Mapping by a linear transformation will be
+         made over the entire input region.
+
+         If a smaller value is used, the input region will first be
+         divided into sub-regions whose size does not exceed \texttt{"} maxpix\texttt{"}
+         pixels in any dimension. Only at this point will attempts at
+         approximation commence.
+
+         This value may occasionally be useful in preventing false
+         convergence of the adaptive algorithm in cases where the
+         Mapping appears approximately linear on large scales, but has
+         irregularities (e.g. holes) on smaller scales. A value of,
+         say, 50 to 100 pixels can also be employed as a safeguard in
+         general-purpose software, since the effect on performance is
+         minimal.
+
+         If too small a value is given, it will have the effect of
+         inhibiting linear approximation altogether (equivalent to
+         setting \texttt{"} tol\texttt{"}  to zero). Although this may degrade
+         performance, accurate results will still be obtained.
+      }
+      \sstsubsection{
+         badval
+      }{
+         This argument should have the same type as the elements of
+         the \texttt{"} in\texttt{"}  array. It specifies the value used to flag missing
+         data (bad pixels) in the input and output arrays.
+
+         If the AST\_\_USEBAD flag is set via the \texttt{"} flags\texttt{"}  parameter,
+         then this value is used to test for bad pixels in the \texttt{"} in\texttt{"}
+         (and \texttt{"} in\_var\texttt{"} ) array(s).
+
+         In all cases, this value is also used to flag any output
+         elements in the \texttt{"} out\texttt{"}  (and \texttt{"} out\_var\texttt{"} ) array(s) for which
+         rebined values could not be obtained (see the \texttt{"} Propagation
+         of Missing Data\texttt{"}  section below for details of the
+         circumstances under which this may occur).
+      }
+      \sstsubsection{
+         ndim\_out
+      }{
+         The number of dimensions in the output grid. This should be
+         at least one. It need not necessarily be equal to the number
+         of dimensions in the input grid.
+      }
+      \sstsubsection{
+         lbnd\_out
+      }{
+         Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"}  elements,
+         containing the coordinates of the centre of the first pixel
+         in the output grid along each dimension.
+      }
+      \sstsubsection{
+         ubnd\_out
+      }{
+         Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"}  elements,
+         containing the coordinates of the centre of the last pixel in
+         the output grid along each dimension.
+
+         Note that \texttt{"} lbnd\_out\texttt{"}  and \texttt{"} ubnd\_out\texttt{"}  together define the
+         shape, size and coordinate system of the output grid in the
+         same way as \texttt{"} lbnd\_in\texttt{"}  and \texttt{"} ubnd\_in\texttt{"}  define the shape, size
+         and coordinate system of the input grid.
+      }
+      \sstsubsection{
+         lbnd
+      }{
+         Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"}  elements,
+         containing the coordinates of the first pixel in the region
+         of the input grid which is to be included in the rebined output
+         array.
+      }
+      \sstsubsection{
+         ubnd
+      }{
+         Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"}  elements,
+         containing the coordinates of the last pixel in the region of
+         the input grid which is to be included in the rebined output
+         array.
+
+         Note that \texttt{"} lbnd\texttt{"}  and \texttt{"} ubnd\texttt{"}  together define the shape and
+         position of a (hyper-)rectangular region of the input grid
+         which is to be included in the rebined output array. This region
+         should lie wholly within the extent of the input grid (as
+         defined by the \texttt{"} lbnd\_in\texttt{"}  and \texttt{"} ubnd\_in\texttt{"}  arrays). Regions of
+         the input grid lying outside this region will not be used.
+      }
+      \sstsubsection{
+         out
+      }{
+         Pointer to an array, with one element for each pixel in the
+         output grid, in which the rebined data values will be
+         returned. The numerical type of this array should match that
+         of the \texttt{"} in\texttt{"}  array, and the data storage order should be such
+         that the index of the first grid dimension varies most
+         rapidly and that of the final dimension least rapidly
+         (i.e. Fortran array indexing is used).
+      }
+      \sstsubsection{
+         out\_var
+      }{
+         An optional pointer to an array with the same type and size
+         as the \texttt{"} out\texttt{"}  array. If given, this array will be used to
+         return variance estimates for the rebined data values. This
+         array will only be used if the \texttt{"} in\_var\texttt{"}  array has also been
+         supplied.
+
+         The output variance values will be calculated on the
+         assumption that errors on the input data values are
+         statistically independent and that their variance estimates
+         may simply be summed (with appropriate weighting factors)
+         when several input pixels contribute to an output data
+         value. If this assumption is not valid, then the output error
+         estimates may be biased. In addition, note that the
+         statistical errors on neighbouring output data values (as
+         well as the estimates of those errors) may often be
+         correlated, even if the above assumption about the input data
+         is correct, because of the pixel spreading schemes
+         employed.
+
+         If no output variance estimates are required, a NULL pointer
+         should be given.
+      }
+   }
+   \sstdiytopic{
+      Data Type Codes
+   }{
+      To select the appropriate rebinning function, you should
+      replace $<$X$>$ in the generic function name astRebin$<$X$>$ with a
+      1- or 2-character data type code, so as to match the numerical
+      type $<$Xtype$>$ of the data you are processing, as follows:
+      \sstitemlist{
+
+         \sstitem
+          D: double
+
+         \sstitem
+          F: float
+
+         \sstitem
+          I: int
+
+         \sstitem
+          B: byte (signed char)
+
+         \sstitem
+          UB: unsigned byte (unsigned char)
+
+      }
+      For example, astRebinD would be used to process \texttt{"} double\texttt{"}
+      data, while astRebinI would be used to process \texttt{"} int\texttt{"}
+      data, etc.
+
+      Note that, unlike
+      \htmlref{astResample$<$X$>$}{astResample$<$X$>$}, the astRebin$<$X$>$
+      set of functions does not yet support unsigned integer data types
+      or integers of different sizes.
+   }
+   \sstdiytopic{
+      Pixel Spreading Schemes
+   }{
+      The pixel spreading scheme specifies the Point Spread Function (PSF)
+      applied to each input pixel value as it is copied into the output
+      array. It can be thought of as the inverse of the sub-pixel
+      interpolation schemes used by the
+      astResample$<$X$>$
+      group of functions. That is, in a sub-pixel interpolation scheme the
+      kernel specifies the weight to assign to each input pixel when
+      forming the weighted mean of the input pixels, whereas the kernel in a
+      pixel spreading scheme specifies the fraction of the input data value
+      which is to be assigned to each output pixel. As for interpolation, the
+      choice of suitable pixel spreading scheme involves stricking a balance
+      between schemes which tend to degrade sharp features in the data by
+      smoothing them, and those which attempt to preserve sharp features but
+      which often tend to introduce unwanted artifacts. See the
+      astResample$<$X$>$
+      documentation for further discussion.
+
+      The binning algorithm used has the ability to introduce artifacts
+      not seen when using a resampling algorithm. Particularly, when
+      viewing the output image at high contrast, systems of curves lines
+      covering the entire image may be visible. These are caused by a
+      beating effect between the input pixel positions and the output pixels
+      position, and their nature and strength depend critically upon the
+      nature of the Mapping and the spreading function being used. In
+      general, the nearest neighbour spreading function demonstrates this
+      effect more clearly than the other functions, and for this reason
+      should be used with caution.
+
+      The following values (defined in the
+      \texttt{"} ast.h\texttt{"}  header file)
+      may be assigned to the
+      \texttt{"} spread\texttt{"}
+      parameter. See the
+      astResample$<$X$>$
+      documentation for details of these schemes including the use of the
+      \texttt{"} fspread\texttt{"}  and \texttt{"} params\texttt{"}  parameters:
+
+      \sstitemlist{
+
+         \sstitem
+          AST\_\_NEAREST
+
+         \sstitem
+          AST\_\_LINEAR
+
+         \sstitem
+          AST\_\_SINC
+
+         \sstitem
+          AST\_\_SINCSINC
+
+         \sstitem
+          AST\_\_SINCCOS
+
+         \sstitem
+          AST\_\_SINCGAUSS
+
+         \sstitem
+          AST\_\_SOMBCOS
+
+      }
+      In addition, the following schemes can be used with
+      astRebin$<$X$>$ but not with astResample$<$X$>$:
+
+      \sstitemlist{
+
+         \sstitem
+          AST\_\_GAUSS: This scheme uses a kernel of the form exp(-k$*$x$*$x), with k
+         a positive constant determined by the full-width at half-maximum (FWHM).
+         The FWHM should be supplied in units of output pixels by means of the
+         \texttt{"} params[1]\texttt{"}
+         value and should be at least 0.1. The
+         \texttt{"} params[0]\texttt{"}
+         value should be used to specify at what point the Gaussian is truncated
+         to zero. This should be given as a number of output pixels on either
+         side of the central output point in each dimension (the nearest integer
+         value is used).
+      }
+   }
+   \sstdiytopic{
+      Control Flags
+   }{
+      The following flags are defined in the \texttt{"} ast.h\texttt{"}  header file and
+      may be used to provide additional control over the rebinning
+      process. Having selected a set of flags, you should supply the
+      bitwise OR of their values via the \texttt{"} flags\texttt{"}  parameter:
+
+      \sstitemlist{
+
+         \sstitem
+          AST\_\_USEBAD: Indicates that there may be bad pixels in the
+         input array(s) which must be recognised by comparing with the
+         value given for \texttt{"} badval\texttt{"}  and propagated to the output array(s).
+         If this flag is not set, all input values are treated literally
+         and the \texttt{"} badval\texttt{"}  value is only used for flagging output array
+         values.
+      }
+   }
+   \sstdiytopic{
+      Propagation of Missing Data
+   }{
+      Instances of missing data (bad pixels) in the output grid are
+      identified by occurrences of the \texttt{"} badval\texttt{"}  value in the \texttt{"} out\texttt{"}
+      array. These are produced if the sum of the weights of the
+      contributing input pixels is less than
+      \texttt{"} wlim\texttt{"} .
+
+      An input pixel is considered bad (and is consequently ignored) if
+      its
+      data value is equal to \texttt{"} badval\texttt{"}  and the AST\_\_USEBAD flag is
+      set via the \texttt{"} flags\texttt{"}  parameter.
+
+      In addition, associated output variance estimates (if
+      calculated) may be declared bad and flagged with the \texttt{"} badval\texttt{"}
+      value in the \texttt{"} out\_var\texttt{"}  array for similar reasons.
+   }
+}
+\sstroutine{
+   astRebinSeq$<$X$>$
+}{
+   Rebin a region of a sequence of data grids
+}{
+   \sstdescription{
+      This set of
+      functions is identical to \htmlref{astRebin$<$X$>$}{astRebin$<$X$>$}
+      except that the rebinned input data is added into the supplied
+      output arrays, rather than simply over-writing the contents of the
+      output arrays. Thus, by calling this
+      function
+      repeatedly, a sequence of input arrays can be rebinned and accumulated
+      into a single output array, effectively forming a mosaic of the
+      input data arrays.
+
+      In addition, the weights associated with each output pixel are
+      returned. The weight of an output pixel indicates the number of input
+      pixels which have been accumulated in that output pixel. If the entire
+      value of an input pixel is assigned to a single output pixel, then the
+      weight of that output pixel is incremented by one. If some fraction of
+      the value of an input pixel is assigned to an output pixel, then the
+      weight of that output pixel is incremented by the fraction used.
+
+      The start of a new sequence is indicated by specifying the
+      AST\_\_REBININIT flag via the
+      \texttt{"} flags\texttt{"}  parameter.
+      This causes the supplied arrays to be filled with zeros before the
+      rebinned input data is added into them. Subsequenct invocations
+      within the same sequence should omit the AST\_\_REBININIT flag.
+
+      The last call in a sequence is indicated by specifying the
+      AST\_\_REBINEND flag. Depending on which flags are supplied, this may
+      cause the output data and variance arrays to be normalised before
+      being returned. This normalisation consists of dividing the data
+      array by the weights array, and can eliminate artifacts which may be
+      introduced into the rebinned data as a consequence of aliasing
+      between the input and output grids. This results in each output
+      pixel value being the weighted mean of the input pixel values that
+      fall in the neighbourhood of the output pixel (rather like
+      \htmlref{astResample$<$X$>$}{astResample$<$X$>$}).
+      Optionally, these normalised
+      values can then be multiplied by a scaling factor to ensure that the
+      total data sum in any small area is unchanged. This scaling factor
+      is equivalent to the number of input pixel values that fall into each
+      output pixel. In addition to
+      normalisation of the output data values, any output variances are
+      also appropriately normalised, and any output data values with
+      weight less than
+      \texttt{"} wlim\texttt{"}  are set to \texttt{"} badval\texttt{"} .
+
+      Output variances can be generated in two ways; by rebinning the supplied
+      input variances with appropriate weights, or by finding the spread of
+      input data values contributing to each output pixel (see the AST\_\_GENVAR
+      and AST\_\_USEVAR flags).
+   }
+   \sstsynopsis{
+      void astRebinSeq$<$X$>$( AstMapping $*$this, double wlim, int ndim\_in,
+                           const int lbnd\_in[], const int ubnd\_in[],
+                           const $<$Xtype$>$ in[], const $<$Xtype$>$ in\_var[],
+                           int spread, const double params[], int flags,
+                           double tol, int maxpix, $<$Xtype$>$ badval,
+                           int ndim\_out, const int lbnd\_out[],
+                           const int ubnd\_out[], const int lbnd[],
+                           const int ubnd[], $<$Xtype$>$ out[], $<$Xtype$>$ out\_var[],
+                           double weights[], int64\_t $*$nused );
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to a \htmlref{Mapping}{Mapping}, whose forward transformation will be
+         used to transform the coordinates of pixels in the input
+         grid into the coordinate system of the output grid.
+
+         The number of input coordinates used by this Mapping (as
+         given by its \htmlref{Nin}{Nin} attribute) should match the number of input
+         grid dimensions given by the value of \texttt{"} ndim\_in\texttt{"}
+         below. Similarly, the number of output coordinates (\htmlref{Nout}{Nout}
+         attribute) should match the number of output grid dimensions
+         given by \texttt{"} ndim\_out\texttt{"} .
+         If \texttt{"} in\texttt{"}  is NULL, the Mapping will not be used, but a valid
+         Mapping must still be supplied.
+      }
+      \sstsubsection{
+         wlim
+      }{
+         This value is only used if the AST\_\_REBINEND flag is specified
+         via the
+         \texttt{"} flags\texttt{"}  parameter.
+         It gives the required number of input pixel values which must
+         contribute to an output pixel (i.e. the output pixel weight) in
+         order for the output pixel value to be considered valid. If the sum
+         of the input pixel weights contributing to an output pixel is less
+         than the supplied
+         \texttt{"} wlim\texttt{"}
+         value, then the output pixel value is returned set to the
+         supplied bad value. If the supplied value is less than 1.0E-10
+         then 1.0E-10 is used instead.
+      }
+      \sstsubsection{
+         ndim\_in
+      }{
+         The number of dimensions in the input grid. This should be at
+         least one.
+         Not used if \texttt{"} in\texttt{"}  is NULL.
+      }
+      \sstsubsection{
+         lbnd\_in
+      }{
+         Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"}  elements,
+         containing the coordinates of the centre of the first pixel
+         in the input grid along each dimension.
+         Not used if \texttt{"} in\texttt{"}  is NULL.
+      }
+      \sstsubsection{
+         ubnd\_in
+      }{
+         Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"}  elements,
+         containing the coordinates of the centre of the last pixel in
+         the input grid along each dimension.
+
+         Note that \texttt{"} lbnd\_in\texttt{"}  and \texttt{"} ubnd\_in\texttt{"}  together define the shape
+         and size of the input grid, its extent along a particular
+         (j\texttt{'} th) dimension being ubnd\_in[j]-lbnd\_in[j]$+$1 (assuming the
+         index \texttt{"} j\texttt{"}  to be zero-based). They also define
+         the input grid\texttt{'} s coordinate system, each pixel having unit
+         extent along each dimension with integral coordinate values
+         at its centre.
+         Not used if \texttt{"} in\texttt{"}  is NULL.
+      }
+      \sstsubsection{
+         in
+      }{
+         Pointer to an array, with one element for each pixel in the
+         input grid, containing the input data to be rebined.  The
+         numerical type of this array should match the 1- or
+         2-character type code appended to the function name (e.g. if
+         you are using astRebinSeqF, the type of each array element
+         should be \texttt{"} float\texttt{"} ).
+
+         The storage order of data within this array should be such
+         that the index of the first grid dimension varies most
+         rapidly and that of the final dimension least rapidly
+         (i.e. Fortran array indexing is used).
+         If a NULL pointer is supplied for \texttt{"} in\texttt{"} , then no data is added to
+         the output arrays, but any initialisation or normalisation
+         requested by \texttt{"} flags\texttt{"}  is still performed.
+      }
+      \sstsubsection{
+         in\_var
+      }{
+         An optional
+         pointer to a
+         second array with the same size and type as the
+         \texttt{"} in\texttt{"}
+         array. If given, this should contain a set of non-negative values
+         which represent estimates of the statistical variance associated
+         with each element of the
+         \texttt{"} in\texttt{"}
+         array.
+         If neither the AST\_\_USEVAR nor the AST\_\_VARWGT flag is set, no
+         input variance estimates are required and this
+         pointer
+         will not be used.
+         A NULL pointer
+         may then be supplied.
+      }
+      \sstsubsection{
+         spread
+      }{
+         This parameter specifies the scheme to be used for dividing
+         each input data value up amongst the corresponding output pixels.
+         It may be used to select
+         from a set of pre-defined schemes by supplying one of the
+         values described in the \texttt{"} Pixel Spreading Schemes\texttt{"}
+         section in the description of the
+         astRebin$<$X$>$ functions.
+         If a value of zero is supplied, then the default linear spreading
+         scheme is used (equivalent to supplying the value AST\_\_LINEAR).
+         Not used if \texttt{"} in\texttt{"}  is NULL.
+      }
+      \sstsubsection{
+         params
+      }{
+         An optional pointer to an array of double which should contain
+         any additional parameter values required by the pixel
+         spreading scheme. If such parameters are required, this
+         will be noted in the \texttt{"} Pixel Spreading Schemes\texttt{"}  section in the
+         description of the
+         astRebin$<$X$>$ functions.
+
+         If no additional parameters are required, this array is not
+         used and a NULL pointer may be given.
+         Not used if \texttt{"} in\texttt{"}  is NULL.
+      }
+      \sstsubsection{
+         flags
+      }{
+         The bitwise OR of a set of flag values which may be used to
+         provide additional control over the rebinning operation. See
+         the \texttt{"} Control Flags\texttt{"}  section below for a description of the
+         options available.  If no flag values are to be set, a value
+         of zero should be given.
+      }
+      \sstsubsection{
+         tol
+      }{
+         The maximum tolerable geometrical distortion which may be
+         introduced as a result of approximating non-linear Mappings
+         by a set of piece-wise linear transformations. This should be
+         expressed as a displacement in pixels in the output grid\texttt{'} s
+         coordinate system.
+
+         If piece-wise linear approximation is not required, a value
+         of zero may be given. This will ensure that the Mapping is
+         used without any approximation, but may increase execution
+         time.
+
+         If the value is too high, discontinuities between the linear
+         approximations used in adjacent panel will be higher, and may
+         cause the edges of the panel to be visible when viewing the output
+         image at high contrast. If this is a problem, reduce the
+         tolerance value used.
+         Not used if \texttt{"} in\texttt{"}  is NULL.
+      }
+      \sstsubsection{
+         maxpix
+      }{
+         A value which specifies an initial scale size (in pixels) for
+         the adaptive algorithm which approximates non-linear Mappings
+         with piece-wise linear transformations. Normally, this should
+         be a large value (larger than any dimension of the region of
+         the input grid being used). In this case, a first attempt to
+         approximate the Mapping by a linear transformation will be
+         made over the entire input region.
+
+         If a smaller value is used, the input region will first be
+         divided into sub-regions whose size does not exceed \texttt{"} maxpix\texttt{"}
+         pixels in any dimension. Only at this point will attempts at
+         approximation commence.
+
+         This value may occasionally be useful in preventing false
+         convergence of the adaptive algorithm in cases where the
+         Mapping appears approximately linear on large scales, but has
+         irregularities (e.g. holes) on smaller scales. A value of,
+         say, 50 to 100 pixels can also be employed as a safeguard in
+         general-purpose software, since the effect on performance is
+         minimal.
+
+         If too small a value is given, it will have the effect of
+         inhibiting linear approximation altogether (equivalent to
+         setting \texttt{"} tol\texttt{"}  to zero). Although this may degrade
+         performance, accurate results will still be obtained.
+         Not used if \texttt{"} in\texttt{"}  is NULL.
+      }
+      \sstsubsection{
+         badval
+      }{
+         This argument should have the same type as the elements of
+         the \texttt{"} in\texttt{"}  array. It specifies the value used to flag missing
+         data (bad pixels) in the input and output arrays.
+
+         If the AST\_\_USEBAD flag is set via the \texttt{"} flags\texttt{"}  parameter,
+         then this value is used to test for bad pixels in the \texttt{"} in\texttt{"}
+         (and \texttt{"} in\_var\texttt{"} ) array(s).
+
+         In all cases, this value is also used to flag any output
+         elements in the \texttt{"} out\texttt{"}  (and \texttt{"} out\_var\texttt{"} ) array(s) for which
+         rebined values could not be obtained (see the \texttt{"} Propagation
+         of Missing Data\texttt{"}  section below for details of the
+         circumstances under which this may occur).
+      }
+      \sstsubsection{
+         ndim\_out
+      }{
+         The number of dimensions in the output grid. This should be
+         at least one. It need not necessarily be equal to the number
+         of dimensions in the input grid.
+      }
+      \sstsubsection{
+         lbnd\_out
+      }{
+         Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"}  elements,
+         containing the coordinates of the centre of the first pixel
+         in the output grid along each dimension.
+      }
+      \sstsubsection{
+         ubnd\_out
+      }{
+         Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"}  elements,
+         containing the coordinates of the centre of the last pixel in
+         the output grid along each dimension.
+
+         Note that \texttt{"} lbnd\_out\texttt{"}  and \texttt{"} ubnd\_out\texttt{"}  together define the
+         shape, size and coordinate system of the output grid in the
+         same way as \texttt{"} lbnd\_in\texttt{"}  and \texttt{"} ubnd\_in\texttt{"}  define the shape, size
+         and coordinate system of the input grid.
+      }
+      \sstsubsection{
+         lbnd
+      }{
+         Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"}  elements,
+         containing the coordinates of the first pixel in the region
+         of the input grid which is to be included in the rebined output
+         array.
+         Not used if \texttt{"} in\texttt{"}  is NULL.
+      }
+      \sstsubsection{
+         ubnd
+      }{
+         Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"}  elements,
+         containing the coordinates of the last pixel in the region of
+         the input grid which is to be included in the rebined output
+         array.
+
+         Note that \texttt{"} lbnd\texttt{"}  and \texttt{"} ubnd\texttt{"}  together define the shape and
+         position of a (hyper-)rectangular region of the input grid
+         which is to be included in the rebined output array. This region
+         should lie wholly within the extent of the input grid (as
+         defined by the \texttt{"} lbnd\_in\texttt{"}  and \texttt{"} ubnd\_in\texttt{"}  arrays). Regions of
+         the input grid lying outside this region will not be used.
+         Not used if \texttt{"} in\texttt{"}  is NULL.
+      }
+      \sstsubsection{
+         out
+      }{
+         Pointer to an array, with one element for each pixel in the
+         output grid. The rebined data values will be added into the
+         original contents of this array. The numerical type of this array
+         should match that of the
+         \texttt{"} in\texttt{"}  array, and the data storage order should be such
+         that the index of the first grid dimension varies most
+         rapidly and that of the final dimension least rapidly
+         (i.e. Fortran array indexing is used).
+      }
+      \sstsubsection{
+         out\_var
+      }{
+         A
+         pointer to an
+         array with the same type and size as the
+         \texttt{"} out\texttt{"}
+         array. This
+         pointer
+         will only be used if the AST\_\_USEVAR or AST\_\_GENVAR flag is set
+         in which case variance estimates for the rebined data values will
+         be added into the array. If neither the AST\_\_USEVAR flag nor the
+         AST\_\_GENVAR flag is set, no output variance estimates will be
+         calculated and this
+         pointer
+         will not be used. A
+         NULL pointer
+         may then be supplied.
+      }
+      \sstsubsection{
+         weights
+      }{
+         Pointer to an array of double,
+         with one or two elements for each pixel in the output grid,
+         depending on whether or not the AST\_\_GENVAR flag has been supplied
+         via the
+         \texttt{"} flags\texttt{"}  parameter.
+         If AST\_\_GENVAR has not been specified then the array should have
+         one element for each output pixel, and it will be used to
+         accumulate the weight associated with each output pixel.
+         If AST\_\_GENVAR has been specified then the array should have
+         two elements for each output pixel. The first half of the array
+         is again used to accumulate the weight associated with each output
+         pixel, and the second half is used to accumulate the square of
+         the weights. In each half, the data storage order should be such that
+         the index of the first grid dimension varies most rapidly and that of
+         the final dimension least rapidly
+         (i.e. Fortran array indexing is used).
+      }
+      \sstsubsection{
+         nused
+      }{
+         A pointer to an int64\_t containing the
+         number of input data values that have been added into the output
+         array so far. The supplied value is incremented on exit by the
+         number of input values used. The value is initially set to zero
+         if the AST\_\_REBININIT flag is set in
+         \texttt{"} flags\texttt{"} .
+      }
+   }
+   \sstdiytopic{
+      Data Type Codes
+   }{
+      To select the appropriate rebinning function, you should
+      replace $<$X$>$ in the generic function name astRebinSeq$<$X$>$ with a
+      1- or 2-character data type code, so as to match the numerical
+      type $<$Xtype$>$ of the data you are processing, as follows:
+      \sstitemlist{
+
+         \sstitem
+          D: double
+
+         \sstitem
+          F: float
+
+         \sstitem
+          I: int
+
+         \sstitem
+          B: byte (signed char)
+
+         \sstitem
+          UB: unsigned byte (unsigned char)
+
+      }
+      For example, astRebinSeqD would be used to process \texttt{"} double\texttt{"}
+      data, while astRebinSeqI would be used to process \texttt{"} int\texttt{"}
+      data, etc.
+
+      Note that, unlike
+      astResample$<$X$>$, the astRebinSeq$<$X$>$
+      set of functions does not yet support unsigned integer data types
+      or integers of different sizes.
+   }
+   \sstdiytopic{
+      Control Flags
+   }{
+      The following flags are defined in the \texttt{"} ast.h\texttt{"}  header file and
+      may be used to provide additional control over the rebinning
+      process. Having selected a set of flags, you should supply the
+      bitwise OR of their values via the \texttt{"} flags\texttt{"}  parameter:
+
+      \sstitemlist{
+
+         \sstitem
+          AST\_\_REBININIT: Used to mark the first call in a sequence. It indicates
+         that the supplied
+         \texttt{"} out\texttt{"} , \texttt{"} out\_var\texttt{"}  and \texttt{"} weights\texttt{"}
+         arrays should be filled with zeros (thus over-writing any supplied
+         values) before adding the rebinned input data into them. This flag
+         should be used when rebinning the first input array in a sequence.
+
+         \sstitem
+          AST\_\_REBINEND: Used to mark the last call in a sequence. It causes
+         each value in the
+         \texttt{"} out\texttt{"}  and \texttt{"} out\_var\texttt{"}
+         arrays to be divided by a normalisation factor before being
+         returned. The normalisation factor for each output data value is just
+         the corresponding value from the weights array. The normalisation
+         factor for each output variance value is the square of the data value
+         normalisation factor (see also AST\_\_CONSERVEFLUX). It also causes
+         output data values to be set bad if the corresponding weight is less
+         than the value supplied for
+         parameter \texttt{"} wlim\texttt{"} .
+         It also causes any temporary values stored in the output variance array
+         (see flag AST\_\_GENVAR below) to be converted into usable variance values.
+         Note, this flag is ignored if the AST\_\_NONORM flag is set.
+
+         \sstitem
+          AST\_\_USEBAD: Indicates that there may be bad pixels in the
+         input array(s) which must be recognised by comparing with the
+         value given for \texttt{"} badval\texttt{"}  and propagated to the output array(s).
+         If this flag is not set, all input values are treated literally
+         and the \texttt{"} badval\texttt{"}  value is only used for flagging output array
+         values.
+
+         \sstitem
+          AST\_\_USEVAR: Indicates that output variance estimates should be
+         created by rebinning the supplied input variance estimates. An
+         error will be reported if both this flag and the AST\_\_GENVAR flag
+         are supplied.
+
+         \sstitem
+          AST\_\_GENVAR: Indicates that output variance estimates should be
+         created based on the spread of input data values contributing to each
+         output pixel. An error will be reported if both this flag and the
+         AST\_\_USEVAR flag are supplied. If the AST\_\_GENVAR flag is specified,
+         the supplied output variance array is first used as a work array to
+         accumulate the temporary values needed to generate the output
+         variances. When the sequence ends (as indicated by the
+         AST\_\_REBINEND flag), the contents of the output variance array are
+         converted into the required variance estimates. If the generation of
+         such output variances is required, this flag should be used on every
+         invocation of this
+         function
+         within a sequence, and any supplied input variances will have no effect
+         on the output variances (although input variances will still be used
+         to weight the input data if the AST\_\_VARWGT flag is also supplied).
+         The statistical meaning of these output varianes is determined by
+         the presence or absence of the AST\_\_DISVAR flag (see below).
+
+         \sstitem
+          AST\_\_DISVAR: This flag is ignored unless the AST\_\_GENVAR flag
+         has also been specified. It determines the statistical meaning of
+         the generated output variances. If AST\_\_DISVAR is not specified,
+         generated variances represent variances on the output mean  values. If
+         AST\_\_DISVAR is specified, the generated variances represent the variance
+         of the distribution from which the input values were taken. Each output
+         variance created with AST\_\_DISVAR will be larger than that created
+         without AST\_\_DISVAR by a factor equal to the number of input samples
+         that contribute to the output sample.
+
+         \sstitem
+          AST\_\_VARWGT: Indicates that the input data should be weighted by
+         the reciprocal of the input variances. Otherwise, all input data are
+         given equal weight. If this flag is specified, the calculation of the
+         output variances (if any) is modified to take account of the
+         varying weights assigned to the input data values.
+
+         \sstitem
+          AST\_\_NONORM: If the simple unnormalised sum of all input data falling
+         in each output pixel is required, then this flag should be set on
+         each call in the sequence and the AST\_\_REBINEND should not be used
+         on the last call. In this case
+         NULL pointers can be supplied for \texttt{"} weights\texttt{"}  and \texttt{"} nused\texttt{"} .
+         This flag cannot be used with the AST\_\_CONSERVEFLUX, AST\_\_GENVAR
+         or AST\_\_VARWGT flag.
+
+         \sstitem
+          AST\_\_CONSERVEFLUX: Indicates that the normalized output pixel values
+         generated by the AST\_\_REBINEND flag should be scaled in such a way as
+         to preserve the total data value in a feature on the sky. Without this
+         flag, each normalised output pixel value represents a weighted mean
+         of the input data values around the corresponding input position.
+         is appropriate if the input data represents the spatial density of
+         some quantity (e.g. surface brightness in Janskys per square
+         arc-second) because the output pixel values will have the same
+         normalisation and units as the input pixel values. However, if the
+         input data values represent flux (or some other physical quantity)
+         per pixel, then the AST\_\_CONSERVEFLUX flag could be of use. It causes
+         each output pixel value to be scaled by the ratio of the output pixel
+         size to the input pixel size.
+
+      }
+      This flag can only be used if the Mapping is successfully approximated
+      by one or more linear transformations. Thus an error will be reported
+      if it used when the
+      \texttt{"} tol\texttt{"}  parameter
+      is set to zero (which stops the use of linear approximations), or
+      if the Mapping is too non-linear to be approximated by a piece-wise
+      linear transformation. The ratio of output to input pixel size is
+      evaluated once for each panel of the piece-wise linear approximation to
+      the Mapping, and is assumed to be constant for all output pixels in the
+      panel. The scaling factors for adjacent panels will in general
+      differ slightly, and so the joints between panels may be visible when
+      viewing the output image at high contrast. If this is a problem,
+      reduce the value of the
+      \texttt{"} tol\texttt{"}  parameter
+      until the difference between adjacent panels is sufficiently small
+      to be insignificant.
+
+      This flag should normally be supplied on each invocation of
+      astRebinSeq$<$X$>$
+      within a given sequence.
+
+      Note, this flag cannot be used in conjunction with the AST\_\_NOSCALE
+      flag (an error will be reported if both flags are specified).
+   }
+   \sstdiytopic{
+      Propagation of Missing Data
+   }{
+      Instances of missing data (bad pixels) in the output grid are
+      identified by occurrences of the \texttt{"} badval\texttt{"}  value in the \texttt{"} out\texttt{"}
+      array. These are only produced if the AST\_\_REBINEND flag is
+      specified and a pixel has zero weight.
+
+      An input pixel is considered bad (and is consequently ignored) if
+      its
+      data value is equal to \texttt{"} badval\texttt{"}  and the AST\_\_USEBAD flag is
+      set via the \texttt{"} flags\texttt{"}  parameter.
+
+      In addition, associated output variance estimates (if
+      calculated) may be declared bad and flagged with the \texttt{"} badval\texttt{"}
+      value in the \texttt{"} out\_var\texttt{"}  array for similar reasons.
+   }
+}
+\sstroutine{
+   astRegionOutline
+}{
+   Draw the outline of an AST Region
+}{
+   \sstdescription{
+      This function draws an outline around the supplied AST \htmlref{Region}{Region} object.
+   }
+   \sstsynopsis{
+      void astRegionOutline( AstPlot $*$this, AstRegion $*$region )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the \htmlref{Plot}{Plot}.
+      }
+      \sstsubsection{
+         region
+      }{
+         Pointer to the Region.
+      }
+   }
+}
+\sstroutine{
+   astRemapFrame
+}{
+   Modify a Frame\texttt{'} s relationship to other Frames in a FrameSet
+}{
+   \sstdescription{
+      This function modifies the relationship (i.e. \htmlref{Mapping}{Mapping}) between a
+      specified \htmlref{Frame}{Frame} in a \htmlref{FrameSet}{FrameSet} and the other Frames in that
+      FrameSet.
+
+      Typically, this might be required if the FrameSet has been used
+      to calibrate (say) an image, and that image is re-binned. The
+      Frame describing the image will then have undergone a coordinate
+      transformation, and this should be communicated to the associated
+      FrameSet using this function.
+   }
+   \sstsynopsis{
+      void astRemapFrame( AstFrameSet $*$this, int iframe, AstMapping $*$map )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FrameSet.
+      }
+      \sstsubsection{
+         iframe
+      }{
+         The index within the FrameSet of the Frame to be modified.
+         This value should lie in the range from 1 to the number of
+         Frames in the FrameSet (as given by its \htmlref{Nframe}{Nframe} attribute).
+      }
+      \sstsubsection{
+         map
+      }{
+         Pointer to a Mapping whose forward transformation converts
+         coordinate values from the original coordinate system
+         described by the Frame to the new one, and whose inverse
+         transformation converts in the opposite direction.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A value of AST\_\_BASE or AST\_\_CURRENT may be given for the
+         \texttt{"} iframe\texttt{"}  parameter to specify the base Frame or the current
+         Frame respectively.
+
+         \sstitem
+          The relationship between the selected Frame and any other
+         Frame within the FrameSet will be modified by this function,
+         but the relationship between all other Frames in the FrameSet
+         remains unchanged.
+
+         \sstitem
+          The number of input coordinate values accepted by the Mapping
+         (its \htmlref{Nin}{Nin} attribute) and the number of output coordinate values
+         generated (its \htmlref{Nout}{Nout} attribute) must be equal and must match the
+         number of axes in the Frame being modified.
+
+         \sstitem
+          If a simple change of axis order is required, then the
+         \htmlref{astPermAxes}{astPermAxes} function may provide a more straightforward method
+         of making the required changes to the FrameSet.
+
+         \sstitem
+          This function cannot be used to change the number of Frame
+         axes. To achieve this, a new Frame must be added to the FrameSet
+         (\htmlref{astAddFrame}{astAddFrame}) and the original one removed if necessary
+         (\htmlref{astRemoveFrame}{astRemoveFrame}).
+
+         \sstitem
+          Any variant Mappings associated with the remapped Frame (except
+         for the current variant) will be lost as a consequence of calling this
+         method (see attribute \texttt{"} \htmlref{Variant}{Variant}\texttt{"} ).
+      }
+   }
+}
+\sstroutine{
+   astRemoveColumn
+}{
+   Remove a column from a table
+}{
+   \sstdescription{
+      This function removes a specified column from the supplied table.
+      The
+      function
+      returns without action if the named column does not exist in the
+      \htmlref{Table}{Table} (no error is reported).
+   }
+   \sstsynopsis{
+      void astRemoveColumn( AstTable $*$this, const char $*$name )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Table.
+      }
+      \sstsubsection{
+         name
+      }{
+         The column name. Trailing spaces are ignored (all other spaces
+         are significant). Case is significant.
+      }
+   }
+}
+\sstroutine{
+   astRemoveFrame
+}{
+   Remove a Frame from a FrameSet
+}{
+   \sstdescription{
+      This function removes a \htmlref{Frame}{Frame} from a \htmlref{FrameSet}{FrameSet}. All other Frames
+      in the FrameSet have their indices re-numbered from one (if
+      necessary), but are otherwise unchanged.
+   }
+   \sstsynopsis{
+      void astRemoveFrame( AstFrameSet $*$this, int iframe )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FrameSet.
+      }
+      \sstsubsection{
+         iframe
+      }{
+         The index within the FrameSet of the Frame to be removed.
+         This value should lie in the range from 1 to the number of
+         Frames in the FrameSet (as given by its \htmlref{Nframe}{Nframe} attribute).
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Removing a Frame from a FrameSet does not affect the
+         relationship between other Frames in the FrameSet, even if they
+         originally depended on the Frame being removed.
+
+         \sstitem
+          The number of Frames in a FrameSet cannot be reduced to zero.
+         An error will result if an attempt is made to remove the only
+         remaining Frame.
+
+         \sstitem
+          A value of AST\_\_BASE or AST\_\_CURRENT may be given for the
+         \texttt{"} iframe\texttt{"}  parameter to specify the base Frame or the current
+         Frame respectively.
+
+         \sstitem
+          If a FrameSet\texttt{'} s base or current Frame is removed, the \htmlref{Base}{Base} or
+         \htmlref{Current}{Current} attribute (respectively) of the FrameSet will have its
+         value cleared, so that another Frame will then assume its role
+         by default.
+
+         \sstitem
+          If any other Frame is removed, the base and current Frames
+         will remain the same. To ensure this, the Base and/or Current
+         attributes of the FrameSet will be changed, if necessary, to
+         reflect any change in the indices of these Frames.
+      }
+   }
+}
+\sstroutine{
+   astRemoveParameter
+}{
+   Remove a global parameter from a table
+}{
+   \sstdescription{
+      This function removes a specified global parameter from the supplied table.
+      The
+      function
+      returns without action if the named parameter does not exist in the
+      \htmlref{Table}{Table} (no error is reported).
+   }
+   \sstsynopsis{
+      void astRemoveParameter( AstTable $*$this, const char $*$name )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Table.
+      }
+      \sstsubsection{
+         name
+      }{
+         The parameter name. Trailing spaces are ignored (all other spaces
+         are significant). Case is significant.
+      }
+   }
+}
+\sstroutine{
+   astRemoveRegions
+}{
+   Remove any Regions from a Mapping
+}{
+   \sstdescription{
+      This function searches the suppliedMapping (which may be a
+      compound \htmlref{Mapping}{Mapping} such as a \htmlref{CmpMap}{CmpMap}) for any component Mappings
+      that are instances of the AST \htmlref{Region}{Region} class. It then creates a new
+      Mapping from which all Regions have been removed. If a Region
+      cannot simply be removed (for instance, if it is a component of a
+      parallel CmpMap), then it is replaced with an equivalent \htmlref{UnitMap}{UnitMap}
+      in the returned Mapping.
+   }
+   \sstsynopsis{
+      AstMapping $*$astRemoveRegions( AstMapping $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the original Mapping.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{CmpFrame}{CmpFrame}
+      }{
+         If the supplied Mapping is a CmpFrame, any component Frames that
+         are instances of the Region class are replaced by the equivalent
+         \htmlref{Frame}{Frame}.
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         If the supplied Mapping is a FrameSet, the returned Mapping
+         will be a copy of the supplied FrameSet in which Regions have
+         been removed from all the inter-Frame Mappings, and any Frames
+         which are instances of the Region class are repalced by the
+         equivalent Frame.
+      }
+      \sstsubsection{
+         Mapping
+      }{
+         This function applies to all Mappings.
+      }
+      \sstsubsection{
+         Region
+      }{
+         If the supplied Mapping is a Region, the returned Mapping will
+         be the equivalent Frame.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astRemoveRegions()
+      }{
+         A new pointer to the (possibly modified) Mapping.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This function can safely be applied even to Mappings which
+         contain no Regions. If no Regions are found, it
+         behaves exactly like \htmlref{astClone}{astClone} and returns a pointer to the
+         original Mapping.
+
+         \sstitem
+          The Mapping returned by this function may not be independent
+         of the original (even if some Regions were removed), and
+         modifying it may therefore result in indirect modification of
+         the original. If a completely independent result is required, a
+         copy should be made using \htmlref{astCopy}{astCopy}.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astRemoveRow
+}{
+   Remove a row from a table
+}{
+   \sstdescription{
+      This function removes a specified row from the supplied table.
+      The
+      function
+      returns without action if the row does not exist in the
+      \htmlref{Table}{Table} (no error is reported).
+   }
+   \sstsynopsis{
+      void astRemoveRow( AstTable $*$this, int index )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Table.
+      }
+      \sstsubsection{
+         index
+      }{
+         The index of the row to be removed. The first row has index 1.
+      }
+   }
+}
+\sstroutine{
+   astRemoveTables
+}{
+   Remove one or more tables from a FitsChan
+}{
+   \sstdescription{
+      This function
+      removes the named tables from the \htmlref{FitsChan}{FitsChan}, it they exist (no error
+      is reported if any the tables do not exist).
+   }
+   \sstsynopsis{
+      void astRemoveTables( AstFitsChan $*$this, const char $*$key )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FitsChan.
+      }
+      \sstsubsection{
+         key
+      }{
+         The key indicating which tables to exist. A single key or a
+         comma-separated list of keys can be supplied. If a blank string
+         is supplied, all tables are removed.
+      }
+   }
+}
+\sstroutine{
+   astResample$<$X$>$
+}{
+   Resample a region of a data grid
+}{
+   \sstdescription{
+      This is a set of functions for resampling gridded data (e.g. an
+      image) under the control of a geometrical transformation, which
+      is specified by a \htmlref{Mapping}{Mapping}.  The functions operate on a pair of
+      data grids (input and output), each of which may have any number
+      of dimensions. Resampling may be restricted to a specified
+      region of the output grid. An associated grid of error estimates
+      associated with the input data may also be supplied (in the form
+      of variance values), so as to produce error estimates for the
+      resampled output data. Propagation of missing data (bad pixels)
+      is supported.
+
+      You should use a resampling function which matches the numerical
+      type of the data you are processing by replacing $<$X$>$ in
+      the generic function name astResample$<$X$>$ by an appropriate 1- or
+      2-character type code. For example, if you are resampling data
+      with type \texttt{"} float\texttt{"} , you should use the function astResampleF (see
+      the \texttt{"} Data Type Codes\texttt{"}  section below for the codes appropriate to
+      other numerical types).
+
+      Resampling of the grid of input data is performed by
+      transforming the coordinates of the centre of each output grid
+      element (or pixel) into the coordinate system of the input grid.
+      Since the resulting coordinates will not, in general, coincide
+      with the centre of an input pixel, sub-pixel interpolation is
+      performed between the neighbouring input pixels. This produces a
+      resampled value which is then assigned to the output pixel. A
+      choice of sub-pixel interpolation schemes is provided, but you
+      may also implement your own.
+
+      This algorithm samples the input data value, it does not integrate
+      it. Thus total data value in the input image will not, in general,
+      be conserved. However, an option is provided (see the \texttt{"} Control Flags\texttt{"}
+      section below) which can produce approximate flux conservation by
+      scaling the output values using the ratio of the output pixel size
+      to the input pixel size. However, if accurate flux conservation is
+      important to you, consder using the
+      \htmlref{astRebin$<$X$>$}{astRebin$<$X$>$} or \htmlref{astRebinSeq$<$X$>$}{astRebinSeq$<$X$>$} family of functions
+      instead.
+
+      Output pixel coordinates are transformed into the coordinate
+      system of the input grid using the inverse transformation of the
+      Mapping which is supplied. This means that geometrical features
+      in the input data are subjected to the Mapping\texttt{'} s forward
+      transformation as they are transferred from the input to the
+      output grid (although the Mapping\texttt{'} s forward transformation is
+      not explicitly used).
+
+      In practice, transforming the coordinates of every pixel of a
+      large data grid can be time-consuming, especially if the Mapping
+      involves complicated functions, such as sky projections. To
+      improve performance, it is therefore possible to approximate
+      non-linear Mappings by a set of linear transformations which are
+      applied piece-wise to separate sub-regions of the data. This
+      approximation process is applied automatically by an adaptive
+      algorithm, under control of an accuracy criterion which
+      expresses the maximum tolerable geometrical distortion which may
+      be introduced, as a fraction of a pixel.
+
+      This algorithm first attempts to approximate the Mapping with a
+      linear transformation applied over the whole region of the
+      output grid which is being used. If this proves to be
+      insufficiently accurate, the output region is sub-divided into
+      two along its largest dimension and the process is repeated
+      within each of the resulting sub-regions. This process of
+      sub-division continues until a sufficiently good linear
+      approximation is found, or the region to which it is being
+      applied becomes too small (in which case the original Mapping is
+      used directly).
+   }
+   \sstsynopsis{
+      int astResample$<$X$>$( AstMapping $*$this, int ndim\_in,
+                          const int lbnd\_in[], const int ubnd\_in[],
+                          const $<$Xtype$>$ in[], const $<$Xtype$>$ in\_var[],
+                          int interp, void ($*$ finterp)( void ),
+                          const double params[], int flags,
+                          double tol, int maxpix,
+                          $<$Xtype$>$ badval, int ndim\_out,
+                          const int lbnd\_out[], const int ubnd\_out[],
+                          const int lbnd[], const int ubnd[],
+                          $<$Xtype$>$ out[], $<$Xtype$>$ out\_var[] );
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to a Mapping, whose inverse transformation will be
+         used to transform the coordinates of pixels in the output
+         grid into the coordinate system of the input grid. This
+         yields the positions which are used to obtain resampled
+         values by sub-pixel interpolation within the input grid.
+
+         The number of input coordinates used by this Mapping (as
+         given by its \htmlref{Nin}{Nin} attribute) should match the number of input
+         grid dimensions given by the value of \texttt{"} ndim\_in\texttt{"}
+         below. Similarly, the number of output coordinates (\htmlref{Nout}{Nout}
+         attribute) should match the number of output grid dimensions
+         given by \texttt{"} ndim\_out\texttt{"} .
+      }
+      \sstsubsection{
+         ndim\_in
+      }{
+         The number of dimensions in the input grid. This should be at
+         least one.
+      }
+      \sstsubsection{
+         lbnd\_in
+      }{
+         Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"}  elements,
+         containing the coordinates of the centre of the first pixel
+         in the input grid along each dimension.
+      }
+      \sstsubsection{
+         ubnd\_in
+      }{
+         Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"}  elements,
+         containing the coordinates of the centre of the last pixel in
+         the input grid along each dimension.
+
+         Note that \texttt{"} lbnd\_in\texttt{"}  and \texttt{"} ubnd\_in\texttt{"}  together define the shape
+         and size of the input grid, its extent along a particular
+         (j\texttt{'} th) dimension being ubnd\_in[j]-lbnd\_in[j]$+$1 (assuming the
+         index \texttt{"} j\texttt{"}  to be zero-based). They also define
+         the input grid\texttt{'} s coordinate system, each pixel having unit
+         extent along each dimension with integral coordinate values
+         at its centre.
+      }
+      \sstsubsection{
+         in
+      }{
+         Pointer to an array, with one element for each pixel in the
+         input grid, containing the input data to be resampled.  The
+         numerical type of this array should match the 1- or
+         2-character type code appended to the function name (e.g. if
+         you are using astResampleF, the type of each array element
+         should be \texttt{"} float\texttt{"} ).
+
+         The storage order of data within this array should be such
+         that the index of the first grid dimension varies most
+         rapidly and that of the final dimension least rapidly
+         (i.e. Fortran array indexing is used).
+      }
+      \sstsubsection{
+         in\_var
+      }{
+         An optional pointer to a second array with the same size and
+         type as the \texttt{"} in\texttt{"}  array. If given, this should contain a set
+         of non-negative values which represent estimates of the
+         statistical variance associated with each element of the \texttt{"} in\texttt{"}
+         array. If this array is supplied (together with the
+         corresponding \texttt{"} out\_var\texttt{"}  array), then estimates of the
+         variance of the resampled output data will be calculated.
+
+         If no input variance estimates are being provided, a NULL
+         pointer should be given.
+      }
+      \sstsubsection{
+         interp
+      }{
+         This parameter specifies the scheme to be used for sub-pixel
+         interpolation within the input grid. It may be used to select
+         from a set of pre-defined schemes by supplying one of the
+         values described in the \texttt{"} Sub-Pixel Interpolation Schemes\texttt{"}
+         section below.  If a value of zero is supplied, then the
+         default linear interpolation scheme is used (equivalent to
+         supplying the value AST\_\_LINEAR).
+
+         Alternatively, you may supply a value which indicates that
+         you will provide your own function to perform sub-pixel
+         interpolation by means of the \texttt{"} finterp \texttt{"}  parameter. Again, see
+         the \texttt{"} Sub-Pixel Interpolation Schemes\texttt{"}  section below for
+         details.
+      }
+      \sstsubsection{
+         finterp
+      }{
+         If the value given for the \texttt{"} interp\texttt{"}  parameter indicates that
+         you will provide your own function for sub-pixel
+         interpolation, then a pointer to that function should be
+         given here. For details of the interface which the function
+         should have (several are possible, depending on the value of
+         \texttt{"} interp\texttt{"} ), see the \texttt{"} Sub-Pixel Interpolation Schemes\texttt{"}  section
+         below.
+
+         If the \texttt{"} interp\texttt{"}  parameter has any other value, corresponding
+         to one of the pre-defined interpolation schemes, then this
+         function will not be used and you may supply a NULL pointer.
+      }
+      \sstsubsection{
+         params
+      }{
+         An optional pointer to an array of double which should contain
+         any additional parameter values required by the sub-pixel
+         interpolation scheme. If such parameters are required, this
+         will be noted in the \texttt{"} Sub-Pixel Interpolation Schemes\texttt{"}
+         section below (you may also use this array to pass values
+         to your own interpolation function).
+
+         If no additional parameters are required, this array is not
+         used and a NULL pointer may be given.
+      }
+      \sstsubsection{
+         flags
+      }{
+         The bitwise OR of a set of flag values which may be used to
+         provide additional control over the resampling operation. See
+         the \texttt{"} Control Flags\texttt{"}  section below for a description of the
+         options available.  If no flag values are to be set, a value
+         of zero should be given.
+      }
+      \sstsubsection{
+         tol
+      }{
+         The maximum tolerable geometrical distortion which may be
+         introduced as a result of approximating non-linear Mappings
+         by a set of piece-wise linear transformations. This should be
+         expressed as a displacement in pixels in the input grid\texttt{'} s
+         coordinate system.
+
+         If piece-wise linear approximation is not required, a value
+         of zero may be given. This will ensure that the Mapping is
+         used without any approximation, but may increase execution
+         time.
+      }
+      \sstsubsection{
+         maxpix
+      }{
+         A value which specifies an initial scale size (in pixels) for
+         the adaptive algorithm which approximates non-linear Mappings
+         with piece-wise linear transformations. Normally, this should
+         be a large value (larger than any dimension of the region of
+         the output grid being used). In this case, a first attempt to
+         approximate the Mapping by a linear transformation will be
+         made over the entire output region.
+
+         If a smaller value is used, the output region will first be
+         divided into sub-regions whose size does not exceed \texttt{"} maxpix\texttt{"}
+         pixels in any dimension. Only at this point will attempts at
+         approximation commence.
+
+         This value may occasionally be useful in preventing false
+         convergence of the adaptive algorithm in cases where the
+         Mapping appears approximately linear on large scales, but has
+         irregularities (e.g. holes) on smaller scales. A value of,
+         say, 50 to 100 pixels can also be employed as a safeguard in
+         general-purpose software, since the effect on performance is
+         minimal.
+
+         If too small a value is given, it will have the effect of
+         inhibiting linear approximation altogether (equivalent to
+         setting \texttt{"} tol\texttt{"}  to zero). Although this may degrade
+         performance, accurate results will still be obtained.
+      }
+      \sstsubsection{
+         badval
+      }{
+         This argument should have the same type as the elements of
+         the \texttt{"} in\texttt{"}  array. It specifies the value used to flag missing
+         data (bad pixels) in the input and output arrays.
+
+         If the AST\_\_USEBAD flag is set via the \texttt{"} flags\texttt{"}  parameter,
+         then this value is used to test for bad pixels in the \texttt{"} in\texttt{"}
+         (and \texttt{"} in\_var\texttt{"} ) array(s).
+
+         Unless the AST\_\_NOBAD flag is set via the \texttt{"} flags\texttt{"}  parameter,
+         this value is also used to flag any output
+         elements in the \texttt{"} out\texttt{"}  (and \texttt{"} out\_var\texttt{"} ) array(s) for which
+         resampled values could not be obtained (see the \texttt{"} Propagation
+         of Missing Data\texttt{"}  section below for details of the
+         circumstances under which this may occur). The astResample$<$X$>$
+         function return value indicates whether any such values have
+         been produced. If the AST\_\_NOBAD flag is set. then output array
+         elements for which no resampled value could be obtained are
+         left set to the value they had on entry to this function.
+      }
+      \sstsubsection{
+         ndim\_out
+      }{
+         The number of dimensions in the output grid. This should be
+         at least one. It need not necessarily be equal to the number
+         of dimensions in the input grid.
+      }
+      \sstsubsection{
+         lbnd\_out
+      }{
+         Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"}  elements,
+         containing the coordinates of the centre of the first pixel
+         in the output grid along each dimension.
+      }
+      \sstsubsection{
+         ubnd\_out
+      }{
+         Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"}  elements,
+         containing the coordinates of the centre of the last pixel in
+         the output grid along each dimension.
+
+         Note that \texttt{"} lbnd\_out\texttt{"}  and \texttt{"} ubnd\_out\texttt{"}  together define the
+         shape, size and coordinate system of the output grid in the
+         same way as \texttt{"} lbnd\_in\texttt{"}  and \texttt{"} ubnd\_in\texttt{"}  define the shape, size
+         and coordinate system of the input grid.
+      }
+      \sstsubsection{
+         lbnd
+      }{
+         Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"}  elements,
+         containing the coordinates of the first pixel in the region
+         of the output grid for which a resampled value is to be
+         calculated.
+      }
+      \sstsubsection{
+         ubnd
+      }{
+         Pointer to an array of integers, with \texttt{"} ndim\_out\texttt{"}  elements,
+         containing the coordinates of the last pixel in the region of
+         the output grid for which a resampled value is to be
+         calculated.
+
+         Note that \texttt{"} lbnd\texttt{"}  and \texttt{"} ubnd\texttt{"}  together define the shape and
+         position of a (hyper-)rectangular region of the output grid
+         for which resampled values should be produced. This region
+         should lie wholly within the extent of the output grid (as
+         defined by the \texttt{"} lbnd\_out\texttt{"}  and \texttt{"} ubnd\_out\texttt{"}  arrays). Regions of
+         the output grid lying outside this region will not be
+         modified.
+      }
+      \sstsubsection{
+         out
+      }{
+         Pointer to an array, with one element for each pixel in the
+         output grid, into which the resampled data values will be
+         returned. The numerical type of this array should match that
+         of the \texttt{"} in\texttt{"}  array, and the data storage order should be such
+         that the index of the first grid dimension varies most
+         rapidly and that of the final dimension least rapidly
+         (i.e. Fortran array indexing is used).
+      }
+      \sstsubsection{
+         out\_var
+      }{
+         An optional pointer to an array with the same type and size
+         as the \texttt{"} out\texttt{"}  array. If given, this array will be used to
+         return variance estimates for the resampled data values. This
+         array will only be used if the \texttt{"} in\_var\texttt{"}  array has also been
+         supplied.
+
+         The output variance values will be calculated on the
+         assumption that errors on the input data values are
+         statistically independent and that their variance estimates
+         may simply be summed (with appropriate weighting factors)
+         when several input pixels contribute to an output data
+         value. If this assumption is not valid, then the output error
+         estimates may be biased. In addition, note that the
+         statistical errors on neighbouring output data values (as
+         well as the estimates of those errors) may often be
+         correlated, even if the above assumption about the input data
+         is correct, because of the sub-pixel interpolation schemes
+         employed.
+
+         If no output variance estimates are required, a NULL pointer
+         should be given.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astResample$<$X$>$()
+      }{
+         The number of output pixels for which no valid resampled value
+         could be obtained. Thus, in the absence of any error, a returned
+         value of zero indicates that all the required output pixels
+         received valid resampled data values (and variances). See the
+         \texttt{"} badval\texttt{"}  and \texttt{"} flags\texttt{"}  parameters.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A value of zero will be returned if this function is invoked
+         with the global error status set, or if it should fail for any
+         reason.
+      }
+   }
+   \sstdiytopic{
+      Data Type Codes
+   }{
+      To select the appropriate resampling function, you should
+      replace $<$X$>$ in the generic function name astResample$<$X$>$ with a
+      1- or 2-character data type code, so as to match the numerical
+      type $<$Xtype$>$ of the data you are processing, as follows:
+      \sstitemlist{
+
+         \sstitem
+          D: double
+
+         \sstitem
+          F: float
+
+         \sstitem
+          L: long int (may be 32 or 64 bit)
+
+         \sstitem
+          K: 64 bit int
+
+         \sstitem
+          UL: unsigned long int (may be 32 or 64 bit)
+
+         \sstitem
+          UK: unsigned 64 bit int
+
+         \sstitem
+          I: int
+
+         \sstitem
+          UI: unsigned int
+
+         \sstitem
+          S: short int
+
+         \sstitem
+          US: unsigned short int
+
+         \sstitem
+          B: byte (signed char)
+
+         \sstitem
+          UB: unsigned byte (unsigned char)
+
+      }
+      For example, astResampleD would be used to process \texttt{"} double\texttt{"}
+      data, while astResampleS would be used to process \texttt{"} short int\texttt{"}
+      data, etc.
+   }
+   \sstdiytopic{
+      Sub-Pixel Interpolation Schemes
+   }{
+      There is no such thing as a perfect sub-pixel interpolation
+      scheme and, in practice, all resampling will result in some
+      degradation of gridded data.  A range of schemes is therefore
+      provided, from which you can choose the one which best suits
+      your needs.
+
+      In general, a balance must be struck between schemes which tend
+      to degrade sharp features in the data by smoothing them, and
+      those which attempt to preserve sharp features. The latter will
+      often tend to introduce unwanted oscillations, typically visible
+      as \texttt{"} ringing\texttt{"}  around sharp features and edges, especially if the
+      data are under-sampled (i.e. if the sharpest features are less
+      than about two pixels across). In practice, a good interpolation
+      scheme is likely to be a compromise and may exhibit some aspects
+      of both these features.
+
+      For under-sampled data, some interpolation schemes may appear to
+      preserve data resolution because they transform single input
+      pixels into single output pixels, rather than spreading their
+      data between several output pixels. While this may look
+      better cosmetically, it can result in a geometrical shift of
+      sharp features in the data. You should beware of this if you
+      plan to use such features (e.g.) for image alignment.
+
+      The following are two easy-to-use sub-pixel interpolation
+      schemes which are generally applicable. They are selected by
+      supplying the appropriate value (defined in the \texttt{"} ast.h\texttt{"}  header
+      file) via the \texttt{"} interp\texttt{"}  parameter. In these cases, the \texttt{"} finterp\texttt{"}
+      and \texttt{"} params\texttt{"}  parameters are not used:
+
+      \sstitemlist{
+
+         \sstitem
+          AST\_\_NEAREST: This is the simplest possible scheme, in which
+         the value of the input pixel with the nearest centre to the
+         interpolation point is used. This is very quick to execute and
+         will preserve single-pixel features in the data, but may
+         displace them by up to half their width along each dimension. It
+         often gives a good cosmetic result, so is useful for quick-look
+         processing, but is unsuitable if accurate geometrical
+         transformation is required.
+
+         \sstitem
+          AST\_\_LINEAR: This is the default scheme, which uses linear
+         interpolation between the nearest neighbouring pixels in the
+         input grid (there are two neighbours in one dimension, four
+         neighbours in two dimensions, eight in three dimensions,
+         etc.). It is superior to the nearest-pixel scheme (above) in not
+         displacing features in the data, yet it still executes fairly
+         rapidly. It is generally a safe choice if you do not have any
+         particular reason to favour another scheme, since it cannot
+         introduce oscillations. However, it does introduce some spatial
+         smoothing which varies according to the distance of the
+         interpolation point from the neighbouring pixels. This can
+         degrade the shape of sharp features in the data in a
+         position-dependent way. It may also show in the output variance
+         grid (if used) as a pattern of stripes or fringes.
+
+      }
+      An alternative set of interpolation schemes is based on forming
+      the interpolated value from the weighted sum of a set of
+      surrounding pixel values (not necessarily just the nearest
+      neighbours). This approach has its origins in the theory of
+      digital filtering, in which interpolated values are obtained by
+      conceptually passing the sampled data (represented by a grid of
+      delta functions) through a linear filter which implements a
+      convolution. Because the convolution kernel is continuous, the
+      convolution yields a continuous function which may then be
+      evaluated at fractional pixel positions. The (possibly
+      multi-dimensional) kernel is usually regarded as \texttt{"} separable\texttt{"}  and
+      formed from the product of a set of identical 1-dimensional
+      kernel functions, evaluated along each dimension. Different
+      interpolation schemes are then distinguished by the choice of
+      this 1-dimensional interpolation kernel. The number of
+      surrounding pixels which contribute to the result may also be
+      varied.
+
+      From a practical standpoint, it is useful to divide the weighted
+      sum of pixel values by the sum of the weights when determining
+      the interpolated value.  Strictly, this means that a true
+      convolution is no longer being performed. However, the
+      distinction is rarely important in practice because (for
+      slightly subtle reasons) the sum of weights is always
+      approximately constant for good interpolation kernels. The
+      advantage of this technique, which is used here, is that it can
+      easily accommodate missing data and tends to minimise unwanted
+      oscillations at the edges of the data grid.
+
+      In the following schemes, which are based on a 1-dimensional
+      interpolation kernel, the first element of the \texttt{"} params\texttt{"}  array
+      should be used to specify how many pixels are to contribute to the
+      interpolated result on either side of the interpolation point in
+      each dimension (the nearest integer value is used). Execution time
+      increases rapidly with this number. Typically, a value of 2 is
+      appropriate and the minimum value used will be 1 (i.e. two pixels
+      altogether, one on either side of the interpolation point).
+      A value of zero or less may be given for \texttt{"} params[0]\texttt{"}
+      to indicate that a suitable number of pixels should be calculated
+      automatically.
+
+      In each of these cases, the \texttt{"} finterp\texttt{"}  parameter is not used:
+
+      \sstitemlist{
+
+         \sstitem
+          AST\_\_GAUSS: This scheme uses a kernel of the form exp(-k$*$x$*$x), with
+         k a positive constant. The full-width at half-maximum (FWHM) is
+         given by
+         \texttt{"} params[1]\texttt{"}
+         to zero will select the number of contributing pixels so as to utilise
+         the width of the kernel out to where the envelope declines to 1\% of its
+         maximum value). This kernel suppresses noise at the expense of
+         smoothing the output array.
+
+         \sstitem
+          AST\_\_SINC: This scheme uses a sinc(pi$*$x) kernel, where x is the
+         pixel offset from the interpolation point and sinc(z)=sin(z)/z. This
+         sometimes features as an \texttt{"} optimal\texttt{"}  interpolation kernel in books on
+         image processing. Its supposed optimality depends on the assumption
+         that the data are band-limited (i.e. have no spatial frequencies above
+         a certain value) and are adequately sampled. In practice, astronomical
+         data rarely meet these requirements. In addition, high spatial
+         frequencies are often present due (e.g.) to image defects and cosmic
+         ray events. Consequently, substantial ringing can be experienced with
+         this kernel. The kernel also decays slowly with distance, so that
+         many surrounding pixels are required, leading to poor performance.
+         Abruptly truncating it, by using only a few neighbouring pixels,
+         improves performance and may reduce ringing (if \texttt{"} params[0]\texttt{"}  is set to
+         zero, then only two pixels will be used on either side). However, a
+         more gradual truncation, as implemented by other kernels, is generally
+         to be preferred. This kernel is provided mainly so that you can
+         convince yourself not to use it!
+
+         \sstitem
+          AST\_\_SINCSINC: This scheme uses an improved kernel, of the form
+         sinc(pi$*$x).sinc(k$*$pi$*$x), with k a constant, out to the point where
+         sinc(k$*$pi$*$x) goes to zero, and zero beyond. The second sinc() factor
+         provides an \texttt{"} envelope\texttt{"}  which gradually rolls off the normal sinc(pi$*$x)
+         kernel at large offsets. The width of this envelope is specified by
+         giving the number of pixels offset at which it goes to zero by means
+         of the \texttt{"} params[1]\texttt{"}  value, which should be at least 1.0 (in addition,
+         setting \texttt{"} params[0]\texttt{"}  to zero will select the number of contributing
+         pixels so as to utilise the full width of the kernel, out to where it
+         reaches zero). The case given by \texttt{"} params[0]=2, params[1]=2\texttt{"}  is typically
+         a good choice and is sometimes known as the Lanczos kernel. This is a
+         valuable general-purpose interpolation scheme, intermediate in its
+         visual effect on images between the AST\_\_NEAREST and AST\_\_LINEAR
+         schemes. Although the kernel is slightly oscillatory, ringing is
+         adequately suppressed if the data are well sampled.
+
+         \sstitem
+          AST\_\_SINCCOS: This scheme uses a kernel of the form
+         sinc(pi$*$x).cos(k$*$pi$*$x), with k a constant, out to the point where
+         cos(k$*$pi$*$x) goes to zero, and zero beyond. As above, the cos() factor
+         provides an envelope which gradually rolls off the sinc() kernel
+         at large offsets. The width of this envelope is specified by giving
+         the number of pixels offset at which it goes to zero by means
+         of the \texttt{"} params[1]\texttt{"}  value, which should be at least 1.0 (in addition,
+         setting \texttt{"} params[0]\texttt{"}  to zero will select the number of contributing
+         pixels so as to utilise the full width of the kernel, out to where it
+         reaches zero). This scheme gives similar results to the
+         AST\_\_SINCSINC scheme, which it resembles.
+
+         \sstitem
+          AST\_\_SINCGAUSS: This scheme uses a kernel of the form
+         sinc(pi$*$x).exp(-k$*$x$*$x), with k a positive constant. Here, the sinc()
+         kernel is rolled off using a Gaussian envelope which is specified by
+         giving its full-width at half-maximum (FWHM) by means of the \texttt{"} params[1]\texttt{"}
+         value, which should be at least 0.1 (in addition, setting \texttt{"} params[0]\texttt{"}
+         to zero will select the number of contributing pixels so as to utilise
+         the width of the kernel out to where the envelope declines to 1\% of its
+         maximum value). On astronomical images and spectra, good results are
+         often obtained by approximately matching the FWHM of the
+         envelope function, given by \texttt{"} params[1]\texttt{"} , to the point spread function
+         of the input data. However, there does not seem to be any theoretical
+         reason for this.
+
+         \sstitem
+          AST\_\_SOMB: This scheme uses a somb(pi$*$x) kernel (a \texttt{"} sombrero\texttt{"}
+         function), where x is the pixel offset from the interpolation point
+         and somb(z)=2$*$J1(z)/z  (J1 is a Bessel function of the first kind of
+         order 1). It is similar to the AST\_\_SINC kernel, and has the same
+         parameter usage.
+
+         \sstitem
+          AST\_\_SOMBCOS: This scheme uses a kernel of the form
+         somb(pi$*$x).cos(k$*$pi$*$x), with k a constant, out to the point where
+         cos(k$*$pi$*$x) goes to zero, and zero beyond. It is similar to the
+         AST\_\_SINCCOS kernel, and has the same parameter usage.
+
+      }
+      In addition, the following schemes are provided which are not based
+      on a 1-dimensional kernel:
+
+      \sstitemlist{
+
+         \sstitem
+          AST\_\_BLOCKAVE: This scheme simply takes an average of all the
+         pixels on the input grid in a cube centred on the interpolation
+         point.  The number of pixels in the cube is determined by the
+         value of the first element of the \texttt{"} params\texttt{"}  array, which gives
+         the number of pixels in each dimension on either side of the
+         central point.  Hence a block of (2 $*$ params[0])$\wedge$ndim\_in
+         pixels in the input grid will be examined to determine the
+         value of the output pixel.  If the variance is not being used
+         (var\_in or var\_out = NULL) then all valid pixels in this cube
+         will be averaged in to the result with equal weight.
+         If variances are being used, then each input pixel will be
+         weighted proportionally to the reciprocal of its variance; any
+         pixel without a valid variance will be discarded.  This scheme
+         is suitable where the output grid is much coarser than the
+         input grid; if the ratio of pixel sizes is R then a suitable
+         value of params[0] may be R/2.
+
+      }
+      Finally, supplying the following values for \texttt{"} interp\texttt{"}  allows you
+      to implement your own sub-pixel interpolation scheme by means of
+      your own function. You should supply a pointer to this function
+      via the \texttt{"} finterp\texttt{"}  parameter:
+
+      \sstitemlist{
+
+         \sstitem
+          AST\_\_UKERN1: In this scheme, you supply a function to evaluate
+         your own 1-dimensional interpolation kernel, which is then used
+         to perform sub-pixel interpolation (as described above). The
+         function you supply should have the same interface as the
+         fictitious \htmlref{astUkern1}{astUkern1} function (q.v.).  In addition, a value
+         should be given via \texttt{"} params[0]\texttt{"}  to specify the number of
+         neighbouring pixels which are to contribute to each interpolated
+         value (in the same way as for the pre-defined interpolation
+         schemes described above). Other elements of the \texttt{"} params\texttt{"}  array
+         are available to pass values to your interpolation function.
+
+         \sstitem
+          AST\_\_UINTERP: This is a completely general scheme, in which
+         your interpolation function has access to all of the input
+         data. This allows you to implement any interpolation algorithm
+         you choose, which could (for example) be non-linear, or
+         adaptive. In this case, the astResample$<$X$>$ functions play no
+         role in the sub-pixel interpolation process and simply handle
+         the geometrical transformation of coordinates and other
+         housekeeping. The function you supply should have the same
+         interface as the fictitious \htmlref{astUinterp}{astUinterp} function (q.v.). In this
+         case, the \texttt{"} params\texttt{"}  parameter is not used by astResample$<$X$>$, but
+         is available to pass values to your interpolation function.
+      }
+   }
+   \sstdiytopic{
+      Control Flags
+   }{
+      The following flags are defined in the \texttt{"} ast.h\texttt{"}  header file and
+      may be used to provide additional control over the resampling
+      process. Having selected a set of flags, you should supply the
+      bitwise OR of their values via the \texttt{"} flags\texttt{"}  parameter:
+
+      \sstitemlist{
+
+         \sstitem
+          AST\_\_NOBAD: Indicates that any output array elements for which no
+         resampled value could be obtained should be left set to the value
+         they had on entry to this function. If this flag is not supplied,
+         such output array elements are set to the value supplied for
+         parameter \texttt{"} badval\texttt{"} . Note, this flag cannot be used in conjunction
+         with the AST\_\_CONSERVEFLUX flag (an error will be reported if both
+         flags are specified).
+
+         \sstitem
+          AST\_\_URESAMP1, 2, 3 \& 4: A set of four flags which are
+         reserved for your own use. They may be used to pass private
+         information to any sub-pixel interpolation function which you
+         implement yourself. They are ignored by all the pre-defined
+         interpolation schemes.
+
+         \sstitem
+          AST\_\_USEBAD: Indicates that there may be bad pixels in the
+         input array(s) which must be recognised by comparing with the
+         value given for \texttt{"} badval\texttt{"}  and propagated to the output array(s).
+         If this flag is not set, all input values are treated literally
+         and the \texttt{"} badval\texttt{"}  value is only used for flagging output array
+         values.
+
+         \sstitem
+          AST\_\_CONSERVEFLUX: Indicates that the output pixel values should
+         be scaled in such a way as to preserve (approximately) the total data
+         value in a feature on the sky. Without this flag, each output pixel
+         value represents an instantaneous sample of the input data values at
+         the corresponding input position. This is appropriate if the input
+         data represents the spatial density of some quantity (e.g. surface
+         brightness in Janskys per square arc-second) because the output
+         pixel values will have the same normalisation and units as the
+         input pixel values. However, if the input data values represent
+         flux (or some other physical quantity) per pixel, then the
+         AST\_\_CONSERVEFLUX flag could be used. This causes each output
+         pixel value to be scaled by the ratio of the output pixel size to
+         the input pixel size.
+
+      }
+      This flag can only be used if the Mapping is successfully approximated
+      by one or more linear transformations. Thus an error will be reported
+      if it used when the
+      \texttt{"} tol\texttt{"}  parameter
+      is set to zero (which stops the use of linear approximations), or
+      if the Mapping is too non-linear to be approximated by a piece-wise
+      linear transformation. The ratio of output to input pixel size is
+      evaluated once for each panel of the piece-wise linear approximation to
+      the Mapping, and is assumed to be constant for all output pixels in the
+      panel. The scaling factors for adjacent panels will in general
+      differ slightly, and so the joints between panels may be visible when
+      viewing the output image at high contrast. If this is a problem,
+      reduce the value of the
+      \texttt{"} tol\texttt{"}  parameter
+      until the difference between adjacent panels is sufficiently small
+      to be insignificant.
+
+      Note, this flag cannot be used in conjunction with the AST\_\_NOBAD
+      flag (an error will be reported if both flags are specified).
+   }
+   \sstdiytopic{
+      Propagation of Missing Data
+   }{
+      Unless the AST\_\_NOBAD flag is specified, instances of missing data
+      (bad pixels) in the output grid are
+      identified by occurrences of the \texttt{"} badval\texttt{"}  value in the \texttt{"} out\texttt{"}
+      array. These may be produced if any of the following happen:
+
+      \sstitemlist{
+
+         \sstitem
+          The input position (the transformed position of the output
+         pixel\texttt{'} s centre) lies outside the boundary of the grid of input
+         pixels.
+
+         \sstitem
+          The input position lies inside the boundary of a bad input
+         pixel. In this context, an input pixel is considered bad if its
+         data value is equal to \texttt{"} badval\texttt{"}  and the AST\_\_USEBAD flag is
+         set via the \texttt{"} flags\texttt{"}  parameter.
+         (Positions which have half-integral coordinate values, and
+         therefore lie on a pixel boundary, are regarded as lying within
+         the pixel with the larger, i.e. more positive, index.)
+
+         \sstitem
+          The set of neighbouring input pixels (excluding those which
+         are bad) is unsuitable for calculating an interpolated
+         value. Whether this is true may depend on the sub-pixel
+         interpolation scheme in use.
+
+         \sstitem
+          The interpolated value lies outside the range which can be
+         represented using the data type of the \texttt{"} out\texttt{"}  array.
+
+      }
+      In addition, associated output variance estimates (if
+      calculated) may be declared bad and flagged with the \texttt{"} badval\texttt{"}
+      value in the \texttt{"} out\_var\texttt{"}  array under any of the following
+      circumstances:
+
+      \sstitemlist{
+
+         \sstitem
+          The associated resampled data value (in the \texttt{"} out\texttt{"}  array) is bad.
+
+         \sstitem
+          The set of neighbouring input pixels which contributed to the
+         output data value do not all have valid variance estimates
+         associated with them. In this context, an input variance
+         estimate may be regarded as bad either because it has the value
+         \texttt{"} badval\texttt{"}  (and the AST\_\_USEBAD flag is set), or because it is
+         negative.
+
+         \sstitem
+          The set of neighbouring input pixels for which valid variance
+         values are available is unsuitable for calculating an overall
+         variance value. Whether this is true may depend on the sub-pixel
+         interpolation scheme in use.
+
+         \sstitem
+          The variance value lies outside the range which can be
+         represented using the data type of the \texttt{"} out\_var\texttt{"}  array.
+
+      }
+      If the AST\_\_NOBAD flag is specified via
+      parameter \texttt{"} flags\texttt{"} ,
+      then output array elements that would otherwise be set to
+      \texttt{"} badval\texttt{"}
+      are instead left holding the value they had on entry to this
+      function. The number of such array elements is returned as
+      the function value.
+   }
+}
+\sstroutine{
+   astResolve
+}{
+   Resolve a vector into two orthogonal components
+}{
+   \sstdescription{
+      This function resolves a vector into two perpendicular components.
+      The vector from point 1 to point 2 is used as the basis vector.
+      The vector from point 1 to point 3 is resolved into components
+      parallel and perpendicular to this basis vector. The lengths of the
+      two components are returned, together with the position of closest
+      aproach of the basis vector to point 3.
+   }
+   \sstsynopsis{
+      void astResolve( AstFrame $*$this, const double point1[],
+                       const double point2[], const double point3[],
+                       double point4[], double $*$d1, double $*$d2 );
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the \htmlref{Frame}{Frame}.
+      }
+      \sstsubsection{
+         point1
+      }{
+         An array of double, with one element for each Frame axis
+         (\htmlref{Naxes}{Naxes} attribute). This marks the start of the basis vector,
+         and of the vector to be resolved.
+      }
+      \sstsubsection{
+         point2
+      }{
+         An array of double, with one element for each Frame axis
+         (Naxes attribute). This marks the end of the basis vector.
+      }
+      \sstsubsection{
+         point3
+      }{
+         An array of double, with one element for each Frame axis
+         (Naxes attribute). This marks the end of the vector to be
+         resolved.
+      }
+      \sstsubsection{
+         point4
+      }{
+         An array of double, with one element for each Frame axis
+         in which the coordinates of the point of closest approach of the
+         basis vector to point 3 will be returned.
+      }
+      \sstsubsection{
+         d1
+      }{
+         The address of a location at which to return the distance from
+         point 1 to point 4 (that is, the length of the component parallel
+         to the basis vector). Positive values are in the same sense as
+         movement from point 1 to point 2.
+      }
+      \sstsubsection{
+         d2
+      }{
+         The address of a location at which to return the distance from
+         point 4 to point 3 (that is, the length of the component
+         perpendicular to the basis vector). The value is always positive.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Each vector used in this function is the path of
+         shortest distance between two points, as defined by the
+         \htmlref{astDistance}{astDistance} function.
+
+         \sstitem
+          This function will return \texttt{"} bad\texttt{"}  coordinate values (AST\_\_BAD)
+         if any of the input coordinates has this value, or if the required
+         output values are undefined.
+      }
+   }
+}
+\sstroutine{
+   astRetainFits
+}{
+   Indicate that the current card in a FitsChan should be retained
+}{
+   \sstdescription{
+      This function
+      stores a flag with the current card in the \htmlref{FitsChan}{FitsChan} indicating that
+      the card should not be removed from the FitsChan when an \htmlref{Object}{Object} is
+      read from the FitsChan using
+      \htmlref{astRead}{astRead}.
+
+      Cards that have not been flagged in this way are removed when a
+      read operation completes succesfully, but only if the card was used
+      in the process of creating the returned AST Object. Any cards that
+      are irrelevant to the creation of the AST Object are retained whether
+      or not they are flagged.
+   }
+   \sstsynopsis{
+      void astRetainFits( AstFitsChan $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FitsChan.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This function returns without action if the FitsChan is
+         initially positioned at the \texttt{"} end-of-file\texttt{"}  (i.e. if the \htmlref{Card}{Card}
+         attribute exceeds the number of cards in the FitsChan).
+
+         \sstitem
+          The current card is not changed by this function.
+      }
+   }
+}
+\sstroutine{
+   astSame
+}{
+   Test if two AST pointers refer to the same Object
+}{
+   \sstdescription{
+      This function returns a boolean result (0 or 1) to indicate
+      whether two pointers refer to the same \htmlref{Object}{Object}.
+   }
+   \sstsynopsis{
+      int astSame( AstObject $*$this,  AstObject $*$that )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the first Object.
+      }
+      \sstsubsection{
+         that
+      }{
+         Pointer to the second Object.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         This function applies to all Objects.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astSame()
+      }{
+         One if the two pointers refer to the same Object, otherwise zero.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Two independent Objects that happen to be identical are not
+         considered to be the same Object by this function.
+
+         \sstitem
+          A value of zero will be returned if this function is invoked
+         with the AST error status set, or if it should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astSelectorMap
+}{
+   Create a SelectorMap
+}{
+   \sstdescription{
+      This function creates a new \htmlref{SelectorMap}{SelectorMap} and optionally initialises
+      its attributes.
+
+      A SelectorMap is a \htmlref{Mapping}{Mapping} that identifies which \htmlref{Region}{Region} contains
+      a given input position.
+
+      A SelectorMap encapsulates a number of Regions that all have the same
+      number of axes and represent the same coordinate \htmlref{Frame}{Frame}. The number of
+      inputs (\htmlref{Nin}{Nin} attribute) of the SelectorMap equals the number of axes
+      spanned by one of the encapsulated Region. All SelectorMaps have only
+      a single output. SelectorMaps do not define an inverse transformation.
+
+      For each input position, the forward transformation of a SelectorMap
+      searches through the encapsulated Regions (in the order supplied when
+      the SelectorMap was created) until a Region is found which contains
+      the input position. The index associated with this Region is
+      returned as the SelectorMap output value (the index value is the
+      position of the Region within the list of Regions supplied when the
+      SelectorMap was created, starting at 1 for the first Region). If an
+      input position is not contained within any Region, a value of zero is
+      returned by the forward transformation.
+
+      If a compound Mapping contains a SelectorMap in series with its own
+      inverse, the combination of the two adjacent SelectorMaps will be
+      replaced by a \htmlref{UnitMap}{UnitMap} when the compound Mapping is simplified using
+      \htmlref{astSimplify}{astSimplify}.
+
+      In practice, SelectorMaps are often used in conjunction with SwitchMaps.
+   }
+   \sstsynopsis{
+      AstSelectorMap $*$astSelectorMap( int nreg, AstRegion $*$regs[],
+                                      double badval, const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         nreg
+      }{
+         The number of supplied Regions.
+      }
+      \sstsubsection{
+         regs
+      }{
+         An array of pointers to the Regions. All the supplied Regions must
+         relate to the same coordinate Frame. The number of axes in this
+         coordinate Frame defines the number of inputs for the SelectorMap.
+      }
+      \sstsubsection{
+         badval
+      }{
+         The value to be returned by the forward transformation of the
+         SelectorMap for any input positions that have a bad (AST\_\_BAD)
+         value on any axis.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new SelectorMap. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astSelectorMap()
+      }{
+         A pointer to the new SelectorMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Deep copies are taken of the supplied Regions. This means that
+         any subsequent changes made to the component Regions using the
+         supplied pointers will have no effect on the SelectorMap.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astSet
+}{
+   Set attribute values for an Object
+}{
+   \sstdescription{
+      This function assigns a set of attribute values to an \htmlref{Object}{Object},
+      over-riding any previous values. The attributes and their new
+      values are specified via a character string, which should
+      contain a comma-separated list of the form:
+
+         \texttt{"} attribute\_1 = value\_1, attribute\_2 = value\_2, ... \texttt{"}
+
+      where \texttt{"} attribute\_n\texttt{"}  specifies an attribute name, and the value
+      to the right of each \texttt{"} =\texttt{"}  sign should be a suitable textual
+      representation of the value to be assigned. This value will be
+      interpreted according to the attribute\texttt{'} s data type.
+
+      The string supplied may also contain \texttt{"} printf\texttt{"} -style format
+      specifiers, identified by \texttt{"} \%\texttt{"}  signs in the usual way. If
+      present, these will be substituted by values supplied as
+      additional optional arguments (using the normal \texttt{"} printf\texttt{"}  rules)
+      before the string is used.
+   }
+   \sstsynopsis{
+      void astSet( AstObject $*$this, const char $*$settings, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Object.
+      }
+      \sstsubsection{
+         settings
+      }{
+         Pointer to a null-terminated character string containing a
+         comma-separated list of attribute settings in the form described
+         above.
+      }
+      \sstsubsection{
+         ...
+      }{
+         Optional additional arguments which supply values to be
+         substituted for any \texttt{"} printf\texttt{"} -style format specifiers that
+         appear in the \texttt{"} settings\texttt{"}  string.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         This function applies to all Objects.
+      }
+   }
+   \sstexamples{
+      \sstexamplesubsection{
+         astSet( map, \texttt{"} \htmlref{Report}{Report} = 1, \htmlref{Zoom}{Zoom} = 25.0\texttt{"}  );
+      }{
+         Sets the Report attribute for Object \texttt{"} map\texttt{"}  to the value 1 and
+         the Zoom attribute to 25.0.
+      }
+      \sstexamplesubsection{
+         astSet( frame, \texttt{"} Label( \%d ) =Offset along axis \%d\texttt{"} , axis, axis );
+      }{
+         Sets the \htmlref{Label(axis)}{Label(axis)} attribute for Object \texttt{"} frame\texttt{"}  to a
+         suitable string, where the axis number is obtained from
+         \texttt{"} axis\texttt{"} , a variable of type int.
+      }
+      \sstexamplesubsection{
+         astSet( frame, \texttt{"} \htmlref{Title}{Title} =\%s\texttt{"} , mystring );
+      }{
+         Sets the Title attribute for Object \texttt{"} frame\texttt{"}  to the contents of
+         the string \texttt{"} mystring\texttt{"} .
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Attribute names are not case sensitive and may be surrounded
+         by white space.
+
+         \sstitem
+          White space may also surround attribute values, where it will
+         generally be ignored (except for string-valued attributes where
+         it is significant and forms part of the value to be assigned).
+
+         \sstitem
+          To include a literal comma in the value assigned to an attribute,
+         the whole attribute value should be enclosed in quotation markes.
+         Alternatively, you can use \texttt{"} \%s\texttt{"}  format and supply the value as a
+         separate additional argument to astSet (or use the astSetC
+         function instead).
+
+         \sstitem
+          The same procedure may be adopted if \texttt{"} \%\texttt{"}  signs are to be included
+         and are not to be interpreted as format specifiers (alternatively,
+         the \texttt{"} printf\texttt{"}  convention of writing \texttt{"} \%\%\texttt{"}  may be used).
+
+         \sstitem
+          An error will result if an attempt is made to set a value for
+         a read-only attribute.
+      }
+   }
+}
+\sstroutine{
+   astSet$<$X$>$
+}{
+   Set an attribute value for an Object
+}{
+   \sstdescription{
+      This is a family of functions which set a specified attribute
+      value for an \htmlref{Object}{Object} using one of several different data
+      types. The type is selected by replacing $<$X$>$ in the function name
+      by C, D, F, I or L, to supply a value in const char$*$ (i.e. string),
+      double, float, int, or long format, respectively.
+
+      If possible, the value you supply is converted to the type of
+      the attribute. If conversion is not possible, an error will
+      result.
+   }
+   \sstsynopsis{
+      void astSet$<$X$>$( AstObject $*$this, const char $*$attrib, $<$X$>$type value )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Object.
+      }
+      \sstsubsection{
+         attrib
+      }{
+         Pointer to a null-terminated character string containing the
+         name of the attribute whose value is to be set.
+      }
+      \sstsubsection{
+         value
+      }{
+         The value to be set for the attribute, in the data type corresponding
+         to $<$X$>$ (or, in the case of astSetC, a pointer to a null-terminated
+         character string containing this value).
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         These functions apply to all Objects.
+      }
+   }
+   \sstexamples{
+      \sstexamplesubsection{
+         astSetI( frame, \texttt{"} Preserve\texttt{"} , 1 );
+      }{
+         Sets the Preserve attribute value for Object \texttt{"} frame\texttt{"}  to 1.
+      }
+      \sstexamplesubsection{
+         astSetC( plot, \texttt{"} Format(1)\texttt{"} , \texttt{"} \%.2g\texttt{"}  );
+      }{
+         Sets the Format(1) attribute value for Object \texttt{"} plot\texttt{"}  to the
+         character string \texttt{"} \%.2g\texttt{"} .
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Attribute names are not case sensitive and may be surrounded
+         by white space.
+
+         \sstitem
+          An error will result if an attempt is made to set a value for
+         a read-only attribute.
+      }
+   }
+}
+\sstroutine{
+   astSetActiveUnit
+}{
+   Specify how the Unit attribute should be used
+}{
+   \sstdescription{
+      This function
+      sets the current value of the ActiveUnit flag for a \htmlref{Frame}{Frame}, which
+      controls how the Frame behaves when it is used (by
+      \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert})
+      to match another Frame. If the ActiveUnit flag is set in both
+      template and target Frames then the returned \htmlref{Mapping}{Mapping} takes into account
+      any differences in axis units. The default value for simple Frames is
+      zero, which preserves the behaviour of versions of AST prior to
+      version 2.0.
+
+      If the ActiveUnit flag of either Frame is
+      zero,
+      then the Mapping will ignore any difference in the Unit attributes of
+      corresponding template and target axes. In this mode, the Unit
+      attributes are purely descriptive commentary for the benefit of
+      human readers and do not influence the Mappings between Frames.
+      This is the behaviour which all Frames had in older version of AST,
+      prior to the introduction of this attribute.
+
+      If the ActiveUnit flag of both Frames is
+      non-zero,
+      then the Mapping from template to target will take account of any
+      difference in the axis Unit attributes, where-ever possible. For
+      instance, if corresponding target and template axes have Unit strings of
+      \texttt{"} km\texttt{"}  and \texttt{"} m\texttt{"} , then the \htmlref{FrameSet}{FrameSet} class will use a \htmlref{ZoomMap}{ZoomMap} to connect
+      them which introduces a scaling of 1000. If no Mapping can be found
+      between the corresponding units string, then an error is reported.
+      In this mode, it is assumed that values of the Unit attribute conform
+      to the syntax for units strings described in the FITS WCS Paper I
+      \texttt{"} Representations of world coordinates in FITS\texttt{"}  (Greisen \& Calabretta).
+      Particularly, any of the named unit symbols, functions, operators or
+      standard multiplier prefixes listed within that paper can be used within
+      a units string. A units string may contain symbols for unit which are
+      not listed in the FITS paper, but transformation to any other units
+      will then not be possible (except to units which depend only on the
+      same unknown units - thus \texttt{"} flops\texttt{"}  can be transformed to \texttt{"} Mflops\texttt{"}
+      even though \texttt{"} flops\texttt{"}  is not a standard FITS unit symbol).
+
+      A range of common non-standard variations of unit names and multiplier
+      prefixes are also allowed, such as adding an \texttt{"} s\texttt{"}  to the end of Angstrom,
+      using a lower case \texttt{"} a\texttt{"}  at the start of \texttt{"} angstrom\texttt{"} , \texttt{"} micron\texttt{"}  instead of
+      \texttt{"} um\texttt{"} , \texttt{"} sec\texttt{"}  instead of \texttt{"} s\texttt{"} , etc.
+
+      If the ActiveUnit flag is non-zero, setting a new Unit value for an
+      axis may also change its Label and Symbol attributes. For instance, if
+      an axis has Unit \texttt{"} Hz\texttt{"}  and Label \texttt{"} frequency\texttt{"} , then changing its Unit to
+      \texttt{"} log(Hz)\texttt{"}  will change its Label to \texttt{"} log( frequency )\texttt{"} . In addition,
+      the \htmlref{Axis}{Axis} Format attribute will be cleared when-ever a new value
+      is assigned to the Unit attribute.
+
+      Note, if a non-zero value is set for the ActiveUnit flag, then changing a
+      Unit value for the current Frame within a FrameSet will result in the
+      Frame being re-mapped (that is, the Mappings which define the
+      relationships between Frames within the FrameSet will be modified to
+      take into account the change in Units).
+   }
+   \sstsynopsis{
+      void astSetActiveUnit( AstFrame $*$this, int value )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Frame.
+      }
+      \sstsubsection{
+         value
+      }{
+         The new value to use.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{SkyFrame}{SkyFrame}
+      }{
+         The ActiveUnit flag for a SkyFrame is always 0 (any value
+         supplied using this function is ignored).
+      }
+      \sstsubsection{
+         \htmlref{SpecFrame}{SpecFrame}
+      }{
+         The ActiveUnit flag for a SpecFrame is always 1 (any value
+         supplied using this function is ignored).
+      }
+      \sstsubsection{
+         \htmlref{FluxFrame}{FluxFrame}
+      }{
+         The ActiveUnit flag for a FluxFrame is always 1 (any value
+         supplied using this function is ignored).
+      }
+      \sstsubsection{
+         \htmlref{CmpFrame}{CmpFrame}
+      }{
+         The default ActiveUnit flag for a CmpFrame is 1 if both of the
+         component Frames are using active units, and zero otherwise. When
+         a new value is set for the ActiveUnit flag, the flag value
+         is propagated to the component Frames. This change will be
+         reflected through all references to the component Frames, not
+         just those encapsulated within the CmpFrame.
+      }
+      \sstsubsection{
+         \htmlref{Region}{Region}:
+      }{
+         Regions always use active units if possible.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The ActiveUnit flag resembles a Frame attribute, except that it
+         cannot be tested or cleared, and it cannot be accessed using the
+         generic \htmlref{astGet$<$X$>$}{astGet$<$X$>$} and \htmlref{astSet$<$X$>$}{astSet$<$X$>$} functions.
+
+         \sstitem
+          The \htmlref{astGetActiveUnit}{astGetActiveUnit} function can be used to retrieve the current
+         value of the ActiveUnit flag.
+      }
+   }
+}
+\sstroutine{
+   astSetFits$<$X$>$
+}{
+   Store a keyword value in a FitsChan
+}{
+   \sstdescription{
+      This is a family of functions which store values for named keywords
+      within a \htmlref{FitsChan}{FitsChan} at the current card position. The supplied keyword
+      value can either over-write an existing keyword value, or can be
+      inserted as a new header card into the FitsChan.
+
+      The keyword data type is selected by replacing $<$X$>$ in the function name
+      by one of the following strings representing the recognised FITS data
+
+      types:
+
+      \sstitemlist{
+
+         \sstitem
+          CF - Complex floating point values.
+
+         \sstitem
+          CI - Complex integer values.
+
+         \sstitem
+          F  - Floating point values.
+
+         \sstitem
+          I  - Integer values.
+
+         \sstitem
+          L  - Logical (i.e. boolean) values.
+
+         \sstitem
+          S  - String values.
+
+         \sstitem
+          CN - A \texttt{"} CONTINUE\texttt{"}  value, these are treated like string values, but
+                are encoded without an equals sign.
+
+      }
+      The data type of the \texttt{"} value\texttt{"}  parameter depends on $<$X$>$ as follows:
+
+      \sstitemlist{
+
+         \sstitem
+          CF - \texttt{"} double $*$\texttt{"}  (a pointer to a 2 element array holding the real and
+                imaginary parts of the complex value).
+
+         \sstitem
+          CI - \texttt{"} int $*$\texttt{"}  (a pointer to a 2 element array holding the real and
+                imaginary parts of the complex value).
+
+         \sstitem
+          F  - \texttt{"} double\texttt{"} .
+
+         \sstitem
+          I  - \texttt{"} int\texttt{"} .
+
+         \sstitem
+          L  - \texttt{"} int\texttt{"} .
+
+         \sstitem
+          S  - \texttt{"} const char $*$\texttt{"} .
+
+         \sstitem
+          CN - \texttt{"} const char $*$\texttt{"} .
+      }
+   }
+   \sstsynopsis{
+      void astSetFits$<$X$>$( AstFitsChan $*$this, const char $*$name, $<$X$>$type value,
+                          const char $*$comment, int overwrite )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FitsChan.
+      }
+      \sstsubsection{
+         name
+      }{
+         Pointer to a null-terminated character string
+         containing the FITS keyword name. This may be a complete FITS
+         header card, in which case the keyword to use is extracted from
+         it. No more than 80 characters are read from this string.
+      }
+      \sstsubsection{
+         value
+      }{
+         The keyword value to store with the named keyword. The data type
+         of this parameter depends on $<$X$>$ as described above.
+      }
+      \sstsubsection{
+         comment
+      }{
+         A pointer to a null terminated string
+         holding a comment to associated with the keyword.
+         If a NULL pointer or
+         a blank string is supplied, then any comment included in the string
+         supplied for the
+         \texttt{"} name\texttt{"}  parameter is used instead. If \texttt{"} name\texttt{"}
+         contains no comment, then any existing comment in the card being
+         over-written is retained. Otherwise, no comment is stored with
+         the card.
+      }
+      \sstsubsection{
+         overwrite
+      }{
+         If non-zero,
+         the new card formed from the supplied keyword name, value and comment
+         string over-writes the current card, and the current card is
+         incremented to refer to the next card (see the \texttt{"} \htmlref{Card}{Card}\texttt{"}  attribute). If
+         zero,
+         the new card is inserted in front of the current card and the current
+         card is left unchanged. In either case, if the current card on entry
+         points to the \texttt{"} end-of-file\texttt{"} , the new card is appended to the end of
+         the list.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The
+         function \htmlref{astSetFitsU}{astSetFitsU}
+         can be used to indicate that no value is associated with a keyword.
+
+         \sstitem
+          The
+         function \htmlref{astSetFitsCM}{astSetFitsCM}
+         can be used to store a pure comment card (i.e. a card with a blank
+         keyword).
+
+         \sstitem
+          To assign a new value for an existing keyword within a FitsChan,
+         first find the card describing the keyword using \htmlref{astFindFits}{astFindFits}, and
+         then use one of the astSetFits$<$X$>$ family to over-write the old value.
+
+         \sstitem
+          If, on exit, there are no cards following the card written by
+         this function, then the current card is left pointing at the
+         \texttt{"} end-of-file\texttt{"} .
+
+         \sstitem
+          An error will be reported if the keyword name does not conform
+         to FITS requirements.
+      }
+   }
+}
+\sstroutine{
+   astSetFitsCM
+}{
+   Store a comment card in a FitsChan
+}{
+   \sstdescription{
+      This
+      function
+      stores a comment card ( i.e. a card with no keyword name or equals
+      sign) within a \htmlref{FitsChan}{FitsChan} at the current card position. The new card
+      can either over-write an existing card, or can be inserted as a new
+      card into the FitsChan.
+   }
+   \sstsynopsis{
+      void astSetFitsCM( AstFitsChan $*$this, const char $*$comment,
+                         int overwrite )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FitsChan.
+      }
+      \sstsubsection{
+         comment
+      }{
+         A pointer to a null terminated string
+         holding the text of the comment card.
+         If a NULL pointer or
+         a blank string is supplied, then a totally blank card is produced.
+      }
+      \sstsubsection{
+         overwrite
+      }{
+         If non-zero,
+         the new card over-writes the current card, and the current card is
+         incremented to refer to the next card (see the \texttt{"} \htmlref{Card}{Card}\texttt{"}  attribute). If
+         zero,
+         the new card is inserted in front of the current card and the current
+         card is left unchanged. In either case, if the current card on entry
+         points to the \texttt{"} end-of-file\texttt{"} , the new card is appended to the end of
+         the list.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If, on exit, there are no cards following the card written by
+         this function, then the current card is left pointing at the
+         \texttt{"} end-of-file\texttt{"} .
+      }
+   }
+}
+\sstroutine{
+   astSetFitsU
+}{
+   Store an undefined keyword value in a FitsChan
+}{
+   \sstdescription{
+      This
+      function
+      stores an undefined value for a named keyword within
+      a \htmlref{FitsChan}{FitsChan} at the current card position. The new undefined value
+      can either over-write an existing keyword value, or can be inserted
+      as a new header card into the FitsChan.
+   }
+   \sstsynopsis{
+      void astSetFitsU( AstFitsChan $*$this, const char $*$name,
+                        const char $*$comment, int overwrite )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FitsChan.
+      }
+      \sstsubsection{
+         name
+      }{
+         Pointer to a null-terminated character string
+         containing the FITS keyword name. This may be a complete FITS
+         header card, in which case the keyword to use is extracted from
+         it. No more than 80 characters are read from this string.
+      }
+      \sstsubsection{
+         comment
+      }{
+         A pointer to a null terminated string
+         holding a comment to associated with the keyword.
+         If a NULL pointer or
+         a blank string is supplied, then any comment included in the string
+         supplied for the
+         \texttt{"} name\texttt{"}  parameter is used instead. If \texttt{"} name\texttt{"}
+         contains no comment, then any existing comment in the card being
+         over-written is retained. Otherwise, no comment is stored with
+         the card.
+      }
+      \sstsubsection{
+         overwrite
+      }{
+         If non-zero,
+         the new card formed from the supplied keyword name and comment
+         string over-writes the current card, and the current card is
+         incremented to refer to the next card (see the \texttt{"} \htmlref{Card}{Card}\texttt{"}  attribute). If
+         zero,
+         the new card is inserted in front of the current card and the current
+         card is left unchanged. In either case, if the current card on entry
+         points to the \texttt{"} end-of-file\texttt{"} , the new card is appended to the end of
+         the list.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If, on exit, there are no cards following the card written by
+         this function, then the current card is left pointing at the
+         \texttt{"} end-of-file\texttt{"} .
+
+         \sstitem
+          An error will be reported if the keyword name does not conform
+         to FITS requirements.
+      }
+   }
+}
+\sstroutine{
+   astSetPutErr
+}{
+   Register an error handling function for use by the AST error model
+}{
+   \sstdescription{
+      This function can be used to register an external function to be
+      used to deliver an error message and (optionally) an accompanying
+      status value to the user.
+
+      If this function is not called prior to the first error occuring
+      within AST, then the external error handling function selected at
+      link-time (using the \htmlref{ast\_link}{ast\_link} command) will be used. To use an
+      alternative error handler, call this function before using any other
+      AST functions, specifying the external error handling function to be
+      used. This will register the function for future use.
+   }
+   \sstsynopsis{
+      void astSetPutErr( void ($*$fun)(int,const char$*$) )
+   }
+   \sstparameters{
+      \sstsubsection{
+         fun
+      }{
+         A Pointer to the function to be used to handle errors. The interface
+         for this function is described below.
+         Once a function has been provided, a NULL pointer can be supplied
+         in a subsequent call to astSetPutErr to reset the function to the
+         corresponding function selected at link-time.
+      }
+   }
+   \sstdiytopic{
+      Function Interface
+   }{
+      The supplied external function should deliver the supplied error message
+      and (optionally) the supplied status value to the user or to some
+      underlying error system. It requires the following interface:
+
+      void PutErr( int status\_value, const char $*$message )
+
+      \sstitemlist{
+
+         \sstitem
+          status\_value -
+           The error status value.
+
+         \sstitem
+          message - Pointer to a null-terminated character string  containing
+           the error message to be delivered.
+      }
+   }
+}
+\sstroutine{
+   astSetRefPos
+}{
+   Set the reference position in a specified celestial coordinate system
+}{
+   \sstdescription{
+      This function
+      sets the reference position (see attributes \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec}) using
+      axis values (in radians) supplied within the celestial coordinate
+      system represented by a supplied \htmlref{SkyFrame}{SkyFrame}.
+   }
+   \sstsynopsis{
+      void astSetRefPos( AstSpecFrame $*$this, AstSkyFrame $*$frm, double lon,
+                         double lat )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the \htmlref{SpecFrame}{SpecFrame}.
+      }
+      \sstsubsection{
+         frm
+      }{
+         Pointer to the SkyFrame which defines the celestial coordinate
+         system in which the longitude and latitude values are supplied.
+         If NULL
+         is supplied, then the supplied longitude and latitude values are
+         assumed to be FK5 J2000 RA and Dec values.
+      }
+      \sstsubsection{
+         lon
+      }{
+         The longitude of the reference point, in the coordinate system
+         represented by the supplied SkyFrame (radians).
+      }
+      \sstsubsection{
+         lat
+      }{
+         The latitude of the reference point, in the coordinate system
+         represented by the supplied SkyFrame (radians).
+      }
+   }
+}
+\sstroutine{
+   astSetStatus
+}{
+   Set the AST error status to an explicit value
+}{
+   \sstdescription{
+      This function sets the AST error status to the value supplied.
+      It does not cause any error message to be produced and should
+      not be used as part of normal error reporting. Its purpose is
+      simply to communicate to AST that an error has occurred in some
+      other item of software.
+
+      For example, a source or sink function supplied as an argument
+      to \htmlref{astChannel}{astChannel} or \htmlref{astFitsChan}{astFitsChan} might use this to signal that an
+      input/output error has occurred. AST could then respond by
+      terminating the current read or write operation.
+   }
+   \sstsynopsis{
+      void astSetStatus( int status\_value )
+   }
+   \sstparameters{
+      \sstsubsection{
+         status\_value
+      }{
+         The new error status value to be set.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If the AST error status is set to an error value, most AST
+         functions will not execute and will simply return without
+         action. To clear the error status and restore normal behaviour,
+         use \htmlref{astClearStatus}{astClearStatus}.
+      }
+   }
+}
+\sstroutine{
+   astSetUnc
+}{
+   Store uncertainty information in a Region
+}{
+   \sstdescription{
+      Each \htmlref{Region}{Region} (of any class) can have an \texttt{"} uncertainty\texttt{"}  which specifies
+      the uncertainties associated with the boundary of the Region. This
+      information is supplied in the form of a second Region. The uncertainty
+      in any point on the boundary of a Region is found by shifting the
+      associated \texttt{"} uncertainty\texttt{"}  Region so that it is centred at the boundary
+      point being considered. The area covered by the shifted uncertainty
+      Region then represents the uncertainty in the boundary position.
+      The uncertainty is assumed to be the same for all points.
+
+      The uncertainty is usually specified when the Region is created, but
+      this
+      function
+      allows it to be changed at any time.
+   }
+   \sstsynopsis{
+      void astSetUnc( AstRegion $*$this, AstRegion $*$unc )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Region which is to be assigned a new uncertainty.
+      }
+      \sstsubsection{
+         unc
+      }{
+         Pointer to the new uncertainty Region. This must be of a class for
+         which all instances are centro-symetric (e.g. \htmlref{Box}{Box}, \htmlref{Circle}{Circle}, \htmlref{Ellipse}{Ellipse},
+         etc.) or be a \htmlref{Prism}{Prism} containing centro-symetric component Regions.
+         A deep copy of the supplied Region will be taken, so subsequent
+         changes to the uncertainty Region using the supplied pointer will
+         have no effect on the Region
+         \texttt{"} this\texttt{"} .
+      }
+   }
+}
+\sstroutine{
+   astShiftMap
+}{
+   Create a ShiftMap
+}{
+   \sstdescription{
+      This function creates a new \htmlref{ShiftMap}{ShiftMap} and optionally initialises its
+      attributes.
+
+      A ShiftMap is a linear \htmlref{Mapping}{Mapping} which shifts each axis by a
+      specified constant value.
+   }
+   \sstsynopsis{
+      AstShiftMap $*$astShiftMap( int ncoord, const double shift[],
+                                const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         ncoord
+      }{
+         The number of coordinate values for each point to be
+         transformed (i.e. the number of dimensions of the space in
+         which the points will reside). The same number is applicable
+         to both input and output points.
+      }
+      \sstsubsection{
+         shift
+      }{
+         An array containing the values to be added on to the input
+         coordinates in order to create the output coordinates. A separate
+         value should be supplied for each coordinate.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new ShiftMap. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astShiftMap()
+      }{
+         A pointer to the new ShiftMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      Status Handling
+   }{
+      The protected interface to this function includes an extra
+      parameter at the end of the parameter list descirbed above. This
+      parameter is a pointer to the integer inherited status
+      variable: \texttt{"} int $*$status\texttt{"} .
+   }
+}
+\sstroutine{
+   astShow
+}{
+   Display a textual representation of an Object on standard output
+}{
+   \sstdescription{
+      This function displays a textual description of any AST \htmlref{Object}{Object}
+      on standard output. It is provided primarily as an aid to
+      debugging.
+   }
+   \sstsynopsis{
+      void astShow( AstObject $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Object to be displayed.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         This function applies to all Objects.
+      }
+   }
+}
+\sstroutine{
+   astShowFits
+}{
+   Display the contents of a FitsChan on standard output
+}{
+   \sstdescription{
+      This function
+      formats and displays all the cards in a \htmlref{FitsChan}{FitsChan} on standard output.
+   }
+   \sstsynopsis{
+      void astShowFits( AstFitsChan $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FitsChan.
+      }
+   }
+}
+\sstroutine{
+   astShowMesh
+}{
+   Display a mesh of points covering the surface of a Region
+}{
+   \sstdescription{
+      This function
+      writes a table to standard output containing the axis values at a
+      mesh of points covering the surface of the supplied \htmlref{Region}{Region}. Each row
+      of output contains a tab-separated list of axis values, one for
+      each axis in the \htmlref{Frame}{Frame} encapsulated by the Region. The number of
+      points in the mesh is determined by the \htmlref{MeshSize}{MeshSize} attribute.
+
+      The table is preceded by a given title string, and followed by a
+      single line containing the word \texttt{"} ENDMESH\texttt{"} .
+   }
+   \sstsynopsis{
+      void astShowMesh( AstRegion $*$this, int format, const char $*$ttl )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Region.
+      }
+      \sstsubsection{
+         format
+      }{
+         A boolean value indicating if the displayed axis values should
+         be formatted according to the Format attribute associated with
+         the Frame\texttt{'} s axis. Otherwise, they are displayed as simple
+         floating point values.
+      }
+      \sstsubsection{
+         ttl
+      }{
+         A title to display before displaying the first position.
+      }
+   }
+}
+\sstroutine{
+   astSimplify
+}{
+   Simplify a Mapping
+}{
+   \sstdescription{
+      This function simplifies a \htmlref{Mapping}{Mapping} (which may be a compound
+      Mapping such as a \htmlref{CmpMap}{CmpMap}) to eliminate redundant computational
+      steps, or to merge separate steps which can be performed more
+      efficiently in a single operation.
+
+      As a simple example, a Mapping which multiplied coordinates by
+      5, and then multiplied the result by 10, could be simplified to
+      a single step which multiplied by 50. Similarly, a Mapping which
+      multiplied by 5, and then divided by 5, could be reduced to a
+      simple copying operation.
+
+      This function should typically be applied to Mappings which have
+      undergone substantial processing or have been formed by merging
+      other Mappings. It is of potential benefit, for example, in
+      reducing execution time if applied before using a Mapping to
+      transform a large number of coordinates.
+   }
+   \sstsynopsis{
+      AstMapping $*$astSimplify( AstMapping $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the original Mapping.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Mapping
+      }{
+         This function applies to all Mappings.
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         If the supplied Mapping is a FrameSet, the returned Mapping
+         will be a copy of the supplied FrameSet in which all the
+         inter-\htmlref{Frame}{Frame} Mappings have been simplified.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astSimplify()
+      }{
+         A new pointer to the (possibly simplified) Mapping.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Mappings that have a set value for their \htmlref{Ident}{Ident} attribute are
+         left unchanged after simplification. This is so that their
+         individual identity is preserved. This restriction does not
+         apply to the simplification of Frames.
+
+         \sstitem
+          This function can safely be applied even to Mappings which
+         cannot be simplified. If no simplification is possible, it
+         behaves exactly like \htmlref{astClone}{astClone} and returns a pointer to the
+         original Mapping.
+
+         \sstitem
+          The Mapping returned by this function may not be independent
+         of the original (even if simplification was possible), and
+         modifying it may therefore result in indirect modification of
+         the original. If a completely independent result is required, a
+         copy should be made using \htmlref{astCopy}{astCopy}.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astSkyFrame
+}{
+   Create a SkyFrame
+}{
+   \sstdescription{
+      This function creates a new \htmlref{SkyFrame}{SkyFrame} and optionally initialises
+      its attributes.
+
+      A SkyFrame is a specialised form of \htmlref{Frame}{Frame} which describes
+      celestial longitude/latitude coordinate systems. The particular
+      celestial coordinate system to be represented is specified by
+      setting the SkyFrame\texttt{'} s \htmlref{System}{System} attribute (currently, the default
+      is ICRS) qualified, as necessary, by a mean \htmlref{Equinox}{Equinox} value and/or
+      an \htmlref{Epoch}{Epoch}.
+
+      For each of the supported celestial coordinate systems, a SkyFrame
+      can apply an optional shift of origin to create a coordinate system
+      representing offsets within the celestial coordinate system from some
+      specified point. This offset coordinate system can also be rotated to
+      define new longitude and latitude axes. See attributes SkyRef, \htmlref{SkyRefIs}{SkyRefIs}
+      and SkyRefP
+
+      All the coordinate values used by a SkyFrame are in
+      radians. These may be formatted in more conventional ways for
+      display by using \htmlref{astFormat}{astFormat}.
+   }
+   \sstsynopsis{
+      AstSkyFrame $*$astSkyFrame( const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new SkyFrame. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+         If no initialisation is required, a zero-length string may be
+         supplied.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astSkyFrame()
+      }{
+         A pointer to the new SkyFrame.
+      }
+   }
+   \sstexamples{
+      \sstexamplesubsection{
+         frame = astSkyFrame( \texttt{"} \texttt{"}  );
+      }{
+         Creates a SkyFrame to describe the default ICRS celestial
+         coordinate system.
+      }
+      \sstexamplesubsection{
+         frame = astSkyFrame( \texttt{"} System = FK5, Equinox = J2005, Digits = 10\texttt{"}  );
+      }{
+         Creates a SkyFrame to describe the FK5 celestial
+         coordinate system, with a mean Equinox of J2005.0.
+         Because especially accurate coordinates will be used,
+         additional precision (10 digits) has been requested. This will
+         be used when coordinate values are formatted for display.
+      }
+      \sstexamplesubsection{
+         frame = astSkyFrame( \texttt{"} System = FK4, Equinox = 1955-sep-2\texttt{"}  );
+      }{
+         Creates a SkyFrame to describe the old FK4 celestial
+         coordinate system.  A default Epoch value (B1950.0) is used,
+         but the mean Equinox value is given explicitly as \texttt{"} 1955-sep-2\texttt{"} .
+      }
+      \sstexamplesubsection{
+         frame = astSkyFrame( \texttt{"} System = GAPPT, Epoch = \%s\texttt{"} , date );
+      }{
+         Creates a SkyFrame to describe the Geocentric Apparent
+         celestial coordinate system. The Epoch value, which specifies
+         the date of observation, is obtained from a date/time string
+         supplied via the string pointer \texttt{"} date\texttt{"} .
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Currently, the default celestial coordinate system is
+         ICRS. However, this default may change in future as new
+         astrometric standards evolve. The intention is to track the most
+         modern appropriate standard. For this reason, you should use the
+         default only if this is what you intend (and can tolerate any
+         associated slight change in behaviour with future versions of
+         this function). If you intend to use the ICRS system
+         indefinitely, then you should specify it explicitly using an
+         \texttt{"} options\texttt{"}  value of \texttt{"} System=ICRS\texttt{"} .
+
+         \sstitem
+          Whichever celestial coordinate system is represented, it will
+         have two axes.  The first of these will be the longitude axis
+         and the second will be the latitude axis. This order can be
+         changed using \htmlref{astPermAxes}{astPermAxes} if required.
+
+         \sstitem
+          When conversion between two SkyFrames is requested (as when
+         supplying SkyFrames to \htmlref{astConvert}{astConvert}),
+         account will be taken of the nature of the celestial coordinate
+         systems they represent, together with any qualifying mean Equinox or
+         Epoch values, etc. The \htmlref{AlignSystem}{AlignSystem} attribute will also be taken into
+         account. The results will therefore fully reflect the
+         relationship between positions on the sky measured in the two
+         systems.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astSkyOffsetMap
+}{
+   Returns a Mapping which goes from absolute coordinates to offset
+   coordinates
+}{
+   \sstdescription{
+      This function returns a \htmlref{Mapping}{Mapping} in which the forward transformation
+      transforms a position in the coordinate system given by the \htmlref{System}{System}
+      attribute of the supplied \htmlref{SkyFrame}{SkyFrame}, into the offset coordinate system
+      specified by the SkyRef, SkyRefP and \htmlref{SkyRefIs}{SkyRefIs} attributes of the
+      supplied SkyFrame.
+
+      A \htmlref{UnitMap}{UnitMap} is returned if the SkyFrame does not define an offset
+      coordinate system.
+   }
+   \sstsynopsis{
+      AstMapping $*$astSkyOffsetMap( AstSkyFrame $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the SkyFrame.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astSkyOffsetMap()
+      }{
+         Pointer to the returned Mapping.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astSlaAdd
+}{
+   Add a celestial coordinate conversion to an SlaMap
+}{
+   \sstdescription{
+      This function adds one of the standard celestial coordinate
+      system conversions provided by the SLALIB Positional Astronomy
+      Library (Starlink User Note SUN/67) to an existing \htmlref{SlaMap}{SlaMap}.
+
+      When an SlaMap is first created (using \htmlref{astSlaMap}{astSlaMap}), it simply
+      performs a unit (null) \htmlref{Mapping}{Mapping}. By using astSlaAdd (repeatedly
+      if necessary), one or more coordinate conversion steps may then
+      be added, which the SlaMap will perform in sequence. This allows
+      multi-step conversions between a variety of celestial coordinate
+      systems to be assembled out of the building blocks provided by
+      SLALIB.
+
+      Normally, if an SlaMap\texttt{'} s \htmlref{Invert}{Invert} attribute is zero (the default),
+      then its forward transformation is performed by carrying out
+      each of the individual coordinate conversions specified by
+      astSlaAdd in the order given (i.e. with the most recently added
+      conversion applied last).
+
+      This order is reversed if the SlaMap\texttt{'} s Invert attribute is
+      non-zero (or if the inverse transformation is requested by any
+      other means) and each individual coordinate conversion is also
+      replaced by its own inverse. This process inverts the overall
+      effect of the SlaMap. In this case, the first conversion to be
+      applied would be the inverse of the one most recently added.
+   }
+   \sstsynopsis{
+      void astSlaAdd( AstSlaMap $*$this, const char $*$cvt, int narg,
+                      const double args[] )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the SlaMap.
+      }
+      \sstsubsection{
+         cvt
+      }{
+         Pointer to a null-terminated string which identifies the
+         celestial coordinate conversion to be added to the
+         SlaMap. See the \texttt{"} SLALIB Conversions\texttt{"}  section for details of
+         those available.
+      }
+      \sstsubsection{
+         narg
+      }{
+         The number of argument values supplied in the
+         \texttt{"} args\texttt{"}  array.
+      }
+      \sstsubsection{
+         args
+      }{
+         An array containing argument values for the celestial
+         coordinate conversion. The number of arguments required, and
+         hence the number of array elements used, depends on the
+         conversion specified (see the \texttt{"} SLALIB Conversions\texttt{"}
+         section). This array is ignored
+         and a NULL pointer may be supplied
+         if no arguments are needed.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          All coordinate values processed by an SlaMap are in
+         radians. The first coordinate is the celestial longitude and the
+         second coordinate is the celestial latitude.
+
+         \sstitem
+          When assembling a multi-stage conversion, it can sometimes be
+         difficult to determine the most economical conversion path. For
+         example, converting to the standard FK5 coordinate system as an
+         intermediate stage is often sensible in formulating the problem,
+         but may introduce unnecessary extra conversion steps. A solution
+         to this is to include all the steps which are (logically)
+         necessary, but then to use \htmlref{astSimplify}{astSimplify} to simplify the resulting
+         SlaMap. The simplification process will eliminate any steps
+         which turn out not to be needed.
+
+         \sstitem
+          This function does not check to ensure that the sequence of
+         coordinate conversions added to an SlaMap is physically
+         meaningful.
+      }
+   }
+   \sstdiytopic{
+      SLALIB Conversions
+   }{
+      The following strings (which are case-insensitive) may be supplied
+      via the \texttt{"} cvt\texttt{"}  parameter to indicate which celestial coordinate
+      conversion is to be added to the SlaMap. Each string is derived
+      from the name of the SLALIB routine that performs the
+      conversion and the relevant documentation (SUN/67) should be
+      consulted for details.  Where arguments are needed by
+      the conversion, they are listed in parentheses. Values for
+      these arguments should be given, via the \texttt{"} args\texttt{"}  array, in the
+      order indicated. The argument names match the corresponding
+      SLALIB routine arguments and their values should be given using
+      exactly the same units, time scale, calendar, etc. as described
+      in SUN/67:
+
+      \sstitemlist{
+
+         \sstitem
+          \texttt{"} ADDET\texttt{"}  (EQ): Add E-terms of aberration.
+
+         \sstitem
+          \texttt{"} SUBET\texttt{"}  (EQ): Subtract E-terms of aberration.
+
+         \sstitem
+          \texttt{"} PREBN\texttt{"}  (BEP0,BEP1): Apply Bessel-Newcomb pre-IAU 1976 (FK4)
+         precession model.
+
+         \sstitem
+          \texttt{"} PREC\texttt{"}  (EP0,EP1): Apply IAU 1975 (FK5) precession model.
+
+         \sstitem
+          \texttt{"} FK45Z\texttt{"}  (BEPOCH): Convert FK4 to FK5 (no proper motion or parallax).
+
+         \sstitem
+          \texttt{"} FK54Z\texttt{"}  (BEPOCH): Convert FK5 to FK4 (no proper motion or parallax).
+
+         \sstitem
+          \texttt{"} AMP\texttt{"}  (DATE,EQ): Convert geocentric apparent to mean place.
+
+         \sstitem
+          \texttt{"} MAP\texttt{"}  (EQ,DATE): Convert mean place to geocentric apparent.
+
+         \sstitem
+          \texttt{"} ECLEQ\texttt{"}  (DATE): Convert ecliptic coordinates to FK5 J2000.0 equatorial.
+
+         \sstitem
+          \texttt{"} EQECL\texttt{"}  (DATE): Convert equatorial FK5 J2000.0 to ecliptic coordinates.
+
+         \sstitem
+          \texttt{"} GALEQ\texttt{"} : Convert galactic coordinates to FK5 J2000.0 equatorial.
+
+         \sstitem
+          \texttt{"} EQGAL\texttt{"} : Convert FK5 J2000.0 equatorial to galactic coordinates.
+
+         \sstitem
+          \texttt{"} HFK5Z\texttt{"}  (JEPOCH): Convert ICRS coordinates to FK5 J2000.0 equatorial.
+
+         \sstitem
+          \texttt{"} FK5HZ\texttt{"}  (JEPOCH): Convert FK5 J2000.0 equatorial coordinates to ICRS.
+
+         \sstitem
+          \texttt{"} GALSUP\texttt{"} : Convert galactic to supergalactic coordinates.
+
+         \sstitem
+          \texttt{"} SUPGAL\texttt{"} : Convert supergalactic coordinates to galactic.
+
+         \sstitem
+          \texttt{"} J2000H\texttt{"} : Convert dynamical J2000.0 to ICRS.
+
+         \sstitem
+          \texttt{"} HJ2000\texttt{"} : Convert ICRS to dynamical J2000.0.
+
+         \sstitem
+          \texttt{"} R2H\texttt{"}  (LAST): Convert RA to Hour Angle.
+
+         \sstitem
+          \texttt{"} H2R\texttt{"}  (LAST): Convert Hour Angle to RA.
+
+      }
+      For example, to use the \texttt{"} ADDET\texttt{"}  conversion, which takes a single
+      argument EQ, you should consult the documentation for the SLALIB
+      routine SLA\_ADDET. This describes the conversion in detail and
+      shows that EQ is the Besselian epoch of the mean equator and
+      equinox.
+      This value should then be supplied to astSlaAdd in args[0].
+
+      In addition the following strings may be supplied for more complex
+      conversions which do not correspond to any one single SLALIB routine
+      (DIURAB is the magnitude of the diurnal aberration vector in units
+      of \texttt{"} day/(2.PI)\texttt{"} , DATE is the Modified Julian Date of the observation,
+      and (OBSX,OBSY,OBZ) are the Heliocentric-Aries-Ecliptic cartesian
+      coordinates, in metres, of the observer):
+
+      \sstitemlist{
+
+         \sstitem
+          \texttt{"} HPCEQ\texttt{"}  (DATE,OBSX,OBSY,OBSZ): Convert Helioprojective-Cartesian coordinates to J2000.0 equatorial.
+
+         \sstitem
+          \texttt{"} EQHPC\texttt{"}  (DATE,OBSX,OBSY,OBSZ): Convert J2000.0 equatorial coordinates to Helioprojective-Cartesian.
+
+         \sstitem
+          \texttt{"} HPREQ\texttt{"}  (DATE,OBSX,OBSY,OBSZ): Convert Helioprojective-Radial coordinates to J2000.0 equatorial.
+
+         \sstitem
+          \texttt{"} EQHPR\texttt{"}  (DATE,OBSX,OBSY,OBSZ): Convert J2000.0 equatorial coordinates to Helioprojective-Radial.
+
+         \sstitem
+          \texttt{"} HEEQ\texttt{"}  (DATE): Convert helio-ecliptic coordinates to J2000.0 equatorial.
+
+         \sstitem
+          \texttt{"} EQHE\texttt{"}  (DATE): Convert J2000.0 equatorial coordinates to helio-ecliptic.
+
+         \sstitem
+          \texttt{"} H2E\texttt{"}  (LAT,DIRUAB): Convert horizon coordinates to equatorial.
+
+         \sstitem
+          \texttt{"} E2H\texttt{"}  (LAT,DIURAB): Convert equatorial coordinates to horizon.
+
+      }
+      Note, the \texttt{"} H2E\texttt{"}  and \texttt{"} E2H\texttt{"}  conversions convert between topocentric
+      horizon coordinates (azimuth,elevation), and apparent local equatorial
+      coordinates (hour angle,declination). Thus, the effects of diurnal
+      aberration are taken into account in the conversions but the effects
+      of atmospheric refraction are not.
+   }
+}
+\sstroutine{
+   astSlaMap
+}{
+   Create an SlaMap
+}{
+   \sstdescription{
+      This function creates a new \htmlref{SlaMap}{SlaMap} and optionally initialises
+      its attributes.
+
+      An SlaMap is a specialised form of \htmlref{Mapping}{Mapping} which can be used to
+      represent a sequence of conversions between standard celestial
+      (longitude, latitude) coordinate systems.
+
+      When an SlaMap is first created, it simply performs a unit
+      (null) Mapping on a pair of coordinates. Using the \htmlref{astSlaAdd}{astSlaAdd}
+      function, a series of coordinate conversion steps may then be
+      added, selected from those provided by the SLALIB Positional
+      Astronomy Library (Starlink User Note SUN/67). This allows
+      multi-step conversions between a variety of celestial coordinate
+      systems to be assembled out of the building blocks provided by
+      SLALIB.
+
+      For details of the individual coordinate conversions available,
+      see the description of the astSlaAdd function.
+   }
+   \sstsynopsis{
+      AstSlaMap $*$astSlaMap( int flags, const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         flags
+      }{
+         This parameter is reserved for future use and should currently
+         always be set to zero.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new SlaMap. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+         If no initialisation is required, a zero-length string may be
+         supplied.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astSlaMap()
+      }{
+         A pointer to the new SlaMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes (number of input and output
+         coordinates) for an SlaMap are both equal to 2. The first
+         coordinate is the celestial longitude and the second coordinate
+         is the celestial latitude. All coordinate values are in radians.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astSpecAdd
+}{
+   Add a spectral coordinate conversion to a SpecMap
+}{
+   \sstdescription{
+      This function adds one of the standard spectral coordinate
+      system conversions listed below to an existing \htmlref{SpecMap}{SpecMap}.
+
+      When a SpecMap is first created (using \htmlref{astSpecMap}{astSpecMap}), it simply
+      performs a unit (null) \htmlref{Mapping}{Mapping}. By using astSpecAdd (repeatedly
+      if necessary), one or more coordinate conversion steps may then
+      be added, which the SpecMap will perform in sequence. This allows
+      multi-step conversions between a variety of spectral coordinate
+      systems to be assembled out of the building blocks provided by
+      this class.
+
+      Normally, if a SpecMap\texttt{'} s \htmlref{Invert}{Invert} attribute is zero (the default),
+      then its forward transformation is performed by carrying out
+      each of the individual coordinate conversions specified by
+      astSpecAdd in the order given (i.e. with the most recently added
+      conversion applied last).
+
+      This order is reversed if the SpecMap\texttt{'} s Invert attribute is
+      non-zero (or if the inverse transformation is requested by any
+      other means) and each individual coordinate conversion is also
+      replaced by its own inverse. This process inverts the overall
+      effect of the SpecMap. In this case, the first conversion to be
+      applied would be the inverse of the one most recently added.
+   }
+   \sstsynopsis{
+      void astSpecAdd( AstSpecMap $*$this, const char $*$cvt, int narg,
+                       const double args[] )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the SpecMap.
+      }
+      \sstsubsection{
+         cvt
+      }{
+         Pointer to a null-terminated string which identifies the
+         spectral coordinate conversion to be added to the
+         SpecMap. See the \texttt{"} Available Conversions\texttt{"}  section for details of
+         those available.
+      }
+      \sstsubsection{
+         narg
+      }{
+         The number of argument values supplied in the
+         \texttt{"} args\texttt{"}  array.
+      }
+      \sstsubsection{
+         args
+      }{
+         An array containing argument values for the spectral
+         coordinate conversion. The number of arguments required, and
+         hence the number of array elements used, depends on the
+         conversion specified (see the \texttt{"} Available Conversions\texttt{"}
+         section). This array is ignored
+         and a NULL pointer may be supplied
+         if no arguments are needed.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          When assembling a multi-stage conversion, it can sometimes be
+         difficult to determine the most economical conversion path. For
+         example, when converting between reference frames, converting first
+         to the heliographic reference frame as an intermediate stage is often
+         sensible in formulating the problem, but may introduce unnecessary
+         extra conversion steps. A solution to this is to include all the steps
+         which are (logically) necessary, but then to use
+         \htmlref{astSimplify}{astSimplify} to simplify the resulting
+         SpecMap. The simplification process will eliminate any steps
+         which turn out not to be needed.
+
+         \sstitem
+          This function does not check to ensure that the sequence of
+         coordinate conversions added to a SpecMap is physically
+         meaningful.
+      }
+   }
+   \sstdiytopic{
+      Available Conversions
+   }{
+      The following strings (which are case-insensitive) may be supplied
+      via the \texttt{"} cvt\texttt{"}  parameter to indicate which spectral coordinate
+      conversion is to be added to the SpecMap. Where arguments are needed by
+      the conversion, they are listed in parentheses. Values for
+      these arguments should be given, via the \texttt{"} args\texttt{"}  array, in the
+      order indicated. Units and argument names are described at the end of
+      the list of conversions.
+
+      \sstitemlist{
+
+         \sstitem
+          \texttt{"} FRTOVL\texttt{"}  (RF): Convert frequency to relativistic velocity.
+
+         \sstitem
+          \texttt{"} VLTOFR\texttt{"}  (RF): Convert relativistic velocity to Frequency.
+
+         \sstitem
+          \texttt{"} ENTOFR\texttt{"} : Convert energy to frequency.
+
+         \sstitem
+          \texttt{"} FRTOEN\texttt{"} : Convert frequency to energy.
+
+         \sstitem
+          \texttt{"} WNTOFR\texttt{"} : Convert wave number to frequency.
+
+         \sstitem
+          \texttt{"} FRTOWN\texttt{"} : Convert frequency to wave number.
+
+         \sstitem
+          \texttt{"} WVTOFR\texttt{"} : Convert wavelength (vacuum) to frequency.
+
+         \sstitem
+          \texttt{"} FRTOWV\texttt{"} : Convert frequency to wavelength (vacuum).
+
+         \sstitem
+          \texttt{"} AWTOFR\texttt{"} : Convert wavelength (air) to frequency.
+
+         \sstitem
+          \texttt{"} FRTOAW\texttt{"} : Convert frequency to wavelength (air).
+
+         \sstitem
+          \texttt{"} VRTOVL\texttt{"} : Convert radio to relativistic velocity.
+
+         \sstitem
+          \texttt{"} VLTOVR\texttt{"} : Convert relativistic to radio velocity.
+
+         \sstitem
+          \texttt{"} VOTOVL\texttt{"} : Convert optical to relativistic velocity.
+
+         \sstitem
+          \texttt{"} VLTOVO\texttt{"} : Convert relativistic to optical velocity.
+
+         \sstitem
+          \texttt{"} ZOTOVL\texttt{"} : Convert redshift to relativistic velocity.
+
+         \sstitem
+          \texttt{"} VLTOZO\texttt{"} : Convert relativistic velocity to redshift.
+
+         \sstitem
+          \texttt{"} BTTOVL\texttt{"} : Convert beta factor to relativistic velocity.
+
+         \sstitem
+          \texttt{"} VLTOBT\texttt{"} : Convert relativistic velocity to beta factor.
+
+         \sstitem
+          \texttt{"} USF2HL\texttt{"}  (VOFF,RA,DEC): Convert frequency from a user-defined
+         reference frame to heliocentric.
+
+         \sstitem
+          \texttt{"} HLF2US\texttt{"}  (VOFF,RA,DEC): Convert frequency from heliocentric
+         reference frame to user-defined.
+
+         \sstitem
+          \texttt{"} TPF2HL\texttt{"}  (OBSLON,OBSLAT,OBSALT,EPOCH,RA,DEC): Convert frequency from
+         topocentric reference frame to heliocentric.
+
+         \sstitem
+          \texttt{"} HLF2TP\texttt{"}  (OBSLON,OBSLAT,OBSALT,EPOCH,RA,DEC): Convert frequency from
+         heliocentric reference frame to topocentric.
+
+         \sstitem
+          \texttt{"} GEF2HL\texttt{"}  (EPOCH,RA,DEC): Convert frequency from geocentric
+         reference frame to heliocentric.
+
+         \sstitem
+          \texttt{"} HLF2GE\texttt{"}  (EPOCH,RA,DEC): Convert frequency from
+         heliocentric reference frame to geocentric.
+
+         \sstitem
+          \texttt{"} BYF2HL\texttt{"}  (EPOCH,RA,DEC): Convert frequency from
+         barycentric reference frame to heliocentric.
+
+         \sstitem
+          \texttt{"} HLF2BY\texttt{"}  (EPOCH,RA,DEC): Convert frequency from
+         heliocentric reference frame to barycentric.
+
+         \sstitem
+          \texttt{"} LKF2HL\texttt{"}  (RA,DEC): Convert frequency from kinematic LSR
+         reference frame to heliocentric.
+
+         \sstitem
+          \texttt{"} HLF2LK\texttt{"}  (RA,DEC): Convert frequency from heliocentric
+         reference frame to kinematic LSR.
+
+         \sstitem
+          \texttt{"} LDF2HL\texttt{"}  (RA,DEC): Convert frequency from dynamical LSR
+         reference frame to heliocentric.
+
+         \sstitem
+          \texttt{"} HLF2LD\texttt{"}  (RA,DEC): Convert frequency from heliocentric
+         reference frame to dynamical LSR.
+
+         \sstitem
+          \texttt{"} LGF2HL\texttt{"}  (RA,DEC): Convert frequency from local group
+         reference frame to heliocentric.
+
+         \sstitem
+          \texttt{"} HLF2LG\texttt{"}  (RA,DEC): Convert frequency from heliocentric
+         reference frame to local group.
+
+         \sstitem
+          \texttt{"} GLF2HL\texttt{"}  (RA,DEC): Convert frequency from galactic
+         reference frame to heliocentric.
+
+         \sstitem
+          \texttt{"} HLF2GL\texttt{"}  (RA,DEC): Convert frequency from heliocentric
+         reference frame to galactic.
+
+      }
+      The units for the values processed by the above conversions are as
+      follows:
+
+      \sstitemlist{
+
+         \sstitem
+          all velocities: metres per second (positive if the source receeds from
+           the observer).
+
+         \sstitem
+          frequency: Hertz.
+
+         \sstitem
+          all wavelengths: metres.
+
+         \sstitem
+          energy: Joules.
+
+         \sstitem
+          wave number: cycles per metre.
+
+      }
+      The arguments used in the above conversions are as follows:
+
+      \sstitemlist{
+
+         \sstitem
+          RF: Rest frequency (Hz).
+
+         \sstitem
+          OBSALT: Geodetic altitude of observer (IAU 1975, metres).
+
+         \sstitem
+          OBSLAT: Geodetic latitude of observer (IAU 1975, radians).
+
+         \sstitem
+          OBSLON: Longitude of observer (radians - positive eastwards).
+
+         \sstitem
+          EPOCH: \htmlref{Epoch}{Epoch} of observation (UT1 expressed as a Modified Julian Date).
+
+         \sstitem
+          RA: Right Ascension of source (radians, FK5 J2000).
+
+         \sstitem
+          DEC: Declination of source (radians, FK5 J2000).
+
+         \sstitem
+          VOFF: Velocity of the user-defined reference frame, towards the
+         position given by RA and DEC, measured in the heliocentric
+         reference frame.
+
+      }
+      If the SpecMap is 3-dimensional, source positions are provided by the
+      values supplied to inputs 2 and 3 of the SpecMap (which are simply
+      copied to outputs 2 and 3). Note, usable values are still required
+      for the RA and DEC arguments in order to define the \texttt{"} user-defined\texttt{"}
+      reference frame used by USF2HL and HLF2US. However, AST\_\_BAD can be
+      supplied for RA and DEC if the user-defined reference frame is not
+      required.
+   }
+}
+\sstroutine{
+   astSpecFluxFrame
+}{
+   Create a SpecFluxFrame
+}{
+   \sstdescription{
+      This function creates a new \htmlref{SpecFluxFrame}{SpecFluxFrame} and optionally initialises
+      its attributes.
+
+      A SpecFluxFrame combines a \htmlref{SpecFrame}{SpecFrame} and a \htmlref{FluxFrame}{FluxFrame} into a single
+      2-dimensional compound \htmlref{Frame}{Frame}. Such a Frame can for instance be used
+      to describe a \htmlref{Plot}{Plot} of a spectrum in which the first axis represents
+      spectral position and the second axis represents flux.
+   }
+   \sstsynopsis{
+      AstSpecFluxFrame $*$astSpecFluxFrame( AstSpecFrame $*$frame1, AstFluxFrame $*$frame2,
+                                          const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         frame1
+      }{
+         Pointer to the SpecFrame. This will form the first axis in the
+         new SpecFluxFrame.
+      }
+      \sstsubsection{
+         frame2
+      }{
+         Pointer to the FluxFrame. This will form the second axis in the
+         new SpecFluxFrame. The \texttt{"} \htmlref{SpecVal}{SpecVal}\texttt{"}  attribute of this FluxFrame is
+         not used by the SpecFluxFrame class and so may be set to AST\_\_BAD
+         when the FluxFrame is created.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new SpecFluxFrame. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astSpecFluxFrame()
+      }{
+         A pointer to the new SpecFluxFrame.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The supplied Frame pointers are stored directly, rather than
+         being used to create deep copies of the supplied Frames. This means
+         that any subsequent changes made to the Frames via the supplied
+         pointers will result in equivalent changes being visible in the
+         SpecFluxFrame.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      Status Handling
+   }{
+      The protected interface to this function includes an extra
+      parameter at the end of the parameter list descirbed above. This
+      parameter is a pointer to the integer inherited status
+      variable: \texttt{"} int $*$status\texttt{"} .
+   }
+}
+\sstroutine{
+   astSpecFrame
+}{
+   Create a SpecFrame
+}{
+   \sstdescription{
+      This function creates a new \htmlref{SpecFrame}{SpecFrame} and optionally initialises
+      its attributes.
+
+      A SpecFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which
+      represents various coordinate systems used to describe positions within
+      an electro-magnetic spectrum. The particular coordinate system to be
+      used is specified by setting the SpecFrame\texttt{'} s \htmlref{System}{System} attribute (the
+      default is wavelength) qualified, as necessary, by other attributes
+      such as the rest frequency, the standard of rest, the epoch of
+      observation, etc (see the description of the System attribute for
+      details).
+
+      By setting a value for thr \htmlref{SpecOrigin}{SpecOrigin} attribute, a SpecFrame can be made
+      to represent offsets from a given spectral position, rather than absolute
+   }
+   \sstsynopsis{
+      AstSpecFrame $*$astSpecFrame( const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new SpecFrame. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+         If no initialisation is required, a zero-length string may be
+         supplied.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astSpecFrame()
+      }{
+         A pointer to the new SpecFrame.
+      }
+   }
+   \sstexamples{
+      \sstexamplesubsection{
+         frame = astSpecFrame( \texttt{"} \texttt{"}  );
+      }{
+         Creates a SpecFrame to describe the default wavelength spectral
+         coordinate system. The \htmlref{RestFreq}{RestFreq} attribute (rest frequency) is
+         unspecified, so it will not be possible to align this SpecFrame
+         with another SpecFrame on the basis of a velocity-based system. The
+         standard of rest is also unspecified. This means that alignment
+         will be possible with other SpecFrames, but no correction will be
+         made for Doppler shift caused by change of rest frame during the
+         alignment.
+      }
+      \sstexamplesubsection{
+         frame = astSpecFrame( \texttt{"} System=VELO, RestFreq=1.0E15, \htmlref{StdOfRest}{StdOfRest}=LSRK\texttt{"}  );
+      }{
+         Creates a SpecFrame describing a apparent radial velocity (\texttt{"} VELO\texttt{"} ) axis
+         with rest frequency 1.0E15 Hz (about 3000 Angstroms), measured
+         in the kinematic Local Standard of Rest (\texttt{"} LSRK\texttt{"} ). Since the
+         source position has not been specified (using attributes \htmlref{RefRA}{RefRA} and
+         \htmlref{RefDec}{RefDec}), it will only be possible to align this SpecFrame with
+         other SpecFrames which are also measured in the LSRK standard of
+         rest.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          When conversion between two SpecFrames is requested (as when
+         supplying SpecFrames to \htmlref{astConvert}{astConvert}),
+         account will be taken of the nature of the spectral coordinate systems
+         they represent, together with any qualifying rest frequency, standard
+         of rest, epoch values, etc. The \htmlref{AlignSystem}{AlignSystem} and \htmlref{AlignStdOfRest}{AlignStdOfRest}
+         attributes will also be taken into account. The results will therefore
+         fully reflect the relationship between positions measured in the two
+         systems. In addition, any difference in the Unit attributes of the two
+         systems will also be taken into account.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astSpecMap
+}{
+   Create a SpecMap
+}{
+   \sstdescription{
+      This function creates a new \htmlref{SpecMap}{SpecMap} and optionally initialises
+      its attributes.
+
+      An SpecMap is a specialised form of \htmlref{Mapping}{Mapping} which can be used to
+      represent a sequence of conversions between standard spectral
+      coordinate systems. This includes conversions between frequency,
+      wavelength, and various forms of velocity, as well as conversions
+      between different standards of rest.
+
+      When a SpecMap is first created, it simply performs a unit
+      (null) Mapping. Using the \htmlref{astSpecAdd}{astSpecAdd} function,
+      a series of coordinate conversion steps may then be added, selected
+      from the list of supported conversions. This allows multi-step
+      conversions between a variety of spectral coordinate systems to
+      be assembled out of the building blocks provided by this class.
+
+      For details of the individual coordinate conversions available,
+      see the description of the astSpecAdd function.
+
+      Conversions are available to transform between standards of rest.
+      Such conversions need to know the source position as an RA and DEC.
+      This information can be supplied in the form of parameters for
+      the relevant conversions, in which case the SpecMap is 1-dimensional,
+      simply transforming the spectral axis values. This means that the
+      same source position will always be used by the SpecMap. However, this
+      may not be appropriate for an accurate description of a 3-D spectral
+      cube, where changes of spatial position can produce significant
+      changes in the Doppler shift introduced when transforming between
+      standards of rest. For this situation, a 3-dimensional SpecMap can
+      be created in which axes 2 and 3 correspond to the source RA and DEC
+      The SpecMap simply copies values for axes 2 and 3 from input to
+      output).
+   }
+   \sstsynopsis{
+      AstSpecMap $*$astSpecMap( int nin, int flags, const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         nin
+      }{
+         The number of inputs to the Mapping (this will also equal the
+         number of outputs). This value must be either 1 or 3. In either
+         case, the first input and output correspoindis the spectral axis.
+         For a 3-axis SpecMap, the second and third axes give the RA and
+         DEC (J2000 FK5) of the source. This positional information is
+         used by conversions which transform between standards of rest,
+         and replaces the \texttt{"} RA\texttt{"}  and \texttt{"} DEC\texttt{"}  arguments for the individual
+         conversions listed in description of the \texttt{"} SpecAdd\texttt{"}
+         function.
+      }
+      \sstsubsection{
+         flags
+      }{
+         This parameter is reserved for future use and should currently
+         always be set to zero.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new SpecMap. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+         If no initialisation is required, a zero-length string may be
+         supplied.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astSpecMap()
+      }{
+         A pointer to the new SpecMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The nature and units of the coordinate values supplied for the
+         first input (i.e. the spectral input) of a SpecMap must be appropriate
+         to the first conversion step applied by the SpecMap. For instance, if
+         the first conversion step is \texttt{"} FRTOVL\texttt{"}  (frequency to relativistic
+         velocity), then the coordinate values for the first input should
+         be frequency in units of Hz. Similarly, the nature and units of the
+         coordinate values returned by a SpecMap will be determined by the
+         last conversion step applied by the SpecMap. For instance, if the
+         last conversion step is \texttt{"} VLTOVO\texttt{"}  (relativistic velocity to optical
+         velocity), then the coordinate values for the first output will be optical
+         velocity in units of metres per second. See the description of the
+         astSpecAdd function for the units expected and returned by each
+         conversion.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astSphMap
+}{
+   Create a SphMap
+}{
+   \sstdescription{
+      This function creates a new \htmlref{SphMap}{SphMap} and optionally initialises
+      its attributes.
+
+      A SphMap is a \htmlref{Mapping}{Mapping} which transforms points from a
+      3-dimensional Cartesian coordinate system into a 2-dimensional
+      spherical coordinate system (longitude and latitude on a unit
+      sphere centred at the origin). It works by regarding the input
+      coordinates as position vectors and finding their intersection
+      with the sphere surface. The inverse transformation always
+      produces points which are a unit distance from the origin
+      (i.e. unit vectors).
+   }
+   \sstsynopsis{
+      AstSphMap $*$astSphMap( const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new SphMap. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astSphMap()
+      }{
+         A pointer to the new SphMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The spherical coordinates are longitude (positive
+         anti-clockwise looking from the positive latitude pole) and
+         latitude. The Cartesian coordinates are right-handed, with the x
+         axis (axis 1) at zero longitude and latitude, and the z axis
+         (axis 3) at the positive latitude pole.
+
+         \sstitem
+          At either pole, the longitude is set to the value of the
+         \htmlref{PolarLong}{PolarLong} attribute.
+
+         \sstitem
+          If the Cartesian coordinates are all zero, then the longitude
+         and latitude are set to the value AST\_\_BAD.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      Status Handling
+   }{
+      The protected interface to this function includes an extra
+      parameter at the end of the parameter list descirbed above. This
+      parameter is a pointer to the integer inherited status
+      variable: \texttt{"} int $*$status\texttt{"} .
+   }
+   \sstdiytopic{
+      Status Handling
+   }{
+      The protected interface to this function includes an extra
+      parameter at the end of the parameter list descirbed above. This
+      parameter is a pointer to the integer inherited status
+      variable: \texttt{"} int $*$status\texttt{"} .
+   }
+   \sstdiytopic{
+      Status Handling
+   }{
+      The protected interface to this function includes an extra
+      parameter at the end of the parameter list descirbed above. This
+      parameter is a pointer to the integer inherited status
+      variable: \texttt{"} int $*$status\texttt{"} .
+   }
+}
+\sstroutine{
+   astStatus
+}{
+   Obtain the current AST error status value
+}{
+   \sstdescription{
+      This function returns the current value of the AST error status.
+   }
+   \sstsynopsis{
+      int astStatus
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astStatus
+      }{
+         The AST error status value.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If the AST error status is set to an error value (after an
+         error), most AST functions will not execute and will simply
+         return without action. To clear the error status and restore
+         normal behaviour, use \htmlref{astClearStatus}{astClearStatus}.
+      }
+   }
+}
+\sstroutine{
+   astStcCatalogEntryLocation
+}{
+   Create a StcCatalogEntryLocation
+}{
+   \sstdescription{
+      This function creates a new \htmlref{StcCatalogEntryLocation}{StcCatalogEntryLocation} and optionally initialises its
+      attributes.
+
+      The StcCatalogEntryLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe
+      the coverage of the datasets contained in some VO resource.
+
+      See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html
+   }
+   \sstsynopsis{
+      AstStcCatalogEntryLocation $*$astStcCatalogEntryLocation( AstRegion $*$region,
+                   int ncoords, AstKeyMap $*$coords[], const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         region
+      }{
+         Pointer to the encapsulated \htmlref{Region}{Region}.
+      }
+      \sstsubsection{
+         ncoords
+      }{
+         The length of the \texttt{"} coords\texttt{"}  array. Supply zero if \texttt{"} coords\texttt{"}  is NULL.
+      }
+      \sstsubsection{
+         coords
+      }{
+         Pointer to an array holding \texttt{"} ncoords\texttt{"}  AstKeyMap pointers (if \texttt{"} ncoords\texttt{"}
+         is zero, the supplied value is ignored). Each supplied \htmlref{KeyMap}{KeyMap}
+         describes the contents of a single STC $<$AstroCoords$>$ element, and
+         should have elements with keys given by constants AST\_\_STCNAME,
+         AST\_\_STCVALUE, AST\_\_STCERROR, AST\_\_STCRES, AST\_\_STCSIZE,
+         AST\_\_STCPIXSZ. Any of these elements may be omitted, but no other
+         elements should be included. If supplied, the AST\_\_STCNAME element
+         should be a vector of character string pointers holding the \texttt{"} Name\texttt{"}
+         item for each axis in the coordinate system represented by
+         \texttt{"} region\texttt{"} .
+         Any other supplied elements should be scalar elements, each  holding
+         a pointer to a Region describing the associated item of ancillary
+         information (error, resolution, size, pixel size or value). These
+         Regions should describe a volume within the coordinate system
+         represented by \texttt{"} region\texttt{"} .
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new StcCatalogEntryLocation. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astStcCatalogEntryLocation()
+      }{
+         A pointer to the new StcCatalogEntryLocation.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A deep copy is taken of the supplied Region. This means that
+         any subsequent changes made to the encapsulated Region using the
+         supplied pointer will have no effect on the Stc.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astStcObsDataLocation
+}{
+   Create a StcObsDataLocation
+}{
+   \sstdescription{
+      This function creates a new \htmlref{StcObsDataLocation}{StcObsDataLocation} and optionally initialises its
+      attributes.
+
+      The StcObsDataLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe
+      the coverage of the datasets contained in some VO resource.
+
+      See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html
+   }
+   \sstsynopsis{
+      AstStcObsDataLocation $*$astStcObsDataLocation( AstRegion $*$region,
+                   int ncoords, AstKeyMap $*$coords[], const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         region
+      }{
+         Pointer to the encapsulated \htmlref{Region}{Region}.
+      }
+      \sstsubsection{
+         ncoords
+      }{
+         The length of the \texttt{"} coords\texttt{"}  array. Supply zero if \texttt{"} coords\texttt{"}  is NULL.
+      }
+      \sstsubsection{
+         coords
+      }{
+         Pointer to an array holding \texttt{"} ncoords\texttt{"}  AstKeyMap pointers (if \texttt{"} ncoords\texttt{"}
+         is zero, the supplied value is ignored). Each supplied \htmlref{KeyMap}{KeyMap}
+         describes the contents of a single STC $<$AstroCoords$>$ element, and
+         should have elements with keys given by constants AST\_\_STCNAME,
+         AST\_\_STCVALUE, AST\_\_STCERROR, AST\_\_STCRES, AST\_\_STCSIZE,
+         AST\_\_STCPIXSZ. Any of these elements may be omitted, but no other
+         elements should be included. If supplied, the AST\_\_STCNAME element
+         should be a vector of character string pointers holding the \texttt{"} Name\texttt{"}
+         item for each axis in the coordinate system represented by
+         \texttt{"} region\texttt{"} .
+         Any other supplied elements should be scalar elements, each  holding
+         a pointer to a Region describing the associated item of ancillary
+         information (error, resolution, size, pixel size or value). These
+         Regions should describe a volume within the coordinate system
+         represented by \texttt{"} region\texttt{"} .
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new StcObsDataLocation. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astStcObsDataLocation()
+      }{
+         A pointer to the new StcObsDataLocation.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A deep copy is taken of the supplied Region. This means that
+         any subsequent changes made to the encapsulated Region using the
+         supplied pointer will have no effect on the Stc.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astStcResourceProfile
+}{
+   Create a StcResourceProfile
+}{
+   \sstdescription{
+      This function creates a new \htmlref{StcResourceProfile}{StcResourceProfile} and optionally initialises its
+      attributes.
+
+      The StcResourceProfile class is a sub-class of \htmlref{Stc}{Stc} used to describe
+      the coverage of the datasets contained in some VO resource.
+
+      See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html
+   }
+   \sstsynopsis{
+      AstStcResourceProfile $*$astStcResourceProfile( AstRegion $*$region,
+                   int ncoords, AstKeyMap $*$coords[], const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         region
+      }{
+         Pointer to the encapsulated \htmlref{Region}{Region}.
+      }
+      \sstsubsection{
+         ncoords
+      }{
+         The length of the \texttt{"} coords\texttt{"}  array. Supply zero if \texttt{"} coords\texttt{"}  is NULL.
+      }
+      \sstsubsection{
+         coords
+      }{
+         Pointer to an array holding \texttt{"} ncoords\texttt{"}  AstKeyMap pointers (if \texttt{"} ncoords\texttt{"}
+         is zero, the supplied value is ignored). Each supplied \htmlref{KeyMap}{KeyMap}
+         describes the contents of a single STC $<$AstroCoords$>$ element, and
+         should have elements with keys given by constants AST\_\_STCNAME,
+         AST\_\_STCVALUE, AST\_\_STCERROR, AST\_\_STCRES, AST\_\_STCSIZE,
+         AST\_\_STCPIXSZ. Any of these elements may be omitted, but no other
+         elements should be included. If supplied, the AST\_\_STCNAME element
+         should be a vector of character string pointers holding the \texttt{"} Name\texttt{"}
+         item for each axis in the coordinate system represented by
+         \texttt{"} region\texttt{"} .
+         Any other supplied elements should be scalar elements, each  holding
+         a pointer to a Region describing the associated item of ancillary
+         information (error, resolution, size, pixel size or value). These
+         Regions should describe a volume within the coordinate system
+         represented by \texttt{"} region\texttt{"} .
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new StcResourceProfile. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astStcResourceProfile()
+      }{
+         A pointer to the new StcResourceProfile.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A deep copy is taken of the supplied Region. This means that
+         any subsequent changes made to the encapsulated Region using the
+         supplied pointer will have no effect on the Stc.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      Status Handling
+   }{
+      The protected interface to this function includes an extra
+      parameter at the end of the parameter list descirbed above. This
+      parameter is a pointer to the integer inherited status
+      variable: \texttt{"} int $*$status\texttt{"} .
+   }
+}
+\sstroutine{
+   astStcSearchLocation
+}{
+   Create a StcSearchLocation
+}{
+   \sstdescription{
+      This function creates a new \htmlref{StcSearchLocation}{StcSearchLocation} and optionally initialises its
+      attributes.
+
+      The StcSearchLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe
+      the coverage of a VO query.
+
+      See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html
+   }
+   \sstsynopsis{
+      AstStcResourceProfile $*$astStcSearchLocation( AstRegion $*$region,
+                    int ncoords, AstKeyMap $*$coords[], const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         region
+      }{
+         Pointer to the encapsulated \htmlref{Region}{Region}.
+      }
+      \sstsubsection{
+         ncoords
+      }{
+         The length of the \texttt{"} coords\texttt{"}  array. Supply zero if \texttt{"} coords\texttt{"}  is NULL.
+      }
+      \sstsubsection{
+         coords
+      }{
+         Pointer to an array holding \texttt{"} ncoords\texttt{"}  AstKeyMap pointers (if \texttt{"} ncoords\texttt{"}
+         is zero, the supplied value is ignored). Each supplied \htmlref{KeyMap}{KeyMap}
+         describes the contents of a single STC $<$AstroCoords$>$ element, and
+         should have elements with keys given by constants AST\_\_STCNAME,
+         AST\_\_STCVALUE, AST\_\_STCERROR, AST\_\_STCRES, AST\_\_STCSIZE,
+         AST\_\_STCPIXSZ. Any of these elements may be omitted, but no other
+         elements should be included. If supplied, the AST\_\_STCNAME element
+         should be a vector of character string pointers holding the \texttt{"} Name\texttt{"}
+         item for each axis in the coordinate system represented by
+         \texttt{"} region\texttt{"} .
+         Any other supplied elements should be scalar elements, each  holding
+         a pointer to a Region describing the associated item of ancillary
+         information (error, resolution, size, pixel size or value). These
+         Regions should describe a volume within the coordinate system
+         represented by \texttt{"} region\texttt{"} .
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new StcSearchLocation. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astStcSearchLocation()
+      }{
+         A pointer to the new StcSearchLocation.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A deep copy is taken of the supplied Region. This means that
+         any subsequent changes made to the encapsulated Region using the
+         supplied pointer will have no effect on the Stc.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      Status Handling
+   }{
+      The protected interface to this function includes an extra
+      parameter at the end of the parameter list descirbed above. This
+      parameter is a pointer to the integer inherited status
+      variable: \texttt{"} int $*$status\texttt{"} .
+   }
+}
+\sstroutine{
+   astStcsChan
+}{
+   Create an StcsChan
+}{
+   \sstdescription{
+      This function creates a new \htmlref{StcsChan}{StcsChan} and optionally initialises
+      its attributes.
+
+      A StcsChan is a specialised form of \htmlref{Channel}{Channel} which supports STC-S
+      I/O operations. Writing an \htmlref{Object}{Object} to an StcsChan (using
+      \htmlref{astWrite}{astWrite}) will, if the Object is suitable, generate an
+      STC-S description of that Object, and reading from an StcsChan will
+      create a new Object from its STC-S description.
+
+      Normally, when you use an StcsChan, you should provide \texttt{"} source\texttt{"}
+      and \texttt{"} sink\texttt{"}  functions which connect it to an external data store
+      by reading and writing the resulting text. These functions
+      should perform any conversions needed between external character
+      encodings and the internal ASCII encoding. If no such functions
+      are supplied, a Channel will read from standard input and write
+      to standard output.
+
+      Alternatively, an \htmlref{XmlChan}{XmlChan} can be told to read or write from
+      specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes,
+      in which case no sink or source function need be supplied.
+   }
+   \sstsynopsis{
+      AstStcsChan $*$astStcsChan( const char $*$($*$ source)( void ),
+                                void ($*$ sink)( const char $*$ ),
+                                const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         source
+      }{
+         Pointer to a source function that takes no arguments and
+         returns a pointer to a null-terminated string.  If no value
+         has been set for the SourceFile attribute, this function
+         will be used by the StcsChan to obtain lines of input text. On
+         each invocation, it should return a pointer to the next input
+         line read from some external data store, and a NULL pointer
+         when there are no more lines to read.
+
+         If \texttt{"} source\texttt{"}  is NULL and no value has been set for the SourceFile
+         attribute, the StcsChan will read from standard input instead.
+      }
+      \sstsubsection{
+         sink
+      }{
+         Pointer to a sink function that takes a pointer to a
+         null-terminated string as an argument and returns void.
+         If no value has been set for the SinkFile attribute, this
+         function will be used by the StcsChan to deliver lines of
+         output text. On each invocation, it should deliver the
+         contents of the string supplied to some external data store.
+
+         If \texttt{"} sink\texttt{"}  is NULL, and no value has been set for the SinkFile
+         attribute, the StcsChan will write to standard output instead.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new StcsChan. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astStcsChan()
+      }{
+         A pointer to the new StcsChan.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If the external data source or sink uses a character encoding
+         other than ASCII, the supplied source and sink functions should
+         translate between the external character encoding and the internal
+         ASCII encoding used by AST.
+
+         \sstitem
+          A null Object pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astStripEscapes
+}{
+   Remove AST escape sequences from a string
+}{
+   \sstdescription{
+      This function removes AST escape sequences from a supplied string,
+      returning the resulting text as the function value. The behaviour
+      of this function can be controlled by invoking the
+      \htmlref{astEscapes}{astEscapes} function,
+      which can be used to supress or enable the removal of escape
+      sequences by this function.
+
+      AST escape sequences are used by the \htmlref{Plot}{Plot} class to modify the
+      appearance and position of sub-strings within a plotted text string.
+      See the \texttt{"} \htmlref{Escape}{Escape}\texttt{"}  attribute for further information.
+   }
+   \sstsynopsis{
+      const char $*$astStripEscapes( const char $*$text )
+   }
+   \sstparameters{
+      \sstsubsection{
+         text
+      }{
+         Pointer to the string to be checked.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astStripEscapes()
+      }{
+         Pointer to the modified string. If no escape sequences were found
+         in the supplied string, then a copy of the supplied pointer is
+         returned. Otherwise, the pointer will point to a static buffer
+         holding the modified text. This text will be over-written by
+         subsequent invocations of this function. If the astEscapes function
+         has been called indicating that escape sequences should not be
+         stripped, then the supplied string is returned without change.
+      }
+   }
+}
+\sstroutine{
+   astSwitchMap
+}{
+   Create a SwitchMap
+}{
+   \sstdescription{
+      This function creates a new \htmlref{SwitchMap}{SwitchMap} and optionally initialises
+      its attributes.
+
+      A SwitchMap is a \htmlref{Mapping}{Mapping} which represents a set of alternate
+      Mappings, each of which is used to transform positions within a
+      particular region of the input or output coordinate system of the
+      SwitchMap.
+
+      A SwitchMap can encapsulate any number of Mappings, but they must
+      all have the same number of inputs (\htmlref{Nin}{Nin} attribute value) and the
+      same number of outputs (\htmlref{Nout}{Nout} attribute value). The SwitchMap itself
+      inherits these same values for its Nin and Nout attributes. Each of
+      these Mappings represents a \texttt{"} route\texttt{"}  through the switch, and are
+      referred to as \texttt{"} route\texttt{"}  Mappings below. Each route Mapping transforms
+      positions between the input and output coordinate space of the entire
+      SwitchMap, but only one Mapping will be used to transform any given
+      position. The selection of the appropriate route Mapping to use with
+      any given input position is made by another Mapping, called the
+      \texttt{"} selector\texttt{"}  Mapping. Each SwitchMap encapsulates two selector
+      Mappings in addition to its route Mappings; one for use with the
+      SwitchMap\texttt{'} s forward transformation (called the \texttt{"} forward selector
+      Mapping\texttt{"} ), and one for use with the SwitchMap\texttt{'} s inverse transformation
+      (called the \texttt{"} inverse selector Mapping\texttt{"} ). The forward selector Mapping
+      must have the same number of inputs as the route Mappings, but
+      should have only one output. Likewise, the inverse selector Mapping
+      must have the same number of outputs as the route Mappings, but
+      should have only one input.
+
+      When the SwitchMap is used to transform a position in the forward
+      direction (from input to output), each supplied input position is
+      first transformed by the forward transformation of the forward selector
+      Mapping. This produces a single output value for each input position
+      referred to as the selector value. The nearest integer to the selector
+      value is found, and is used to index the array of route Mappings (the
+      first supplied route Mapping has index 1, the second route Mapping has
+      index 2, etc). If the nearest integer to the selector value is less
+      than 1 or greater than the number of route Mappings, then the SwitchMap
+      output position is set to a value of AST\_\_BAD on every axis. Otherwise,
+      the forward transformation of the selected route Mapping is used to
+      transform the supplied input position to produce the SwitchMap output
+      position.
+
+      When the SwitchMap is used to transform a position in the inverse
+      direction (from \texttt{"} output\texttt{"}  to \texttt{"} input\texttt{"} ), each supplied \texttt{"} output\texttt{"}  position
+      is first transformed by the inverse transformation of the inverse
+      selector Mapping. This produces a selector value for each \texttt{"} output\texttt{"}
+      position. Again, the nearest integer to the selector value is found,
+      and is used to index the array of route Mappings. If this selector
+      index value is within the bounds of the array of route Mappings, then
+      the inverse transformation of the selected route Mapping is used to
+      transform the supplied \texttt{"} output\texttt{"}  position to produce the SwitchMap
+      \texttt{"} input\texttt{"}  position. If the selector index value is outside the bounds
+      of the array of route Mappings, then the SwitchMap \texttt{"} input\texttt{"}  position is
+      set to a value of AST\_\_BAD on every axis.
+
+      In practice, appropriate selector Mappings should be chosen to
+      associate a different route Mapping with each region of coordinate
+      space. Note that the \htmlref{SelectorMap}{SelectorMap} class of Mapping is particularly
+      appropriate for this purpose.
+
+      If a compound Mapping contains a SwitchMap in series with its own
+      inverse, the combination of the two adjacent SwitchMaps will be
+      replaced by a \htmlref{UnitMap}{UnitMap} when the compound Mapping is simplified using
+      \htmlref{astSimplify}{astSimplify}.
+   }
+   \sstsynopsis{
+      AstSwitchMap $*$astSwitchMap( AstMapping $*$fsmap, AstMapping $*$ismap,
+                                  int nroute, AstMapping $*$routemaps[],
+                                  const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         fsmap
+      }{
+         Pointer to the forward selector Mapping. This must have a
+         defined forward transformation, but need not have a defined
+         inverse transformation. It must have one output, and the number of
+         inputs must match the number of inputs of each of the supplied
+         route Mappings.
+         NULL
+         may be supplied, in which case the SwitchMap will have an undefined
+         forward Mapping.
+      }
+      \sstsubsection{
+         ismap
+      }{
+         Pointer to the inverse selector Mapping. This must have a
+         defined inverse transformation, but need not have a defined
+         forward transformation. It must have one input, and the number of
+         outputs must match the number of outputs of each of the supplied
+         route Mappings.
+         NULL
+         may be supplied, in which case the SwitchMap will have an undefined
+         inverse Mapping.
+      }
+      \sstsubsection{
+         nroute
+      }{
+         The number of supplied route Mappings.
+      }
+      \sstsubsection{
+         routemaps
+      }{
+         An array of pointers to the route Mappings. All the supplied
+         route Mappings must have common values for the Nin and Nout
+         attributes, and these values define the number of inputs and
+         outputs of the SwitchMap.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new SwitchMap. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astSwitchMap()
+      }{
+         A pointer to the new SwitchMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Note that the component Mappings supplied are not copied by
+         astSwitchMap (the new SwitchMap simply retains a reference to
+         them). They may continue to be used for other purposes, but
+         should not be deleted. If a SwitchMap containing a copy of its
+         component Mappings is required, then a copy of the SwitchMap should
+         be made using \htmlref{astCopy}{astCopy}.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astTable
+}{
+   Create a Table
+}{
+   \sstdescription{
+      This function creates a new empty \htmlref{Table}{Table} and optionally initialises
+      its attributes.
+
+      The Table class is a type of \htmlref{KeyMap}{KeyMap} that represents a two-dimensional
+      table of values. The
+      astMapGet... and astMapPut...
+      methods provided by the KeyMap class should be used for storing and
+      retrieving values from individual cells within a Table. Each entry
+      in the KeyMap represents a single cell of the table and has an
+      associated key of the form \texttt{"} $<$COL$>$(i)\texttt{"}  where \texttt{"} $<$COL$>$\texttt{"}  is the name of a
+      table column and \texttt{"} i\texttt{"}  is the row index (the first row is row 1). Keys
+      of this form should always be used when using KeyMap methods to access
+      entries within a Table.
+
+      Columns must be declared using the
+      \htmlref{astAddColumn}{astAddColumn}
+      method before values can be stored within them. This also fixes the
+      type and shape of the values that may be stored in any cell of the
+      column. Cells may contain scalar or vector values of any data type
+      supported by the KeyMap class. Multi-dimensional arrays may also be
+      stored, but these must be vectorised when storing and retrieving
+      them within a table cell. All cells within a single column must
+      have the same type and shape (specified when the column is declared).
+
+      Tables may have parameters that describe global properties of the
+      entire table. These are stored as entries in the parent KeyMap and
+      can be access using the get and set method of the KeyMap class.
+      However, parameters must be declared using the
+      \htmlref{astAddParameter}{astAddParameter}
+      method before being accessed.
+
+      Note - since accessing entries within a KeyMap is a relatively slow
+      process, it is not recommended to use the Table class to store
+      very large tables.
+   }
+   \sstsynopsis{
+      AstTable $*$astTable( const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new Table. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astTable()
+      }{
+         A pointer to the new Table.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      Status Handling
+   }{
+      The protected interface to this function includes an extra
+      parameter at the end of the parameter list described above. This
+      parameter is a pointer to the integer inherited status
+      variable: \texttt{"} int $*$status\texttt{"} .
+   }
+}
+\sstroutine{
+   astTableSource
+}{
+   Register a source function for accessing tables in FITS files
+}{
+   \sstdescription{
+      This function can be used to register a call-back function
+      with a \htmlref{FitsChan}{FitsChan}. The registered
+      function
+      is called when-ever the FitsChan needs to read information from a
+      binary table contained within a FITS file. This occurs if the
+      \htmlref{astRead}{astRead}
+      function is invoked to read a \htmlref{FrameSet}{FrameSet} from a set of FITS headers
+      that use the \texttt{"} -TAB\texttt{"}  algorithm to describe one or more axes. Such
+      axes use a FITS binary table to store a look-up table of axis values.
+      The FitsChan will fail to read such axes unless the \texttt{"} \htmlref{TabOK}{TabOK}\texttt{"}  attribute
+      is set to a non-zero positive integer value. The table containing the
+      axis values must be made available to the FitsChan either by storing
+      the table contents in the FitsChan (using
+      \htmlref{astPutTables}{astPutTables} or \htmlref{astPutTable}{astPutTable}) prior to invoking astRead
+      or by registering a call-back
+      function using astTableSource.
+      The first method is possibly simpler, but requires that the name of
+      the extension containing the table be known in advance. Since the
+      table name is embedded in the FITS headers, the name is often not
+      known in advance. If a call-back is registered, the FitsChan will
+      determine the name of the required table and invoke the call-back
+      function
+      to supply the table at the point where it is needed (i.e. within
+      the astRead method).
+   }
+   \sstsynopsis{
+      void astTableSource( AstFitsChan $*$this,
+                           void ($*$ tabsource)( AstFitsChan $*$, const char $*$,
+                                               int, int, int $*$ ) )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FitsChan.
+      }
+      \sstsubsection{
+         tabsource
+      }{
+         Pointer to the table source function to use.
+         It takes five arguments - the first is a pointer to the
+         FitsChan, the second is a string holding the name of the
+         FITS extension containing the required binary table (\texttt{"} EXTNAME\texttt{"} ),
+         the third is the integer FITS \texttt{"} EXTVER\texttt{"}  header value for the
+         required extension, the fourth is the integer FITS \texttt{"} EXTLEVEL\texttt{"}
+         header value for the required extension, and the fifth is
+         a pointer to
+         the inherited integer status value.
+
+         The call-back should read the entire contents (header and data)
+         of the binary table in the named extension of the external FITS
+         file, storing the contents in a newly created \htmlref{FitsTable}{FitsTable} object. It
+         should then store this FitsTable in the FitsChan using the
+         astPutTables or astPutTable
+         method, and finally annull its local copy of the FitsTable pointer.
+         If the table cannot be read for any reason, or if any other
+         error occurs, it should return a non-zero integer for the final
+         (third) argument.
+
+         If \texttt{"} tabsource\texttt{"}  is NULL,
+         any registered call-back function will be removed.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Application code can pass arbitrary data (such as file
+         descriptors, etc) to the table source function using the
+         \htmlref{astPutChannelData}{astPutChannelData} function. The source function should use
+         the \htmlref{astChannelData}{astChannelData} macro to retrieve this data.
+      }
+   }
+}
+\sstroutine{
+   astTest
+}{
+   Test if an Object attribute value is set
+}{
+   \sstdescription{
+      This function returns a boolean result (0 or 1) to indicate
+      whether a value has been explicitly set for one of an \htmlref{Object}{Object}\texttt{'} s
+      attributes.
+   }
+   \sstsynopsis{
+      int astTest( AstObject $*$this, const char $*$attrib )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Object.
+      }
+      \sstsubsection{
+         attrib
+      }{
+         Pointer to a null-terminated character string containing
+         the name of the attribute to be tested.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         This function applies to all Objects.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astTest()
+      }{
+         One if a value has previously been explicitly set for the attribute
+         (and hasn\texttt{'} t been cleared), otherwise zero.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Attribute names are not case sensitive and may be surrounded
+         by white space.
+
+         \sstitem
+          A value of zero will be returned if this function is invoked
+         with the AST error status set, or if it should fail for any reason.
+
+         \sstitem
+          A value of zero will also be returned if this function is used
+         to test a read-only attribute, although no error will result.
+      }
+   }
+}
+\sstroutine{
+   astTestFits
+}{
+   See if a named keyword has a defined value in a FitsChan
+}{
+   \sstdescription{
+      This function serches for a named keyword in a \htmlref{FitsChan}{FitsChan}. If found,
+      and if the keyword has a value associated with it, a
+      non-zero
+      value is returned. If the keyword is not found, or if it does not
+      have an associated value, a
+      zero
+      value is returned.
+   }
+   \sstsynopsis{
+      int astTestFits( AstFitsChan $*$this, const char $*$name, int $*$there )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FitsChan.
+      }
+      \sstsubsection{
+         name
+      }{
+         Pointer to a null-terminated character string
+         containing the FITS keyword name. This may be a complete FITS
+         header card, in which case the keyword to use is extracted from
+         it. No more than 80 characters are read from this string. If
+         NULL
+         is supplied, the current card is tested.
+      }
+      \sstsubsection{
+         there
+      }{
+         Pointer to an integer which will be returned holding a non-zero
+         value if the keyword was found in the header, and zero otherwise.
+         This parameter allows a distinction to be made between the case
+         where a keyword is not present, and the case where a keyword is
+         present but has no associated value.
+         A NULL pointer may be supplied if this information is not
+         required.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astTestFits()
+      }{
+         A value of zero
+         is returned if the keyword was not found in the FitsChan or has
+         no associated value. Otherwise, a value of
+         one
+         is returned.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The current card is left unchanged by this function.
+
+         \sstitem
+          The card following the current card is checked first. If this is
+         not the required card, then the rest of the FitsChan is searched,
+         starting with the first card added to the FitsChan. Therefore cards
+         should be accessed in the order they are stored in the FitsChan (if
+         possible) as this will minimise the time spent searching for cards.
+
+         \sstitem
+          An error will be reported if the keyword name does not conform
+         to FITS requirements.
+
+         \sstitem
+          Zero
+         is returned as the function value if an error has already occurred,
+         or if this function should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astText
+}{
+   Draw a text string for a Plot
+}{
+   \sstdescription{
+      This function draws a string of text at a position specified in
+      the physical coordinate system of a \htmlref{Plot}{Plot}. The physical position
+      is transformed into graphical coordinates to determine where the
+      text should appear within the plotting area.
+   }
+   \sstsynopsis{
+      void astText( AstPlot $*$this, const char $*$text, const double pos[],
+                    const float up[], const char $*$just )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Plot.
+      }
+      \sstsubsection{
+         text
+      }{
+         Pointer to a null-terminated character string containing the
+         text to be drawn. Trailing white space is ignored.
+      }
+      \sstsubsection{
+         pos
+      }{
+         An array, with one element for each axis of the Plot, giving
+         the physical coordinates of the point where the reference
+         position of the text string is to be placed.
+      }
+      \sstsubsection{
+         up
+      }{
+         An array holding the components of a vector in the \texttt{"} up\texttt{"}
+         direction of the text (in graphical coordinates). For
+         example, to get horizontal text, the vector \{0.0f,1.0f\} should
+         be supplied. For a basic Plot, 2 values should be supplied. For
+         a \htmlref{Plot3D}{Plot3D}, 3 values should be supplied, and the actual up vector
+         used is the projection of the supplied up vector onto the text plane
+         specified by the current value of the Plot3D\texttt{'} s Norm attribute.
+      }
+      \sstsubsection{
+         just
+      }{
+         Pointer to a null-terminated character string identifying the
+         reference point for the text being drawn. The first character in
+         this string identifies the reference position in the \texttt{"} up\texttt{"}  direction
+         and may be \texttt{"} B\texttt{"}  (baseline), \texttt{"} C\texttt{"}  (centre), \texttt{"} T\texttt{"}  (top) or \texttt{"} M\texttt{"}  (bottom).
+         The second character identifies the side-to-side reference position
+         and may be \texttt{"} L\texttt{"}  (left), \texttt{"} C\texttt{"}  (centre) or \texttt{"} R\texttt{"}  (right ). The string is
+         case-insensitive, and only the first two characters are significant.
+
+         For example, a value of \texttt{"} BL\texttt{"}  means that the left end of the
+         baseline of the original (un-rotated) text is to be drawn at the
+         position given by \texttt{"} pos\texttt{"} .
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The Plot3D class currently does not interpret graphical escape
+         sequences contained within text displayed using this method.
+
+         \sstitem
+          Text is not drawn at positions which have any coordinate equal
+         to the value AST\_\_BAD (or where the transformation into
+         graphical coordinates yields coordinates containing the value
+         AST\_\_BAD).
+
+         \sstitem
+          If the plotting position is clipped (see \htmlref{astClip}{astClip}), then no
+         text is drawn.
+
+         \sstitem
+          An error results if the base \htmlref{Frame}{Frame} of the Plot is not
+         2-dimensional or (for a Plot3D) 3-dimensional.
+
+         \sstitem
+          An error also results if the transformation between the
+         current and base Frames of the Plot is not defined (i.e. the
+         Plot\texttt{'} s \htmlref{TranInverse}{TranInverse} attribute is zero).
+      }
+   }
+}
+\sstroutine{
+   astThread
+}{
+   Determine the thread that owns an Object
+}{
+   \sstdescription{
+      Returns an integer that indicates whether the supplied \htmlref{Object}{Object} (or
+      Object pointer) is currently unlocked, or is currently locked by
+      the running thread, or another thread.
+   }
+   \sstsynopsis{
+      int astThread( AstObject $*$this, int ptr )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Object to be checked.
+      }
+      \sstsubsection{
+         ptr
+      }{
+         If non-zero, returns information about the supplied Object
+         pointer, rather than the Object structure itself. See \texttt{"} Object
+         Pointers and Structures\texttt{"}  below.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astThread()
+      }{
+         A value of AST\_\_UNLOCKED is returned if the Object (or pointer)
+         is currently unlocked (i.e. has been unlocked using \htmlref{astUnlock}{astUnlock}
+         but has not yet been locked using \htmlref{astLock}{astLock}). A value of
+         AST\_\_RUNNING is returned if the Object (or pointer) is currently
+         locked by the running thread. A value of AST\_\_OTHER is returned
+         if the Object (or pointer) is currently locked by the another
+         thread.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This function attempts to execute even if the global error
+         status is set, but no further error report will be made if it
+         subsequently fails under these circumstances.
+
+         \sstitem
+          This function is only available in the C interface.
+
+         \sstitem
+          This function always returns AST\_\_RUNNING if the AST library has
+         been built without POSIX thread support (i.e. the \texttt{"} -with-pthreads\texttt{"}
+         option was not specified when running the \texttt{"} configure\texttt{"}  script).
+      }
+   }
+   \sstdiytopic{
+      Object Pointers and Structures
+   }{
+      At any one time, an AST Object can have several distinct pointers,
+      any one of which can be used to access the Object structure. For
+      instance, the \htmlref{astClone}{astClone} function will produce a new distinct pointer
+      for a given Object. In fact, an AST \texttt{"} pointer\texttt{"}  is not a real pointer
+      at all - it is an identifier for a \texttt{"} handle\texttt{"}  structure, encoded to
+      make it look like a pointer. Each handle contains (amongst othere
+      things) a \texttt{"} real\texttt{"}  pointer to the Object structure. This allows more
+      than one handle to refer to the same Object structure. So when you
+      call astClone (for instance) you get back an identifier for a new
+      handle that refers to the same Object as the supplied handle.
+
+      In order to use an Object for anything useful, it must be locked
+      for use by the running thread (either implicitly at creation or
+      explicitly using astLock). The identity of the thread is stored in
+      both the Object structure, and in the handle that was passed to
+      astLock (or returned by the constructor function). Thus it is
+      possible for a thread to have active pointers for Objects that are
+      currently locked by another thread. In general, if such a pointer is
+      passed to an AST function an error will be reported indicating that
+      the Object is currently locked by another thread. The two exceptions
+      to this is that \htmlref{astAnnul}{astAnnul} can be used to annull such a pointer, and
+      this function can be used to return information about the pointer.
+
+      The other practical consequence of this is that when \htmlref{astEnd}{astEnd} is
+      called, all active pointers currently owned by the running thread
+      (at the current context level) are annulled. This includes pointers
+      for Objects that are currently locked by other threads.
+
+      If the \texttt{"} ptr\texttt{"}  parameter is zero, then the returned value describes
+      the Object structure itself. If \texttt{"} ptr\texttt{"}  is non-zero, then the returned
+      value describes the supplied Object pointer (i.e. handle), rather
+      than the Object structure.
+   }
+}
+\sstroutine{
+   astTimeAdd
+}{
+   Add a time coordinate conversion to a TimeMap
+}{
+   \sstdescription{
+      This function adds one of the standard time coordinate
+      system conversions listed below to an existing \htmlref{TimeMap}{TimeMap}.
+
+      When a TimeMap is first created (using \htmlref{astTimeMap}{astTimeMap}), it simply
+      performs a unit (null) \htmlref{Mapping}{Mapping}. By using astTimeAdd (repeatedly
+      if necessary), one or more coordinate conversion steps may then
+      be added, which the TimeMap will perform in sequence. This allows
+      multi-step conversions between a variety of time coordinate
+      systems to be assembled out of the building blocks provided by
+      this class.
+
+      Normally, if a TimeMap\texttt{'} s \htmlref{Invert}{Invert} attribute is zero (the default),
+      then its forward transformation is performed by carrying out
+      each of the individual coordinate conversions specified by
+      astTimeAdd in the order given (i.e. with the most recently added
+      conversion applied last).
+
+      This order is reversed if the TimeMap\texttt{'} s Invert attribute is
+      non-zero (or if the inverse transformation is requested by any
+      other means) and each individual coordinate conversion is also
+      replaced by its own inverse. This process inverts the overall
+      effect of the TimeMap. In this case, the first conversion to be
+      applied would be the inverse of the one most recently added.
+   }
+   \sstsynopsis{
+      void astTimeAdd( AstTimeMap $*$this, const char $*$cvt, int narg,
+                       const double args[] )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the TimeMap.
+      }
+      \sstsubsection{
+         cvt
+      }{
+         Pointer to a null-terminated string which identifies the
+         time coordinate conversion to be added to the
+         TimeMap. See the \texttt{"} Available Conversions\texttt{"}  section for details of
+         those available.
+      }
+      \sstsubsection{
+         narg
+      }{
+         The number of argument values supplied in the
+         \texttt{"} args\texttt{"}  array.
+      }
+      \sstsubsection{
+         args
+      }{
+         An array containing argument values for the time
+         coordinate conversion. The number of arguments required, and
+         hence the number of array elements used, depends on the
+         conversion specified (see the \texttt{"} Available Conversions\texttt{"}
+         section). This array is ignored
+         and a NULL pointer may be supplied
+         if no arguments are needed.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          When assembling a multi-stage conversion, it can sometimes be
+         difficult to determine the most economical conversion path. A solution
+         to this is to include all the steps which are (logically) necessary,
+         but then to use
+         \htmlref{astSimplify}{astSimplify} to simplify the resulting
+         TimeMap. The simplification process will eliminate any steps
+         which turn out not to be needed.
+
+         \sstitem
+          This function does not check to ensure that the sequence of
+         coordinate conversions added to a TimeMap is physically
+         meaningful.
+      }
+   }
+   \sstdiytopic{
+      Available Conversions
+   }{
+      The following strings (which are case-insensitive) may be supplied
+      via the \texttt{"} cvt\texttt{"}  parameter to indicate which time coordinate
+      conversion is to be added to the TimeMap. Where arguments are needed by
+      the conversion, they are listed in parentheses. Values for
+      these arguments should be given, via the \texttt{"} args\texttt{"}  array, in the
+      order indicated. Units and argument names are described at the end of
+      the list of conversions, and \texttt{"} MJD\texttt{"}  means Modified Julian Date.
+
+      \sstitemlist{
+
+         \sstitem
+          \texttt{"} MJDTOMJD\texttt{"}   (MJDOFF1,MJDOFF2): Convert MJD from one offset to another.
+
+         \sstitem
+          \texttt{"} MJDTOJD\texttt{"}   (MJDOFF,JDOFF): Convert MJD to Julian Date.
+
+         \sstitem
+          \texttt{"} JDTOMJD\texttt{"}   (JDOFF,MJDOFF): Convert Julian Date to MJD.
+
+         \sstitem
+          \texttt{"} MJDTOBEP\texttt{"}  (MJDOFF,BEPOFF): Convert MJD to Besselian epoch.
+
+         \sstitem
+          \texttt{"} BEPTOMJD\texttt{"}  (BEPOFF,MJDOFF): Convert Besselian epoch to MJD.
+
+         \sstitem
+          \texttt{"} MJDTOJEP\texttt{"}  (MJDOFF,JEPOFF): Convert MJD to Julian epoch.
+
+         \sstitem
+          \texttt{"} JEPTOMJD\texttt{"}  (JEPOFF,MJDOFF): Convert Julian epoch to MJD.
+
+         \sstitem
+          \texttt{"} TAITOUTC\texttt{"}  (MJDOFF,DTAI): Convert a TAI MJD to a UTC MJD.
+
+         \sstitem
+          \texttt{"} UTCTOTAI\texttt{"}  (MJDOFF,DTAI): Convert a UTC MJD to a TAI MJD.
+
+         \sstitem
+          \texttt{"} TAITOTT\texttt{"}   (MJDOFF): Convert a TAI MJD to a TT MJD.
+
+         \sstitem
+          \texttt{"} TTTOTAI\texttt{"}   (MJDOFF): Convert a TT MJD to a TAI MJD.
+
+         \sstitem
+          \texttt{"} TTTOTDB\texttt{"}   (MJDOFF,OBSLON,OBSLAT,OBSALT,DTAI): Convert a TT MJD to a TDB MJD.
+
+         \sstitem
+          \texttt{"} TDBTOTT\texttt{"}   (MJDOFF,OBSLON,OBSLAT,OBSALT,DTAI): Convert a TDB MJD to a TT MJD.
+
+         \sstitem
+          \texttt{"} TTTOTCG\texttt{"}   (MJDOFF): Convert a TT MJD to a TCG MJD.
+
+         \sstitem
+          \texttt{"} TCGTOTT\texttt{"}   (MJDOFF): Convert a TCG MJD to a TT MJD.
+
+         \sstitem
+          \texttt{"} TDBTOTCB\texttt{"}  (MJDOFF): Convert a TDB MJD to a TCB MJD.
+
+         \sstitem
+          \texttt{"} TCBTOTDB\texttt{"}  (MJDOFF): Convert a TCB MJD to a TDB MJD.
+
+         \sstitem
+          \texttt{"} UTTOGMST\texttt{"}  (MJDOFF): Convert a UT MJD to a GMST MJD.
+
+         \sstitem
+          \texttt{"} GMSTTOUT\texttt{"}  (MJDOFF): Convert a GMST MJD to a UT MJD.
+
+         \sstitem
+          \texttt{"} GMSTTOLMST\texttt{"}  (MJDOFF,OBSLON,OBSLAT): Convert a GMST MJD to a LMST MJD.
+
+         \sstitem
+          \texttt{"} LMSTTOGMST\texttt{"}  (MJDOFF,OBSLON,OBSLAT): Convert a LMST MJD to a GMST MJD.
+
+         \sstitem
+          \texttt{"} LASTTOLMST\texttt{"}  (MJDOFF,OBSLON,OBSLAT): Convert a GMST MJD to a LMST MJD.
+
+         \sstitem
+          \texttt{"} LMSTTOLAST\texttt{"}  (MJDOFF,OBSLON,OBSLAT): Convert a LMST MJD to a GMST MJD.
+
+         \sstitem
+          \texttt{"} UTTOUTC\texttt{"}  (DUT1): Convert a UT1 MJD to a UTC MJD.
+
+         \sstitem
+          \texttt{"} UTCTOUT\texttt{"}  (DUT1): Convert a UTC MJD to a UT1 MJD.
+
+         \sstitem
+          \texttt{"} LTTOUTC\texttt{"}  (LTOFF): Convert a Local Time MJD to a UTC MJD.
+
+         \sstitem
+          \texttt{"} UTCTOLT\texttt{"}  (LTOFF): Convert a UTC MJD to a Local Time MJD.
+
+      }
+      The units for the values processed by the above conversions are as
+      follows:
+
+      \sstitemlist{
+
+         \sstitem
+          Julian epochs and offsets: Julian years
+
+         \sstitem
+          Besselian epochs and offsets: Tropical years
+
+         \sstitem
+          Modified Julian Dates and offsets: days
+
+         \sstitem
+          Julian Dates and offsets: days
+
+      }
+      The arguments used in the above conversions are the zero-points
+      used by the
+      astTransform function.
+      The axis values supplied and returned by
+      astTransform
+      are offsets away from these zero-points:
+
+      \sstitemlist{
+
+         \sstitem
+          MJDOFF: The zero-point being used with MJD values.
+
+         \sstitem
+          JDOFF: The zero-point being used with Julian Date values.
+
+         \sstitem
+          BEPOFF: The zero-point being used with Besselian epoch values.
+
+         \sstitem
+          JEPOFF: The zero-point being used with Julian epoch values.
+
+         \sstitem
+          OBSLON: Observer longitude in radians ($+$ve westwards).
+
+         \sstitem
+          OBSLAT: Observer geodetic latitude (IAU 1975) in radians ($+$ve northwards).
+
+         \sstitem
+          OBSALT: Observer geodetic altitude (IAU 1975) in metres.
+
+         \sstitem
+          DTAI: The value of TAI-UTC (the value returned by astDat is used if
+         DTAI is AST\_\_BAD).
+
+         \sstitem
+          DUT1: The UT1-UTC value to use.
+
+         \sstitem
+          LTOFF: The offset between Local Time and UTC (in hours, positive
+         for time zones east of Greenwich).
+      }
+   }
+}
+\sstroutine{
+   astTimeFrame
+}{
+   Create a TimeFrame
+}{
+   \sstdescription{
+      This function creates a new \htmlref{TimeFrame}{TimeFrame} and optionally initialises
+      its attributes.
+
+      A TimeFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which
+      represents various coordinate systems used to describe positions in
+      time.
+
+      A TimeFrame represents a moment in time as either an Modified Julian
+      Date (MJD), a Julian Date (JD), a Besselian epoch or a Julian epoch,
+      as determined by the \htmlref{System}{System} attribute. Optionally, a zero point can be
+      specified (using attribute \htmlref{TimeOrigin}{TimeOrigin}) which results in the TimeFrame
+      representing time offsets from the specified zero point.
+
+      Even though JD and MJD are defined as being in units of days, the
+      TimeFrame class allows other units to be used (via the Unit attribute)
+      on the basis of simple scalings (60 seconds = 1 minute, 60 minutes = 1
+      hour, 24 hours = 1 day, 365.25 days = 1 year). Likewise, Julian epochs
+      can be described in units other than the usual years. Besselian epoch
+      are always represented in units of (tropical) years.
+
+      The \htmlref{TimeScale}{TimeScale} attribute allows the time scale to be specified (that
+      is, the physical proces used to define the rate of flow of time).
+      MJD, JD and Julian epoch can be used to represent a time in any
+      supported time scale. However, Besselian epoch may only be used with the
+      \texttt{"} TT\texttt{"}  (Terrestrial Time) time scale. The list of supported time scales
+      includes universal time and siderial time. Strictly, these represent
+      angles rather than time scales, but are included in the list since
+      they are in common use and are often thought of as time scales.
+
+      When a time value is formatted it can be formated either as a simple
+      floating point value, or as a Gregorian date (see the Format
+      attribute).
+   }
+   \sstsynopsis{
+      AstTimeFrame $*$astTimeFrame( const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new TimeFrame. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+         If no initialisation is required, a zero-length string may be
+         supplied.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astTimeFrame()
+      }{
+         A pointer to the new TimeFrame.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          When conversion between two TimeFrames is requested (as when
+         supplying TimeFrames to \htmlref{astConvert}{astConvert}),
+         account will be taken of the nature of the time coordinate systems
+         they represent, together with any qualifying time scale, offset,
+         unit, etc. The \htmlref{AlignSystem}{AlignSystem} and \htmlref{AlignTimeScale}{AlignTimeScale} attributes will also be
+         taken into account.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astTimeMap
+}{
+   Create a TimeMap
+}{
+   \sstdescription{
+      This function creates a new \htmlref{TimeMap}{TimeMap} and optionally initialises
+      its attributes.
+
+      A TimeMap is a specialised form of 1-dimensional \htmlref{Mapping}{Mapping} which can be
+      used to represent a sequence of conversions between standard time
+      coordinate systems.
+
+      When a TimeMap is first created, it simply performs a unit
+      (null) Mapping. Using the \htmlref{astTimeAdd}{astTimeAdd}
+      function, a series of coordinate conversion steps may then be
+      added. This allows multi-step conversions between a variety of
+      time coordinate systems to be assembled out of a set of building
+      blocks.
+
+      For details of the individual coordinate conversions available,
+      see the description of the astTimeAdd function.
+   }
+   \sstsynopsis{
+      AstTimeMap $*$astTimeMap( int flags, const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         flags
+      }{
+         This parameter is reserved for future use and should currently
+         always be set to zero.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new TimeMap. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+         If no initialisation is required, a zero-length string may be
+         supplied.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astTimeMap()
+      }{
+         A pointer to the new TimeMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The nature and units of the coordinate values supplied for the
+         first input (i.e. the time input) of a TimeMap must be appropriate
+         to the first conversion step applied by the TimeMap. For instance, if
+         the first conversion step is \texttt{"} MJDTOBEP\texttt{"}  (Modified Julian Date to
+         Besselian epoch) then the coordinate values for the first input should
+         be date in units of days. Similarly, the nature and units of the
+         coordinate values returned by a TimeMap will be determined by the
+         last conversion step applied by the TimeMap.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astToString
+}{
+   Create an in-memory serialisation of an Object
+}{
+   \sstdescription{
+      This function returns a string holding a minimal textual
+      serialisation of the supplied AST \htmlref{Object}{Object}. The Object can re
+      re-created from the serialisation using \htmlref{astFromString}{astFromString}.
+   }
+   \sstsynopsis{
+      char $*$astToString( AstObject $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Object to be serialised.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astToString()
+      }{
+         Pointer to dynamically allocated memory holding the
+         serialisation, or NULL if an error occurs. The pointer
+         should be freed when no longer needed using \htmlref{astFree}{astFree}.
+      }
+   }
+}
+\sstroutine{
+   astTran1
+}{
+   Transform 1-dimensional coordinates
+}{
+   \sstdescription{
+      This function applies a \htmlref{Mapping}{Mapping} to transform the coordinates of
+      a set of points in one dimension.
+   }
+   \sstsynopsis{
+      void astTran1( AstMapping $*$this, int npoint, const double xin[],
+                     int forward, double xout[] )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Mapping to be applied.
+      }
+      \sstsubsection{
+         npoint
+      }{
+         The number of points to be transformed.
+      }
+      \sstsubsection{
+         xin
+      }{
+         An array of \texttt{"} npoint\texttt{"}  coordinate values for the input
+         (untransformed) points.
+      }
+      \sstsubsection{
+         forward
+      }{
+         A non-zero value indicates that the Mapping\texttt{'} s forward
+         coordinate transformation is to be applied, while a zero
+         value indicates that the inverse transformation should be
+         used.
+      }
+      \sstsubsection{
+         xout
+      }{
+         An array (with \texttt{"} npoint\texttt{"}  elements) into which the
+         coordinates of the output (transformed) points will be written.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The Mapping supplied must have the value 1 for both its \htmlref{Nin}{Nin}
+         and \htmlref{Nout}{Nout} attributes.
+      }
+   }
+}
+\sstroutine{
+   astTran2
+}{
+   Transform 2-dimensional coordinates
+}{
+   \sstdescription{
+      This function applies a \htmlref{Mapping}{Mapping} to transform the coordinates of
+      a set of points in two dimensions.
+   }
+   \sstsynopsis{
+      void astTran2( AstMapping $*$this,
+                     int npoint, const double xin[], const double yin[],
+                     int forward, double xout[], double yout[] )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Mapping to be applied.
+      }
+      \sstsubsection{
+         npoint
+      }{
+         The number of points to be transformed.
+      }
+      \sstsubsection{
+         xin
+      }{
+         An array of \texttt{"} npoint\texttt{"}  X-coordinate values for the input
+         (untransformed) points.
+      }
+      \sstsubsection{
+         yin
+      }{
+         An array of \texttt{"} npoint\texttt{"}  Y-coordinate values for the input
+         (untransformed) points.
+      }
+      \sstsubsection{
+         forward
+      }{
+         A non-zero value indicates that the Mapping\texttt{'} s forward
+         coordinate transformation is to be applied, while a zero
+         value indicates that the inverse transformation should be
+         used.
+      }
+      \sstsubsection{
+         xout
+      }{
+         An array (with \texttt{"} npoint\texttt{"}  elements) into which the
+         X-coordinates of the output (transformed) points will be written.
+      }
+      \sstsubsection{
+         yout
+      }{
+         An array (with \texttt{"} npoint\texttt{"}  elements) into which the
+         Y-coordinates of the output (transformed) points will be written.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The Mapping supplied must have the value 2 for both its \htmlref{Nin}{Nin}
+         and \htmlref{Nout}{Nout} attributes.
+      }
+   }
+}
+\sstroutine{
+   astTranGrid
+}{
+   Transform a grid of positions
+}{
+   \sstdescription{
+      This function uses the supplied \htmlref{Mapping}{Mapping} to transforms a regular square
+      grid of points covering a specified box. It attempts to do this
+      quickly by first approximating the Mapping with a linear transformation
+      applied over the whole region of the input grid which is being used.
+      If this proves to be insufficiently accurate, the input region is
+      sub-divided into two along its largest dimension and the process is
+      repeated within each of the resulting sub-regions. This process of
+      sub-division continues until a sufficiently good linear approximation
+      is found, or the region to which it is being applied becomes too small
+      (in which case the original Mapping is used directly).
+   }
+   \sstsynopsis{
+      void astTranGrid( AstMapping $*$this, int ncoord\_in,
+                        const int lbnd[], const int ubnd[],
+                        double tol, int maxpix, int forward,
+                        int ncoord\_out, int outdim, double $*$out );
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Mapping to be applied.
+      }
+      \sstsubsection{
+         ncoord\_in
+      }{
+         The number of coordinates being supplied for each box corner
+         (i.e. the number of dimensions of the space in which the
+         input points reside).
+      }
+      \sstsubsection{
+         lbnd
+      }{
+         Pointer to an array of integers, with \texttt{"} ncoord\_in\texttt{"}  elements,
+         containing the coordinates of the centre of the first pixel
+         in the input grid along each dimension.
+      }
+      \sstsubsection{
+         ubnd
+      }{
+         Pointer to an array of integers, with \texttt{"} ncoord\_in\texttt{"}  elements,
+         containing the coordinates of the centre of the last pixel in
+         the input grid along each dimension.
+
+         Note that \texttt{"} lbnd\texttt{"}  and \texttt{"} ubnd\texttt{"}  together define the shape
+         and size of the input grid, its extent along a particular
+         (j\texttt{'} th) dimension being ubnd[j]-lbnd[j]$+$1 (assuming the
+         index \texttt{"} j\texttt{"}  to be zero-based). They also define
+         the input grid\texttt{'} s coordinate system, each pixel having unit
+         extent along each dimension with integral coordinate values
+         at its centre.
+      }
+      \sstsubsection{
+         tol
+      }{
+         The maximum tolerable geometrical distortion which may be
+         introduced as a result of approximating non-linear Mappings
+         by a set of piece-wise linear transformations. This should be
+         expressed as a displacement within the output coordinate system
+         of the Mapping.
+
+         If piece-wise linear approximation is not required, a value
+         of zero may be given. This will ensure that the Mapping is
+         used without any approximation, but may increase execution
+         time.
+
+         If the value is too high, discontinuities between the linear
+         approximations used in adjacent panel will be higher. If this
+         is a problem, reduce the tolerance value used.
+      }
+      \sstsubsection{
+         maxpix
+      }{
+         A value which specifies an initial scale size (in input grid points)
+         for the adaptive algorithm which approximates non-linear Mappings
+         with piece-wise linear transformations. Normally, this should
+         be a large value (larger than any dimension of the region of
+         the input grid being used). In this case, a first attempt to
+         approximate the Mapping by a linear transformation will be
+         made over the entire input region.
+
+         If a smaller value is used, the input region will first be
+         divided into sub-regions whose size does not exceed \texttt{"} maxpix\texttt{"}
+         grid points in any dimension. Only at this point will attempts
+         at approximation commence.
+
+         This value may occasionally be useful in preventing false
+         convergence of the adaptive algorithm in cases where the
+         Mapping appears approximately linear on large scales, but has
+         irregularities (e.g. holes) on smaller scales. A value of,
+         say, 50 to 100 grid points can also be employed as a safeguard
+         in general-purpose software, since the effect on performance is
+         minimal.
+
+         If too small a value is given, it will have the effect of
+         inhibiting linear approximation altogether (equivalent to
+         setting \texttt{"} tol\texttt{"}  to zero). Although this may degrade
+         performance, accurate results will still be obtained.
+      }
+      \sstsubsection{
+         forward
+      }{
+         A non-zero value indicates that the Mapping\texttt{'} s forward
+         coordinate transformation is to be applied, while a zero
+         value indicates that the inverse transformation should be
+         used.
+      }
+      \sstsubsection{
+         ncoord\_out
+      }{
+         The number of coordinates being generated by the Mapping for
+         each output point (i.e. the number of dimensions of the
+         space in which the output points reside). This need not be
+         the same as \texttt{"} ncoord\_in\texttt{"} .
+      }
+      \sstsubsection{
+         outdim
+      }{
+         The number of elements along the second dimension of the \texttt{"} out\texttt{"}
+         array (which will contain the output coordinates). The value
+         given should not be less than the number of points in the grid.
+      }
+      \sstsubsection{
+         out
+      }{
+         The address of the first element in a 2-dimensional array of
+         shape \texttt{"} [ncoord\_out][outdim]\texttt{"} , into
+         which the coordinates of the output (transformed) points will
+         be written. These will be stored such that the value of
+         coordinate number \texttt{"} coord\texttt{"}  for output point number \texttt{"} point\texttt{"}
+         will be found in element \texttt{"} out[coord][point]\texttt{"} .
+         The points are ordered such that the first axis of the input
+         grid changes most rapidly. For example, if the input grid is
+         2-dimensional and extends from (2,-1) to (3,1), the output
+         points will be stored in the order (2,-1), (3, -1), (2,0), (3,0),
+         (2,1), (3,1).
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If the forward coordinate transformation is being applied, the
+         Mapping supplied must have the value of \texttt{"} ncoord\_in\texttt{"}  for its \htmlref{Nin}{Nin}
+         attribute and the value of \texttt{"} ncoord\_out\texttt{"}  for its \htmlref{Nout}{Nout} attribute. If
+         the inverse transformation is being applied, these values should
+         be reversed.
+      }
+   }
+}
+\sstroutine{
+   astTranMap
+}{
+   Create a TranMap
+}{
+   \sstdescription{
+      This function creates a new \htmlref{TranMap}{TranMap} and optionally initialises
+      its attributes.
+
+      A TranMap is a \htmlref{Mapping}{Mapping} which combines the forward transformation of
+      a supplied Mapping with the inverse transformation of another
+      supplied Mapping, ignoring the un-used transformation in each
+      Mapping (indeed the un-used transformation need not exist).
+
+      When the forward transformation of the TranMap is referred to, the
+      transformation actually used is the forward transformation of the
+      first Mapping supplied when the TranMap was constructed. Likewise,
+      when the inverse transformation of the TranMap is referred to, the
+      transformation actually used is the inverse transformation of the
+      second Mapping supplied when the TranMap was constructed.
+   }
+   \sstsynopsis{
+      AstTranMap $*$astTranMap( AstMapping $*$map1, AstMapping $*$map2,
+                            const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         map1
+      }{
+         Pointer to the first component Mapping, which defines the
+         forward transformation.
+      }
+      \sstsubsection{
+         map2
+      }{
+         Pointer to the second component Mapping, which defines the
+         inverse transformation.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new TranMap. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astTranMap()
+      }{
+         A pointer to the new TranMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The number of output coordinates generated by the two Mappings
+         (their \htmlref{Nout}{Nout} attribute) must be equal, as must the number of input
+         coordinates accepted by each Mapping (their \htmlref{Nin}{Nin} attribute).
+
+         \sstitem
+          The forward transformation of the first Mapping must exist.
+
+         \sstitem
+          The inverse transformation of the second Mapping must exist.
+
+         \sstitem
+          Note that the component Mappings supplied are not copied by
+         astTranMap (the new TranMap simply retains a reference to
+         them). They may continue to be used for other purposes, but
+         should not be deleted. If a TranMap containing a copy of its
+         component Mappings is required, then a copy of the TranMap should
+         be made using \htmlref{astCopy}{astCopy}.
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      Status Handling
+   }{
+      The protected interface to this function includes an extra
+      parameter at the end of the parameter list descirbed above. This
+      parameter is a pointer to the integer inherited status
+      variable: \texttt{"} int $*$status\texttt{"} .
+   }
+}
+\sstroutine{
+   astTranN
+}{
+   Transform N-dimensional coordinates
+}{
+   \sstdescription{
+      This function applies a \htmlref{Mapping}{Mapping} to transform the coordinates of
+      a set of points in an arbitrary number of dimensions. It is the
+      appropriate routine to use if the coordinates are not purely 1-
+      or 2-dimensional and are stored in a single array (which they
+      need not fill completely).
+
+      If the coordinates are not stored in a single array, then the
+      \htmlref{astTranP}{astTranP} function might be more suitable.
+   }
+   \sstsynopsis{
+      void astTranN( AstMapping $*$this, int npoint,
+                     int ncoord\_in, int indim, const double $*$in,
+                     int forward,
+                     int ncoord\_out, int outdim, double $*$out )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Mapping to be applied.
+      }
+      \sstsubsection{
+         npoint
+      }{
+         The number of points to be transformed.
+      }
+      \sstsubsection{
+         ncoord\_in
+      }{
+         The number of coordinates being supplied for each input point
+         (i.e. the number of dimensions of the space in which the
+         input points reside).
+      }
+      \sstsubsection{
+         indim
+      }{
+         The number of elements along the second dimension of the \texttt{"} in\texttt{"}
+         array (which contains the input coordinates). This value is
+         required so that the coordinate values can be correctly
+         located if they do not entirely fill this array. The value
+         given should not be less than \texttt{"} npoint\texttt{"} .
+      }
+      \sstsubsection{
+         in
+      }{
+         The address of the first element in a 2-dimensional array of
+         shape \texttt{"} [ncoord\_in][indim]\texttt{"} ,
+         containing the coordinates of the input (untransformed)
+         points. These should be stored such that the value of
+         coordinate number \texttt{"} coord\texttt{"}  for input point number \texttt{"} point\texttt{"}  is
+         found in element \texttt{"} in[coord][point]\texttt{"} .
+      }
+      \sstsubsection{
+         forward
+      }{
+         A non-zero value indicates that the Mapping\texttt{'} s forward
+         coordinate transformation is to be applied, while a zero
+         value indicates that the inverse transformation should be
+         used.
+      }
+      \sstsubsection{
+         ncoord\_out
+      }{
+         The number of coordinates being generated by the Mapping for
+         each output point (i.e. the number of dimensions of the
+         space in which the output points reside). This need not be
+         the same as \texttt{"} ncoord\_in\texttt{"} .
+      }
+      \sstsubsection{
+         outdim
+      }{
+         The number of elements along the second dimension of the \texttt{"} out\texttt{"}
+         array (which will contain the output coordinates). This value
+         is required so that the coordinate values can be correctly
+         located if they will not entirely fill this array. The value
+         given should not be less than \texttt{"} npoint\texttt{"} .
+      }
+      \sstsubsection{
+         out
+      }{
+         The address of the first element in a 2-dimensional array of
+         shape \texttt{"} [ncoord\_out][outdim]\texttt{"} , into
+         which the coordinates of the output (transformed) points will
+         be written. These will be stored such that the value of
+         coordinate number \texttt{"} coord\texttt{"}  for output point number \texttt{"} point\texttt{"}
+         will be found in element \texttt{"} out[coord][point]\texttt{"} .
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If the forward coordinate transformation is being applied, the
+         Mapping supplied must have the value of \texttt{"} ncoord\_in\texttt{"}  for its \htmlref{Nin}{Nin}
+         attribute and the value of \texttt{"} ncoord\_out\texttt{"}  for its \htmlref{Nout}{Nout} attribute. If
+         the inverse transformation is being applied, these values should
+         be reversed.
+      }
+   }
+}
+\sstroutine{
+   astTranP
+}{
+   Transform N-dimensional coordinates held in separate arrays
+}{
+   \sstdescription{
+      This function applies a \htmlref{Mapping}{Mapping} to transform the coordinates of
+      a set of points in an arbitrary number of dimensions. It is the
+      appropriate routine to use if the coordinates are not purely 1-
+      or 2-dimensional and are stored in separate arrays, since each
+      coordinate array is located by supplying a separate pointer to
+      it.
+
+      If the coordinates are stored in a single (2-dimensional) array,
+      then the \htmlref{astTranN}{astTranN} function might be more suitable.
+   }
+   \sstsynopsis{
+      void astTranP( AstMapping $*$this, int npoint,
+                     int ncoord\_in, const double $*$ptr\_in[],
+                     int forward, int ncoord\_out, double $*$ptr\_out[] )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Mapping to be applied.
+      }
+      \sstsubsection{
+         npoint
+      }{
+         The number of points to be transformed.
+      }
+      \sstsubsection{
+         ncoord\_in
+      }{
+         The number of coordinates being supplied for each input point
+         (i.e. the number of dimensions of the space in which the
+         input points reside).
+      }
+      \sstsubsection{
+         ptr\_in
+      }{
+         An array of pointers to double, with \texttt{"} ncoord\_in\texttt{"}
+         elements. Element \texttt{"} ptr\_in[coord]\texttt{"}  should point at the first
+         element of an array of double (with \texttt{"} npoint\texttt{"}  elements) which
+         contain the values of coordinate number \texttt{"} coord\texttt{"}  for each
+         input (untransformed) point. The value of coordinate number
+         \texttt{"} coord\texttt{"}  for input point number \texttt{"} point\texttt{"}  is therefore given by
+         \texttt{"} ptr\_in[coord][point]\texttt{"}  (assuming both indices are
+         zero-based).
+      }
+      \sstsubsection{
+         forward
+      }{
+         A non-zero value indicates that the Mapping\texttt{'} s forward
+         coordinate transformation is to be applied, while a zero
+         value indicates that the inverse transformation should be
+         used.
+      }
+      \sstsubsection{
+         ncoord\_out
+      }{
+         The number of coordinates being generated by the Mapping for
+         each output point (i.e. the number of dimensions of the space
+         in which the output points reside). This need not be the same
+         as \texttt{"} ncoord\_in\texttt{"} .
+      }
+      \sstsubsection{
+         ptr\_out
+      }{
+         An array of pointers to double, with \texttt{"} ncoord\_out\texttt{"}
+         elements. Element \texttt{"} ptr\_out[coord]\texttt{"}  should point at the first
+         element of an array of double (with \texttt{"} npoint\texttt{"}  elements) into
+         which the values of coordinate number \texttt{"} coord\texttt{"}  for each output
+         (transformed) point will be written.  The value of coordinate
+         number \texttt{"} coord\texttt{"}  for output point number \texttt{"} point\texttt{"}  will therefore
+         be found in \texttt{"} ptr\_out[coord][point]\texttt{"} .
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If the forward coordinate transformation is being applied, the
+         Mapping supplied must have the value of \texttt{"} ncoord\_in\texttt{"}  for its \htmlref{Nin}{Nin}
+         attribute and the value of \texttt{"} ncoord\_out\texttt{"}  for its \htmlref{Nout}{Nout}
+         attribute. If the inverse transformation is being applied, these
+         values should be reversed.
+
+         \sstitem
+          This routine is not available in the Fortran 77 interface to
+         the AST library.
+      }
+   }
+}
+\sstroutine{
+   astTune
+}{
+   Set or get an integer-valued AST global tuning parameter
+}{
+   \sstdescription{
+      This function returns the current value of an integer-valued AST
+      global tuning parameter, optionally storing a new value for the
+      parameter. For character-valued tuning parameters, see
+      \htmlref{astTuneC}{astTuneC}.
+   }
+   \sstsynopsis{
+      int astTune( const char $*$name, int value )
+   }
+   \sstparameters{
+      \sstsubsection{
+         name
+      }{
+         The name of the tuning parameter (case-insensitive).
+      }
+      \sstsubsection{
+         value
+      }{
+         The new value for the tuning parameter. If this is AST\_\_TUNULL,
+         the existing current value will be retained.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astTune()
+      }{
+         The original value of the tuning parameter. A default value will
+         be returned if no value has been set for the parameter.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This function attempts to execute even if the AST error
+         status is set
+         on entry, although no further error report will be
+         made if it subsequently fails under these circumstances.
+
+         \sstitem
+          All threads in a process share the same AST tuning parameters
+         values.
+      }
+   }
+   \sstdiylist{
+      Tuning Parameters
+   }{
+      \sstsubsection{
+         ObjectCaching
+      }{
+         A boolean flag which indicates what should happen
+         to the memory occupied by an AST \htmlref{Object}{Object} when the Object is deleted
+         (i.e. when its reference count falls to zero or it is deleted using
+         \htmlref{astDelete}{astDelete}).
+         If this is zero, the memory is simply freed using the systems \texttt{"} free\texttt{"}
+         function. If it is non-zero, the memory is not freed. Instead a
+         pointer to it is stored in a pool of such pointers, all of which
+         refer to allocated but currently unused blocks of memory. This allows
+         AST to speed up subsequent Object creation by re-using previously
+         allocated memory blocks rather than allocating new memory using the
+         systems malloc function. The default value for this parameter is
+         zero. Setting it to a non-zero value will result in Object memory
+         being cached in future. Setting it back to zero causes any memory
+         blocks currently in the pool to be freed. Note, this tuning parameter
+         only controls the caching of memory used to store AST Objects. To
+         cache other memory blocks allocated by AST, use MemoryCaching.
+      }
+      \sstsubsection{
+         MemoryCaching
+      }{
+         A boolean flag similar to ObjectCaching except
+         that it controls caching of all memory blocks of less than 300 bytes
+         allocated by AST (whether for internal or external use), not just
+         memory used to store AST Objects.
+      }
+   }
+}
+\sstroutine{
+   astTuneC
+}{
+   Set or get a character-valued AST global tuning parameter
+}{
+   \sstdescription{
+      This function returns the current value of a character-valued
+      AST global tuning parameter, optionally storing a new value
+      for the parameter. For integer-valued tuning parameters, see
+      \htmlref{astTune}{astTune}.
+   }
+   \sstsynopsis{
+      void astTuneC( const char $*$name, const char $*$value, char $*$buff,
+                     int bufflen )
+   }
+   \sstparameters{
+      \sstsubsection{
+         name
+      }{
+         The name of the tuning parameter (case-insensitive).
+      }
+      \sstsubsection{
+         value
+      }{
+         The new value for the tuning parameter. If this is
+         NULL,
+         the existing current value will be retained.
+      }
+      \sstsubsection{
+         buff
+      }{
+         A character string in which to return the original value of
+         the tuning parameter. An error will be reported if the buffer
+         is too small to hold the value.
+         NULL may be supplied if the old value is not required.
+      }
+      \sstsubsection{
+         bufflen
+      }{
+         The size of the supplied \texttt{"} buff\texttt{"}  array. Ignored if \texttt{"} buff\texttt{"}  is NULL.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This function attempts to execute even if the AST error
+         status is set
+         on entry, although no further error report will be
+         made if it subsequently fails under these circumstances.
+
+         \sstitem
+          All threads in a process share the same AST tuning parameters
+         values.
+      }
+   }
+   \sstdiylist{
+      Tuning Parameters
+   }{
+      \sstsubsection{
+         HRDel
+      }{
+         A string to be drawn following the hours field in a formatted
+         sky axis value when \texttt{"} g\texttt{"}  format is in use (see the Format
+         attribute). This string may include escape sequences to produce
+         super-scripts, etc. (see the Escapes attribute for details
+         of the escape sequences allowed). The default value is
+         \texttt{"} \%-\%$\wedge$50$+$\%s70$+$h\%$+$\texttt{"}  which produces a super-script \texttt{"} h\texttt{"} .
+      }
+      \sstsubsection{
+         MNDel
+      }{
+         A string to be drawn following the minutes field in a formatted
+         sky axis value when \texttt{"} g\texttt{"}  format is in use. The default value is
+         \texttt{"} \%-\%$\wedge$50$+$\%s70$+$m\%$+$\texttt{"}  which produces a super-script \texttt{"} m\texttt{"} .
+      }
+      \sstsubsection{
+         SCDel
+      }{
+         A string to be drawn following the seconds field in a formatted
+         sky axis value when \texttt{"} g\texttt{"}  format is in use. The default value is
+         \texttt{"} \%-\%$\wedge$50$+$\%s70$+$s\%$+$\texttt{"}  which produces a super-script \texttt{"} s\texttt{"} .
+      }
+      \sstsubsection{
+         DGDel
+      }{
+         A string to be drawn following the degrees field in a formatted
+         sky axis value when \texttt{"} g\texttt{"}  format is in use. The default value is
+         \texttt{"} \%-\%$\wedge$53$+$\%s60$+$o\%$+$\texttt{"}  which produces a super-script \texttt{"} o\texttt{"} .
+      }
+      \sstsubsection{
+         AMDel
+      }{
+         A string to be drawn following the arc-minutes field in a formatted
+         sky axis value when \texttt{"} g\texttt{"}  format is in use. The default value is
+         \texttt{"} \%-\%$\wedge$20$+$\%s85$+$\texttt{'} \%$+$\texttt{"}  which produces a super-script \texttt{"} \texttt{'} \texttt{"}  (single quote).
+      }
+      \sstsubsection{
+         ASDel
+      }{
+         A string to be drawn following the arc-seconds field in a formatted
+         sky axis value when \texttt{"} g\texttt{"}  format is in use. The default value is
+         \texttt{"} \%-\%$\wedge$20$+$\%s85$+$$\backslash$\texttt{"} \%$+$\texttt{"}  which produces a super-script \texttt{"} \texttt{"} \texttt{"}  (double quote).
+      }
+      \sstsubsection{
+         EXDel
+      }{
+         A string to be drawn to introduce the exponent in a value when \texttt{"} g\texttt{"}
+         format is in use. The default value is \texttt{"} 10\%-\%$\wedge$50$+$\%s70$+$\texttt{"}  which
+         produces \texttt{"} 10\texttt{"}  followed by the exponent as a super-script.
+      }
+   }
+}
+\sstroutine{
+   astUinterp
+}{
+   Perform sub-pixel interpolation on a grid of data
+}{
+   \sstdescription{
+      This is a fictitious function which does not actually
+      exist. Instead, this description constitutes a template so that
+      you may implement a function with this interface for yourself
+      (and give it any name you wish). A pointer to such a function
+      may be passed via the \texttt{"} finterp\texttt{"}  parameter of the \htmlref{astResample$<$X$>$}{astResample$<$X$>$}
+      functions (q.v.) in order to perform sub-pixel interpolation
+      during resampling of gridded data (you must also set the
+      \texttt{"} interp\texttt{"}  parameter of astResample$<$X$>$ to the value
+      AST\_\_UINTERP). This allows you to use your own interpolation
+      algorithm in addition to those which are pre-defined.
+
+      The function interpolates an input grid of data (and,
+      optionally, processes associated statistical variance estimates)
+      at a specified set of points.
+   }
+   \sstsynopsis{
+      void astUinterp( int ndim\_in, const int lbnd\_in[], const int ubnd\_in[],
+                       const $<$Xtype$>$ in[], const $<$Xtype$>$ in\_var[],
+                       int npoint, const int offset[],
+                       const double $*$const coords[], const double params[],
+                       int flags, $<$Xtype$>$ badval,
+                       $<$Xtype$>$ out[], $<$Xtype$>$ out\_var[], int $*$nbad )
+   }
+   \sstparameters{
+      \sstsubsection{
+         ndim\_in
+      }{
+         The number of dimensions in the input grid. This will be at
+         least one.
+      }
+      \sstsubsection{
+         lbnd\_in
+      }{
+         Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"}  elements,
+         containing the coordinates of the centre of the first pixel
+         in the input grid along each dimension.
+      }
+      \sstsubsection{
+         ubnd\_in
+      }{
+         Pointer to an array of integers, with \texttt{"} ndim\_in\texttt{"}  elements,
+         containing the coordinates of the centre of the last pixel in
+         the input grid along each dimension.
+
+         Note that \texttt{"} lbnd\_in\texttt{"}  and \texttt{"} ubnd\_in\texttt{"}  together define the shape,
+         size and coordinate system of the input grid in the same
+         way as they do in astResample$<$X$>$.
+      }
+      \sstsubsection{
+         in
+      }{
+         Pointer to an array, with one element for each pixel in the
+         input grid, containing the input data. This will be the same
+         array as was passed to astResample$<$X$>$ via the \texttt{"} in\texttt{"}  parameter.
+         The numerical type of this array should match that of the
+         data being processed.
+      }
+      \sstsubsection{
+         in\_var
+      }{
+         Pointer to an optional second array with the same size and
+         type as the \texttt{"} in\texttt{"}  array. If given, this will contain the set
+         of variance values associated with the input data and will be
+         the same array as was passed to astResample$<$X$>$ via the
+         \texttt{"} in\_var\texttt{"}  parameter.
+
+         If no variance values are being processed, this will be a
+         NULL pointer.
+      }
+      \sstsubsection{
+         npoint
+      }{
+         The number of points at which the input grid is to be
+         interpolated. This will be at least one.
+      }
+      \sstsubsection{
+         offset
+      }{
+         Pointer to an array of integers with \texttt{"} npoint\texttt{"}  elements. For
+         each interpolation point, this will contain the zero-based
+         index in the \texttt{"} out\texttt{"}  (and \texttt{"} out\_var\texttt{"} ) array(s) at which the
+         interpolated value (and its variance, if required) should be
+         stored. For example, the interpolated value for point number
+         \texttt{"} point\texttt{"}  should be stored in \texttt{"} out[offset[point]]\texttt{"}  (assuming
+         the index \texttt{"} point\texttt{"}  is zero-based).
+      }
+      \sstsubsection{
+         coords
+      }{
+         An array of pointers to double, with \texttt{"} ndim\_in\texttt{"}
+         elements. Element \texttt{"} coords[coord]\texttt{"}  will point at the first
+         element of an array of double (with \texttt{"} npoint\texttt{"}  elements) which
+         contains the values of coordinate number \texttt{"} coord\texttt{"}  for each
+         interpolation point. The value of coordinate number \texttt{"} coord\texttt{"}
+         for interpolation point number \texttt{"} point\texttt{"}  is therefore given by
+         \texttt{"} coords[coord][point]\texttt{"}  (assuming both indices are
+         zero-based).
+
+         If any interpolation point has any of its coordinates equal
+         to the value AST\_\_BAD (as defined in the \texttt{"} ast.h\texttt{"}  header
+         file), then the corresponding output data (and variance)
+         should either be set to the value given by \texttt{"} badval\texttt{"} ,
+         or left unchanged, depending on whether the AST\_\_NOBAD flag is
+         specified by \texttt{"} flags\texttt{"} .
+      }
+      \sstsubsection{
+         params
+      }{
+         This will be a pointer to the same array as was given via the
+         \texttt{"} params\texttt{"}  parameter of astResample$<$X$>$. You may use this to
+         pass any additional parameter values required by your
+         interpolation algorithm.
+      }
+      \sstsubsection{
+         flags
+      }{
+         This will be the same value as was given via the \texttt{"} flags\texttt{"}
+         parameter of astResample$<$X$>$. You may test this value to
+         provide additional control over the operation of your
+         resampling algorithm. Note that the special flag values
+         AST\_\_URESAMP1, 2, 3 \& 4 are reserved for you to use for your
+         own purposes and will not clash with other pre-defined flag
+         values (see astResample$<$X$>$).
+      }
+      \sstsubsection{
+         badval
+      }{
+         This will be the same value as was given via the \texttt{"} badval\texttt{"}
+         parameter of astResample$<$X$>$, and will have the same numerical
+         type as the data being processed (i.e. as elements of the
+         \texttt{"} in\texttt{"}  array).  It should be used to test for bad pixels in the
+         input grid (but only if the AST\_\_USEBAD flag is set via the
+         \texttt{"} flags\texttt{"}  parameter) and (unless the AST\_\_NOBAD flag is set in
+         \texttt{"} flags\texttt{"} ) for identifying bad output values in
+         the \texttt{"} out\texttt{"}  (and \texttt{"} out\_var\texttt{"} ) array(s).
+      }
+      \sstsubsection{
+         out
+      }{
+         Pointer to an array with the same numerical type as the \texttt{"} in\texttt{"}
+         array, into which the interpolated data values should be
+         returned.  Note that details of the storage order and number
+         of dimensions of this array are not required, since the
+         \texttt{"} offset\texttt{"}  array contains all necessary information about where
+         each returned value should be stored.
+
+         In general, not all elements of this array (or the \texttt{"} out\_var\texttt{"}
+         array below) may be used in any particular invocation of the
+         function. Those which are not used should be returned
+         unchanged.
+      }
+      \sstsubsection{
+         out\_var
+      }{
+         Pointer to an optional array with the same type and size as
+         the \texttt{"} out\texttt{"}  array, into which variance estimates for the
+         resampled values should be returned.  This array will only be
+         given if the \texttt{"} in\_var\texttt{"}  array has also been given.
+
+         If given, it is addressed in exactly the same way (via the
+         \texttt{"} offset\texttt{"}  array) as the \texttt{"} out\texttt{"}  array. The values returned
+         should be estimates of the statistical variance of the
+         corresponding values in the \texttt{"} out\texttt{"}  array, on the assumption
+         that all errors in input data values are statistically
+         independent and that their variance estimates may simply be
+         summed (with appropriate weighting factors).
+
+         If no output variance estimates are required, a NULL pointer
+         will be given.
+      }
+      \sstsubsection{
+         nbad
+      }{
+         Pointer to an int in which to return the number of interpolation
+         points at
+         which no valid interpolated value could be obtained.  The maximum
+         value that should be returned is \texttt{"} npoint\texttt{"} , and the minimum is
+         zero (indicating that all output values were successfully
+         obtained).
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The data type $<$Xtype$>$ indicates the numerical type of the data
+         being processed, as for astResample$<$X$>$.
+
+         \sstitem
+          This function will typically be invoked more than once for each
+         invocation of astResample$<$X$>$.
+
+         \sstitem
+          If an error occurs within this function, it should use
+         \htmlref{astSetStatus}{astSetStatus} to set the AST error status to an error value.
+         This will cause an immediate return from astResample$<$X$>$. The error
+         value AST\_\_UINER is available for this purpose, but other values may
+         also be used (e.g. if you wish to distinguish different types of
+         error).
+      }
+   }
+}
+\sstroutine{
+   astUkern1
+}{
+   1-dimensional sub-pixel interpolation kernel
+}{
+   \sstdescription{
+      This is a fictitious function which does not actually
+      exist. Instead, this description constitutes a template so that
+      you may implement a function with this interface for yourself
+      (and give it any name you wish). A pointer to such a function
+      may be passed via the \texttt{"} finterp\texttt{"}  parameter of the \htmlref{astResample$<$X$>$}{astResample$<$X$>$}
+      functions (q.v.) in order to supply a 1-dimensional
+      interpolation kernel to the algorithm which performs sub-pixel
+      interpolation during resampling of gridded data (you must also
+      set the \texttt{"} interp\texttt{"}  parameter of astResample$<$X$>$ to the value
+      AST\_\_UKERN1). This allows you to use your own interpolation
+      kernel in addition to those which are pre-defined.
+
+      The function calculates the value of a 1-dimensional sub-pixel
+      interpolation kernel. This determines how the weight given to
+      neighbouring pixels in calculating an interpolated value depends
+      on the pixel\texttt{'} s offset from the interpolation point. In more than
+      one dimension, the weight assigned to a pixel is formed by
+      evaluating this 1-dimensional kernel using the offset along each
+      dimension in turn. The product of the returned values is then
+      used as the pixel weight.
+   }
+   \sstsynopsis{
+      void astUkern1( double offset, const double params[], int flags,
+                      double $*$value )
+   }
+   \sstparameters{
+      \sstsubsection{
+         offset
+      }{
+         This will be the offset of the pixel from the interpolation
+         point, measured in pixels. This value may be positive or
+         negative, but for most practical interpolation schemes its
+         sign should be ignored.
+      }
+      \sstsubsection{
+         params
+      }{
+         This will be a pointer to the same array as was given via the
+         \texttt{"} params\texttt{"}  parameter of astResample$<$X$>$. You may use this to
+         pass any additional parameter values required by your kernel,
+         but note that \texttt{"} params[0]\texttt{"}  will already have been used to specify
+         the number of neighbouring pixels which contribute to the
+         interpolated value.
+      }
+      \sstsubsection{
+         flags
+      }{
+         This will be the same value as was given via the \texttt{"} flags\texttt{"}
+         parameter of astResample$<$X$>$. You may test this value to
+         provide additional control over the operation of your
+         function. Note that the special flag values AST\_\_URESAMP1, 2,
+         3 \& 4 are reserved for you to use for your own purposes and
+         will not clash with other pre-defined flag
+         values (see astResample$<$X$>$).
+      }
+      \sstsubsection{
+         value
+      }{
+         Pointer to a double to receive the calculated kernel value,
+         which may be positive or negative.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Not all functions make good interpolation kernels. In general,
+         acceptable kernels tend to be symmetrical about zero, to have a
+         positive peak (usually unity) at zero, and to evaluate to zero
+         whenever the pixel offset has any other integral value (this
+         ensures that the interpolated values pass through the original
+         data). An interpolation kernel may or may not have regions with
+         negative values. You should consult a good book on image
+         processing for more details.
+
+         \sstitem
+          If an error occurs within this function, it should use
+         \htmlref{astSetStatus}{astSetStatus} to set the AST error status to an error value.
+         This will cause an immediate return from astResample$<$X$>$. The error
+         value AST\_\_UK1ER is available for this purpose, but other values may
+         also be used (e.g. if you wish to distinguish different types of
+         error).
+      }
+   }
+}
+\sstroutine{
+   astUnformat
+}{
+   Read a formatted coordinate value for a Frame axis
+}{
+   \sstdescription{
+      This function reads a formatted coordinate value (given as a
+      character string) for a \htmlref{Frame}{Frame} axis and returns the equivalent
+      numerical (double) value. It also returns the number of
+      characters read from the string.
+
+      The principle use of this function is in decoding user-supplied
+      input which contains formatted coordinate values. Free-format
+      input is supported as far as possible. If input is ambiguous, it
+      is interpreted with reference to the Frame\texttt{'} s attributes (in
+      particular, the Format string associated with the Frame\texttt{'} s
+      axis). This function is, in essence, the inverse of \htmlref{astFormat}{astFormat}.
+   }
+   \sstsynopsis{
+      int astUnformat( AstFrame $*$this, int axis, const char $*$string,
+                       double $*$value )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Frame.
+      }
+      \sstsubsection{
+         axis
+      }{
+         The number of the Frame axis for which a coordinate value is to
+         be read (axis numbering starts at 1 for the first axis).
+      }
+      \sstsubsection{
+         string
+      }{
+         Pointer to a null-terminated character string containing the
+         formatted coordinate value.
+         This string may contain additional information following the
+         value to be read, in which case reading stops at the first
+         character which cannot be interpreted as part of the value.
+         Any white space before or after the value is discarded.
+      }
+      \sstsubsection{
+         value
+      }{
+         Pointer to a double in which the coordinate value read will be
+         returned.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Frame
+      }{
+         This function applies to all Frames. See the \texttt{"} Frame Input
+         Format\texttt{"}  section below for details of the input formats
+         accepted by a basic Frame.
+      }
+      \sstsubsection{
+         \htmlref{SkyFrame}{SkyFrame}
+      }{
+         The SkyFrame class re-defines the input format to be suitable
+         for representing angles and times, with the resulting
+         coordinate value returned in radians.  See the \texttt{"} SkyFrame
+         Input Format\texttt{"}  section below for details of the formats
+         accepted.
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         The input formats accepted by a FrameSet are determined by
+         its current Frame (as specified by the \htmlref{Current}{Current} attribute).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astUnformat()
+      }{
+         The number of characters read from the string in order to
+         obtain the coordinate value. This will include any white
+         space which occurs before or after the value.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A function value of zero (and no coordinate value) will be
+         returned, without error, if the string supplied does not contain
+         a suitably formatted value.
+
+         \sstitem
+          Beware that it is possible for a formatting error part-way
+         through an input string to terminate input before it has been
+         completely read, but to yield a coordinate value that appears
+         valid. For example, if a user types \texttt{"} 1.5r6\texttt{"}  instead of \texttt{"} 1.5e6\texttt{"} ,
+         the \texttt{"} r\texttt{"}  will terminate input, giving an incorrect coordinate
+         value of 1.5. It is therefore most important to check the return
+         value of this function to ensure that the correct number of
+         characters have been read.
+
+         \sstitem
+          An error will result if a value is read which appears to have
+         the correct format, but which cannot be converted into a valid
+         coordinate value (for instance, because the value of one or more
+         of its fields is invalid).
+
+         \sstitem
+          The string \texttt{"} $<$bad$>$\texttt{"}  is recognised as a special case and will
+         yield the coordinate value AST\_\_BAD without error. The test for
+         this string is case-insensitive and also permits embedded white
+         space.
+
+         \sstitem
+          A function result of zero will be returned and no coordinate
+         value will be returned via the \texttt{"} value\texttt{"}  pointer if this function
+         is invoked with the AST error status set, or if it should fail
+         for any reason.
+      }
+   }
+   \sstdiytopic{
+      Frame Input Format
+   }{
+      The input format accepted for a basic Frame axis is as follows:
+      \sstitemlist{
+
+         \sstitem
+          An optional sign, followed by:
+
+         \sstitem
+          A sequence of one or more digits possibly containing a decimal point,
+         followed by:
+
+         \sstitem
+          An optional exponent field.
+
+         \sstitem
+          The exponent field, if present, consists of \texttt{"} E\texttt{"}  or \texttt{"} e\texttt{"}
+         followed by a possibly signed integer.
+
+      }
+      Examples of acceptable Frame input formats include:
+      \sstitemlist{
+
+         \sstitem
+          99
+
+         \sstitem
+          1.25
+
+         \sstitem
+          -1.6
+
+         \sstitem
+          1E8
+
+         \sstitem
+          -.99e-17
+
+         \sstitem
+          $<$bad$>$
+      }
+   }
+   \sstdiytopic{
+      SkyFrame Input Format
+   }{
+      The input format accepted for a SkyFrame axis is as follows:
+      \sstitemlist{
+
+         \sstitem
+          An optional sign, followed by between one and three fields
+         representing either degrees, arc-minutes, arc-seconds or hours,
+         minutes, seconds (e.g. \texttt{"} -12 42 03\texttt{"} ).
+
+         \sstitem
+          Each field should consist of a sequence of one or more digits,
+         which may include leading zeros. At most one field may contain a
+         decimal point, in which case it is taken to be the final field
+         (e.g. decimal degrees might be given as \texttt{"} 124.707\texttt{"} , while degrees
+         and decimal arc-minutes might be given as \texttt{"} -13 33.8\texttt{"} ).
+
+         \sstitem
+          The first field given may take any value, allowing angles and
+         times outside the conventional ranges to be
+         represented. However, subsequent fields must have values of less
+         than 60 (e.g. \texttt{"} 720 45 31\texttt{"}  is valid, whereas \texttt{"} 11 45 61\texttt{"}  is not).
+
+         \sstitem
+          Fields may be separated by white space or by \texttt{"} :\texttt{"}  (colon), but
+         the choice of separator must be used consistently throughout the
+         value. Additional white space may be present around fields and
+         separators (e.g. \texttt{"} - 2: 04 : 7.1\texttt{"} ).
+
+         \sstitem
+          The following field identification characters may be used as
+         separators to replace either of those above (or may be appended
+         to the final field), in order to identify the field to which
+         they are appended: \texttt{"} d\texttt{"} ---degrees; \texttt{"} h\texttt{"} ---hours; \texttt{"} m\texttt{"} ---minutes of
+         arc or time; \texttt{"} s\texttt{"} ---seconds of arc or time; \texttt{"} \texttt{'} \texttt{"}  (single
+         quote)---minutes of arc; \texttt{"} \texttt{"} \texttt{"}  (double quote)---seconds of arc.
+         Either lower or upper case may be used.  Fields must be given in
+         order of decreasing significance (e.g. \texttt{"} -11D 3\texttt{'}  14.4\texttt{"} \texttt{"}  or
+         \texttt{"} 22h14m11.2s\texttt{"} ).
+
+         \sstitem
+          The presence of any of the field identification characters
+         \texttt{"} d\texttt{"} , \texttt{"} \texttt{'} \texttt{"}  (single quote) or \texttt{"} \texttt{"} \texttt{"}  (double quote) indicates that the
+         value is to be interpreted as an angle. Conversely, the presence
+         of \texttt{"} h\texttt{"}  indicates that it is to be interpreted as a time (with 24
+         hours corresponding to 360 degrees). Incompatible angle/time
+         identification characters may not be mixed (e.g. \texttt{"} 10h14\texttt{'} 3\texttt{"} \texttt{"}  is
+         not valid).  The remaining field identification characters and
+         separators do not specify a preference for an angle or a time
+         and may be used with either.
+
+         \sstitem
+          If no preference for an angle or a time is expressed anywhere
+         within the value, it is interpreted as an angle if the Format
+         attribute string associated with the SkyFrame axis generates an
+         angle and as a time otherwise. This ensures that values produced
+         by astFormat are correctly interpreted by astUnformat.
+
+         \sstitem
+          Fields may be omitted, in which case they default to zero. The
+         remaining fields may be identified by using appropriate field
+         identification characters (see above) and/or by adding extra
+         colon separators (e.g. \texttt{"} -05m13s\texttt{"}  is equivalent to \texttt{"} -:05:13\texttt{"} ). If
+         a field is not identified explicitly, it is assumed that
+         adjacent fields have been given, after taking account of any
+         extra separator characters (e.g. \texttt{"} 14:25.4s\texttt{"}  specifies minutes
+         and seconds, while \texttt{"} 14::25.4s\texttt{"}  specifies degrees and seconds).
+
+         \sstitem
+          If fields are omitted in such a way that the remaining ones
+         cannot be identified uniquely (e.g. \texttt{"} 01:02\texttt{"} ), then the first
+         field (either given explicitly or implied by an extra leading
+         colon separator) is taken to be the most significant field that
+         astFormat would produce when formatting a value (using the
+         Format attribute associated with the SkyFrame axis).  By
+         default, this means that the first field will normally be
+         interpreted as degrees or hours. However, if this does not
+         result in consistent field identification, then the last field
+         (either given explicitly or implied by an extra trailing colon
+         separator) is taken to to be the least significant field that
+         astFormat would produce.
+
+      }
+      This final convention is intended to ensure that values formatted
+      by astFormat which contain less than three fields will be
+      correctly interpreted if read back using astUnformat, even if
+      they do not contain field identification characters.
+
+      Examples of acceptable SkyFrame input formats (with
+      interpretation in parentheses) include:
+      \sstitemlist{
+
+         \sstitem
+          -14d 13m 22.2s (-14d 13\texttt{'}  22.2\texttt{"} )
+
+         \sstitem
+          $+$ 12:34:56.7 (12d 34\texttt{'}  56.7\texttt{"}  or 12h 34m 56.7s)
+
+         \sstitem
+          001 : 02 : 03.4 (1d 02\texttt{'}  03.4\texttt{"}  or 1h 02m 03.4s)
+
+         \sstitem
+          22h 30 (22h 30m 00s)
+
+         \sstitem
+          136::10\texttt{"}  (136d 00\texttt{'}  10\texttt{"}  or 136h 00m 10s)
+
+         \sstitem
+          -14M 27S (-0d 14\texttt{'}  27\texttt{"}  or -0h 14m 27s)
+
+         \sstitem
+          -:14: (-0d 14\texttt{'}  00\texttt{"}  or -0h 14m 00s)
+
+         \sstitem
+          -::4.1 (-0d 00\texttt{'}  04.1\texttt{"}  or -0h 00m 04.1s)
+
+         \sstitem
+          .9\texttt{"}  (0d 00\texttt{'}  00.9\texttt{"} )
+
+         \sstitem
+          d12m (0d 12\texttt{'}  00\texttt{"} )
+
+         \sstitem
+          H 12:22.3s (0h 12m 22.3s)
+
+         \sstitem
+          $<$bad$>$ (AST\_\_BAD)
+
+      }
+      Where alternative interpretations are shown, the choice of angle or
+      time depends on the associated \htmlref{Format(axis)}{Format(axis)} attribute.
+   }
+}
+\sstroutine{
+   astUnitMap
+}{
+   Create a UnitMap
+}{
+   \sstdescription{
+      This function creates a new \htmlref{UnitMap}{UnitMap} and optionally initialises
+      its attributes.
+
+      A UnitMap is a unit (null) \htmlref{Mapping}{Mapping} that has no effect on the
+      coordinates supplied to it. They are simply copied. This can be
+      useful if a Mapping is required (e.g. to pass to another
+      function) but you do not want it to have any effect.
+   }
+   \sstsynopsis{
+      AstUnitMap $*$astUnitMap( int ncoord, const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         ncoord
+      }{
+         The number of input and output coordinates (these numbers are
+         necessarily the same).
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new UnitMap. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astUnitMap()
+      }{
+         A pointer to the new UnitMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astUnitNormMap
+}{
+   Create a UnitNormMap
+}{
+   \sstdescription{
+      This function creates a new \htmlref{UnitNormMap}{UnitNormMap} and optionally initialises its
+      attributes.
+
+      The forward transformation of a UnitNormMap subtracts the specified centre
+      and then transforms the resulting vector to a unit vector and the vector norm.
+      The output contains one more coordinate than the input: the initial
+      \htmlref{Nin}{Nin} outputs are in the same order as the input; the final output is the norm.
+      If the norm is 0, then the output of the forward transformation is AST\_\_BAD
+      for each component of the unit vector and 0 for the norm (the final value).
+
+      The inverse transformation of a UnitNormMap multiplies each component
+      of the provided vector by the provided norm and adds the specified centre.
+      The output contains one fewer coordinate than the input: the initial Nin inputs
+      are in the same order as the output; the final input is the norm.
+      If the provided norm is 0 then the other input values are ignored,
+      and the output vector is the centre.
+
+      Example: if centre = [1, -1] then [5, 2] transforms to [4, 3] after subtracting the centre;
+      the norm is 5, so the output is [0.8, 0.6, 5].
+
+      UnitNormMap enables radially symmetric transformations, as follows:
+      \sstitemlist{
+
+         \sstitem
+          apply a UnitNormMap to produce a unit vector and norm (radius)
+
+         \sstitem
+          apply a one-dimensional mapping to the norm (radius), while passing the unit vector unchanged
+
+         \sstitem
+          apply the same UnitNormMap in the inverse direction to produce the result
+      }
+   }
+   \sstsynopsis{
+      AstUnitNormMap $*$astUnitNormMap( int ncoord, const double centre[],
+                                const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         ncoord
+      }{
+         The number of coordinate values for each point to be
+         transformed (i.e. the number of dimensions of the space in
+         which the points will reside). Output will include one additional coordinate.
+      }
+      \sstsubsection{
+         centre
+      }{
+         An array containing the values to be subtracted from the input
+         coordinates before computing unit vector and norm. A separate
+         value must be supplied for each coordinate.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new UnitNormMap. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astUnitNormMap()
+      }{
+         A pointer to the new UnitNormMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      Status Handling
+   }{
+      The protected interface to this function includes an extra
+      parameter at the end of the parameter list descirbed above. This
+      parameter is a pointer to the integer inherited status
+      variable: \texttt{"} int $*$status\texttt{"} .
+   }
+}
+\sstroutine{
+   astUnlock
+}{
+   Unlock an Object for use by other threads
+}{
+   \sstdescription{
+      Unlocks an \htmlref{Object}{Object} previously locked using \htmlref{astLock}{astLock}, so that other
+      threads can use the Object. See astLock for further details.
+   }
+   \sstsynopsis{
+      void astUnlock( AstObject $*$this, int report )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Object to be unlocked.
+      }
+      \sstsubsection{
+         report
+      }{
+         If non-zero, an error will be reported if the supplied Object,
+         or any Object contained within the supplied Object, is not
+         currently locked by the running thread. If zero, such Objects
+         will be left unchanged, and no error will be reported.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         This function applies to all Objects.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This function attempts to execute even if the global error
+         status is set, but no further error report will be made if it
+         subsequently fails under these circumstances.
+
+         \sstitem
+          All unlocked Objects are excluded from AST context handling until
+         they are re-locked using astLock.
+
+         \sstitem
+          This function is only available in the C interface.
+
+         \sstitem
+          This function returns without action if the Object is not currently
+         locked by any thread. If it is locked by the running thread, it is
+         unlocked. If it is locked by another thread, an error will be reported
+         if \texttt{"} error\texttt{"}  is non-zero.
+
+         \sstitem
+          This function returns without action if the AST library has
+         been built without POSIX thread support (i.e. the \texttt{"} -with-pthreads\texttt{"}
+         option was not specified when running the \texttt{"} configure\texttt{"}  script).
+      }
+   }
+}
+\sstroutine{
+   astVersion
+}{
+   Return the version of the AST library being used
+}{
+   \sstdescription{
+      This macro invokes a function which
+      returns an integer representing the version of the AST library
+      being used. The library version is formatted as a string such as
+      \texttt{"} 2.0-7\texttt{"}  which contains integers representing the \texttt{"} major version\texttt{"}  (2),
+      the \texttt{"} minor version\texttt{"}  (0) and the \texttt{"} release\texttt{"}  (7). The integer returned
+      by this function combines all three integers together into a single
+      integer using the expresion:
+
+      (major version)$*$1E6 $+$ (minor version)$*$1E3 $+$ (release)
+   }
+   \sstsynopsis{
+      int astVersion
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{Object}{Object}
+      }{
+         This macro applies to all Objects.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astVersion
+      }{
+         The major version, minor version and release numbers for the AST
+         library, encoded as a single integer.
+      }
+   }
+}
+\sstroutine{
+   astWarnings
+}{
+   Returns any warnings issued by the previous read or write operation
+}{
+   \sstdescription{
+      This function returns an AST \htmlref{KeyMap}{KeyMap} object holding the text of any
+      warnings issued as a result of the previous invocation of the
+      \htmlref{astRead}{astRead} or \htmlref{astWrite}{astWrite}
+      function on the \htmlref{Channel}{Channel}. If no warnings were issued, a
+      a NULL value
+      will be returned.
+
+      Such warnings are non-fatal and will not prevent the
+      read or write operation succeeding. However, the converted object
+      may not be identical to the original object in all respects.
+      Differences which would usually be deemed as insignificant in most
+      usual cases will generate a warning, whereas more significant
+      differences will generate an error.
+
+      The \texttt{"} \htmlref{Strict}{Strict}\texttt{"}  attribute allows this warning facility to be switched
+      off, so that a fatal error is always reported for any conversion
+      error.
+   }
+   \sstsynopsis{
+      AstKeyMap $*$astWarnings( AstChannel $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Channel.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Channel
+      }{
+         The basic Channel class generates a warning when ever an
+         un-recognised item is encountered whilst reading an \htmlref{Object}{Object} from
+         an external data source. If Strict is zero (the default), then
+         unexpected items in the Object description are simply ignored,
+         and any remaining items are used to construct the returned
+         Object. If Strict is non-zero, an error will be reported and a
+         NULL Object pointer returned if any unexpected items are
+         encountered.
+
+         As AST continues to be developed, new attributes are added
+         occasionally to selected classes. If an older version of AST is
+         used to read external Object descriptions created by a more
+         recent version of AST, then the Channel class will, by default,
+         ignore the new attributes, using the remaining attributes to
+         construct the Object. This is usually a good thing. However,
+         since external Object descriptions are often stored in plain
+         text, it is possible to edit them using a text editor. This
+         gives rise to the possibility of genuine errors in the
+         description due to finger-slips, typos, or simple
+         mis-understanding. Such inappropriate attributes will be ignored
+         if Strict is left at its default zero value. This will cause the
+         mis-spelled attribute to revert to its default value,
+         potentially causing subtle changes in the behaviour of
+         application software. If such an effect is suspected, the Strict
+         attribute can be set non-zero, resulting in the erroneous
+         attribute being identified in an error message.
+      }
+      \sstsubsection{
+         \htmlref{FitsChan}{FitsChan}
+      }{
+         The returned KeyMap will contain warnings for all conditions
+         listed in the \htmlref{Warnings}{Warnings} attribute.
+      }
+      \sstsubsection{
+         \htmlref{XmlChan}{XmlChan}
+      }{
+         Reports conversion errors that result in what are usally
+         insignificant  changes.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astWarnings()
+      }{
+         A pointer to the KeyMap holding the warning messages, or
+         NULL
+         if no warnings were issued during the previous read operation.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The returned KeyMap uses keys of the form \texttt{"} Warning\_1\texttt{"} ,
+         \texttt{"} Warning\_2\texttt{"} , etc.
+
+         \sstitem
+          A value of
+         NULL will be returned if this function is invoked with the AST
+         error status set,
+         or if it should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astWatch
+}{
+   Identify a new error status variable for the AST library
+}{
+   \sstdescription{
+      This function allows a new error status variable to be accessed
+      by the AST library when checking for and reporting error
+      conditions.
+
+      By default, the library uses an internal integer error status
+      which is set to an error value if an error occurs. Use of
+      astWatch allows the internal error status to be replaced by an
+      integer variable of your choosing, so that the AST library can
+      share its error status directly with other code which uses the
+      same error detection convention.
+
+      If an alternative error status variable is supplied, it is used
+      by all related AST functions and macros (e.g. \htmlref{astOK}{astOK}, \htmlref{astStatus}{astStatus}
+      and \htmlref{astClearStatus}{astClearStatus}).
+   }
+   \sstsynopsis{
+      int $*$astWatch( int $*$status\_ptr )
+   }
+   \sstparameters{
+      \sstsubsection{
+         status\_ptr
+      }{
+         Pointer to an int whose value is to be used subsequently as
+         the AST inherited status value. If a NULL pointer is supplied,
+         the AST library will revert to using its own internal error status.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astWatch()
+      }{
+         Address of the previous error status variable. This may later
+         be passed back to astWatch to restore the previous behaviour
+         of the library. (Note that on the first invocation of
+         astWatch the returned value will be the address of the
+         internal error status variable.)
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This function is not available in the FORTRAN 77 interface to
+         the AST library.
+      }
+   }
+}
+\sstroutine{
+   astWcsMap
+}{
+   Create a WcsMap
+}{
+   \sstdescription{
+      This function creates a new \htmlref{WcsMap}{WcsMap} and optionally initialises its
+      attributes.
+
+      A WcsMap is used to represent sky coordinate projections as
+      described in the (draft) FITS world coordinate system (FITS-WCS)
+      paper by E.W. Griesen and M. Calabretta (A \& A, in preparation).
+      This paper defines a set of functions, or sky projections, which
+      transform longitude-latitude pairs representing spherical
+      celestial coordinates into corresponding pairs of Cartesian
+      coordinates (and vice versa).
+
+      A WcsMap is a specialised form of \htmlref{Mapping}{Mapping} which implements these
+      sky projections and applies them to a specified pair of coordinates.
+      All the projections in the FITS-WCS paper are supported, plus the now
+      deprecated \texttt{"} TAN with polynomial correction terms\texttt{"}  projection which
+      is refered to here by the code \texttt{"} TPN\texttt{"} . Using the FITS-WCS terminology,
+      the transformation is between \texttt{"} native spherical\texttt{"}  and \texttt{"} projection
+      plane\texttt{"}  coordinates.  These coordinates may, optionally, be embedded in
+      a space with more than two dimensions, the remaining coordinates being
+      copied unchanged. Note, however, that for consistency with other AST
+      facilities, a WcsMap handles coordinates that represent angles
+      in radians (rather than the degrees used by FITS-WCS).
+
+      The type of FITS-WCS projection to be used and the coordinates
+      (axes) to which it applies are specified when a WcsMap is first
+      created. The projection type may subsequently be determined
+      using the \htmlref{WcsType}{WcsType} attribute and the coordinates on which it acts
+      may be determined using the \htmlref{WcsAxis(lonlat)}{WcsAxis(lonlat)} attribute.
+
+      Each WcsMap also allows up to 100 \texttt{"} projection parameters\texttt{"}  to be
+      associated with each axis. These specify the precise form of the
+      projection, and are accessed using \htmlref{PVi\_m}{PVi\_m} attribute, where \texttt{"} i\texttt{"}  is
+      the integer axis index (starting at 1), and m is an integer
+      \texttt{"} parameter index\texttt{"}  in the range 0 to 99. The number of projection
+      parameters required by each projection, and their meanings, are
+      dependent upon the projection type (most projections either do not
+      use any projection parameters, or use parameters 1 and 2 associated
+      with the latitude axis). Before creating a WcsMap you should consult
+      the FITS-WCS paper for details of which projection parameters are
+      required, and which have defaults. When creating the WcsMap, you must
+      explicitly set values for all those required projection parameters
+      which do not have defaults defined in this paper.
+   }
+   \sstsynopsis{
+      AstWcsMap $*$astWcsMap( int ncoord, int type, int lonax, int latax,
+                            const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         ncoord
+      }{
+         The number of coordinate values for each point to be
+         transformed (i.e. the number of dimensions of the space in
+         which the points will reside). This must be at least 2. The
+         same number is applicable to both input and output points.
+      }
+      \sstsubsection{
+         type
+      }{
+         The type of FITS-WCS projection to apply. This should be
+         given using a macro value such as AST\_\_TAN (for a tangent
+         plane projection), where the characters following the double
+         underscore give the projection type code (in upper case) as
+         used in the FITS-WCS \texttt{"} CTYPEi\texttt{"}  keyword. You should consult the
+         FITS-WCS paper for a list of the available projections. The
+         additional code of AST\_\_TPN can be supplied which represents a
+         TAN projection with polynomial correction terms as defined in an
+         early draft of the FITS-WCS paper.
+      }
+      \sstsubsection{
+         lonax
+      }{
+         The index of the longitude axis. This should lie in the range
+         1 to \texttt{"} ncoord\texttt{"} .
+      }
+      \sstsubsection{
+         latax
+      }{
+         The index of the latitude axis. This should lie in the range
+         1 to \texttt{"} ncoord\texttt{"}  and be distinct from \texttt{"} lonax\texttt{"} .
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new WcsMap. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+
+         If the sky projection to be implemented requires projection
+         parameter values to be set, then this should normally be done
+         here via the PVi\_m attribute (see the \texttt{"} Examples\texttt{"}
+         section). Setting values for these parameters is mandatory if
+         they do not have default values (as defined in the FITS-WCS
+         paper).
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astWcsMap()
+      }{
+         A pointer to the new WcsMap.
+      }
+   }
+   \sstexamples{
+      \sstexamplesubsection{
+         wcsmap = astWcsMap( 2, AST\_\_MER, 1, 2, \texttt{"} \texttt{"}  );
+      }{
+         Creates a WcsMap that implements a FITS-WCS Mercator
+         projection on pairs of coordinates, with coordinates 1 and 2
+         representing the longitude and latitude respectively. Note
+         that the FITS-WCS Mercator projection does not require any
+         projection parameters.
+      }
+      \sstexamplesubsection{
+         wcsmap = astWcsMap( 3, AST\_\_COE, 2, 3, \texttt{"} PV3\_1=40.0\texttt{"}  );
+      }{
+         Creates a WcsMap that implements a FITS-WCS conical equal
+         area projection. The WcsMap acts on points in a 3-dimensional
+         space; coordinates 2 and 3 represent longitude and latitude
+         respectively, while the values of coordinate 1 are copied
+         unchanged.  \htmlref{Projection}{Projection} parameter 1 associatyed with the latitude
+         axis (corresponding to FITS keyword \texttt{"} PV3\_1\texttt{"} ) is required and has
+         no default, so is set explicitly to 40.0 degrees. Projection
+         parameter 2 (corresponding to FITS keyword \texttt{"} PV3\_2\texttt{"} ) is required
+         but has a default of zero, so need not be specified.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The forward transformation of a WcsMap converts between
+         FITS-WCS \texttt{"} native spherical\texttt{"}  and \texttt{"} relative physical\texttt{"}  coordinates,
+         while the inverse transformation converts in the opposite
+         direction. This arrangement may be reversed, if required, by
+         using \htmlref{astInvert}{astInvert} or by setting the \htmlref{Invert}{Invert} attribute to a non-zero
+         value.
+
+         \sstitem
+          If any set of coordinates cannot be transformed (for example,
+         many projections do not cover the entire celestial sphere), then
+         a WcsMap will yield coordinate values of AST\_\_BAD.
+
+         \sstitem
+          The validity of any projection parameters given via the PVi\_m
+         parameter in the \texttt{"} options\texttt{"}  string is not checked by this
+         function. However, their validity is checked when the resulting
+         WcsMap is used to transform coordinates, and an error will
+         result if the projection parameters do not satisfy all the
+         required constraints (as defined in the FITS-WCS paper).
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      Status Handling
+   }{
+      The protected interface to this function includes an extra
+      parameter at the end of the parameter list descirbed above. This
+      parameter is a pointer to the integer inherited status
+      variable: \texttt{"} int $*$status\texttt{"} .
+   }
+}
+\sstroutine{
+   astWinMap
+}{
+   Create a WinMap
+}{
+   \sstdescription{
+      This function creates a new \htmlref{WinMap}{WinMap} and optionally initialises its
+      attributes.
+
+      A Winmap is a linear \htmlref{Mapping}{Mapping} which transforms a rectangular
+      window in one coordinate system into a similar window in another
+      coordinate system by scaling and shifting each axis (the window
+      edges being parallel to the coordinate axes).
+
+      A WinMap is specified by giving the coordinates of two opposite
+      corners (A and B) of the window in both the input and output
+      coordinate systems.
+   }
+   \sstsynopsis{
+      AstWinMap $*$astWinMap( int ncoord,
+                            const double ina[],  const double inb[],
+                            const double outa[], const double outb[],
+                            const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         ncoord
+      }{
+         The number of coordinate values for each point to be
+         transformed (i.e. the number of dimensions of the space in
+         which the points will reside). The same number is applicable
+         to both input and output points.
+      }
+      \sstsubsection{
+         ina
+      }{
+         An array containing the \texttt{"} ncoord\texttt{"}
+         coordinates of corner A of the window in the input coordinate
+         system.
+      }
+      \sstsubsection{
+         inb
+      }{
+         An array containing the \texttt{"} ncoord\texttt{"}
+         coordinates of corner B of the window in the input coordinate
+         system.
+      }
+      \sstsubsection{
+         outa
+      }{
+         An array containing the \texttt{"} ncoord\texttt{"}
+         coordinates of corner A of the window in the output coordinate
+         system.
+      }
+      \sstsubsection{
+         outb
+      }{
+         An array containing the \texttt{"} ncoord\texttt{"}
+         coordinates of corner B of the window in the output coordinate
+         system.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new WinMap. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astWinMap()
+      }{
+         A pointer to the new WinMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      Status Handling
+   }{
+      The protected interface to this function includes an extra
+      parameter at the end of the parameter list descirbed above. This
+      parameter is a pointer to the integer inherited status
+      variable: \texttt{"} int $*$status\texttt{"} .
+   }
+}
+\sstroutine{
+   astWrite
+}{
+   Write an Object to a Channel
+}{
+   \sstdescription{
+      This function writes an \htmlref{Object}{Object} to a \htmlref{Channel}{Channel}, appending it to any
+      previous Objects written to that Channel.
+   }
+   \sstsynopsis{
+      int astWrite( AstChannel $*$this, AstObject $*$object )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the Channel.
+      }
+      \sstsubsection{
+         object
+      }{
+         Pointer to the Object which is to be written.
+      }
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{FitsChan}{FitsChan}
+      }{
+         If the FitsChan uses a foreign encoding (e.g. FITS-WCS) rather
+         than the native AST encoding, then storing values in the
+         FitsChan for keywords NAXIS1, NAXIS2, etc., before invoking
+         astWrite
+         can help to produce a successful write.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astWrite()
+      }{
+         The number of Objects written to the Channel by this
+         invocation of astWrite (normally, this will be one).
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A value of zero will be returned if this function is invoked
+         with the AST error status set, or if it should fail for any
+         reason.
+
+         \sstitem
+          Invoking this function will usually cause the sink function
+         associated with the channel to be called in order to transfer a
+         textual description of the supplied object to some external data
+         store. However, the FitsChan class behaves differently. Invoking
+         this function on a FitsChan causes new FITS header cards to be
+         added to an internal buffer (the sink function is not invoked).
+         This buffer is written out through the sink function only when the
+         FitsChan is deleted.
+      }
+   }
+}
+\sstroutine{
+   astWriteFits
+}{
+   Write out all cards in a FitsChan to the sink function
+}{
+   \sstdescription{
+      This function
+      writes out all cards currently in the \htmlref{FitsChan}{FitsChan}. If the \htmlref{SinkFile}{SinkFile}
+      attribute is set, they will be written out to the specified sink file.
+      Otherwise, they will be written out using the sink function specified
+      when the FitsChan was created. All cards are then deleted from the
+      FitsChan.
+   }
+   \sstsynopsis{
+      void astWriteFits( AstFitsChan $*$this )
+   }
+   \sstparameters{
+      \sstsubsection{
+         this
+      }{
+         Pointer to the FitsChan.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If the SinkFile is unset, and no sink function is available, this
+         method simply empties the FitsChan, and is then equivalent to
+         \htmlref{astEmptyFits}{astEmptyFits}.
+
+         \sstitem
+          This method attempt to execute even if an error has occurred
+         previously.
+      }
+   }
+}
+\sstroutine{
+   astXmlChan
+}{
+   Create an XmlChan
+}{
+   \sstdescription{
+      This function creates a new \htmlref{XmlChan}{XmlChan} and optionally initialises
+      its attributes.
+
+      A XmlChan is a specialised form of \htmlref{Channel}{Channel} which supports XML I/O
+      operations. Writing an \htmlref{Object}{Object} to an XmlChan (using
+      \htmlref{astWrite}{astWrite}) will, if the Object is suitable, generate an
+      XML description of that Object, and reading from an XmlChan will
+      create a new Object from its XML description.
+
+      Normally, when you use an XmlChan, you should provide \texttt{"} source\texttt{"}
+      and \texttt{"} sink\texttt{"}  functions which connect it to an external data store
+      by reading and writing the resulting XML text. By default, however,
+      an XmlChan will read from standard input and write to standard
+      output.
+
+      Alternatively, an XmlChan can be told to read or write from
+      specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes,
+      in which case no sink or source function need be supplied.
+   }
+   \sstsynopsis{
+      AstXmlChan $*$astXmlChan( const char $*$($*$ source)( void ),
+                              void ($*$ sink)( const char $*$ ),
+                              const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         source
+      }{
+         Pointer to a source function that takes no arguments and
+         returns a pointer to a null-terminated string.  If no value
+         has been set for the SourceFile attribute, this function
+         will be used by the XmlChan to obtain lines of input text. On
+         each invocation, it should return a pointer to the next input
+         line read from some external data store, and a NULL pointer
+         when there are no more lines to read.
+
+         If \texttt{"} source\texttt{"}  is NULL and no value has been set for the SourceFile
+         attribute, the XmlChan will read from standard input instead.
+      }
+      \sstsubsection{
+         sink
+      }{
+         Pointer to a sink function that takes a pointer to a
+         null-terminated string as an argument and returns void.
+         If no value has been set for the SinkFile attribute, this
+         function will be used by the XmlChan to deliver lines of
+         output text. On each invocation, it should deliver the
+         contents of the string supplied to some external data store.
+
+         If \texttt{"} sink\texttt{"}  is NULL, and no value has been set for the SinkFile
+         attribute, the XmlChan will write to standard output instead.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new XmlChan. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astXmlChan()
+      }{
+         A pointer to the new XmlChan.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If the external data source or sink uses a character encoding
+         other than ASCII, the supplied source and sink functions should
+         translate between the external character encoding and the internal
+         ASCII encoding used by AST.
+
+         \sstitem
+          A null Object pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astZoomMap
+}{
+   Create a ZoomMap
+}{
+   \sstdescription{
+      This function creates a new \htmlref{ZoomMap}{ZoomMap} and optionally initialises its
+      attributes.
+
+      A ZoomMap is a \htmlref{Mapping}{Mapping} which \texttt{"} zooms\texttt{"}  a set of points about the
+      origin by multiplying all coordinate values by the same scale
+      factor (the inverse transformation is performed by dividing by
+      this scale factor).
+   }
+   \sstsynopsis{
+      AstZoomMap $*$astZoomMap( int ncoord, double zoom,
+                              const char $*$options, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         ncoord
+      }{
+         The number of coordinate values for each point to be
+         transformed (i.e. the number of dimensions of the space in
+         which the points will reside). The same number is applicable
+         to both input and output points.
+      }
+      \sstsubsection{
+         zoom
+      }{
+         Initial scale factor by which coordinate values should be
+         multiplied (by the forward transformation) or divided (by the
+         inverse transformation). This factor may subsequently be
+         changed via the ZoomMap\texttt{'} s \htmlref{Zoom}{Zoom} attribute. It may be positive
+         or negative, but should not be zero.
+      }
+      \sstsubsection{
+         options
+      }{
+         Pointer to a null-terminated string containing an optional
+         comma-separated list of attribute assignments to be used for
+         initialising the new ZoomMap. The syntax used is identical to
+         that for the \htmlref{astSet}{astSet} function and may include \texttt{"} printf\texttt{"}  format
+         specifiers identified by \texttt{"} \%\texttt{"}  symbols in the normal way.
+      }
+      \sstsubsection{
+         ...
+      }{
+         If the \texttt{"} options\texttt{"}  string contains \texttt{"} \%\texttt{"}  format specifiers, then
+         an optional list of additional arguments may follow it in
+         order to supply values to be substituted for these
+         specifiers. The rules for supplying these are identical to
+         those for the astSet function (and for the C \texttt{"} printf\texttt{"}
+         function).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astZoomMap()
+      }{
+         A pointer to the new ZoomMap.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A null \htmlref{Object}{Object} pointer (AST\_\_NULL) will be returned if this
+         function is invoked with the AST error status set, or if it
+         should fail for any reason.
+      }
+   }
+   \sstdiytopic{
+      Status Handling
+   }{
+      The protected interface to this function includes an extra
+      parameter at the end of the parameter list descirbed above. This
+      parameter is a pointer to the integer inherited status
+      variable: \texttt{"} int $*$status\texttt{"} .
+   }
+}
+\normalsize
+
+\cleardoublepage
+\section{\label{ss:attributedescriptions}AST Attribute Descriptions}
+\small
+\sstroutine{
+   Abbrev(axis)
+}{
+   Abbreviate leading fields within numerical axis labels?
+}{
+   \sstdescription{
+      This attribute controls the appearance of an annotated
+      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
+      whether matching leading fields should be removed from adjacent
+      numerical axis labels. It takes a separate value for each physical
+      axis of a \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} Abbrev(2)=0\texttt{"}
+      specifies that matching leading fields should not be removed on
+      the second axis.
+
+      If the Abbrev value of a Plot is non-zero (the default), then
+      leading fields will be removed from adjacent axis labels if they
+      are equal.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If no axis is specified, (e.g. \texttt{"} Abbrev\texttt{"}  instead of
+         \texttt{"} Abbrev(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect
+         the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or
+         \texttt{"} test\texttt{"}  operation will use just the Abbrev(1) value.
+      }
+   }
+}
+\sstroutine{
+   Adaptive
+}{
+   Should the area adapt to changes in the coordinate system?
+}{
+   \sstdescription{
+      The coordinate system represented by a \htmlref{Region}{Region} may be changed by
+      assigning new values to attributes such as \htmlref{System}{System}, Unit, etc.
+      For instance, a Region representing an area on the sky in ICRS
+      coordinates may have its System attribute changed so that it
+      represents (say) Galactic coordinates instead of ICRS. This
+      attribute controls what happens when the coordinate system
+      represented by a Region is changed in this way.
+
+      If Adaptive is non-zero (the default), then area represented by the
+      Region adapts to the new coordinate system. That is, the numerical
+      values which define the area represented by the Region are changed
+      by mapping them from the old coordinate system into the new coordinate
+      system. Thus the Region continues to represent the same physical
+      area.
+
+      If Adaptive is zero, then area represented by the Region does not adapt
+      to the new coordinate system. That is, the numerical values which
+      define the area represented by the Region are left unchanged. Thus
+      the physical area represented by the Region will usually change.
+
+      As an example, consider a Region describe a range of wavelength from
+      2000 Angstrom to 4000 Angstrom. If the Unit attribute for the Region
+      is changed from Angstrom to \texttt{"} nm\texttt{"}  (nanometre), what happens depends
+      on the setting of Adaptive. If Adaptive is non-zero, the \htmlref{Mapping}{Mapping}
+      from the old to the new coordinate system is found. In this case it
+      is a simple scaling by a factor of 0.1 (since 1 Angstrom is 0.1 nm).
+      This Mapping is then used to modify the numerical values within the
+      Region, changing 2000 to 200 and 4000 to 400. Thus the modified
+      region represents 200 nm to 400 nm, the same physical space as
+      the original 2000 Angstrom to 4000 Angstrom. However, if Adaptive
+      had been zero, then the numerical values would not have been changed,
+      resulting in the final Region representing 2000 nm to 4000 nm.
+
+      Setting Adaptive to zero can be necessary if you want correct
+      inaccurate attribute settings in an existing Region. For instance,
+      when creating a Region you may not know what \htmlref{Epoch}{Epoch} value to use, so
+      you would leave Epoch unset resulting in some default value being used.
+      If at some later point in the application, the correct Epoch value
+      is determined, you could assign the correct value to the Epoch
+      attribute. However, you would first need to set Adaptive temporarily
+      to zero, because otherwise the area represented by the Region would
+      be Mapped from the spurious default Epoch to the new correct Epoch,
+      which is not what is required.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Region
+      }{
+         All Regions have this attribute.
+      }
+   }
+}
+\sstroutine{
+   AlignOffset
+}{
+   Align SkyFrames using the offset coordinate system?
+}{
+   \sstdescription{
+      This attribute is a boolean value which controls how a \htmlref{SkyFrame}{SkyFrame}
+      behaves when it is used (by
+      \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}) as a template to match another (target)
+      SkyFrame. It determines the coordinate system in which the two
+      SkyFrames are aligned if a match occurs.
+
+      If the template and target SkyFrames both have defined offset coordinate
+      systems (i.e. the \htmlref{SkyRefIs}{SkyRefIs} attribute is set to either \texttt{"} Origin\texttt{"}  or \texttt{"}
+      Pole\texttt{"} ), and they both have a non-zero value for AlignOffset, then
+      alignment occurs within the offset coordinate systems (that is, a
+      \htmlref{UnitMap}{UnitMap} will always be used to align the two SkyFrames). If either
+      the template or target SkyFrame has zero (the default value) for
+      AlignOffset, or if either SkyFrame has SkyRefIs set to \texttt{"} Ignored\texttt{"} , then
+      alignment occurring within the coordinate system specified by the
+      \htmlref{AlignSystem}{AlignSystem} attribute.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         SkyFrame
+      }{
+         All SkyFrames have this attribute.
+      }
+   }
+}
+\sstroutine{
+   AlignSideBand
+}{
+   Should the SideBand attribute be taken into account when aligning
+   this \htmlref{DSBSpecFrame}{DSBSpecFrame} with another DSBSpecFrame?
+}{
+   \sstdescription{
+      This attribute controls how a DSBSpecFrame behaves when an attempt
+      is made to align it with another DSBSpecFrame using
+      \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}.
+      If both DSBSpecFrames have a non-zero value for AlignSideBand, the
+      value of the \htmlref{SideBand}{SideBand} attribute in each DSBSpecFrame is used so that
+      alignment occurs between sidebands. That is, if one DSBSpecFrame
+      represents USB and the other represents LSB then
+      astFindFrame and astConvert
+      will recognise that the DSBSpecFrames represent different sidebands
+      and will take this into account when constructing the \htmlref{Mapping}{Mapping} that
+      maps positions in one DSBSpecFrame into the other. If AlignSideBand
+      in either DSBSpecFrame is set to zero, then the values of the SideBand
+      attributes are ignored. In the above example, this would result in a
+      frequency in the first DSBSpecFrame being mapped onto the same
+      frequency in the second DSBSpecFrame, even though those frequencies
+      refer to different sidebands. In other words, if either AlignSideBand
+      attribute is zero, then the two DSBSpecFrames aligns like basic
+      SpecFrames. The default value for AlignSideBand is zero.
+
+      When astFindFrame or astConvert
+      is used on two DSBSpecFrames (potentially describing different spectral
+      coordinate systems and/or sidebands), it returns a Mapping which can be
+      used to transform a position in one DSBSpecFrame into the corresponding
+      position in the other. The Mapping is made up of the following steps in
+      the indicated order:
+
+      \sstitemlist{
+
+         \sstitem
+          If both DSBSpecFrames have a value of 1 for the AlignSideBand
+         attribute, map values from the target\texttt{'} s current sideband (given by its
+         SideBand attribute) to the observed sideband (whether USB or LSB). If
+         the target already represents the observed sideband, this step will
+         leave the values unchanged. If either of the two DSBSpecFrames have a
+         value of zero for its AlignSideBand attribute, then this step is omitted.
+
+         \sstitem
+          Map the values from the spectral system of the target to the spectral
+         system of the template. This Mapping takes into account all the
+         inherited \htmlref{SpecFrame}{SpecFrame} attributes such as \htmlref{System}{System}, \htmlref{StdOfRest}{StdOfRest}, Unit, etc.
+
+         \sstitem
+          If both DSBSpecFrames have a value of 1 for the AlignSideBand
+         attribute, map values from the result\texttt{'} s observed sideband to the
+         result\texttt{'} s current sideband (given by its SideBand attribute). If the
+         result already represents the observed sideband, this step will leave
+         the values unchanged. If either of the two DSBSpecFrames have a value
+         of zero for its AlignSideBand attribute, then this step is omitted.
+      }
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         DSBSpecFrame
+      }{
+         All DSBSpecFrames have this attribute.
+      }
+   }
+}
+\sstroutine{
+   AlignSpecOffset
+}{
+   Align SpecFrames using the offset coordinate system?
+}{
+   \sstdescription{
+      This attribute is a boolean value which controls how a \htmlref{SpecFrame}{SpecFrame}
+      behaves when it is used (by
+      \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}) as a template to match another (target)
+      SpecFrame. It determines whether alignment occurs between the offset
+      values defined by the current value of the SpecOffset attribute, or
+      between the corresponding absolute spectral values.
+
+      The default value of zero results in the two SpecFrames being aligned
+      so that a given absolute spectral value in one is mapped to the same
+      absolute value in the other. A non-zero value results in the SpecFrames
+      being aligned so that a given offset value in one is mapped to the same
+      offset value in the other.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         SpecFrame
+      }{
+         All SpecFrames have this attribute.
+      }
+   }
+}
+\sstroutine{
+   AlignStdOfRest
+}{
+   Standard of rest to use when aligning SpecFrames
+}{
+   \sstdescription{
+      This attribute controls how a \htmlref{SpecFrame}{SpecFrame} behaves when it is used (by
+      \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}) as a template to match another (target)
+      SpecFrame. It identifies the standard of rest in which alignment is
+      to occur. See the \htmlref{StdOfRest}{StdOfRest} attribute for a desription of the values
+      which may be assigned to this attribute. The default AlignStdOfRest
+      value is \texttt{"} Helio\texttt{"}  (heliographic).
+
+      When astFindFrame or astConvert is used on two SpecFrames (potentially
+      describing different spectral coordinate systems), it returns a \htmlref{Mapping}{Mapping}
+      which can be used to transform a position in one SpecFrame into the
+      corresponding position in the other. The Mapping is made up of the
+      following steps in the indicated order:
+
+      \sstitemlist{
+
+         \sstitem
+          Map values from the system used by the target (wavelength,
+         apparent radial velocity, etc) to the system specified by the
+         \htmlref{AlignSystem}{AlignSystem} attribute, using the target\texttt{'} s rest frequency if necessary.
+
+         \sstitem
+          Map these values from the target\texttt{'} s standard of rest to the standard of
+         rest specified by the AlignStdOfRest attribute, using the \htmlref{Epoch}{Epoch}, \htmlref{ObsLat}{ObsLat},
+         \htmlref{ObsLon}{ObsLon}, \htmlref{ObsAlt}{ObsAlt}, \htmlref{RefDec}{RefDec} and \htmlref{RefRA}{RefRA} attributes of the target to define the
+         two standards of rest.
+
+         \sstitem
+          Map these values from the standard of rest specified by the
+         AlignStdOfRest attribute, to the template\texttt{'} s standard of rest, using the
+         Epoch, ObsLat, ObsLon, ObsAlt, RefDec and RefRA attributes of the
+         template to define the two standards of rest.
+
+         \sstitem
+          Map these values from the system specified by the AlignSystem
+         attribute, to the system used by the template, using the template\texttt{'} s
+         rest frequency if necessary.
+      }
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         SpecFrame
+      }{
+         All SpecFrames have this attribute.
+      }
+   }
+}
+\sstroutine{
+   AlignSystem
+}{
+   Coordinate system in which to align the Frame
+}{
+   \sstdescription{
+      This attribute controls how a \htmlref{Frame}{Frame} behaves when it is used (by
+      \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}) as a template to match another (target)
+      Frame. It identifies the coordinate system in which the two Frames
+      will be aligned by the match.
+
+      The values which may be assigned to this attribute, and its default
+      value, depend on the class of Frame and are described in the
+      \texttt{"} Applicability\texttt{"}  section below. In general, the AlignSystem attribute
+      will accept any of the values which may be assigned to the \htmlref{System}{System}
+      attribute.
+
+      The \htmlref{Mapping}{Mapping} returned by AST\_FINDFRAME or AST\_CONVERT will use the
+      coordinate system specified by the AlignSystem attribute as an
+      intermediate coordinate system. The total returned Mapping will first
+      map positions from the first Frame into this intermediate coordinate
+      system, using the attributes of the first Frame. It will then map
+      these positions from the intermediate coordinate system into the
+      second Frame, using the attributes of the second Frame.
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Frame
+      }{
+         The AlignSystem attribute for a basic Frame always equals \texttt{"} Cartesian\texttt{"} ,
+         and may not be altered.
+      }
+      \sstsubsection{
+         \htmlref{CmpFrame}{CmpFrame}
+      }{
+         The AlignSystem attribute for a CmpFrame always equals \texttt{"} Compound\texttt{"} ,
+         and may not be altered.
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         The AlignSystem attribute of a FrameSet is the same as that of its
+         current Frame (as specified by the \htmlref{Current}{Current} attribute).
+      }
+      \sstsubsection{
+         \htmlref{SkyFrame}{SkyFrame}
+      }{
+         The default AlignSystem attribute for a SkyFrame is \texttt{"} ICRS\texttt{"} .
+      }
+      \sstsubsection{
+         \htmlref{SpecFrame}{SpecFrame}
+      }{
+         The default AlignSystem attribute for a SpecFrame is \texttt{"} Wave\texttt{"}
+         (wavelength).
+      }
+      \sstsubsection{
+         \htmlref{TimeFrame}{TimeFrame}
+      }{
+         The default AlignSystem attribute for a TimeFrame is \texttt{"} MJD\texttt{"} .
+      }
+   }
+}
+\sstroutine{
+   AlignTimeScale
+}{
+   Time scale to use when aligning TimeFrames
+}{
+   \sstdescription{
+      This attribute controls how a \htmlref{TimeFrame}{TimeFrame} behaves when it is used (by
+      \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}) as a template to match another (target)
+      TimeFrame. It identifies the time scale in which alignment is
+      to occur. See the \htmlref{TimeScale}{TimeScale} attribute for a desription of the values
+      which may be assigned to this attribute. The default AlignTimeScale
+      value depends on the current value of TimeScale: if TimeScale is
+      UT1, GMST, LMST or LAST, the default for AlignTimeScale is UT1, for all
+      other TimeScales the default is TAI.
+
+      When astFindFrame or astConvert is used on two TimeFrames (potentially
+      describing different time coordinate systems), it returns a \htmlref{Mapping}{Mapping}
+      which can be used to transform a position in one TimeFrame into the
+      corresponding position in the other. The Mapping is made up of the
+      following steps in the indicated order:
+
+      \sstitemlist{
+
+         \sstitem
+          Map values from the system used by the target (MJD, JD, etc) to the
+         system specified by the \htmlref{AlignSystem}{AlignSystem} attribute.
+
+         \sstitem
+          Map these values from the target\texttt{'} s time scale to the time scale
+         specified by the AlignTimeScale attribute.
+
+         \sstitem
+          Map these values from the time scale specified by the AlignTimeScale
+         attribute, to the template\texttt{'} s time scale.
+
+         \sstitem
+          Map these values from the system specified by the AlignSystem
+         attribute, to the system used by the template.
+      }
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         TimeFrame
+      }{
+         All TimeFrames have this attribute.
+      }
+   }
+}
+\sstroutine{
+   AllVariants
+}{
+   A list of the variant Mappings associated with the current Frame
+}{
+   \sstdescription{
+      This attribute gives a space separated list of the names of all the
+      variant Mappings associated with the current \htmlref{Frame}{Frame} (see attribute
+      \texttt{"} \htmlref{Variant}{Variant}\texttt{"} ). If the current Frame has no variant Mappings, then the
+      list will hold a single entry equal to the \htmlref{Domain}{Domain} name of the
+      current Frame.
+   }
+   \sstattributetype{
+      String, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         All FrameSets have this attribute.
+      }
+   }
+}
+\sstroutine{
+   AllWarnings
+}{
+   A list of all currently available condition names
+}{
+   \sstdescription{
+      This read-only attribute is a space separated list of all the conditions
+      names recognized by the \htmlref{Warnings}{Warnings} attribute. The names are listed
+      below.
+   }
+   \sstattributetype{
+      String, read-only
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{FitsChan}{FitsChan}
+      }{
+         All FitsChans have this attribute.
+      }
+   }
+   \sstdiytopic{
+      Conditions
+   }{
+      The following conditions are currently recognised (all are
+      case-insensitive):
+
+      \sstitemlist{
+
+         \sstitem
+          \texttt{"} BadCel\texttt{"} : This condition arises when reading a \htmlref{FrameSet}{FrameSet} from a
+         non-Native encoded FitsChan if an unknown celestial co-ordinate
+         system is specified by the CTYPE keywords.
+
+         \sstitem
+          \texttt{"} BadCTYPE\texttt{"} : This condition arises when reading a FrameSet from a
+         non-Native encoded FitsChan if an illegal algorithm code is specified
+         by a CTYPE keyword, and the illegal code can be converted to an
+         equivalent legal code.
+
+         \sstitem
+          \texttt{"} BadKeyName\texttt{"} : This condition arises if a FITS keyword name is
+         encountered that contains an illegal character (i.e. one not allowed
+         by the FITS standard).
+
+         \sstitem
+          \texttt{"} BadKeyValue\texttt{"} : This condition arises if the value of a FITS keyword
+         cannot be determined from the content of the header card.
+
+         \sstitem
+          \texttt{"} BadLat\texttt{"} : This condition arises when reading a FrameSet from a
+         non-Native encoded FitsChan if the latitude of the reference point
+         has an absolute value greater than 90 degrees. The actual absolute
+         value used is set to exactly 90 degrees in these cases.
+
+         \sstitem
+          \texttt{"} BadMat\texttt{"} : This condition arises if the matrix describing the
+         transformation from pixel offsets to intermediate world coordinates
+         cannot be inverted. This matrix describes the scaling, rotation, shear,
+         etc., applied to the pixel axes, and is specified by keywords such as
+         PCi\_j, CDi\_j, CROTA, etc. For example, the matrix will not be invertable
+         if any rows or columns consist entirely of zeros. The FITS-WCS Paper I
+         \texttt{"} Representation of World Coordinates in FITS\texttt{"}  by Greisen \& Calabretta
+         requires that this matrix be invertable. Many operations (such as
+         grid plotting) will not be possible if the matrix cannot be inverted.
+
+         \sstitem
+          \texttt{"} BadPV\texttt{"} : This condition arises when reading a FrameSet from a
+         non-Native encoded FitsChan. It is issued if a \htmlref{PVi\_m}{PVi\_m} header is found
+         that refers to a projection parameter that is not used by the
+         projection type specified by CTYPE, or the PV values are otherwise
+         inappropriate for the projection type.
+
+         \sstitem
+          \texttt{"} BadVal\texttt{"} : This condition arises when reading a FrameSet from a
+         non-Native encoded FitsChan if it is not possible to convert the
+         value of a FITS keywords to the expected type. For instance, this
+         can occur if the FITS header contains a string value for a keyword
+         which should have a floating point value, or if the keyword has no
+         value at all (i.e. is a comment card).
+
+         \sstitem
+          \texttt{"} Distortion\texttt{"} : This condition arises when reading a FrameSet from a
+         non-Native encoded FitsChan if any of the CTYPE keywords specify an
+         unsupported distortion code using the \texttt{"} 4-3-3\texttt{"}  format specified in
+         FITS-WCS paper IV. Such distortion codes are ignored.
+
+         \sstitem
+          \texttt{"} NoCTYPE\texttt{"} : This condition arises if a default CTYPE value is used
+         within \htmlref{astRead}{astRead}, due to no value being present in the supplied FitsChan.
+         This condition is only tested for when using non-Native encodings.
+
+         \sstitem
+          \texttt{"} NoEquinox\texttt{"} : This condition arises if a default equinox value is used
+         within astRead, due to no value being present in the supplied FitsChan.
+         This condition is only tested for when using non-Native encodings.
+
+         \sstitem
+          \texttt{"} NoRadesys\texttt{"} : This condition arises if a default reference frame is
+         used for an equatorial co-ordinate system within astRead, due to no
+         value being present in the supplied FitsChan. This condition is only
+         tested for when using non-Native encodings.
+
+         \sstitem
+          \texttt{"} NoLonpole\texttt{"} : This condition arises if a default value is used for
+         the LONPOLE keyword within astRead, due to no value being present
+         in the supplied FitsChan. This condition is only tested for when
+         using non-Native encodings.
+
+         \sstitem
+          \texttt{"} NoLatpole\texttt{"} : This condition arises if a default value is used for
+         the LATPOLE keyword within astRead, due to no value being present
+         in the supplied FitsChan. This condition is only tested for when
+         using non-Native encodings.
+
+         \sstitem
+          \texttt{"} NoMjd-obs\texttt{"} : This condition arises if a default value is used for
+         the date of observation within astRead, due to no value being present
+         in the supplied FitsChan. This condition is only tested for when using
+         non-Native encodings.
+
+         \sstitem
+          \texttt{"} Tnx\texttt{"} : This condition arises if a FrameSet is read from a FITS
+         header containing an IRAF \texttt{"} TNX\texttt{"}  projection which includes terms
+         not supproted by AST. Such terms are ignored and so the resulting
+         FrameSet may be inaccurate.
+
+         \sstitem
+          \texttt{"} Zpx\texttt{"} : This condition arises if a FrameSet is read from a FITS
+         header containing an IRAF \texttt{"} ZPX\texttt{"}  projection which includes \texttt{"} lngcor\texttt{"}
+         or \texttt{"} latcor\texttt{"}  correction terms. These terms are not supported by AST
+         and are ignored. The resulting FrameSet may therefore be inaccurate.
+      }
+   }
+}
+\sstroutine{
+   AsTime(axis)
+}{
+   Format celestal coordinates as times?
+}{
+   \sstdescription{
+      This attribute specifies the default style of formatting to be
+      used (e.g. by \htmlref{astFormat}{astFormat}) for the celestial coordinate values
+      described by a \htmlref{SkyFrame}{SkyFrame}. It takes a separate boolean value for
+      each SkyFrame axis so that, for instance, the setting
+      \texttt{"} AsTime(2)=0\texttt{"}  specifies the default formatting style for
+      celestial latitude values.
+
+      If the AsTime attribute for a SkyFrame axis is zero, then
+      coordinates on that axis will be formatted as angles by default
+      (using degrees, minutes and seconds), otherwise they will be
+      formatted as times (using hours, minutes and seconds).
+
+      The default value of AsTime is chosen according to the sky
+      coordinate system being represented, as determined by the
+      SkyFrame\texttt{'} s \htmlref{System}{System} attribute. This ensures, for example, that
+      right ascension values will be formatted as times by default,
+      following normal conventions.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         SkyFrame
+      }{
+         All SkyFrames have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The AsTime attribute operates by changing the default value of
+         the corresponding \htmlref{Format(axis)}{Format(axis)} attribute. This, in turn, may
+         also affect the value of the \htmlref{Unit(axis)}{Unit(axis)} attribute.
+
+         \sstitem
+          Only the default style of formatting is affected by the AsTime
+         value. If an explicit Format(axis) value is set, it will
+         over-ride any effect from the AsTime attribute.
+      }
+   }
+}
+\sstroutine{
+   Base
+}{
+   FrameSet base Frame index
+}{
+   \sstdescription{
+      This attribute gives the index of the \htmlref{Frame}{Frame} which is to be
+      regarded as the \texttt{"} base\texttt{"}  Frame within a \htmlref{FrameSet}{FrameSet}. The default is
+      the first Frame added to the FrameSet when it is created (this
+      Frame always has an index of 1).
+
+      When setting a new value for this attribute, a string may be
+      supplied instead of an integer index. In this case a search
+      is made within the FrameSet for a Frame that has its \htmlref{Domain}{Domain}
+      attribute value equal to the supplied string (the comparison is
+      case-insensitive). If found, the Frame is made the base Frame.
+      Otherwise an error is reported.
+   }
+   \sstattributetype{
+      Integer.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         FrameSet
+      }{
+         All FrameSets have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Inverting a FrameSet (inverting the boolean sense of its
+         \htmlref{Invert}{Invert} attribute, with the \htmlref{astInvert}{astInvert} function for example) will
+         interchange the values of its Base and \htmlref{Current}{Current} attributes.
+      }
+   }
+}
+\sstroutine{
+   Border
+}{
+   Draw a border around valid regions of a Plot?
+}{
+   \sstdescription{
+      This attribute controls the appearance of an annotated
+      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
+      whether a border is drawn around regions corresponding to the
+      valid physical coordinates of a \htmlref{Plot}{Plot} (c.f. \htmlref{astBorder}{astBorder}).
+
+      If the Border value of a Plot is non-zero, then this border will
+      be drawn as part of the grid. Otherwise, the border is not drawn
+      (although axis labels and tick marks will still appear, unless
+      other relevant Plot attributes indicate that they should
+      not). The default behaviour is to draw the border if tick marks
+      and numerical labels will be drawn around the edges of the
+      plotting area (see the \htmlref{Labelling}{Labelling} attribute), but to omit it
+      otherwise.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Bottom(axis)
+}{
+   Lowest axis value to display
+}{
+   \sstdescription{
+      This attribute gives the lowest axis value to be displayed (for
+      instance, by the \htmlref{astGrid}{astGrid} method).
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{Frame}{Frame}
+      }{
+         The default supplied by the Frame class is to display all axis
+         values, without any limit.
+      }
+      \sstsubsection{
+         \htmlref{SkyFrame}{SkyFrame}
+      }{
+         The SkyFrame class re-defines the default Bottom value to -90 degrees
+         for latitude axes, and 0 degrees for co-latitude axes. The
+         default for longitude axes is to display all axis values.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          When specifying this attribute by name, it should be
+         subscripted with the number of the Frame axis to which it
+         applies.
+      }
+   }
+}
+\sstroutine{
+   Bounded
+}{
+   Is the Region bounded?
+}{
+   \sstdescription{
+      This is a read-only attribute indicating if the \htmlref{Region}{Region} is bounded.
+      A Region is bounded if it is contained entirely within some
+      finite-size bounding box.
+   }
+   \sstattributetype{
+      Integer (boolean), read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Region
+      }{
+         All Regions have this attribute.
+      }
+   }
+}
+\sstroutine{
+   CDMatrix
+}{
+   Use CDi\_j keywords to represent pixel scaling, rotation, etc?
+}{
+   \sstdescription{
+      This attribute is a boolean value which specifies how the linear
+      transformation from pixel coordinates to intermediate world
+      coordinates should be represented within a \htmlref{FitsChan}{FitsChan} when using
+      FITS-WCS encoding. This transformation describes the scaling,
+      rotation, shear, etc., of the pixel axes.
+
+      If the attribute has a non-zero value then the transformation is
+      represented by a set of CDi\_j keywords representing a square matrix
+      (where \texttt{"} i\texttt{"}  is the index of an intermediate world coordinate axis
+      and \texttt{"} j\texttt{"}  is the index of a pixel axis). If the attribute has a zero
+      value the transformation is represented by a set of PCi\_j keywords
+      (which also represent a square matrix) together with a corresponding
+      set of CDELTi keywords representing the axis scalings. See FITS-WCS
+      paper II \texttt{"} Representation of Celestial Coordinates in FITS\texttt{"}  by
+      M. Calabretta \& E.W. Greisen, for a complete description of these two
+      schemes.
+
+      The default value of the CDMatrix attribute is determined by the
+      contents of the FitsChan at the time the attribute is accessed. If
+      the FitsChan contains any CDi\_j keywords then the default value is
+      non-zero. Otherwise it is zero. Note, reading a \htmlref{FrameSet}{FrameSet} from a
+      FitsChan will in general consume any CDi\_j keywords present in the
+      FitsChan. Thus the default value for CDMatrix following a read will
+      usually be zero, even if the FitsChan originally contained some
+      CDi\_j keywords. This behaviour is similar to that of the \htmlref{Encoding}{Encoding}
+      attribute, the default value for which is determined by the contents
+      of the FitsChan at the time the attribute is accessed. If you wish
+      to retain the original value of the CDMatrix attribute (that is,
+      the value before reading the FrameSet) then you should enquire the
+      default value before doing the read, and then set that value
+      explicitly.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         FitsChan
+      }{
+         All FitsChans have this attribute.
+      }
+   }
+}
+\sstroutine{
+   CarLin
+}{
+   Ignore spherical rotations on CAR projections?
+}{
+   \sstdescription{
+      This attribute is a boolean value which specifies how FITS \texttt{"} CAR\texttt{"}
+      (plate carree, or \texttt{"} Cartesian\texttt{"} ) projections should be treated when
+      reading a \htmlref{FrameSet}{FrameSet} from a foreign encoded FITS header. If zero (the
+      default), it is assumed that the CAR projection conforms to the
+      conventions described in the FITS world coordinate system (FITS-WCS)
+      paper II \texttt{"} Representation of Celestial Coordinates in FITS\texttt{"}  by
+      M. Calabretta \& E.W. Greisen. If CarLin is non-zero, then these
+      conventions are ignored, and it is assumed that the mapping from pixel
+      coordinates to celestial coordinates is a simple linear transformation
+      (hence the attribute name \texttt{"} CarLin\texttt{"} ). This is appropriate for some older
+      FITS data which claims to have a \texttt{"} CAR\texttt{"}  projection, but which in fact do
+      not conform to the conventions of the FITS-WCS paper.
+
+      The FITS-WCS paper specifies that headers which include a CAR projection
+      represent a linear mapping from pixel coordinates to \texttt{"} native spherical
+      coordinates\texttt{"} , NOT celestial coordinates. An extra mapping is then
+      required from native spherical to celestial. This mapping is a 3D
+      rotation and so the overall \htmlref{Mapping}{Mapping} from pixel to celestial coordinates
+      is NOT linear. See the FITS-WCS papers for further details.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{FitsChan}{FitsChan}
+      }{
+         All FitsChans have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Card
+}{
+   Index of current FITS card in a FitsChan
+}{
+   \sstdescription{
+      This attribute gives the index of the \texttt{"} current\texttt{"}  FITS header card
+      within a \htmlref{FitsChan}{FitsChan}, the first card having an index of 1. The
+      choice of current card affects the behaviour of functions that
+      access the contents of the FitsChan, such as \htmlref{astDelFits}{astDelFits},
+      \htmlref{astFindFits}{astFindFits} and \htmlref{astPutFits}{astPutFits}.
+
+      A value assigned to Card will position the FitsChan at any
+      desired point, so that a particular card within it can be
+      accessed. Alternatively, the value of Card may be enquired in
+      order to determine the current position of a FitsChan.
+
+      The default value of Card is 1. This means that clearing
+      this attribute (using \htmlref{astClear}{astClear}) effectively \texttt{"} rewinds\texttt{"}  the
+      FitsChan, so that the first card is accessed next.  If Card is
+      set to a value which exceeds the total number of cards in the
+      FitsChan (as given by its \htmlref{Ncard}{Ncard} attribute), it is regarded as
+      pointing at the \texttt{"} end-of-file\texttt{"} . In this case, the value returned
+      in response to an enquiry is always one more than the number of
+      cards in the FitsChan.
+   }
+   \sstattributetype{
+      Integer.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         FitsChan
+      }{
+         All FitsChans have this attribute.
+      }
+   }
+}
+\sstroutine{
+   CardComm
+}{
+   The comment for the current card in a FitsChan
+}{
+   \sstdescription{
+      This attribute gives the comment for the current card of the
+      \htmlref{FitsChan}{FitsChan}. A zero-length string is returned if the card has no comment.
+   }
+   \sstattributetype{
+      String, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         FitsChan
+      }{
+         All FitsChans have this attribute.
+      }
+   }
+}
+\sstroutine{
+   CardName
+}{
+   The keyword name of the current card in a FitsChan
+}{
+   \sstdescription{
+      This attribute gives the name of the keyword for the
+      current card of the \htmlref{FitsChan}{FitsChan}.
+   }
+   \sstattributetype{
+      String, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         FitsChan
+      }{
+         All FitsChans have this attribute.
+      }
+   }
+}
+\sstroutine{
+   CardType
+}{
+   The data type of the current card in a FitsChan
+}{
+   \sstdescription{
+      This attribute gives the data type of the keyword value for the
+      current card of the \htmlref{FitsChan}{FitsChan}. It will be one of the following
+      integer constants: AST\_\_NOTYPE, AST\_\_COMMENT, AST\_\_INT, AST\_\_FLOAT,
+      AST\_\_STRING, AST\_\_COMPLEXF, AST\_\_COMPLEXI, AST\_\_LOGICAL,
+      AST\_\_CONTINUE, AST\_\_UNDEF.
+   }
+   \sstattributetype{
+      Integer, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         FitsChan
+      }{
+         All FitsChans have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Class
+}{
+   Object class name
+}{
+   \sstdescription{
+      This attribute gives the name of the class to which an \htmlref{Object}{Object}
+      belongs.
+   }
+   \sstattributetype{
+      Character string, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         All Objects have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Clean
+}{
+   Remove cards used whilst reading even if an error occurs?
+}{
+   \sstdescription{
+      This attribute indicates whether or not cards should be removed from
+      the \htmlref{FitsChan}{FitsChan} if an error occurs within
+      \htmlref{astRead}{astRead}.
+      A succesful read on a FitsChan always results in the removal of
+      the cards which were involved in the description of the returned
+      \htmlref{Object}{Object}. However, in the event of an error during the read (for instance
+      if the cards in the FitsChan have illegal values, or if some required
+      cards are missing) no cards will be removed from the FitsChan if
+      the Clean attribute is zero (the default). If Clean is non-zero then
+      any cards which were used in the aborted attempt to read an object
+      will be removed.
+
+      This provides a means of \texttt{"} cleaning\texttt{"}  a FitsChan of WCS related cards
+      which works even in the event of the cards not forming a legal WCS
+      description.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         FitsChan
+      }{
+         All FitsChans have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Clip
+}{
+   Clip lines and/or markers at the Plot boundary?
+}{
+   \sstdescription{
+      This attribute controls whether curves and markers are clipped at the
+      boundary of the graphics box specified when the \htmlref{Plot}{Plot} was created. A
+      value of 3 implies both markers and curves are clipped at the Plot
+      boundary. A value of 2 implies markers are clipped, but not curves. A
+      value of 1 implies curves are clipped, but not markers. A value of
+      zero implies neither curves nor markers are clipped. The default
+      value is 1. Note, this attributes controls only the clipping
+      performed internally within AST. The underlying graphics system may
+      also apply clipping. In such cases, removing clipping using this
+      attribute does not guarantee that no clipping will be visible in the
+      final plot.
+
+      The \htmlref{astClip}{astClip} function
+      can be used to establish generalised clipping within arbitrary
+      regions of the Plot.
+   }
+   \sstattributetype{
+      Integer.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+}
+\sstroutine{
+   ClipOp
+}{
+   Combine Plot clipping limits using a boolean OR?
+}{
+   \sstdescription{
+      This attribute controls how the clipping limits specified for
+      each axis of a \htmlref{Plot}{Plot} (using the \htmlref{astClip}{astClip} function) are
+      combined. This, in turn, determines which parts of the graphical
+      output will be visible.
+
+      If the ClipOp attribute of a Plot is zero (the default),
+      graphical output is visible only if it satisfies the clipping
+      limits on all the axes of the clipping \htmlref{Frame}{Frame} (a boolean
+      AND). Otherwise, if ClipOp is non-zero, output is visible if it
+      satisfies the clipping limits on one or more axes (a boolean
+      OR).
+
+      An important use of this attribute is to allow areas of a Plot
+      to be left clear (e.g. as a background for some text). To
+      achieve this, the lower and upper clipping bounds supplied to
+      astClip should be reversed, and the ClipOp attribute of the
+      Plot should be set to a non-zero value.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Closed
+}{
+   Should the boundary be considered to be inside the region?
+}{
+   \sstdescription{
+      This attribute controls whether points on the boundary of a \htmlref{Region}{Region}
+      are considered to be inside or outside the region. If the attribute
+      value is non-zero (the default), points on the boundary are considered
+      to be inside the region (that is, the Region is \texttt{"} closed\texttt{"} ). However,
+      if the attribute value is zero, points on the bounary are considered
+      to be outside the region.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Region
+      }{
+         All Regions have this attribute.
+      }
+      \sstsubsection{
+         \htmlref{PointList}{PointList}
+      }{
+         The value of the Closed attribute is ignored by PointList regions.
+         If the PointList region has not been negated, then it is always
+         assumed to be closed. If the PointList region has been negated, then
+         it is always assumed to be open. This is required since points
+         have zero volume and therefore consist entirely of boundary.
+      }
+      \sstsubsection{
+         \htmlref{CmpRegion}{CmpRegion}
+      }{
+         The default Closed value for a CmpRegion is the Closed value of its
+         first component Region.
+      }
+      \sstsubsection{
+         \htmlref{Stc}{Stc}
+      }{
+         The default Closed value for an Stc is the Closed value of its
+         encapsulated Region.
+      }
+   }
+}
+\sstroutine{
+   Colour(element)
+}{
+   Colour index for a Plot element
+}{
+   \sstdescription{
+      This attribute determines the colour index used when drawing
+      each element of graphical output produced by a \htmlref{Plot}{Plot}. It takes a
+      separate value for each graphical element so that, for instance,
+      the setting \texttt{"} Colour(title)=2\texttt{"}  causes the Plot title to be drawn
+      using colour index 2. The synonym \texttt{"} Color\texttt{"}  may also be used.
+
+      The range of integer colour indices available and their
+      appearance is determined by the underlying graphics system. The
+      default behaviour is for all graphical elements to be drawn
+      using the default colour index supplied by this graphics system
+      (normally, this is likely to result in white plotting on a black
+      background, or vice versa).
+   }
+   \sstattributetype{
+      Integer.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          For a list of the graphical elements available, see the
+         description of the Plot class.
+
+         \sstitem
+          If no graphical element is specified, (e.g. \texttt{"} Colour\texttt{"}  instead
+         of \texttt{"} Colour(title)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will
+         affect the attribute value of all graphical elements, while a
+         \texttt{"} get\texttt{"}  or \texttt{"} test\texttt{"}  operation will use just the Colour(TextLab)
+         value.
+      }
+   }
+}
+\sstroutine{
+   ColumnLenC(column)
+}{
+   The largest string length of any value in a column
+}{
+   \sstdescription{
+      This attribute holds the minimum length which a character variable
+      must have in order to be able to store the longest value currently
+      present (at any row) in a specified column of the supplied \htmlref{Table}{Table}.
+      This does not include room for a trailing null character.
+      The required column name should be placed inside the parentheses in
+      the attribute name. If the named column holds vector values, then
+      the attribute value is the length of the longest element of the
+      vector value.
+   }
+   \sstattributetype{
+      Integer, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Table
+      }{
+         All Tables have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If the named column holds numerical values, the length returned
+         is the length of the largest string that would be generated if the
+         column values were accessed as strings.
+      }
+   }
+}
+\sstroutine{
+   ColumnLength(column)
+}{
+   The number of elements in each value in a column
+}{
+   \sstdescription{
+      This attribute holds the number of elements in each value stored
+      in a named column. Each value can be a scalar (in which case the
+      ColumnLength attribute has a value of 1), or a multi-dimensional
+      array ( in which case the ColumnLength value is equal to the
+      product of the array dimensions).
+   }
+   \sstattributetype{
+      Integer, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{Table}{Table}
+      }{
+         All Tables have this attribute.
+      }
+   }
+}
+\sstroutine{
+   ColumnNdim(column)
+}{
+   The number of axes spanned by each value in a column
+}{
+   \sstdescription{
+      This attribute holds the number of axes spanned by each value in a
+      column. If each cell in the column is a scalar, ColumnNdim will be
+      zero. If each cell in the column is a 1D spectrum, ColumnNdim will
+      be one. If each cell in the column is a 2D image, ColumnNdim will be
+      two, etc. The required column name should be placed inside the
+      parentheses in the attribute name.
+   }
+   \sstattributetype{
+      Integer, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{Table}{Table}
+      }{
+         All Tables have this attribute.
+      }
+   }
+}
+\sstroutine{
+   ColumnType(column)
+}{
+   The data type of each value in a column
+}{
+   \sstdescription{
+      This attribute holds a integer value indicating the data type of
+      a named column in a \htmlref{Table}{Table}. This is the data type which was used
+      when the column was added to the Table using \htmlref{astAddColumn}{astAddColumn}. The
+      required column name should be placed inside the parentheses in
+      the attribute name.
+
+      The attribute value will be one of AST\_\_INTTYPE (for integer),
+      AST\_\_SINTTYPE (for
+      short int),
+      AST\_\_BYTETYPE (for
+      unsigned bytes - i.e. unsigned chars),
+      AST\_\_DOUBLETYPE (for double
+      precision floating point), AST\_\_FLOATTYPE (for single
+      precision floating point), AST\_\_STRINGTYPE (for character string),
+      AST\_\_OBJECTTYPE (for AST \htmlref{Object}{Object} pointer), AST\_\_POINTERTYPE (for
+      arbitrary C pointer) or AST\_\_UNDEFTYPE (for undefined values
+      created by
+      \htmlref{astMapPutU}{astMapPutU}).
+   }
+   \sstattributetype{
+      Integer, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Table
+      }{
+         All Tables have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Comment
+}{
+   Include textual comments in output?
+}{
+   \sstdescription{
+      This is a boolean attribute which controls whether textual
+      comments are to be included in the output generated by a
+      \htmlref{Channel}{Channel}. If included, they will describe what each item of
+      output represents.
+
+      If Comment is non-zero, then comments will be included. If
+      it is zero, comments will be omitted.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Channel
+      }{
+         The default value is non-zero for a normal Channel.
+      }
+      \sstsubsection{
+         \htmlref{FitsChan}{FitsChan}
+      }{
+         The default value is non-zero for a FitsChan.
+      }
+      \sstsubsection{
+         \htmlref{XmlChan}{XmlChan}
+      }{
+         The default value is zero for an XmlChan.
+      }
+   }
+}
+\sstroutine{
+   Current
+}{
+   FrameSet current Frame index
+}{
+   \sstdescription{
+      This attribute gives the index of the \htmlref{Frame}{Frame} which is to be
+      regarded as the \texttt{"} current\texttt{"}  Frame within a \htmlref{FrameSet}{FrameSet}. The default
+      is the most recent Frame added to the FrameSet (this Frame
+      always has an index equal to the FrameSet\texttt{'} s \htmlref{Nframe}{Nframe} attribute).
+
+      When setting a new value for this attribute, a string may be
+      supplied instead of an integer index. In this case a search
+      is made within the FrameSet for a Frame that has its \htmlref{Domain}{Domain}
+      attribute value equal to the supplied string (the comparison is
+      case-insensitive). If found, the Frame is made the current Frame.
+      Otherwise an error is reported.
+   }
+   \sstattributetype{
+      Integer.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         FrameSet
+      }{
+         All FrameSets have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Inverting a FrameSet (inverting the boolean sense of its
+         \htmlref{Invert}{Invert} attribute, with the \htmlref{astInvert}{astInvert} function for example) will
+         interchange the values of its \htmlref{Base}{Base} and Current attributes.
+      }
+   }
+}
+\sstroutine{
+   DSBCentre
+}{
+   The central position of interest in a dual sideband spectrum
+}{
+   \sstdescription{
+      This attribute specifies the central position of interest in a dual
+      sideband spectrum. Its sole use is to determine the local oscillator
+      frequency (the frequency which marks the boundary between the lower
+      and upper sidebands). See the description of the \htmlref{IF}{IF} (intermediate
+      frequency) attribute for details of how the local oscillator frequency
+      is calculated. The sideband containing this central position is
+      referred to as the \texttt{"} observed\texttt{"}  sideband, and the other sideband as
+      the \texttt{"} image\texttt{"}  sideband.
+
+      The value is accessed as a position in the spectral system
+      represented by the \htmlref{SpecFrame}{SpecFrame} attributes inherited by this class, but
+      is stored internally as topocentric frequency. Thus, if the \htmlref{System}{System}
+      attribute of the \htmlref{DSBSpecFrame}{DSBSpecFrame} is set to \texttt{"} VRAD\texttt{"} , the Unit attribute
+      set to \texttt{"} m/s\texttt{"}  and the \htmlref{StdOfRest}{StdOfRest} attribute set to \texttt{"} LSRK\texttt{"} , then values
+      for the DSBCentre attribute should be supplied as radio velocity in
+      units of \texttt{"} m/s\texttt{"}  relative to the kinematic LSR (alternative units may
+      be used by appending a suitable units string to the end of the value).
+      This value is then converted to topocentric frequency and stored. If
+      (say) the Unit attribute is subsequently changed to \texttt{"} km/s\texttt{"}  before
+      retrieving the current value of the DSBCentre attribute, the stored
+      topocentric frequency will be converted back to LSRK radio velocity,
+      this time in units of \texttt{"} km/s\texttt{"} , before being returned.
+
+      The default value for this attribute is 30 GHz.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         DSBSpecFrame
+      }{
+         All DSBSpecFrames have this attribute.
+      }
+   }
+   \sstdiytopic{
+      Note
+   }{
+      \sstitemlist{
+
+         \sstitem
+          The attributes which define the transformation to or from topocentric
+         frequency should be assigned their correct values before accessing
+         this attribute. These potentially include System, Unit, StdOfRest,
+         \htmlref{ObsLon}{ObsLon}, \htmlref{ObsLat}{ObsLat}, \htmlref{ObsAlt}{ObsAlt}, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA}, \htmlref{RefDec}{RefDec} and \htmlref{RestFreq}{RestFreq}.
+      }
+   }
+}
+\sstroutine{
+   DefB1950
+}{
+   Use FK4 B1950 as defaults?
+}{
+   \sstdescription{
+      This attribute is a boolean value which specifies a default equinox
+      and reference frame to use when reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan}
+      with a foreign (i.e. non-native) encoding. It is only used if the FITS
+      header contains RA and DEC axes but contains no information about the
+      reference frame or equinox. If this is the case, then values of FK4 and
+      B1950 are assumed if the DefB1950 attribute has a non-zero value and
+      ICRS is assumed if DefB1950 is zero. The default value for DefB1950
+      depends on the value of the \htmlref{Encoding}{Encoding} attribute: for FITS-WCS encoding
+      the default is zero, and for all other encodings it is one.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         FitsChan
+      }{
+         All FitsChans have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Digits/Digits(axis)
+}{
+   Number of digits of precision
+}{
+   \sstdescription{
+      This attribute specifies how many digits of precision are
+      required by default when a coordinate value is formatted for a
+      \htmlref{Frame}{Frame} axis (e.g. using \htmlref{astFormat}{astFormat}). Its value may be set either
+      for a Frame as a whole, or (by subscripting the attribute name
+      with the number of an axis) for each axis individually. Any
+      value set for an individual axis will over-ride the value for
+      the Frame as a whole.
+
+      Note that the Digits value acts only as a means of determining a
+      default Format string. Its effects are over-ridden if a Format
+      string is set explicitly for an axis. However, if the Format
+      attribute specifies the precision using the string \texttt{"} .$*$\texttt{"} , then
+      the Digits attribute is used to determine the number of decimal
+      places to produce.
+   }
+   \sstattributetype{
+      Integer.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Frame
+      }{
+         The default Digits value supplied by the Frame class is 7. If
+         a value less than 1 is supplied, then 1 is used instead.
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         The Digits attribute of a FrameSet (or one of its axes) is
+         the same as that of its current Frame (as specified by the
+         \htmlref{Current}{Current} attribute).
+      }
+      \sstsubsection{
+         \htmlref{Plot}{Plot}
+      }{
+         The default Digits value used by the Plot class when drawing
+         annotated axis labels is the smallest value which results in all
+         adjacent labels being distinct.
+      }
+      \sstsubsection{
+         \htmlref{TimeFrame}{TimeFrame}
+      }{
+         The Digits attribute is ignored when a TimeFrame formats a value
+         as a date and time string (see the Format attribute).
+      }
+   }
+}
+\sstroutine{
+   Direction(axis)
+}{
+   Display axis in conventional direction?
+}{
+   \sstdescription{
+      This attribute is a boolean value which suggests how the axes of
+      a \htmlref{Frame}{Frame} should be displayed (e.g.) in graphical output. By
+      default, it has the value one, indicating that they should be
+      shown in the conventional sense (increasing left to right for an
+      abscissa, and bottom to top for an ordinate). If set to zero,
+      this attribute indicates that the direction should be reversed,
+      as would often be done for an astronomical magnitude or a right
+      ascension axis.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Frame
+      }{
+         The default Direction value supplied by the Frame class is 1,
+         indicating that all axes should be displayed in the
+         conventional direction.
+      }
+      \sstsubsection{
+         \htmlref{SkyFrame}{SkyFrame}
+      }{
+         The SkyFrame class re-defines the default Direction value to
+         suggest that certain axes (e.g. right ascension) should be
+         plotted in reverse when appropriate.
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         The Direction attribute of a FrameSet axis is the same as
+         that of its current Frame (as specified by the \htmlref{Current}{Current}
+         attribute).
+      }
+      \sstsubsection{
+         \htmlref{Plot}{Plot}
+      }{
+         The Direction attribute of the base Frame in a Plot is set to
+         indicate the sense of the two graphics axes, as implied by the
+         graphics bounding box supplied when the Plot was created.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          When specifying this attribute by name, it should be
+         subscripted with the number of the Frame axis to which it
+         applies.
+
+         \sstitem
+          The Direction attribute does not directly affect the behaviour
+         of the AST library. Instead, it serves as a hint to applications
+         programs about the orientation in which they may wish to display
+         any data associated with the Frame. Applications are free to
+         ignore this hint if they wish.
+      }
+   }
+}
+\sstroutine{
+   Disco
+}{
+   PcdMap pincushion/barrel distortion coefficient
+}{
+   \sstdescription{
+      This attribute specifies the pincushion/barrel distortion coefficient
+      used by a \htmlref{PcdMap}{PcdMap}. This coefficient is set when the PcdMap is created,
+      but may later be modified. If the attribute is cleared, its default
+      value is zero, which gives no distortion. For pincushion distortion,
+      the value should be positive. For barrel distortion, it should be
+      negative.
+
+      Note that the forward transformation of a PcdMap applies the
+      distortion specified by this attribute and the inverse
+      transformation removes this distortion. If the PcdMap is inverted
+      (e.g. using \htmlref{astInvert}{astInvert}), then the forward transformation will
+      remove the distortion and the inverse transformation will apply
+      it. The distortion itself will still be given by the same value of
+      Disco.
+
+      Note, the value of this attribute may changed only if the PcdMap
+      has no more than one reference. That is, an error is reported if the
+      PcdMap has been cloned, either by including it within another object
+      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
+      \htmlref{astClone}{astClone}
+      function.
+   }
+   \sstattributetype{
+      Double precision.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         PcdMap
+      }{
+         All PcdMaps have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Domain
+}{
+   Coordinate system domain
+}{
+   \sstdescription{
+      This attribute contains a string which identifies the physical
+      domain of the coordinate system that a \htmlref{Frame}{Frame} describes.
+
+      The Domain attribute also controls how a Frame behaves when it is
+      used (by \htmlref{astFindFrame}{astFindFrame}) as a template to match another (target)
+      Frame. It does this by specifying the Domain that the target
+      Frame should have in order to match the template. If the Domain
+      value in the template Frame is set, then only targets with the
+      same Domain value will be matched. If the template\texttt{'} s Domain
+      value is not set, however, then the target\texttt{'} s Domain will be
+      ignored.
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Frame
+      }{
+         The default Domain value supplied by the Frame class is an
+         empty string.
+      }
+      \sstsubsection{
+         \htmlref{SkyFrame}{SkyFrame}
+      }{
+         The SkyFrame class re-defines the default Domain value to be
+         \texttt{"} SKY\texttt{"} .
+      }
+      \sstsubsection{
+         \htmlref{CmpFrame}{CmpFrame}
+      }{
+         The CmpFrame class re-defines the default Domain value to be
+         of the form \texttt{"} $<$dom1$>$-$<$dom2$>$\texttt{"} , where $<$dom1$>$ and $<$dom2$>$ are the
+         Domains of the two component Frames. If both these Domains are
+         blank, then the string \texttt{"} CMP\texttt{"}  is used as the default Domain name.
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         The Domain attribute of a FrameSet is the same as that of its
+         current Frame (as specified by the \htmlref{Current}{Current} attribute).
+      }
+      \sstsubsection{
+         \htmlref{SpecFrame}{SpecFrame}
+      }{
+         The SpecFrame class re-defines the default Domain value to be
+         \texttt{"} SPECTRUM\texttt{"} .
+      }
+      \sstsubsection{
+         \htmlref{DSBSpecFrame}{DSBSpecFrame}
+      }{
+         The DSBSpecFrame class re-defines the default Domain value to be
+         \texttt{"} DSBSPECTRUM\texttt{"} .
+      }
+      \sstsubsection{
+         \htmlref{FluxFrame}{FluxFrame}
+      }{
+         The FluxFrame class re-defines the default Domain value to be
+         \texttt{"} FLUX\texttt{"} .
+      }
+      \sstsubsection{
+         \htmlref{SpecFluxFrame}{SpecFluxFrame}
+      }{
+         The FluxFrame class re-defines the default Domain value to be
+         \texttt{"} SPECTRUM-FLUX\texttt{"} .
+      }
+      \sstsubsection{
+         \htmlref{TimeFrame}{TimeFrame}
+      }{
+         The TimeFrame class re-defines the default Domain value to be
+         \texttt{"} TIME\texttt{"} .
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          All Domain values are converted to upper case and white space
+         is removed before use.
+      }
+   }
+}
+\sstroutine{
+   DrawAxes(axis)
+}{
+   Draw axes for a Plot?
+}{
+   \sstdescription{
+      This attribute controls the appearance of an annotated
+      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
+      whether curves representing coordinate axes should be drawn.
+      It takes a separate value for each physical axis of a
+      \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} DrawAxes(2)=0\texttt{"}
+      specifies that no axis should be drawn for the second axis.
+
+      If drawn, these axis lines will pass through any tick marks
+      associated with numerical labels drawn to mark values on the
+      axes. The location of these tick marks and labels (and hence the
+      axis lines) is determined by the Plot\texttt{'} s \htmlref{LabelAt(axis)}{LabelAt(axis)} attribute.
+
+      If the DrawAxes value of a Plot is non-zero (the default), then
+      axis lines will be drawn, otherwise they will be omitted.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{Axis}{Axis} lines are drawn independently of any coordinate grid
+         lines (see the \htmlref{Grid}{Grid} attribute) so grid lines may be used to
+         substitute for axis lines if required.
+
+         \sstitem
+          In some circumstances, numerical labels and tick marks are
+         drawn around the edges of the plotting area (see the \htmlref{Labelling}{Labelling}
+         attribute).  In this case, the value of the DrawAxes attribute
+         is ignored.
+
+         \sstitem
+          If no axis is specified, (e.g. \texttt{"} DrawAxes\texttt{"}  instead of
+         \texttt{"} DrawAxes(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect
+         the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or
+         \texttt{"} test\texttt{"}  operation will use just the DrawAxes(1) value.
+      }
+   }
+}
+\sstroutine{
+   DrawTitle
+}{
+   Draw a title for a Plot?
+}{
+   \sstdescription{
+      This attribute controls the appearance of an annotated
+      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
+      whether a title is drawn.
+
+      If the DrawTitle value of a \htmlref{Plot}{Plot} is non-zero (the default), then
+      the title will be drawn, otherwise it will be omitted.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+      \sstsubsection{
+         \htmlref{Plot3D}{Plot3D}
+      }{
+         The Plot3D class ignores this attributes, assuming a value of
+         zero.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The text used for the title is obtained from the Plot\texttt{'} s \htmlref{Title}{Title}
+         attribute.
+
+         \sstitem
+          The vertical placement of the title can be controlled using
+         the \htmlref{TitleGap}{TitleGap} attribute.
+      }
+   }
+}
+\sstroutine{
+   Dtai
+}{
+   The TAI-UTC correction
+}{
+   \sstdescription{
+      This attribute specifies the difference between TAI and UTC (i.e.
+      the number of leap seconds) at the moment corresponding to the
+      \htmlref{Frame}{Frame}\texttt{'} s \htmlref{Epoch}{Epoch} value. The default value of AST\_\_BAD causes the
+      number of leap seconds to be determined from an internal look-up
+      table, which is kept up-to-date manually by the AST development team.
+      Therefore it is only necessary to assign a value to this attribute
+      if the version of AST in use is so old that it does not include all
+      leap seconds that occurred prior to the time represented by the
+      Frame\texttt{'} s Epoch value.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Frame
+      }{
+         All Frames have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Dut1
+}{
+   The UT1-UTC correction
+}{
+   \sstdescription{
+      This attribute is used when calculating the Local Apparent Sidereal
+      Time corresponding to \htmlref{SkyFrame}{SkyFrame}\texttt{'} s \htmlref{Epoch}{Epoch} value (used when converting
+      positions to or from the \texttt{"} AzEl\texttt{"}  system). It should be set to the
+      difference, in seconds, between the UT1 and UTC timescales at the
+      moment in time represented by the SkyFrame\texttt{'} s Epoch attribute. The
+      value to use is unpredictable and depends on changes in the earth\texttt{'} s
+      rotation speed. Values for UT1-UTC can be obtained from the
+      International Earth Rotation and Reference Systems Service
+      (IERS) at http://www.iers.org/.
+
+      Currently, the correction is always less than 1 second. This is
+      ensured by the occasional introduction of leap seconds into the UTC
+      timescale. Therefore no great error will usually result if no value
+      is assigned to this attribute (in which case a default value of
+      zero is used). However, it is possible that a decision may be taken
+      at some time in the future to abandon the introduction of leap
+      seconds, in which case the DUT correction could grow to significant
+      sizes.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{Frame}{Frame}
+      }{
+         All Frames have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Edge(axis)
+}{
+   Which edges to label in a Plot
+}{
+   \sstdescription{
+      This attribute controls the appearance of an annotated
+      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
+      which edges of a \htmlref{Plot}{Plot} are used for displaying numerical and
+      descriptive axis labels. It takes a separate value for each
+      physical axis of the Plot so that, for instance, the setting
+      \texttt{"} Edge(2)=left\texttt{"}  specifies which edge to use to display labels for
+      the second axis.
+
+      The values \texttt{"} left\texttt{"} , \texttt{"} top\texttt{"} , \texttt{"} right\texttt{"}  and \texttt{"} bottom\texttt{"}  (or any
+      abbreviation) can be supplied for this attribute. The default is
+      usually \texttt{"} bottom\texttt{"}  for the first axis and \texttt{"} left\texttt{"}  for the second
+      axis. However, if exterior labelling was requested (see the
+      \htmlref{Labelling}{Labelling} attribute) but cannot be produced using these default
+      Edge values, then the default values will be swapped if this
+      enables exterior labelling to be produced.
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+      \sstsubsection{
+         \htmlref{Plot3D}{Plot3D}
+      }{
+         The Plot3D class ignores this attributes. Instead it uses its
+         own \htmlref{RootCorner}{RootCorner} attribute to determine which edges of the 3D plot
+         to label.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          In some circumstances, numerical labels will be drawn along
+         internal grid lines instead of at the edges of the plotting area
+         (see the Labelling attribute). In this case, the Edge attribute
+         only affects the placement of the descriptive labels (these are
+         drawn at the edges of the plotting area, rather than along the
+         axis lines).
+      }
+   }
+}
+\sstroutine{
+   Encoding
+}{
+   System for encoding Objects as FITS headers
+}{
+   \sstdescription{
+      This attribute specifies the encoding system to use when AST
+      Objects are stored as FITS header cards in a \htmlref{FitsChan}{FitsChan}. It
+      affects the behaviour of the \htmlref{astWrite}{astWrite} and \htmlref{astRead}{astRead} functions when
+      they are used to transfer any AST \htmlref{Object}{Object} to or from an external
+      representation consisting of FITS header cards (i.e. whenever a
+      write or read operation is performed using a FitsChan as the I/O
+      \htmlref{Channel}{Channel}).
+
+      There are several ways (conventions) by which coordinate system
+      information may be represented in the form of FITS headers and
+      the Encoding attribute is used to specify which of these should
+      be used. The encoding options available are outlined in the
+      \texttt{"} Encodings Available\texttt{"}  section below, and in more detail in the
+      sections which follow.
+
+      Encoding systems differ in the range of possible Objects
+      (e.g. classes) they can represent, in the restrictions they
+      place on these Objects (e.g. compatibility with some
+      externally-defined coordinate system model) and in the number of
+      Objects that can be stored together in any particular set of
+      FITS header cards (e.g. multiple Objects, or only a single
+      Object). The choice of encoding also affects the range of
+      external applications which can potentially read and interpret
+      the FITS header cards produced.
+
+      The encoding options available are not necessarily mutually
+      exclusive, and it may sometimes be possible to store multiple
+      Objects (or the same Object several times) using different
+      encodings within the same set of FITS header cards. This
+      possibility increases the likelihood of other applications being
+      able to read and interpret the information.
+
+      By default, a FitsChan will attempt to determine which encoding
+      system is already in use, and will set the default Encoding
+      value accordingly (so that subsequent I/O operations adopt the
+      same conventions). It does this by looking for certain critical
+      FITS keywords which only occur in particular encodings. For
+      details of how this works, see the \texttt{"} Choice of Default Encoding\texttt{"}
+      section below. If you wish to ensure that a particular encoding
+      system is used, independently of any FITS cards already present,
+      you should set an explicit Encoding value yourself.
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         FitsChan
+      }{
+         All FitsChans have this attribute.
+      }
+   }
+   \sstdiytopic{
+      Encodings Available
+   }{
+      The Encoding attribute can take any of the following (case
+      insensitive) string values to select the corresponding encoding
+
+      system:
+
+      \sstitemlist{
+
+         \sstitem
+          \texttt{"} DSS\texttt{"} : Encodes coordinate system information in FITS header
+         cards using the convention developed at the Space Telescope
+         Science Institute (STScI) for the Digitised Sky Survey (DSS)
+         astrometric plate calibrations. The main advantages of this
+         encoding are that FITS images which use it are widely available
+         and it is understood by a number of important and
+         well-established astronomy applications. For further details,
+         see the section \texttt{"} The DSS Encoding\texttt{"}  below.
+
+         \sstitem
+          \texttt{"} FITS-WCS\texttt{"} : Encodes coordinate system information in FITS
+         header cards using the conventions described in the FITS
+         world coordinate system (FITS-WCS) papers by E.W. Greisen,
+         M. Calabretta, et al. The main advantages of this encoding are that
+         it should be understood by any FITS-WCS compliant application and
+         is likely to be adopted widely for FITS data in future. For further
+         details, see the section \texttt{"} The FITS-WCS Encoding\texttt{"}  below.
+
+         \sstitem
+          \texttt{"} FITS-PC\texttt{"} : Encodes coordinate system information in FITS
+         header cards using the conventions described in an earlier draft
+         of the FITS world coordinate system papers by E.W. Greisen and
+         M. Calabretta. This encoding uses a combination of CDELTi and
+         PCiiijjj keywords to describe the scale and rotation of the pixel
+         axes. This encoding is included to support existing data and
+         software which uses these now superceded conventions. In general,
+         the \texttt{"} FITS-WCS\texttt{"}  encoding (which uses CDi\_j or PCi\_j keywords to
+         describe the scale and rotation) should be used in preference to
+         \texttt{"} FITS-PC\texttt{"} .
+
+         \sstitem
+          \texttt{"} FITS-IRAF\texttt{"} : Encodes coordinate system information in FITS
+         header cards using the conventions described in the document
+         \texttt{"} World Coordinate Systems Representations Within the FITS
+         Format\texttt{"}  by R.J. Hanisch and D.G. Wells, 1988.  This encoding is
+         currently employed by the IRAF data analysis facility, so its
+         use will facilitate data exchange with IRAF. Its main advantages
+         are that it is a stable convention which approximates to a
+         subset of the propsed FITS-WCS encoding (above). This makes it
+         suitable as an interim method for storing coordinate system
+         information in FITS headers until the FITS-WCS encoding becomes
+         stable. Since many datasets currently use the FITS-IRAF
+         encoding, conversion of data from FITS-IRAF to the final form of
+         FITS-WCS is likely to be well supported.
+
+         \sstitem
+          \texttt{"} FITS-AIPS\texttt{"} : Encodes coordinate system information in FITS
+         header cards using the conventions originally introduced by the
+         AIPS data analysis facility. This is base on the use of CDELTi and
+         CROTAi keuwords to desribe the scale and rotation of each axis.
+         These conventions have been superceded but are still widely used.
+
+         \sstitem
+          \texttt{"} FITS-AIPS$+$$+$\texttt{"} : Encodes coordinate system information in FITS
+         header cards using the conventions used by the AIPS$+$$+$ project.
+         This is an extension of FITS-AIPS which includes some of the
+         features of FITS-IRAF and FITS-PC.
+
+         \sstitem
+          \texttt{"} FITS-CLASS\texttt{"} : Encodes coordinate system information in FITS
+         header cards using the conventions used by the CLASS project.
+         CLASS is a software package for reducing single-dish radio and
+         sub-mm spectroscopic data. See the section \texttt{"} CLASS FITS format\texttt{"}  at
+         http://www.iram.fr/IRAMFR/GILDAS/doc/html/class-html/.
+
+         \sstitem
+          \texttt{"} NATIVE\texttt{"} : Encodes AST Objects in FITS header cards using a
+         convention which is private to the AST library (but adheres to
+         the general FITS standard) and which uses FITS keywords that
+         will not clash with other encoding systems. The main advantages
+         of this are that any class of AST Object may be encoded, and any
+         (reasonable) number of Objects may be stored sequentially in the
+         same FITS header. This makes FITS headers an almost loss-less
+         communication path for passing AST Objects between applications
+         (although all such applications must, of course, make use of the
+         AST library to interpret the information). For further details,
+         see the section \texttt{"} The NATIVE Encoding\texttt{"}  below.
+      }
+   }
+   \sstdiytopic{
+      Choice of Default Encoding
+   }{
+      If the Encoding attribute of a FitsChan is not set, the default
+      value it takes is determined by the presence of certain critical
+      FITS keywords within the FitsChan. The sequence of decisions
+
+      used to arrive at the default value is as follows:
+
+      \sstitemlist{
+
+         \sstitem
+          If the FitsChan contains any keywords beginning with the
+         string \texttt{"} BEGAST\texttt{"} , then NATIVE encoding is used,
+
+         \sstitem
+          Otherwise, FITS-CLASS is used if the FitsChan contains a DELTAV
+         keyword and a keyword of the form VELO-xxx, where xxx indicates one
+         of the rest frames used by class (e.g. \texttt{"} VELO-LSR\texttt{"} ), or \texttt{"} VLSR\texttt{"} .
+
+         \sstitem
+          Otherwise, if the FitsChan contains a CTYPE keyword which
+         represents a spectral axis using the conventions of the AIPS and
+         AIPS$+$$+$ projects (e.g. \texttt{"} FELO-LSR\texttt{"} , etc), then one of FITS-AIPS or
+         FITS-AIPS$+$$+$ encoding is used. FITS-AIPS$+$$+$ is used if any of the
+         keywords CDi\_j, PROJP, LONPOLE or LATPOLE are
+         found in the FitsChan. Otherwise FITS-AIPS is used.
+
+         \sstitem
+          Otherwise, if the FitsChan contains a keyword of the form
+         \texttt{"} PCiiijjj\texttt{"} , where \texttt{"} i\texttt{"}  and \texttt{"} j\texttt{"}  are single digits, then
+         FITS-PC encoding is used,
+
+         \sstitem
+          Otherwise, if the FitsChan contains a keyword of the form
+         \texttt{"} CDiiijjj\texttt{"} , where \texttt{"} i\texttt{"}  and \texttt{"} j\texttt{"}  are single digits, then
+         FITS-IRAF encoding is used,
+
+         \sstitem
+          Otherwise, if the FitsChan contains a keyword of the form
+         \texttt{"} CDi\_j\texttt{"} , and at least one of RADECSYS, PROJPi, or CjVALi
+         where \texttt{"} i\texttt{"}  and \texttt{"} j\texttt{"}  are single digits, then FITS-IRAF encoding is
+         used.
+
+         \sstitem
+          Otherwise, if the FitsChan contains any keywords of the form
+         PROJPi, CjVALi or RADECSYS, where \texttt{"} i\texttt{"}  and \texttt{"} j\texttt{"}  are single digits,
+         then FITS-PC encoding is used.
+
+         \sstitem
+          Otherwise, if the FitsChan contains a keyword of the form
+         CROTAi, where \texttt{"} i\texttt{"}  is a single digit, then FITS-AIPS encoding is
+         used.
+
+         \sstitem
+          Otherwise, if the FitsChan contains a keyword of the form
+         CRVALi, where \texttt{"} i\texttt{"}  is a single digit, then FITS-WCS encoding is
+         used.
+
+         \sstitem
+          Otherwise, if the FitsChan contains the \texttt{"} PLTRAH\texttt{"}  keyword, then
+         DSS encoding is used,
+
+         \sstitem
+          Otherwise, if none of these conditions is met (as would be the
+         case when using an empty FitsChan), then NATIVE encoding is
+         used.
+
+      }
+      Except for the NATIVE and DSS encodings, all the above checks
+      also require that the header contains at least one CTYPE, CRPIX and
+      CRVAL keyword (otherwise the checking process continues to the next
+      case).
+
+      Setting an explicit value for the Encoding attribute always
+      over-rides this default behaviour.
+
+      Note that when writing information to a FitsChan, the choice of
+      encoding will depend greatly on the type of application you
+      expect to be reading the information in future. If you do not
+      know this, there may sometimes be an advantage in writing the
+      information several times, using a different encoding on each
+      occasion.
+   }
+   \sstdiytopic{
+      The DSS Encoding
+   }{
+      The DSS encoding uses FITS header cards to store a multi-term
+      polynomial which relates pixel positions on a digitised
+      photographic plate to celestial coordinates (right ascension and
+      declination). This encoding may only be used to store a single
+      AST Object in any set of FITS header cards, and that Object must
+      be a \htmlref{FrameSet}{FrameSet} which conforms to the STScI/DSS coordinate system
+      model (this means the \htmlref{Mapping}{Mapping} which relates its base and current
+      Frames must include either a \htmlref{DssMap}{DssMap} or a \htmlref{WcsMap}{WcsMap} with type
+      AST\_\_TAN or AST\_\_TPN).
+
+      When reading a DSS encoded Object (using astRead), the FitsChan
+      concerned must initially be positioned at the first card (its
+      \htmlref{Card}{Card} attribute must equal 1) and the result of the read, if
+      successful, will always be a pointer to a FrameSet. The base
+      \htmlref{Frame}{Frame} of this FrameSet represents DSS pixel coordinates, and the
+      current Frame represents DSS celestial coordinates. Such a read
+      is always destructive and causes the FITS header cards required
+      for the construction of the FrameSet to be removed from the
+      FitsChan, which is then left positioned at the \texttt{"} end-of-file\texttt{"} . A
+      subsequent read using the same encoding will therefore not
+      return another FrameSet, even if the FitsChan is rewound.
+
+      When astWrite is used to store a FrameSet using DSS encoding,
+      an attempt is first made to simplify the FrameSet to see if it
+      conforms to the DSS model.  Specifically, the current Frame must
+      be a FK5 \htmlref{SkyFrame}{SkyFrame}; the projection must be a tangent plane
+      (gnomonic) projection with polynomial corrections conforming to
+      DSS requirements, and north must be parallel to the second base
+      Frame axis.
+
+      If the simplification process succeeds, a description of the
+      FrameSet is written to the FitsChan using appropriate DSS FITS
+      header cards. The base Frame of the FrameSet is used to form the
+      DSS pixel coordinate system and the current Frame gives the DSS
+      celestial coordinate system.  A successful write operation will
+      over-write any existing DSS encoded data in the FitsChan, but
+      will not affect other (non-DSS) header cards. If a destructive
+      read of a DSS encoded Object has previously occurred, then an
+      attempt will be made to store the FITS header cards back in
+      their original locations.
+
+      If an attempt to simplify a FrameSet to conform to the DSS model
+      fails (or if the Object supplied is not a FrameSet), then no
+      data will be written to the FitsChan and astWrite will return
+      zero. No error will result.
+   }
+   \sstdiytopic{
+      The FITS-WCS Encoding
+   }{
+      The FITS-WCS convention uses FITS header cards to describe the
+      relationship between pixels in an image (not necessarily
+      2-dimensional) and one or more related \texttt{"} world coordinate systems\texttt{"} .
+      The FITS-WCS encoding may only be used to store a single AST Object
+      in any set of FITS header cards, and that Object must be a FrameSet
+      which conforms to the FITS-WCS model (the FrameSet may, however,
+      contain multiple Frames which will be result in multiple FITS
+      \texttt{"} alternate axis descriptions\texttt{"} ). Details of the use made by this
+      Encoding of the conventions described in the FITS-WCS papers are
+      given in the appendix \texttt{"} FITS-WCS Coverage\texttt{"}  of this document. A few
+      main points are  described below.
+
+      The rotation and scaling of the intermediate world coordinate system
+      can be specified using either \texttt{"} CDi\_j\texttt{"}  keywords, or \texttt{"} PCi\_j\texttt{"}  together
+      with \texttt{"} CDELTi\texttt{"}  keywords. When writing a FrameSet to a FitsChan, the
+      the value of the \htmlref{CDMatrix}{CDMatrix} attribute of the FitsChan determines
+      which system is used.
+
+      In addition, this encoding supports the \texttt{"} TAN with polynomial correction
+      terms\texttt{"}  projection which was included in a draft of the FITS-WCS paper,
+      but was not present in the final version. A \texttt{"} TAN with polynomial
+      correction terms\texttt{"}  projection is represented using a WcsMap with type
+      AST\_\_TPN (rather than AST\_\_TAN which is used to represent simple
+      TAN projections). When reading a FITS header, a CTYPE keyword value
+      including a \texttt{"} -TAN\texttt{"}  code results in an AST\_\_TPN projection if there are
+      any projection parameters (given by the \htmlref{PVi\_m}{PVi\_m} keywords) associated with
+      the latitude axis, or if there are projection parameters associated
+      with the longitude axis for m greater than 4. When writing a
+      FrameSet to a FITS header, an AST\_\_TPN projection gives rise to a
+      CTYPE value including the normal \texttt{"} -TAN\texttt{"}  code, but the projection
+      parameters are stored in keywords with names \texttt{"} QVi\_m\texttt{"} , instead of the
+      usual \texttt{"} PVi\_m\texttt{"} . Since these QV parameters are not part of the
+      FITS-WCS standard they will be ignored by other non-AST software,
+      resulting in the WCS being interpreted as a simple TAN projection
+      without any corrections. This should be seen as an interim solution
+      until such time as an agreed method for describing projection
+      distortions within FITS-WCS has been published.
+
+      AST extends the range of celestial coordinate systems which may be
+      described using this encoding by allowing the inclusion of
+      \texttt{"} AZ--\texttt{"}  and \texttt{"} EL--\texttt{"}  as the coordinate specification within CTYPE
+      values. These form a longitude/latitude pair of axes which describe
+      azimuth and elevation. The geographic position of the observer
+      should be supplied using the OBSGEO-X/Y/Z keywords described in FITS-WCS
+      paper III. Currently, a simple model is used which includes diurnal
+      aberration, but ignores atmospheric refraction, polar motion, etc.
+      These may be added in a later release.
+
+      If an AST SkyFrame that represents offset rather than absolute
+      coordinates (see attribute \htmlref{SkyRefIs}{SkyRefIs}) is written to a FitsChan using
+      FITS-WCS encoding, two alternate axis descriptions will be created.
+      One will describe the offset coordinates, and will use \texttt{"} OFLN\texttt{"}  and
+      \texttt{"} OFLT\texttt{"}  as the axis codes in the CTYPE keywords. The other will
+      describe absolute coordinates as specified by the \htmlref{System}{System} attribute
+      of the SkyFrame, using the usual CTYPE codes (\texttt{"} RA--\texttt{"} /\texttt{"} DEC-\texttt{"} , etc).
+      In addition, the absolute coordinates description will contain
+      AST-specific keywords (SREF1/2, SREFP1/2 and SREFIS) that allow the
+      header to be read back into AST in order to reconstruct the original
+      SkyFrame.
+
+      When reading a FITS-WCS encoded Object (using astRead), the FitsChan
+      concerned must initially be positioned at the first card (its
+      Card attribute must equal 1) and the result of the read, if
+      successful, will always be a pointer to a FrameSet. The base
+      Frame of this FrameSet represents FITS-WCS pixel coordinates,
+      and the current Frame represents the physical coordinate system
+      described by the FITS-WCS primary axis descriptions. If
+      secondary axis descriptions are also present, then the FrameSet
+      may contain additional (non-current) Frames which represent
+      these.  Such a read is always destructive and causes the FITS
+      header cards required for the construction of the FrameSet to be
+      removed from the FitsChan, which is then left positioned at the
+      \texttt{"} end-of-file\texttt{"} . A subsequent read using the same encoding will
+      therefore not return another FrameSet, even if the FitsChan is
+      rewound.
+
+      When astWrite is used to store a FrameSet using FITS-WCS
+      encoding, an attempt is first made to simplify the FrameSet to
+      see if it conforms to the FITS-WCS model. If this simplification
+      process succeeds (as it often should, as the model is reasonably
+      flexible), a description of the FrameSet is written to the
+      FitsChan using appropriate FITS header cards. The base Frame of
+      the FrameSet is used to form the FITS-WCS pixel coordinate
+      system and the current Frame gives the physical coordinate
+      system to be described by the FITS-WCS primary axis
+      descriptions.  Any additional Frames in the FrameSet may be used
+      to construct secondary axis descriptions, where appropriate.
+
+      A successful write operation will over-write any existing
+      FITS-WCS encoded data in the FitsChan, but will not affect other
+      (non-FITS-WCS) header cards. If a destructive read of a FITS-WCS
+      encoded Object has previously occurred, then an attempt will be
+      made to store the FITS header cards back in their original
+      locations. Otherwise, the new cards will be inserted following
+      any other FITS-WCS related header cards present or, failing
+      that, in front of the current card (as given by the Card
+      attribute).
+
+      If an attempt to simplify a FrameSet to conform to the FITS-WCS
+      model fails (or if the Object supplied is not a FrameSet), then
+      no data will be written to the FitsChan and astWrite will
+      return zero. No error will result.
+   }
+   \sstdiytopic{
+      The FITS-IRAF Encoding
+   }{
+      The FITS-IRAF encoding can, for most purposes, be considered as
+      a subset of the FITS-WCS encoding (above), although it differs
+      in the details of the FITS keywords used. It is used in exactly
+      the same way and has the same restrictions, but with the
+
+      addition of the following:
+
+      \sstitemlist{
+
+         \sstitem
+          The only celestial coordinate systems that may be represented
+         are equatorial, galactic and ecliptic,
+
+         \sstitem
+          Sky projections can be represented only if any associated
+         projection parameters are set to their default values.
+
+         \sstitem
+          Secondary axis descriptions are not supported, so when writing
+         a FrameSet to a FitsChan, only information from the base and
+         current Frames will be stored.
+
+      }
+      Note that this encoding is provided mainly as an interim measure to
+      provide a more stable alternative to the FITS-WCS encoding until the
+      FITS standard for encoding WCS information is finalised.  The name
+      \texttt{"} FITS-IRAF\texttt{"}  indicates the general keyword conventions used and does
+      not imply that this encoding will necessarily support all features of
+      the WCS scheme used by IRAF software. Nevertheless, an attempt has
+      been made to support a few such features where they are known to be
+      used by important sources of data.
+
+      When writing a FrameSet using the FITS-IRAF encoding, axis rotations
+      are specified by a matrix of FITS keywords of the form \texttt{"} CDi\_j\texttt{"} , where
+      \texttt{"} i\texttt{"}  and \texttt{"} j\texttt{"}  are single digits. The alternative form \texttt{"} CDiiijjj\texttt{"} , which
+      is also in use, is recognised when reading an Object, but is never
+      written.
+
+      In addition, the experimental IRAF \texttt{"} ZPX\texttt{"}  and \texttt{"} TNX\texttt{"}  sky projections will
+      be accepted when reading, but will never be written (the corresponding
+      FITS \texttt{"} ZPN\texttt{"}  or \texttt{"} distorted TAN\texttt{"}  projection being used instead). However,
+      there are restrictions on the use of these experimental projections.
+      For \texttt{"} ZPX\texttt{"} , longitude and latitude correction surfaces (appearing as
+      \texttt{"} lngcor\texttt{"}  or \texttt{"} latcor\texttt{"}  terms in the IRAF-specific \texttt{"} WAT\texttt{"}  keywords) are
+      not supported. For \texttt{"} TNX\texttt{"}  projections, only cubic surfaces encoded as
+      simple polynomials with \texttt{"} half cross-terms\texttt{"}  are supported. If an
+      un-usable \texttt{"} TNX\texttt{"}  or \texttt{"} ZPX\texttt{"}  projection is encountered while reading
+      from a FitsChan, a simpler form of TAN or ZPN projection is used
+      which ignores the unsupported features and may therefore be
+      inaccurate. If this happens, a warning message is added to the
+      contents of the FitsChan as a set of cards using the keyword \texttt{"} ASTWARN\texttt{"} .
+
+      You should not normally attempt to mix the foreign FITS encodings within
+      the same FitsChan, since there is a risk that keyword clashes may occur.
+   }
+   \sstdiytopic{
+      The FITS-PC Encoding
+   }{
+      The FITS-PC encoding can, for most purposes, be considered as
+      equivalent to the FITS-WCS encoding (above), although it differs
+      in the details of the FITS keywords used. It is used in exactly
+      the same way and has the same restrictions.
+   }
+   \sstdiytopic{
+      The FITS-AIPS Encoding
+   }{
+      The FITS-AIPS encoding can, for most purposes, be considered as
+      equivalent to the FITS-WCS encoding (above), although it differs
+      in the details of the FITS keywords used. It is used in exactly
+      the same way and has the same restrictions, but with the
+
+      addition of the following:
+
+      \sstitemlist{
+
+         \sstitem
+          The only celestial coordinate systems that may be represented
+         are equatorial, galactic and ecliptic,
+
+         \sstitem
+          Spectral axes can only be represented if they represent
+         frequency, radio velocity or optical velocity, and are linearly
+         sampled in frequency. In addition, the standard of rest
+         must be LSRK, LSRD, barycentric or geocentric.
+
+         \sstitem
+          Sky projections can be represented only if any associated
+         projection parameters are set to their default values.
+
+         \sstitem
+          The AIT, SFL and MER projections can only be written if the CRVAL
+         keywords are zero for both longitude and latitude axes.
+
+         \sstitem
+          Secondary axis descriptions are not supported, so when writing
+         a FrameSet to a FitsChan, only information from the base and
+         current Frames will be stored.
+
+         \sstitem
+          If there are more than 2 axes in the base and current Frames, any
+         rotation must be restricted to the celestial plane, and must involve
+         no shear.
+      }
+   }
+   \sstdiytopic{
+      The FITS-AIPS$+$$+$ Encoding
+   }{
+      The FITS-AIPS$+$$+$ encoding is based on the FITS-AIPS encoding, but
+      includes some features of the FITS-IRAF and FITS-PC encodings.
+      Specifically, any celestial projections supported by FITS-PC may be
+      used, including those which require parameterisation, and the axis
+      rotation and scaling may be specified using CDi\_j keywords. When
+      writing a FITS header, rotation will be specified using CROTA/CDELT
+      keywords if possible, otherwise CDi\_j keywords will be used instead.
+   }
+   \sstdiytopic{
+      The FITS-CLASS Encoding
+   }{
+      The FITS-CLASS encoding uses the conventions of the CLASS project.
+      These are described in the section \texttt{"} Developer Manual\texttt{"} /\texttt{"} CLASS FITS
+
+      Format\texttt{"}  contained in the CLASS documentation at:
+
+      http://www.iram.fr/IRAMFR/GILDAS/doc/html/class-html/class.html.
+
+      This encoding is similar to FITS-AIPS with the following restrictions:
+
+      \sstitemlist{
+
+         \sstitem
+          When a \htmlref{SpecFrame}{SpecFrame} is created by reading a FITS-CLASS header, the
+           attributes describing the observer\texttt{'} s position (\htmlref{ObsLat}{ObsLat}, \htmlref{ObsLon}{ObsLon} and
+           \htmlref{ObsAlt}{ObsAlt}) are left unset because the CLASS encoding does not specify
+           these values. Conversions to or from the topocentric standard of rest
+           will therefore be inaccurate (typically by up to about 0.5 km/s)
+           unless suitable values are assigned to these attributes after the
+           FrameSet has been created.
+
+         \sstitem
+          When writing a FrameSet to a FITS-CLASS header, the current Frame
+           in the FrameSet must have at least 3 WCS axes, of which one must be
+           a linear spectral axis. The spectral axis in the created header will
+           always describe frequency. If the spectral axis in the supplied
+           FrameSet refers to some other system (e.g. radio velocity, etc),
+           then it will be converted to frequency.
+
+         \sstitem
+          There must be a pair of celestial axes - either (RA,Dec) or
+           (GLON,GLAT). RA and Dec must be either FK4/B1950 or FK5/J2000.
+
+         \sstitem
+          A limited range of projection codes (TAN, ARC, STG, AIT, SFL, SIN)
+           can be used. For AIT and SFL, the reference point must be at the
+           origin of longitude and latitude. For SIN, the associated projection
+           parameters must both be zero.
+
+         \sstitem
+          No rotation of the celestial axes is allowed, unless the spatial
+           axes are degenerate (i.e. cover only a single pixel).
+
+         \sstitem
+          The frequency axis in the created header will always describe
+           frequency in the source rest frame. If the supplied FrameSet uses
+           some other standard of rest then suitable conversion will be applied.
+
+         \sstitem
+          The source velocity must be defined. In other words, the SpecFrame
+           attributes \htmlref{SourceVel}{SourceVel} and \htmlref{SourceVRF}{SourceVRF} must have been assigned values.
+
+         \sstitem
+          The frequency axis in a FITS-CLASS header does not represent
+           absolute frequency, but instead represents offsets from the rest
+           frequency in the standard of rest of the source.
+
+      }
+      When writing a FrameSet out using FITS-CLASS encoding, the current
+      Frame may be temporarily modified if this will allow the header
+      to be produced. If this is done, the associated pixel-$>$WCS Mapping
+      will also be modified to take account of the changes to the Frame.
+      The modifications performed include re-ordering axes (WCS axes, not
+      pixel axes), changing spectral coordinate system and standard of
+      rest, changing the celestial coordinate system and reference equinox,
+      and changing axis units.
+   }
+   \sstdiytopic{
+      The NATIVE Encoding
+   }{
+      The NATIVE encoding may be used to store a description of any
+      class of AST Object in the form of FITS header cards, and (for
+      most practical purposes) any number of these Object descriptions
+      may be stored within a single set of FITS cards. If multiple
+      Object descriptions are stored, they are written and read
+      sequentially. The NATIVE encoding makes use of unique FITS
+      keywords which are designed not to clash with keywords that have
+      already been used for other purposes (if a potential clash is
+      detected, an alternative keyword is constructed to avoid the
+      clash).
+
+      When reading a NATIVE encoded object from a FitsChan (using
+      astRead), FITS header cards are read, starting at the current
+      card (as determined by the Card attribute), until the start of
+      the next Object description is found. This description is then
+      read and converted into an AST Object, for which a pointer is
+      returned. Such a read is always destructive and causes all the
+      FITS header cards involved in the Object description to be
+      removed from the FitsChan, which is left positioned at the
+      following card.
+
+      The Object returned may be of any class, depending on the
+      description that was read, and other AST routines may be used to
+      validate it (for example, by examining its \htmlref{Class}{Class} or \htmlref{ID}{ID} attribute
+      using astGetC). If further NATIVE encoded Object descriptions
+      exist in the FitsChan, subsequent calls to astRead will return
+      the Objects they describe in sequence (and destroy their
+      descriptions) until no more remain between the current card and
+      the \texttt{"} end-of-file\texttt{"} .
+
+      When astWrite is used to write an Object using NATIVE encoding,
+      a description of the Object is inserted immediately before the
+      current card (as determined by the Card attribute).  Multiple
+      Object descriptions may be written in this way and are stored
+      separately (and sequentially if the Card attribute is not
+      modified between the writes). A write operation using the NATIVE
+      encoding does not over-write previously written Object
+      descriptions. Note, however, that subsequent behaviour is
+      undefined if an Object description is written inside a
+      previously-written description, so this should be avoided.
+
+      When an Object is written to a FitsChan using NATIVE encoding,
+      astWrite should (barring errors) always transfer data and
+      return a value of 1.
+   }
+}
+\sstroutine{
+   Epoch
+}{
+   Epoch of observation
+}{
+   \sstdescription{
+      This attribute is used to qualify the coordinate systems described by
+      a \htmlref{Frame}{Frame}, by giving the moment in time when the coordinates are known
+      to be correct. Often, this will be the date of observation, and is
+      important in cases where coordinates systems move with respect to each
+      other over the course of time.
+
+      The Epoch attribute is stored as a Modified Julian Date, but
+      when setting its value it may be given in a variety of
+      formats. See the \texttt{"} Input Formats\texttt{"}  section (below) for details.
+      Strictly, the Epoch value should be supplied in the TDB timescale,
+      but for some purposes (for instance, for converting sky positions
+      between different types of equatorial system) the timescale is not
+      significant, and UTC may be used.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Frame
+      }{
+         All Frames have this attribute. The basic Frame class provides
+         a default of J2000.0 (Julian) but makes no use of the Epoch value.
+         This is because the Frame class does not distinguish between
+         different Cartesian coordinate systems (see the \htmlref{System}{System} attribute).
+      }
+      \sstsubsection{
+         \htmlref{CmpFrame}{CmpFrame}
+      }{
+         The default Epoch value for a CmpFrame is selected as follows;
+         if the Epoch attribute has been set in the first component Frame
+         then the Epoch value from the first component Frame is used as
+         the default for the CmpFrame. Otherwise, if the Epoch attribute has
+         been set in the second component Frame then the Epoch value from the
+         second component Frame is used as the default for the CmpFrame.
+         Otherwise, the default Epoch value from the first component
+         Frame is used as the default for the CmpFrame. When the Epoch
+         attribute of a CmpFrame is set or cleared, it is also set or
+         cleared in the two component Frames.
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         The Epoch attribute of a FrameSet is the same as that of its current
+         Frame (as specified by the \htmlref{Current}{Current} attribute).
+      }
+      \sstsubsection{
+         \htmlref{SkyFrame}{SkyFrame}
+      }{
+         The coordinates of sources within a SkyFrame can change with time
+         for various reasons, including: (i) changing aberration of light
+         caused by the observer\texttt{'} s velocity (e.g. due to the Earth\texttt{'} s motion
+         around the Sun), (ii) changing gravitational deflection by the Sun
+         due to changes in the observer\texttt{'} s position with time, (iii) fictitious
+         motion due to rotation of non-inertial coordinate systems (e.g. the
+         old FK4 system), and (iv) proper motion of the source itself (although
+         this last effect is not handled by the SkyFrame class because it
+         affects individual sources rather than the coordinate system as
+         a whole).
+
+         The default Epoch value in a SkyFrame is B1950.0 (Besselian) for the
+         old FK4-based coordinate systems (see the System attribute) and
+         J2000.0 (Julian) for all others.
+
+         Care must be taken to distinguish the Epoch value, which relates to
+         motion (or apparent motion) of the source, from the superficially
+         similar \htmlref{Equinox}{Equinox} value. The latter is used to qualify a coordinate
+         system which is itself in motion in a (notionally) predictable way
+         as a result of being referred to a slowly moving reference plane
+         (e.g. the equator).
+
+         See the description of the System attribute for details of which
+         qualifying attributes apply to each celestial coordinate system.
+      }
+      \sstsubsection{
+         \htmlref{TimeFrame}{TimeFrame}
+      }{
+         A TimeFrame describes a general time axis and so cannot be completely
+         characterised by a single Epoch value. For this reason the TimeFrame
+         class makes no use of the Epoch attribute. However, user code can
+         still make use of the attribute if necessary to represent a \texttt{"} typical\texttt{"}
+         time spanned by the TimeFrame. The default Epoch value for a TimeFrame
+         will be the TDB equivalent of the current value of the TimeFrame\texttt{'} s
+         \htmlref{TimeOrigin}{TimeOrigin} attribute. If no value has been set for TimeOrigin,
+         then the default Epoch value is J2000.0.
+      }
+   }
+   \sstdiytopic{
+      Input Formats
+   }{
+      The formats accepted when setting an Epoch value are listed
+      below. They are all case-insensitive and are generally tolerant
+      of extra white space and alternative field delimiters:
+
+      \sstitemlist{
+
+         \sstitem
+          Besselian Epoch: Expressed in decimal years, with or without
+         decimal places (\texttt{"} B1950\texttt{"}  or \texttt{"} B1976.13\texttt{"}  for example).
+
+         \sstitem
+          Julian Epoch: Expressed in decimal years, with or without
+         decimal places (\texttt{"} J2000\texttt{"}  or \texttt{"} J2100.9\texttt{"}  for example).
+
+         \sstitem
+          Year: Decimal years, with or without decimal places (\texttt{"} 1996.8\texttt{"}
+         for example).  Such values are interpreted as a Besselian epoch
+         (see above) if less than 1984.0 and as a Julian epoch otherwise.
+
+         \sstitem
+          Julian Date: With or without decimal places (\texttt{"} JD 2454321.9\texttt{"}  for
+         example).
+
+         \sstitem
+          Modified Julian Date: With or without decimal places
+         (\texttt{"} MJD 54321.4\texttt{"}  for example).
+
+         \sstitem
+          Gregorian Calendar Date: With the month expressed either as an
+         integer or a 3-character abbreviation, and with optional decimal
+         places to represent a fraction of a day (\texttt{"} 1996-10-2\texttt{"}  or
+         \texttt{"} 1996-Oct-2.6\texttt{"}  for example). If no fractional part of a day is
+         given, the time refers to the start of the day (zero hours).
+
+         \sstitem
+          Gregorian Date and Time: Any calendar date (as above) but with
+         a fraction of a day expressed as hours, minutes and seconds
+         (\texttt{"} 1996-Oct-2 12:13:56.985\texttt{"}  for example). The date and time can be
+         separated by a space or by a \texttt{"} T\texttt{"}  (as used by ISO8601 format).
+      }
+   }
+   \sstdiytopic{
+      Output Format
+   }{
+      When enquiring Epoch values, the format used is the \texttt{"} Year\texttt{"}
+      format described under \texttt{"} Input Formats\texttt{"} . This is a value in
+      decimal years which will be a Besselian epoch if less than
+      1984.0 and a Julian epoch otherwise.  By omitting any character
+      prefix, this format allows the Epoch value to be obtained as
+      either a character string or a floating point value.
+   }
+}
+\sstroutine{
+   Equinox
+}{
+   Epoch of the mean equinox
+}{
+   \sstdescription{
+      This attribute is used to qualify those celestial coordinate
+      systems described by a \htmlref{SkyFrame}{SkyFrame} which are notionally based on
+      the ecliptic (the plane of the Earth\texttt{'} s orbit around the Sun)
+      and/or the Earth\texttt{'} s equator.
+
+      Both of these planes are in motion and their positions are
+      difficult to specify precisely. In practice, therefore, a model
+      ecliptic and/or equator are used instead. These, together with
+      the point on the sky that defines the coordinate origin (the
+      intersection of the two planes termed the \texttt{"} mean equinox\texttt{"} ) move
+      with time according to some model which removes the more rapid
+      fluctuations. The SkyFrame class supports both the FK4 and
+      FK5 models.
+
+      The position of a fixed source expressed in any of these
+      coordinate systems will appear to change with time due to
+      movement of the coordinate system itself (rather than motion of
+      the source).  Such coordinate systems must therefore be
+      qualified by a moment in time (the \texttt{"} epoch of the mean equinox\texttt{"}
+      or \texttt{"} equinox\texttt{"}  for short) which allows the position of the model
+      coordinate system on the sky to be determined. This is the role
+      of the Equinox attribute.
+
+      The Equinox attribute is stored as a Modified Julian Date, but
+      when setting or getting its value you may use the same formats
+      as for the \htmlref{Epoch}{Epoch} attribute (q.v.).
+
+      The default Equinox value is B1950.0 (Besselian) for the old
+      FK4-based coordinate systems (see the \htmlref{System}{System} attribute) and
+      J2000.0 (Julian) for all others.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         SkyFrame
+      }{
+         All SkyFrames have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Care must be taken to distinguish the Equinox value, which
+         relates to the definition of a time-dependent coordinate system
+         (based on solar system reference planes which are in motion),
+         from the superficially similar Epoch value. The latter is used
+         to qualify coordinate systems where the positions of sources
+         change with time (or appear to do so) for a variety of other
+         reasons, such as aberration of light caused by the observer\texttt{'} s
+         motion, etc.
+
+         \sstitem
+          See the description of the System attribute for details of
+         which qualifying attributes apply to each celestial coordinate
+         system.
+      }
+   }
+}
+\sstroutine{
+   Escape
+}{
+   Allow changes of character attributes within strings?
+}{
+   \sstdescription{
+      This attribute controls the appearance of text strings and numerical
+      labels drawn by the \htmlref{astGrid}{astGrid} and (for the \htmlref{Plot}{Plot} class) \htmlref{astText}{astText} functions,
+      by determining if any escape sequences contained within the strings
+      should be used to control the appearance of the text, or should
+      be printed literally. Note, the \htmlref{Plot3D}{Plot3D} class only interprets escape
+      sequences within the
+      astGrid function.
+
+      If the Escape value of a Plot is one (the default), then any
+      escape sequences in text strings produce the effects described
+      below when printed. Otherwise, they are printed literally.
+
+      See also the \htmlref{astEscapes}{astEscapes} function.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+   \sstdiytopic{
+      Escape Sequences
+   }{
+      Escape sequences are introduced into the text string by a percent
+      \texttt{"} \%\texttt{"}  character. Any unrecognised, illegal or incomplete escape sequences
+      are printed literally. The following escape sequences are
+      currently recognised (\texttt{"} ...\texttt{"}  represents a string of one or more
+      decimal digits):
+
+        \%\%      - Print a literal \texttt{"} \%\texttt{"}  character.
+
+        \%$\wedge$...$+$  - Draw subsequent characters as super-scripts. The digits
+                  \texttt{"} ...\texttt{"}  give the distance from the base-line of \texttt{"} normal\texttt{"}
+                  text to the base-line of the super-script text, scaled
+                  so that a value of \texttt{"} 100\texttt{"}  corresponds to the height of
+                  \texttt{"} normal\texttt{"}  text.
+        \%$\wedge$$+$     - Draw subsequent characters with the normal base-line.
+
+        \%v...$+$  - Draw subsequent characters as sub-scripts. The digits
+                  \texttt{"} ...\texttt{"}  give the distance from the base-line of \texttt{"} normal\texttt{"}
+                  text to the base-line of the sub-script text, scaled
+                  so that a value of \texttt{"} 100\texttt{"}  corresponds to the height of
+                  \texttt{"} normal\texttt{"}  text.
+
+        \%v$+$     - Draw subsequent characters with the normal base-line
+                  (equivalent to \%$\wedge$$+$).
+
+        \%$>$...$+$  - Leave a gap before drawing subsequent characters.
+                  The digits \texttt{"} ...\texttt{"}  give the size of the gap, scaled
+                  so that a value of \texttt{"} 100\texttt{"}  corresponds to the height of
+                  \texttt{"} normal\texttt{"}  text.
+
+        \%$<$...$+$  - Move backwards before drawing subsequent characters.
+                  The digits \texttt{"} ...\texttt{"}  give the size of the movement, scaled
+                  so that a value of \texttt{"} 100\texttt{"}  corresponds to the height of
+                  \texttt{"} normal\texttt{"}  text.
+
+        \%s...$+$  - Change the Size attribute for subsequent characters. The
+                  digits \texttt{"} ...\texttt{"}  give the new Size as a fraction of the
+                  \texttt{"} normal\texttt{"}  Size, scaled so that a value of \texttt{"} 100\texttt{"}  corresponds
+                  to 1.0;
+
+        \%s$+$     - Reset the Size attribute to its \texttt{"} normal\texttt{"}  value.
+
+        \%w...$+$  - Change the Width attribute for subsequent characters. The
+                  digits \texttt{"} ...\texttt{"}  give the new width as a fraction of the
+                  \texttt{"} normal\texttt{"}  Width, scaled so that a value of \texttt{"} 100\texttt{"}  corresponds
+                  to 1.0;
+
+        \%w$+$     - Reset the Size attribute to its \texttt{"} normal\texttt{"}  value.
+
+        \%f...$+$  - Change the Font attribute for subsequent characters. The
+                  digits \texttt{"} ...\texttt{"}  give the new Font value.
+
+        \%f$+$     - Reset the Font attribute to its \texttt{"} normal\texttt{"}  value.
+
+        \%c...$+$  - Change the Colour attribute for subsequent characters. The
+                  digits \texttt{"} ...\texttt{"}  give the new Colour value.
+
+        \%c$+$     - Reset the Colour attribute to its \texttt{"} normal\texttt{"}  value.
+
+        \%t...$+$  - Change the Style attribute for subsequent characters. The
+                  digits \texttt{"} ...\texttt{"}  give the new Style value.
+
+        \%t$+$     - Reset the Style attribute to its \texttt{"} normal\texttt{"}  value.
+
+        \%h$+$     - Remember the current horizontal position (see \texttt{"} \%g$+$\texttt{"} )
+
+        \%g$+$     - Go to the horizontal position of the previous \texttt{"} \%h$+$\texttt{"}  (if any).
+
+        \%-      - Push the current graphics attribute values onto the top of
+                  the stack (see \texttt{"} \%$+$\texttt{"} ).
+
+        \%$+$      - Pop attributes values of the top the stack (see \texttt{"} \%-\texttt{"} ). If
+                  the stack is empty, \texttt{"} normal\texttt{"}  attribute values are restored.
+   }
+}
+\sstroutine{
+   FillFactor
+}{
+   Fraction of the Region which is of interest
+}{
+   \sstdescription{
+      This attribute indicates the fraction of the \htmlref{Region}{Region} which is of
+      interest. AST does not use this attribute internally for any purpose.
+      Typically, it could be used to indicate the fraction of the Region for
+      which data is available.
+
+      The supplied value must be in the range 0.0 to 1.0, and the default
+      value is 1.0 (except as noted below).
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Region
+      }{
+         All Regions have this attribute.
+      }
+      \sstsubsection{
+         \htmlref{CmpRegion}{CmpRegion}
+      }{
+         The default FillFactor for a CmpRegion is the FillFactor of its
+         first component Region.
+      }
+      \sstsubsection{
+         \htmlref{Prism}{Prism}
+      }{
+         The default FillFactor for a Prism is the product of the
+         FillFactors of its two component Regions.
+      }
+      \sstsubsection{
+         \htmlref{Stc}{Stc}
+      }{
+         The default FillFactor for an Stc is the FillFactor of its
+         encapsulated Region.
+      }
+   }
+}
+\sstroutine{
+   FitsAxisOrder
+}{
+   Frame title
+}{
+   \sstdescription{
+      This attribute specifies the order for the WCS axes in any new
+      FITS-WCS headers created using the
+      \htmlref{astWrite}{astWrite}
+      method.
+
+      The value of the FitsAxisOrder attribute can be either \texttt{"} $<$auto$>$\texttt{"}
+      (the default value), \texttt{"} $<$copy$>$\texttt{"}  or a space-separated list of axis
+      symbols:
+
+      \texttt{"} $<$auto$>$\texttt{"} : causes the WCS axis order to be chosen automatically so that
+      the i\texttt{'} th WCS axis in the new FITS header is the WCS axis which is
+      more nearly parallel to the i\texttt{'} th pixel axis.
+
+      \texttt{"} $<$copy$>$\texttt{"} : causes the WCS axis order to be set so that the i\texttt{'} th WCS
+      axis in the new FITS header is the i\texttt{'} th WCS axis in the current
+      \htmlref{Frame}{Frame} of the \htmlref{FrameSet}{FrameSet} being written out to the header.
+
+      \texttt{"} Sym1 Sym2...\texttt{"} : the space-separated list is seached in turn for
+      the Symbol attribute of each axis in the current Frame of the
+      FrameSet. The order in which these Symbols occur within the
+      space-separated list defines the order of the WCS axes in the
+      new FITS header. An error is reported if Symbol for a current
+      Frame axis is not present in the supplied list. However, no error
+      is reported if the list contains extra words that do not correspond
+      to the Symbol of any current Frame axis.
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{FitsChan}{FitsChan}
+      }{
+         All FitsChans have this attribute.
+      }
+   }
+}
+\sstroutine{
+   FitsDigits
+}{
+   Digits of precision for floating point FITS values
+}{
+   \sstdescription{
+      This attribute gives the number of significant decimal digits to
+      use when formatting floating point values for inclusion in the
+      FITS header cards within a \htmlref{FitsChan}{FitsChan}.
+
+      By default, a positive value is used which results in no loss of
+      information, assuming that the value\texttt{'} s precision is double.
+      Usually, this causes no problems.
+
+      However, to adhere strictly to the recommendations of the FITS
+      standard, the width of the formatted value (including sign,
+      decimal point and exponent) ought not to be more than 20
+      characters. If you are concerned about this, you should set
+      FitsDigits to a negative value, such as -15. In this case, the
+      absolute value ($+$15) indicates the maximum number of significant
+      digits to use, but the actual number used may be fewer than this
+      to ensure that the FITS recommendations are satisfied. When
+      using this approach, the resulting number of significant digits
+      may depend on the value being formatted and on the presence of
+      any sign, decimal point or exponent.
+
+      The value of this attribute is effective when FITS header cards
+      are output, either using
+      \htmlref{astFindFits}{astFindFits} or by the action of the FitsChan\texttt{'} s sink function
+      when it is finally deleted.
+   }
+   \sstattributetype{
+      Integer.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         FitsChan
+      }{
+         All FitsChans have this attribute.
+      }
+   }
+}
+\sstroutine{
+   FitsTol
+}{
+   Maximum non-linearity allowed when exporting to FITS-WCS
+}{
+   \sstdescription{
+      This attribute is used when attempting to write a \htmlref{FrameSet}{FrameSet} to a
+      \htmlref{FitsChan}{FitsChan} using a foreign encoding. It specifies the maximum
+      departure from linearity allowed on any axis within the mapping
+      from pixel coordinates to Intermediate World Coordinates. It is
+      expressed in units of pixels. If an axis of the \htmlref{Mapping}{Mapping} is found
+      to deviate from linearity by more than this amount, the write
+      operation fails. If the linearity test succeeds, a linear
+      approximation to the mapping is used to determine the FITS keyword
+      values to be placed in the FitsChan.
+
+      The default value is one tenth of a pixel.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         FitsChan
+      }{
+         All FitsChans have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Font(element)
+}{
+   Character font for a Plot element
+}{
+   \sstdescription{
+      This attribute determines the character font index used when
+      drawing each element of graphical output produced by a \htmlref{Plot}{Plot}. It
+      takes a separate value for each graphical element so that, for
+      instance, the setting \texttt{"} Font(title)=2\texttt{"}  causes the Plot title to
+      be drawn using font number 2.
+
+      The range of integer font indices available and the appearance
+      of the resulting text is determined by the underlying graphics
+      system.  The default behaviour is for all graphical elements to
+      be drawn using the default font supplied by this graphics
+      system.
+   }
+   \sstattributetype{
+      Integer.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          For a list of the graphical elements available, see the
+         description of the Plot class.
+
+         \sstitem
+          If no graphical element is specified, (e.g. \texttt{"} Font\texttt{"}  instead
+         of \texttt{"} Font(title)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will
+         affect the attribute value of all graphical elements, while a
+         \texttt{"} get\texttt{"}  or \texttt{"} test\texttt{"}  operation will use just the Font(TextLab)
+         value.
+      }
+   }
+}
+\sstroutine{
+   Format(axis)
+}{
+   Format specification for axis values
+}{
+   \sstdescription{
+      This attribute specifies the format to be used when displaying
+      coordinate values associated with a particular \htmlref{Frame}{Frame} axis
+      (i.e. to convert values from binary to character form). It is
+      interpreted by the \htmlref{astFormat}{astFormat} function and determines the
+      formatting which it applies.
+
+      If no Format value is set for a Frame axis, a default value is
+      supplied instead. This is based on the value of the Digits, or
+      Digits(axis), attribute and is chosen so that it displays the
+      requested number of digits of precision.
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Frame
+      }{
+         The Frame class interprets this attribute as a format
+         specification string to be passed to the C \texttt{"} printf\texttt{"}  function
+         (e.g. \texttt{"} \%1.7G\texttt{"} ) in order to format a single coordinate value
+         (supplied as a double precision number).
+
+         When supplying a value for this attribute, beware that the
+         \texttt{"} \%\texttt{"}  character may be interpreted directly as a format
+         specification by some printf-like functions (such as
+         \htmlref{astSet}{astSet}). You may need to double it (i.e. use \texttt{"} \%\%\texttt{"} ) to avoid
+         this.
+      }
+      \sstsubsection{
+         \htmlref{SkyFrame}{SkyFrame}
+      }{
+         The SkyFrame class re-defines the syntax and default value of
+         the Format string to allow the formatting of sexagesimal
+         values as appropriate for the particular celestial coordinate
+         system being represented. The syntax of SkyFrame Format
+         strings is described (below) in the \texttt{"} SkyFrame Formats\texttt{"}
+         section.
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         The Format attribute of a FrameSet axis is the same as that
+         of its current Frame (as specified by the \htmlref{Current}{Current}
+         attribute). Note that the syntax of the Format string is also
+         determined by the current Frame.
+      }
+      \sstsubsection{
+         \htmlref{TimeFrame}{TimeFrame}
+      }{
+         The TimeFrame class extends the syntax of the Format string to
+         allow the formatting of TimeFrame axis values as Gregorian calendar
+         dates and times. The syntax of TimeFrame Format strings is described
+         (below) in the \texttt{"} TimeFrame Formats\texttt{"}  section.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          When specifying this attribute by name, it should be
+         subscripted with the number of the Frame axis to which it
+         applies.
+      }
+   }
+   \sstdiytopic{
+      SkyFrame Formats
+   }{
+      The Format string supplied for a SkyFrame should contain zero or
+      more of the following characters. These may occur in any order,
+      but the following is recommended for clarity:
+
+      \sstitemlist{
+
+         \sstitem
+          \texttt{"} $+$\texttt{"} : Indicates that a plus sign should be prefixed to positive
+         values. By default, no plus sign is used.
+
+         \sstitem
+          \texttt{"} z\texttt{"} : Indicates that leading zeros should be prefixed to the
+         value so that the first field is of constant width, as would be
+         required in a fixed-width table (leading zeros are always
+         prefixed to any fields that follow). By default, no leading
+         zeros are added.
+
+         \sstitem
+          \texttt{"} i\texttt{"} : Use the standard ISO field separator (a colon) between
+         fields. This is the default behaviour.
+
+         \sstitem
+          \texttt{"} b\texttt{"} : Use a blank to separate fields.
+
+         \sstitem
+          \texttt{"} l\texttt{"} : Use a letter (\texttt{"} h\texttt{"} /\texttt{"} d\texttt{"} , \texttt{"} m\texttt{"}  or \texttt{"} s\texttt{"}  as appropriate) to
+         separate fields.
+
+         \sstitem
+          \texttt{"} g\texttt{"} : Use a letter and symbols to separate fields (\texttt{"} h\texttt{"} /\texttt{"} d\texttt{"} , \texttt{"} m\texttt{"}  or \texttt{"} s\texttt{"} ,
+         etc, as appropriate), but include escape sequences in the formatted
+         value so that the \htmlref{Plot}{Plot} class will draw the separators as small
+         super-scripts.
+         The default escape sequences are optimised for the pgplot graphics
+         package, but new escape sequences may be specified using function
+         astSetSkyDelim.
+
+         \sstitem
+          \texttt{"} d\texttt{"} : Include a degrees field. Expressing the angle purely in
+         degrees is also the default if none of \texttt{"} h\texttt{"} , \texttt{"} m\texttt{"} , \texttt{"} s\texttt{"}  or \texttt{"} t\texttt{"}  are
+         given.
+
+         \sstitem
+          \texttt{"} h\texttt{"} : Express the angle as a time and include an hours field
+         (where 24 hours correspond to 360 degrees). Expressing the angle
+         purely in hours is also the default if \texttt{"} t\texttt{"}  is given without
+         either \texttt{"} m\texttt{"}  or \texttt{"} s\texttt{"} .
+
+         \sstitem
+          \texttt{"} m\texttt{"} : Include a minutes field. By default this is not included.
+
+         \sstitem
+          \texttt{"} s\texttt{"} : Include a seconds field. By default this is not included.
+         This request is ignored if \texttt{"} d\texttt{"}  or \texttt{"} h\texttt{"}  is given, unless a minutes
+         field is also included.
+
+         \sstitem
+          \texttt{"} t\texttt{"} : Express the angle as a time (where 24 hours correspond to
+         360 degrees). This option is ignored if either \texttt{"} d\texttt{"}  or \texttt{"} h\texttt{"}  is
+         given and is intended for use where the value is to be expressed
+         purely in minutes and/or seconds of time (with no hours
+         field). If \texttt{"} t\texttt{"}  is given without \texttt{"} d\texttt{"} , \texttt{"} h\texttt{"} , \texttt{"} m\texttt{"}  or \texttt{"} s\texttt{"}  being
+         present, then it is equivalent to \texttt{"} h\texttt{"} .
+
+         \sstitem
+          \texttt{"} .\texttt{"} : Indicates that decimal places are to be given for the
+         final field in the formatted string (whichever field this
+         is). The \texttt{"} .\texttt{"}  should be followed immediately by an unsigned
+         integer which gives the number of decimal places required, or by an
+         asterisk. If an asterisk is supplied, a default number of decimal
+         places is used which is based on the value of the Digits
+         attribute.
+
+      }
+      All of the above format specifiers are case-insensitive. If
+      several characters make conflicting requests (e.g. if both \texttt{"} i\texttt{"}
+      and \texttt{"} b\texttt{"}  appear), then the character occurring last takes
+      precedence, except that \texttt{"} d\texttt{"}  and \texttt{"} h\texttt{"}  always override \texttt{"} t\texttt{"} .
+
+      If the format string starts with a percentage sign (\%), then the
+      whole format string is assumed to conform to the syntax defined by
+      the Frame class, and the axis values is formated as a decimal
+      radians value.
+   }
+   \sstdiytopic{
+      TimeFrame Formats
+   }{
+      The Format string supplied for a TimeFrame should either use the
+      syntax defined by the base Frame class (i.e. a C \texttt{"} printf\texttt{"}  format
+      string), or the extended \texttt{"} iso\texttt{"}  syntax described below (the default
+      value is inherited from the Frame class):
+
+      \sstitemlist{
+
+         \sstitem
+          C \texttt{"} printf\texttt{"}  syntax: If the Format string is a C \texttt{"} printf\texttt{"}  format
+         description such as \texttt{"} \%1.7G\texttt{"} , the TimeFrame axis value will be
+         formatted without change as a floating point value using this format.
+         The formatted string will thus represent an offset from the zero point
+         specified by the TimeFrame\texttt{'} s \htmlref{TimeOrigin}{TimeOrigin} attribute, measured in
+         units given by the TimeFrame\texttt{'} s Unit attribute.
+
+         \sstitem
+          \texttt{"} iso\texttt{"}  syntax: This is used to format a TimeFrame axis value as a
+         Gregorian date followed by an optional time of day. If the Format
+         value commences with the string \texttt{"} iso\texttt{"}  then the TimeFrame axis value
+         will be converted to an absolute MJD, including the addition of the
+         current TimeOrigin value, and then formatted as a Gregorian date
+         using the format \texttt{"} yyyy-mm-dd\texttt{"} . Optionally, the Format value may
+         include an integer precision following the \texttt{"} iso\texttt{"}  specification (e.g.
+         \texttt{"} iso.2\texttt{"} ), in which case the time of day will be appended to the
+         formatted date (if no time of day is included, the date field is
+         rounded to the nearest day). The integer value in the Format string
+         indicates the number of decimal places to use in the seconds field. For
+         instance, a Format value of \texttt{"} iso.0\texttt{"}  produces a time of day of the form
+         \texttt{"} hh:mm:ss\texttt{"} , and a Format value of \texttt{"} iso.2\texttt{"}  produces a time of day of the
+         form \texttt{"} hh:mm:ss.ss\texttt{"} . The date and time fields will be separated by a
+         space unless \texttt{'} T\texttt{'}  is appended to the end of string, in which case
+         the letter T (upper case) will be used as the separator. The value of
+         the Digits attribute is ignored when using this \texttt{"} iso\texttt{"}  format.
+      }
+   }
+}
+\sstroutine{
+   Full
+}{
+   Set level of output detail
+}{
+   \sstdescription{
+      This attribute is a three-state flag and takes values of -1, 0
+      or $+$1.  It controls the amount of information included in the
+      output generated by a \htmlref{Channel}{Channel}.
+
+      If Full is zero, then a modest amount of
+      non-essential but useful information will be included in the
+      output. If Full is negative, all non-essential information will
+      be suppressed to minimise the amount of output, while if it is
+      positive, the output will include the maximum amount of detailed
+      information about the \htmlref{Object}{Object} being written.
+   }
+   \sstattributetype{
+      Integer.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Channel
+      }{
+         The default value is zero for a normal Channel.
+      }
+      \sstsubsection{
+         \htmlref{FitsChan}{FitsChan}
+      }{
+         The default value is zero for a FitsChan.
+      }
+      \sstsubsection{
+         \htmlref{XmlChan}{XmlChan}
+      }{
+         The default value is -1 for an XmlChan.
+      }
+      \sstsubsection{
+         \htmlref{StcsChan}{StcsChan}
+      }{
+         The default value is zero for an StcsChan. Set a positive value
+         to cause default values to be included in STC-S descriptions.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          All positive values supplied for this attribute are converted
+         to $+$1 and all negative values are converted to -1.
+      }
+   }
+}
+\sstroutine{
+   Gap(axis)
+}{
+   Interval between linearly spaced major axis values of a Plot
+}{
+   \sstdescription{
+      This attribute controls the appearance of an annotated
+      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
+      the linear interval between the \texttt{"} major\texttt{"}  axis values of a \htmlref{Plot}{Plot}, at
+      which (for example) major tick marks are drawn. It takes a separate
+      value for each physical axis of the Plot so that, for instance,
+      the setting \texttt{"} Gap(2)=3.0\texttt{"}  specifies the difference between adjacent major
+      values along the second axis. The Gap attribute is only used when
+      the LogTicks attribute indicates that the spacing between major axis
+      values is to be linear. If major axis values are logarithmically spaced
+      then the gap is specified using attribute LogGap.
+
+      The Gap value supplied will usually be rounded to the nearest
+      \texttt{"} nice\texttt{"}  value, suitable (e.g.) for generating axis labels, before
+      use. To avoid this \texttt{"} nicing\texttt{"}  you should set an explicit format
+      for the axis using the \htmlref{Format(axis)}{Format(axis)} or \htmlref{Digits/Digits(axis)}{Digits/Digits(axis)}
+      attribute. The default behaviour is for the Plot to generate its
+      own Gap value when required, based on the range of axis values
+      to be represented.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The Gap value should use the same units as are used internally
+         for storing coordinate values on the corresponding axis. For
+         example, with a celestial coordinate system, the Gap value
+         should be in radians, not hours or degrees.
+
+         \sstitem
+          If no axis is specified, (e.g. \texttt{"} Gap\texttt{"}  instead of \texttt{"} Gap(2)\texttt{"} ),
+         then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect the attribute
+         value of all the Plot axes, while a \texttt{"} get\texttt{"}  or \texttt{"} test\texttt{"}  operation
+         will use just the Gap(1) value.
+      }
+   }
+}
+\sstroutine{
+   Grf
+}{
+   Use Grf functions registered through astGrfSet?
+}{
+   \sstdescription{
+      This attribute selects the functions which are used to draw graphics by
+      the \htmlref{Plot}{Plot} class. If it is zero, then the functions in the graphics
+      interface selected at link-time are used (see the \htmlref{ast\_link}{ast\_link} script).
+      Otherwise, functions registered using \htmlref{astGrfSet}{astGrfSet} are used. In this
+      case, if a function is needed which has not been registered,
+      then the function in the graphics interface selected at link-time is
+      used.
+
+      The default is to use the graphics interface
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+      \sstsubsection{
+         \htmlref{Plot3D}{Plot3D}
+      }{
+         The Plot3D class ignores this attributes, assuming a value of
+         zero.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The value of this attribute is not saved when the Plot is written
+         out through a \htmlref{Channel}{Channel} to an external data store. On re-loading such
+         a Plot using \htmlref{astRead}{astRead}, the attribute will be cleared, resulting in the
+         graphics interface selected at link-time being used.
+      }
+   }
+}
+\sstroutine{
+   Grid
+}{
+   Draw grid lines for a Plot?
+}{
+   \sstdescription{
+      This attribute controls the appearance of an annotated
+      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
+      whether grid lines (a grid of curves marking the \texttt{"} major\texttt{"}  values
+      on each axis) are drawn across the plotting area.
+
+      If the Grid value of a \htmlref{Plot}{Plot} is non-zero, then grid lines will be
+      drawn. Otherwise, short tick marks on the axes are used to mark
+      the major axis values.  The default behaviour is to use tick
+      marks if the entire plotting area is filled by valid physical
+      coordinates, but to draw grid lines otherwise.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The spacing between major axis values, which determines the
+         spacing of grid lines, may be set using the \htmlref{Gap(axis)}{Gap(axis)} attribute.
+      }
+   }
+}
+\sstroutine{
+   GrismAlpha
+}{
+   The angle of incidence of the incoming light on the grating surface
+}{
+   \sstdescription{
+      This attribute holds the angle between the incoming light and the
+      normal to the grating surface, in radians. The default value is 0.
+
+      Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap}
+      has no more than one reference. That is, an error is reported if the
+      GrismMap has been cloned, either by including it within another object
+      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
+      \htmlref{astClone}{astClone}
+      function.
+   }
+   \sstattributetype{
+      Double precision.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         GrismMap
+      }{
+         All GrismMaps have this attribute.
+      }
+   }
+}
+\sstroutine{
+   GrismEps
+}{
+   The angle between the normal and the dispersion plane
+}{
+   \sstdescription{
+      This attribute holds the angle (in radians) between the normal to
+      the grating or exit prism face, and the dispersion plane. The
+      dispersion plane is the plane spanned by the incoming and outgoing
+      ray. The default value is 0.0.
+
+      Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap}
+      has no more than one reference. That is, an error is reported if the
+      GrismMap has been cloned, either by including it within another object
+      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
+      \htmlref{astClone}{astClone}
+      function.
+   }
+   \sstattributetype{
+      Double precision.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         GrismMap
+      }{
+         All GrismMaps have this attribute.
+      }
+   }
+}
+\sstroutine{
+   GrismG
+}{
+   The grating ruling density
+}{
+   \sstdescription{
+      This attribute holds the number of grating rulings per unit length.
+      The unit of length used should be consistent with the units used
+      for attributes \htmlref{GrismWaveR}{GrismWaveR} and \htmlref{GrismNRP}{GrismNRP}. The default value is 0.0.
+      (the appropriate value for a pure prism disperser with no grating).
+
+      Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap}
+      has no more than one reference. That is, an error is reported if the
+      GrismMap has been cloned, either by including it within another object
+      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
+      \htmlref{astClone}{astClone}
+      function.
+   }
+   \sstattributetype{
+      Double precision.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         GrismMap
+      }{
+         All GrismMaps have this attribute.
+      }
+   }
+}
+\sstroutine{
+   GrismM
+}{
+   The interference order
+}{
+   \sstdescription{
+      This attribute holds the interference order being considered.
+      The default value is 0.
+
+      Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap}
+      has no more than one reference. That is, an error is reported if the
+      GrismMap has been cloned, either by including it within another object
+      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
+      \htmlref{astClone}{astClone}
+      function.
+   }
+   \sstattributetype{
+      Integer.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         GrismMap
+      }{
+         All GrismMaps have this attribute.
+      }
+   }
+}
+\sstroutine{
+   GrismNR
+}{
+   The refractive index at the reference wavelength
+}{
+   \sstdescription{
+      This attribute holds refractive index of the grism material at the
+      reference wavelength (given by attribute \htmlref{GrismWaveR}{GrismWaveR}). The default
+      value is 1.0.
+
+      Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap}
+      has no more than one reference. That is, an error is reported if the
+      GrismMap has been cloned, either by including it within another object
+      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
+      \htmlref{astClone}{astClone}
+      function.
+   }
+   \sstattributetype{
+      Double precision.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         GrismMap
+      }{
+         All GrismMaps have this attribute.
+      }
+   }
+}
+\sstroutine{
+   GrismNRP
+}{
+   The rate of change of refractive index with wavelength
+}{
+   \sstdescription{
+      This attribute holds the rate of change of the refractive index of the
+      grism material with respect to wavelength at the reference wavelength
+      (given by attribute \htmlref{GrismWaveR}{GrismWaveR}). The default value is 0.0 (the
+      appropriate value for a pure grating disperser with no prism). The
+      units of this attribute should be consistent with those of attributes
+      GrismWaveR and \htmlref{GrismG}{GrismG}.
+
+      Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap}
+      has no more than one reference. That is, an error is reported if the
+      GrismMap has been cloned, either by including it within another object
+      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
+      \htmlref{astClone}{astClone}
+      function.
+   }
+   \sstattributetype{
+      Double precision.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         GrismMap
+      }{
+         All GrismMaps have this attribute.
+      }
+   }
+}
+\sstroutine{
+   GrismTheta
+}{
+   Angle between normal to detector plane and reference ray
+}{
+   \sstdescription{
+      This attribute gives the angle of incidence of light of the
+      reference wavelength (given by attribute \htmlref{GrismWaveR}{GrismWaveR}) onto the
+      detector. Specifically, it holds the angle (in radians) between
+      the normal to the detector plane and an incident ray at the reference
+      wavelength. The default value is 0.0.
+
+      Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap}
+      has no more than one reference. That is, an error is reported if the
+      GrismMap has been cloned, either by including it within another object
+      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
+      \htmlref{astClone}{astClone}
+      function.
+   }
+   \sstattributetype{
+      Double precision.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         GrismMap
+      }{
+         All GrismMaps have this attribute.
+      }
+   }
+}
+\sstroutine{
+   GrismWaveR
+}{
+   The reference wavelength
+}{
+   \sstdescription{
+      This attribute holds reference wavelength. The default value is
+      5000 (Angstrom). The units of this attribute should be consistent with
+      those of attributes \htmlref{GrismNRP}{GrismNRP} and \htmlref{GrismG}{GrismG}.
+
+      Note, the value of this attribute may changed only if the \htmlref{GrismMap}{GrismMap}
+      has no more than one reference. That is, an error is reported if the
+      GrismMap has been cloned, either by including it within another object
+      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
+      \htmlref{astClone}{astClone}
+      function.
+   }
+   \sstattributetype{
+      Double precision.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         GrismMap
+      }{
+         All GrismMaps have this attribute.
+      }
+   }
+}
+\sstroutine{
+   ID
+}{
+   Object identification string
+}{
+   \sstdescription{
+      This attribute contains a string which may be used to identify
+      the \htmlref{Object}{Object} to which it is attached. There is no restriction on
+      the contents of this string, which is not used internally by the
+      AST library, and is simply returned without change when
+      required. The default value is an empty string.
+
+      An identification string can be valuable when, for example,
+      several Objects have been stored in a file (using \htmlref{astWrite}{astWrite}) and
+      are later retrieved (using \htmlref{astRead}{astRead}). Consistent use of the ID
+      attribute allows the retrieved Objects to be identified without
+      depending simply on the order in which they were stored.
+
+      This attribute may also be useful during debugging, to
+      distinguish similar Objects when using \htmlref{astShow}{astShow} to display them.
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         All Objects have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Unlike most other attributes, the value of the ID attribute is
+         not transferred when an Object is copied. Instead, its value is
+         undefined (and therefore defaults to an empty string) in any
+         copy. However, it is retained in any external representation of
+         an Object produced by the astWrite function.
+      }
+   }
+}
+\sstroutine{
+   IF
+}{
+   The intermediate frequency in a dual sideband spectrum
+}{
+   \sstdescription{
+      This attribute specifies the (topocentric) intermediate frequency in
+      a dual sideband spectrum. Its sole use is to determine the local
+      oscillator (LO) frequency (the frequency which marks the boundary
+      between the lower and upper sidebands). The LO frequency is
+      equal to the sum of the centre frequency and the intermediate
+      frequency. Here, the \texttt{"} centre frequency\texttt{"}  is the topocentric
+      frequency in Hz corresponding to the current value of the \htmlref{DSBCentre}{DSBCentre}
+      attribute. The value of the IF attribute may be positive or
+      negative: a positive value results in the LO frequency being above
+      the central frequency, whilst a negative IF value results in the LO
+      frequency being below the central frequency. The sign of the IF
+      attribute value determines the default value for the \htmlref{SideBand}{SideBand}
+      attribute.
+
+      When setting a new value for this attribute, the units in which the
+      frequency value is supplied may be indicated by appending a suitable
+      string to the end of the formatted value. If the units are not
+      specified, then the supplied value is assumed to be in units of GHz.
+      For instance, the following strings all result in an IF of 4 GHz being
+      used: \texttt{"} 4.0\texttt{"} , \texttt{"} 4.0 GHz\texttt{"} , \texttt{"} 4.0E9 Hz\texttt{"} , etc.
+
+      When getting the value of this attribute, the returned value is
+      always in units of GHz. The default value for this attribute is 4 GHz.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{DSBSpecFrame}{DSBSpecFrame}
+      }{
+         All DSBSpecFrames have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Ident
+}{
+   Permanent Object identification string
+}{
+   \sstdescription{
+      This attribute is like the \htmlref{ID}{ID} attribute, in that it contains a
+      string which may be used to identify the \htmlref{Object}{Object} to which it is
+      attached. The only difference between ID and Ident is that Ident
+      is transferred when an Object is copied, but ID is not.
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         All Objects have this attribute.
+      }
+   }
+}
+\sstroutine{
+   ImagFreq
+}{
+   The image sideband equivalent of the rest frequency
+}{
+   \sstdescription{
+      This is a read-only attribute giving the frequency which
+      corresponds to the rest frequency but is in the opposite sideband.
+
+      The value is calculated by first transforming the rest frequency
+      (given by the \htmlref{RestFreq}{RestFreq} attribute) from the standard of rest of the
+      source (given by the \htmlref{SourceVel}{SourceVel} and \htmlref{SourceVRF}{SourceVRF} attributes) to the
+      standard of rest of the observer (i.e. the topocentric standard of
+      rest). The resulting topocentric frequency is assumed to be in the
+      same sideband as the value given for the \htmlref{DSBCentre}{DSBCentre} attribute (the
+      \texttt{"} observed\texttt{"}  sideband), and is transformed to the other sideband (the
+      \texttt{"} image\texttt{"}  sideband). The new frequency is converted back to the standard
+      of rest of the source, and the resulting value is returned as the
+      attribute value, in units of GHz.
+   }
+   \sstattributetype{
+      Floating point, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{DSBSpecFrame}{DSBSpecFrame}
+      }{
+         All DSBSpecFrames have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Indent
+}{
+   Specifies the indentation to use in text produced by a Channel
+}{
+   \sstdescription{
+      This attribute controls the indentation within the output text produced by
+      the \htmlref{astWrite}{astWrite} function.
+      It gives the increase in the indentation for each level in the object
+      heirarchy. If it is set to zero, no indentation will be used. [3]
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{Channel}{Channel}
+      }{
+         The default value is zero for a basic Channel.
+      }
+      \sstsubsection{
+         \htmlref{FitsChan}{FitsChan}
+      }{
+         The FitsChan class ignores this attribute.
+      }
+      \sstsubsection{
+         \htmlref{StcsChan}{StcsChan}
+      }{
+         The default value for an StcsChan is zero, which causes the entire
+         STC-S description is written out by a single invocation of the sink
+         function. The text supplied to the sink function will not contain
+         any linefeed characters, and each pair of adjacent words will be
+         separated by a single space. The text may thus be arbitrarily large
+         and the \htmlref{StcsLength}{StcsLength} attribute is ignored.
+
+         If Indent is non-zero, then the text is written out via multiple
+         calls to the sink function, each call corresponding to a single
+         \texttt{"} line\texttt{"}  of text (although no line feed characters will be inserted
+         by AST). The complete STC-S description is broken into lines so that:
+
+         \sstitemlist{
+
+            \sstitem
+             the line length specified by attribute StcsLength is not exceeded
+
+            \sstitem
+             each sub-phrase (time, space, etc.) starts on a new line
+
+            \sstitem
+             each argument in a compound spatial region starts on a new line
+
+         }
+         If this causes a sub-phrase to extend to two or more lines, then the
+         second and subsequent lines will be indented by three spaces compared
+         to the first line. In addition, lines within a compound spatial region
+         will have extra indentation to highlight the nesting produced by the
+         parentheses. Each new level of nesting will be indented by a further
+         three spaces.
+      }
+      \sstsubsection{
+         \htmlref{XmlChan}{XmlChan}
+      }{
+         The default value for an XmlChan is zero, which results in no
+         linefeeds or indentation strings being added to output text.
+         If any non-zero value is assigned to Indent, then extra linefeed and
+         space characters will be inserted as necessary to ensure that each
+         XML tag starts on a new line, and each tag will be indented by
+         a further 3 spaces to show its depth in the containment hierarchy.
+      }
+   }
+}
+\sstroutine{
+   InternalUnit(axis)
+}{
+   Physical units for unformated axis values
+}{
+   \sstdescription{
+      This read-only attribute contains a textual representation of the
+      physical units used to represent unformatted (i.e. floating point)
+      values on a particular axis of a \htmlref{Frame}{Frame}, typically handled internally
+      within application code. In most cases, the value of the InternalUnit
+      attribute will be the same as Unit attribute (i.e. formatted and
+      unformatted axis values will normally use the same system of units).
+      The main exception to this is the \htmlref{SkyFrame}{SkyFrame} class, which represents
+      unformatted axis values in radians, regardless of the current
+      setting of the Unit attribute.
+   }
+   \sstattributetype{
+      String, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Frame
+      }{
+         All Frames have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          When specifying this attribute by name, it should be
+         subscripted with the number of the Frame axis to which it
+         applies.
+      }
+   }
+}
+\sstroutine{
+   IntraFlag
+}{
+   IntraMap identification string
+}{
+   \sstdescription{
+      This attribute allows an \htmlref{IntraMap}{IntraMap} to be flagged so that it is
+      distinguishable from other IntraMaps. The transformation function
+      associated with the IntraMap may then enquire the value of this
+      attribute and adapt the transformation it provides according to the
+      particular IntraMap involved.
+
+      Although this is a string attribute, it may often be useful to store
+      numerical values here, encoded as a character string, and to use these
+      as data within the transformation function. Note, however, that this
+      mechanism is not suitable for transferring large amounts of data (more
+      than about 1000 characters) to an IntraMap. For that purpose, global
+      variables are recommended, although the IntraFlag value can be used to
+      supplement this approach. The default IntraFlag value is an empty
+      string.
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         IntraMap
+      }{
+         All IntraMaps have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A pair of IntraMaps whose transformations may potentially cancel
+         cannot be simplified to produce a \htmlref{UnitMap}{UnitMap} (e.g. using \htmlref{astSimplify}{astSimplify})
+         unless they have the same IntraFlag values. The test for equality is
+         case-sensitive.
+      }
+   }
+}
+\sstroutine{
+   Invert
+}{
+   Mapping inversion flag
+}{
+   \sstdescription{
+      This attribute controls which one of a \htmlref{Mapping}{Mapping}\texttt{'} s two possible
+      coordinate transformations is considered the \texttt{"} forward\texttt{"}
+      transformation (the other being the \texttt{"} inverse\texttt{"}
+      transformation). If the attribute value is zero (the default),
+      the Mapping\texttt{'} s behaviour will be the same as when it was first
+      created. However, if it is non-zero, its two transformations
+      will be inter-changed, so that the Mapping displays the inverse
+      of its original behaviour.
+
+      Inverting the boolean sense of the Invert attribute will cause
+      the values of a Mapping\texttt{'} s \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes to be
+      interchanged. The values of its \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse}
+      attributes will also be interchanged. This operation may be
+      performed with the \htmlref{astInvert}{astInvert} function.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Mapping
+      }{
+         All Mappings have this attribute.
+      }
+      \sstsubsection{
+         \htmlref{UnitMap}{UnitMap}
+      }{
+         The value of the Invert attribute has no effect on the
+         behaviour of a UnitMap.
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         Inverting the boolean sense of the Invert attribute for a
+         FrameSet will cause its base and current Frames (and its \htmlref{Base}{Base}
+         and \htmlref{Current}{Current} attributes) to be interchanged. This, in turn,
+         may affect other properties and attributes of the FrameSet
+         (such as Nin, Nout, \htmlref{Naxes}{Naxes}, TranForward, TranInverse,
+         etc.). The Invert attribute of a FrameSet is not itself
+         affected by selecting a new base or current \htmlref{Frame}{Frame}.
+      }
+   }
+}
+\sstroutine{
+   Invisible
+}{
+   Draw graphics using invisible ink?
+}{
+   \sstdescription{
+      This attribute controls the appearance of all graphics produced by
+      \htmlref{Plot}{Plot} methods by determining whether graphics should be visible or
+      invisible.
+
+      If the Invisible value of a Plot is non-zero, then all the Plot
+      methods which normally generate graphical output do not do so (you
+      can think of them drawing with \texttt{"} invisible ink\texttt{"} ). Such methods do,
+      however, continue to do all the calculations which would be needed to
+      produce the graphics. In particular, the bounding box enclosing the
+      graphics is still calculated and can be retrieved as normal using
+      \htmlref{astBoundingBox}{astBoundingBox}. The default value is zero, resulting in all methods
+      drawing graphics as normal, using visible ink.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+}
+\sstroutine{
+   IsLatAxis(axis)
+}{
+   Is the specified celestial axis a latitude axis?
+}{
+   \sstdescription{
+      This is a read-only boolean attribute that indicates the nature of
+      the specified axis. The attribute has a non-zero value if the
+      specified axis is a celestial latitude axis (Declination, Galactic
+      latitude, etc), and is zero otherwise.
+   }
+   \sstattributetype{
+      Integer (boolean), read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{SkyFrame}{SkyFrame}
+      }{
+         All SkyFrames have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          When specifying this attribute by name, it should be
+         subscripted with the number of the SkyFrame axis to be tested.
+      }
+   }
+}
+\sstroutine{
+   IsLinear
+}{
+   Is the Mapping linear?
+}{
+   \sstdescription{
+      This attribute indicates whether a \htmlref{Mapping}{Mapping} is an instance of a
+      class that always represents a linear transformation. Note, some
+      Mapping classes can represent linear or non-linear transformations
+      (the \htmlref{MathMap}{MathMap} class for instance). Such classes have a zero value for
+      the IsLinear attribute. Specific instances of such classes can be
+      tested for linearity using the
+      \htmlref{astLinearApprox}{astLinearApprox} function.
+      AST\_LINEARAPPROX routine.
+   }
+   \sstattributetype{
+      Integer (boolean), read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Mapping
+      }{
+         All Mappings have this attribute.
+      }
+      \sstsubsection{
+         \htmlref{CmpMap}{CmpMap}
+      }{
+         The IsLinear value for a CmpMap is determined by the classes
+         of the encapsulated Mappings. For instance, a CmpMap that combines
+         a \htmlref{ZoomMap}{ZoomMap} and a \htmlref{ShiftMap}{ShiftMap} will have a non-zero value for its IsLinear
+         attribute, but a CmpMap that contains a MathMap will have a
+         value of zero for its IsLinear attribute.
+      }
+      \sstsubsection{
+         \htmlref{Frame}{Frame}
+      }{
+         The IsLinear value for a Frame is 1 (since a Frame is equivalent
+         to a \htmlref{UnitMap}{UnitMap}).
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         The IsLinear value for a FrameSet is obtained from the Mapping
+         from the base Frame to the current Frame.
+      }
+   }
+}
+\sstroutine{
+   IsLonAxis(axis)
+}{
+   Is the specified celestial axis a longitude axis?
+}{
+   \sstdescription{
+      This is a read-only boolean attribute that indicates the nature of
+      the specified axis. The attribute has a non-zero value if the
+      specified axis is a celestial longitude axis (Right Ascension, Galactic
+      longitude, etc), and is zero otherwise.
+   }
+   \sstattributetype{
+      Integer (boolean), read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{SkyFrame}{SkyFrame}
+      }{
+         All SkyFrames have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          When specifying this attribute by name, it should be
+         subscripted with the number of the SkyFrame axis to be tested.
+      }
+   }
+}
+\sstroutine{
+   IsSimple
+}{
+   Has the Mapping been simplified?
+}{
+   \sstdescription{
+      This attribute indicates whether a \htmlref{Mapping}{Mapping} has been simplified
+      by the
+      \htmlref{astSimplify}{astSimplify}
+      method. If the IsSimple value is non-zero, then the Mapping has
+      been simplified and so there is nothing to be gained by simplifying
+      it again. Indeed, the
+      astSimplify
+      method will immediately return the Mapping unchanged if the IsSimple
+      attribute indicates that the Mapping has already been simplified.
+   }
+   \sstattributetype{
+      Integer (boolean), read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Mapping
+      }{
+         All Mappings have this attribute.
+      }
+      \sstsubsection{
+         \htmlref{Frame}{Frame}
+      }{
+         All classes of Frame return zero for the IsSimple attribute.
+         This is because changes can be made to a Frame which affect the
+         Mapping represented by the Frame, and so there can be no
+         guarantee that the Mapping may not need re-simplifying. Most
+         non-Frame Mappings, on the other hand, are immutable and so when
+         they are simplified it is certain that they weill remain in a
+         simple state.
+      }
+   }
+}
+\sstroutine{
+   IterInverse
+}{
+   Provide an iterative inverse transformation?
+}{
+   \sstdescription{
+      This attribute indicates whether the inverse transformation of
+      the \htmlref{PolyMap}{PolyMap} should be implemented via an iterative Newton-Raphson
+      approximation that uses the forward transformation to transform
+      candidate input positions until an output position is found which
+      is close to the required output position. By default, an iterative
+      inverse is provided if, and only if, no inverse polynomial was supplied
+      when the PolyMap was constructed.
+
+      The \htmlref{NiterInverse}{NiterInverse} and \htmlref{TolInverse}{TolInverse} attributes provide parameters that
+      control the behaviour of the inverse approximation method.
+
+      The iterative inverse returns AST\_\_BAD axis values at positions
+      for which the inverse transformation is undefined. For instance,
+      if the forward transformation is y = x$*$x, the iterative inverse
+      will return x = AST\_\_BAD at y = -1. If the inverse transformation
+      is multiply defined, the position returned by the iterative inverse
+      will be the position of the solution that is closest to the
+      supplied position. For instance, using the above example, y = x$*$x,
+      the iterative inverse will return x = $+$2 at y = 4, because x = $+$2
+      is the closest solution to 4 (the other solution is x = -2).
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         PolyMap
+      }{
+         All PolyMaps have this attribute.
+      }
+      \sstsubsection{
+         \htmlref{ChebyMap}{ChebyMap}
+      }{
+         The ChebyMap class does not currently provide an option for an
+         iterative inverse, and so the IterInverse value is always zero.
+         Setting or clearing the IterInverse attribute of a ChebyMap has
+         no effect.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The transformation replaced by the iterative algorithm is the
+         transformation from the original PolyMap output space to the
+         original PolyMap input space (i.e. the input and output spaces as
+         defined by the arguments of the PolyMap constructor). This is still
+         the case even if the PolyMap has subsequently been inverted. In
+         other words if a PolyMap is created and then inverted, setting
+         the IterInverse to a non-zero value will replace the forward
+         transformation of the inverted PolyMap (i.e. the inverse
+         transformation of the original PolyMap). It is not possible to
+         replace the other transformation (i.e. from the original PolyMap
+         input space to the original PolyMap output space) with an iterative
+         algorithm.
+
+         \sstitem
+          If a PolyMap that has an iterative inverse transformation is
+         subsequently inverted, the inverted PolyMap will have an iterative
+         forward transformation.
+
+         \sstitem
+          An iterative inverse can only be used if the PolyMap has equal
+         numbers of inputs and outputs, as given by the \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout}
+         attributes. An error will be reported if IterInverse is set non-zero
+         for a PolyMap that does not meet this requirement.
+      }
+   }
+}
+\sstroutine{
+   Iwc
+}{
+   Include a Frame representing FITS-WCS intermediate world coordinates?
+}{
+   \sstdescription{
+      This attribute is a boolean value which is used when a \htmlref{FrameSet}{FrameSet} is
+      read from a \htmlref{FitsChan}{FitsChan} with a foreign FITS encoding (e.g. FITS-WCS) using
+      \htmlref{astRead}{astRead}.
+      If it has a non-zero value then the returned FrameSet will include
+      Frames representing \texttt{"} intermediate world coordinates\texttt{"}  (IWC). These
+      Frames will have \htmlref{Domain}{Domain} name \texttt{"} IWC\texttt{"}  for primary axis descriptions, and
+      \texttt{"} IWCa\texttt{"}  for secondary axis descriptions, where \texttt{"} a\texttt{"}  is replaced by
+      the single alternate axis description character, as used in the
+      FITS-WCS header. The default value for \texttt{"} Iwc\texttt{"}  is zero.
+
+      FITS-WCS paper 1 defines IWC as a Cartesian coordinate system with one
+      axis for each WCS axis, and is the coordinate system produced by the
+      rotation matrix (represented by FITS keyword PCi\_j, CDi\_j, etc).
+      For instance, for a 2-D FITS-WCS header describing projected
+      celestial longitude and latitude, the intermediate world
+      coordinates represent offsets in degrees from the reference point
+      within the plane of projection.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         FitsChan
+      }{
+         All FitsChans have this attribute.
+      }
+   }
+}
+\sstroutine{
+   KeyCase
+}{
+   Are keys case sensitive?
+}{
+   \sstdescription{
+      This attribute is a boolean value which controls how keys are
+      used. If KeyCase is zero, then key strings supplied to any method
+      are automatically converted to upper case before being used. If
+      KeyCase is non-zero (the default), then supplied key strings are
+      used without modification.
+
+      The value of this attribute can only be changed if the \htmlref{KeyMap}{KeyMap} is
+      empty. Its value can be set conveniently when creating the KeyMap.
+      An error will be reported if an attempt is made to change the
+      attribute value when the KeyMap contains any entries.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         KeyMap
+      }{
+         All KeyMaps have this attribute.
+      }
+      \sstsubsection{
+         \htmlref{Table}{Table}
+      }{
+         The Table class over-rides this attribute by forcing it to zero.
+         That is, keys within a Table are always case insensitive.
+      }
+   }
+}
+\sstroutine{
+   KeyError
+}{
+   Report an error when getting the value of a non-existant KeyMap entry?
+}{
+   \sstdescription{
+      This attribute is a boolean value which controls how the
+      astMapGet...
+      functions behave if the requested key is not found in the \htmlref{KeyMap}{KeyMap}.
+      If KeyError is zero (the default), then these functions will return
+      zero
+      but no error will be reported. If KeyError is non-zero, then the
+      same values are returned but an error is also reported.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         KeyMap
+      }{
+         All KeyMaps have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          When setting a new value for KeyError, the supplied value is
+         propagated to any KeyMaps contained within the supplied KeyMap.
+
+         \sstitem
+          When clearing the KeyError attribute, the attribute is also
+         cleared in any KeyMaps contained within the supplied KeyMap.
+      }
+   }
+}
+\sstroutine{
+   LTOffset
+}{
+   The offset from UTC to Local Time, in hours
+}{
+   \sstdescription{
+      This specifies the offset from UTC to Local Time, in hours (fractional
+      hours can be supplied). It is positive for time zones east of Greenwich.
+      AST uses the figure as given, without making any attempt to correct for
+      daylight saving. The default value is zero.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{TimeFrame}{TimeFrame}
+      }{
+         All TimeFrames have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Label(axis)
+}{
+   Axis label
+}{
+   \sstdescription{
+      This attribute specifies a label to be attached to each axis of
+      a \htmlref{Frame}{Frame} when it is represented (e.g.) in graphical output.
+
+      If a Label value has not been set for a Frame axis, then a
+      suitable default is supplied.
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Frame
+      }{
+         The default supplied by the Frame class is the string \texttt{"} \htmlref{Axis}{Axis}
+         $<$n$>$\texttt{"} , where $<$n$>$ is 1, 2, etc. for each successive axis.
+      }
+      \sstsubsection{
+         \htmlref{SkyFrame}{SkyFrame}
+      }{
+         The SkyFrame class re-defines the default Label value
+         (e.g. to \texttt{"} Right ascension\texttt{"}  or \texttt{"} Galactic latitude\texttt{"} ) as
+         appropriate for the particular celestial coordinate system
+         being represented.
+      }
+      \sstsubsection{
+         \htmlref{TimeFrame}{TimeFrame}
+      }{
+         The TimeFrame class re-defines the default Label value as
+         appropriate for the particular time system being represented.
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         The Label attribute of a FrameSet axis is the same as that of
+         its current Frame (as specified by the \htmlref{Current}{Current} attribute).
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Axis labels are intended purely for interpretation by human
+         readers and not by software.
+
+         \sstitem
+          When specifying this attribute by name, it should be
+         subscripted with the number of the Frame axis to which it
+         applies.
+      }
+   }
+}
+\sstroutine{
+   LabelAt(axis)
+}{
+   Where to place numerical labels for a Plot
+}{
+   \sstdescription{
+      This attribute controls the appearance of an annotated
+      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
+      where numerical axis labels and associated tick marks are
+      placed.  It takes a separate value for each physical axis of a
+      \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} LabelAt(2)=10.0\texttt{"}
+      specifies where the numerical labels and tick marks for the
+      second axis should be drawn.
+
+      For each axis, the LabelAt value gives the value on the other
+      axis at which numerical labels and tick marks should be placed
+      (remember that Plots suitable for use with astGrid may only
+      have two axes).  For example, in a celestial (RA,Dec) coordinate
+      system, LabelAt(1) gives a Dec value which defines a line (of
+      constant Dec) along which the numerical RA labels and their
+      associated tick marks will be drawn. Similarly, LabelAt(2) gives
+      the RA value at which the Dec labels and ticks will be drawn.
+
+      The default bahaviour is for the Plot to generate its own
+      position for numerical labels and tick marks.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The LabelAt value should use the same units as are used
+         internally for storing coordinate values on the appropriate
+         axis. For example, with a celestial coordinate system, the
+         LabelAt value should be in radians, not hours or degrees.
+
+         \sstitem
+          Normally, the LabelAt value also determines where the lines
+         representing coordinate axes will be drawn, so that the tick
+         marks will lie on these lines (but also see the DrawAxes
+         attribute).
+
+         \sstitem
+          In some circumstances, numerical labels and tick marks are
+         drawn around the edges of the plotting area (see the \htmlref{Labelling}{Labelling}
+         attribute).  In this case, the value of the LabelAt attribute is
+         ignored.
+      }
+   }
+}
+\sstroutine{
+   LabelUnits(axis)
+}{
+   Use axis unit descriptions in a Plot?
+}{
+   \sstdescription{
+      This attribute controls the appearance of an annotated
+      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
+      whether the descriptive labels drawn for each axis of a \htmlref{Plot}{Plot}
+      should include a description of the units being used on the
+      axis.  It takes a separate value for each physical axis of a
+      Plot so that, for instance, the setting \texttt{"} LabelUnits(2)=1\texttt{"}
+      specifies that a unit description should be included in the
+      label for the second axis.
+
+      If the LabelUnits value of a Plot axis is non-zero, a unit
+      description will be included in the descriptive label for that
+      axis, otherwise it will be omitted.  The default behaviour is to
+      include a unit description unless the current \htmlref{Frame}{Frame} of the Plot
+      is a \htmlref{SkyFrame}{SkyFrame} representing equatorial, ecliptic, galactic or
+      supergalactic coordinates, in which case it is omitted.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The text used for the unit description is obtained from the
+         Plot\texttt{'} s \htmlref{Unit(axis)}{Unit(axis)} attribute.
+
+         \sstitem
+          If no axis is specified, (e.g. \texttt{"} LabelUnits\texttt{"}  instead of
+         \texttt{"} LabelUnits(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect
+         the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or
+         \texttt{"} test\texttt{"}  operation will use just the LabelUnits(1) value.
+
+         \sstitem
+          If the current Frame of the Plot is not a SkyFrame, but includes
+         axes which were extracted from a SkyFrame, then the default behaviour
+         is to include a unit description only for those axes which were not
+         extracted from a SkyFrame.
+      }
+   }
+}
+\sstroutine{
+   LabelUp(axis)
+}{
+   Draw numerical Plot labels upright?
+}{
+   \sstdescription{
+      This attribute controls the appearance of an annotated
+      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
+      whether the numerical labels for each axis of a \htmlref{Plot}{Plot} should be
+      drawn upright or not. It takes a separate value for each
+      physical axis of a Plot so that, for instance, the setting
+      \texttt{"} LabelUp(2)=1\texttt{"}  specifies that numerical labels for the second
+      axis should be drawn upright.
+
+      If the LabelUp value of a Plot axis is non-zero, it causes
+      numerical labels for that axis to be plotted upright (i.e. as
+      normal, horizontal text), otherwise labels are drawn parallel to
+      the axis to which they apply.
+
+      The default is to produce upright labels if the labels are placed
+      around the edge of the plot, and to produce labels that follow the
+      axes if the labels are placed within the interior of the plot (see
+      attribute \htmlref{Labelling}{Labelling}).
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          In some circumstances, numerical labels and tick marks are
+         drawn around the edges of the plotting area (see the Labelling
+         attribute).  In this case, the value of the LabelUp attribute is
+         ignored.
+
+         \sstitem
+          If no axis is specified, (e.g. \texttt{"} LabelUp\texttt{"}  instead of
+         \texttt{"} LabelUp(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect the
+         attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or \texttt{"} test\texttt{"}
+         operation will use just the LabelUp(1) value.
+      }
+   }
+}
+\sstroutine{
+   Labelling
+}{
+   Label and tick placement option for a Plot
+}{
+   \sstdescription{
+      This attribute controls the appearance of an annotated
+      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
+      the strategy for placing numerical labels and tick marks for a \htmlref{Plot}{Plot}.
+
+      If the Labelling value of a Plot is \texttt{"} exterior\texttt{"}  (the default), then
+      numerical labels and their associated tick marks are placed
+      around the edges of the plotting area, if possible. If this is
+      not possible, or if the Labelling value is \texttt{"} interior\texttt{"} , then they
+      are placed along grid lines inside the plotting area.
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The \htmlref{LabelAt(axis)}{LabelAt(axis)} attribute may be used to determine the exact
+         placement of labels and tick marks that are drawn inside the
+         plotting area.
+      }
+   }
+}
+\sstroutine{
+   LatAxis
+}{
+   Index of the latitude axis
+}{
+   \sstdescription{
+      This read-only attribute gives the index (1 or 2) of the latitude
+      axis within the \htmlref{SkyFrame}{SkyFrame} (taking into account any current axis
+      permutations).
+   }
+   \sstattributetype{
+      Integer.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         SkyFrame
+      }{
+         All SkyFrames have this attribute.
+      }
+   }
+}
+\sstroutine{
+   ListSize
+}{
+   Number of points in a PointList
+}{
+   \sstdescription{
+      This is a read-only attribute giving the number of points in a
+      \htmlref{PointList}{PointList}. This value is determined when the PointList is created.
+   }
+   \sstattributetype{
+      Integer, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         PointList
+      }{
+         All PointLists have this attribute.
+      }
+   }
+}
+\sstroutine{
+   LogGap(axis)
+}{
+   Interval between major axis values of a Plot
+}{
+   \sstdescription{
+      This attribute controls the appearance of an annotated
+      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
+      the logarithmic interval between the \texttt{"} major\texttt{"}  axis values of a \htmlref{Plot}{Plot}, at
+      which (for example) major tick marks are drawn. It takes a separate
+      value for each physical axis of the Plot so that, for instance,
+      the setting \texttt{"} LogGap(2)=100.0\texttt{"}  specifies the ratio between adjacent major
+      values along the second axis. The LogGap attribute is only used when
+      the LogTicks attribute indicates that the spacing between major axis
+      values is to be logarithmic. If major axis values are linearly spaced
+      then the gap is specified using attribute Gap.
+
+      The LogGap value supplied will be rounded to the nearest power of 10.
+      The reciprocal of the supplied value may be used if this is necessary
+      to produce usable major axis values. If a zero or negative value is
+      supplied, an error will be reported when the grid is drawn. The default
+      behaviour is for the Plot to generate its own LogGap value when
+      required, based on the range of axis values to be represented.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The LogGap value is a ratio between axis values and is therefore
+         dimensionless.
+
+         \sstitem
+          If no axis is specified, (e.g. \texttt{"} LogGap\texttt{"}  instead of \texttt{"} LogGap(2)\texttt{"} ),
+         then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect the attribute
+         value of all the Plot axes, while a \texttt{"} get\texttt{"}  or \texttt{"} test\texttt{"}  operation
+         will use just the LogGap(1) value.
+      }
+   }
+}
+\sstroutine{
+   LogLabel(axis)
+}{
+   Use exponential format for numerical axis labels?
+}{
+   \sstdescription{
+      This attribute controls the appearance of an annotated
+      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
+      whether the numerical axis labels should be in normal decimal form
+      or should be represented as 10 raised to the appropriate power.
+      That is, an axis value of 1000.0 will be drawn as \texttt{"} 1000.0\texttt{"}  if
+      LogLabel is zero, but as \texttt{"} 10$\wedge$3\texttt{"}  if LogLabel is non-zero. If
+      graphical escape sequences are supported (see attribute \htmlref{Escape}{Escape}),
+      the power in such exponential labels will be drawn as a small
+      superscript instead of using a \texttt{"} $\wedge$\texttt{"}  character to represent
+      exponentiation.
+
+      The default is to produce exponential labels if the major tick
+      marks are logarithmically spaced (see the LogTicks attribute).
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{Plot}{Plot}
+      }{
+         All Plots have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If no axis is specified, (e.g. \texttt{"} LogLabel\texttt{"}  instead of
+         \texttt{"} LogLabel(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect the
+         attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or \texttt{"} test\texttt{"}
+         operation will use just the LogLabel(1) value.
+      }
+   }
+}
+\sstroutine{
+   LogPlot(axis)
+}{
+   Map the plot logarithmically onto the screen?
+}{
+   \sstdescription{
+      This attribute controls the appearance of all graphics produced by
+      the \htmlref{Plot}{Plot}, by determining whether the axes of the plotting surface
+      are mapped logarithmically or linearly onto the base \htmlref{Frame}{Frame} of the
+      \htmlref{FrameSet}{FrameSet} supplied when the Plot was constructed. It takes a separate
+      value for each axis of the graphics coordinate system (i.e. the
+      base Frame in the Plot) so that, for instance, the setting
+      \texttt{"} LogPlot(2)=1\texttt{"}  specifies that the second axis of the graphics
+      coordinate system (usually the vertical axis) should be mapped
+      logarithmically onto the second axis of the base Frame of the
+      FrameSet supplied when the Plot was constructed.
+
+      If the LogPlot value of a Plot axis is non-zero, it causes that
+      axis to be mapped logarithmically, otherwise (the default) the axis
+      is mapped linearly.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The setting of the LogPlot attribute provides the default value
+         for the related LogTicks attribute. By selecting suitable values for
+         LogPlot and LogTicks, it is possible to have tick marks which are evenly
+         spaced in value but which are mapped logarithmically onto the screen
+         (and vice-versa).
+
+         \sstitem
+          An axis may only be mapped logarithmically if the visible part of
+         the axis does not include the value zero. The visible part of the
+         axis is that part which is mapped onto the plotting area, and is
+         measured within the base Frame of the FrameSet which was supplied when
+         the Plot was constructed. Any attempt to set LogPlot to a non-zero value
+         will be ignored (without error) if the visible part of the axis
+         includes the value zero
+
+         \sstitem
+          If no axis is specified, (e.g. \texttt{"} LogPlot\texttt{"}  instead of
+         \texttt{"} LogPlot(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect the
+         attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or \texttt{"} test\texttt{"}
+         operation will use just the LogPlot(1) value.
+      }
+   }
+}
+\sstroutine{
+   LogTicks(axis)
+}{
+   Space the major tick marks logarithmically?
+}{
+   \sstdescription{
+      This attribute controls the appearance of an annotated
+      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
+      whether the major tick marks should be spaced logarithmically or
+      linearly in axis value. It takes a separate value for each physical
+      axis of the \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} LogTicks(2)=1\texttt{"}
+      specifies that the major tick marks on the second axis should be
+      spaced logarithmically.
+
+      If the LogTicks value for a physical axis is non-zero, the major
+      tick marks on that axis will be spaced logarithmically (that is,
+      there will be a constant ratio between the axis values at adjacent
+      major tick marks). An error will be reported if the dynamic range of
+      the axis (the ratio of the largest to smallest displayed axis value)
+      is less than 10.0. If the LogTicks value is zero, the major tick marks
+      will be evenly spaced (that is, there will be a constant difference
+      between the axis values at adjacent major tick marks). The default is
+      to produce logarithmically spaced tick marks if the corresponding
+      LogPlot attribute is non-zero and the ratio of maximum axis value
+      to minimum axis value is 100 or more. If either of these conditions
+      is not met, the default is to produce linearly spaced tick marks.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The setting of the LogTicks attribute does not affect the mapping
+         of the plot onto the screen, which is controlled by attribute LogPlot.
+         By selecting suitable values for LogPlot and LogTicks, it is possible to
+         have tick marks which are evenly spaced in value but which are mapped
+         logarithmically onto the screen (and vica-versa).
+
+         \sstitem
+          An error will be reported when drawing an annotated axis grid if
+         the visible part of the physical axis includes the value zero.
+
+         \sstitem
+          If no axis is specified, (e.g. \texttt{"} LogTicks\texttt{"}  instead of
+         \texttt{"} LogTicks(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect the
+         attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or \texttt{"} test\texttt{"}
+         operation will use just the LogTicks(1) value.
+      }
+   }
+}
+\sstroutine{
+   LonAxis
+}{
+   Index of the longitude axis
+}{
+   \sstdescription{
+      This read-only attribute gives the index (1 or 2) of the longitude
+      axis within the \htmlref{SkyFrame}{SkyFrame} (taking into account any current axis
+      permutations).
+   }
+   \sstattributetype{
+      Integer.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         SkyFrame
+      }{
+         All SkyFrames have this attribute.
+      }
+   }
+}
+\sstroutine{
+   LutEpsilon
+}{
+   The relative error of the values held in the took-up table
+}{
+   \sstdescription{
+      This attribute holds the relative error of the values held in the
+      took-up table. It is used when simplifying a \htmlref{LutMap}{LutMap}, to determine
+      if the LutMap should be considered linear. Setting a larger value
+      makes it more likely that a LutMap will be replaced by a \htmlref{WinMap}{WinMap}
+      (i.e. a linear \htmlref{Mapping}{Mapping}) when simplified.
+
+      The default value is the value of the system constant DBL\_EPSILON
+      (typically around 1e-16 or 2E-16). If the values in the look-up
+      table were derived from single precision data, it may be appropriate
+      to set this attribute to a value around 1E-7.
+
+      Note, the value of this attribute may changed only if the LutMap
+      has no more than one reference. That is, an error is reported if the
+      LutMap has been cloned, either by including it within another object
+      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
+      \htmlref{astClone}{astClone}
+      function.
+   }
+   \sstattributetype{
+      Double precision.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         LutMap
+      }{
+         All LutMaps have this attribute.
+      }
+   }
+}
+\sstroutine{
+   LutInterp
+}{
+   Look-up table interpolation method
+}{
+   \sstdescription{
+      This attribute indicates the method to be used when finding the
+      output value of a \htmlref{LutMap}{LutMap} for an input value part way between two
+      table entries. If it is set to 0 (the default) then linear
+      interpolation is used. Otherwise, nearest neighbour interpolation
+      is used.
+
+      Using nearest neighbour interpolation causes AST\_\_BAD to be returned
+      for any point which falls outside the bounds of the table. Linear
+      interpolation results in an extrapolated value being returned based
+      on the two end entries in the table.
+
+      Note, the value of this attribute may changed only if the LutMap
+      has no more than one reference. That is, an error is reported if the
+      LutMap has been cloned, either by including it within another object
+      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
+      \htmlref{astClone}{astClone}
+      function.
+   }
+   \sstattributetype{
+      Integer.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         LutMap
+      }{
+         All LutMaps have this attribute.
+      }
+   }
+}
+\sstroutine{
+   MajTickLen(axis)
+}{
+   Length of major tick marks for a Plot
+}{
+   \sstdescription{
+      This attribute controls the appearance of an annotated
+      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
+      the length of the major tick marks drawn on the axes of a \htmlref{Plot}{Plot}.
+      It takes a separate value for each physical axis of the Plot so
+      that, for instance, the setting \texttt{"} MajTickLen(2)=0\texttt{"}  specifies the
+      length of the major tick marks drawn on the second axis.
+
+      The MajTickLen value should be given as a fraction of the
+      minimum dimension of the plotting area. Negative values cause
+      major tick marks to be placed on the outside of the
+      corresponding grid line or axis (but subject to any clipping
+      imposed by the underlying graphics system), while positive
+      values cause them to be placed on the inside.
+
+      The default behaviour depends on whether a coordinate grid is
+      drawn inside the plotting area (see the \htmlref{Grid}{Grid} attribute). If so,
+      the default MajTickLen value is zero (so that major ticks are
+      not drawn), otherwise the default is $+$0.015.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If no axis is specified, (e.g. \texttt{"} MajTickLen\texttt{"}  instead of
+         \texttt{"} MajTickLen(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect
+         the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or \texttt{"} test\texttt{"}
+         operation will use just the MajTickLen(1) value.
+      }
+   }
+}
+\sstroutine{
+   MapLocked
+}{
+   Prevent new entries being added to a KeyMap?
+}{
+   \sstdescription{
+      If this boolean attribute is set to
+      a non-zero value,
+      an error will be reported if an attempt is made to add a new entry
+      to the \htmlref{KeyMap}{KeyMap}. Note, the value associated with any existing entries
+      can still be changed, but no new entries can be stored in the KeyMap.
+      The default value
+      (zero)
+      allows new entries to be added to the KeyMap.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         KeyMap
+      }{
+         All KeyMaps have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          When setting a new value for MapLocked, the supplied value is
+         propagated to any KeyMaps contained within the supplied KeyMap.
+
+         \sstitem
+          When clearing the MapLocked attribute, the attribute is also
+         cleared in any KeyMaps contained within the supplied KeyMap.
+      }
+   }
+}
+\sstroutine{
+   MatchEnd
+}{
+   Match trailing axes?
+}{
+   \sstdescription{
+      This attribute is a boolean value which controls how a \htmlref{Frame}{Frame}
+      behaves when it is used (by \htmlref{astFindFrame}{astFindFrame}) as a template to match
+      another (target) Frame. It applies only in the case where a
+      match occurs between template and target Frames with different
+      numbers of axes.
+
+      If the MatchEnd value of the template Frame is zero, then the
+      axes which occur first in the target Frame will be matched and
+      any trailing axes (in either the target or template) will be
+      disregarded. If it is non-zero, the final axes in each Frame
+      will be matched and any un-matched leading axes will be
+      disregarded instead.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Frame
+      }{
+         The default MatchEnd value for a Frame is zero, so that
+         trailing axes are disregarded.
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         The MatchEnd attribute of a FrameSet is the same as that of
+         its current Frame (as specified by the \htmlref{Current}{Current} attribute).
+      }
+   }
+}
+\sstroutine{
+   MaxAxes
+}{
+   Maximum number of Frame axes to match
+}{
+   \sstdescription{
+      This attribute controls how a \htmlref{Frame}{Frame} behaves when it is used (by
+      \htmlref{astFindFrame}{astFindFrame}) as a template to match another (target) Frame. It
+      specifies the maximum number of axes that the target Frame may
+      have in order to match the template.
+
+      Normally, this value will equal the number of Frame axes, so
+      that a template Frame will only match another Frame with the
+      same number of axes as itself. By setting a different value,
+      however, the matching process may be used to identify Frames
+      with specified numbers of axes.
+   }
+   \sstattributetype{
+      Integer.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Frame
+      }{
+         The default MaxAxes value for a Frame is equal to the number
+         of Frame axes (\htmlref{Naxes}{Naxes} attribute).
+      }
+      \sstsubsection{
+         \htmlref{CmpFrame}{CmpFrame}
+      }{
+         The MaxAxes attribute of a CmpFrame defaults to a large number
+         (1000000) which is much larger than any likely number of axes in
+         a Frame. Combined with the \htmlref{MinAxes}{MinAxes} default of zero (for a
+         CmpFrame), this means that the default behaviour for a CmpFrame
+         is to match any target Frame that consists of a subset of the
+         axes in the template CmpFrame. To change this so that a CmpFrame
+         will only match Frames that have the same number of axes, you
+         should set the CmpFrame MaxAxes and MinAxes attributes to the
+         number of axes in the CmpFrame.
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         The MaxAxes attribute of a FrameSet is the same as that of
+         its current Frame (as specified by the \htmlref{Current}{Current} attribute).
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          When setting a MaxAxes value, the value of the MinAxes
+         attribute may also be silently changed so that it remains
+         consistent with (i.e. does not exceed) the new value. The
+         default MaxAxes value may also be reduced to remain consistent
+         with the MinAxes value.
+
+         \sstitem
+          If a template Frame is used to match a target with a different
+         number of axes, the \htmlref{MatchEnd}{MatchEnd} attribute of the template is used
+         to determine how the individual axes of each Frame should match.
+      }
+   }
+}
+\sstroutine{
+   MeshSize
+}{
+   Number of points used to represent the boundary of a Region
+}{
+   \sstdescription{
+      This attribute controls how many points are used when creating a
+      mesh of points covering the boundary or volume of a \htmlref{Region}{Region}. Such a
+      mesh is returned by the
+      \htmlref{astGetRegionMesh}{astGetRegionMesh}
+      method. The boundary mesh is also used when testing for overlap
+      between two Regions: each point in the bomdary mesh of the first
+      Region is checked to see if it is inside or outside the second Region.
+      Thus, the reliability of the overlap check depends on the value assigned
+      to this attribute. If the value used is very low, it is possible for
+      overlaps to go unnoticed. High values produce more reliable results, but
+      can result in the overlap test being very slow. The default value is 200
+      for two dimensional Regions and 2000 for three or more dimensional
+      Regions (this attribute is not used for 1-dimensional regions since the
+      boundary of a simple 1-d Region can only ever have two points). A
+      value of five is used if the supplied value is less than five.
+   }
+   \sstattributetype{
+      Integer.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Region
+      }{
+         All Regions have this attribute.
+      }
+      \sstsubsection{
+         \htmlref{CmpRegion}{CmpRegion}
+      }{
+         The default MeshSize for a CmpRegion is the MeshSize of its
+         first component Region.
+      }
+      \sstsubsection{
+         \htmlref{Stc}{Stc}
+      }{
+         The default MeshSize for an Stc is the MeshSize of its
+         encapsulated Region.
+      }
+   }
+}
+\sstroutine{
+   MinAxes
+}{
+   Minimum number of Frame axes to match
+}{
+   \sstdescription{
+      This attribute controls how a \htmlref{Frame}{Frame} behaves when it is used (by
+      \htmlref{astFindFrame}{astFindFrame}) as a template to match another (target) Frame. It
+      specifies the minimum number of axes that the target Frame may
+      have in order to match the template.
+
+      Normally, this value will equal the number of Frame axes, so
+      that a template Frame will only match another Frame with the
+      same number of axes as itself. By setting a different value,
+      however, the matching process may be used to identify Frames
+      with specified numbers of axes.
+   }
+   \sstattributetype{
+      Integer.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Frame
+      }{
+         The default MinAxes value for a Frame is equal to the number
+         of Frame axes (\htmlref{Naxes}{Naxes} attribute).
+      }
+      \sstsubsection{
+         \htmlref{CmpFrame}{CmpFrame}
+      }{
+         The MinAxes attribute of a CmpFrame defaults to zero. Combined
+         with the \htmlref{MaxAxes}{MaxAxes} default of 1000000 (for a CmpFrame), this means
+         that the default behaviour for a CmpFrame is to match any target
+         Frame that consists of a subset of the axes in the template
+         CmpFrame. To change this so that a CmpFrame will only match Frames
+         that have the same number of axes, you should set the CmpFrame
+         MinAxes and MaxAxes attributes to the number of axes in the CmpFrame.
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         The MinAxes attribute of a FrameSet is the same as that of
+         its current Frame (as specified by the \htmlref{Current}{Current} attribute).
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          When setting a MinAxes value, the value of the MaxAxes
+         attribute may also be silently changed so that it remains
+         consistent with (i.e. is not less than) the new value. The
+         default MinAxes value may also be reduced to remain consistent
+         with the MaxAxes value.
+
+         \sstitem
+          If a template Frame is used to match a target with a different
+         number of axes, the \htmlref{MatchEnd}{MatchEnd} attribute of the template is used
+         to determine how the individual axes of each Frame should match.
+      }
+   }
+}
+\sstroutine{
+   MinTick(axis)
+}{
+   Density of minor tick marks for a Plot
+}{
+   \sstdescription{
+      This attribute controls the appearance of an annotated
+      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
+      the density of minor tick marks which appear between the major
+      axis values of a \htmlref{Plot}{Plot}. It takes a separate value for each
+      physical axis of a Plot so that, for instance, the setting
+      \texttt{"} MinTick(2)=2\texttt{"}  specifies the density of minor tick marks along
+      the second axis.
+
+      The value supplied should be the number of minor divisions
+      required between each pair of major axis values, this being one
+      more than the number of minor tick marks to be drawn.  By
+      default, a value is chosen that depends on the gap between major
+      axis values and the nature of the axis.
+   }
+   \sstattributetype{
+      Integer.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If no axis is specified, (e.g. \texttt{"} MinTick\texttt{"}  instead of
+         \texttt{"} MinTick(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect
+         the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or
+         \texttt{"} test\texttt{"}  operation will use just the MinTick(1) value.
+      }
+   }
+}
+\sstroutine{
+   MinTickLen(axis)
+}{
+   Length of minor tick marks for a Plot
+}{
+   \sstdescription{
+      This attribute controls the appearance of an annotated
+      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
+      the length of the minor tick marks drawn on the axes of a \htmlref{Plot}{Plot}.
+      It takes a separate value for each physical axis of the Plot so
+      that, for instance, the setting \texttt{"} MinTickLen(2)=0\texttt{"}  specifies the
+      length of the minor tick marks drawn on the second axis.
+
+      The MinTickLen value should be given as a fraction of the
+      minimum dimension of the plotting area. Negative values cause
+      minor tick marks to be placed on the outside of the
+      corresponding grid line or axis (but subject to any clipping
+      imposed by the underlying graphics system), while positive
+      values cause them to be placed on the inside.
+
+      The default value is $+$0.007.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The number of minor tick marks drawn is determined by the
+         Plot\texttt{'} s \htmlref{MinTick(axis)}{MinTick(axis)} attribute.
+
+         \sstitem
+          If no axis is specified, (e.g. \texttt{"} MinTickLen\texttt{"}  instead of
+         \texttt{"} MinTickLen(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect
+         the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or \texttt{"} test\texttt{"}
+         operation will use just the MinTickLen(1) value.
+      }
+   }
+}
+\sstroutine{
+   NatLat
+}{
+   Native latitude of the reference point of a FITS-WCS projection
+}{
+   \sstdescription{
+      This attribute gives the latitude of the reference point of the
+      FITS-WCS projection implemented by a \htmlref{WcsMap}{WcsMap}. The value is in
+      radians in the \texttt{"} native spherical\texttt{"}  coordinate system. This value is
+      fixed for most projections, for instance it is PI/2 (90 degrees)
+      for all zenithal projections. For some projections (e.g. the conics)
+      the value is not fixed, but is specified by parameter one on the
+      latitude axis.
+
+      FITS-WCS paper II introduces the concept of a \texttt{"} fiducial point\texttt{"}
+      which is logical distinct from the projection reference point.
+      It is easy to confuse the use of these two points. The fiducial
+      point is the point which has celestial coordinates given by the
+      CRVAL FITS keywords. The native spherical coordinates for this point
+      default to the values of the NatLat and \htmlref{NatLon}{NatLon}, but these defaults
+      mey be over-ridden by values stored in the PVi\_j keywords. Put
+      another way, the CRVAL keywords will by default give the celestial
+      coordinates of the projection reference point, but may refer to
+      some other point if alternative native longitude and latitude values
+      are provided through the PVi\_j keywords.
+
+      The NatLat attribute is read-only.
+   }
+   \sstattributetype{
+      Floating point, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         WcsMap
+      }{
+         All WcsMaps have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A default value of AST\_\_BAD is used if no latitude value is available.
+      }
+   }
+}
+\sstroutine{
+   NatLon
+}{
+   Native longitude of the reference point of a FITS-WCS projection
+}{
+   \sstdescription{
+      This attribute gives the longitude of the reference point of the
+      FITS-WCS projection implemented by a \htmlref{WcsMap}{WcsMap}. The value is in
+      radians in the \texttt{"} native spherical\texttt{"}  coordinate system, and will
+      usually be zero. See the description of attribute \htmlref{NatLat}{NatLat} for further
+      information.
+
+      The NatLon attribute is read-only.
+   }
+   \sstattributetype{
+      Floating point, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         WcsMap
+      }{
+         All WcsMaps have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Naxes
+}{
+   Number of Frame axes
+}{
+   \sstdescription{
+      This is a read-only attribute giving the number of axes in a
+      \htmlref{Frame}{Frame} (i.e. the number of dimensions of the coordinate space
+      which the Frame describes). This value is determined when the
+      Frame is created.
+   }
+   \sstattributetype{
+      Integer, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Frame
+      }{
+         All Frames have this attribute.
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         The Naxes attribute of a FrameSet is the same as that of its
+         current Frame (as specified by the \htmlref{Current}{Current} attribute).
+      }
+      \sstsubsection{
+         \htmlref{CmpFrame}{CmpFrame}
+      }{
+         The Naxes attribute of a CmpFrame is equal to the sum of the
+         Naxes values of its two component Frames.
+      }
+   }
+}
+\sstroutine{
+   Ncard
+}{
+   Number of FITS header cards in a FitsChan
+}{
+   \sstdescription{
+      This attribute gives the total number of FITS header cards
+      stored in a \htmlref{FitsChan}{FitsChan}. It is updated as cards are added or
+      deleted.
+   }
+   \sstattributetype{
+      Integer, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         FitsChan
+      }{
+         All FitsChans have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Ncolumn
+}{
+   The number of columns in the table
+}{
+   \sstdescription{
+      This attribute holds the number of columns currently in the table. Columns
+      are added and removed using the
+      \htmlref{astAddColumn}{astAddColumn} and \htmlref{astRemoveColumn}{astRemoveColumn}
+      functions.
+   }
+   \sstattributetype{
+      Integer, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{Table}{Table}
+      }{
+         All Tables have this attribute.
+      }
+   }
+}
+\sstroutine{
+   NegLon
+}{
+   Display negative longitude values?
+}{
+   \sstdescription{
+      This attribute is a boolean value which controls how longitude values
+      are normalized for display by \htmlref{astNorm}{astNorm}.
+
+      If the NegLon attribute is zero, then normalized
+      longitude values will be in the range zero to 2.pi. If NegLon is
+      non-zero, then normalized longitude values will be in the range -pi
+      to pi.
+
+      The default value depends on the current value of the \htmlref{SkyRefIs}{SkyRefIs}
+      attribute, If SkyRefIs has a value of \texttt{"} Origin\texttt{"} , then the default for
+      NegLon is one, otherwise the default is zero.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{SkyFrame}{SkyFrame}
+      }{
+         All SkyFrames have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Negated
+}{
+   Region negation flag
+}{
+   \sstdescription{
+      This attribute controls whether a \htmlref{Region}{Region} represents the \texttt{"} inside\texttt{"}  or
+      the \texttt{"} outside\texttt{"}  of the area which was supplied when the Region was
+      created. If the attribute value is zero (the default), the Region
+      represents the inside of the original area. However, if it is non-zero,
+      it represents the outside of the original area. The value of this
+      attribute may be toggled using the
+      \htmlref{astNegate}{astNegate} function.
+
+      Note, whether the boundary is considered to be inside the Region or
+      not is controlled by the \htmlref{Closed}{Closed} attribute. Changing the value of
+      the Negated attribute does not change the value of the Closed attribute.
+      Thus, if Region is closed, then the boundary of the Region will be
+      inside the Region, whatever the setting of the Negated attribute.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Region
+      }{
+         All Regions have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Nframe
+}{
+   Number of Frames in a FrameSet
+}{
+   \sstdescription{
+      This attribute gives the number of Frames in a \htmlref{FrameSet}{FrameSet}. This
+      value will change as Frames are added or removed, but will
+      always be at least one.
+   }
+   \sstattributetype{
+      Integer, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         FrameSet
+      }{
+         All FrameSets have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Nin
+}{
+   Number of input coordinates for a Mapping
+}{
+   \sstdescription{
+      This attribute gives the number of coordinate values required to
+      specify an input point for a \htmlref{Mapping}{Mapping} (i.e. the number of
+      dimensions of the space in which the Mapping\texttt{'} s input points
+      reside).
+   }
+   \sstattributetype{
+      Integer, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Mapping
+      }{
+         All Mappings have this attribute.
+      }
+      \sstsubsection{
+         \htmlref{CmpMap}{CmpMap}
+      }{
+         If a CmpMap\texttt{'} s component Mappings are joined in series, then
+         its Nin attribute is equal to the Nin attribute of the first
+         component (or to the \htmlref{Nout}{Nout} attribute of the second component
+         if the the CmpMap\texttt{'} s \htmlref{Invert}{Invert} attribute is non-zero).
+
+         If a CmpMap\texttt{'} s component Mappings are joined in parallel, then
+         its Nin attribute is given by the sum of the Nin attributes
+         of each component (or to the sum of their Nout attributes if
+         the CmpMap\texttt{'} s Invert attribute is non-zero).
+      }
+      \sstsubsection{
+         \htmlref{Frame}{Frame}
+      }{
+         The Nin attribute for a Frame is always equal to the number
+         of Frame axes (\htmlref{Naxes}{Naxes} attribute).
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         The Nin attribute of a FrameSet is equal to the number of
+         axes (Naxes attribute) of its base Frame (as specified by the
+         FrameSet\texttt{'} s \htmlref{Base}{Base} attribute). The Nin attribute value may
+         therefore change if a new base Frame is selected.
+      }
+   }
+}
+\sstroutine{
+   NiterInverse
+}{
+   Maximum number of iterations for the iterative inverse transformation
+}{
+   \sstdescription{
+      This attribute controls the iterative inverse transformation
+      used if the \htmlref{IterInverse}{IterInverse} attribute is non-zero.
+
+      Its value gives the maximum number of iterations of the
+      Newton-Raphson algorithm to be used for each transformed position.
+      The default value is 4. See also attribute \htmlref{TolInverse}{TolInverse}.
+   }
+   \sstattributetype{
+      Integer.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{PolyMap}{PolyMap}
+      }{
+         All PolyMaps have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Nkey
+}{
+   Number of unique FITS keywords in a FitsChan
+}{
+   \sstdescription{
+      This attribute gives the total number of unique FITS keywords
+      stored in a \htmlref{FitsChan}{FitsChan}. It is updated as cards are added or
+      deleted. If no keyword occurrs more than once in the FitsChan, the
+      \htmlref{Ncard}{Ncard} and Nkey attributes will be equal. If any keyword occurrs
+      more than once, the Nkey attribute value will be smaller than
+      the Ncard attribute value.
+   }
+   \sstattributetype{
+      Integer, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         FitsChan
+      }{
+         All FitsChans have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Nobject
+}{
+   Number of Objects in class
+}{
+   \sstdescription{
+      This attribute gives the total number of Objects currently in
+      existence in the same class as the \htmlref{Object}{Object} whose attribute value
+      is requested. This count does not include Objects which belong
+      to derived (more specialised) classes.
+
+      This attribute is mainly intended for debugging. It can be used
+      to detect whether Objects which should have been deleted have,
+      in fact, been deleted.
+   }
+   \sstattributetype{
+      Integer, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         All Objects have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Norm(axis)
+}{
+   Specifies the plane upon which a Plot3D draws text and markers
+}{
+   \sstdescription{
+      This attribute controls the appearance of text and markers drawn
+      by a \htmlref{Plot3D}{Plot3D}. It specifies the orientation of the plane upon which
+      text and markers will be drawn by all subsequent invocations of the
+      \htmlref{astText}{astText} and \htmlref{astMark}{astMark} functions.
+
+      When setting or getting the Norm attribute, the attribute name must
+      be qualified by an axis index in the range 1 to 3. The 3 elements of
+      the Norm attribute are together interpreted as a vector in 3D graphics
+      coordinates that is normal to the plane upon which text and marks
+      should be drawn. When testing or clearing the attribute, the axis
+      index is optional. If no index is supplied, then clearing the Norm
+      attribute will clear all three elements, and testing the Norm attribute
+      will return a non-zero value if any of the three elements are set.
+
+      The default value is 1.0 for each of the 3 elements. The length of
+      the vector is insignificant, but an error will be reported when
+      attempting to draw text or markers if the vector has zero length.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{Plot}{Plot}
+      }{
+         All Plot3Ds have this attribute.
+      }
+   }
+}
+\sstroutine{
+   NormUnit(axis)
+}{
+   Normalised physical units for formatted axis values
+}{
+   \sstdescription{
+      The value of this read-only attribute is derived from the current
+      value of the Unit attribute. It will represent an equivalent system
+      of units to the Unit attribute, but will potentially be simplified.
+      For instance, if Unit is set to \texttt{"} s$*$(m/s)\texttt{"} , the NormUnit value will
+      be \texttt{"} m\texttt{"} . If no simplification can be performed, the value of the
+      NormUnit attribute will equal that of the Unit attribute.
+   }
+   \sstattributetype{
+      String, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{Frame}{Frame}
+      }{
+         All Frames have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          When specifying this attribute by name, it should be
+         subscripted with the number of the Frame axis to which it
+         applies.
+      }
+   }
+}
+\sstroutine{
+   Nout
+}{
+   Number of output coordinates for a Mapping
+}{
+   \sstdescription{
+      This attribute gives the number of coordinate values generated
+      by a \htmlref{Mapping}{Mapping} to specify each output point (i.e. the number of
+      dimensions of the space in which the Mapping\texttt{'} s output points
+      reside).
+   }
+   \sstattributetype{
+      Integer, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Mapping
+      }{
+         All Mappings have this attribute.
+      }
+      \sstsubsection{
+         \htmlref{CmpMap}{CmpMap}
+      }{
+         If a CmpMap\texttt{'} s component Mappings are joined in series, then
+         its Nout attribute is equal to the Nout attribute of the
+         second component (or to the \htmlref{Nin}{Nin} attribute of the first
+         component if the the CmpMap\texttt{'} s \htmlref{Invert}{Invert} attribute is non-zero).
+
+         If a CmpMap\texttt{'} s component Mappings are joined in parallel, then
+         its Nout attribute is given by the sum of the Nout attributes
+         of each component (or to the sum of their Nin attributes if
+         the CmpMap\texttt{'} s Invert attribute is non-zero).
+      }
+      \sstsubsection{
+         \htmlref{Frame}{Frame}
+      }{
+         The Nout attribute for a Frame is always equal to the number
+         of Frame axes (\htmlref{Naxes}{Naxes} attribute).
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         The Nout attribute of a FrameSet is equal to the number of
+         FrameSet axes (Naxes attribute) which, in turn, is equal to
+         the Naxes attribute of the FrameSet\texttt{'} s current Frame (as
+         specified by the \htmlref{Current}{Current} attribute). The Nout attribute value
+         may therefore change if a new current Frame is selected.
+      }
+   }
+}
+\sstroutine{
+   Nparameter
+}{
+   The number of global parameters in the table
+}{
+   \sstdescription{
+      This attribute holds the number of global parameters currently in the table.
+      Parameters are added and removed using the
+      \htmlref{astAddParameter}{astAddParameter} and \htmlref{astRemoveParameter}{astRemoveParameter}
+      functions.
+   }
+   \sstattributetype{
+      Integer, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{Table}{Table}
+      }{
+         All Tables have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Nrow
+}{
+   The number of rows in the table
+}{
+   \sstdescription{
+      This attribute holds the index of the last row to which any
+      contents have been added using any of the
+      astMapPut...
+      AST\_MAPPUT...
+      functions. The first row has index 1.
+   }
+   \sstattributetype{
+      Integer, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{Table}{Table}
+      }{
+         All Tables have this attribute.
+      }
+   }
+}
+\sstroutine{
+   NumLab(axis)
+}{
+   Draw numerical axis labels for a Plot?
+}{
+   \sstdescription{
+      This attribute controls the appearance of an annotated
+      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
+      whether labels should be drawn to represent the numerical values
+      along each axis of a \htmlref{Plot}{Plot}. It takes a separate value for each
+      physical axis of a Plot so that, for instance, the setting
+      \texttt{"} NumLab(2)=1\texttt{"}  specifies that numerical labels should be drawn
+      for the second axis.
+
+      If the NumLab value of a Plot axis is non-zero (the default),
+      then numerical labels will be drawn for that axis, otherwise
+      they will be omitted.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The drawing of associated descriptive axis labels for a Plot
+         (describing the quantity being plotted along each axis) is
+         controlled by the \htmlref{TextLab(axis)}{TextLab(axis)} attribute.
+
+         \sstitem
+          If no axis is specified, (e.g. \texttt{"} NumLab\texttt{"}  instead of
+         \texttt{"} NumLab(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect the
+         attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or \texttt{"} test\texttt{"}
+         operation will use just the NumLab(1) value.
+      }
+   }
+}
+\sstroutine{
+   NumLabGap(axis)
+}{
+   Spacing of numerical labels for a Plot
+}{
+   \sstdescription{
+      This attribute controls the appearance of an annotated
+      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
+      where numerical axis labels are placed relative to the axes they
+      describe.  It takes a separate value for each physical axis of a
+      \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} NumLabGap(2)=-0.01\texttt{"}
+      specifies where the numerical label for the second axis should
+      be drawn.
+
+      For each axis, the NumLabGap value gives the spacing between the
+      axis line (or edge of the plotting area, if appropriate) and the
+      nearest edge of the corresponding numerical axis
+      labels. Positive values cause the descriptive label to be placed
+      on the opposite side of the line to the default tick marks,
+      while negative values cause it to be placed on the same side.
+
+      The NumLabGap value should be given as a fraction of the minimum
+      dimension of the plotting area, the default value being $+$0.01.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If no axis is specified, (e.g. \texttt{"} NumLabGap\texttt{"}  instead of
+         \texttt{"} NumLabGap(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect
+         the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or
+         \texttt{"} test\texttt{"}  operation will use just the NumLabGap(1) value.
+      }
+   }
+}
+\sstroutine{
+   ObjSize
+}{
+   The in-memory size of the Object
+}{
+   \sstdescription{
+      This attribute gives the total number of bytes of memory used by
+      the \htmlref{Object}{Object}. This includes any Objects which are encapsulated within
+      the supplied Object.
+   }
+   \sstattributetype{
+      Integer, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         All Objects have this attribute.
+      }
+   }
+}
+\sstroutine{
+   ObsAlt
+}{
+   The geodetic altitude of the observer
+}{
+   \sstdescription{
+      This attribute specifies the geodetic altitude of the observer, in
+      metres, relative to the IAU 1976 reference ellipsoid. The basic \htmlref{Frame}{Frame}
+      class makes no use of this attribute, but specialised subclasses of
+      Frame may use it. For instance, the \htmlref{SpecFrame}{SpecFrame}, \htmlref{SkyFrame}{SkyFrame} and \htmlref{TimeFrame}{TimeFrame}
+      classes use it. The default value is zero.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Frame
+      }{
+         All Frames have this attribute.
+      }
+      \sstsubsection{
+         SpecFrame
+      }{
+         Together with the \htmlref{ObsLon}{ObsLon}, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes,
+         it defines the Doppler shift introduced by the observers diurnal
+         motion around the earths axis, which is needed when converting to
+         or from the topocentric standard of rest. The maximum velocity
+         error which can be caused by an incorrect value is 0.5 km/s. The
+         default value for the attribute is zero.
+      }
+      \sstsubsection{
+         TimeFrame
+      }{
+         Together with the ObsLon attribute, it is used when converting
+         between certain time scales (TDB, TCB, LMST, LAST)
+      }
+   }
+}
+\sstroutine{
+   ObsLat
+}{
+   The geodetic latitude of the observer
+}{
+   \sstdescription{
+      This attribute specifies the geodetic latitude of the observer, in
+      degrees, relative to the IAU 1976 reference ellipsoid. The basic \htmlref{Frame}{Frame}
+      class makes no use of this attribute, but specialised subclasses of
+      Frame may use it. For instance, the \htmlref{SpecFrame}{SpecFrame}, \htmlref{SkyFrame}{SkyFrame} and \htmlref{TimeFrame}{TimeFrame}
+      classes use it. The default value is zero.
+
+      The value is stored internally in radians, but is converted to and
+      from a degrees string for access. Some example input formats are:
+      \texttt{"} 22:19:23.2\texttt{"} , \texttt{"} 22 19 23.2\texttt{"} , \texttt{"} 22:19.387\texttt{"} , \texttt{"} 22.32311\texttt{"} , \texttt{"} N22.32311\texttt{"} ,
+      \texttt{"} -45.6\texttt{"} , \texttt{"} S45.6\texttt{"} . As indicated, the sign of the latitude can
+      optionally be indicated using characters \texttt{"} N\texttt{"}  and \texttt{"} S\texttt{"}  in place of the
+      usual \texttt{"} $+$\texttt{"}  and \texttt{"} -\texttt{"} . When converting the stored value to a string, the
+      format \texttt{"} [s]dd:mm:ss.ss\texttt{"}  is used, when \texttt{"} [s]\texttt{"}  is \texttt{"} N\texttt{"}  or \texttt{"} S\texttt{"} .
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Frame
+      }{
+         All Frames have this attribute.
+      }
+      \sstsubsection{
+         SpecFrame
+      }{
+         Together with the \htmlref{ObsLon}{ObsLon}, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes,
+         it defines the Doppler shift introduced by the observers diurnal
+         motion around the earths axis, which is needed when converting to
+         or from the topocentric standard of rest. The maximum velocity
+         error which can be caused by an incorrect value is 0.5 km/s. The
+         default value for the attribute is zero.
+      }
+      \sstsubsection{
+         TimeFrame
+      }{
+         Together with the ObsLon attribute, it is used when converting
+         between certain time scales (TDB, TCB, LMST, LAST)
+      }
+   }
+}
+\sstroutine{
+   ObsLon
+}{
+   The geodetic longitude of the observer
+}{
+   \sstdescription{
+      This attribute specifies the geodetic (or equivalently, geocentric)
+      longitude of the observer, in degrees, measured positive eastwards.
+      See also attribute \htmlref{ObsLat}{ObsLat}. The basic \htmlref{Frame}{Frame} class makes no use of this
+      attribute, but specialised subclasses of Frame may use it. For instance,
+      the \htmlref{SpecFrame}{SpecFrame}, \htmlref{SkyFrame}{SkyFrame} and \htmlref{TimeFrame}{TimeFrame} classes use it. The default value
+      is zero.
+
+      The value is stored internally in radians, but is converted to and
+      from a degrees string for access. Some example input formats are:
+      \texttt{"} 155:19:23.2\texttt{"} , \texttt{"} 155 19 23.2\texttt{"} , \texttt{"} 155:19.387\texttt{"} , \texttt{"} 155.32311\texttt{"} , \texttt{"} E155.32311\texttt{"} ,
+      \texttt{"} -204.67689\texttt{"} , \texttt{"} W204.67689\texttt{"} . As indicated, the sign of the longitude can
+      optionally be indicated using characters \texttt{"} E\texttt{"}  and \texttt{"} W\texttt{"}  in place of the
+      usual \texttt{"} $+$\texttt{"}  and \texttt{"} -\texttt{"} . When converting the stored value to a string, the
+      format \texttt{"} [s]ddd:mm:ss.ss\texttt{"}  is used, when \texttt{"} [s]\texttt{"}  is \texttt{"} E\texttt{"}  or \texttt{"} W\texttt{"}  and the
+      numerical value is chosen to be less than 180 degrees.
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Frame
+      }{
+         All Frames have this attribute.
+      }
+      \sstsubsection{
+         SpecFrame
+      }{
+         Together with the ObsLon, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes,
+         it defines the Doppler shift introduced by the observers diurnal
+         motion around the earths axis, which is needed when converting to
+         or from the topocentric standard of rest. The maximum velocity
+         error which can be caused by an incorrect value is 0.5 km/s. The
+         default value for the attribute is zero.
+      }
+      \sstsubsection{
+         TimeFrame
+      }{
+         Together with the ObsLon attribute, it is used when converting
+         between certain time scales (TDB, TCB, LMST, LAST)
+      }
+   }
+}
+\sstroutine{
+   PVMax(i)
+}{
+   Maximum number of FITS-WCS projection parameters
+}{
+   \sstdescription{
+      This attribute specifies the largest legal index for a PV projection
+      parameter attached to a specified axis of the \htmlref{WcsMap}{WcsMap} (i.e. the
+      largest legal value for \texttt{"} m\texttt{"}  when accessing the \texttt{"} \htmlref{PVi\_m}{PVi\_m}\texttt{"}  attribute).
+      The axis index is specified by i, and should be in the range 1 to 99.
+      The value for each axis is determined by the projection type specified
+      when the WcsMap
+      is first created using \htmlref{astWcsMap}{astWcsMap} and cannot subsequently be
+      changed.
+   }
+   \sstattributetype{
+      Integer, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         WcsMap
+      }{
+         All WcsMaps have this attribute.
+      }
+   }
+}
+\sstroutine{
+   PVi\_m
+}{
+   FITS-WCS projection parameters
+}{
+   \sstdescription{
+      This attribute specifies the projection parameter values to be
+      used by a \htmlref{WcsMap}{WcsMap} when implementing a FITS-WCS sky projection.
+      Each PV attribute name should include two integers, i and m,
+      separated by an underscore. The axis index is specified
+      by i, and should be in the range 1 to 99. The parameter number
+      is specified by m, and should be in the range 0 to 99. For
+      example, \texttt{"} PV2\_1=45.0\texttt{"}  would specify a value for projection
+      parameter 1 of axis 2 in a WcsMap.
+
+      These projection parameters correspond exactly to the values
+      stored using the FITS-WCS keywords \texttt{"} PV1\_1\texttt{"} , \texttt{"} PV1\_2\texttt{"} , etc. This
+      means that projection parameters which correspond to angles must
+      be given in degrees (despite the fact that the angular
+      coordinates and other attributes used by a WcsMap are in
+      radians).
+
+      The set of projection parameters used by a WcsMap depends on the
+      type of projection, which is determined by its \htmlref{WcsType}{WcsType}
+      parameter.  Most projections either do not require projection
+      parameters, or use parameters 1 and 2 associated with the latitude
+      axis. You should consult the FITS-WCS paper for details.
+
+      Some projection parameters have default values (as defined in
+      the FITS-WCS paper) which apply if no explicit value is given.
+      You may omit setting a value for these \texttt{"} optional\texttt{"}  parameters and the
+      default will apply. Some projection parameters, however, have no
+      default and a value must be explicitly supplied.  This is most
+      conveniently
+      done using the \texttt{"} options\texttt{"}  argument of \htmlref{astWcsMap}{astWcsMap} (q.v.) when a WcsMap
+      is first created. An error will result when a WcsMap is used to
+      transform coordinates if any of its required projection
+      parameters has not been set and lacks a default value.
+
+      A \texttt{"} get\texttt{"}  operation for a parameter which has not been assigned a value
+      will return the default value defined in the FITS-WCS paper, or
+      AST\_\_BAD if the paper indicates that the parameter has no default.
+      A default value of zero is returned for parameters which are not
+      accessed by the projection.
+
+      Note, the FITS-WCS paper reserves parameters 1 and 2 on the longitude
+      axis to hold the native longitude and latitude of the fiducial
+      point of the projection, in degrees. The default values for these
+      parameters are determined by the projection type. The AST-specific
+      TPN projection does not use this convention - all projection
+      parameters for both axes are used to represent polynomical correction
+      terms, and the native longitude and latitude at the fiducial point may
+      not be changed from the default values of zero and 90 degrees.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         WcsMap
+      }{
+         All WcsMaps have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The value of this attribute may changed only if the WcsMap
+         has no more than one reference. That is, an error is reported if the
+         WcsMap has been cloned, either by including it within another object
+         such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
+         \htmlref{astClone}{astClone}
+         function.
+
+         \sstitem
+          If the projection parameter values given for a WcsMap do not
+         satisfy all the required constraints (as defined in the FITS-WCS
+         paper), then an error will result when the WcsMap is used to
+         transform coordinates.
+      }
+   }
+}
+\sstroutine{
+   PcdCen(axis)
+}{
+   Centre coordinates of pincushion/barrel distortion
+}{
+   \sstdescription{
+      This attribute specifies the centre of the pincushion/barrel
+      distortion implemented by a \htmlref{PcdMap}{PcdMap}. It takes a separate value for
+      each axis of the PcdMap so that, for instance, the settings
+      \texttt{"} PcdCen(1)=345.0,PcdCen(2)=-104.4\texttt{"}  specify that the pincushion
+      distortion is centred at positions of 345.0 and -104.4 on axes 1 and 2
+      respectively. This attribute is set when a PcdMap is created, but may
+      later be modified. If the attribute is cleared, the default value for
+      both axes is zero.
+
+      Note, the value of this attribute may changed only if the PcdMap
+      has no more than one reference. That is, an error is reported if the
+      PcdMap has been cloned, either by including it within another object
+      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
+      \htmlref{astClone}{astClone}
+      function.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         PcdMap
+      }{
+         All PcdMaps have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If no axis is specified, (e.g. \texttt{"} PcdCen\texttt{"}  instead of
+         \texttt{"} PcdCen(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect
+         the attribute value of both axes, while a \texttt{"} get\texttt{"}  or \texttt{"} test\texttt{"}
+         operation will use just the PcdCen(1) value.
+      }
+   }
+}
+\sstroutine{
+   Permute
+}{
+   Permute axis order?
+}{
+   \sstdescription{
+      This attribute is a boolean value which controls how a \htmlref{Frame}{Frame}
+      behaves when it is used (by \htmlref{astFindFrame}{astFindFrame}) as a template to match
+      another (target) Frame. It specifies whether the axis order of
+      the target Frame may be permuted in order to obtain a match.
+
+      If the template\texttt{'} s Permute value is zero, it will match a target
+      only if it can do so without changing the order of its
+      axes. Otherwise, it will attempt to permute the target\texttt{'} s axes as
+      necessary.
+
+      The default value is 1, so that axis permutation will be attempted.
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Frame
+      }{
+         All Frames have this attribute. However, the Frame class
+         effectively ignores this attribute and behaves as if it has
+         the value 1. This is because the axes of a basic Frame are
+         not distinguishable and will always match any other Frame
+         whatever their order.
+      }
+      \sstsubsection{
+         \htmlref{SkyFrame}{SkyFrame}
+      }{
+         Unlike a basic Frame, the SkyFrame class makes use of this
+         attribute.
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         The Permute attribute of a FrameSet is the same as that of
+         its current Frame (as specified by the \htmlref{Current}{Current} attribute).
+      }
+   }
+}
+\sstroutine{
+   PolarLong
+}{
+   The longitude value to assign to either pole
+}{
+   \sstdescription{
+      This attribute holds the longitude value, in radians, to be
+      returned when a Cartesian position corresponding to either the north
+      or south pole is transformed into spherical coordinates. The
+      default value is zero.
+
+      Note, the value of this attribute may changed only if the \htmlref{SphMap}{SphMap}
+      has no more than one reference. That is, an error is reported if the
+      SphMap has been cloned, either by including it within another object
+      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
+      \htmlref{astClone}{astClone}
+      function.
+   }
+   \sstattributetype{
+      Double precision.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         SphMap
+      }{
+         All SphMaps have this attribute.
+      }
+   }
+}
+\sstroutine{
+   PolyTan
+}{
+   Use PVi\_m keywords to define distorted TAN projection?
+}{
+   \sstdescription{
+      This attribute is a boolean value which specifies how FITS \texttt{"} TAN\texttt{"}
+      projections should be treated when reading a \htmlref{FrameSet}{FrameSet} from a foreign
+      encoded FITS header. If zero, the projection is assumed to conform
+      to the published FITS-WCS standard. If positive, the convention
+      for a distorted TAN projection included in an early draft version
+      of FITS-WCS paper II are assumed. In this convention the
+      coefficients of a polynomial distortion to be applied to
+      intermediate world coordinates are specified by the \htmlref{PVi\_m}{PVi\_m} keywords.
+      This convention was removed from the paper before publication and so
+      does not form part of the standard. Indeed, it is incompatible with
+      the published standard because it re-defines the meaning of the
+      first five PVi\_m keywords on the longitude axis, which are reserved
+      by the published standard for other purposes. However, this
+      scheme has now been added to the registry of FITS conventions
+      (http://fits.gsfc.nasa.gov/registry/tpvwcs.html) and headers
+      that use this convention are created by the SCAMP utility
+      (http://www.astromatic.net/software/scamp) and the Dark Energy
+      Camera at NOAO.
+
+      The default value for the PolyTan attribute is -1. A negative
+      values causes the used convention to depend on the contents
+      of the \htmlref{FitsChan}{FitsChan}. If the FitsChan contains any PVi\_m keywords for
+      the latitude axis, or if it contains PVi\_m keywords for the
+      longitude axis with \texttt{"} m\texttt{"}  greater than 4, then the distorted TAN
+      convention is used. Otherwise, the standard convention is used.
+   }
+   \sstattributetype{
+      Integer.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         FitsChan
+      }{
+         All FitsChans have this attribute.
+      }
+   }
+}
+\sstroutine{
+   PreserveAxes
+}{
+   Preserve axes?
+}{
+   \sstdescription{
+      This attribute controls how a \htmlref{Frame}{Frame} behaves when it is used (by
+      \htmlref{astFindFrame}{astFindFrame}) as a template to match another (target) Frame. It
+      determines which axes appear (and in what order) in the \texttt{"} result\texttt{"}
+      Frame produced.
+
+      If PreserveAxes is zero in the template Frame, then the result
+      Frame will have the same number (and order) of axes as the
+      template. If it is non-zero, however, the axes of the target
+      Frame will be preserved, so that the result Frame will have the
+      same number (and order) of axes as the target.
+
+      The default value is zero, so that target axes are not preserved
+      and the result Frame resembles the template.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Frame
+      }{
+         All Frames have this attribute.
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         The PreserveAxes attribute of a FrameSet is the same as that
+         of its current Frame (as specified by the \htmlref{Current}{Current} attribute).
+      }
+   }
+}
+\sstroutine{
+   ProjP(m)
+}{
+   FITS-WCS projection parameters
+}{
+   \sstdescription{
+      This attribute provides aliases for the PV attributes, which
+      specifies the projection parameter values to be used by a \htmlref{WcsMap}{WcsMap}
+      when implementing a FITS-WCS sky projection. ProjP is retained for
+      compatibility with previous versions of FITS-WCS and AST. New
+      applications should use the PV attibute instead.
+
+      Attributes ProjP(0) to ProjP(9) correspond to attributes PV$<$axlat$>$\_0
+      to PV$<$axlat$>$\_9, where $<$axlat$>$ is replaced by the index of the
+      latitude axis (given by attribute WcsAxis(2)). See PV for further
+      details.
+
+      Note, the value of this attribute may changed only if the WcsMap
+      has no more than one reference. That is, an error is reported if the
+      WcsMap has been cloned, either by including it within another object
+      such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet} or by calling the
+      \htmlref{astClone}{astClone}
+      function.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         WcsMap
+      }{
+         All WcsMaps have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Projection
+}{
+   Sky projection description
+}{
+   \sstdescription{
+      This attribute provides a place to store a description of the
+      type of sky projection used when a \htmlref{SkyFrame}{SkyFrame} is attached to a
+      2-dimensional object, such as an image or plotting surface. For
+      example, typical values might be \texttt{"} orthographic\texttt{"} , \texttt{"} Hammer-Aitoff\texttt{"}
+      or \texttt{"} cylindrical equal area\texttt{"} .
+
+      The Projection value is purely descriptive and does not affect
+      the celestial coordinate system represented by the SkyFrame in
+      any way. If it is set to a non-blank string, the description
+      provided may be used when forming the default value for the
+      SkyFrame\texttt{'} s \htmlref{Title}{Title} attribute (so that typically it will appear in
+      graphical output, for instance). The default value is an empty
+      string.
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         SkyFrame
+      }{
+         All SkyFrames have this attribute.
+      }
+   }
+}
+\sstroutine{
+   RefCount
+}{
+   Count of active Object pointers
+}{
+   \sstdescription{
+      This attribute gives the number of active pointers associated
+      with an \htmlref{Object}{Object}. It is modified whenever pointers are created or
+      annulled (by \htmlref{astClone}{astClone}, \htmlref{astAnnul}{astAnnul} or \htmlref{astEnd}{astEnd} for example). The count
+      includes the initial pointer issued when the Object was created.
+
+      If the reference count for an Object falls to zero as the result
+      of annulling a pointer to it, then the Object will be deleted.
+   }
+   \sstattributetype{
+      Integer, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         All Objects have this attribute.
+      }
+   }
+}
+\sstroutine{
+   RefDec
+}{
+   The declination of the reference point
+}{
+   \sstdescription{
+      This attribute specifies the FK5 J2000.0 declination of a reference
+      point on the sky. See the description of attribute \htmlref{RefRA}{RefRA} for details.
+      The default RefDec is \texttt{"} 0:0:0\texttt{"} .
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{SpecFrame}{SpecFrame}
+      }{
+         All SpecFrames have this attribute.
+      }
+   }
+}
+\sstroutine{
+   RefRA
+}{
+   The right ascension of the reference point
+}{
+   \sstdescription{
+      This attribute, together with the \htmlref{RefDec}{RefDec} attribute, specifies the FK5
+      J2000.0 coordinates of a reference point on the sky. For 1-dimensional
+      spectra, this should normally be the position of the source. For
+      spectral data with spatial coverage (spectral cubes, etc), this should
+      be close to centre of the spatial coverage. It is used to define the
+      correction for Doppler shift to be applied when using the
+      \htmlref{astFindFrame}{astFindFrame} or \htmlref{astConvert}{astConvert}
+      method to convert between different standards of rest.
+
+      The \htmlref{SpecFrame}{SpecFrame} class assumes this velocity correction is spatially
+      invariant. If a single SpecFrame is used (for instance, as a
+      component of a \htmlref{CmpFrame}{CmpFrame}) to describe spectral values at different
+      points on the sky, then it is assumes that the doppler shift at any
+      spatial position is the same as at the reference position. The
+      maximum velocity error introduced by this assumption is of the order
+      of V$*$SIN(FOV), where FOV is the angular field of view, and V is the
+      relative velocity of the two standards of rest. As an example, when
+      correcting from the observers rest frame (i.e. the topocentric rest
+      frame) to the kinematic local standard of rest the maximum value of V
+      is about 20 km/s, so for 5 arc-minute field of view the maximum velocity
+      error introduced by the correction will be about 0.03 km/s. As another
+      example, the maximum error when correcting from the observers rest frame
+      to the local group is about 5 km/s over a 1 degree field of view.
+
+      The RefRA and RefDec attributes are stored internally in radians, but
+      are converted to and from a string for access. The format \texttt{"} hh:mm:ss.ss\texttt{"}
+      is used for RefRA, and \texttt{"} dd:mm:ss.s\texttt{"}  is used for RefDec. The methods
+      \htmlref{astSetRefPos}{astSetRefPos} and \htmlref{astGetRefPos}{astGetRefPos} may be used to access the values of
+      these attributes directly as unformatted values in radians.
+
+      The default for RefRA is \texttt{"} 0:0:0\texttt{"} .
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         SpecFrame
+      }{
+         All SpecFrames have this attribute.
+      }
+   }
+}
+\sstroutine{
+   RegionClass
+}{
+   The AST class name of the Region encapsulated within an Stc
+}{
+   \sstdescription{
+      This is a read-only attribute giving the AST class name of the
+      \htmlref{Region}{Region} encapsulated within an \htmlref{Stc}{Stc} (that is, the class of the Region
+      which was supplied when the Stc was created).
+   }
+   \sstattributetype{
+      String, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Stc
+      }{
+         All Stc objects this attribute.
+      }
+   }
+}
+\sstroutine{
+   Report
+}{
+   Report transformed coordinates?
+}{
+   \sstdescription{
+      This attribute controls whether coordinate values are reported
+      whenever a \htmlref{Mapping}{Mapping} is used to transform a set of points. If its
+      value is zero (the default), no report is made. However, if it
+      is non-zero, the coordinates of each point are reported (both
+      before and after transformation) by writing them to standard
+      output.
+
+      This attribute is provided as an aid to debugging, and to avoid
+      having to report values explicitly in simple programs.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Mapping
+      }{
+         All Mappings have this attribute.
+      }
+      \sstsubsection{
+         \htmlref{CmpMap}{CmpMap}
+      }{
+         When applied to a compound Mapping (CmpMap), only the Report
+         attribute of the CmpMap, and not those of its component
+         Mappings, is used.  Coordinate information is never reported
+         for the component Mappings individually, only for the
+         complete CmpMap.
+      }
+      \sstsubsection{
+         \htmlref{Frame}{Frame}
+      }{
+         When applied to any Frame, the formatting capabilities of the
+         Frame (as provided by the \htmlref{astFormat}{astFormat} function) will be used to
+         format the reported coordinates.
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         When applied to any FrameSet, the formatting capabilities of
+         the base and current Frames will be used (as above) to
+         individually format the input and output coordinates, as
+         appropriate. The Report attribute of a FrameSet is not itself
+         affected by selecting a new base or current Frame, but the
+         resulting formatting capabilities may be.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Unlike most other attributes, the value of the Report
+         attribute is not transferred when a Mapping is copied. Instead,
+         its value is undefined (and therefore defaults to zero) in any
+         copy. Similarly, it becomes undefined in any external
+         representation of a Mapping produced by the \htmlref{astWrite}{astWrite} function.
+      }
+   }
+}
+\sstroutine{
+   ReportLevel
+}{
+   Determines which read/write conditions are reported
+}{
+   \sstdescription{
+      This attribute determines which, if any, of the conditions that occur
+      whilst reading or writing an \htmlref{Object}{Object} should be reported. These
+      conditions will generate either a fatal error or a warning, as
+      determined by attribute \htmlref{Strict}{Strict}. ReportLevel can take any of the
+      following values:
+
+      0 - Do not report any conditions.
+
+      1 - \htmlref{Report}{Report} only conditions where significant information content has been
+      changed. For instance, an unsupported time-scale has been replaced by a
+      supported near-equivalent time-scale. Another example is if a basic
+      \htmlref{Channel}{Channel} unexpected encounters data items that may have been introduced
+      by later versions of AST.
+
+      2 - Report the above, and in addition report significant default
+      values. For instance, if no time-scale was specified when reading an
+      Object from an external data source, report the default time-scale
+      that is being used.
+
+      3 - Report the above, and in addition report any other potentially
+      interesting conditions that have no significant effect on the
+      conversion. For instance, report if a time-scale of \texttt{"} TT\texttt{"}
+      (terrestrial time) is used in place of \texttt{"} ET\texttt{"}  (ephemeris time). This
+      change has no signficiant effect because ET is the predecessor of,
+      and is continuous with, TT. Synonyms such as \texttt{"} IAT\texttt{"}  and \texttt{"} TAI\texttt{"}  are
+      another example.
+
+      The default value is 1. Note, there are many other conditions that
+      can occur whilst reading or writing an Object that completely
+      prevent the conversion taking place. Such conditions will always
+      generate errors, irrespective of the ReportLevel and Strict attributes.
+   }
+   \sstattributetype{
+      Integer.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Channel
+      }{
+         All Channels have this attribute.
+      }
+      \sstsubsection{
+         \htmlref{FitsChan}{FitsChan}
+      }{
+         All the conditions selected by the FitsChan \htmlref{Warnings}{Warnings} attribute are
+         reported at level 1.
+      }
+   }
+}
+\sstroutine{
+   RestFreq
+}{
+   The rest frequency
+}{
+   \sstdescription{
+      This attribute specifies the frequency corresponding to zero
+      velocity. It is used when converting between between velocity-based
+      coordinate systems and and other coordinate systems (such as frequency,
+      wavelength, energy, etc). The default value is 1.0E5 GHz.
+
+      When setting a new value for this attribute, the new value can be
+      supplied either directly as a frequency, or indirectly as a wavelength
+      or energy, in which case the supplied value is converted to a frequency
+      before being stored. The nature of the supplied value is indicated by
+      appending text to the end of the numerical value indicating the units in
+      which the value is supplied. If the units are not specified, then the
+      supplied value is assumed to be a frequency in units of GHz. If the
+      supplied unit is a unit of frequency, the supplied value is assumed to
+      be a frequency in the given units. If the supplied unit is a unit of
+      length, the supplied value is assumed to be a (vacuum) wavelength. If
+      the supplied unit is a unit of energy, the supplied value is assumed to
+      be an energy. For instance, the following strings all result in
+      a rest frequency of around 1.4E14 Hz being used: \texttt{"} 1.4E5\texttt{"} , \texttt{"} 1.4E14 Hz\texttt{"} ,
+      \texttt{"} 1.4E14 s$*$$*$-1\texttt{"} , \texttt{"} 1.4E5 GHz\texttt{"} , \texttt{"} 2.14E-6 m\texttt{"} , \texttt{"} 21400 Angstrom\texttt{"} , \texttt{"} 9.28E-20 J\texttt{"} ,
+      \texttt{"} 9.28E-13 erg\texttt{"} , \texttt{"} 0.58 eV\texttt{"} , etc.
+
+      When getting the value of this attribute, the returned value is
+      always a frequency in units of GHz.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{SpecFrame}{SpecFrame}
+      }{
+         All SpecFrames have this attribute.
+      }
+   }
+}
+\sstroutine{
+   RootCorner
+}{
+   Specifies which edges of the 3D box should be annotated
+}{
+   \sstdescription{
+      This attribute controls the appearance of an annotated
+      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
+      which edges of the cube enclosing the 3D graphics space are used
+      for displaying numerical and descriptive axis labels. The attribute
+      value identifies one of the eight corners of the cube within
+      which graphics are being drawn (i.e. the cube specified by the
+      \texttt{"} graphbox\texttt{"}  parameter when \htmlref{astPlot3D}{astPlot3D}
+      was called tp create the \htmlref{Plot3D}{Plot3D}). \htmlref{Axis}{Axis} labels and tick marks will
+      be placed on the three cube edges that meet at the given corner.
+
+      The attribute value should consist of three character, each of
+      which must be either \texttt{"} U\texttt{"}  or \texttt{"} L\texttt{"} . The first character in the string
+      specifies the position of the corner on the first graphics axis.
+      If the character is \texttt{"} U\texttt{"}  then the corner is at the upper bound on the
+      first graphics axis. If it is \texttt{"} L\texttt{"} , then the corner is at the lower
+      bound on the first axis. Likewise, the second and third characters
+      in the string specify the location of the corner on the second and
+      third graphics axes.
+
+      For instance, corner \texttt{"} LLL\texttt{"}  is the corner that is at the lower bound
+      on all three graphics axes, and corner \texttt{"} ULU\texttt{"}  is at the upper bound
+      on axes 1 and 3 but at the lower bound on axis 2.
+
+      The default value is \texttt{"} LLL\texttt{"} .
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot3D
+      }{
+         All Plot3Ds have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Seed
+}{
+   Random number seed for a MathMap
+}{
+   \sstdescription{
+      This attribute, which may take any integer value, determines the
+      sequence of random numbers produced by the random number functions in
+      \htmlref{MathMap}{MathMap} expressions. It is set to an unpredictable default value when
+      a MathMap is created, so that by default each MathMap uses a different
+      set of random numbers.
+
+      If required, you may set this Seed attribute to a value of your
+      choosing in order to produce repeatable behaviour from the random
+      number functions. You may also enquire the Seed value (e.g. if an
+      initially unpredictable value has been used) and then use it to
+      reproduce the resulting sequence of random numbers, either from the
+      same MathMap or from another one.
+
+      Clearing the Seed attribute gives it a new unpredictable default
+      value.
+   }
+   \sstattributetype{
+      Integer.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         MathMap
+      }{
+         All MathMaps have this attribute.
+      }
+   }
+}
+\sstroutine{
+   SideBand
+}{
+   Indicates which sideband a dual sideband spectrum represents
+}{
+   \sstdescription{
+      This attribute indicates whether the \htmlref{DSBSpecFrame}{DSBSpecFrame} currently
+      represents its lower or upper sideband, or an offset from the local
+      oscillator frequency. When querying the current value, the returned
+      string is always one of \texttt{"} usb\texttt{"}  (for upper sideband), \texttt{"} lsb\texttt{"}  (for lower
+      sideband), or \texttt{"} lo\texttt{"}  (for offset from the local oscillator frequency).
+      When setting a new value, any of the strings \texttt{"} lsb\texttt{"} , \texttt{"} usb\texttt{"} , \texttt{"} observed\texttt{"} ,
+      \texttt{"} image\texttt{"}  or \texttt{"} lo\texttt{"}  may be supplied (case insensitive). The \texttt{"} observed\texttt{"}
+      sideband is which ever sideband (upper or lower) contains the central
+      spectral position given by attribute \htmlref{DSBCentre}{DSBCentre}, and the \texttt{"} image\texttt{"}
+      sideband is the other sideband. It is the sign of the \htmlref{IF}{IF} attribute
+      which determines if the observed sideband is the upper or lower
+      sideband. The default value for SideBand is the observed sideband.
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         DSBSpecFrame
+      }{
+         All DSBSpecFrames have this attribute.
+      }
+   }
+}
+\sstroutine{
+   SimpFI
+}{
+   Forward-inverse MathMap pairs simplify?
+}{
+   \sstdescription{
+      This attribute should be set to a non-zero value if applying a
+      \htmlref{MathMap}{MathMap}\texttt{'} s forward transformation, followed immediately by the matching
+      inverse transformation will always restore the original set of
+      coordinates. It indicates that AST may replace such a sequence of
+      operations by an identity \htmlref{Mapping}{Mapping} (a \htmlref{UnitMap}{UnitMap}) if it is encountered
+      while simplifying a compound Mapping (e.g. using \htmlref{astSimplify}{astSimplify}).
+
+      By default, the SimpFI attribute is zero, so that AST will not perform
+      this simplification unless you have set SimpFI to indicate that it is
+      safe to do so.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         MathMap
+      }{
+         All MathMaps have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          For simplification to occur, the two MathMaps must be in series and
+         be identical (with textually identical transformation
+         functions). Functional equivalence is not sufficient.
+
+         \sstitem
+          The consent of both MathMaps is required before simplification can
+         take place. If either has a SimpFI value of zero, then simplification
+         will not occur.
+
+         \sstitem
+          The SimpFI attribute controls simplification only in the case where
+         a MathMap\texttt{'} s forward transformation is followed by the matching inverse
+         transformation. It does not apply if an inverse transformation is
+         followed by a forward transformation. This latter case is controlled
+         by the \htmlref{SimpIF}{SimpIF} attribute.
+
+         \sstitem
+          The \texttt{"} forward\texttt{"}  and \texttt{"} inverse\texttt{"}  transformations referred to are those
+         defined when the MathMap is created (corresponding to the \texttt{"} fwd\texttt{"}  and
+         \texttt{"} inv\texttt{"}  parameters of its constructor function). If the MathMap is
+         inverted (i.e. its \htmlref{Invert}{Invert} attribute is non-zero), then the role of the
+         SimpFI and SimpIF attributes will be interchanged.
+      }
+   }
+}
+\sstroutine{
+   SimpIF
+}{
+   Inverse-forward MathMap pairs simplify?
+}{
+   \sstdescription{
+      This attribute should be set to a non-zero value if applying a
+      \htmlref{MathMap}{MathMap}\texttt{'} s inverse transformation, followed immediately by the matching
+      forward transformation will always restore the original set of
+      coordinates. It indicates that AST may replace such a sequence of
+      operations by an identity \htmlref{Mapping}{Mapping} (a \htmlref{UnitMap}{UnitMap}) if it is encountered
+      while simplifying a compound Mapping (e.g. using \htmlref{astSimplify}{astSimplify}).
+
+      By default, the SimpIF attribute is zero, so that AST will not perform
+      this simplification unless you have set SimpIF to indicate that it is
+      safe to do so.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         MathMap
+      }{
+         All MathMaps have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          For simplification to occur, the two MathMaps must be in series and
+         be identical (with textually identical transformation
+         functions). Functional equivalence is not sufficient.
+
+         \sstitem
+          The consent of both MathMaps is required before simplification can
+         take place. If either has a SimpIF value of zero, then simplification
+         will not occur.
+
+         \sstitem
+          The SimpIF attribute controls simplification only in the case where
+         a MathMap\texttt{'} s inverse transformation is followed by the matching forward
+         transformation. It does not apply if a forward transformation is
+         followed by an inverse transformation. This latter case is controlled
+         by the \htmlref{SimpFI}{SimpFI} attribute.
+
+         \sstitem
+          The \texttt{"} forward\texttt{"}  and \texttt{"} inverse\texttt{"}  transformations referred to are those
+         defined when the MathMap is created (corresponding to the \texttt{"} fwd\texttt{"}  and
+         \texttt{"} inv\texttt{"}  parameters of its constructor function). If the MathMap is
+         inverted (i.e. its \htmlref{Invert}{Invert} attribute is non-zero), then the role of the
+         SimpFI and SimpIF attributes will be interchanged.
+      }
+   }
+}
+\sstroutine{
+   SimpVertices
+}{
+   Simplify a Polygon by transforming its vertices?
+}{
+   \sstdescription{
+      This attribute controls the behaviour of the
+      \htmlref{astSimplify}{astSimplify}
+      method when applied to a \htmlref{Polygon}{Polygon}. The simplified Polygon is created
+      by transforming the vertices from the \htmlref{Frame}{Frame} in which the Polygon
+      was originally defined into the Frame currently represented by the
+      Polygon. If SimpVertices is non-zero (the default) then this
+      simplified Polygon is returned without further checks. If SimpVertices
+      is zero, a check is made that the edges of the new Polygon do not
+      depart significantly from the edges of the original Polygon (as
+      determined by the uncertainty associated with the Polygon). This
+      could occur, for instance, if the \htmlref{Mapping}{Mapping} frrm the original to the
+      current Frame is highly non-linear. If this check fails, the
+      original unsimplified Polygon is returned without change.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Polygon
+      }{
+         All Polygons have this attribute.
+      }
+   }
+}
+\sstroutine{
+   SinkFile
+}{
+   Output file to which to data should be written
+}{
+   \sstdescription{
+      This attribute specifies the name of a file to which the \htmlref{Channel}{Channel}
+      should write data. If specified it is used in preference to any sink
+      function specified when the Channel was created.
+
+      Assigning a new value to this attribute will cause any previously
+      opened SinkFile to be closed. The first subsequent call to
+      \htmlref{astWrite}{astWrite}
+      will attempt to open the new file (an error will be reported if the
+      file cannot be opened), and write data to it. All subsequent call to
+      astWrite
+      will write data to the new file, until the SinkFile attribute is
+      cleared or changed.
+
+      Clearing the attribute causes any open SinkFile to be closed. All
+      subsequent data writes will use the sink function specified when the
+      Channel was created, or will write to standard output if no sink
+      function was specified.
+
+      If no value has been assigned to SinkFile, a null string will be
+      returned if an attempt is made to get the attribute value.
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{FitsChan}{FitsChan}
+      }{
+         When the FitsChan is destroyed, any headers in the FitsChan will be
+         written out to the sink file, if one is specified (if not, the
+         sink function used when the FitsChan was created is used). The
+         sink file is a text file (not a FITS file) containing one header
+         per line.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A new SinkFile will over-write any existing file with the same
+         name unless the existing file is write protected, in which case an
+         error will be reported.
+
+         \sstitem
+          Any open SinkFile is closed when the Channel is deleted.
+
+         \sstitem
+          If the Channel is copied or dumped
+         (using \htmlref{astCopy}{astCopy} or \htmlref{astShow}{astShow})
+         the SinkFile attribute is left in a cleared state in the output
+         Channel (i.e. the value of the SinkFile attribute is not copied).
+      }
+   }
+}
+\sstroutine{
+   SipOK
+}{
+   Use Spitzer Space Telescope keywords to define distortion?
+}{
+   \sstdescription{
+      This attribute is a boolean value which specifies whether to include
+      support for the \texttt{"} SIP\texttt{"}  scheme, which can be used to add distortion to
+      basic FITS-WCS projections. This scheme was first defined by the
+      Spitzer Space Telescope and is described in the following document:
+      http://irsa.ipac.caltech.edu/data/SPITZER/docs/files/spitzer/shupeADASS.pdf
+      The default for SipOK is 1.
+
+      When using
+      \htmlref{astRead}{astRead}
+      to read a FITS-WCS encoded header, a suitable \htmlref{PolyMap}{PolyMap} will always be
+      included in the returned \htmlref{FrameSet}{FrameSet} if the header contains SIP
+      keywords, regardless of the value of the SipOK attribute. The PolyMap
+      will be immediately before the \htmlref{MatrixMap}{MatrixMap} that corresponds to the FITS-WCS
+      PC or CD matrix.
+
+      When using
+      \htmlref{astWrite}{astWrite}
+      to write a FrameSet to a FITS-WCS encoded header, suitable SIP
+      keywords will be included in the header if the FrameSet contains a
+      PolyMap immediately before the MatrixMap that corresponds to the
+      FITS-WCS PC or CD matrix, but only if the SipOK attribute is non-zero.
+      If the FrameSet contains a PolyMap but SipOK is zero, then an attempt
+      will be made to write out the FrameSet without SIP keywords using a
+      linear approximation to the pixel-to-IWC mapping. If this fails
+      because the \htmlref{Mapping}{Mapping} exceeds the linearity requirement specified by
+      attribute \htmlref{FitsTol}{FitsTol},
+      astWrite
+      will return zero, indicating that the FrameSet could not be written
+      out. Note, SIP headers can only be produced for axes that form part
+      of a \htmlref{SkyFrame}{SkyFrame}.
+
+      Note, the SIP distortion scheme is independent of the TPV/TPN
+      distortion schemes (see attribute \htmlref{PolyTan}{PolyTan}). A FITS-WCS header could
+      in principle, contain keywords for both schemes although this is unlikely.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{FitsChan}{FitsChan}
+      }{
+         All FitsChans have this attribute.
+      }
+   }
+}
+\sstroutine{
+   SipReplace
+}{
+   Replace SIP inverse transformation?
+}{
+   \sstdescription{
+      This attribute is a boolean value which specifies how SIP keywords
+      should be handled when reading a FITS-WCS encoded header using the
+      \htmlref{astRead}{astRead}
+      function. See
+      http://irsa.ipac.caltech.edu/data/SPITZER/docs/files/spitzer/shupeADASS.pdf
+      for more information about SIP headers. If SipReplace is non-zero,
+      then any SIP keywords describing the inverse transformation (i.e. from
+      WCS to pixel coordinates) are ignored. Instead a new inverse
+      transformation is found by performing a fit to the forward
+      transformation. The SipReplace attribute can be set to zero to prevent
+      this happening. If SipReplace is zero, any SIP keywords describing the
+      inverse transformation are used as supplied, rather than being
+      replaced using a new fit. The default value is 1.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{FitsChan}{FitsChan}
+      }{
+         All FitsChans have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Size(element)
+}{
+   Character size for a Plot element
+}{
+   \sstdescription{
+      This attribute determines the character size used when drawing
+      each element of graphical output produced by a \htmlref{Plot}{Plot}. It takes a
+      separate value for each graphical element so that, for instance,
+      the setting \texttt{"} Size(title)=2.0\texttt{"}  causes the Plot title to be drawn
+      using twice the default character size.
+
+      The range of character sizes available and the appearance of the
+      resulting text is determined by the underlying graphics system.
+      The default behaviour is for all graphical elements to be drawn
+      using the default character size supplied by this graphics
+      system.
+   }
+   \sstattributetype{
+      Floating Point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          For a list of the graphical elements available, see the
+         description of the Plot class.
+
+         \sstitem
+          If no graphical element is specified, (e.g. \texttt{"} Size\texttt{"}  instead
+         of \texttt{"} Size(title)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will
+         affect the attribute value of all graphical elements, while a
+         \texttt{"} get\texttt{"}  or \texttt{"} test\texttt{"}  operation will use just the Size(TextLab)
+         value.
+      }
+   }
+}
+\sstroutine{
+   SizeGuess
+}{
+   The expected size of the KeyMap
+}{
+   \sstdescription{
+      This is attribute gives an estimate of the number of entries that
+      will be stored in the \htmlref{KeyMap}{KeyMap}. It is used to tune the internal
+      properties of the KeyMap for speed and efficiency. A larger value
+      will result in faster access at the expense of increased memory
+      requirements. However if the SizeGuess value is much larger than
+      the actual size of the KeyMap, then there will be little, if any,
+      speed gained by making the SizeGuess even larger. The default value
+      is 300.
+
+      The value of this attribute can only be changed if the KeyMap is
+      empty. Its value can be set conveniently when creating the KeyMap.
+      An error will be reported if an attempt is made to set or clear the
+      attribute when the KeyMap contains any entries.
+   }
+   \sstattributetype{
+      Integer.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         KeyMap
+      }{
+         All KeyMaps have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Skip
+}{
+   Skip irrelevant data?
+}{
+   \sstdescription{
+      This is a boolean attribute which indicates whether the \htmlref{Object}{Object}
+      data being read through a \htmlref{Channel}{Channel} are inter-mixed with other,
+      irrelevant, external data.
+
+      If Skip is zero (the default), then the source of input data is
+      expected to contain descriptions of AST Objects and comments and
+      nothing else (if anything else is read, an error will
+      result). If Skip is non-zero, then any non-Object data
+      encountered between Objects will be ignored and simply skipped
+      over in order to reach the next Object.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Channel
+      }{
+         All Channels have this attribute.
+      }
+      \sstsubsection{
+         \htmlref{FitsChan}{FitsChan}
+      }{
+         The FitsChan class sets the default value of this attribute
+         to 1, so that all irrelevant FITS headers will normally be
+         ignored.
+      }
+   }
+}
+\sstroutine{
+   SkyRef(axis)
+}{
+   Position defining the offset coordinate system
+}{
+   \sstdescription{
+      This attribute allows a \htmlref{SkyFrame}{SkyFrame} to represent offsets, rather than
+      absolute axis values, within the coordinate system specified by the
+      \htmlref{System}{System} attribute. If supplied, SkyRef should be set to hold the
+      longitude and latitude of a point within the coordinate system
+      specified by the System attribute. The coordinate system represented
+      by the SkyFrame will then be rotated in order to put the specified
+      position at either the pole or the origin of the new coordinate system
+      (as indicated by the \htmlref{SkyRefIs}{SkyRefIs} attribute). The orientation of the
+      modified coordinate system is then controlled using the SkyRefP
+      attribute.
+
+      If an integer axis index is included in the attribute name (e.g.
+      \texttt{"} SkyRef(1)\texttt{"} ) then the attribute value should be supplied as a single
+      floating point axis value, in radians, when setting a value for the
+      attribute, and will be returned in the same form when getting the value
+      of the attribute. In this case the integer axis index should be \texttt{"} 1\texttt{"}
+      or \texttt{"} 2\texttt{"}  (the values to use for longitude and latitude axes are
+      given by the \htmlref{LonAxis}{LonAxis} and \htmlref{LatAxis}{LatAxis} attributes).
+
+      If no axis index is included in the attribute name (e.g. \texttt{"} SkyRef\texttt{"} ) then
+      the attribute value should be supplied as a character string
+      containing two formatted axis values (an axis 1 value followed by a
+      comma, followed by an axis 2 value). The same form
+      will be used when getting the value of the attribute.
+
+      The default values for SkyRef are zero longitude and zero latitude.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         SkyFrame
+      }{
+         All SkyFrames have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If the System attribute of the SkyFrame is changed, any position
+         given for SkyRef is transformed into the new System.
+
+         \sstitem
+          If a value has been assigned to SkyRef attribute, then
+         the default values for certain attributes are changed as follows:
+         the default axis Labels for the SkyFrame are modified by appending
+         \texttt{"}  offset\texttt{"}  to the end, the default axis Symbols for the SkyFrame are
+         modified by prepending the character \texttt{"} D\texttt{"}  to the start, and the
+         default title is modified by replacing the projection information by the
+         origin information.
+      }
+   }
+   \sstdiytopic{
+      Aligning SkyFrames with Offset Coordinate Systems
+   }{
+      The offset coordinate system within a SkyFrame should normally be
+      considered as a superficial \texttt{"} re-badging\texttt{"}  of the axes of the coordinate
+      system specified by the System attribute - it merely provides an
+      alternative numerical \texttt{"} label\texttt{"}  for each position in the System coordinate
+      system. The SkyFrame retains full knowledge of the celestial coordinate
+      system on which the offset coordinate system is based (given by the
+      System attribute). For instance, the SkyFrame retains knowledge of the
+      way that one celestial coordinate system may \texttt{"} drift\texttt{"}  with respect to
+      another over time. Normally, if you attempt to align two SkyFrames (e.g.
+      using the \htmlref{astConvert}{astConvert} or \htmlref{astFindFrame}{astFindFrame} routine),
+      the effect of any offset coordinate system defined in either SkyFrame
+      will be removed, resulting in alignment being performed in the
+      celestial coordinate system given by the \htmlref{AlignSystem}{AlignSystem} attribute.
+      However, by setting the \htmlref{AlignOffset}{AlignOffset} attribute to a non-zero value, it
+      is possible to change this behaviour so that the effect of the offset
+      coordinate system is not removed when aligning two SkyFrames.
+   }
+}
+\sstroutine{
+   SkyRefIs
+}{
+   Selects the nature of the offset coordinate system
+}{
+   \sstdescription{
+      This attribute controls how the values supplied for the SkyRef and
+      SkyRefP attributes are used. These three attributes together allow
+      a \htmlref{SkyFrame}{SkyFrame} to represent offsets relative to some specified origin
+      or pole within the coordinate system specified by the \htmlref{System}{System} attribute,
+      rather than absolute axis values. SkyRefIs can take one of the
+      case-insensitive values \texttt{"} Origin\texttt{"} , \texttt{"} Pole\texttt{"}  or \texttt{"} Ignored\texttt{"} .
+
+      If SkyRefIs is set to \texttt{"} Origin\texttt{"} , then the coordinate system
+      represented by the SkyFrame is modified to put the origin of longitude
+      and latitude at the position specified by the SkyRef attribute.
+
+      If SkyRefIs is set to \texttt{"} Pole\texttt{"} , then the coordinate system represented
+      by the SkyFrame is modified to put the north pole at the position
+      specified by the SkyRef attribute.
+
+      If SkyRefIs is set to \texttt{"} Ignored\texttt{"}  (the default), then any value set for the
+      SkyRef attribute is ignored, and the SkyFrame represents the coordinate
+      system specified by the System attribute directly without any rotation.
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         SkyFrame
+      }{
+         All SkyFrames have this attribute.
+      }
+   }
+}
+\sstroutine{
+   SkyRefP(axis)
+}{
+   Position on primary meridian of offset coordinate system
+}{
+   \sstdescription{
+      This attribute is used to control the orientation of the offset
+      coordinate system defined by attributes SkyRef and \htmlref{SkyRefIs}{SkyRefIs}. If used,
+      it should be set to hold the longitude and latitude of a point within
+      the coordinate system specified by the \htmlref{System}{System} attribute. The offset
+      coordinate system represented by the \htmlref{SkyFrame}{SkyFrame} will then be rotated in
+      order to put the position supplied for SkyRefP on the zero longitude
+      meridian. This rotation is about an axis from the centre of the
+      celestial sphere to the point specified by the SkyRef attribute.
+      The default value for SkyRefP is usually the north pole (that is, a
+      latitude of $+$90 degrees in the coordinate system specified by the System
+      attribute). The exception to this is if the SkyRef attribute is
+      itself set to either the north or south pole. In these cases the
+      default for SkyRefP is the origin (that is, a (0,0) in the coordinate
+      system specified by the System attribute).
+
+      If an integer axis index is included in the attribute name (e.g.
+      \texttt{"} SkyRefP(1)\texttt{"} ) then the attribute value should be supplied as a single
+      floating point axis value, in radians, when setting a value for the
+      attribute, and will be returned in the same form when getting the value
+      of the attribute. In this case the integer axis index should be \texttt{"} 1\texttt{"}
+      or \texttt{"} 2\texttt{"}  (the values to use for longitude and latitude axes are
+      given by the \htmlref{LonAxis}{LonAxis} and \htmlref{LatAxis}{LatAxis} attributes).
+
+      If no axis index is included in the attribute name (e.g. \texttt{"} SkyRefP\texttt{"} ) then
+      the attribute value should be supplied as a character string
+      containing two formatted axis values (an axis 1 value followed by a
+      comma, followed by an axis 2 value). The same form
+      will be used when getting the value of the attribute.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         SkyFrame
+      }{
+         All SkyFrames have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If the position given by the SkyRef attribute defines the origin
+         of the offset coordinate system (that is, if the SkyRefIs attribute
+         is set to \texttt{"} origin\texttt{"} ), then there will in general be two orientations
+         which will put the supplied SkyRefP position on the zero longitude
+         meridian. The orientation which is actually used is the one which
+         gives the SkyRefP position a positive latitude in the offset coordinate
+         system (the other possible orientation would give the SkyRefP position
+         a negative latitude).
+
+         \sstitem
+          An error will be reported if an attempt is made to use a
+         SkyRefP value which is co-incident with SkyRef or with the point
+         diametrically opposite to SkyRef on the celestial sphere. The
+         reporting of this error is deferred until the SkyRef and SkyRefP
+         attribute values are used within a calculation.
+
+         \sstitem
+          If the System attribute of the SkyFrame is changed, any position
+         given for SkyRefP is transformed into the new System.
+      }
+   }
+}
+\sstroutine{
+   SkyTol
+}{
+   The smallest significant shift in sky coordinates
+}{
+   \sstdescription{
+      This attribute indicates the accuracy of the axis values that will
+      be represented by the \htmlref{SkyFrame}{SkyFrame}. If the arc-distance between two
+      positions within the SkyFrame is smaller than the value of SkyTol,
+      then the two positions will (for the puposes indicated below) be
+      considered to be co-incident.
+
+      This value is used only when constructing the \htmlref{Mapping}{Mapping} between
+      two different SkyFrames (for instance, when calling
+      \htmlref{astConvert}{astConvert} or \htmlref{astFindFrame}{astFindFrame}).
+      If the transformation between the two SkyFrames causes positions to
+      shift by less than SkyTol arc-seconds, then the transformation is
+      replaced by a \htmlref{UnitMap}{UnitMap}.  This could in certain circumatances allow
+      major simplifications to be made to the transformation between
+      any pixel grids associated with the two SkyFrames (for instance, if
+      each SkyFrame is part of the WCS \htmlref{FrameSet}{FrameSet} associated with an image).
+
+      A common case is when two SkyFrames use the FK5 system, but have
+      slightly different \htmlref{Epoch}{Epoch} values. If the \htmlref{AlignSystem}{AlignSystem} attribute has
+      its default value of \texttt{"} ICRS\texttt{"} , then the transformation between the
+      two SkyFrames will include a very small rotation (FK5 rotates with
+      respect to ICRS as a rate of about 0.0005 arc-seconds per year). In
+      most circumstances such a small rotation is insignificant. Setting
+      SkyTol to some suitably small non-zero value will cause this
+      rotation to be ignored, allowing much simpler transformations to
+      be used.
+
+      The test to determine the shift introduced by transforming between
+      the two SkyFrames is performed by transforming a set of 14 position
+      spread evenly over the whole sky. The largest shift produced at any
+      of these 14 positions is compared to the value of SkyTol.
+
+      The SkyTol value is in units of arc-seconds, and the default value
+      is 0.001.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         SkyFrame
+      }{
+         All SkyFrames have this attribute.
+      }
+   }
+}
+\sstroutine{
+   SortBy
+}{
+   Determines how keys are sorted in a KeyMap
+}{
+   \sstdescription{
+      This attribute determines the order in which keys are returned by the
+      \htmlref{astMapKey}{astMapKey}
+      function. It may take the following values (the default is \texttt{"} None\texttt{"} ):
+
+      \sstitemlist{
+
+         \sstitem
+          \texttt{"} None\texttt{"} : The keys are returned in an arbitrary order. This is the
+         fastest method as it avoids the need for a sorted list of keys to
+         be maintained and used.
+
+         \sstitem
+          \texttt{"} AgeDown\texttt{"} : The keys are returned in the order in which values were
+         stored in the \htmlref{KeyMap}{KeyMap}, with the key for the most recent value being
+         returned last. If the value of an existing entry is changed, it goes
+         to the end of the list.
+
+         \sstitem
+          \texttt{"} AgeUp\texttt{"} : The keys are returned in the order in which values were
+         stored in the KeyMap, with the key for the most recent value being
+         returned first. If the value of an existing entry is changed, it goes
+         to the top of the list.
+
+         \sstitem
+          \texttt{"} KeyAgeDown\texttt{"} : The keys are returned in the order in which they
+         were originally stored in the KeyMap, with the most recent key being
+         returned last. If the value of an existing entry is changed, its
+         position in the list does not change.
+
+         \sstitem
+          \texttt{"} KeyAgeUp\texttt{"} : The keys are returned in the order in which they
+         were originally stored in the KeyMap, with the most recent key being
+         returned first. If the value of an existing entry is changed, its
+         position in the list does not change.
+
+         \sstitem
+          \texttt{"} KeyDown\texttt{"} : The keys are returned in alphabetical order, with \texttt{"} A...\texttt{"}
+         being returned last.
+
+         \sstitem
+          \texttt{"} KeyUp\texttt{"} : The keys are returned in alphabetical order, with \texttt{"} A...\texttt{"}
+         being returned first.
+      }
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         KeyMap
+      }{
+         All KeyMaps have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If a new value is assigned to SortBy (or if SortBy is cleared),
+         all entries currently in the KeyMap are re-sorted according to the
+         new SortBy value.
+      }
+   }
+}
+\sstroutine{
+   SourceFile
+}{
+   Input file from which to read data
+}{
+   \sstdescription{
+      This attribute specifies the name of a file from which the \htmlref{Channel}{Channel}
+      should read data. If specified it is used in preference to any source
+      function specified when the Channel was created.
+
+      Assigning a new value to this attribute will cause any previously
+      opened SourceFile to be closed. The first subsequent call to
+      \htmlref{astRead}{astRead}
+      will attempt to open the new file (an error will be reported if the
+      file cannot be opened), and read data from it. All subsequent call to
+      astRead
+      will read data from the new file, until the SourceFile attribute is
+      cleared or changed.
+
+      Clearing the attribute causes any open SourceFile to be closed. All
+      subsequent data reads will use the source function specified when the
+      Channel was created, or will read from standard input if no source
+      function was specified.
+
+      If no value has been assigned to SourceFile, a null string will be
+      returned if an attempt is made to get the attribute value.
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{FitsChan}{FitsChan}
+      }{
+         In the case of a FitsChan, the specified SourceFile supplements
+         the source function specified when the FitsChan was created,
+         rather than replacing the source function. The source file
+         should be a text file (not a FITS file) containing one header per
+         line. When a value is assigned to SourceFile, the file is opened
+         and read immediately, and all headers read from the file are
+         appended to the end of any header already in the FitsChan. The file
+         is then closed. Clearing the SourceFile attribute has no further
+         effect, other than nullifying the string (i.e. the file name)
+         associated with the attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Any open SourceFile is closed when the Channel is deleted.
+
+         \sstitem
+          If the Channel is copied or dumped
+         (using \htmlref{astCopy}{astCopy} or \htmlref{astShow}{astShow})
+         the SourceFile attribute is left in a cleared state in the output
+         Channel (i.e. the value of the SourceFile attribute is not copied).
+      }
+   }
+}
+\sstroutine{
+   SourceSys
+}{
+   Spectral system in which the source velocity is stored
+}{
+   \sstdescription{
+      This attribute identifies the spectral system in which the
+      \htmlref{SourceVel}{SourceVel} attribute value (the source velocity) is supplied and
+      returned. It can be one of the following:
+
+      \sstitemlist{
+
+         \sstitem
+             \texttt{"} VRAD\texttt{"}  or \texttt{"} VRADIO\texttt{"} : Radio velocity (km/s)
+
+         \sstitem
+             \texttt{"} VOPT\texttt{"}  or \texttt{"} VOPTICAL\texttt{"} : Optical velocity (km/s)
+
+         \sstitem
+             \texttt{"} ZOPT\texttt{"}  or \texttt{"} REDSHIFT\texttt{"} : Redshift (dimensionless)
+
+         \sstitem
+             \texttt{"} BETA\texttt{"} : Beta factor (dimensionless)
+
+         \sstitem
+             \texttt{"} VELO\texttt{"}  or \texttt{"} VREL\texttt{"} : Apparent radial (\texttt{"} relativistic\texttt{"} ) velocity (km/s)
+
+      }
+      When setting a new value for the SourceVel attribute, the source
+      velocity should be supplied in the spectral system indicated
+      by this attribute. Likewise, when getting the value of the SourceVel
+      attribute, the velocity will be returned in this spectral system.
+
+      If the value of SourceSys is changed, the value stored for SourceVel
+      will be converted from the old to the new spectral systems.
+
+      The default value is \texttt{"} VELO\texttt{"}  (apparent radial velocity).
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{SpecFrame}{SpecFrame}
+      }{
+         All SpecFrames have this attribute.
+      }
+   }
+}
+\sstroutine{
+   SourceVRF
+}{
+   Rest frame in which the source velocity is stored
+}{
+   \sstdescription{
+      This attribute identifies the rest frame in which the source
+      velocity or redshift is stored (the source velocity or redshift is
+      accessed using attribute \htmlref{SourceVel}{SourceVel}). When setting a new value for the
+      SourceVel attribute, the source velocity or redshift should be supplied
+      in the rest frame indicated by this attribute. Likewise, when getting
+      the value of the SourceVel attribute, the velocity or redshift will be
+      returned in this rest frame.
+
+      If the value of SourceVRF is changed, the value stored for SourceVel
+      will be converted from the old to the new rest frame.
+
+      The values which can be supplied are the same as for the \htmlref{StdOfRest}{StdOfRest}
+      attribute (except that SourceVRF cannot be set to \texttt{"} Source\texttt{"} ). The
+      default value is \texttt{"} Helio\texttt{"} .
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{SpecFrame}{SpecFrame}
+      }{
+         All SpecFrames have this attribute.
+      }
+   }
+}
+\sstroutine{
+   SourceVel
+}{
+   The source velocity
+}{
+   \sstdescription{
+      This attribute (together with \htmlref{SourceSys}{SourceSys}, \htmlref{SourceVRF}{SourceVRF}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec})
+      defines the \texttt{"} Source\texttt{"}  standard of rest (see attribute \htmlref{StdOfRest}{StdOfRest}). This is
+      a rest frame which is moving towards the position given by RefRA and
+      RefDec at a  velocity given by SourceVel. A positive value means
+      the source is moving away from the observer. When a new value is
+      assigned to this attribute, the supplied value is assumed to refer
+      to the spectral system specified by the SourceSys attribute. For
+      instance, the SourceVel value may be supplied as a radio velocity, a
+      redshift, a beta factor, etc. Similarly, when the current value of
+      the SourceVel attribute is obtained, the returned value will refer
+      to the spectral system specified by the SourceSys value. If the
+      SourceSys value is changed, any value previously stored for the SourceVel
+      attribute will be changed automatically from the old spectral system
+      to the new spectral system.
+
+      When setting a value for SourceVel, the value should be supplied in the
+      rest frame specified by the SourceVRF attribute. Likewise, when getting
+      the value of SourceVel, it will be returned in the rest frame specified
+      by the SourceVRF attribute.
+
+      The default SourceVel value is zero.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{SpecFrame}{SpecFrame}
+      }{
+         All SpecFrames have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          It is important to set an appropriate value for SourceVRF and
+         SourceSys before setting a value for SourceVel. If a new value is later
+         set for SourceVRF or SourceSys, the value stored for SourceVel will
+         simultaneously be changed to the new standard of rest or spectral
+         system.
+      }
+   }
+}
+\sstroutine{
+   SpecOrigin
+}{
+   The zero point for SpecFrame axis values
+}{
+   \sstdescription{
+      This specifies the origin from which all spectral values are measured.
+      The default value (zero) results in the \htmlref{SpecFrame}{SpecFrame} describing
+      absolute spectral values in the system given by the \htmlref{System}{System} attribute
+      (e.g. frequency, velocity, etc). If a SpecFrame is to be used to
+      describe offset from some origin, the SpecOrigin attribute
+      should be set to hold the required origin value. The SpecOrigin value
+      stored inside the SpecFrame structure is modified whenever SpecFrame
+      attribute values are changed so that it refers to the original spectral
+      position.
+
+      When setting a new value for this attribute, the supplied value is assumed
+      to be in the system, units and standard of rest described by the SpecFrame.
+      Likewise, when getting the value of this attribute, the value is returned
+      in the system, units and standard of rest described by the SpecFrame. If
+      any of these attributes are changed, then any previously stored SpecOrigin
+      value will also be changed so that refers to the new system, units or
+      standard of rest.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         SpecFrame
+      }{
+         All SpecFrames have this attribute.
+      }
+   }
+}
+\sstroutine{
+   SpecVal
+}{
+   The spectral position at which flux values are measured
+}{
+   \sstdescription{
+      This attribute specifies the spectral position (frequency, wavelength,
+      etc.), at which the values described by the \htmlref{FluxFrame}{FluxFrame} are measured.
+      It is used when determining the \htmlref{Mapping}{Mapping} between between FluxFrames.
+
+      The default value and spectral system used for this attribute are
+      both specified when the FluxFrame is created.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         FluxFrame
+      }{
+         All FluxFrames have this attribute.
+      }
+   }
+}
+\sstroutine{
+   StcsArea
+}{
+   Return the CoordinateArea component when reading an STC-S document?
+}{
+   \sstdescription{
+      This is a boolean attribute which controls what is returned
+      by the
+      \htmlref{astRead}{astRead}
+      function when it is used to read from an \htmlref{StcsChan}{StcsChan}.
+      If StcsArea is set non-zero (the default), then a \htmlref{Region}{Region}
+      representing the STC CoordinateArea will be returned by
+      astRead.
+      If StcsArea is set to zero, then the STC CoordinateArea
+      will not be returned.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         StcsChan
+      }{
+         All StcsChans have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Other attributes such as \htmlref{StcsCoords}{StcsCoords} and \htmlref{StcsProps}{StcsProps} can be used to
+         specify other Objects to be returned by
+         astRead.
+         If more than one of these attributes is set non-zero, then the
+         actual \htmlref{Object}{Object} returned by
+         astRead
+         will be a \htmlref{KeyMap}{KeyMap}, containing the requested Objects. In this
+         case, the Region representing the STC CoordinateArea will be
+         stored in the returned KeyMap using the key \texttt{"} AREA\texttt{"} . If StcsArea
+         is the only attribute to be set non-zero, then the Object returned by
+         astRead
+         will be the CoordinateArea Region itself.
+
+         \sstitem
+          The class of Region used to represent the CoordinateArea for each
+         STC-S sub-phrase is determined by the first word in the
+         sub-phrase (the \texttt{"} sub-phrase identifier\texttt{"} ). The individual sub-phrase
+         Regions are combined into a single \htmlref{Prism}{Prism}, which is then simplified
+         using \htmlref{astSimplify}{astSimplify}
+         to form the returned region.
+
+         \sstitem
+          Sub-phrases that represent a single value ( that is, have
+         identifiers \texttt{"} Time\texttt{"} , \texttt{"} Position\texttt{"} , \texttt{"} Spectral\texttt{"}  or \texttt{"} Redshift\texttt{"}  ) are
+         considered to be be part of the STC CoordinateArea component.
+
+         \sstitem
+          The \htmlref{TimeFrame}{TimeFrame} used to represent a time STC-S sub-phrase will have
+         its \htmlref{TimeOrigin}{TimeOrigin} attribute set to the sub-phrase start time. If no
+         start time is specified by the sub-phrase, then the stop time will be
+         used instead. If no stop time is specified by the sub-phrase, then
+         the single time value specified in the sub-phrase will be used
+         instead. Subsequently clearing the TimeOrigin attribute (or setting
+         its value to zero) will cause the TimeFrame to reprsent absolute times.
+
+         \sstitem
+          The \htmlref{Epoch}{Epoch} attribute for the returned Region is set in the same
+         way as the TimeOrigin attribute (see above).
+      }
+   }
+}
+\sstroutine{
+   StcsCoords
+}{
+   Return the Coordinates component when reading an STC-S document?
+}{
+   \sstdescription{
+      This is a boolean attribute which controls what is returned
+      by the
+      \htmlref{astRead}{astRead}
+      function when it is used to read from an \htmlref{StcsChan}{StcsChan}.
+      If StcsCoords is set non-zero, then a \htmlref{PointList}{PointList}
+      representing the STC Coordinates will be returned by
+      astRead.
+      If StcsCoords is set to zero (the default), then the STC
+      Coordinates will not be returned.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         StcsChan
+      }{
+         All StcsChans have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Other attributes such as \htmlref{StcsArea}{StcsArea} and \htmlref{StcsProps}{StcsProps} can be used to
+         specify other Objects to be returned by
+         astRead.
+         If more than one of these attributes is set non-zero, then the
+         actual \htmlref{Object}{Object} returned by
+         astRead
+         will be a \htmlref{KeyMap}{KeyMap}, containing the requested Objects. In this
+         case, the PointList representing the STC Coordinates will be
+         stored in the returned KeyMap using the key \texttt{"} COORDS\texttt{"} . If StcsCoords
+         is the only attribute to be set non-zero, then the Object returned by
+         astRead
+         will be the Coordinates PointList itself.
+
+         \sstitem
+          The Coordinates component is specified by the additional axis
+         values embedded within the body of each STC-S sub-phrase that
+         represents an extended area. Sub-phrases that represent a single
+         value ( that is, have identifiers \texttt{"} Time\texttt{"} , \texttt{"} Position\texttt{"} , \texttt{"} Spectral\texttt{"}
+         or \texttt{"} Redshift\texttt{"}  ) are not considered to be be part of the STC
+         Coordinates component.
+
+         \sstitem
+          If the STC-S documents does not contain a Coordinates component,
+         then a NULL object pointer
+         will be returned by
+         astRead
+         if the Coordinates component is the only object being returned. If
+         other objects are also being returned (see attributes StcsProps and
+         StcsArea), then the returned KeyMap will contain a \texttt{"} COORDS\texttt{"}  key
+         only if the Coordinates component is read succesfully.
+
+         \sstitem
+          The \htmlref{TimeFrame}{TimeFrame} used to represent a time STC-S sub-phrase will have
+         its \htmlref{TimeOrigin}{TimeOrigin} attribute set to the sub-phrase start time. If no
+         start time is specified by the sub-phrase, then the stop time will be
+         used instead. If no stop time is specified by the sub-phrase, then
+         the single time value specified in the sub-phrase will be used
+         instead. Subsequently clearing the TimeOrigin attribute (or setting
+         its value to zero) will cause the TimeFrame to reprsent absolute times.
+
+         \sstitem
+          The \htmlref{Epoch}{Epoch} attribute for the returned \htmlref{Region}{Region} is set in the same
+         way as the TimeOrigin attribute (see above).
+      }
+   }
+}
+\sstroutine{
+   StcsLength
+}{
+   Controls output line length
+}{
+   \sstdescription{
+      This attribute specifies the maximum length to use when writing out
+      text through the sink function supplied when the \htmlref{StcsChan}{StcsChan} was created.
+      It is ignored if the \htmlref{Indent}{Indent} attribute is zero (in which case the text
+      supplied to the sink function can be of any length). The default value
+      is 70.
+
+      The number of characters in each string written out through the sink
+      function will not usually be greater than the value of this attribute
+      (but may be less). However, if any single word in the STC-S
+      description exceeds the specified length, then the word will be
+      written out as a single line.
+   }
+   \sstattributetype{
+      Integer.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         StcsChan
+      }{
+         All StcsChans have this attribute.
+      }
+   }
+}
+\sstroutine{
+   StcsProps
+}{
+   Return all properties when reading an STC-S document?
+}{
+   \sstdescription{
+      This is a boolean attribute which controls what is returned
+      by the
+      \htmlref{astRead}{astRead}
+      function when it is used to read from an \htmlref{StcsChan}{StcsChan}.
+      If StcsProps is set non-zero, then a \htmlref{KeyMap}{KeyMap} containing all the
+      properties read from the STC-S document will be returned by
+      astRead.
+      If StcsProps is set to zero (the default), then the properties
+      will not be returned.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         StcsChan
+      }{
+         All StcsChans have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          Other attributes such as \htmlref{StcsCoords}{StcsCoords} and \htmlref{StcsArea}{StcsArea} can be used to
+         specify other Objects to be returned by
+         astRead.
+         If more than one of these attributes is set non-zero, then the
+         actual \htmlref{Object}{Object} returned by
+         astRead
+         will be a KeyMap containing the requested Objects. In this
+         case, the properties KeyMap will be stored in the returned KeyMap
+         using the key \texttt{"} PROPS\texttt{"} . If StcsProps is the only attribute to be
+         set non-zero, then the Object returned by
+         astRead
+         will be the properties KeyMap itself.
+
+         \sstitem
+          The KeyMap containing the properties will have entries for one or
+         more of the following keys: \texttt{"} TIME\_PROPS\texttt{"} , \texttt{"} SPACE\_PROPS\texttt{"} , \texttt{"} SPECTRAL\_PROPS\texttt{"}
+         and \texttt{"} REDSHIFT\_PROPS\texttt{"} . Each of these entries will be another KeyMap
+         containing the properties of the corresponding STC-S sub-phrase.
+      }
+   }
+}
+\sstroutine{
+   StdOfRest
+}{
+   Standard of rest
+}{
+   \sstdescription{
+      This attribute identifies the standard of rest to which the spectral
+      axis values of a \htmlref{SpecFrame}{SpecFrame} refer, and may take any of the values
+      listed in the \texttt{"} Standards of Rest\texttt{"}  section (below).
+
+      The default StdOfRest value is \texttt{"} Helio\texttt{"} .
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         SpecFrame
+      }{
+         All SpecFrames have this attribute.
+      }
+   }
+   \sstdiytopic{
+      Standards of Rest
+   }{
+      The SpecFrame class supports the following StdOfRest values (all are
+      case-insensitive):
+
+      \sstitemlist{
+
+         \sstitem
+          \texttt{"} Topocentric\texttt{"} , \texttt{"} Topocent\texttt{"}  or \texttt{"} Topo\texttt{"} : The observers rest-frame (assumed
+         to be on the surface of the earth). Spectra recorded in this standard of
+         rest suffer a Doppler shift which varies over the course of a day
+         because of the rotation of the observer around the axis of the earth.
+         This standard of rest must be qualified using the \htmlref{ObsLat}{ObsLat}, \htmlref{ObsLon}{ObsLon},
+         \htmlref{ObsAlt}{ObsAlt}, \htmlref{Epoch}{Epoch}, \htmlref{RefRA}{RefRA} and \htmlref{RefDec}{RefDec} attributes.
+
+         \sstitem
+          \texttt{"} Geocentric\texttt{"} , \texttt{"} Geocentr\texttt{"}  or \texttt{"} Geo\texttt{"} : The rest-frame of the earth centre.
+         Spectra recorded in this standard of rest suffer a Doppler shift which
+         varies over the course of a year because of the rotation of the earth
+         around the Sun. This standard of rest must be qualified using the Epoch,
+         RefRA and RefDec attributes.
+
+         \sstitem
+          \texttt{"} Barycentric\texttt{"} , \texttt{"} Barycent\texttt{"}  or \texttt{"} Bary\texttt{"} : The rest-frame of the solar-system
+         barycentre. Spectra recorded in this standard of rest suffer a Doppler
+         shift which depends both on the velocity of the Sun through the Local
+         Standard of Rest, and on the movement of the planets through the solar
+         system. This standard of rest must be qualified using the Epoch, RefRA
+         and RefDec attributes.
+
+         \sstitem
+          \texttt{"} Heliocentric\texttt{"} , \texttt{"} Heliocen\texttt{"}  or \texttt{"} Helio\texttt{"} : The rest-frame of the Sun.
+         Spectra recorded in this standard of rest suffer a Doppler shift which
+         depends on the velocity of the Sun through the Local Standard of Rest.
+         This standard of rest must be qualified using the RefRA and RefDec
+         attributes.
+
+         \sstitem
+          \texttt{"} LSRK\texttt{"} , \texttt{"} LSR\texttt{"} : The rest-frame of the kinematical Local Standard of
+         Rest. Spectra recorded in this standard of rest suffer a Doppler shift
+         which depends on the velocity of the kinematical Local Standard of Rest
+         through the galaxy. This standard of rest must be qualified using the
+         RefRA and RefDec attributes.
+
+         \sstitem
+          \texttt{"} LSRD\texttt{"} : The rest-frame of the dynamical Local Standard of Rest. Spectra
+         recorded in this standard of rest suffer a Doppler shift which depends
+         on the velocity of the dynamical Local Standard of Rest through the
+         galaxy.  This standard of rest must be qualified using the RefRA and
+         RefDec attributes.
+
+         \sstitem
+          \texttt{"} Galactic\texttt{"} , \texttt{"} Galactoc\texttt{"}  or \texttt{"} Gal\texttt{"} : The rest-frame of the galactic centre.
+         Spectra recorded in this standard of rest suffer a Doppler shift which
+         depends on the velocity of the galactic centre through the local group.
+         This standard of rest must be qualified using the RefRA and RefDec
+         attributes.
+
+         \sstitem
+          \texttt{"} Local\_group\texttt{"} , \texttt{"} Localgrp\texttt{"}  or \texttt{"} LG\texttt{"} : The rest-frame of the local group.
+         This standard of rest must be qualified using the RefRA and RefDec
+         attributes.
+
+         \sstitem
+          \texttt{"} Source\texttt{"} , or \texttt{"} src\texttt{"} : The rest-frame of the source. This standard of
+         rest must be qualified using the RefRA, RefDec and \htmlref{SourceVel}{SourceVel} attributes.
+
+      }
+      Where more than one alternative \htmlref{System}{System} value is shown above, the
+      first of these will be returned when an enquiry is made.
+   }
+}
+\sstroutine{
+   Strict
+}{
+   Report an error if any unexpeted data items are found?
+}{
+   \sstdescription{
+      This is a boolean attribute which indicates whether a warning
+      rather than an error should be issed for insignificant conversion
+      problems. If it is set non-zero, then fatal errors are issued
+      instead of warnings, resulting in the
+      AST error status being set.
+      If Strict is zero (the default), then execution continues after minor
+      conversion problems, and a warning message is added to the \htmlref{Channel}{Channel}
+      structure. Such messages can be retrieved using the
+      \htmlref{astWarnings}{astWarnings}
+      function.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Channel
+      }{
+         All Channels have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This attribute was introduced in AST version 5.0. Prior to this
+         version of AST unexpected data items read by a basic Channel always
+         caused an error to be reported. So applications linked against
+         versions of AST prior to version 5.0 may not be able to read \htmlref{Object}{Object}
+         descriptions created by later versions of AST, if the Object\texttt{'} s class
+         description has changed.
+      }
+   }
+}
+\sstroutine{
+   Style(element)
+}{
+   Line style for a Plot element
+}{
+   \sstdescription{
+      This attribute determines the line style used when drawing each
+      element of graphical output produced by a \htmlref{Plot}{Plot}. It takes a
+      separate value for each graphical element so that, for instance,
+      the setting \texttt{"} Style(border)=2\texttt{"}  causes the Plot border to be drawn
+      using line style 2 (which might result in, say, a dashed line).
+
+      The range of integer line styles available and their appearance
+      is determined by the underlying graphics system.  The default
+      behaviour is for all graphical elements to be drawn using the
+      default line style supplied by this graphics system (normally,
+      this is likely to give a solid line).
+   }
+   \sstattributetype{
+      Integer.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          For a list of the graphical elements available, see the
+         description of the Plot class.
+
+         \sstitem
+          If no graphical element is specified, (e.g. \texttt{"} Style\texttt{"}  instead of
+         \texttt{"} Style(border)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect
+         the attribute value of all graphical elements, while a \texttt{"} get\texttt{"}  or
+         \texttt{"} test\texttt{"}  operation will use just the Style(\htmlref{Border}{Border}) value.
+      }
+   }
+}
+\sstroutine{
+   Symbol(axis)
+}{
+   Axis symbol
+}{
+   \sstdescription{
+      This attribute specifies a short-form symbol to be used to
+      represent coordinate values for a particular axis of a
+      \htmlref{Frame}{Frame}. This might be used (e.g.) in algebraic expressions where
+      a full description of the axis would be inappropriate. Examples
+      include \texttt{"} RA\texttt{"}  and \texttt{"} Dec\texttt{"}  (for Right Ascension and Declination).
+
+      If a Symbol value has not been set for a Frame axis, then a
+      suitable default is supplied.
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Frame
+      }{
+         The default Symbol value supplied by the Frame class is the
+         string \texttt{"} $<$\htmlref{Domain}{Domain}$>$$<$n$>$\texttt{"} , where $<$n$>$ is 1, 2, etc. for successive
+         axes, and $<$Domain$>$ is the value of the Frame\texttt{'} s Domain
+         attribute (truncated if necessary so that the final string
+         does not exceed 15 characters). If no Domain value has been
+         set, \texttt{"} x\texttt{"}  is used as the $<$Domain$>$ value in constructing this
+         default string.
+      }
+      \sstsubsection{
+         \htmlref{SkyFrame}{SkyFrame}
+      }{
+         The SkyFrame class re-defines the default Symbol value
+         (e.g. to \texttt{"} RA\texttt{"}  or \texttt{"} Dec\texttt{"} ) as appropriate for the particular
+         celestial coordinate system being represented.
+      }
+      \sstsubsection{
+         \htmlref{TimeFrame}{TimeFrame}
+      }{
+         The TimeFrame class re-defines the default Symbol value as
+         appropriate for the particular time system being represented.
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         The Symbol attribute of a FrameSet axis is the same as that
+         of its current Frame (as specified by the \htmlref{Current}{Current} attribute).
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          When specifying this attribute by name, it should be
+         subscripted with the number of the Frame axis to which it
+         applies.
+      }
+   }
+}
+\sstroutine{
+   System
+}{
+   Coordinate system used to describe positions within the domain
+}{
+   \sstdescription{
+      In general it is possible for positions within a given physical
+      domain to be described using one of several different coordinate
+      systems. For instance, the \htmlref{SkyFrame}{SkyFrame} class can use galactic
+      coordinates, equatorial coordinates, etc, to describe positions on
+      the sky. As another example, the \htmlref{SpecFrame}{SpecFrame} class can use frequency,
+      wavelength, velocity, etc, to describe a position within an
+      electromagnetic spectrum. The System attribute identifies the particular
+      coordinate system represented by a \htmlref{Frame}{Frame}. Each class of Frame
+      defines a set of acceptable values for this attribute, as listed
+      below (all are case insensitive). Where more than one alternative
+      System value is shown, the first of will be returned when an
+      enquiry is made.
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Frame
+      }{
+         The System attribute for a basic Frame always equals \texttt{"} Cartesian\texttt{"} ,
+         and may not be altered.
+      }
+      \sstsubsection{
+         \htmlref{CmpFrame}{CmpFrame}
+      }{
+         The System attribute for a CmpFrame always equals \texttt{"} Compound\texttt{"} ,
+         and may not be altered. In addition, the CmpFrame class allows
+         the System attribute to be referenced for a component Frame by
+         including the index of an axis within the required component
+         Frame. For instance, \texttt{"} System(3)\texttt{"}  refers to the System attribute
+         of the component Frame which includes axis 3 of the CmpFrame.
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         The System attribute of a FrameSet is the same as that of its
+         current Frame (as specified by the \htmlref{Current}{Current} attribute).
+      }
+      \sstsubsection{
+         SkyFrame
+      }{
+         The SkyFrame class supports the following System values and
+         associated celestial coordinate systems:
+
+         \sstitemlist{
+
+            \sstitem
+             \texttt{"} AZEL\texttt{"} : Horizon coordinates. The longitude axis is azimuth
+            such that geographic north has an azimuth of zero and geographic
+            east has an azimuth of $+$PI/2 radians. The zenith has elevation
+            $+$PI/2. When converting to and from other celestial coordinate
+            systems, no corrections are applied for atmospheric refraction
+            or polar motion (however, a correction for diurnal aberattion is
+            applied). Note, unlike most other
+            celestial coordinate systems, this system is right handed. Also,
+            unlike other SkyFrame systems, the AzEl system is sensitive to
+            the timescale in which the \htmlref{Epoch}{Epoch} value is supplied. This is
+            because of the gross diurnal rotation which this system undergoes,
+            causing a small change in time to translate to a large rotation.
+            When converting to or from an AzEl system, the Epoch value for
+            both source and destination SkyFrames should be supplied in the
+            TDB timescale. The difference between TDB and TT is between 1
+            and 2 milliseconds, and so a TT value can usually be supplied in
+            place of a TDB value. The TT timescale is related to TAI via
+            TT = TAI $+$ 32.184 seconds.
+
+            \sstitem
+             \texttt{"} ECLIPTIC\texttt{"} : Ecliptic coordinates (IAU 1980), referred to the
+            ecliptic and mean equinox specified by the qualifying \htmlref{Equinox}{Equinox}
+            value.
+
+            \sstitem
+             \texttt{"} FK4\texttt{"} : The old FK4 (barycentric) equatorial coordinate system,
+            which should be qualified by an Equinox value. The underlying
+            model on which this is based is non-inertial and rotates slowly
+            with time, so for accurate work FK4 coordinate systems should
+            also be qualified by an Epoch value.
+
+            \sstitem
+             \texttt{"} FK4-NO-E\texttt{"}  or \texttt{"} FK4\_NO\_E\texttt{"} : The old FK4 (barycentric) equatorial
+            system but without the \texttt{"} E-terms of aberration\texttt{"}  (e.g. some radio
+            catalogues). This coordinate system should also be qualified by
+            both an Equinox and an Epoch value.
+
+            \sstitem
+             \texttt{"} FK5\texttt{"}  or \texttt{"} EQUATORIAL\texttt{"} : The modern FK5 (barycentric) equatorial
+            coordinate system. This should be qualified by an Equinox value.
+
+            \sstitem
+             \texttt{"} GALACTIC\texttt{"} : Galactic coordinates (IAU 1958).
+
+            \sstitem
+             \texttt{"} GAPPT\texttt{"} , \texttt{"} GEOCENTRIC\texttt{"}  or \texttt{"} APPARENT\texttt{"} : The geocentric apparent
+            equatorial coordinate system, which gives the apparent positions
+            of sources relative to the true plane of the Earth\texttt{'} s equator and
+            the equinox (the coordinate origin) at a time specified by the
+            qualifying Epoch value. (Note that no Equinox is needed to
+            qualify this coordinate system because no model \texttt{"} mean equinox\texttt{"}
+            is involved.)  These coordinates give the apparent right
+            ascension and declination of a source for a specified date of
+            observation, and therefore form an approximate basis for
+            pointing a telescope. Note, however, that they are applicable to
+            a fictitious observer at the Earth\texttt{'} s centre, and therefore
+            ignore such effects as atmospheric refraction and the (normally
+            much smaller) aberration of light due to the rotational velocity
+            of the Earth\texttt{'} s surface.  Geocentric apparent coordinates are
+            derived from the standard FK5 (J2000.0) barycentric coordinates
+            by taking account of the gravitational deflection of light by
+            the Sun (usually small), the aberration of light caused by the
+            motion of the Earth\texttt{'} s centre with respect to the barycentre
+            (larger), and the precession and nutation of the Earth\texttt{'} s spin
+            axis (normally larger still).
+
+            \sstitem
+             \texttt{"} HELIOECLIPTIC\texttt{"} : Ecliptic coordinates (IAU 1980), referred to the
+            ecliptic and mean equinox of J2000.0, in which an offset is added to
+            the longitude value which results in the centre of the sun being at
+            zero longitude at the date given by the Epoch attribute. Attempts to
+            set a value for the Equinox attribute will be ignored, since this
+            system is always referred to J2000.0.
+
+            \sstitem
+             \texttt{"} ICRS\texttt{"} : The Internation Celestial Reference System, realised
+            through the Hipparcos catalogue. Whilst not an equatorial system
+            by definition, the ICRS is very close to the FK5 (J2000) system
+            and is usually treated as an equatorial system. The distinction
+            between ICRS and FK5 (J2000) only becomes important when accuracies
+            of 50 milli-arcseconds or better are required. ICRS need not be
+            qualified by an Equinox value.
+
+            \sstitem
+             \texttt{"} J2000\texttt{"} : An equatorial coordinate system based on the mean
+            dynamical equator and equinox of the J2000 epoch. The dynamical
+            equator and equinox differ slightly from those used by the FK5
+            model, and so a \texttt{"} J2000\texttt{"}  SkyFrame will differ slightly from an
+            \texttt{"} FK5(Equinox=J2000)\texttt{"}  SkyFrame. The J2000 System need not be
+            qualified by an Equinox value
+
+            \sstitem
+             \texttt{"} SUPERGALACTIC\texttt{"} : De Vaucouleurs Supergalactic coordinates.
+
+            \sstitem
+             \texttt{"} UNKNOWN\texttt{"} : Any other general spherical coordinate system. No
+            \htmlref{Mapping}{Mapping} can be created between a pair of SkyFrames if either of the
+            SkyFrames has System set to \texttt{"} Unknown\texttt{"} .
+
+         }
+         Currently, the default System value is \texttt{"} ICRS\texttt{"} . However, this
+         default may change in future as new astrometric standards
+         evolve. The intention is to track the most modern appropriate
+         standard. For this reason, you should use the default only if
+         this is what you intend (and can tolerate any associated slight
+         change in future). If you intend to use the ICRS system
+         indefinitely, then you should specify it explicitly.
+      }
+      \sstsubsection{
+         SpecFrame
+      }{
+         The SpecFrame class supports the following System values and
+         associated spectral coordinate systems (the default is \texttt{"} WAVE\texttt{"}  -
+         wavelength). They are all defined in FITS-WCS paper III:
+
+         \sstitemlist{
+
+            \sstitem
+             \texttt{"} FREQ\texttt{"} : Frequency (GHz)
+
+            \sstitem
+             \texttt{"} ENER\texttt{"}  or \texttt{"} ENERGY\texttt{"} : Energy (J)
+
+            \sstitem
+             \texttt{"} WAVN\texttt{"}  or \texttt{"} WAVENUM\texttt{"} : Wave-number (1/m)
+
+            \sstitem
+             \texttt{"} WAVE\texttt{"}  or \texttt{"} WAVELEN\texttt{"} : Vacuum wave-length (Angstrom)
+
+            \sstitem
+             \texttt{"} AWAV\texttt{"}  or \texttt{"} AIRWAVE\texttt{"} : Wave-length in air (Angstrom)
+
+            \sstitem
+             \texttt{"} VRAD\texttt{"}  or \texttt{"} VRADIO\texttt{"} : Radio velocity (km/s)
+
+            \sstitem
+             \texttt{"} VOPT\texttt{"}  or \texttt{"} VOPTICAL\texttt{"} : Optical velocity (km/s)
+
+            \sstitem
+             \texttt{"} ZOPT\texttt{"}  or \texttt{"} REDSHIFT\texttt{"} : Redshift (dimensionless)
+
+            \sstitem
+             \texttt{"} BETA\texttt{"} : Beta factor (dimensionless)
+
+            \sstitem
+             \texttt{"} VELO\texttt{"}  or \texttt{"} VREL\texttt{"} : Apparent radial (\texttt{"} relativistic\texttt{"} ) velocity (km/s)
+
+         }
+         The default value for the Unit attribute for each system is shown
+         in parentheses. Note that the default value for the ActiveUnit flag
+         is non-zero
+         for a SpecFrame, meaning that changes to the Unit attribute for
+         a SpecFrame will result in the SpecFrame being re-mapped within
+         its enclosing FrameSet in order to reflect the change in units
+         (see \htmlref{astSetActiveUnit}{astSetActiveUnit} function for further information).
+      }
+      \sstsubsection{
+         \htmlref{TimeFrame}{TimeFrame}
+      }{
+         The TimeFrame class supports the following System values and
+         associated coordinate systems (the default is \texttt{"} MJD\texttt{"} ):
+
+         \sstitemlist{
+
+            \sstitem
+             \texttt{"} MJD\texttt{"} : Modified Julian Date (d)
+
+            \sstitem
+             \texttt{"} JD\texttt{"} : Julian Date (d)
+
+            \sstitem
+             \texttt{"} JEPOCH\texttt{"} : Julian epoch (yr)
+
+            \sstitem
+             \texttt{"} BEPOCH\texttt{"} : Besselian (yr)
+
+         }
+         The default value for the Unit attribute for each system is shown
+         in parentheses. Strictly, these systems should not allow changes
+         to be made to the units. For instance, the usual definition of
+         \texttt{"} MJD\texttt{"}  and \texttt{"} JD\texttt{"}  include the statement that the values will be in
+         units of days. However, AST does allow the use of other units
+         with all the above supported systems (except BEPOCH), on the
+         understanding that conversion to the \texttt{"} correct\texttt{"}  units involves
+         nothing more than a simple scaling (1 yr = 365.25 d, 1 d = 24 h,
+         1 h = 60 min, 1 min = 60 s). Besselian epoch values are defined
+         in terms of tropical years of 365.2422 days, rather than the
+         usual Julian year of 365.25 days. Therefore, to avoid any
+         confusion, the Unit attribute is automatically cleared to \texttt{"} yr\texttt{"}  when
+         a System value of BEPOCH System is selected, and an error is
+         reported if any attempt is subsequently made to change the Unit
+         attribute.
+
+         Note that the default value for the ActiveUnit flag
+         is non-zero
+         for a TimeFrame, meaning that changes to the Unit attribute for
+         a TimeFrame will result in the TimeFrame being re-mapped within
+         its enclosing FrameSet in order to reflect the change in units
+         (see astSetActiveUnit function for further information).
+      }
+      \sstsubsection{
+         \htmlref{FluxFrame}{FluxFrame}
+      }{
+         The FluxFrame class supports the following System values and
+         associated systems for measuring observed value:
+
+         \sstitemlist{
+
+            \sstitem
+             \texttt{"} FLXDN\texttt{"} : Flux per unit frequency (W/m$\wedge$2/Hz)
+
+            \sstitem
+             \texttt{"} FLXDNW\texttt{"} : Flux per unit wavelength (W/m$\wedge$2/Angstrom)
+
+            \sstitem
+             \texttt{"} SFCBR\texttt{"} : Surface brightness in frequency units (W/m$\wedge$2/Hz/arcmin$*$$*$2)
+
+            \sstitem
+             \texttt{"} SFCBRW\texttt{"} : Surface brightness in wavelength units (W/m$\wedge$2/Angstrom/arcmin$*$$*$2)
+
+         }
+         The above lists specified the default units for each System. If an
+         explicit value is set for the Unit attribute but no value is set
+         for System, then the default System value is determined by the Unit
+         string (if the units are not appropriate for describing any of the
+         supported Systems then an error will be reported when an attempt is
+         made to access the System value). If no value has been specified for
+         either Unit or System, then System=FLXDN and Unit=W/m$\wedge$2/Hz are
+         used.
+      }
+   }
+}
+\sstroutine{
+   TabOK
+}{
+   Should the FITS-WCS -TAB algorithm be recognised?
+}{
+   \sstdescription{
+      This attribute is an integer value which indicates if the \texttt{"} -TAB\texttt{"}
+      algorithm, defined in FITS-WCS paper III, should be supported by
+      the \htmlref{FitsChan}{FitsChan}. The default value is zero. A zero or negative value
+      results in no support for -TAB axes (i.e. axes that have \texttt{"} -TAB\texttt{"}
+      in their CTYPE keyword value). In this case, the
+      \htmlref{astWrite}{astWrite}
+      method will return zero if the write operation would required the
+      use of the -TAB algorithm, and the
+      \htmlref{astRead}{astRead}
+      method will return
+      a NULL pointer
+      if any axis in the supplied header uses the -TAB algorithm.
+
+      If TabOK is set to a non-zero positive integer, these methods will
+      recognise and convert axes described by the -TAB algorithm, as
+      follows:
+
+      The astWrite
+      method will generate headers that use the -TAB algorithm (if
+      possible) if no other known FITS-WCS algorithm can be used to
+      describe the supplied \htmlref{FrameSet}{FrameSet}. This will result in a table of
+      coordinate values and index vectors being stored in the FitsChan.
+      After the write operation, the calling application should check to
+      see if such a table has been stored in the FitsChan. If so, the
+      table should be retrived from the FitsChan using the
+      \htmlref{astGetTables}{astGetTables}
+      method, and the data (and headers) within it copied into a new
+      FITS binary table extension. See
+      astGetTables
+      for more information. The FitsChan uses a \htmlref{FitsTable}{FitsTable} object to store
+      the table data and headers. This FitsTable will contain the required
+      columns and headers as described by FITS-WCS paper III - the
+      coordinates array will be in a column named \texttt{"} COORDS\texttt{"} , and the index
+      vector(s) will be in columns named \texttt{"} INDEX$<$i$>$\texttt{"}  (where $<$i$>$ is the index
+      of the corresponding FITS WCS  axis). Note, index vectors are only
+      created if required. The EXTNAME value will be set to the value of the
+      AST\_\_TABEXTNAME constant (currently \texttt{"} WCS-TAB\texttt{"} ). The EXTVER header
+      will be set to the positive integer value assigned to the TabOK
+      attribute. No value will be stored for the EXTLEVEL header, and should
+      therefore be considered to default to 1.
+
+      The astRead
+      method will generate a FrameSet from headers that use the -TAB
+      algorithm so long as the necessary FITS binary tables are made
+      available. There are two ways to do this: firstly, if the application
+      knows which FITS binary tables will be needed, then it can create a
+      Fitstable describing each such table and store it in the FitsChan
+      (using method
+      \htmlref{astPutTables}{astPutTables} or \htmlref{astPutTable}{astPutTable}) before invoking the astRead method.
+      Secondly, if the application does not know which FITS binary tables
+      will be needed by
+      astRead,
+      then it can register a call-back function with the FitsChan using
+      method
+      \htmlref{astTableSource}{astTableSource}.
+      This call-back function will be called from within
+      astRead
+      if and when a -TAB header is encountered. When called, its arguments
+      will give the name, version and level of the FITS extension containing
+      a required table. The call-back function should read this table from
+      an external FITS file, and create a corresponding FitsTable which
+      it should then return to
+      astRead. Note, currently astRead
+      can only handle -TAB headers that describe 1-dimensional (i.e.
+      separable) axes.
+   }
+   \sstattributetype{
+      Integer.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         FitsChan
+      }{
+         All FitsChans have this attribute.
+      }
+   }
+}
+\sstroutine{
+   TextLab(axis)
+}{
+   Draw descriptive axis labels for a Plot?
+}{
+   \sstdescription{
+      This attribute controls the appearance of an annotated
+      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
+      whether textual labels should be drawn to describe the quantity
+      being represented on each axis of a \htmlref{Plot}{Plot}. It takes a separate
+      value for each physical axis of a Plot so that, for instance,
+      the setting \texttt{"} TextLab(2)=1\texttt{"}  specifies that descriptive labels
+      should be drawn for the second axis.
+
+      If the TextLab value of a Plot axis is non-zero, then
+      descriptive labels will be drawn for that axis, otherwise they
+      will be omitted. The default behaviour is to draw descriptive
+      labels if tick marks and numerical labels are being drawn around
+      the edges of the plotting area (see the \htmlref{Labelling}{Labelling} attribute),
+      but to omit them otherwise.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The text used for the descriptive labels is derived from the
+         Plot\texttt{'} s \htmlref{Label(axis)}{Label(axis)} attribute, together with its \htmlref{Unit(axis)}{Unit(axis)}
+         attribute if appropriate (see the \htmlref{LabelUnits(axis)}{LabelUnits(axis)} attribute).
+
+         \sstitem
+          The drawing of numerical axis labels for a Plot (which
+         indicate values on the axis) is controlled by the \htmlref{NumLab(axis)}{NumLab(axis)}
+         attribute.
+
+         \sstitem
+          If no axis is specified, (e.g. \texttt{"} TextLab\texttt{"}  instead of
+         \texttt{"} TextLab(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect
+         the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or
+         \texttt{"} test\texttt{"}  operation will use just the TextLab(1) value.
+      }
+   }
+}
+\sstroutine{
+   TextLabGap(axis)
+}{
+   Spacing of descriptive axis labels for a Plot
+}{
+   \sstdescription{
+      This attribute controls the appearance of an annotated
+      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
+      where descriptive axis labels are placed relative to the axes they
+      describe.  It takes a separate value for each physical axis of a
+      \htmlref{Plot}{Plot} so that, for instance, the setting \texttt{"} TextLabGap(2)=0.01\texttt{"}
+      specifies where the descriptive label for the second axis should
+      be drawn.
+
+      For each axis, the TextLabGap value gives the spacing between the
+      descriptive label and the edge of a box enclosing all other parts
+      of the annotated grid (excluding other descriptive labels). The gap
+      is measured to the nearest edge of the label (i.e. the top or the
+      bottom). Positive values cause the descriptive label to be placed
+      outside the bounding box, while negative values cause it to be placed
+      inside.
+
+      The TextLabGap value should be given as a fraction of the minimum
+      dimension of the plotting area, the default value being $+$0.01.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If drawn, descriptive labels are always placed at the edges of
+         the plotting area, even although the corresponding numerical
+         labels may be drawn along axis lines in the interior of the
+         plotting area (see the \htmlref{Labelling}{Labelling} attribute).
+
+         \sstitem
+          If no axis is specified, (e.g. \texttt{"} TextLabGap\texttt{"}  instead of
+         \texttt{"} TextLabGap(2)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect
+         the attribute value of all the Plot axes, while a \texttt{"} get\texttt{"}  or
+         \texttt{"} test\texttt{"}  operation will use just the TextLabGap(1) value.
+      }
+   }
+}
+\sstroutine{
+   TickAll
+}{
+   Draw tick marks on all edges of a Plot?
+}{
+   \sstdescription{
+      This attribute controls the appearance of an annotated
+      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
+      whether tick marks should be drawn on all edges of a \htmlref{Plot}{Plot}.
+
+      If the TickAll value of a Plot is non-zero (the default), then
+      tick marks will be drawn on all edges of the Plot. Otherwise,
+      they will be drawn only on those edges where the numerical and
+      descriptive axis labels are drawn (see the \htmlref{Edge(axis)}{Edge(axis)}
+      attribute).
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          In some circumstances, numerical labels and tick marks are
+         drawn along grid lines inside the plotting area, rather than
+         around its edges (see the \htmlref{Labelling}{Labelling} attribute).  In this case,
+         the value of the TickAll attribute is ignored.
+      }
+   }
+}
+\sstroutine{
+   TimeOrigin
+}{
+   The zero point for TimeFrame axis values
+}{
+   \sstdescription{
+      This specifies the origin from which all time values are measured.
+      The default value (zero) results in the \htmlref{TimeFrame}{TimeFrame} describing
+      absolute time values in the system given by the \htmlref{System}{System} attribute
+      (e.g. MJD, Julian epoch, etc). If a TimeFrame is to be used to
+      describe elapsed time since some origin, the TimeOrigin attribute
+      should be set to hold the required origin value. The TimeOrigin value
+      stored inside the TimeFrame structure is modified whenever TimeFrame
+      attribute values are changed so that it refers to the original moment
+      in time.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         TimeFrame
+      }{
+         All TimeFrames have this attribute.
+      }
+   }
+   \sstdiytopic{
+      Input Formats
+   }{
+      The formats accepted when setting a TimeOrigin value are listed
+      below. They are all case-insensitive and are generally tolerant
+      of extra white space and alternative field delimiters:
+
+      \sstitemlist{
+
+         \sstitem
+          Besselian \htmlref{Epoch}{Epoch}: Expressed in decimal years, with or without
+         decimal places (\texttt{"} B1950\texttt{"}  or \texttt{"} B1976.13\texttt{"}  for example).
+
+         \sstitem
+          Julian Epoch: Expressed in decimal years, with or without
+         decimal places (\texttt{"} J2000\texttt{"}  or \texttt{"} J2100.9\texttt{"}  for example).
+
+         \sstitem
+          Units: An unqualified decimal value is interpreted as a value in
+         the system specified by the TimeFrame\texttt{'} s System attribute, in the
+         units given by the TimeFrame\texttt{'} s Unit attribute. Alternatively, an
+         appropriate unit string can be appended to the end of the floating
+         point value (\texttt{"} 123.4 d\texttt{"}  for example), in which case the supplied value
+         is scaled into the units specified by the Unit attribute.
+
+         \sstitem
+          Julian Date: With or without decimal places (\texttt{"} JD 2454321.9\texttt{"}  for
+         example).
+
+         \sstitem
+          Modified Julian Date: With or without decimal places
+         (\texttt{"} MJD 54321.4\texttt{"}  for example).
+
+         \sstitem
+          Gregorian Calendar Date: With the month expressed either as an
+         integer or a 3-character abbreviation, and with optional decimal
+         places to represent a fraction of a day (\texttt{"} 1996-10-2\texttt{"}  or
+         \texttt{"} 1996-Oct-2.6\texttt{"}  for example). If no fractional part of a day is
+         given, the time refers to the start of the day (zero hours).
+
+         \sstitem
+          Gregorian Date and Time: Any calendar date (as above) but with
+         a fraction of a day expressed as hours, minutes and seconds
+         (\texttt{"} 1996-Oct-2 12:13:56.985\texttt{"}  for example). The date and time can be
+         separated by a space or by a \texttt{"} T\texttt{"}  (as used by ISO8601 format).
+      }
+   }
+   \sstdiytopic{
+      Output Format
+   }{
+      When enquiring TimeOrigin values, the returned formatted floating
+      point value represents a value in the TimeFrame\texttt{'} s System, in the unit
+      specified by the TimeFrame\texttt{'} s Unit attribute.
+   }
+}
+\sstroutine{
+   TimeScale
+}{
+   Time scale
+}{
+   \sstdescription{
+      This attribute identifies the time scale to which the time axis values
+      of a \htmlref{TimeFrame}{TimeFrame} refer, and may take any of the values listed in the
+      \texttt{"} Time Scales\texttt{"}  section (below).
+
+      The default TimeScale value depends on the current \htmlref{System}{System} value; if
+      the current TimeFrame system is \texttt{"} Besselian epoch\texttt{"}  the default is
+      \texttt{"} TT\texttt{"} , otherwise it is \texttt{"} TAI\texttt{"} . Note, if the System attribute is set
+      so that the TimeFrame represents Besselian \htmlref{Epoch}{Epoch}, then an error
+      will be reported if an attempt is made to set the TimeScale to
+      anything other than TT.
+
+      Note, the supported time scales fall into two groups. The first group
+      containing  UT1, GMST, LAST and LMST define time in terms of the
+      orientation of the earth. The second group (containing all the remaining
+      time scales) define time in terms of an atomic process. Since the rate of
+      rotation of the earth varies in an unpredictable way, conversion between
+      two timescales in different groups relies on a value being supplied for
+      the \htmlref{Dut1}{Dut1} attribute (defined by the parent \htmlref{Frame}{Frame} class). This attribute
+      specifies the difference between the UT1 and UTC time scales, in seconds,
+      and defaults to zero. See the documentation for the Dut1 attribute for
+      further details.
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         TimeFrame
+      }{
+         All TimeFrames have this attribute.
+      }
+   }
+   \sstdiytopic{
+      Time Scales
+   }{
+      The TimeFrame class supports the following TimeScale values (all are
+      case-insensitive):
+
+      \sstitemlist{
+
+         \sstitem
+          \texttt{"} TAI\texttt{"}  - International Atomic Time
+
+         \sstitem
+          \texttt{"} UTC\texttt{"}  - Coordinated Universal Time
+
+         \sstitem
+          \texttt{"} UT1\texttt{"}  - Universal Time
+
+         \sstitem
+          \texttt{"} GMST\texttt{"}  - Greenwich Mean Sidereal Time
+
+         \sstitem
+          \texttt{"} LAST\texttt{"}  - Local Apparent Sidereal Time
+
+         \sstitem
+          \texttt{"} LMST\texttt{"}  - Local Mean Sidereal Time
+
+         \sstitem
+          \texttt{"} TT\texttt{"}  - Terrestrial Time
+
+         \sstitem
+          \texttt{"} TDB\texttt{"}  - Barycentric Dynamical Time
+
+         \sstitem
+          \texttt{"} TCB\texttt{"}  - Barycentric Coordinate Time
+
+         \sstitem
+          \texttt{"} TCG\texttt{"}  - Geocentric Coordinate Time
+
+         \sstitem
+          \texttt{"} LT\texttt{"}  - Local Time (the offset from UTC is given by attribute \htmlref{LTOffset}{LTOffset})
+
+      }
+      An very informative description of these and other time scales is
+      available at http://www.ucolick.org/$\sim$sla/leapsecs/timescales.html.
+   }
+   \sstdiytopic{
+      UTC \htmlref{Warnings}{Warnings}
+   }{
+      UTC should ideally be expressed using separate hours, minutes and
+      seconds fields (or at least in seconds for a given date) if leap seconds
+      are to be taken into account. Since the TimeFrame class represents
+      each moment in time using a single floating point number (the axis value)
+      there will be an ambiguity during a leap second. Thus an error of up to
+      1 second can result when using AST to convert a UTC time to another
+      time scale if the time occurs within a leap second. Leap seconds
+      occur at most twice a year, and are introduced to take account of
+      variation in the rotation of the earth. The most recent leap second
+      occurred on 1st January 1999. Although in the vast majority of cases
+      leap second ambiguities won\texttt{'} t matter, there are potential problems in
+      on-line data acquisition systems and in critical applications involving
+      taking the difference between two times.
+   }
+}
+\sstroutine{
+   Title
+}{
+   Frame title
+}{
+   \sstdescription{
+      This attribute holds a string which is used as a title in (e.g.)
+      graphical output to describe the coordinate system which a \htmlref{Frame}{Frame}
+      represents. Examples might be \texttt{"} Detector Coordinates\texttt{"}  or
+      \texttt{"} Galactic Coordinates\texttt{"} .
+
+      If a Title value has not been set for a Frame, then a suitable
+      default is supplied, depending on the class of the Frame.
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Frame
+      }{
+         The default supplied by the Frame class is \texttt{"} $<$n$>$-d coordinate
+         system\texttt{"} , where $<$n$>$ is the number of Frame axes (\htmlref{Naxes}{Naxes}
+         attribute).
+      }
+      \sstsubsection{
+         \htmlref{CmpFrame}{CmpFrame}
+      }{
+         The CmpFrame class re-defines the default Title value to be
+         \texttt{"} $<$n$>$-d compound coordinate system\texttt{"} , where $<$n$>$ is the number
+         of CmpFrame axes (Naxes attribute).
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         The Title attribute of a FrameSet is the same as that of its
+         current Frame (as specified by the \htmlref{Current}{Current} attribute).
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A Frame\texttt{'} s Title is intended purely for interpretation by human
+         readers and not by software.
+      }
+   }
+}
+\sstroutine{
+   TitleGap
+}{
+   Vertical spacing for a Plot title
+}{
+   \sstdescription{
+      This attribute controls the appearance of an annotated
+      coordinate grid (drawn with the \htmlref{astGrid}{astGrid} function) by determining
+      where the title of a \htmlref{Plot}{Plot} is drawn.
+
+      Its value gives the spacing between the bottom edge of the title
+      and the top edge of a bounding box containing all the other parts
+      of the annotated grid. Positive values cause the title to be
+      drawn outside the box, while negative values cause it to be drawn
+      inside.
+
+      The TitleGap value should be given as a fraction of the minimum
+      dimension of the plotting area, the default value being $+$0.05.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+      \sstsubsection{
+         \htmlref{Plot3D}{Plot3D}
+      }{
+         The Plot3D class ignores this attributes since it does not draw
+         a \htmlref{Title}{Title}.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The text used for the title is obtained from the Plot\texttt{'} s Title
+         attribute.
+      }
+   }
+}
+\sstroutine{
+   Tol
+}{
+   Plotting tolerance
+}{
+   \sstdescription{
+      This attribute specifies the plotting tolerance (or resolution)
+      to be used for the graphical output produced by a \htmlref{Plot}{Plot}.  Smaller
+      values will result in smoother and more accurate curves being
+      drawn, but may slow down the plotting process. Conversely,
+      larger values may speed up the plotting process in cases where
+      high resolution is not required.
+
+      The Tol value should be given as a fraction of the minimum
+      dimension of the plotting area, and should lie in the range
+      from 1.0e-7 to 1.0. By default, a value of 0.01 is used.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+}
+\sstroutine{
+   TolInverse
+}{
+   Target relative error for the iterative inverse transformation
+}{
+   \sstdescription{
+      This attribute controls the iterative inverse transformation
+      used if the \htmlref{IterInverse}{IterInverse} attribute is non-zero.
+
+      Its value gives the target relative error in the axis values of
+      each transformed position. Further iterations will be performed
+      until the target relative error is reached, or the maximum number
+      of iterations given by attribute \htmlref{NiterInverse}{NiterInverse} is reached.
+
+      The default value is 1.0E-6.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{PolyMap}{PolyMap}
+      }{
+         All PolyMaps have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Top(axis)
+}{
+   Highest axis value to display
+}{
+   \sstdescription{
+      This attribute gives the highest axis value to be displayed (for
+      instance, by the \htmlref{astGrid}{astGrid} method).
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{Frame}{Frame}
+      }{
+         The default supplied by the Frame class is to display all axis
+         values, without any limit.
+      }
+      \sstsubsection{
+         \htmlref{SkyFrame}{SkyFrame}
+      }{
+         The SkyFrame class re-defines the default Top value to $+$90 degrees
+         for latitude axes, and 180 degrees for co-latitude axes. The
+         default for longitude axes is to display all axis values.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          When specifying this attribute by name, it should be
+         subscripted with the number of the Frame axis to which it
+         applies.
+      }
+   }
+}
+\sstroutine{
+   TranForward
+}{
+   Forward transformation defined?
+}{
+   \sstdescription{
+      This attribute indicates whether a \htmlref{Mapping}{Mapping} is able to transform
+      coordinates in the \texttt{"} forward\texttt{"}  direction (i.e. converting input
+      coordinates into output coordinates). If this attribute is
+      non-zero, the forward transformation is available. Otherwise, it
+      is not.
+   }
+   \sstattributetype{
+      Integer (boolean), read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Mapping
+      }{
+         All Mappings have this attribute.
+      }
+      \sstsubsection{
+         \htmlref{CmpMap}{CmpMap}
+      }{
+         The TranForward attribute value for a CmpMap is given by the
+         boolean AND of the value for each component Mapping.
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         The TranForward attribute of a FrameSet applies to the
+         transformation which converts between the FrameSet\texttt{'} s base
+         \htmlref{Frame}{Frame} and its current Frame (as specified by the \htmlref{Base}{Base} and
+         \htmlref{Current}{Current} attributes). This value is given by the boolean AND
+         of the TranForward values which apply to each of the
+         individual sub-Mappings required to perform this conversion.
+         The TranForward attribute value for a FrameSet may therefore
+         change if a new Base or Current Frame is selected.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          An error will result if a Mapping with a TranForward value of
+         zero is used to transform coordinates in the forward direction.
+      }
+   }
+}
+\sstroutine{
+   TranInverse
+}{
+   Inverse transformation defined?
+}{
+   \sstdescription{
+      This attribute indicates whether a \htmlref{Mapping}{Mapping} is able to transform
+      coordinates in the \texttt{"} inverse\texttt{"}  direction (i.e. converting output
+      coordinates back into input coordinates). If this attribute is
+      non-zero, the inverse transformation is available. Otherwise, it
+      is not.
+   }
+   \sstattributetype{
+      Integer (boolean), readonly.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Mapping
+      }{
+         All Mappings have this attribute.
+      }
+      \sstsubsection{
+         \htmlref{CmpMap}{CmpMap}
+      }{
+         The TranInverse attribute value for a CmpMap is given by the
+         boolean AND of the value for each component Mapping.
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         The TranInverse attribute of a FrameSet applies to the
+         transformation which converts between the FrameSet\texttt{'} s current
+         \htmlref{Frame}{Frame} and its base Frame (as specified by the \htmlref{Current}{Current} and
+         \htmlref{Base}{Base} attributes). This value is given by the boolean AND of
+         the TranInverse values which apply to each of the individual
+         sub-Mappings required to perform this conversion.
+         The TranInverse attribute value for a FrameSet may therefore
+         change if a new Base or Current Frame is selected.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          An error will result if a Mapping with a TranInverse value of
+         zero is used to transform coordinates in the inverse direction.
+      }
+   }
+}
+\sstroutine{
+   Unit(axis)
+}{
+   Physical units for formatted axis values
+}{
+   \sstdescription{
+      This attribute contains a textual representation of the physical
+      units used to represent formatted coordinate values on a particular
+      axis of a \htmlref{Frame}{Frame}.
+      The \htmlref{astSetActiveUnit}{astSetActiveUnit} function controls how the Unit values
+      are used.
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Frame
+      }{
+         The default supplied by the Frame class is an empty string.
+      }
+      \sstsubsection{
+         \htmlref{SkyFrame}{SkyFrame}
+      }{
+         The SkyFrame class re-defines the default Unit value (e.g. to
+         \texttt{"} hh:mm:ss.sss\texttt{"} ) to describe the character string returned by
+         the \htmlref{astFormat}{astFormat} function when formatting coordinate values.
+      }
+      \sstsubsection{
+         \htmlref{SpecFrame}{SpecFrame}
+      }{
+         The SpecFrame class re-defines the default Unit value so that it
+         is appropriate for the current \htmlref{System}{System} value. See the System
+         attribute for details. An error will be reported if an attempt
+         is made to use an inappropriate Unit.
+      }
+      \sstsubsection{
+         \htmlref{TimeFrame}{TimeFrame}
+      }{
+         The TimeFrame class re-defines the default Unit value so that it
+         is appropriate for the current System value. See the System
+         attribute for details. An error will be reported if an attempt
+         is made to use an inappropriate Unit (e.g. \texttt{"} km\texttt{"} ).
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         The Unit attribute of a FrameSet axis is the same as that of
+         its current Frame (as specified by the \htmlref{Current}{Current} attribute).
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This attribute described the units used when an axis value is
+         formatted into a string using
+         astFormat.
+         In some cases these units may be different to those used to represent
+         floating point axis values within application code (for instance a
+         SkyFrame always uses radians to represent floating point axis values).
+         The InternalUnit attribute described the units used for floating
+         point values.
+
+         \sstitem
+          When specifying this attribute by name, it should be
+         subscripted with the number of the Frame axis to which it
+         applies.
+      }
+   }
+}
+\sstroutine{
+   UnitRadius
+}{
+   SphMap input vectors lie on a unit sphere?
+}{
+   \sstdescription{
+      This is a boolean attribute which indicates whether the
+      3-dimensional vectors which are supplied as input to a \htmlref{SphMap}{SphMap}
+      are known to always have unit length, so that they lie on a unit
+      sphere centred on the origin.
+
+      If this condition is true (indicated by setting UnitRadius
+      non-zero), it implies that a \htmlref{CmpMap}{CmpMap} which is composed of a
+      SphMap applied in the forward direction followed by a similar
+      SphMap applied in the inverse direction may be simplified
+      (e.g. by \htmlref{astSimplify}{astSimplify}) to become a \htmlref{UnitMap}{UnitMap}. This is because the
+      input and output vectors will both have unit length and will
+      therefore have the same coordinate values.
+
+      If UnitRadius is zero (the default), then although the output
+      vector produced by the CmpMap (above) will still have unit
+      length, the input vector may not have. This will, in general,
+      change the coordinate values, so it prevents the pair of SphMaps
+      being simplified.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         SphMap
+      }{
+         All SphMaps have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This attribute is intended mainly for use when SphMaps are
+         involved in a sequence of Mappings which project (e.g.) a
+         dataset on to the celestial sphere. By regarding the celestial
+         sphere as a unit sphere (and setting UnitRadius to be non-zero)
+         it becomes possible to cancel the SphMaps present, along with
+         associated sky projections, when two datasets are aligned using
+         celestial coordinates. This often considerably improves
+         performance.
+
+         \sstitem
+          Such a situations often arises when interpreting FITS data and
+         is handled automatically by the \htmlref{FitsChan}{FitsChan} class.
+
+         \sstitem
+          The value of the UnitRadius attribute is used only to control
+         the simplification of Mappings and has no effect on the value of
+         the coordinates transformed by a SphMap. The lengths of the
+         input 3-dimensional Cartesian vectors supplied are always
+         ignored, even if UnitRadius is non-zero.
+
+         \sstitem
+          The value of this attribute may changed only if the SphMap
+         has no more than one reference. That is, an error is reported if the
+         SphMap has been cloned, either by including it within another object
+         such as a CmpMap or \htmlref{FrameSet}{FrameSet} or by calling the
+         \htmlref{astClone}{astClone}
+         function.
+      }
+   }
+}
+\sstroutine{
+   UseDefs
+}{
+   Use default values for unspecified attributes?
+}{
+   \sstdescription{
+      This attribute specifies whether default values should be used
+      internally for object attributes which have not been assigned a
+      value explicitly. If a non-zero value (the default) is supplied for
+      UseDefs, then default values will be used for attributes which have
+      not explicitly been assigned a value. If zero is supplied for UseDefs,
+      then an error will be reported if an attribute for which no explicit
+      value has been supplied is needed internally within AST.
+
+      Many attributes (including the UseDefs attribute itself) are unaffected
+      by the setting of the UseDefs attribute, and default values will always
+      be used without error for such attributes. The \texttt{"} Applicability:\texttt{"}  section
+      below lists the attributes which are affected by the setting of UseDefs.
+
+      Note, UseDefs only affects access to attributes internally within
+      AST. The public accessor functions such as
+      astGetC
+      is unaffected by the UseDefs attribute - default values will always
+      be returned if no value has been set. Application code should use the
+      \htmlref{astTest}{astTest}
+      function if required to determine if a value has been set for an
+      attribute.
+   }
+   \sstattributetype{
+      Integer (boolean).
+   }
+   \sstapplicability{
+      \sstsubsection{
+         \htmlref{Object}{Object}
+      }{
+         All Objects have this attribute, but ignore its setting except
+         as described below for individual classes.
+      }
+      \sstsubsection{
+         \htmlref{FrameSet}{FrameSet}
+      }{
+         The default value of UseDefs for a FrameSet is redefined to be
+         the UseDefs value of its current \htmlref{Frame}{Frame}.
+      }
+      \sstsubsection{
+         \htmlref{CmpFrame}{CmpFrame}
+      }{
+         The default value of UseDefs for a CmpFrame is redefined to be
+         the UseDefs value of its first component Frame.
+      }
+      \sstsubsection{
+         \htmlref{Region}{Region}
+      }{
+         The default value of UseDefs for a Region is redefined to be
+         the UseDefs value of its encapsulated Frame.
+      }
+      \sstsubsection{
+         Frame
+      }{
+         If UseDefs is zero, an error is reported when aligning Frames if the
+         \htmlref{Epoch}{Epoch}, \htmlref{ObsLat}{ObsLat} or \htmlref{ObsLon}{ObsLon} attribute is required but has not been
+         assigned a value explicitly.
+      }
+      \sstsubsection{
+         \htmlref{SkyFrame}{SkyFrame}
+      }{
+         If UseDefs is zero, an error is reported when aligning SkyFrames
+         if any of the following attributes are required but have not been
+         assigned a value explicitly: Epoch, \htmlref{Equinox}{Equinox}.
+      }
+      \sstsubsection{
+         \htmlref{SpecFrame}{SpecFrame}
+      }{
+         If UseDefs is zero, an error is reported when aligning SpecFrames
+         if any of the following attributes are required but have not been
+         assigned a value explicitly: Epoch, \htmlref{RefRA}{RefRA}, \htmlref{RefDec}{RefDec}, \htmlref{RestFreq}{RestFreq},
+         \htmlref{SourceVel}{SourceVel}, \htmlref{StdOfRest}{StdOfRest}.
+      }
+      \sstsubsection{
+         \htmlref{DSBSpecFrame}{DSBSpecFrame}
+      }{
+         If UseDefs is zero, an error is reported when aligning DSBSpecFrames
+         or when accessing the \htmlref{ImagFreq}{ImagFreq} attribute if any of the following
+         attributes are required but have not been assigned a value explicitly:
+         Epoch, \htmlref{DSBCentre}{DSBCentre}, \htmlref{IF}{IF}.
+      }
+   }
+}
+\sstroutine{
+   Variant
+}{
+   Indicates which variant of the current Frame is to be used
+}{
+   \sstdescription{
+      This attribute can be used to change the \htmlref{Mapping}{Mapping} that connects the
+      current \htmlref{Frame}{Frame} to the other Frames in the \htmlref{FrameSet}{FrameSet}. By default, each
+      Frame in a FrameSet is connected to the other Frames by a single
+      Mapping that can only be changed by using the
+      \htmlref{astRemapFrame}{astRemapFrame}
+      method. However, it is also possible to associate multiple Mappings
+      with a Frame, each Mapping having an identifying name. If this is
+      done, the \texttt{"} Variant\texttt{"}  attribute can be set to indicate the name of
+      the Mapping that is to be used with the current Frame.
+
+      A possible (if unlikely) use-case is to create a FrameSet that can
+      be used to describe the WCS of an image formed by co-adding images
+      of two different parts of the sky. In such an image, each pixel contains
+      flux from two points on the sky.and so the WCS for the image should
+      ideally contain one pixel Frame and two SkyFrames - one describing
+      each of the two co-added images. There is nothing to prevent a
+      FrameSet containing two explicit SkyFrames, but the problem then arises
+      of how to distinguish between them. The two primary characteristics of
+      a Frame that distinguishes it from other Frames  are its class and its
+      \htmlref{Domain}{Domain} attribute value. The class of a Frame cannot be changed, but we
+      could in principle use two different Domain values to distinguish the
+      two SkyFrames. However, in practice it is not uncommon for application
+      software to assume that SkyFrames will have the default Domain value
+      of \texttt{"} SKY\texttt{"} . That is, instead of searching for Frames that have a class
+      of \texttt{"} \htmlref{SkyFrame}{SkyFrame}\texttt{"} , such software searches for Frames that have a Domain
+      of \texttt{"} SKY\texttt{"} . To alleviate this problem, it is possible to add a single
+      SkyFrame to the FrameSet, but specifying two alternate Mappings to
+      use with the SkyFrame. Setting the \texttt{"} Variant\texttt{"}  attribute to the name
+      of one or the other of these alternate Mappings will cause the
+      SkyFrame to be remapped within the FrameSet so that it uses the
+      specified Mapping. The same facility can be used with any class of
+      Frame, not just SkyFrames.
+
+      To use this facility, the Frame should first be added to the
+      FrameSet in the usual manner using the
+      \htmlref{astAddFrame}{astAddFrame} method. By default, the Mapping supplied to astAddFrame
+      is assigned a name equal to the Domain name of the Frame. To assign a
+      different name to it, the
+      \htmlref{astAddVariant}{astAddVariant}
+      method should then be called specifying the required name and a NULL
+      Mapping. The
+      astAddVariant
+      method should then be called repeatedly to add each required extra
+      Mapping to the current Frame, supplying a unique name for each one.
+
+      Each Frame in a FrameSet can have its own set of variant Mappings.
+      To control the Mappings in use with a specific Frame, you need first
+      to make it the current Frame in the FrameSet.
+
+      The
+      \htmlref{astMirrorVariants}{astMirrorVariants} function
+      allows the effects of variant Mappings associated with a nominated
+      Frame to be propagated to other Frames in the FrameSet.
+
+      Once this has been done, setting a new value for the \texttt{"} Variant\texttt{"}
+      attribute of a FrameSet will cause the current Frame in the
+      FrameSet to be remapped to use the specified variant Mapping. An
+      error will be reported if the current Frame has no variant Mapping
+      with the supplied name.
+
+      Getting the value of the \texttt{"} Variant\texttt{"}  attribute will return the name
+      of the variant Mapping currently in use with the current Frame. If
+      the Frame has no variant Mappings, the value will default to the
+      Domain name of the current Frame.
+
+      Clearing the \texttt{"} Variant\texttt{"}  attribute will have the effect of removing
+      all variant Mappings (except for the currently selected Mapping) from
+      the current Frame.
+
+      Testing the \texttt{"} Variant\texttt{"}  attribute will return
+      a non-zero value
+      if the current Frame contains any variant Mappings, and
+      zero
+      otherwise.
+
+      A complete list of the names associated with all the available
+      variant Mappings in the current Frame can be obtained from the
+      \htmlref{AllVariants}{AllVariants} attribute.
+
+      If a Frame with variant Mappings is remapped using the
+      astRemapFrame
+      method, the currently selected variant Mapping is used by
+      astRemapFrame
+      and the other variant Mappings are removed from the Frame.
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         FrameSet
+      }{
+         All FrameSets have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Warnings
+}{
+   Controls the issuing of warnings about various conditions
+}{
+   \sstdescription{
+      This attribute controls the issuing of warnings about selected
+      conditions when an \htmlref{Object}{Object} or keyword is read from or written to a
+      \htmlref{FitsChan}{FitsChan}. The value supplied for the Warnings attribute should
+      consist of a space separated list of condition names (see the
+      \htmlref{AllWarnings}{AllWarnings} attribute for a list of the currently defined names).
+      Each name indicates a condition which should be reported. The default
+      value for Warnings is the string \texttt{"} BadKeyName BadKeyValue Tnx Zpx
+      BadCel BadMat BadPV BadCTYPE\texttt{"} .
+
+      The text of any warning will be stored within the FitsChan in the
+      form of one or more new header cards with keyword ASTWARN. If
+      required, applications can check the FitsChan for ASTWARN cards
+      (using \htmlref{astFindFits}{astFindFits}) after the call to \htmlref{astRead}{astRead} or \htmlref{astWrite}{astWrite} has been
+      performed, and report the text of any such cards to the user. ASTWARN
+      cards will be propagated to any output header unless they are
+      deleted from the FitsChan using \htmlref{astDelFits}{astDelFits}.
+   }
+   \sstattributetype{
+      String
+   }
+   \sstapplicability{
+      \sstsubsection{
+         FitsChan
+      }{
+         All FitsChans have this attribute.
+      }
+   }
+   \sstnotes{
+      This attribute only controls the warnings that are to be stored as
+      a set of header cards in the FitsChan as described above. It has no
+      effect on the storage of warnings in the parent \htmlref{Channel}{Channel} structure.
+      All warnings are stored in the parent Channel structure, from where
+      they can be retrieved using the
+      \htmlref{astWarnings}{astWarnings}
+      function.
+   }
+}
+\sstroutine{
+   WcsAxis(lonlat)
+}{
+   FITS-WCS projection axes
+}{
+   \sstdescription{
+      This attribute gives the indices of the longitude and latitude
+      coordinates of the FITS-WCS projection within the coordinate
+      space used by a \htmlref{WcsMap}{WcsMap}. These indices are defined when the
+      WcsMap is first created using \htmlref{astWcsMap}{astWcsMap} and cannot
+      subsequently be altered.
+
+      If \texttt{"} lonlat\texttt{"}  is 1, the index of the longitude axis is
+      returned. Otherwise, if it is 2, the index of the latitude axis
+      is returned.
+   }
+   \sstattributetype{
+      Integer, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         WcsMap
+      }{
+         All WcsMaps have this attribute.
+      }
+   }
+}
+\sstroutine{
+   WcsType
+}{
+   FITS-WCS projection type
+}{
+   \sstdescription{
+      This attribute specifies which type of FITS-WCS projection will
+      be performed by a \htmlref{WcsMap}{WcsMap}. The value is specified when a WcsMap
+      is first created using \htmlref{astWcsMap}{astWcsMap} and cannot subsequently be
+      changed.
+
+      The values used are represented by macros with names of
+      the form \texttt{"} AST\_\_XXX\texttt{"} , where \texttt{"} XXX\texttt{"}  is the (upper case) 3-character
+      code used by the FITS-WCS \texttt{"} CTYPEi\texttt{"}  keyword to identify the
+      projection. For example, possible values are AST\_\_TAN (for the
+      tangent plane or gnomonic projection) and AST\_\_AIT (for the
+      Hammer-Aitoff projection). AST\_\_TPN is an exception in that it
+      is not part of the FITS-WCS standard (it represents a TAN
+      projection with polynomial correction terms as defined in an early
+      draft of the FITS-WCS paper).
+   }
+   \sstattributetype{
+      Integer, read-only.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         WcsMap
+      }{
+         All WcsMaps have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          For a list of available projections, see the FITS-WCS paper.
+      }
+   }
+}
+\sstroutine{
+   Width(element)
+}{
+   Line width for a Plot element
+}{
+   \sstdescription{
+      This attribute determines the line width used when drawing each
+      element of graphical output produced by a \htmlref{Plot}{Plot}.  It takes a
+      separate value for each graphical element so that, for instance,
+      the setting \texttt{"} Width(border)=2.0\texttt{"}  causes the Plot border to be
+      drawn using a line width of 2.0. A value of 1.0 results in a
+      line thickness which is approximately 0.0005 times the length of
+      the diagonal of the entire display surface.
+
+      The actual appearance of lines drawn with any particular width,
+      and the range of available widths, is determined by the
+      underlying graphics system.  The default behaviour is for all
+      graphical elements to be drawn using the default line width
+      supplied by this graphics system. This will not necessarily
+      correspond to a Width value of 1.0.
+   }
+   \sstattributetype{
+      Floating point.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Plot
+      }{
+         All Plots have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          For a list of the graphical elements available, see the
+         description of the Plot class.
+
+         \sstitem
+          If no graphical element is specified, (e.g. \texttt{"} Width\texttt{"}  instead of
+         \texttt{"} Width(border)\texttt{"} ), then a \texttt{"} set\texttt{"}  or \texttt{"} clear\texttt{"}  operation will affect
+         the attribute value of all graphical elements, while a \texttt{"} get\texttt{"}  or
+         \texttt{"} test\texttt{"}  operation will use just the Width(\htmlref{Border}{Border}) value.
+      }
+   }
+}
+\sstroutine{
+   XmlFormat
+}{
+   System for formatting Objects as XML
+}{
+   \sstdescription{
+      This attribute specifies the formatting system to use when AST
+      Objects are written out as XML through an \htmlref{XmlChan}{XmlChan}. It
+      affects the behaviour of the \htmlref{astWrite}{astWrite} function when
+      they are used to transfer any AST \htmlref{Object}{Object} to or from an external
+      XML representation.
+
+      The XmlChan class allows AST objects to be represented in the form
+      of XML in several ways (conventions) and the XmlFormat attribute is
+      used to specify which of these should be used. The formatting options
+      available are outlined in the \texttt{"} Formats Available\texttt{"}  section below.
+
+      By default, an XmlChan will attempt to determine which format system
+      is already in use, and will set the default XmlFormat value
+      accordingly (so that subsequent I/O operations adopt the same
+      conventions). It does this by looking for certain critical items
+      which only occur in particular formats. For details of how this
+      works, see the \texttt{"} Choice of Default Format\texttt{"}  section below. If you wish
+      to ensure that a particular format system is used, independently of
+      any XML already read, you should set an explicit XmlFormat value
+      yourself.
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         XmlChan
+      }{
+         All XmlChans have this attribute.
+      }
+   }
+   \sstdiytopic{
+      Formats Available
+   }{
+      The XmlFormat attribute can take any of the following (case
+      insensitive) string values to select the corresponding formatting
+      system:
+
+      \sstitemlist{
+
+         \sstitem
+          \texttt{"} NATIVE\texttt{"} : This is a direct conversion to XML of the heirarchical
+         format used by a standard XML channel (and also by the NATIVE
+         encoding of a \htmlref{FitsChan}{FitsChan}).
+
+         \sstitem
+          \texttt{"} QUOTED\texttt{"} : This is the same as NATIVE format except that extra
+         information is included which allows client code to convert the
+         XML into a form which can be read by a standard AST \htmlref{Channel}{Channel}. This
+         extra information indicates which AST attribute values should be
+         enclosed in quotes before being passed to a Channel.
+
+         \sstitem
+          \texttt{"} IVOA\texttt{"} : This is a format that uses an early draft of the STC-X schema
+         developed by the International Virtual Observatory Alliance (IVOA -
+         see \texttt{"} http://www.ivoa.net/\texttt{"} ) to describe coordinate systems, regions,
+         mappings, etc. Support is limited to V1.20 described at
+         \texttt{"} http://www.ivoa.net/Documents/WD/STC/STC-20050225.html\texttt{"} . Since the
+         version of STC-X finally adopted by the IVOA differs in several
+         significant respects from V1.20, this format is now mainly of
+         historical interest. Note, the alternative \texttt{"} STC-S\texttt{"}  format (a
+         simpler non-XML encoding of the STC metadata) is supported by the
+         \htmlref{StcsChan}{StcsChan} class.
+      }
+   }
+   \sstdiytopic{
+      Choice of Default Format;
+   }{
+      If the XmlFormat attribute of an XmlChan is not set, the default
+      value it takes is determined by the presence of certain critical
+      items within the document most recently read using
+      \htmlref{astRead}{astRead}.
+      The sequence of decision used to arrive at the default value is as
+      follows:
+
+      \sstitemlist{
+
+         \sstitem
+          If the previous document read contained any elements in any of the STC
+         namespaces (\texttt{"} urn:nvo-stc\texttt{"} , \texttt{"} urn:nvo-coords\texttt{"}  or \texttt{"} urn:nvo-region\texttt{"} ), then
+         the default value is IVOA.
+
+         \sstitem
+          If the previous document read contained any elements in the AST
+         namespace which had an associated XML attribute called \texttt{"} quoted\texttt{"} , then
+         the default value is QUOTED.
+
+         \sstitem
+          Otherwise, if none of these conditions is met (as would be the
+         case if no document had yet been read), then NATIVE format is
+         used.
+
+      }
+      Setting an explicit value for the XmlFormat attribute always
+      over-rides this default behaviour.
+   }
+   \sstdiytopic{
+      The IVOA Format
+   }{
+      The IVOA support caters only for certain parts of V1.20 of the
+      draft Space-Time Coordinate (STC) schema (see
+      http://www.ivoa.net/Documents/WD/STC/STC-20050225.html). Note, this
+      draft has now been superceded by an officially adopted version that
+      differs in several significant respects from V1.20. Consequently,
+      the \texttt{"} IVOA\texttt{"}  XmlChan format is of historical interest only.
+
+      The following points should be noted when using an XmlChan to read
+      or write STC information (note, this list is currently incomplete):
+
+      \sstitemlist{
+
+         \sstitem
+          Objects can currently only be read using this format, not written.
+
+         \sstitem
+          The AST object generated by reading an $<$STCMetadata$>$ element will
+         be an instance of one of the AST \texttt{"} \htmlref{Stc}{Stc}\texttt{"}  classes: \htmlref{StcResourceProfile}{StcResourceProfile},
+         \htmlref{StcSearchLocation}{StcSearchLocation}, \htmlref{StcCatalogEntryLocation}{StcCatalogEntryLocation}, \htmlref{StcObsDataLocation}{StcObsDataLocation}.
+
+         \sstitem
+          When reading an $<$STCMetadata$>$ element, the axes in the returned
+         AST Object will be in the order space, time, spectral, redshift,
+         irrespective of the order in which the axes occur in the $<$STCMetadata$>$
+         element. If the supplied $<$STCMetadata$>$ element does not contain all of
+         these axes, the returned AST Object will also omit them, but the
+         ordering of those axes which are present will be as stated above. If
+         the spatial frame represents a celestial coordinate system the
+         spatial axes will be in the order (longitude, latitude).
+
+         \sstitem
+          Until such time as the AST \htmlref{TimeFrame}{TimeFrame} is complete, a simple
+         1-dimensional \htmlref{Frame}{Frame} (with \htmlref{Domain}{Domain} set to TIME) will be used to
+         represent the STC $<$TimeFrame$>$ element. Consequently, most of the
+         information within a $<$TimeFrame$>$ element is currently ignored.
+
+         \sstitem
+          $<$SpaceFrame$>$ elements can only be read if they describe a celestial
+         longitude and latitude axes supported by the AST \htmlref{SkyFrame}{SkyFrame} class. The
+         space axes will be returned in the order (longitude, latitude).
+
+         \sstitem
+          Velocities associated with SpaceFrames cannot be read.
+
+         \sstitem
+          Any $<$GenericCoordFrame$>$ elements within an $<$AstroCoordSystem$>$ element
+         are currently ignored.
+
+         \sstitem
+          Any second or subsequent $<$AstroCoordSystem$>$ found within an
+         STCMetaData element is ignored.
+
+         \sstitem
+          Any second or subsequent $<$AstroCoordArea$>$ found within an
+         STCMetaData element is ignored.
+
+         \sstitem
+          Any $<$OffsetCenter$>$ found within a $<$SpaceFrame$>$ is ignored.
+
+         \sstitem
+          Any CoordFlavor element found within a $<$SpaceFrame$>$ is ignored.
+
+         \sstitem
+          $<$SpaceFrame$>$ elements can only be read if they refer to
+         one of the following space reference frames: ICRS, GALACTIC\_II,
+         SUPER\_GALACTIC, HEE, FK4, FK5, ECLIPTIC.
+
+         \sstitem
+          $<$SpaceFrame$>$ elements can only be read if the reference
+         position is TOPOCENTER. Also, any planetary ephemeris is ignored.
+
+         \sstitem
+          Regions: there is currently no support for STC regions of type
+         Sector, ConvexHull or SkyIndex.
+
+         \sstitem
+          The AST \htmlref{Region}{Region} read from a CoordInterval element is considered to
+         be open if either the lo\_include or the hi\_include attribute is
+         set to false.
+
+         \sstitem
+          $<$RegionFile$>$ elements are not supported.
+
+         \sstitem
+          Vertices within $<$\htmlref{Polygon}{Polygon}$>$ elements are always considered to be
+         joined using great circles (that is, $<$SmallCircle$>$ elements are
+         ignored).
+      }
+   }
+}
+\sstroutine{
+   XmlLength
+}{
+   Controls output buffer length
+}{
+   \sstdescription{
+      This attribute specifies the maximum length to use when writing out
+      text through the sink function supplied when the \htmlref{XmlChan}{XmlChan} was created.
+
+      The number of characters in each string written out through the sink
+      function will not be greater than the value of this attribute (but
+      may be less). A value of zero (the default) means there is no limit -
+      each string can be of any length.
+   }
+   \sstattributetype{
+      Integer.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         XmlChan
+      }{
+         All XmlChans have this attribute.
+      }
+   }
+}
+\sstroutine{
+   XmlPrefix
+}{
+   The namespace prefix to use when writing
+}{
+   \sstdescription{
+      This attribute is a string which is to be used as the namespace
+      prefix for all XML elements created as a result of writing an AST
+      \htmlref{Object}{Object} out through an \htmlref{XmlChan}{XmlChan}. The URI associated with the namespace
+      prefix is given by the symbolic constant AST\_\_XMLNS defined in
+      ast.h.
+      A definition of the namespace prefix is included in each top-level
+      element produced by the XmlChan.
+
+      The default value is a blank string which causes no prefix to be
+      used. In this case each top-level element will set the default
+      namespace to be the value of AST\_\_XMLNS.
+   }
+   \sstattributetype{
+      String.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         Object
+      }{
+         All Objects have this attribute.
+      }
+   }
+}
+\sstroutine{
+   Zoom
+}{
+   ZoomMap scale factor
+}{
+   \sstdescription{
+      This attribute holds the \htmlref{ZoomMap}{ZoomMap} scale factor, by which
+      coordinate values are multiplied (by the forward transformation)
+      or divided (by the inverse transformation). The default value
+      is unity.
+
+      Note that if a ZoomMap is inverted (e.g. by using \htmlref{astInvert}{astInvert}),
+      then the reciprocal of this zoom factor will, in effect, be
+      used.
+
+      In general, \htmlref{Mapping}{Mapping} attributes cannot be changed after the Mapping
+      has been created (the exception to this is the \htmlref{Invert}{Invert} attribute,
+      which can be changed at any time). However, several of the oldest
+      Mapping classes - including the ZoomMap class - were introduced
+      into the AST library before this restriction was enforced. To
+      reduce the chances of breaking existing software, the attributes of
+      such Mappings may still be changed, but only for Mapping instances
+      that have exactly one active reference. In other words, an error will
+      be reported if an attempt is made to set or clear an attribute of a
+      Mapping (other than the Invert attribute) if that Mapping has been
+      cloned. Mappings are cloned when they are incorporated into another
+      object such as a \htmlref{CmpMap}{CmpMap} or \htmlref{FrameSet}{FrameSet}, or when the
+      \htmlref{astClone}{astClone}
+      function is used.
+   }
+   \sstattributetype{
+      Double precision.
+   }
+   \sstapplicability{
+      \sstsubsection{
+         ZoomMap
+      }{
+         All ZoomMaps have this attribute.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          The Zoom attribute may not be set to zero.
+      }
+   }
+}
+\normalsize
+
+\cleardoublepage
+\section{\label{ss:classdescriptions}AST Class Descriptions}
+\small
+\sstroutine{
+   Axis
+}{
+   Store axis information
+}{
+   \sstdescription{
+      The Axis class is used to store information associated with a
+      particular axis of a \htmlref{Frame}{Frame}. It is used internally by the AST
+      library and has no constructor function. You should encounter it
+      only within textual output (e.g. from \htmlref{astWrite}{astWrite}).
+   }
+   \sstconstructor{
+      None.
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The Axis class inherits from the \htmlref{Object}{Object} class.
+   }
+}
+\sstroutine{
+   Box
+}{
+   A box region with sides parallel to the axes of a Frame
+}{
+   \sstdescription{
+      The Box class implements a \htmlref{Region}{Region} which represents a box with sides
+      parallel to the axes of a \htmlref{Frame}{Frame} (i.e. an area which encloses a given
+      range of values on each axis). A Box is similar to an \htmlref{Interval}{Interval}, the
+      only real difference being that the Interval class allows some axis
+      limits to be unspecified. Note, a Box will only look like a box if
+      the Frame geometry is approximately flat. For instance, a Box centred
+      close to a pole in a \htmlref{SkyFrame}{SkyFrame} will look more like a fan than a box
+      (the \htmlref{Polygon}{Polygon} class can be used to create a box-like region close to a
+      pole).
+   }
+   \sstconstructor{
+      \htmlref{astBox}{astBox}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The Box class inherits from the Region class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The Box class does not define any new attributes beyond
+      those which are applicable to all Regions.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The Box class does not define any new functions beyond those
+      which are applicable to all Regions.
+   }
+}
+\sstroutine{
+   Channel
+}{
+   Basic (textual) I/O channel
+}{
+   \sstdescription{
+      The Channel class implements low-level input/output for the AST
+      library.  Writing an \htmlref{Object}{Object} to a Channel will generate a textual
+      representation of that Object, and reading from a Channel will
+      create a new Object from its textual representation.
+
+      Normally, when you use a Channel, you should provide \texttt{"} source\texttt{"}
+      and \texttt{"} sink\texttt{"}  functions which connect it to an external data store
+      by reading and writing the resulting text. By default, however,
+      a Channel will read from standard input and write to standard
+      output. Alternatively, a Channel can be told to read or write from
+      specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes,
+      in which case no sink or source function need be supplied.
+   }
+   \sstconstructor{
+      \htmlref{astChannel}{astChannel}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The Channel class inherits from the Object class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all Objects, every
+      Channel also has the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{Comment}{Comment}: Include textual comments in output?
+
+         \sstitem
+          \htmlref{Full}{Full}: Set level of output detail
+
+         \sstitem
+          \htmlref{Indent}{Indent}: Indentation increment between objects
+
+         \sstitem
+          \htmlref{ReportLevel}{ReportLevel}: Selects the level of error reporting
+
+         \sstitem
+          \htmlref{SinkFile}{SinkFile}: The path to a file to which the Channel should write
+
+         \sstitem
+          \htmlref{Skip}{Skip}: Skip irrelevant data?
+
+         \sstitem
+          \htmlref{SourceFile}{SourceFile}: The path to a file from which the Channel should read
+
+         \sstitem
+          \htmlref{Strict}{Strict}: Generate errors instead of warnings?
+      }
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      In addition to those functions applicable to all Objects, the
+      following functions may also be applied to all Channels:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{astWarnings}{astWarnings}: Return warnings from the previous read or write
+
+         \sstitem
+          \htmlref{astPutChannelData}{astPutChannelData}: Store data to pass to source or sink functions
+
+         \sstitem
+          \htmlref{astRead}{astRead}: Read an Object from a Channel
+
+         \sstitem
+          \htmlref{astWrite}{astWrite}: Write an Object to a Channel
+      }
+   }
+}
+\sstroutine{
+   ChebyMap
+}{
+   Map coordinates using Chebyshev polynomial functions
+}{
+   \sstdescription{
+      A ChebyMap is a form of \htmlref{Mapping}{Mapping} which performs a Chebyshev polynomial
+      transformation.  Each output coordinate is a linear combination of
+      Chebyshev polynomials of the first kind, of order zero up to a
+      specified maximum order, evaluated at the input coordinates. The
+      coefficients to be used in the linear combination are specified
+      separately for each output coordinate.
+
+      For a 1-dimensional ChebyMap, the forward transformation is defined
+      as follows:
+
+         f(x) = c0.T0(x\texttt{'} ) $+$ c1.T1(x\texttt{'} ) $+$ c2.T2(x\texttt{'} ) $+$ ...
+
+      where:
+      \sstitemlist{
+
+         \sstitem
+             Tn(x\texttt{'} ) is the nth Chebyshev polynomial of the first kind:
+
+         \sstitem
+                  T0(x\texttt{'} ) = 1
+
+         \sstitem
+                  T1(x\texttt{'} ) = x\texttt{'}
+
+         \sstitem
+                  Tn$+$1(x\texttt{'} ) = 2.x\texttt{'} .Tn(x\texttt{'} ) $+$ Tn-1(x\texttt{'} )
+
+         \sstitem
+             x\texttt{'}  is the inpux axis value, x, offset and scaled to the range
+              [-1, 1] as x ranges over a specified bounding box, given when the
+              ChebyMap is created. The input positions, x,  supplied to the
+              forward transformation must fall within the bounding box - bad
+              axis values (AST\_\_BAD) are generated for points outside the
+              bounding box.
+
+      }
+      For an N-dimensional ChebyMap, the forward transformation is a
+      generalisation of the above form. Each output axis value is the sum
+      of \texttt{"} ncoeff\texttt{"}
+      terms, where each term is the product of a single coefficient
+      value and N factors of the form Tn(x\texttt{'} \_i), where \texttt{"} x\texttt{'} \_i\texttt{"}  is the
+      normalised value of the i\texttt{'} th input axis value.
+
+      The forward and inverse transformations are defined independantly
+      by separate sets of coefficients, supplied when the ChebyMap is
+      created. If no coefficients are supplied to define the inverse
+      transformation, the
+      \htmlref{astPolyTran}{astPolyTran}
+      method of the parent \htmlref{PolyMap}{PolyMap} class can instead be used to create an
+      inverse transformation. The inverse transformation so generated
+      will be a Chebyshev polynomial with coefficients chosen to minimise
+      the residuals left by a round trip (forward transformation followed
+      by inverse transformation).
+   }
+   \sstconstructor{
+      \htmlref{astChebyMap}{astChebyMap}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The ChebyMap class inherits from the PolyMap class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The ChebyMap class does not define any new attributes beyond those
+      which are applicable to all PolyMaps.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      In addition to those functions applicable to all PolyMap, the
+      following functions may also be applied to all ChebyMaps:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{astChebyDomain}{astChebyDomain}: Get the bounds of the domain of the ChebyMap
+      }
+   }
+}
+\sstroutine{
+   Circle
+}{
+   A circular or spherical region within a Frame
+}{
+   \sstdescription{
+      The Circle class implements a \htmlref{Region}{Region} which represents a circle or
+      sphere within a \htmlref{Frame}{Frame}.
+   }
+   \sstconstructor{
+      \htmlref{astCircle}{astCircle}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The Circle class inherits from the Region class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The Circle class does not define any new attributes beyond
+      those which are applicable to all Regions.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      In addition to those functions applicable to all Regions, the
+      following functions may also be applied to all Circles:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{astCirclePars}{astCirclePars}: Get the geometric parameters of the Circle
+      }
+   }
+}
+\sstroutine{
+   CmpFrame
+}{
+   Compound Frame
+}{
+   \sstdescription{
+      A CmpFrame is a compound \htmlref{Frame}{Frame} which allows two component Frames
+      (of any class) to be merged together to form a more complex
+      Frame. The axes of the two component Frames then appear together
+      in the resulting CmpFrame (those of the first Frame, followed by
+      those of the second Frame).
+
+      Since a CmpFrame is itself a Frame, it can be used as a
+      component in forming further CmpFrames. Frames of arbitrary
+      complexity may be built from simple individual Frames in this
+      way.
+
+      Also since a Frame is a \htmlref{Mapping}{Mapping}, a CmpFrame can also be used as a
+      Mapping. Normally, a CmpFrame is simply equivalent to a \htmlref{UnitMap}{UnitMap},
+      but if either of the component Frames within a CmpFrame is a \htmlref{Region}{Region}
+      (a sub-class of Frame), then the CmpFrame will use the Region as a
+      Mapping when transforming values for axes described by the Region.
+      Thus input axis values corresponding to positions which are outside the
+      Region will result in bad output axis values.
+   }
+   \sstconstructor{
+      \htmlref{astCmpFrame}{astCmpFrame}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The CmpFrame class inherits from the Frame class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The CmpFrame class does not define any new attributes beyond
+      those which are applicable to all Frames. However, the attributes
+      of the component Frames can be accessed as if they were attributes
+      of the CmpFrame. For instance, if a CmpFrame contains a \htmlref{SpecFrame}{SpecFrame}
+      and a \htmlref{SkyFrame}{SkyFrame}, then the CmpFrame will recognise the \texttt{"} \htmlref{Equinox}{Equinox}\texttt{"}
+      attribute and forward access requests to the component SkyFrame.
+      Likewise, it will recognise the \texttt{"} \htmlref{RestFreq}{RestFreq}\texttt{"}  attribute and forward
+      access requests to the component SpecFrame. An axis index can
+      optionally be appended to the end of any attribute name, in which
+      case the request to access the attribute will be forwarded to the
+      primary Frame defining the specified axis.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The CmpFrame class does not define any new functions beyond those
+      which are applicable to all Frames.
+   }
+}
+\sstroutine{
+   CmpMap
+}{
+   Compound Mapping
+}{
+   \sstdescription{
+      A CmpMap is a compound \htmlref{Mapping}{Mapping} which allows two component
+      Mappings (of any class) to be connected together to form a more
+      complex Mapping. This connection may either be \texttt{"} in series\texttt{"}
+      (where the first Mapping is used to transform the coordinates of
+      each point and the second mapping is then applied to the
+      result), or \texttt{"} in parallel\texttt{"}  (where one Mapping transforms the
+      earlier coordinates for each point and the second Mapping
+      simultaneously transforms the later coordinates).
+
+      Since a CmpMap is itself a Mapping, it can be used as a
+      component in forming further CmpMaps. Mappings of arbitrary
+      complexity may be built from simple individual Mappings in this
+      way.
+   }
+   \sstconstructor{
+      \htmlref{astCmpMap}{astCmpMap}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The CmpMap class inherits from the Mapping class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The CmpMap class does not define any new attributes beyond those
+      which are applicable to all Mappings.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The CmpMap class does not define any new functions beyond those
+      which are applicable to all Mappings.
+   }
+}
+\sstroutine{
+   CmpRegion
+}{
+   A combination of two regions within a single Frame
+}{
+   \sstdescription{
+      A CmpRegion is a \htmlref{Region}{Region} which allows two component
+      Regions (of any class) to be combined to form a more complex
+      Region. This combination may be performed a boolean AND, OR
+      or XOR (exclusive OR) operator. If the AND operator is
+      used, then a position is inside the CmpRegion only if it is
+      inside both of its two component Regions. If the OR operator is
+      used, then a position is inside the CmpRegion if it is inside
+      either (or both) of its two component Regions. If the XOR operator
+      is used, then a position is inside the CmpRegion if it is inside
+      one but not both of its two component Regions. Other operators can
+      be formed by negating one or both component Regions before using
+      them to construct a new CmpRegion.
+
+      The two component Region need not refer to the same coordinate
+      \htmlref{Frame}{Frame}, but it must be possible for the
+      \htmlref{astConvert}{astConvert}
+      function to determine a \htmlref{Mapping}{Mapping} between them (an error will be
+      reported otherwise when the CmpRegion is created). For instance,
+      a CmpRegion may combine a Region defined within an ICRS \htmlref{SkyFrame}{SkyFrame}
+      with a Region defined within a Galactic SkyFrame. This is
+      acceptable because the SkyFrame class knows how to convert between
+      these two systems, and consequently the
+      astConvert
+      function will also be able to convert between them. In such cases,
+      the second component Region will be mapped into the coordinate Frame
+      of the first component Region, and the Frame represented by the
+      CmpRegion as a whole will be the Frame of the first component Region.
+
+      Since a CmpRegion is itself a Region, it can be used as a
+      component in forming further CmpRegions. Regions of arbitrary
+      complexity may be built from simple individual Regions in this
+      way.
+   }
+   \sstconstructor{
+      \htmlref{astCmpRegion}{astCmpRegion}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The CmpRegion class inherits from the Region class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The CmpRegion class does not define any new attributes beyond those
+      which are applicable to all Regions.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The CmpRegion class does not define any new functions beyond those
+      which are applicable to all Regions.
+   }
+}
+\sstroutine{
+   DSBSpecFrame
+}{
+   Dual sideband spectral coordinate system description
+}{
+   \sstdescription{
+      A DSBSpecFrame is a specialised form of \htmlref{SpecFrame}{SpecFrame} which represents
+      positions in a spectrum obtained using a dual sideband instrument.
+      Such an instrument produces a spectrum in which each point contains
+      contributions from two distinctly different frequencies, one from
+      the \texttt{"} lower side band\texttt{"}  (LSB) and one from the \texttt{"} upper side band\texttt{"}  (USB).
+      Corresponding LSB and USB frequencies are connected by the fact
+      that they are an equal distance on either side of a fixed central
+      frequency known as the \texttt{"} Local Oscillator\texttt{"}  (LO) frequency.
+
+      When quoting a position within such a spectrum, it is necessary to
+      indicate whether the quoted position is the USB position or the
+      corresponding LSB position. The \htmlref{SideBand}{SideBand} attribute provides this
+      indication. Another option that the SideBand attribute provides is
+      to represent a spectral position by its topocentric offset from the
+      LO frequency.
+
+      In practice, the LO frequency is specified by giving the distance
+      from the LO frequency to some \texttt{"} central\texttt{"}  spectral position. Typically
+      this central position is that of some interesting spectral feature.
+      The distance from this central position to the LO frequency is known
+      as the \texttt{"} intermediate frequency\texttt{"}  (\htmlref{IF}{IF}). The value supplied for IF can
+      be a signed value in order to indicate whether the LO frequency is
+      above or below the central position.
+   }
+   \sstconstructor{
+      \htmlref{astDSBSpecFrame}{astDSBSpecFrame}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The DSBSpecFrame class inherits from the SpecFrame class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all SpecFrames, every
+      DSBSpecFrame also has the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{AlignSideBand}{AlignSideBand}: Should alignment occur between sidebands?
+
+         \sstitem
+          \htmlref{DSBCentre}{DSBCentre}: The central position of interest.
+
+         \sstitem
+          \htmlref{IF}{IF}: The intermediate frequency used to define the LO frequency.
+
+         \sstitem
+          \htmlref{ImagFreq}{ImagFreq}: The image sideband equivalent of the rest frequency.
+
+         \sstitem
+          \htmlref{SideBand}{SideBand}: Indicates which sideband the DSBSpecFrame represents.
+      }
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The DSBSpecFrame class does not define any new functions beyond those
+      which are applicable to all SpecFrames.
+   }
+}
+\sstroutine{
+   DssMap
+}{
+   Map points using a Digitised Sky Survey plate solution
+}{
+   \sstdescription{
+      The DssMap class implements a \htmlref{Mapping}{Mapping} which transforms between
+      2-dimensional pixel coordinates and an equatorial sky coordinate
+      system (right ascension and declination) using a Digitised Sky
+      Survey (DSS) astrometric plate solution.
+
+      The input coordinates are pixel numbers along the first and
+      second dimensions of an image, where the centre of the first
+      pixel is located at (1,1) and the spacing between pixel centres
+      is unity.
+
+      The output coordinates are right ascension and declination in
+      radians. The celestial coordinate system used (FK4, FK5, etc.)
+      is unspecified, and will usually be indicated by appropriate
+      keywords in a FITS header.
+   }
+   \sstconstructor{
+      The DssMap class does not have a constructor function.  A DssMap
+      is created only as a by-product of reading a \htmlref{FrameSet}{FrameSet} (using
+      \htmlref{astRead}{astRead}) from a \htmlref{FitsChan}{FitsChan} which contains FITS header cards
+      describing a DSS plate solution, and whose \htmlref{Encoding}{Encoding} attribute is
+      set to \texttt{"} DSS\texttt{"} . The result of such a read, if successful, is a
+      FrameSet whose base and current Frames are related by a DssMap.
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The DssMap class inherits from the Mapping class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The DssMap class does not define any new attributes beyond those
+      which are applicable to all Mappings.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The DssMap class does not define any new functions beyond those
+      which are applicable to all Mappings.
+   }
+}
+\sstroutine{
+   Ellipse
+}{
+   An elliptical region within a 2-dimensional Frame
+}{
+   \sstdescription{
+      The Ellipse class implements a \htmlref{Region}{Region} which represents a ellipse
+      within a 2-dimensional \htmlref{Frame}{Frame}.
+   }
+   \sstconstructor{
+      \htmlref{astEllipse}{astEllipse}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The Ellipse class inherits from the Region class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The Ellipse class does not define any new attributes beyond
+      those which are applicable to all Regions.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      In addition to those functions applicable to all Regions, the
+      following functions may also be applied to all Ellipses:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{astEllipsePars}{astEllipsePars}: Get the geometric parameters of the Ellipse
+      }
+   }
+}
+\sstroutine{
+   FitsChan
+}{
+   I/O Channel using FITS header cards to represent Objects
+}{
+   \sstdescription{
+      A FitsChan is a specialised form of \htmlref{Channel}{Channel} which supports I/O
+      operations involving the use of FITS (Flexible Image Transport
+      \htmlref{System}{System}) header cards. Writing an \htmlref{Object}{Object} to a FitsChan (using
+      \htmlref{astWrite}{astWrite}) will, if the Object is suitable, generate a
+      description of that Object composed of FITS header cards, and
+      reading from a FitsChan will create a new Object from its FITS
+      header card description.
+
+      While a FitsChan is active, it represents a buffer which may
+      contain zero or more 80-character \texttt{"} header cards\texttt{"}  conforming to
+      FITS conventions. Any sequence of FITS-conforming header cards
+      may be stored, apart from the \texttt{"} END\texttt{"}  card whose existence is
+      merely implied.  The cards may be accessed in any order by using
+      the FitsChan\texttt{'} s integer \htmlref{Card}{Card} attribute, which identifies a \texttt{"} current\texttt{"}
+      card, to which subsequent operations apply. Searches
+      based on keyword may be performed (using \htmlref{astFindFits}{astFindFits}), new
+      cards may be inserted (\htmlref{astPutFits}{astPutFits}, \htmlref{astPutCards}{astPutCards}, \htmlref{astSetFits$<$X$>$}{astSetFits$<$X$>$}) and
+      existing ones may be deleted (\htmlref{astDelFits}{astDelFits}), extracted (\htmlref{astGetFits$<$X$>$}{astGetFits$<$X$>$}),
+      or changed (astSetFits$<$X$>$).
+
+      When you create a FitsChan, you have the option of specifying
+      \texttt{"} source\texttt{"}  and \texttt{"} sink\texttt{"}  functions which connect it to external data
+      stores by reading and writing FITS header cards. If you provide
+      a source function, it is used to fill the FitsChan with header cards
+      when it is accessed for the first time. If you do not provide a
+      source function, the FitsChan remains empty until you explicitly enter
+      data into it (e.g. using astPutFits, astPutCards, astWrite
+      or by using the \htmlref{SourceFile}{SourceFile} attribute to specifying a text file from
+      which headers should be read). When the FitsChan is deleted, any
+      remaining header cards in the FitsChan can be saved in either of
+      two ways: 1) by specifying a value for the \htmlref{SinkFile}{SinkFile} attribute (the
+      name of a text file to which header cards should be written), or 2)
+      by providing a sink function (used to to deliver header cards to an
+      external data store). If you do not provide a sink function or a
+      value for SinkFile, any header cards remaining when the FitsChan
+      is deleted will be lost, so you should arrange to extract them
+      first if necessary
+      (e.g. using astFindFits or \htmlref{astRead}{astRead}).
+
+      Coordinate system information may be described using FITS header
+      cards using several different conventions, termed
+      \texttt{"} encodings\texttt{"} . When an AST Object is written to (or read from) a
+      FitsChan, the value of the FitsChan\texttt{'} s \htmlref{Encoding}{Encoding} attribute
+      determines how the Object is converted to (or from) a
+      description involving FITS header cards. In general, different
+      encodings will result in different sets of header cards to
+      describe the same Object. Examples of encodings include the DSS
+      encoding (based on conventions used by the STScI Digitised Sky
+      Survey data), the FITS-WCS encoding (based on a proposed FITS
+      standard) and the NATIVE encoding (a near loss-less way of
+      storing AST Objects in FITS headers).
+
+      The available encodings differ in the range of Objects they can
+      represent, in the number of Object descriptions that can coexist
+      in the same FitsChan, and in their accessibility to other
+      (external) astronomy applications (see the Encoding attribute
+      for details). Encodings are not necessarily mutually exclusive
+      and it may sometimes be possible to describe the same Object in
+      several ways within a particular set of FITS header cards by
+      using several different encodings.
+
+      The detailed behaviour of astRead and astWrite, when used with
+      a FitsChan, depends on the encoding in use. In general, however,
+      all successful use of astRead is destructive, so that FITS header cards
+      are consumed in the process of reading an Object, and are
+      removed from the FitsChan (this deletion can be prevented for
+      specific cards by calling the
+      \htmlref{astRetainFits}{astRetainFits} function).
+      An unsuccessful call of
+      astRead
+      (for instance, caused by the FitsChan not containing the necessary
+      FITS headers cards needed to create an Object) results in the
+      contents of the FitsChan being left unchanged.
+
+      If the encoding in use allows only a single Object description
+      to be stored in a FitsChan (e.g. the DSS, FITS-WCS and FITS-IRAF
+      encodings), then write operations using astWrite will
+      over-write any existing Object description using that
+      encoding. Otherwise (e.g. the NATIVE encoding), multiple Object
+      descriptions are written sequentially and may later be read
+      back in the same sequence.
+   }
+   \sstconstructor{
+      \htmlref{astFitsChan}{astFitsChan}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The FitsChan class inherits from the Channel class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all Channels, every
+
+      FitsChan also has the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{AllWarnings}{AllWarnings}: A list of the available conditions
+
+         \sstitem
+          \htmlref{Card}{Card}: Index of current FITS card in a FitsChan
+
+         \sstitem
+          \htmlref{CardComm}{CardComm}: The comment of the current FITS card in a FitsChan
+
+         \sstitem
+          \htmlref{CardName}{CardName}: The keyword name of the current FITS card in a FitsChan
+
+         \sstitem
+          \htmlref{CardType}{CardType}: The data type of the current FITS card in a FitsChan
+
+         \sstitem
+          \htmlref{CarLin}{CarLin}: Ignore spherical rotations on CAR projections?
+
+         \sstitem
+          \htmlref{CDMatrix}{CDMatrix}: Use a CD matrix instead of a PC matrix?
+
+         \sstitem
+          \htmlref{Clean}{Clean}: Remove cards used whilst reading even if an error occurs?
+
+         \sstitem
+          \htmlref{DefB1950}{DefB1950}: Use FK4 B1950 as default equatorial coordinates?
+
+         \sstitem
+          \htmlref{Encoding}{Encoding}: System for encoding Objects as FITS headers
+
+         \sstitem
+          \htmlref{FitsAxisOrder}{FitsAxisOrder}: Sets the order of WCS axes within new FITS-WCS headers
+
+         \sstitem
+          \htmlref{FitsDigits}{FitsDigits}: Digits of precision for floating-point FITS values
+
+         \sstitem
+          \htmlref{Iwc}{Iwc}: Add a \htmlref{Frame}{Frame} describing Intermediate World Coords?
+
+         \sstitem
+          \htmlref{Ncard}{Ncard}: Number of FITS header cards in a FitsChan
+
+         \sstitem
+          \htmlref{Nkey}{Nkey}: Number of unique keywords in a FitsChan
+
+         \sstitem
+          \htmlref{PolyTan}{PolyTan}: Use \htmlref{PVi\_m}{PVi\_m} keywords to define distorted TAN projection?
+
+         \sstitem
+          \htmlref{SipReplace}{SipReplace}: Replace SIP inverse transformation?
+
+         \sstitem
+          \htmlref{SipOK}{SipOK}: Use Spitzer Space Telescope keywords to define distortion?
+
+         \sstitem
+          \htmlref{SipReplace}{SipReplace}: Replace SIP inverse transformation?
+
+         \sstitem
+          \htmlref{TabOK}{TabOK}: Should the FITS \texttt{"} -TAB\texttt{"}  algorithm be recognised?
+
+         \sstitem
+          \htmlref{Warnings}{Warnings}: Produces warnings about selected conditions
+      }
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      In addition to those functions applicable to all Channels, the
+      following functions may also be applied to all FitsChans:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{astDelFits}{astDelFits}: Delete the current FITS card in a FitsChan
+
+         \sstitem
+          \htmlref{astEmptyFits}{astEmptyFits}: Delete all cards in a FitsChan
+
+         \sstitem
+          \htmlref{astFindFits}{astFindFits}: Find a FITS card in a FitsChan by keyword
+
+         \sstitem
+          \htmlref{astGetFits$<$X$>$}{astGetFits$<$X$>$}: Get a keyword value from a FitsChan
+
+         \sstitem
+          \htmlref{astGetTables}{astGetTables}: Retrieve any FitsTables from a FitsChan
+
+         \sstitem
+          \htmlref{astPurgeWCS}{astPurgeWCS}: Delete all WCS-related cards in a FitsChan
+
+         \sstitem
+          \htmlref{astPutCards}{astPutCards}: Stores a set of FITS header card in a FitsChan
+
+         \sstitem
+          \htmlref{astPutFits}{astPutFits}: Store a FITS header card in a FitsChan
+
+         \sstitem
+          \htmlref{astPutTable}{astPutTable}: Store a single \htmlref{FitsTable}{FitsTable} in a FitsChan
+
+         \sstitem
+          \htmlref{astPutTables}{astPutTables}: Store multiple FitsTables in a FitsChan
+
+         \sstitem
+          \htmlref{astReadFits}{astReadFits}: Read cards in through the source function
+
+         \sstitem
+          \htmlref{astRemoveTables}{astRemoveTables}: Remove one or more FitsTables from a FitsChan
+
+         \sstitem
+          \htmlref{astRetainFits}{astRetainFits}: Ensure current card is retained in a FitsChan
+
+         \sstitem
+          \htmlref{astSetFits$<$X$>$}{astSetFits$<$X$>$}: Store a new keyword value in a FitsChan
+
+         \sstitem
+          \htmlref{astShowFits}{astShowFits}: Display the contents of a FitsChan on standard output
+
+         \sstitem
+          \htmlref{astTableSource}{astTableSource}: Register a source function for FITS table access
+
+         \sstitem
+          \htmlref{astTestFits}{astTestFits}: Test if a keyword has a defined value in a FitsChan
+
+         \sstitem
+          \htmlref{astWriteFits}{astWriteFits}: Write all cards out to the sink function
+
+         \sstitem
+          AST\_SHOWFITS: Display the contents of a FitsChan on standard output
+      }
+   }
+}
+\sstroutine{
+   FitsTable
+}{
+   A representation of a FITS binary table
+}{
+   \sstdescription{
+      The FitsTable class is a representation of a FITS binary table. It
+      inherits from the \htmlref{Table}{Table} class. The parent Table is used to hold the
+      binary data of the main table, and a \htmlref{FitsChan}{FitsChan} (encapsulated within
+      the FitsTable) is used to hold the FITS header.
+
+      Note - it is not recommended to use the FitsTable class to store
+      very large tables.
+
+      FitsTables are primarily geared towards the needs of the \texttt{"} -TAB\texttt{"}
+      algorithm defined in FITS-WCS paper 2, and so do not support all
+      features of FITS binary tables. In particularly, they do not
+      provide any equivalent to the following features of FITS binary
+      tables: \texttt{"} heap\texttt{"}  data (i.e. binary data following the main table),
+      columns holding complex values, columns holding variable length
+      arrays, scaled columns, column formats, columns holding bit values,
+      8-byte integer values or logical values.
+   }
+   \sstconstructor{
+      \htmlref{astFitsTable}{astFitsTable}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The FitsTable class inherits from the Table class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The FitsTable class does not define any new attributes beyond
+      those which are applicable to all Tables.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      In addition to those functions applicable to all Tables, the
+      following functions may also be applied to all FitsTables:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{astColumnNull}{astColumnNull}: Get/set the null value for a column of a FitsTable
+
+         \sstitem
+          \htmlref{astColumnSize}{astColumnSize}: Get number of bytes needed to hold a full column of data
+
+         \sstitem
+          \htmlref{astGetColumnData}{astGetColumnData}: Retrieve all the data values stored in a column
+
+         \sstitem
+          \htmlref{astGetTableHeader}{astGetTableHeader}: Get the FITS headers from a FitsTable
+
+         \sstitem
+          \htmlref{astPutColumnData}{astPutColumnData}: Store data values in a column
+
+         \sstitem
+          \htmlref{astPutTableHeader}{astPutTableHeader}: Store FITS headers within a FitsTable
+      }
+   }
+}
+\sstroutine{
+   FluxFrame
+}{
+   Measured flux description
+}{
+   \sstdescription{
+      A FluxFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which
+      represents various systems used to represent the signal level in an
+      observation. The particular coordinate system to be used is specified
+      by setting the FluxFrame\texttt{'} s \htmlref{System}{System} attribute qualified, as necessary, by
+      other attributes such as the units, etc (see the description of the
+      System attribute for details).
+
+      All flux values are assumed to be measured at the same frequency or
+      wavelength (as given by the \htmlref{SpecVal}{SpecVal} attribute). Thus this class is
+      more appropriate for use with images rather than spectra.
+   }
+   \sstconstructor{
+      \htmlref{astFluxFrame}{astFluxFrame}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The FluxFrame class inherits from the Frame class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all Frames, every
+      FluxFrame also has the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{SpecVal}{SpecVal}: The spectral position at which the flux values are measured.
+      }
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The FluxFrame class does not define any new functions beyond those
+      which are applicable to all Frames.
+   }
+}
+\sstroutine{
+   Frame
+}{
+   Coordinate system description
+}{
+   \sstdescription{
+      This class is used to represent coordinate systems. It does this
+      in rather the same way that a frame around a graph describes the
+      coordinate space in which data are plotted. Consequently, a
+      Frame has a \htmlref{Title}{Title} (string) attribute, which describes the
+      coordinate space, and contains axes which in turn hold
+      information such as Label and Units strings which are used for
+      labelling (e.g.) graphical output. In general, however, the
+      number of axes is not restricted to two.
+
+      Functions are available for converting Frame coordinate values
+      into a form suitable for display, and also for calculating
+      distances and offsets between positions within the Frame.
+
+      Frames may also contain knowledge of how to transform to and
+      from related coordinate systems.
+   }
+   \sstconstructor{
+      \htmlref{astFrame}{astFrame}
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          When used as a \htmlref{Mapping}{Mapping}, a Frame implements a unit (null)
+         transformation in both the forward and inverse directions
+         (equivalent to a \htmlref{UnitMap}{UnitMap}). The \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attribute values are
+         both equal to the number of Frame axes.
+      }
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The Frame class inherits from the Mapping class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all Mappings, every
+      Frame also has the following attributes (if the Frame has only one
+      axis, the axis specifier can be omited from the following attribute
+      names):
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{AlignSystem}{AlignSystem}: Coordinate system used to align Frames
+
+         \sstitem
+          \htmlref{Bottom(axis)}{Bottom(axis)}: Lowest axis value to display
+
+         \sstitem
+          \htmlref{Digits/Digits(axis)}{Digits/Digits(axis)}: Number of digits of precision
+
+         \sstitem
+          \htmlref{Direction(axis)}{Direction(axis)}: Display axis in conventional direction?
+
+         \sstitem
+          \htmlref{Domain}{Domain}: Coordinate system domain
+
+         \sstitem
+          \htmlref{Dtai}{Dtai}: Difference between the TAI and UTC timescale
+
+         \sstitem
+          \htmlref{Dut1}{Dut1}: Difference between the UT1 and UTC timescale
+
+         \sstitem
+          \htmlref{Epoch}{Epoch}: Epoch of observation
+
+         \sstitem
+          \htmlref{Format(axis)}{Format(axis)}: Format specification for axis values
+
+         \sstitem
+          \htmlref{InternalUnit(axis)}{InternalUnit(axis)}: Physical units for unformated axis values
+
+         \sstitem
+          \htmlref{Label(axis)}{Label(axis)}: \htmlref{Axis}{Axis} label
+
+         \sstitem
+          \htmlref{MatchEnd}{MatchEnd}: Match trailing axes?
+
+         \sstitem
+          \htmlref{MaxAxes}{MaxAxes}: Maximum number of Frame axes to match
+
+         \sstitem
+          \htmlref{MinAxes}{MinAxes}: Minimum number of Frame axes to match
+
+         \sstitem
+          \htmlref{Naxes}{Naxes}: Number of Frame axes
+
+         \sstitem
+          \htmlref{NormUnit(axis)}{NormUnit(axis)}: Normalised physical units for formatted axis values
+
+         \sstitem
+          \htmlref{ObsAlt}{ObsAlt}: Geodetic altitude of observer
+
+         \sstitem
+          \htmlref{ObsLat}{ObsLat}: Geodetic latitude of observer
+
+         \sstitem
+          \htmlref{ObsLon}{ObsLon}: Geodetic longitude of observer
+
+         \sstitem
+          \htmlref{Permute}{Permute}: Permute axis order?
+
+         \sstitem
+          \htmlref{PreserveAxes}{PreserveAxes}: Preserve axes?
+
+         \sstitem
+          \htmlref{Symbol(axis)}{Symbol(axis)}: Axis symbol
+
+         \sstitem
+          \htmlref{System}{System}: Coordinate system used to describe the domain
+
+         \sstitem
+          \htmlref{Title}{Title}: Frame title
+
+         \sstitem
+          \htmlref{Top(axis)}{Top(axis)}: Highest axis value to display
+
+         \sstitem
+          \htmlref{Unit(axis)}{Unit(axis)}: Physical units for formatted axis values
+      }
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      In addition to those functions applicable to all Mappings, the
+      following functions may also be applied to all Frames:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{astAngle}{astAngle}: Calculate the angle subtended by two points at a third point
+
+         \sstitem
+          \htmlref{astAxAngle}{astAxAngle}: Find the angle from an axis, to a line through two points
+
+         \sstitem
+          \htmlref{astAxDistance}{astAxDistance}: Calculate the distance between two axis values
+
+         \sstitem
+          \htmlref{astAxNorm}{astAxNorm}: Normalises an array of axis values
+
+         \sstitem
+          \htmlref{astAxOffset}{astAxOffset}: Calculate an offset along an axis
+
+         \sstitem
+          \htmlref{astConvert}{astConvert}: Determine how to convert between two coordinate systems
+
+         \sstitem
+          \htmlref{astDistance}{astDistance}: Calculate the distance between two points in a Frame
+
+         \sstitem
+          \htmlref{astFindFrame}{astFindFrame}: Find a coordinate system with specified characteristics
+
+         \sstitem
+          \htmlref{astFormat}{astFormat}: Format a coordinate value for a Frame axis
+
+         \sstitem
+          \htmlref{astGetActiveUnit}{astGetActiveUnit}: Determines how the Unit attribute will be used
+
+         \sstitem
+          \htmlref{astIntersect}{astIntersect}: Find the intersection between two geodesic curves
+
+         \sstitem
+          \htmlref{astMatchAxes}{astMatchAxes}: Find any corresponding axes in two Frames
+
+         \sstitem
+          \htmlref{astNorm}{astNorm}: Normalise a set of Frame coordinates
+
+         \sstitem
+          \htmlref{astOffset}{astOffset}: Calculate an offset along a geodesic curve
+
+         \sstitem
+          \htmlref{astOffset2}{astOffset2}: Calculate an offset along a geodesic curve in a 2D Frame
+
+         \sstitem
+          \htmlref{astPermAxes}{astPermAxes}: Permute the order of a Frame\texttt{'} s axes
+
+         \sstitem
+          \htmlref{astPickAxes}{astPickAxes}: Create a new Frame by picking axes from an existing one
+
+         \sstitem
+          \htmlref{astResolve}{astResolve}: Resolve a vector into two orthogonal components
+
+         \sstitem
+          \htmlref{astSetActiveUnit}{astSetActiveUnit}: Specify how the Unit attribute should be used
+
+         \sstitem
+          \htmlref{astUnformat}{astUnformat}: Read a formatted coordinate value for a Frame axis
+      }
+   }
+}
+\sstroutine{
+   FrameSet
+}{
+   Set of inter-related coordinate systems
+}{
+   \sstdescription{
+      A FrameSet consists of a set of one or more Frames (which
+      describe coordinate systems), connected together by Mappings
+      (which describe how the coordinate systems are inter-related). A
+      FrameSet makes it possible to obtain a \htmlref{Mapping}{Mapping} between any pair
+      of these Frames (i.e. to convert between any of the coordinate
+      systems which it describes).  The individual Frames are
+      identified within the FrameSet by an integer index, with Frames
+      being numbered consecutively from one as they are added to the
+      FrameSet.
+
+      Every FrameSet has a \texttt{"} base\texttt{"}  \htmlref{Frame}{Frame} and a \texttt{"} current\texttt{"}  Frame (which
+      are allowed to be the same). Any of the Frames may be nominated
+      to hold these positions, and the choice is determined by the
+      values of the FrameSet\texttt{'} s \htmlref{Base}{Base} and \htmlref{Current}{Current} attributes, which hold
+      the indices of the relevant Frames.  By default, the first Frame
+      added to a FrameSet is its base Frame, and the last one added is
+      its current Frame.
+
+      The base Frame describes the \texttt{"} native\texttt{"}  coordinate system of
+      whatever the FrameSet is used to calibrate (e.g. the pixel
+      coordinates of an image) and the current Frame describes the
+      \texttt{"} apparent\texttt{"}  coordinate system in which it should be viewed
+      (e.g. displayed, etc.). Any further Frames represent a library
+      of alternative coordinate systems, which may be selected by
+      making them current.
+
+      When a FrameSet is used in a context that requires a Frame,
+      (e.g. obtaining its \htmlref{Title}{Title} value, or number of axes), the current
+      Frame is used. A FrameSet may therefore be used in place of its
+      current Frame in most situations.
+
+      When a FrameSet is used in a context that requires a Mapping,
+      the Mapping used is the one between its base Frame and its
+      current Frame. Thus, a FrameSet may be used to convert \texttt{"} native\texttt{"}
+      coordinates into \texttt{"} apparent\texttt{"}  ones, and vice versa. Like any
+      Mapping, a FrameSet may also be inverted (see \htmlref{astInvert}{astInvert}), which
+      has the effect of interchanging its base and current Frames and
+      hence of reversing the Mapping between them.
+
+      Regions may be added into a FrameSet (since a \htmlref{Region}{Region} is a type of
+      Frame), either explicitly or as components within CmpFrames. In this
+      case the Mapping between a pair of Frames within a FrameSet will
+      include the effects of the clipping produced by any Regions included
+      in the path between the Frames.
+   }
+   \sstconstructor{
+      \htmlref{astFrameSet}{astFrameSet}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The FrameSet class inherits from the Frame class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all Frames, every
+      FrameSet also has the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{AllVariants}{AllVariants}: List of all variant mappings stored with current Frame
+
+         \sstitem
+          \htmlref{Base}{Base}: FrameSet base Frame index
+
+         \sstitem
+          \htmlref{Current}{Current}: FrameSet current Frame index
+
+         \sstitem
+          \htmlref{Nframe}{Nframe}: Number of Frames in a FrameSet
+
+         \sstitem
+          \htmlref{Variant}{Variant}: Name of variant mapping in use by current Frame
+
+      }
+      Every FrameSet also inherits any further attributes that belong
+      to its current Frame, regardless of that Frame\texttt{'} s class. (For
+      example, the \htmlref{Equinox}{Equinox} attribute, defined by the \htmlref{SkyFrame}{SkyFrame} class, is
+      inherited by any FrameSet which has a SkyFrame as its current
+      Frame.) The set of attributes belonging to a FrameSet may therefore
+      change when a new current Frame is selected.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      In addition to those functions applicable to all Frames, the
+      following functions may also be applied to all FrameSets:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{astAddFrame}{astAddFrame}: Add a Frame to a FrameSet to define a new coordinate
+         system
+
+         \sstitem
+          \htmlref{astAddVariant}{astAddVariant}: Add a variant Mapping to the current Frame
+
+         \sstitem
+          \htmlref{astGetFrame}{astGetFrame}: Obtain a pointer to a specified Frame in a FrameSet
+
+         \sstitem
+          \htmlref{astGetMapping}{astGetMapping}: Obtain a Mapping between two Frames in a FrameSet
+
+         \sstitem
+          \htmlref{astMirrorVariants}{astMirrorVariants}: Make the current Frame mirror variant Mappings in another Frame
+
+         \sstitem
+          \htmlref{astRemapFrame}{astRemapFrame}: Modify a Frame\texttt{'} s relationship to the other Frames in a
+         FrameSet
+
+         \sstitem
+          \htmlref{astRemoveFrame}{astRemoveFrame}: Remove a Frame from a FrameSet
+      }
+   }
+}
+\sstroutine{
+   GrismMap
+}{
+   Transform 1-dimensional coordinates using a grism dispersion equation
+}{
+   \sstdescription{
+      A GrismMap is a specialised form of \htmlref{Mapping}{Mapping} which transforms
+      1-dimensional coordinates using the spectral dispersion equation
+      described in FITS-WCS paper III \texttt{"} Representation of spectral
+      coordinates in FITS\texttt{"} . This describes the dispersion produced by
+      gratings, prisms and grisms.
+
+      When initially created, the forward transformation of a GrismMap
+      transforms input \texttt{"} grism parameter\texttt{"}  values into output wavelength
+      values. The \texttt{"} grism parameter\texttt{"}  is a dimensionless value which is
+      linearly related to position on the detector. It is defined in FITS-WCS
+      paper III as \texttt{"} the offset on the detector from the point of intersection
+      of the camera axis, measured in units of the effective local length\texttt{"} .
+      The units in which wavelength values are expected or returned is
+      determined by the values supplied for the \htmlref{GrismWaveR}{GrismWaveR}, \htmlref{GrismNRP}{GrismNRP} and
+      \htmlref{GrismG}{GrismG} attribute: whatever units are used for these attributes will
+      also be used for the wavelength values.
+   }
+   \sstconstructor{
+      \htmlref{astGrismMap}{astGrismMap}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The GrismMap class inherits from the Mapping class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all Mappings, every
+      GrismMap also has the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{GrismNR}{GrismNR}: The refractive index at the reference wavelength
+
+         \sstitem
+          \htmlref{GrismNRP}{GrismNRP}: Rate of change of refractive index with wavelength
+
+         \sstitem
+          \htmlref{GrismWaveR}{GrismWaveR}: The reference wavelength
+
+         \sstitem
+          \htmlref{GrismAlpha}{GrismAlpha}: The angle of incidence of the incoming light
+
+         \sstitem
+          \htmlref{GrismG}{GrismG}: The grating ruling density
+
+         \sstitem
+          \htmlref{GrismM}{GrismM}: The interference order
+
+         \sstitem
+          \htmlref{GrismEps}{GrismEps}: The angle between the normal and the dispersion plane
+
+         \sstitem
+          \htmlref{GrismTheta}{GrismTheta}: Angle between normal to detector plane and reference ray
+      }
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The GrismMap class does not define any new functions beyond those
+      which are applicable to all Mappings.
+   }
+}
+\sstroutine{
+   Interval
+}{
+   A region representing an interval on one or more axes of a Frame
+}{
+   \sstdescription{
+      The Interval class implements a \htmlref{Region}{Region} which represents upper
+      and/or lower limits on one or more axes of a \htmlref{Frame}{Frame}. For a point to
+      be within the region represented by the Interval, the point must
+      satisfy all the restrictions placed on all the axes. The point is
+      outside the region if it fails to satisfy any one of the restrictions.
+      Each axis may have either an upper limit, a lower limit, both or
+      neither. If both limits are supplied but are in reverse order (so
+      that the lower limit is greater than the upper limit), then the
+      interval is an excluded interval, rather than an included interval.
+
+      Note, The Interval class makes no allowances for cyclic nature of
+      some coordinate systems (such as \htmlref{SkyFrame}{SkyFrame} coordinates). A \htmlref{Box}{Box}
+      should usually be used in these cases since this requires the user
+      to think about suitable upper and lower limits,
+   }
+   \sstconstructor{
+      \htmlref{astInterval}{astInterval}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The Interval class inherits from the Region class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The Interval class does not define any new attributes beyond
+      those which are applicable to all Regions.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The Interval class does not define any new functions beyond those
+      which are applicable to all Regions.
+   }
+}
+\sstroutine{
+   IntraMap
+}{
+   Map points using a private transformation function
+}{
+   \sstdescription{
+      The IntraMap class provides a specialised form of \htmlref{Mapping}{Mapping} which
+      encapsulates a privately-defined coordinate transformation
+      other AST Mapping. This allows you to create Mappings that
+      perform any conceivable coordinate transformation.
+
+      However, an IntraMap is intended for use within a single program
+      or a private suite of software, where all programs have access
+      to the same coordinate transformation functions (i.e. can be
+      linked against them). IntraMaps should not normally be stored in
+      datasets which may be exported for processing by other software,
+      since that software will not have the necessary transformation
+      functions available, resulting in an error.
+
+      You must register any coordinate transformation functions to be
+      used using \htmlref{astIntraReg}{astIntraReg} before creating an IntraMap.
+   }
+   \sstconstructor{
+      \htmlref{astIntraMap}{astIntraMap} (also see astIntraReg)
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The IntraMap class inherits from the Mapping class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all Mappings, every
+      IntraMap also has the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{IntraFlag}{IntraFlag}: IntraMap identification string
+      }
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The IntraMap class does not define any new functions beyond those
+      which are applicable to all Mappings.
+   }
+}
+\sstroutine{
+   KeyMap
+}{
+   Store a set of key/value pairs
+}{
+   \sstdescription{
+      The KeyMap class is used to store a set of values with associated keys
+      which identify the values. The keys are strings. These may be case
+      sensitive or insensitive as selected by the \htmlref{KeyCase}{KeyCase} attribute, and
+      trailing spaces are ignored. The value associated with a key can be
+      integer (signed 4 and 2 byte, or unsigned 1 byte), floating point
+      (single or double precision),
+      void pointer,
+      character string or AST \htmlref{Object}{Object} pointer. Each
+      value can be a scalar or a one-dimensional vector. A KeyMap is
+      conceptually similar to a \htmlref{Mapping}{Mapping} in that a KeyMap transforms an
+      input into an output - the input is the key, and the output is the
+      value associated with the key. However, this is only a conceptual
+      similarity, and it should be noted that the KeyMap class inherits from
+      the Object class rather than the Mapping class. The methods of the
+      Mapping class cannot be used with a KeyMap.
+   }
+   \sstconstructor{
+      \htmlref{astKeyMap}{astKeyMap}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The KeyMap class inherits from the Object class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all Objects, every
+      KeyMap also has the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{KeyCase}{KeyCase}: Sets the case in which keys are stored
+
+         \sstitem
+          \htmlref{KeyError}{KeyError}: \htmlref{Report}{Report} an error if the requested key does not exist?
+
+         \sstitem
+          \htmlref{SizeGuess}{SizeGuess}: The expected size of the KeyMap.
+
+         \sstitem
+          \htmlref{SortBy}{SortBy}: Determines how keys are sorted in a KeyMap.
+
+         \sstitem
+          \htmlref{MapLocked}{MapLocked}: Prevent new entries being added to the KeyMap?
+      }
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      In addition to those functions applicable to all Objects, the
+      following functions may also be applied to all KeyMaps:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{astMapDefined}{astMapDefined}: Does a KeyMap contain a defined value for a key?
+
+         \sstitem
+          \htmlref{astMapGetC}{astMapGetC}: Get a scalar or vector entry as a single string.
+
+         \sstitem
+          \htmlref{astMapGet0$<$X$>$}{astMapGet0$<$X$>$}: Get a named scalar entry from a KeyMap
+
+         \sstitem
+          \htmlref{astMapGet1$<$X$>$}{astMapGet1$<$X$>$}: Get a named vector entry from a KeyMap
+
+         \sstitem
+          \htmlref{astMapGetElem$<$X$>$}{astMapGetElem$<$X$>$}: Get an element of a named vector entry from a KeyMap
+
+         \sstitem
+          \htmlref{astMapHasKey}{astMapHasKey}: Does the KeyMap contain a named entry?
+
+         \sstitem
+          \htmlref{astMapKey}{astMapKey}: Return the key name at a given index in the KeyMap
+
+         \sstitem
+          \htmlref{astMapLenC}{astMapLenC}: Get the length of a named character entry in a KeyMap
+
+         \sstitem
+          \htmlref{astMapLength}{astMapLength}: Get the length of a named entry in a KeyMap
+
+         \sstitem
+          \htmlref{astMapCopy}{astMapCopy}: Copy entries from one KeyMap into another
+
+         \sstitem
+          \htmlref{astMapPut0$<$X$>$}{astMapPut0$<$X$>$}: Add a new scalar entry to a KeyMap
+
+         \sstitem
+          \htmlref{astMapPut1$<$X$>$}{astMapPut1$<$X$>$}: Add a new vector entry to a KeyMap
+
+         \sstitem
+          \htmlref{astMapPutElem$<$X$>$}{astMapPutElem$<$X$>$}: Puts a value into a vector entry in a KeyMap
+
+         \sstitem
+          \htmlref{astMapPutU}{astMapPutU}: Add a new entry to a KeyMap with an undefined value
+
+         \sstitem
+          \htmlref{astMapRemove}{astMapRemove}: Removed a named entry from a KeyMap
+
+         \sstitem
+          \htmlref{astMapRename}{astMapRename}: Rename an existing entry in a KeyMap
+
+         \sstitem
+          \htmlref{astMapSize}{astMapSize}: Get the number of entries in a KeyMap
+
+         \sstitem
+          \htmlref{astMapType}{astMapType}: Return the data type of a named entry in a map
+      }
+   }
+}
+\sstroutine{
+   LutMap
+}{
+   Transform 1-dimensional coordinates using a lookup table
+}{
+   \sstdescription{
+      A LutMap is a specialised form of \htmlref{Mapping}{Mapping} which transforms
+      1-dimensional coordinates by using linear interpolation in a
+      lookup table.
+
+      Each input coordinate value is first scaled to give the index of
+      an entry in the table by subtracting a starting value (the input
+      coordinate corresponding to the first table entry) and dividing
+      by an increment (the difference in input coordinate value
+      between adjacent table entries).
+
+      The resulting index will usually contain a fractional part, so
+      the output coordinate value is then generated by interpolating
+      linearly between the appropriate entries in the table. If the
+      index lies outside the range of the table, linear extrapolation
+      is used based on the two nearest entries (i.e. the two entries
+      at the start or end of the table, as appropriate). If either of the
+      entries used for the interplation has a value of AST\_\_BAD, then the
+      interpolated value is returned as AST\_\_BAD.
+
+      If the lookup table entries increase or decrease monotonically
+      (ignoring any flat sections), then the inverse transformation may
+      also be performed.
+   }
+   \sstconstructor{
+      \htmlref{astLutMap}{astLutMap}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The LutMap class inherits from the Mapping class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all Mappings, every
+      LutMap also has the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{LutEpsilon}{LutEpsilon}: The relative error of the values in the table.
+
+         \sstitem
+          \htmlref{LutInterp}{LutInterp}: The interpolation method to use between table entries.
+      }
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The LutMap class does not define any new functions beyond those
+      which are applicable to all Mappings.
+   }
+}
+\sstroutine{
+   Mapping
+}{
+   Inter-relate two coordinate systems
+}{
+   \sstdescription{
+      This class provides the basic facilities for transforming a set
+      of coordinates (representing \texttt{"} input\texttt{"}  points) to give a new set
+      of coordinates (representing \texttt{"} output\texttt{"}  points).  It is used to
+      describe the relationship which exists between two different
+      coordinate systems and to implement operations which make use of
+      this (such as transforming coordinates and resampling grids of
+      data).  However, the Mapping class does not have a constructor
+      function of its own, as it is simply a container class for a
+      family of specialised Mappings which implement particular types
+      of coordinate transformation.
+   }
+   \sstconstructor{
+      None.
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The Mapping class inherits from the \htmlref{Object}{Object} class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all Objects, every
+      Mapping also has the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{Invert}{Invert}: Mapping inversion flag
+
+         \sstitem
+          \htmlref{IsLinear}{IsLinear}: Is the Mapping linear?
+
+         \sstitem
+          \htmlref{IsSimple}{IsSimple}: Has the Mapping been simplified?
+
+         \sstitem
+          \htmlref{Nin}{Nin}: Number of input coordinates for a Mapping
+
+         \sstitem
+          \htmlref{Nout}{Nout}: Number of output coordinates for a Mapping
+
+         \sstitem
+          \htmlref{Report}{Report}: Report transformed coordinates?
+
+         \sstitem
+          \htmlref{TranForward}{TranForward}: Forward transformation defined?
+
+         \sstitem
+          \htmlref{TranInverse}{TranInverse}: Inverse transformation defined?
+      }
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      In addition to those functions applicable to all Objects, the
+      following functions may also be applied to all Mappings:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{astDecompose}{astDecompose}: Decompose a Mapping into two component Mappings
+
+         \sstitem
+          \htmlref{astTranGrid}{astTranGrid}: Transform a grid of positions
+
+         \sstitem
+          \htmlref{astInvert}{astInvert}: Invert a Mapping
+
+         \sstitem
+          \htmlref{astLinearApprox}{astLinearApprox}: Calculate a linear approximation to a Mapping
+
+         \sstitem
+          \htmlref{astMapBox}{astMapBox}: Find a bounding box for a Mapping
+
+         \sstitem
+          \htmlref{astMapSplit}{astMapSplit}: Split a Mapping up into parallel component Mappings
+
+         \sstitem
+          \htmlref{astQuadApprox}{astQuadApprox}: Calculate a quadratic approximation to a 2D Mapping
+
+         \sstitem
+          \htmlref{astRate}{astRate}: Calculate the rate of change of a Mapping output
+
+         \sstitem
+          \htmlref{astRebin$<$X$>$}{astRebin$<$X$>$}: Rebin a region of a data grid
+
+         \sstitem
+          \htmlref{astRebinSeq$<$X$>$}{astRebinSeq$<$X$>$}: Rebin a region of a sequence of data grids
+
+         \sstitem
+          \htmlref{astResample$<$X$>$}{astResample$<$X$>$}: Resample a region of a data grid
+
+         \sstitem
+          \htmlref{astRemoveRegions}{astRemoveRegions}: Remove any Regions from a Mapping
+
+         \sstitem
+          \htmlref{astSimplify}{astSimplify}: Simplify a Mapping
+
+         \sstitem
+          \htmlref{astTran1}{astTran1}: Transform 1-dimensional coordinates
+
+         \sstitem
+          \htmlref{astTran2}{astTran2}: Transform 2-dimensional coordinates
+
+         \sstitem
+          \htmlref{astTranN}{astTranN}: Transform N-dimensional coordinates
+
+         \sstitem
+          \htmlref{astTranP}{astTranP}: Transform N-dimensional coordinates held in separate arrays
+      }
+   }
+}
+\sstroutine{
+   MathMap
+}{
+   Transform coordinates using mathematical expressions
+}{
+   \sstdescription{
+      A MathMap is a \htmlref{Mapping}{Mapping} which allows you to specify a set of forward
+      and/or inverse transformation functions using arithmetic operations
+      and mathematical functions similar to those available in C. The
+      MathMap interprets these functions at run-time, whenever its forward
+      or inverse transformation is required. Because the functions are not
+      compiled in the normal sense (unlike an \htmlref{IntraMap}{IntraMap}), they may be used to
+      describe coordinate transformations in a transportable manner. A
+      MathMap therefore provides a flexible way of defining new types of
+      Mapping whose descriptions may be stored as part of a dataset and
+      interpreted by other programs.
+   }
+   \sstconstructor{
+      \htmlref{astMathMap}{astMathMap}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The MathMap class inherits from the Mapping class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all Mappings, every
+      MathMap also has the following attributes:
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{Seed}{Seed}: Random number seed
+
+         \sstitem
+          \htmlref{SimpFI}{SimpFI}: Forward-inverse MathMap pairs simplify?
+
+         \sstitem
+          \htmlref{SimpIF}{SimpIF}: Inverse-forward MathMap pairs simplify?
+      }
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The MathMap class does not define any new functions beyond those
+      which are applicable to all Mappings.
+   }
+}
+\sstroutine{
+   MatrixMap
+}{
+   Map coordinates by multiplying by a matrix
+}{
+   \sstdescription{
+      A MatrixMap is form of \htmlref{Mapping}{Mapping} which performs a general linear
+      transformation. Each set of input coordinates, regarded as a
+      column-vector, are pre-multiplied by a matrix (whose elements
+      are specified when the MatrixMap is created) to give a new
+      column-vector containing the output coordinates. If appropriate,
+      the inverse transformation may also be performed.
+   }
+   \sstconstructor{
+      \htmlref{astMatrixMap}{astMatrixMap}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The MatrixMap class inherits from the Mapping class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The MatrixMap class does not define any new attributes beyond
+      those which are applicable to all Mappings.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The MatrixMap class does not define any new functions beyond those
+      which are applicable to all Mappings.
+   }
+}
+\sstroutine{
+   NormMap
+}{
+   Normalise coordinates using a supplied Frame
+}{
+   \sstdescription{
+      The NormMap class implements a \htmlref{Mapping}{Mapping} which normalises coordinate
+      values using the
+      \htmlref{astNorm}{astNorm} function
+      of a supplied \htmlref{Frame}{Frame}. The number of inputs and outputs of a NormMap
+      are both equal to the number of axes in the supplied Frame.
+
+      The forward and inverse transformation of a NormMap are both
+      defined but are identical (that is, they do not form a real inverse
+      pair in that the inverse transformation does not undo the
+      normalisation, instead it reapplies it). However, the
+      \htmlref{astSimplify}{astSimplify}
+      function will replace neighbouring pairs of forward and inverse
+      NormMaps by a single \htmlref{UnitMap}{UnitMap} (so long as the Frames encapsulated by
+      the two NormMaps are equal - i.e. have the same class and the same
+      attribute values). This means, for instance, that if a \htmlref{CmpMap}{CmpMap} contains
+      a NormMap, the CmpMap will still cancel with its own inverse.
+   }
+   \sstconstructor{
+      \htmlref{astNormMap}{astNormMap}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The NormMap class inherits from the Mapping class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The NormMap class does not define any new attributes beyond
+      those which are applicable to all Mappings.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The NormMap class does not define any new functions beyond those
+      which are applicable to all Mappings.
+   }
+}
+\sstroutine{
+   NullRegion
+}{
+   A boundless region within a Frame
+}{
+   \sstdescription{
+      The NullRegion class implements a \htmlref{Region}{Region} with no bounds within a \htmlref{Frame}{Frame}.
+      If the \htmlref{Negated}{Negated} attribute of a NullRegion is false, the NullRegion
+      represents a Region containing no points. If the Negated attribute of
+      a NullRegion is true, the NullRegion represents an infinite Region
+      (that is, all points in the coordinate system are inside the NullRegion).
+   }
+   \sstconstructor{
+      \htmlref{astNullRegion}{astNullRegion}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The NullRegion class inherits from the Region class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The NullRegion class does not define any new attributes beyond
+      those which are applicable to all Regions.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The NullRegion class does not define any new functions beyond those
+      which are applicable to all Regions.
+   }
+}
+\sstroutine{
+   Object
+}{
+   Base class for all AST Objects
+}{
+   \sstdescription{
+      This class is the base class from which all other classes in the
+      AST library are derived. It provides all the basic Object
+      behaviour and Object manipulation facilities required throughout
+      the library. There is no Object constructor, however, as Objects
+      on their own are not useful.
+   }
+   \sstconstructor{
+      None.
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The Object base class does not inherit from any other class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      All Objects have the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{Class}{Class}: Object class name
+
+         \sstitem
+          \htmlref{ID}{ID}: Object identification string
+
+         \sstitem
+          \htmlref{Ident}{Ident}: Permanent Object identification string
+
+         \sstitem
+          \htmlref{Nobject}{Nobject}: Number of Objects in class
+
+         \sstitem
+          \htmlref{ObjSize}{ObjSize}: The in-memory size of the Object in bytes
+
+         \sstitem
+          \htmlref{RefCount}{RefCount}: Count of active Object pointers
+
+         \sstitem
+          \htmlref{UseDefs}{UseDefs}: Allow use of default values for Object attributes?
+      }
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The following functions may be applied to all Objects:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{astAnnul}{astAnnul}: Annul a pointer to an Object
+
+         \sstitem
+          \htmlref{astBegin}{astBegin}: Begin a new AST context
+
+         \sstitem
+          \htmlref{astClear}{astClear}: Clear attribute values for an Object
+
+         \sstitem
+          \htmlref{astClone}{astClone}: Clone a pointer to an Object
+
+         \sstitem
+          \htmlref{astCopy}{astCopy}: Copy an Object
+
+         \sstitem
+          \htmlref{astCreatedAt}{astCreatedAt}: Returns information about where an object was created
+
+         \sstitem
+          \htmlref{astDelete}{astDelete}: Delete an Object
+
+         \sstitem
+          \htmlref{astEnd}{astEnd}: End an AST context
+
+         \sstitem
+          \htmlref{astEscapes}{astEscapes}: Control whether graphical escape sequences are removed
+
+         \sstitem
+          \htmlref{astExempt}{astExempt}: Exempt an Object pointer from AST context handling
+
+         \sstitem
+          \htmlref{astExport}{astExport}: Export an Object pointer to an outer context
+
+         \sstitem
+          \htmlref{astGet$<$X$>$}{astGet$<$X$>$}: Get an attribute value for an Object
+
+         \sstitem
+          \htmlref{astHasAttribute}{astHasAttribute}: Test if an Object has a named attribute
+
+         \sstitem
+          \htmlref{astImport}{astImport}: Import an Object pointer to the current context
+
+         \sstitem
+          \htmlref{astIsA$<$Class$>$}{astIsA$<$Class$>$}: Test class membership
+
+         \sstitem
+          \htmlref{astLock}{astLock}: Lock an Object for use by the calling thread
+
+         \sstitem
+          \htmlref{astToString}{astToString}: Create an in-memory serialisation of an Object
+
+         \sstitem
+          \htmlref{astSame}{astSame}: Do two AST pointers refer to the same Object?
+
+         \sstitem
+          \htmlref{astSet}{astSet}: Set attribute values for an Object
+
+         \sstitem
+          \htmlref{astSet$<$X$>$}{astSet$<$X$>$}: Set an attribute value for an Object
+
+         \sstitem
+          \htmlref{astShow}{astShow}: Display a textual representation of an Object on standard
+         output
+
+         \sstitem
+          \htmlref{astTest}{astTest}: Test if an attribute value is set for an Object
+
+         \sstitem
+          \htmlref{astTune}{astTune}: Set or get an integer AST tuning parameter
+
+         \sstitem
+          \htmlref{astTuneC}{astTuneC}: Set or get a character AST tuning parameter
+
+         \sstitem
+          \htmlref{astUnlock}{astUnlock}: Unlock an Object for use by other threads
+
+         \sstitem
+          \htmlref{astFromString}{astFromString}: Re-create an Object from an in-memory serialisation
+
+         \sstitem
+          \htmlref{astVersion}{astVersion}: Return the verson of the AST library being used.
+      }
+   }
+}
+\sstroutine{
+   PcdMap
+}{
+   Apply 2-dimensional pincushion/barrel distortion
+}{
+   \sstdescription{
+      A PcdMap is a non-linear \htmlref{Mapping}{Mapping} which transforms 2-dimensional
+      positions to correct for the radial distortion introduced by some
+      cameras and telescopes. This can take the form either of pincushion
+      or barrel distortion, and is characterized by a single distortion
+      coefficient.
+
+      A PcdMap is specified by giving this distortion coefficient and the
+      coordinates of the centre of the radial distortion. The forward
+      transformation of a PcdMap applies the distortion:
+
+         RD = R $*$ ( 1 $+$ C $*$ R $*$ R )
+
+      where R is the undistorted radial distance from the distortion
+      centre (specified by attribute PcdCen), RD is the radial distance
+      from the same centre in the presence of distortion, and C is the
+      distortion coefficient (given by attribute \htmlref{Disco}{Disco}).
+
+      The inverse transformation of a PcdMap removes the distortion
+      produced by the forward transformation. The expression used to derive
+      R from RD is an approximate inverse of the expression above.
+   }
+   \sstconstructor{
+      \htmlref{astPcdMap}{astPcdMap}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The PcdMap class inherits from the Mapping class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all Mappings, every
+      PcdMap also has the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{Disco}{Disco}: PcdMap pincushion/barrel distortion coefficient
+
+         \sstitem
+          \htmlref{PcdCen(axis)}{PcdCen(axis)}: Centre coordinates of pincushion/barrel distortion
+      }
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The PcdMap class does not define any new functions beyond those
+      which are applicable to all Mappings.
+   }
+}
+\sstroutine{
+   PermMap
+}{
+   Coordinate permutation Mapping
+}{
+   \sstdescription{
+      A PermMap is a \htmlref{Mapping}{Mapping} which permutes the order of coordinates,
+      and possibly also changes the number of coordinates, between its
+      input and output.
+
+      In addition to permuting the coordinate order, a PermMap may
+      also assign constant values to coordinates. This is useful when
+      the number of coordinates is being increased as it allows fixed
+      values to be assigned to any new ones.
+   }
+   \sstconstructor{
+      \htmlref{astPermMap}{astPermMap}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The PermMap class inherits from the Mapping class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The PermMap class does not define any new attributes beyond
+      those which are applicable to all Mappings.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The PermMap class does not define any new functions beyond those
+      which are applicable to all Mappings.
+   }
+}
+\sstroutine{
+   Plot
+}{
+   Provide facilities for 2D graphical output
+}{
+   \sstdescription{
+      This class provides facilities for producing 2D graphical output.
+      A Plot is a specialised form of \htmlref{FrameSet}{FrameSet}, in which the base
+      \htmlref{Frame}{Frame} describes a \texttt{"} graphical\texttt{"}  coordinate system and is
+      associated with a rectangular plotting area in the underlying
+      graphics system. This plotting area is where graphical output
+      appears. It is defined when the Plot is created.
+
+      The current Frame of a Plot describes a \texttt{"} physical\texttt{"}  coordinate
+      system, which is the coordinate system in which plotting
+      operations are specified. The results of each plotting operation
+      are automatically transformed into graphical coordinates so as
+      to appear in the plotting area (subject to any clipping which
+      may be in effect).
+
+      Because the \htmlref{Mapping}{Mapping} between physical and graphical coordinates
+      may often be non-linear, or even discontinuous, most plotting
+      does not result in simple straight lines. The basic plotting
+      element is therefore not a straight line, but a geodesic curve
+      (see \htmlref{astCurve}{astCurve}, \htmlref{astGenCurve}{astGenCurve} and \htmlref{astPolyCurve}{astPolyCurve}). A Plot also provides facilities for
+      drawing markers or symbols (\htmlref{astMark}{astMark}), text (\htmlref{astText}{astText}) and grid lines
+      (\htmlref{astGridLine}{astGridLine}). It is also possible to draw curvilinear axes with
+      optional coordinate grids (\htmlref{astGrid}{astGrid}).
+      A range of Plot attributes is available to allow precise control
+      over the appearance of graphical output produced by these
+      functions.
+
+      You may select different physical coordinate systems in which to
+      plot (including the native graphical coordinate system itself)
+      by selecting different Frames as the current Frame of a Plot,
+      using its \htmlref{Current}{Current} attribute.  You may also set up clipping (see
+      \htmlref{astClip}{astClip}) to limit the extent of any plotting you perform, and
+      this may be done in any of the coordinate systems associated
+      with the Plot, not necessarily the one you are plotting in.
+
+      Like any FrameSet, a Plot may also be used as a Frame. In this
+      case, it behaves like its current Frame, which describes the
+      physical coordinate system.
+
+      When used as a Mapping, a Plot describes the inter-relation
+      between graphical coordinates (its base Frame) and physical
+      coordinates (its current Frame).  It differs from a normal
+      FrameSet, however, in that an attempt to transform points which
+      lie in clipped areas of the Plot will result in bad coordinate
+      values (AST\_\_BAD).
+   }
+   \sstconstructor{
+      \htmlref{astPlot}{astPlot}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The Plot class inherits from the FrameSet class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all FrameSets, every
+      Plot also has the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          Abbrev: Abbreviate leading fields?
+
+         \sstitem
+          \htmlref{Border}{Border}: Draw a border around valid regions of a Plot?
+
+         \sstitem
+          \htmlref{Clip}{Clip}: Clip lines and/or markers at the Plot boundary?
+
+         \sstitem
+          \htmlref{ClipOp}{ClipOp}: Combine Plot clipping limits using a boolean OR?
+
+         \sstitem
+          \htmlref{Colour(element)}{Colour(element)}: Colour index for a Plot element
+
+         \sstitem
+          \htmlref{DrawAxes(axis)}{DrawAxes(axis)}: Draw axes for a Plot?
+
+         \sstitem
+          \htmlref{DrawTitle}{DrawTitle}: Draw a title for a Plot?
+
+         \sstitem
+          \htmlref{Escape}{Escape}: Allow changes of character attributes within strings?
+
+         \sstitem
+          \htmlref{Edge(axis)}{Edge(axis)}: Which edges to label in a Plot
+
+         \sstitem
+          \htmlref{Font(element)}{Font(element)}: Character font for a Plot element
+
+         \sstitem
+          \htmlref{Gap(axis)}{Gap(axis)}: \htmlref{Interval}{Interval} between linearly spaced major axis values
+
+         \sstitem
+          \htmlref{Grf}{Grf}: Select the graphics interface to use.
+
+         \sstitem
+          \htmlref{Grid}{Grid}: Draw grid lines for a Plot?
+
+         \sstitem
+          \htmlref{Invisible}{Invisible}: Draw graphics in invisible ink?
+
+         \sstitem
+          \htmlref{LabelAt(axis)}{LabelAt(axis)}: Where to place numerical labels for a Plot
+
+         \sstitem
+          \htmlref{LabelUnits(axis)}{LabelUnits(axis)}: Use axis unit descriptions in a Plot?
+
+         \sstitem
+          \htmlref{LabelUp(axis)}{LabelUp(axis)}: Draw numerical Plot labels upright?
+
+         \sstitem
+          \htmlref{Labelling}{Labelling}: Label and tick placement option for a Plot
+
+         \sstitem
+          \htmlref{LogGap(axis)}{LogGap(axis)}: Interval between logarithmically spaced major axis values
+
+         \sstitem
+          \htmlref{LogPlot(axis)}{LogPlot(axis)}: Map the plot onto the screen logarithmically?
+
+         \sstitem
+          \htmlref{LogTicks(axis)}{LogTicks(axis)}: Space the major tick marks logarithmically?
+
+         \sstitem
+          \htmlref{MajTickLen(axis)}{MajTickLen(axis)}: Length of major tick marks for a Plot
+
+         \sstitem
+          \htmlref{MinTickLen(axis)}{MinTickLen(axis)}: Length of minor tick marks for a Plot
+
+         \sstitem
+          \htmlref{MinTick(axis)}{MinTick(axis)}: Density of minor tick marks for a Plot
+
+         \sstitem
+          \htmlref{NumLab(axis)}{NumLab(axis)}: Draw numerical axis labels for a Plot?
+
+         \sstitem
+          \htmlref{NumLabGap(axis)}{NumLabGap(axis)}: Spacing of numerical axis labels for a Plot
+
+         \sstitem
+          \htmlref{Size(element)}{Size(element)}: Character size for a Plot element
+
+         \sstitem
+          \htmlref{Style(element)}{Style(element)}: Line style for a Plot element
+
+         \sstitem
+          \htmlref{TextLab(axis)}{TextLab(axis)}: Draw descriptive axis labels for a Plot?
+
+         \sstitem
+          \htmlref{TextLabGap(axis)}{TextLabGap(axis)}: Spacing of descriptive axis labels for a Plot
+
+         \sstitem
+          \htmlref{TickAll}{TickAll}: Draw tick marks on all edges of a Plot?
+
+         \sstitem
+          \htmlref{TitleGap}{TitleGap}: Vertical spacing for a Plot title
+
+         \sstitem
+          \htmlref{Tol}{Tol}: Plotting tolerance
+
+         \sstitem
+          \htmlref{Width(element)}{Width(element)}: Line width for a Plot element
+      }
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      In addition to those functions applicable to all FrameSets, the
+      following functions may also be applied to all Plots:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{astBBuf}{astBBuf}: Begin a new graphical buffering context
+
+         \sstitem
+          \htmlref{astBorder}{astBorder}: Draw a border around valid regions of a Plot
+
+         \sstitem
+          \htmlref{astBoundingBox}{astBoundingBox}: Returns a bounding box for previously drawn graphics
+
+         \sstitem
+          \htmlref{astClip}{astClip}: Set up or remove clipping for a Plot
+
+         \sstitem
+          \htmlref{astCurve}{astCurve}: Draw a geodesic curve
+
+         \sstitem
+          \htmlref{astEBuf}{astEBuf}: End the current graphical buffering context
+
+         \sstitem
+          \htmlref{astGenCurve}{astGenCurve}: Draw a generalized curve
+
+         \sstitem
+          \htmlref{astGetGrfContext}{astGetGrfContext}: Get the graphics context for a Plot
+
+         \sstitem
+          \htmlref{astGrfPop}{astGrfPop}: Retrieve previously saved graphics functions
+
+         \sstitem
+          \htmlref{astGrfPush}{astGrfPush}: Save the current graphics functions
+
+         \sstitem
+          \htmlref{astGrfSet}{astGrfSet}: Register a graphics routine for use by a Plot
+
+         \sstitem
+          \htmlref{astGrid}{astGrid}: Draw a set of labelled coordinate axes
+
+         \sstitem
+          \htmlref{astGridLine}{astGridLine}: Draw a grid line (or axis) for a Plot
+
+         \sstitem
+          \htmlref{astMark}{astMark}: Draw a set of markers for a Plot
+
+         \sstitem
+          \htmlref{astPolyCurve}{astPolyCurve}: Draw a series of connected geodesic curves
+
+         \sstitem
+          \htmlref{astRegionOutline}{astRegionOutline}: Draw the outline of an AST \htmlref{Region}{Region}
+
+         \sstitem
+          \htmlref{astText}{astText}: Draw a text string for a Plot
+      }
+   }
+   \sstdiytopic{
+      Graphical Elements
+   }{
+      The colour index, character font, character size, line style and
+      line width used for plotting can be set independently for
+      various elements of the graphical output produced by a Plot.
+      The different graphical elements are identified by appending the
+      strings listed below as subscripts to the Plot attributes
+      Colour(element), Font(element), Size(element), Style(element)
+      and Width(element). These strings are case-insensitive and
+      unambiguous abbreviations may be used. Elements of the graphical
+      output which relate to individual axes can be referred to either
+      independently (e.g. \texttt{"} (Grid1)\texttt{"}  and \texttt{"} (Grid2)\texttt{"}  ) or together (e.g.
+      \texttt{"} (Grid)\texttt{"} ):
+
+      \sstitemlist{
+
+         \sstitem
+          Axes: \htmlref{Axis}{Axis} lines drawn through tick marks using astGrid
+
+         \sstitem
+          Axis1: Axis line drawn through tick marks on axis 1 using astGrid
+
+         \sstitem
+          Axis2: Axis line drawn through tick marks on axis 2 using astGrid
+
+         \sstitem
+          Border: The Plot border drawn using astBorder, astGrid or astRegionOutline
+
+         \sstitem
+          Curves: Geodesic curves drawn using astCurve, astGenCurve or astPolyCurve
+
+         \sstitem
+          Grid: Grid lines drawn using astGridLine or astGrid
+
+         \sstitem
+          Grid1: Grid lines which cross axis 1, drawn using astGridLine or astGrid
+
+         \sstitem
+          Grid2: Grid lines which cross axis 2, drawn using astGridLine or astGrid
+
+         \sstitem
+          Markers: Graphical markers (symbols) drawn using astMark
+
+         \sstitem
+          NumLab: Numerical axis labels drawn using astGrid
+
+         \sstitem
+          NumLab1: Numerical labels for axis 1 drawn using astGrid
+
+         \sstitem
+          NumLab2: Numerical labels for axis 2 drawn using astGrid
+
+         \sstitem
+          Strings: Text strings drawn using astText
+
+         \sstitem
+          TextLab: Descriptive axis labels drawn using astGrid
+
+         \sstitem
+          TextLab1: Descriptive label for axis 1 drawn using astGrid
+
+         \sstitem
+          TextLab2: Descriptive label for axis 2 drawn using astGrid
+
+         \sstitem
+          Ticks: Tick marks (both major and minor) drawn using astGrid
+
+         \sstitem
+          Ticks1: Tick marks (both major and minor) for axis 1 drawn using astGrid
+
+         \sstitem
+          Ticks2: Tick marks (both major and minor) for axis 2 drawn using astGrid
+
+         \sstitem
+          \htmlref{Title}{Title}: The Plot title drawn using astGrid
+      }
+   }
+}
+\sstroutine{
+   Plot3D
+}{
+   Provide facilities for 3D graphical output
+}{
+   \sstdescription{
+      A Plot3D is a specialised form of \htmlref{Plot}{Plot} that provides facilities
+      for producing 3D graphical output, including fully annotated 3D
+      coordinate grids. The base \htmlref{Frame}{Frame} in a Plot3D describes a 3-dimensional
+      \texttt{"} graphical\texttt{"}  coordinate system. The axes of this coordinate system are
+      assumed to be right-handed (that is, if X appears horizontally to the
+      right and Y vertically upwards, then Z is out of the screen towards
+      the viewer), and are assumed to be equally scaled (that is, the same
+      units are used to measure positions on each of the 3 axes). The upper
+      and lower bounds of a volume within this graphical coordinate system
+      is specified when the Plot3D is created, and all subsequent graphics
+      are \texttt{"} drawn\texttt{"}  in this volume.
+
+      The Plot3D class does not itself include any ability to draw on a
+      graphics device. Instead it calls upon function in an externally
+      supplied module (the \texttt{"} grf3d\texttt{"}  module) to do the required drawing.
+      A module should be written that implements the functions of the
+      grf3d interface using the facilities of a specific graphics system
+      This module should then be linked into the application so that the
+      Plot3D class can use its functions (see the description of the
+      \htmlref{ast\_link}{ast\_link} commands for details of how to do this). The grf3d interface
+      defines a few simple functions for drawing primitives such as straight
+      lines, markers and character strings. These functions all accept
+      positions in the 3D graphics coordinate system (the base Frame of the
+      Plot3D), and so the grf3d module must also manage the projection of
+      these 3D coordinates onto the 2D viewing surface, including the choice
+      of \texttt{"} eye\texttt{"} /\texttt{"} camera\texttt{"}  position, direction of viewing, etc. The AST
+      library includes a sample implementation of the grf3d interface
+      based on the PGPLOT graphics system (see file grf3d\_pgplot.c). This
+      implementation also serves to document the grf3d interface itself and
+      should be consulted for details before writing a new implementation.
+
+      The current Frame of a Plot3D describes a \texttt{"} physical\texttt{"}  3-dimensional
+      coordinate system, which is the coordinate system in which plotting
+      operations are specified when invoking the methods of the Plot3D
+      class. The results of each plotting operation are automatically
+      transformed into 3D graphical coordinates before being plotted
+      using the facilities of the grf3d module linked into the application.
+      Note, at least one of the three axes of the current Frame must be
+      independent of the other two current Frame axes.
+
+      You may select different physical coordinate systems in which to
+      plot (including the native graphical coordinate system itself)
+      by selecting different Frames as the current Frame of a Plot3D,
+      using its \htmlref{Current}{Current} attribute.
+
+      Like any \htmlref{FrameSet}{FrameSet}, a Plot3D may also be used as a Frame. In this
+      case, it behaves like its current Frame, which describes the
+      physical coordinate system.
+
+      When used as a \htmlref{Mapping}{Mapping}, a Plot3D describes the inter-relation
+      between 3D graphical coordinates (its base Frame) and 3D physical
+      coordinates (its current Frame).
+
+      Although the Plot3D class inherits from the Plot class, several of
+      the facilities of the Plot class are not available in the Plot3D
+      class, and an error will be reported if any attempt is made to use
+      them. Specifically, the Plot3D class does not support clipping
+      using the
+      \htmlref{astClip}{astClip} function.
+      Nor does it support the specification of graphics primitive functions
+      at run-time using the
+      \htmlref{astGrfSet}{astGrfSet}, \htmlref{astGrfPop}{astGrfPop}, \htmlref{astGrfPush}{astGrfPush} and \htmlref{astGetGrfContext}{astGetGrfContext} functions.
+   }
+   \sstconstructor{
+      \htmlref{astPlot3D}{astPlot3D}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The Plot3D class inherits from the Plot class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all Plots, every
+      Plot3D also has the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          Norm: Normal vector defining the 2D plane used for text and markers
+
+         \sstitem
+          \htmlref{RootCorner}{RootCorner}: Specifies which edges of the 3D box should be annotated.
+
+      }
+      Some attributes of the Plot class refer to specific physical
+      coordinate axes (e.g. Gap, LabelUp, DrawAxes, etc). For a basic
+      Plot, the axis index must be 1 or 2, but for a Plot3D the axis index
+      can be 1, 2 or 3.
+
+      Certain Plot attributes are ignored by the Plot3D class (e.g. Edge,
+      \htmlref{DrawTitle}{DrawTitle}, \htmlref{TitleGap}{TitleGap}, etc). Consult the Plot attribute documentation
+      for details. All other Plot attributes can be set for a specific
+      plane of the 3-d plot by appending one of the strings \texttt{"} \_XY\texttt{"} , \texttt{"} \_XZ\texttt{"}
+      or \texttt{"} \_YZ\texttt{"}  to the end of the Plot attribute name. For instance,
+      \texttt{"} \htmlref{Grid}{Grid}\_YZ\texttt{"}  refers to the \texttt{"} Grid\texttt{"}  attribute for the plane spanning
+      the second (Y) and third (Z) axes of the 3-d plot.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+       The Plot3D class does not define any new functions beyond those
+       which are applicable to all Plots. Note, however, that the
+       following methods inherited from the Plot class cannot be used with
+       a Plot3D and will report an error if called:
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{astBoundingBox}{astBoundingBox}, astClip, \htmlref{astCurve}{astCurve}, \htmlref{astGenCurve}{astGenCurve},
+         astGetGrfContext, astGrfPop, astGrfPush, astGrfSet, \htmlref{astGridLine}{astGridLine},
+         \htmlref{astPolyCurve}{astPolyCurve}.
+      }
+   }
+}
+\sstroutine{
+   PointList
+}{
+   A collection of points in a Frame
+}{
+   \sstdescription{
+      The PointList class implements a \htmlref{Region}{Region} which represents a collection
+      of points in a \htmlref{Frame}{Frame}.
+   }
+   \sstconstructor{
+      \htmlref{astPointList}{astPointList}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The PointList class inherits from the Region class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all Regions, every
+      PointList also has the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{ListSize}{ListSize}: The number of positions stored in the PointList
+      }
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The PointList class does not define any new functions beyond those
+      which are applicable to all Regions.
+   }
+}
+\sstroutine{
+   PolyMap
+}{
+   Map coordinates using polynomial functions
+}{
+   \sstdescription{
+      A PolyMap is a form of \htmlref{Mapping}{Mapping} which performs a general polynomial
+      transformation.  Each output coordinate is a polynomial function of
+      all the input coordinates. The coefficients are specified separately
+      for each output coordinate. The forward and inverse transformations
+      are defined independantly by separate sets of coefficients. If no
+      inverse transformation is supplied, the default behaviour is to use
+      an iterative method to evaluate the inverse based only on the forward
+      transformation (see attribute \htmlref{IterInverse}{IterInverse}).
+   }
+   \sstconstructor{
+      \htmlref{astPolyMap}{astPolyMap}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The PolyMap class inherits from the Mapping class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all Mappings, every
+      PolyMap also has the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{IterInverse}{IterInverse}: Provide an iterative inverse transformation?
+
+         \sstitem
+          \htmlref{NiterInverse}{NiterInverse}: Maximum number of iterations for iterative inverse
+
+         \sstitem
+          \htmlref{TolInverse}{TolInverse}: Target relative error for iterative inverse
+      }
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      In addition to those functions applicable to all Objects, the
+      following functions may also be applied to all Mappings:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{astPolyCoeffs}{astPolyCoeffs}: Retrieve the coefficients of a PolyMap transformation
+
+         \sstitem
+          \htmlref{astPolyTran}{astPolyTran}: Fit a PolyMap inverse or forward transformation
+      }
+   }
+}
+\sstroutine{
+   Polygon
+}{
+   A polygonal region within a 2-dimensional Frame
+}{
+   \sstdescription{
+      The Polygon class implements a polygonal area, defined by a
+      collection of vertices, within a 2-dimensional \htmlref{Frame}{Frame}. The vertices
+      are connected together by geodesic curves within the encapsulated Frame.
+      For instance, if the encapsulated Frame is a simple Frame then the
+      geodesics will be straight lines, but if the Frame is a \htmlref{SkyFrame}{SkyFrame} then
+      the geodesics will be great circles. Note, the vertices must be
+      supplied in an order such that the inside of the polygon is to the
+      left of the boundary as the vertices are traversed. Supplying them
+      in the reverse order will effectively negate the polygon.
+
+      Within a SkyFrame, neighbouring vertices are always joined using the
+      shortest path. Thus if an edge of 180 degrees or more in length is
+      required, it should be split into section each of which is less
+      than 180 degrees. The closed path joining all the vertices in order
+      will divide the celestial sphere into two disjoint regions. The
+      inside of the polygon is the region which is circled in an
+      anti-clockwise manner (when viewed from the inside of the celestial
+      sphere) when moving through the list of vertices in the order in
+      which they were supplied when the Polygon was created (i.e. the
+      inside is to the left of the boundary when moving through the
+      vertices in the order supplied).
+   }
+   \sstconstructor{
+      \htmlref{astPolygon}{astPolygon}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The Polygon class inherits from the \htmlref{Region}{Region} class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all Regions, every
+      Polygon also has the following attributes:
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{SimpVertices}{SimpVertices}: Simplify by transforming the vertices?
+      }
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      In addition to those functions applicable to all Regions, the
+      following functions may also be applied to all Polygons:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{astDownsize}{astDownsize}: Reduce the number of vertices in a Polygon.
+
+         \sstitem
+          \htmlref{astConvex$<$X$>$}{astConvex$<$X$>$}: Create a Polygon giving the convex hull of a pixel array
+
+         \sstitem
+          \htmlref{astOutline$<$X$>$}{astOutline$<$X$>$}: Create a Polygon outlining values in a pixel array
+      }
+   }
+}
+\sstroutine{
+   Prism
+}{
+   An extrusion of a region into higher dimensions
+}{
+   \sstdescription{
+      A Prism is a \htmlref{Region}{Region} which represents an extrusion of an existing Region
+      into one or more orthogonal dimensions (specified by another Region).
+      If the Region to be extruded has N axes, and the Region defining the
+      extrusion has M axes, then the resulting Prism will have (M$+$N) axes.
+      A point is inside the Prism if the first N axis values correspond to
+      a point inside the Region being extruded, and the remaining M axis
+      values correspond to a point inside the Region defining the extrusion.
+
+      As an example, a cylinder can be represented by extruding an existing
+      \htmlref{Circle}{Circle}, using an \htmlref{Interval}{Interval} to define the extrusion. Ih this case, the
+      Interval would have a single axis and would specify the upper and
+      lower limits of the cylinder along its length.
+   }
+   \sstconstructor{
+      \htmlref{astPrism}{astPrism}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The Prism class inherits from the Region class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The Prism class does not define any new attributes beyond those
+      which are applicable to all Regions.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The Prism class does not define any new functions beyond those
+      which are applicable to all Regions.
+   }
+}
+\sstroutine{
+   RateMap
+}{
+   Mapping which represents differentiation
+}{
+   \sstdescription{
+      A RateMap is a \htmlref{Mapping}{Mapping} which represents a single element of the
+      Jacobian matrix of another Mapping. The Mapping for which the
+      Jacobian is required is specified when the new RateMap is created,
+      and is referred to as the \texttt{"} encapsulated Mapping\texttt{"}  below.
+
+      The number of inputs to a RateMap is the same as the number of inputs
+      to its encapsulated Mapping. The number of outputs from a RateMap
+      is always one. This one output equals the rate of change of a
+      specified output of the encapsulated Mapping with respect to a
+      specified input of the encapsulated Mapping (the input and output
+      to use are specified when the RateMap is created).
+
+      A RateMap which has not been inverted does not define an inverse
+      transformation. If a RateMap has been inverted then it will define
+      an inverse transformation but not a forward transformation.
+   }
+   \sstconstructor{
+      \htmlref{astRateMap}{astRateMap}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The RateMap class inherits from the Mapping class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The RateMap class does not define any new attributes beyond those
+      which are applicable to all Mappings.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The RateMap class does not define any new functions beyond those
+      which are applicable to all Mappings.
+   }
+}
+\sstroutine{
+   Region
+}{
+   Represents a region within a coordinate system
+}{
+   \sstdescription{
+      This class provides the basic facilities for describing a region within
+      a specified coordinate system. However, the Region class does not
+      have a constructor function of its own, as it is simply a container
+      class for a family of specialised sub-classes such as \htmlref{Circle}{Circle}, \htmlref{Box}{Box}, etc,
+      which implement Regions with particular shapes.
+
+      All sub-classes of Region require a \htmlref{Frame}{Frame} to be supplied when the Region
+      is created. This Frame describes the coordinate system in which the
+      Region is defined, and is referred to as the \texttt{"} encapsulated Frame\texttt{"}  below.
+      Constructors will also typically required one or more positions to be
+      supplied which define the location and extent of the region. These
+      positions must be supplied within the encapsulated Frame.
+
+      The Region class inherits from the Frame class, and so a Region can be
+      supplied where-ever a Frame is expected. In these cases, supplying a
+      Region is equivalent to supplying a reference to its encapsulated Frame.
+      Thus all the methods of the Frame class can be used on the Region class.
+      For instance, the
+      \htmlref{astFormat}{astFormat} function
+      may be used on a Region to format an axis value.
+
+      In addition, since Frame inherits from \htmlref{Mapping}{Mapping}, a Region is also a sort
+      of Mapping. Transforming positions by supplying a Region to one of the
+      astTran$<$X$>$ functions
+      is the way to determine if a given position is inside or outside the
+      Region. When used as a Mapping, most classes of Frame are equivalent to
+      a \htmlref{UnitMap}{UnitMap}. However, the Region class modifies this behaviour so that a
+      Region acts like a UnitMap only for input positions which are within the
+      area represented by the Region. Input positions which are outside the
+      area produce bad output values (i.e. the output values are equal to
+      AST\_\_BAD). This behaviour is the same for both the forward and the
+      inverse transformation. In this sense the \texttt{"} inverse transformation\texttt{"}
+      is not a true inverse of the forward transformation, since applying
+      the forward transformation to a point outside the Region, and then
+      applying the inverse transformation results, in a set of AST\_\_BAD axis
+      values rather than the original axis values. If required, the
+      \htmlref{astRemoveRegions}{astRemoveRegions}
+      function can be used to remove the \texttt{"} masking\texttt{"}  effect of any Regions
+      contained within a compound Mapping or \htmlref{FrameSet}{FrameSet}. It does this by
+      replacing each Region with a UnitMap or equivalent Frame (depending
+      on the context in which the Region is used).
+
+      If the coordinate system represented by the Region is changed (by
+      changing the values of one or more of the attribute which the Region
+      inherits from its encapsulated Frame), the area represented by
+      the Region is mapped into the new coordinate system. For instance, let\texttt{'} s
+      say a Circle (a subclass of Region) is created, a \htmlref{SkyFrame}{SkyFrame} being
+      supplied to the constructor so that the Circle describes a circular
+      area on the sky in FK4 equatorial coordinates. Since Region inherits
+      from Frame, the Circle will have a \htmlref{System}{System} attribute and this attribute
+      will be set to \texttt{"} FK4\texttt{"} . If the System attribute of the Region is then
+      changed from FK4 to FK5, the circular area represented by the Region
+      will automatically be mapped from the FK4 system into the FK5 system.
+      In general, changing the coordinate system in this way may result in the
+      region changing shape - for instance, a circle may change into an
+      ellipse if the transformation from the old to the new coordinate system
+      is linear but with different scales on each axis. Thus the specific
+      class of a Region cannot be used as a guarantee of the shape in any
+      particular coordinate system. If the
+      \htmlref{astSimplify}{astSimplify} function
+      is used on a Region, it will endeavour to return a new Region of
+      a sub-class which accurately describes the shape in the current
+      coordinate system of the Region (but this may not always be possible).
+
+      It is possible to negate an existing Region so that it represents all
+      areas of the encapsulated Frame except for the area specified when
+      the Region was created.
+   }
+   \sstconstructor{
+      None.
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The Region class inherits from the Frame class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all Frames, every
+      Region also has the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{Adaptive}{Adaptive}: Should the area adapt to changes in the coordinate system?
+
+         \sstitem
+          \htmlref{Negated}{Negated}: Has the original region been negated?
+
+         \sstitem
+          \htmlref{Closed}{Closed}: Should the boundary be considered to be inside the region?
+
+         \sstitem
+          \htmlref{MeshSize}{MeshSize}: Number of points used to create a mesh covering the Region
+
+         \sstitem
+          \htmlref{FillFactor}{FillFactor}: Fraction of the Region which is of interest
+
+         \sstitem
+          \htmlref{Bounded}{Bounded}: Is the Region bounded?
+
+      }
+      Every Region also inherits any further attributes that belong
+      to the encapsulated Frame, regardless of that Frame\texttt{'} s class. (For
+      example, the \htmlref{Equinox}{Equinox} attribute, defined by the SkyFrame class, is
+      inherited by any Region which represents a SkyFrame.)
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      In addition to those functions applicable to all Frames, the
+      following functions may also be applied to all Regions:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{astGetRegionBounds}{astGetRegionBounds}: Get the bounds of a Region
+
+         \sstitem
+          \htmlref{astGetRegionFrame}{astGetRegionFrame}: Get a copy of the Frame represent by a Region
+
+         \sstitem
+          \htmlref{astGetRegionFrameSet}{astGetRegionFrameSet}: Get a copy of the Frameset encapsulated by a Region
+
+         \sstitem
+          \htmlref{astGetRegionMesh}{astGetRegionMesh}: Get a mesh of points covering a Region
+
+         \sstitem
+          \htmlref{astGetRegionPoints}{astGetRegionPoints}: Get the positions that define a Region
+
+         \sstitem
+          \htmlref{astGetUnc}{astGetUnc}: Obtain uncertainty information from a Region
+
+         \sstitem
+          \htmlref{astMapRegion}{astMapRegion}: Transform a Region into a new coordinate system
+
+         \sstitem
+          \htmlref{astNegate}{astNegate}: Toggle the value of the Negated attribute
+
+         \sstitem
+          \htmlref{astOverlap}{astOverlap}: Determines the nature of the overlap between two Regions
+
+         \sstitem
+          \htmlref{astMask$<$X$>$}{astMask$<$X$>$}: Mask a region of a data grid
+
+         \sstitem
+          \htmlref{astSetUnc}{astSetUnc}: Associate a new uncertainty with a Region
+
+         \sstitem
+          \htmlref{astShowMesh}{astShowMesh}: Display a mesh of points on the surface of a Region
+      }
+   }
+}
+\sstroutine{
+   SelectorMap
+}{
+   A Mapping that locates positions within one of a set of alternate
+   Regions
+}{
+   \sstdescription{
+      A SelectorMap is a \htmlref{Mapping}{Mapping} that identifies which \htmlref{Region}{Region} contains
+      a given input position.
+
+      A SelectorMap encapsulates a number of Regions that all have the same
+      number of axes and represent the same coordinate \htmlref{Frame}{Frame}. The number of
+      inputs (\htmlref{Nin}{Nin} attribute) of the SelectorMap equals the number of axes
+      spanned by one of the encapsulated Region. All SelectorMaps have only
+      a single output. SelectorMaps do not define an inverse transformation.
+
+      For each input position, the forward transformation of a SelectorMap
+      searches through the encapsulated Regions (in the order supplied when
+      the SelectorMap was created) until a Region is found which contains
+      the input position. The index associated with this Region is
+      returned as the SelectorMap output value (the index value is the
+      position of the Region within the list of Regions supplied when the
+      SelectorMap was created, starting at 1 for the first Region). If an
+      input position is not contained within any Region, a value of zero is
+      returned by the forward transformation.
+
+      If a compound Mapping contains a SelectorMap in series with its own
+      inverse, the combination of the two adjacent SelectorMaps will be
+      replaced by a \htmlref{UnitMap}{UnitMap} when the compound Mapping is simplified using
+      \htmlref{astSimplify}{astSimplify}.
+
+      In practice, SelectorMaps are often used in conjunction with SwitchMaps.
+   }
+   \sstconstructor{
+      \htmlref{astSelectorMap}{astSelectorMap}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The SelectorMap class inherits from the Mapping class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The SelectorMap class does not define any new attributes beyond those
+      which are applicable to all Mappings.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The SelectorMap class does not define any new functions beyond those
+      which are applicable to all Mappings.
+   }
+}
+\sstroutine{
+   ShiftMap
+}{
+   Add a constant value to each coordinate
+}{
+   \sstdescription{
+      A ShiftMap is a linear \htmlref{Mapping}{Mapping} which shifts each axis by a
+      specified constant value.
+   }
+   \sstconstructor{
+      \htmlref{astShiftMap}{astShiftMap}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The ShiftMap class inherits from the Mapping class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The ShiftMap class does not define any new attributes beyond those
+      which are applicable to all Mappings.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The ShiftMap class does not define any new functions beyond those
+      which are applicable to all Mappings.
+   }
+}
+\sstroutine{
+   SkyAxis
+}{
+   Store celestial axis information
+}{
+   \sstdescription{
+      The SkyAxis class is used to store information associated with a
+      particular axis of a \htmlref{SkyFrame}{SkyFrame}. It is used internally by the AST
+      library and has no constructor function. You should encounter it
+      only within textual output (e.g. from \htmlref{astWrite}{astWrite}).
+   }
+   \sstconstructor{
+      None.
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The SkyAxis class inherits from the \htmlref{Axis}{Axis} class.
+   }
+}
+\sstroutine{
+   SkyFrame
+}{
+   Celestial coordinate system description
+}{
+   \sstdescription{
+      A SkyFrame is a specialised form of \htmlref{Frame}{Frame} which describes
+      celestial longitude/latitude coordinate systems. The particular
+      celestial coordinate system to be represented is specified by
+      setting the SkyFrame\texttt{'} s \htmlref{System}{System} attribute (currently, the default
+      is ICRS) qualified, as necessary, by a mean \htmlref{Equinox}{Equinox} value and/or
+      an \htmlref{Epoch}{Epoch}.
+
+      For each of the supported celestial coordinate systems, a SkyFrame
+      can apply an optional shift of origin to create a coordinate system
+      representing offsets within the celestial coordinate system from some
+      specified reference point. This offset coordinate system can also be
+      rotated to define new longitude and latitude axes. See attributes
+      SkyRef, \htmlref{SkyRefIs}{SkyRefIs}, SkyRefP and \htmlref{AlignOffset}{AlignOffset}.
+
+      All the coordinate values used by a SkyFrame are in
+      radians. These may be formatted in more conventional ways for
+      display by using \htmlref{astFormat}{astFormat}.
+      For a SkyFrame, the Unit attribute describes the formatted value of
+      a SkyFrame axis, and may for instance be \texttt{"} h:m:s\texttt{"} , indicating that a
+      formatted axis value contains colon-separated fields for hours, minutes
+      and seconds. On the other hand, the InternalUnit attribute for a
+      SkyFrame is always set to \texttt{"} rad\texttt{"}  (i.e. radians), indicating that the
+      unformatted (i.e. floating point) axis values used by application code
+      are always in units of radians
+   }
+   \sstconstructor{
+      \htmlref{astSkyFrame}{astSkyFrame}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The SkyFrame class inherits from the Frame class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all Frames, every
+      SkyFrame also has the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{AlignOffset}{AlignOffset}: Align SkyFrames using the offset coordinate system?
+
+         \sstitem
+          \htmlref{AsTime(axis)}{AsTime(axis)}: Format celestial coordinates as times?
+
+         \sstitem
+          \htmlref{Equinox}{Equinox}: Epoch of the mean equinox
+
+         \sstitem
+          IsLatAxis: Is the specified axis the latitude axis?
+
+         \sstitem
+          IsLonAxis: Is the specified axis the longitude axis?
+
+         \sstitem
+          \htmlref{LatAxis}{LatAxis}: Index of the latitude axis
+
+         \sstitem
+          \htmlref{LonAxis}{LonAxis}: Index of the longitude axis
+
+         \sstitem
+          \htmlref{NegLon}{NegLon}: Display longitude values in the range [-pi,pi]?
+
+         \sstitem
+          \htmlref{Projection}{Projection}: Sky projection description.
+
+         \sstitem
+          SkyRef: Position defining location of the offset coordinate system
+
+         \sstitem
+          \htmlref{SkyRefIs}{SkyRefIs}: Selects the nature of the offset coordinate system
+
+         \sstitem
+          SkyRefP: Position defining orientation of the offset coordinate system
+
+         \sstitem
+          \htmlref{SkyTol}{SkyTol}: Smallest significant shift in sky coordinates
+      }
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      In addition to those
+      functions
+      applicable to all Frames, the following
+      functions
+      may also be applied to all SkyFrames:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{astSkyOffsetMap}{astSkyOffsetMap}: Obtain a \htmlref{Mapping}{Mapping} from absolute to offset coordinates
+      }
+   }
+}
+\sstroutine{
+   SlaMap
+}{
+   Sequence of celestial coordinate conversions
+}{
+   \sstdescription{
+      An SlaMap is a specialised form of \htmlref{Mapping}{Mapping} which can be used to
+      represent a sequence of conversions between standard celestial
+      (longitude, latitude) coordinate systems.
+
+      When an SlaMap is first created, it simply performs a unit
+      (null) Mapping on a pair of coordinates. Using the \htmlref{astSlaAdd}{astSlaAdd}
+      function, a series of coordinate conversion steps may then be
+      added, selected from those provided by the SLALIB Positional
+      Astronomy Library (Starlink User Note SUN/67). This allows
+      multi-step conversions between a variety of celestial coordinate
+      systems to be assembled out of the building blocks provided by
+      SLALIB.
+
+      For details of the individual coordinate conversions available,
+      see the description of the astSlaAdd function.
+   }
+   \sstconstructor{
+      \htmlref{astSlaMap}{astSlaMap} (also see astSlaAdd)
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The SlaMap class inherits from the Mapping class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The SlaMap class does not define any new attributes beyond those
+      which are applicable to all Mappings.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      In addition to those functions applicable to all Mappings, the
+      following function may also be applied to all SlaMaps:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{astSlaAdd}{astSlaAdd}: Add a celestial coordinate conversion to an SlaMap
+      }
+   }
+}
+\sstroutine{
+   SpecFluxFrame
+}{
+   Compound spectrum/flux Frame
+}{
+   \sstdescription{
+      A SpecFluxFrame combines a \htmlref{SpecFrame}{SpecFrame} and a \htmlref{FluxFrame}{FluxFrame} into a single
+      2-dimensional compound \htmlref{Frame}{Frame}. Such a Frame can for instance be used
+      to describe a \htmlref{Plot}{Plot} of a spectrum in which the first axis represents
+      spectral position and the second axis represents flux.
+   }
+   \sstconstructor{
+      \htmlref{astSpecFluxFrame}{astSpecFluxFrame}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The SpecFluxFrame class inherits from the \htmlref{CmpFrame}{CmpFrame} class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The SpecFluxFrame class does not define any new attributes beyond
+      those which are applicable to all CmpFrames. However, the attributes
+      of the component Frames can be accessed as if they were attributes
+      of the SpecFluxFrame. For instance, the SpecFluxFrame will recognise
+      the \texttt{"} \htmlref{StdOfRest}{StdOfRest}\texttt{"}  attribute and forward access requests to the component
+      SpecFrame. An axis index can optionally be appended to the end of any
+      attribute name, in which case the request to access the attribute will
+      be forwarded to the primary Frame defining the specified axis.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The SpecFluxFrame class does not define any new functions beyond those
+      which are applicable to all CmpFrames.
+   }
+}
+\sstroutine{
+   SpecFrame
+}{
+   Spectral coordinate system description
+}{
+   \sstdescription{
+      A SpecFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which
+      represents various coordinate systems used to describe positions within
+      an electro-magnetic spectrum. The particular coordinate system to be
+      used is specified by setting the SpecFrame\texttt{'} s \htmlref{System}{System} attribute (the
+      default is wavelength) qualified, as necessary, by other attributes
+      such as the rest frequency, the standard of rest, the epoch of
+      observation, units, etc (see the description of the System attribute
+      for details).
+
+      By setting a value for thr \htmlref{SpecOrigin}{SpecOrigin} attribute, a SpecFrame can be made
+      to represent offsets from a given spectral position, rather than absolute
+      spectral values.
+   }
+   \sstconstructor{
+      \htmlref{astSpecFrame}{astSpecFrame}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The SpecFrame class inherits from the Frame class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all Frames, every
+      SpecFrame also has the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{AlignSpecOffset}{AlignSpecOffset}: Align SpecFrames using the offset coordinate system?
+
+         \sstitem
+          \htmlref{AlignStdOfRest}{AlignStdOfRest}: Standard of rest in which to align SpecFrames
+
+         \sstitem
+          \htmlref{RefDec}{RefDec}: Declination of the source (FK5 J2000)
+
+         \sstitem
+          \htmlref{RefRA}{RefRA}: Right ascension of the source (FK5 J2000)
+
+         \sstitem
+          \htmlref{RestFreq}{RestFreq}: Rest frequency
+
+         \sstitem
+          \htmlref{SourceSys}{SourceSys}: Source velocity spectral system
+
+         \sstitem
+          \htmlref{SourceVel}{SourceVel}: Source velocity
+
+         \sstitem
+          \htmlref{SourceVRF}{SourceVRF}: Source velocity rest frame
+
+         \sstitem
+          \htmlref{SpecOrigin}{SpecOrigin}: The zero point for SpecFrame axis values
+
+         \sstitem
+          \htmlref{StdOfRest}{StdOfRest}: Standard of rest
+
+      }
+      Several of the Frame attributes inherited by the SpecFrame class
+      refer to a specific axis of the Frame (for instance \htmlref{Unit(axis)}{Unit(axis)},
+      \htmlref{Label(axis)}{Label(axis)}, etc). Since a SpecFrame is strictly one-dimensional,
+      it allows these attributes to be specified without an axis index.
+      So for instance, \texttt{"} Unit\texttt{"}  is allowed in place of \texttt{"} Unit(1)\texttt{"} .
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      In addition to those functions applicable to all Frames, the
+      following functions may also be applied to all SpecFrames:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{astSetRefPos}{astSetRefPos}: Set reference position in any celestial system
+
+         \sstitem
+          \htmlref{astGetRefPos}{astGetRefPos}: Get reference position in any celestial system
+      }
+   }
+}
+\sstroutine{
+   SpecMap
+}{
+   Sequence of spectral coordinate conversions
+}{
+   \sstdescription{
+      A SpecMap is a specialised form of \htmlref{Mapping}{Mapping} which can be used to
+      represent a sequence of conversions between standard spectral
+      coordinate systems.
+
+      When an SpecMap is first created, it simply performs a unit
+      (null) Mapping. Using the \htmlref{astSpecAdd}{astSpecAdd}
+      function, a series of coordinate conversion steps may then be
+      added. This allows multi-step conversions between a variety of
+      spectral coordinate systems to be assembled out of a set of building
+      blocks.
+
+      Conversions are available to transform between standards of rest.
+      Such conversions need to know the source position as an RA and DEC.
+      This information can be supplied in the form of parameters for
+      the relevant conversions, in which case the SpecMap is 1-dimensional,
+      simply transforming the spectral axis values. This means that the
+      same source position will always be used by the SpecMap. However, this
+      may not be appropriate for an accurate description of a 3-D spectral
+      cube, where changes of spatial position can produce significant
+      changes in the Doppler shift introduced when transforming between
+      standards of rest. For this situation, a 3-dimensional SpecMap can
+      be created in which axes 2 and 3 correspond to the source RA and DEC
+      The SpecMap simply copies values for axes 2 and 3 from input to
+      output), but modifies axis 1 values (the spectral axis) appropriately.
+
+      For details of the individual coordinate conversions available,
+      see the description of the astSpecAdd function.
+   }
+   \sstconstructor{
+      \htmlref{astSpecMap}{astSpecMap} (also see astSpecAdd)
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The SpecMap class inherits from the Mapping class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The SpecMap class does not define any new attributes beyond those
+      which are applicable to all Mappings.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      In addition to those functions applicable to all Mappings, the
+      following function may also be applied to all SpecMaps:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{astSpecAdd}{astSpecAdd}: Add a spectral coordinate conversion to an SpecMap
+      }
+   }
+}
+\sstroutine{
+   SphMap
+}{
+   Map 3-d Cartesian to 2-d spherical coordinates
+}{
+   \sstdescription{
+      A SphMap is a \htmlref{Mapping}{Mapping} which transforms points from a
+      3-dimensional Cartesian coordinate system into a 2-dimensional
+      spherical coordinate system (longitude and latitude on a unit
+      sphere centred at the origin). It works by regarding the input
+      coordinates as position vectors and finding their intersection
+      with the sphere surface. The inverse transformation always
+      produces points which are a unit distance from the origin
+      (i.e. unit vectors).
+   }
+   \sstconstructor{
+      \htmlref{astSphMap}{astSphMap}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The SphMap class inherits from the Mapping class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all Mappings, every
+      SphMap also has the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{UnitRadius}{UnitRadius}: SphMap input vectors lie on a unit sphere?
+
+         \sstitem
+          \htmlref{PolarLong}{PolarLong}: The longitude value to assign to either pole
+      }
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The SphMap class does not define any new functions beyond those
+      which are applicable to all Mappings.
+   }
+}
+\sstroutine{
+   Stc
+}{
+   Represents an instance of the IVOA STC class
+}{
+   \sstdescription{
+      The Stc class is an implementation of the IVOA STC class which forms
+      part of the IVOA Space-Time Coordinate Metadata system. See:
+
+      http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html
+
+      The Stc class does not have a constructor function of its own, as it
+      is simply a container class for a family of specialised sub-classes
+      including \htmlref{StcCatalogEntryLocation}{StcCatalogEntryLocation}, \htmlref{StcResourceProfile}{StcResourceProfile}, \htmlref{StcSearchLocation}{StcSearchLocation}
+      and \htmlref{StcObsDataLocation}{StcObsDataLocation}.
+   }
+   \sstconstructor{
+      astStc
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The Stc class inherits from the \htmlref{Region}{Region} class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all Regions, every
+      Stc also has the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{RegionClass}{RegionClass}: The class name of the encapsulated Region.
+      }
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      In addition to those functions applicable to all Regions, the
+      following functions may also be applied to all Stc\texttt{'} s:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{astGetStcRegion}{astGetStcRegion}: Get a pointer to the encapsulated Region
+
+         \sstitem
+          \htmlref{astGetStcCoord}{astGetStcCoord}: Get information about an AstroCoords element
+
+         \sstitem
+          \htmlref{astGetStcNCoord}{astGetStcNCoord}: Returns the number of AstroCoords elements in an Stc
+      }
+   }
+}
+\sstroutine{
+   StcCatalogEntryLocation
+}{
+   Correspond to the IVOA STCCatalogEntryLocation class
+}{
+   \sstdescription{
+      The StcCatalogEntryLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe
+      the coverage of the datasets contained in some VO resource.
+
+      See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html
+   }
+   \sstconstructor{
+      \htmlref{astStcCatalogEntryLocation}{astStcCatalogEntryLocation}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The StcCatalogEntryLocation class inherits from the Stc class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The StcCatalogEntryLocation class does not define any new attributes beyond
+      those which are applicable to all Stcs.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The StcCatalogEntryLocation class does not define any new functions beyond those
+      which are applicable to all Stcs.
+   }
+}
+\sstroutine{
+   StcObsDataLocation
+}{
+   Correspond to the IVOA ObsDataLocation class
+}{
+   \sstdescription{
+      The StcObsDataLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe
+      the coordinate space occupied by a particular observational dataset.
+
+      See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html
+
+      An STC ObsDataLocation element specifies the extent of the
+      observation within a specified coordinate system, and also specifies
+      the observatory location within a second coordinate system.
+
+      The AST StcObsDataLocation class inherits from Stc, and therefore
+      an StcObsDataLocation can be used directly as an Stc. When used
+      in this way, the StcObsDataLocation describes the location of the
+      observation (not the observatory).
+
+      Eventually, this class will have a method for returning an Stc
+      describing the observatory location. However, AST currently does not
+      include any classes of \htmlref{Frame}{Frame} for describing terrestrial or solar
+      system positions. Therefore, the provision for returning observatory
+      location as an Stc is not yet available. However, for terrestrial
+      observations, the position of the observatory can still be recorded
+      using the \htmlref{ObsLon}{ObsLon} and \htmlref{ObsLat}{ObsLat} attributes of the Frame encapsulated
+      within the Stc representing the observation location (this assumes
+      the observatory is located at sea level).
+   }
+   \sstconstructor{
+      \htmlref{astStcObsDataLocation}{astStcObsDataLocation}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The StcObsDataLocation class inherits from the Stc class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The StcObsDataLocation class does not define any new attributes beyond
+      those which are applicable to all Stcs.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The StcObsDataLocation class does not define any new functions beyond those
+      which are applicable to all Stcs.
+   }
+}
+\sstroutine{
+   StcResourceProfile
+}{
+   Correspond to the IVOA STCResourceProfile class
+}{
+   \sstdescription{
+      The StcResourceProfile class is a sub-class of \htmlref{Stc}{Stc} used to describe
+      the coverage of the datasets contained in some VO resource.
+
+      See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html
+   }
+   \sstconstructor{
+      \htmlref{astStcResourceProfile}{astStcResourceProfile}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The StcResourceProfile class inherits from the Stc class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The StcResourceProfile class does not define any new attributes beyond
+      those which are applicable to all Stcs.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The StcResourceProfile class does not define any new functions beyond those
+      which are applicable to all Stcs.
+   }
+}
+\sstroutine{
+   StcSearchLocation
+}{
+   Correspond to the IVOA SearchLocation class
+}{
+   \sstdescription{
+      The StcSearchLocation class is a sub-class of \htmlref{Stc}{Stc} used to describe
+      the coverage of a query.
+
+      See http://hea-www.harvard.edu/$\sim$arots/nvometa/STC.html
+   }
+   \sstconstructor{
+      \htmlref{astStcSearchLocation}{astStcSearchLocation}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The StcSearchLocation class inherits from the Stc class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The StcSearchLocation class does not define any new attributes beyond
+      those which are applicable to all Stcs.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The StcSearchLocation class does not define any new functions beyond those
+      which are applicable to all Stcs.
+   }
+}
+\sstroutine{
+   StcsChan
+}{
+   I/O Channel using STC-S to represent Objects
+}{
+   \sstdescription{
+      A StcsChan is a specialised form of \htmlref{Channel}{Channel} which supports STC-S
+      I/O operations. Writing an \htmlref{Object}{Object} to an StcsChan (using
+      \htmlref{astWrite}{astWrite}) will, if the Object is suitable, generate an
+      STC-S description of that Object, and reading from an StcsChan will
+      create a new Object from its STC-S description.
+
+      When an STC-S description is read using
+      \htmlref{astRead}{astRead},
+      the returned AST Object may be 1) a \htmlref{PointList}{PointList} describing the STC
+      AstroCoords (i.e. a single point of interest within the coordinate frame
+      described by the STC-S description), or 2) a \htmlref{Region}{Region} describing the STC
+      AstrCoordsArea (i.e. an area or volume of interest within the coordinate
+      frame described by the STC-S description), or 3) a \htmlref{KeyMap}{KeyMap}
+      containing the uninterpreted property values read form the STC-S
+      description, or 4) a KeyMap containing any combination of the first
+      3 options. The attributes \htmlref{StcsArea}{StcsArea}, \htmlref{StcsCoords}{StcsCoords} and \htmlref{StcsProps}{StcsProps}
+      control which of the above is returned by
+      astRead.
+
+      When an STC-S description is created from an AST Object using
+      astWrite,
+      the AST Object must be either a Region or a KeyMap. If it is a
+      Region, it is assumed to define the AstroCoordsArea or (if the
+      Region is a single point) the AstroCoords to write to the STC-S
+      description. If the Object is a KeyMap, it may contain an entry
+      with the key \texttt{"} AREA\texttt{"} , holding a Region to be used to define the
+      AstroCoordsArea. It may also contain an entry with the key \texttt{"} COORDS\texttt{"} ,
+      holding a Region (a PointList) to be used to create the
+      AstroCoords. It may also contain an entry with key \texttt{"} PROPS\texttt{"} , holding
+      a KeyMap that contains uninterpreted property values to be used as
+      defaults for any STC-S properties that are not determined by the
+      other supplied Regions. In addition, a KeyMap supplied to
+      astWrite
+      may itself hold the default STC-S properties (rather than defaults
+      being held in a secondary KeyMap, stored as the \texttt{"} PROPS\texttt{"}  entry in the
+      supplied KeyMap).
+
+      The
+      astRead and astWrite
+      functions work together so that any Object returned by
+      astRead can immediately be re-written using astWrite.
+
+      Normally, when you use an StcsChan, you should provide \texttt{"} source\texttt{"}
+      and \texttt{"} sink\texttt{"}  functions which connect it to an external data store
+      by reading and writing the resulting text. These functions
+      should perform any conversions needed between external character
+      encodings and the internal ASCII encoding. If no such functions
+      are supplied, a Channel will read from standard input and write
+      to standard output.
+
+      Alternatively, an \htmlref{XmlChan}{XmlChan} can be told to read or write from
+      specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes,
+      in which case no sink or source function need be supplied.
+
+      Support for STC-S is currently based on the IVOA document \texttt{"} STC-S:
+      Space-Time Coordinate (STC) Metadata Linear String Implementation\texttt{"} ,
+      version 1.30 (dated 5th December 2007), available at
+      http://www.ivoa.net/Documents/latest/STC-S.html. Note, this
+      document is a recommednation only and does not constitute an accepted
+      IVOA standard.
+
+      The full text of version 1.30 is supported by the StcsChan class,
+      with the following exceptions and provisos:
+
+      \sstitemlist{
+
+         \sstitem
+          When reading an STC-S phrase, case is ignored except when reading
+         units strings.
+
+         \sstitem
+          There is no support for multiple intervals specified within a
+         TimeInterval, PositionInterval, SpectralInterval or RedshiftInterval.
+
+         \sstitem
+          If the ET timescale is specified, TT is used instead.
+
+         \sstitem
+          If the TEB timescale is specified, TDB is used instead.
+
+         \sstitem
+          The LOCAL timescale is not supported.
+
+         \sstitem
+          The AST \htmlref{TimeFrame}{TimeFrame} and \htmlref{SkyFrame}{SkyFrame} classes do not currently allow a
+         reference position to be specified. Consequently, any $<$refpos$>$
+         specified within the Time or Space sub-phrase of an STC-S document
+         is ignored.
+
+         \sstitem
+          The Convex identifier for the space sub-phrase is not supported.
+
+         \sstitem
+          The GEO\_C and GEO\_D space frames are not supported.
+
+         \sstitem
+          The UNITSPHERE and SPHER3 space flavours are not supported.
+
+         \sstitem
+          If any Error values are supplied in a space sub-phrase, then the
+         number of values supplied should equal the number of spatial axes,
+         and the values are assumed to specify an error box (i.e. error
+         circles, ellipses, etc, are not supported).
+
+         \sstitem
+          The spectral and redshift sub-phrases do not support the
+         following $<$refpos$>$ values: LOCAL\_GROUP\_CENTER, UNKNOWNRefPos,
+         EMBARYCENTER, MOON, MERCURY, VENUS, MARS, JUPITER, SATURN, URANUS,
+         NEPTUNE, PLUTO.
+
+         \sstitem
+          Error values are supported but error ranges are not.
+
+         \sstitem
+          Resolution, PixSize and Size values are ignored.
+
+         \sstitem
+          Space velocity sub-phrases are ignored.
+      }
+   }
+   \sstconstructor{
+      \htmlref{astStcsChan}{astStcsChan}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The StcsChan class inherits from the Channel class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all Channels, every
+      StcsChan also has the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{StcsArea}{StcsArea}: Return the CoordinateArea component after reading an STC-S?
+
+         \sstitem
+          \htmlref{StcsCoords}{StcsCoords}: Return the Coordinates component after reading an STC-S?
+
+         \sstitem
+          \htmlref{StcsLength}{StcsLength}: Controls output buffer length
+
+         \sstitem
+          \htmlref{StcsProps}{StcsProps}: Return the STC-S properties after reading an STC-S?
+      }
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The StcsChan class does not define any new functions beyond those
+      which are applicable to all Channels.
+   }
+}
+\sstroutine{
+   SwitchMap
+}{
+   A Mapping that encapsulates a set of alternate Mappings
+}{
+   \sstdescription{
+      A SwitchMap is a \htmlref{Mapping}{Mapping} which represents a set of alternate
+      Mappings, each of which is used to transform positions within a
+      particular region of the input or output coordinate system of the
+      SwitchMap.
+
+      A SwitchMap can encapsulate any number of Mappings, but they must
+      all have the same number of inputs (\htmlref{Nin}{Nin} attribute value) and the
+      same number of outputs (\htmlref{Nout}{Nout} attribute value). The SwitchMap itself
+      inherits these same values for its Nin and Nout attributes. Each of
+      these Mappings represents a \texttt{"} route\texttt{"}  through the switch, and are
+      referred to as \texttt{"} route\texttt{"}  Mappings below. Each route Mapping transforms
+      positions between the input and output coordinate space of the entire
+      SwitchMap, but only one Mapping will be used to transform any given
+      position. The selection of the appropriate route Mapping to use with
+      any given input position is made by another Mapping, called the
+      \texttt{"} selector\texttt{"}  Mapping. Each SwitchMap encapsulates two selector
+      Mappings in addition to its route Mappings; one for use with the
+      SwitchMap\texttt{'} s forward transformation (called the \texttt{"} forward selector
+      Mapping\texttt{"} ), and one for use with the SwitchMap\texttt{'} s inverse transformation
+      (called the \texttt{"} inverse selector Mapping\texttt{"} ). The forward selector Mapping
+      must have the same number of inputs as the route Mappings, but
+      should have only one output. Likewise, the inverse selector Mapping
+      must have the same number of outputs as the route Mappings, but
+      should have only one input.
+
+      When the SwitchMap is used to transform a position in the forward
+      direction (from input to output), each supplied input position is
+      first transformed by the forward transformation of the forward selector
+      Mapping. This produces a single output value for each input position
+      referred to as the selector value. The nearest integer to the selector
+      value is found, and is used to index the array of route Mappings (the
+      first supplied route Mapping has index 1, the second route Mapping has
+      index 2, etc). If the nearest integer to the selector value is less
+      than 1 or greater than the number of route Mappings, then the SwitchMap
+      output position is set to a value of AST\_\_BAD on every axis. Otherwise,
+      the forward transformation of the selected route Mapping is used to
+      transform the supplied input position to produce the SwitchMap output
+      position.
+
+      When the SwitchMap is used to transform a position in the inverse
+      direction (from \texttt{"} output\texttt{"}  to \texttt{"} input\texttt{"} ), each supplied \texttt{"} output\texttt{"}  position
+      is first transformed by the inverse transformation of the inverse
+      selector Mapping. This produces a selector value for each \texttt{"} output\texttt{"}
+      position. Again, the nearest integer to the selector value is found,
+      and is used to index the array of route Mappings. If this selector
+      index value is within the bounds of the array of route Mappings, then
+      the inverse transformation of the selected route Mapping is used to
+      transform the supplied \texttt{"} output\texttt{"}  position to produce the SwitchMap
+      \texttt{"} input\texttt{"}  position. If the selector index value is outside the bounds
+      of the array of route Mappings, then the SwitchMap \texttt{"} input\texttt{"}  position is
+      set to a value of AST\_\_BAD on every axis.
+
+      In practice, appropriate selector Mappings should be chosen to
+      associate a different route Mapping with each region of coordinate
+      space. Note that the \htmlref{SelectorMap}{SelectorMap} class of Mapping is particularly
+      appropriate for this purpose.
+
+      If a compound Mapping contains a SwitchMap in series with its own
+      inverse, the combination of the two adjacent SwitchMaps will be
+      replaced by a \htmlref{UnitMap}{UnitMap} when the compound Mapping is simplified using
+      \htmlref{astSimplify}{astSimplify}.
+   }
+   \sstconstructor{
+      \htmlref{astSwitchMap}{astSwitchMap}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The SwitchMap class inherits from the Mapping class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The SwitchMap class does not define any new attributes beyond those
+      which are applicable to all Mappings.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The SwitchMap class does not define any new functions beyond those
+      which are applicable to all Mappings.
+   }
+}
+\sstroutine{
+   Table
+}{
+   A 2-dimensional table of values
+}{
+   \sstdescription{
+      The Table class is a type of \htmlref{KeyMap}{KeyMap} that represents a two-dimensional
+      table of values. The
+      astMapGet... and astMapPut...
+      methods provided by the KeyMap class should be used for storing and
+      retrieving values from individual cells within a Table. Each entry
+      in the KeyMap represents a single cell of the table and has an
+      associated key of the form \texttt{"} $<$COL$>$(i)\texttt{"}  where \texttt{"} $<$COL$>$\texttt{"}  is the
+      upper-case name of a table column and \texttt{"} i\texttt{"}  is the row index (the
+      first row is row 1). Keys of this form should always be used when
+      using KeyMap methods to access entries within a Table.
+
+      Columns must be declared using the
+      \htmlref{astAddColumn}{astAddColumn}
+      method before values can be stored within them. This also fixes the
+      type and shape of the values that may be stored in any cell of the
+      column. Cells may contain scalar or vector values of any data type
+      supported by the KeyMap class. Multi-dimensional arrays may also be
+      stored, but these must be vectorised when storing and retrieving
+      them within a table cell. All cells within a single column must
+      have the same type and shape, as specified when the column is added
+      to the Table.
+
+      Tables may have parameters that describe global properties of the
+      entire table. These are stored as entries in the parent KeyMap and
+      can be access using the get and set method of the KeyMap class.
+      However, parameters must be declared using the
+      \htmlref{astAddParameter}{astAddParameter}
+      method before being accessed.
+
+      Note - since accessing entries within a KeyMap is a relatively slow
+      process, it is not recommended to use the Table class to store
+      very large tables.
+   }
+   \sstconstructor{
+      \htmlref{astTable}{astTable}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The Table class inherits from the KeyMap class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all KeyMaps, every
+      Table also has the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{ColumnLenC(column)}{ColumnLenC(column)}: The largest string length of any value in a column
+
+         \sstitem
+          \htmlref{ColumnLength(column)}{ColumnLength(column)}: The number of elements in each value in a column
+
+         \sstitem
+          \htmlref{ColumnNdim(column)}{ColumnNdim(column)}: The number of axes spanned by each value in a column
+
+         \sstitem
+          \htmlref{ColumnType(column)}{ColumnType(column)}: The data type of each value in a column
+
+         \sstitem
+          ColumnUnit(column): The unit string describing each value in a column
+
+         \sstitem
+          \htmlref{Ncolumn}{Ncolumn}: The number of columns currently in the Table
+
+         \sstitem
+          \htmlref{Nrow}{Nrow}: The number of rows currently in the Table
+
+         \sstitem
+          \htmlref{Nparameter}{Nparameter}: The number of global parameters currently in the Table
+      }
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      In addition to those functions applicable to all KeyMaps, the
+      following functions may also be applied to all Tables:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{astAddColumn}{astAddColumn}: Add a new column definition to a Table
+
+         \sstitem
+          \htmlref{astAddParameter}{astAddParameter}: Add a new global parameter definition to a Table
+
+         \sstitem
+          \htmlref{astColumnName}{astColumnName}: Return the name of the column with a given index
+
+         \sstitem
+          \htmlref{astColumnShape}{astColumnShape}: Return the shape of the values in a named column
+
+         \sstitem
+          \htmlref{astHasColumn}{astHasColumn}: Checks if a column exists in a Table
+
+         \sstitem
+          \htmlref{astHasParameter}{astHasParameter}: Checks if a global parameter exists in a Table
+
+         \sstitem
+          \htmlref{astParameterName}{astParameterName}: Return the name of the parameter with a given index
+
+         \sstitem
+          \htmlref{astPurgeRows}{astPurgeRows}: Remove all empty rows from a Table
+
+         \sstitem
+          \htmlref{astRemoveColumn}{astRemoveColumn}: Remove a column from a Table
+
+         \sstitem
+          \htmlref{astRemoveParameter}{astRemoveParameter}: Remove a global parameter from a Table
+
+         \sstitem
+          \htmlref{astRemoveRow}{astRemoveRow}: Remove a row from a Table
+      }
+   }
+}
+\sstroutine{
+   TimeFrame
+}{
+   Time coordinate system description
+}{
+   \sstdescription{
+      A TimeFrame is a specialised form of one-dimensional \htmlref{Frame}{Frame} which
+      represents various coordinate systems used to describe positions in
+      time.
+
+      A TimeFrame represents a moment in time as either an Modified Julian
+      Date (MJD), a Julian Date (JD), a Besselian epoch or a Julian epoch,
+      as determined by the \htmlref{System}{System} attribute. Optionally, a zero point can be
+      specified (using attribute \htmlref{TimeOrigin}{TimeOrigin}) which results in the TimeFrame
+      representing time offsets from the specified zero point.
+
+      Even though JD and MJD are defined as being in units of days, the
+      TimeFrame class allows other units to be used (via the Unit attribute)
+      on the basis of simple scalings (60 seconds = 1 minute, 60 minutes = 1
+      hour, 24 hours = 1 day, 365.25 days = 1 year). Likewise, Julian epochs
+      can be described in units other than the usual years. Besselian epoch
+      are always represented in units of (tropical) years.
+
+      The \htmlref{TimeScale}{TimeScale} attribute allows the time scale to be specified (that
+      is, the physical process used to define the rate of flow of time).
+      MJD, JD and Julian epoch can be used to represent a time in any
+      supported time scale. However, Besselian epoch may only be used with the
+      \texttt{"} TT\texttt{"}  (Terrestrial Time) time scale. The list of supported time scales
+      includes universal time and siderial time. Strictly, these represent
+      angles rather than time scales, but are included in the list since
+      they are in common use and are often thought of as time scales.
+
+      When a time value is formatted it can be formated either as a simple
+      floating point value, or as a Gregorian date (see the Format
+      attribute).
+   }
+   \sstconstructor{
+      \htmlref{astTimeFrame}{astTimeFrame}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The TimeFrame class inherits from the Frame class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all Frames, every
+      TimeFrame also has the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{AlignTimeScale}{AlignTimeScale}: Time scale in which to align TimeFrames
+
+         \sstitem
+          \htmlref{LTOffset}{LTOffset}: The offset of Local Time from UTC, in hours.
+
+         \sstitem
+          \htmlref{TimeOrigin}{TimeOrigin}: The zero point for TimeFrame axis values
+
+         \sstitem
+          \htmlref{TimeScale}{TimeScale}: The timescale used by the TimeFrame
+
+      }
+      Several of the Frame attributes inherited by the TimeFrame class
+      refer to a specific axis of the Frame (for instance \htmlref{Unit(axis)}{Unit(axis)},
+      \htmlref{Label(axis)}{Label(axis)}, etc). Since a TimeFrame is strictly one-dimensional,
+      it allows these attributes to be specified without an axis index.
+      So for instance, \texttt{"} Unit\texttt{"}  is allowed in place of \texttt{"} Unit(1)\texttt{"} .
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      In addition to those functions applicable to all Frames, the
+      following functions may also be applied to all TimeFrames:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{astCurrentTime}{astCurrentTime}: Return the current system time
+      }
+   }
+}
+\sstroutine{
+   TimeMap
+}{
+   Sequence of time coordinate conversions
+}{
+   \sstdescription{
+      A TimeMap is a specialised form of 1-dimensional \htmlref{Mapping}{Mapping} which can be
+      used to represent a sequence of conversions between standard time
+      coordinate systems.
+
+      When a TimeMap is first created, it simply performs a unit
+      (null) Mapping. Using the \htmlref{astTimeAdd}{astTimeAdd}
+      function, a series of coordinate conversion steps may then be
+      added. This allows multi-step conversions between a variety of
+      time coordinate systems to be assembled out of a set of building
+      blocks.
+
+      For details of the individual coordinate conversions available,
+      see the description of the astTimeAdd function.
+   }
+   \sstconstructor{
+      \htmlref{astTimeMap}{astTimeMap} (also see astTimeAdd)
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The TimeMap class inherits from the Mapping class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The TimeMap class does not define any new attributes beyond those
+      which are applicable to all Mappings.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      In addition to those functions applicable to all Mappings, the
+      following function may also be applied to all TimeMaps:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{astTimeAdd}{astTimeAdd}: Add a time coordinate conversion to an TimeMap
+      }
+   }
+}
+\sstroutine{
+   TranMap
+}{
+   Mapping with specified forward and inverse transformations
+}{
+   \sstdescription{
+      A TranMap is a \htmlref{Mapping}{Mapping} which combines the forward transformation of
+      a supplied Mapping with the inverse transformation of another
+      supplied Mapping, ignoring the un-used transformation in each
+      Mapping (indeed the un-used transformation need not exist).
+
+      When the forward transformation of the TranMap is referred to, the
+      transformation actually used is the forward transformation of the
+      first Mapping supplied when the TranMap was constructed. Likewise,
+      when the inverse transformation of the TranMap is referred to, the
+      transformation actually used is the inverse transformation of the
+      second Mapping supplied when the TranMap was constructed.
+   }
+   \sstconstructor{
+      \htmlref{astTranMap}{astTranMap}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The TranMap class inherits from the Mapping class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The TranMap class does not define any new attributes beyond those
+      which are applicable to all Mappings.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The TranMap class does not define any new functions beyond those
+      which are applicable to all Mappings.
+   }
+}
+\sstroutine{
+   UnitMap
+}{
+   Unit (null) Mapping
+}{
+   \sstdescription{
+      A UnitMap is a unit (null) \htmlref{Mapping}{Mapping} that has no effect on the
+      coordinates supplied to it. They are simply copied. This can be
+      useful if a Mapping is required (e.g. to pass to another
+      function) but you do not want it to have any effect.
+      The \htmlref{Nin}{Nin} and \htmlref{Nout}{Nout} attributes of a UnitMap are always equal and
+      are specified when it is created.
+   }
+   \sstconstructor{
+      \htmlref{astUnitMap}{astUnitMap}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The UnitMap class inherits from the Mapping class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The UnitMap class does not define any new attributes beyond
+      those which are applicable to all Mappings.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The UnitMap class does not define any new functions beyond those
+      which are applicable to all Mappings.
+   }
+}
+\sstroutine{
+   UnitNormMap
+}{
+   Convert a vector to a unit vector and its norm, relative to a specified centre
+}{
+   \sstdescription{
+      The forward transformation of a UnitNormMap subtracts the specified centre
+      and then transforms the resulting vector to a unit vector and the vector norm.
+      The output contains one more coordinate than the input: the initial
+      \htmlref{Nin}{Nin} outputs are in the same order as the input; the final output is the norm.
+      If the norm is 0, then the output of the forward transformation is AST\_\_BAD
+      for each component of the unit vector and 0 for the norm (the final value).
+
+      The inverse transformation of a UnitNormMap multiplies each component
+      of the provided vector by the provided norm and adds the specified centre.
+      The output contains one fewer coordinate than the input: the initial Nin inputs
+      are in the same order as the output; the final input is the norm.
+      If the provided norm is 0 then the other input values are ignored,
+      and the output vector is the centre.
+
+      Example: if centre = [1, -1] then [5, 2] transforms to [4, 3] after subtracting the centre;
+      the norm is 5, so the output is [0.8, 0.6, 5].
+
+      UnitNormMap enables radially symmetric transformations, as follows:
+      \sstitemlist{
+
+         \sstitem
+          apply a UnitNormMap to produce a unit vector and norm (radius)
+
+         \sstitem
+          apply a one-dimensional mapping to the norm (radius), while passing the unit vector unchanged
+
+         \sstitem
+          apply the same UnitNormMap in the inverse direction to produce the result
+      }
+   }
+   \sstconstructor{
+      \htmlref{astUnitNormMap}{astUnitNormMap}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The UnitNormMap class inherits from the \htmlref{Mapping}{Mapping} class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The UnitNormMap class does not define any new attributes beyond those
+      which are applicable to all Mappings.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The UnitNormMap class does not define any new functions beyond those
+      which are applicable to all Mappings.
+   }
+}
+\sstroutine{
+   WcsMap
+}{
+   Implement a FITS-WCS sky projection
+}{
+   \sstdescription{
+      This class is used to represent sky coordinate projections as
+      described in the FITS world coordinate system (FITS-WCS) paper II
+      \texttt{"} Representations of Celestial Coordinates in FITS\texttt{"}  by M. Calabretta
+      and E.W. Griesen. This paper defines a set of functions, or sky
+      projections, which transform longitude-latitude pairs representing
+      spherical celestial coordinates into corresponding pairs of Cartesian
+      coordinates (and vice versa).
+
+      A WcsMap is a specialised form of \htmlref{Mapping}{Mapping} which implements these
+      sky projections and applies them to a specified pair of coordinates.
+      All the projections in the FITS-WCS paper are supported, plus the now
+      deprecated \texttt{"} TAN with polynomial correction terms\texttt{"}  projection which
+      is refered to here by the code \texttt{"} TPN\texttt{"} . Using the FITS-WCS terminology,
+      the transformation is between \texttt{"} native spherical\texttt{"}  and \texttt{"} projection
+      plane\texttt{"}  coordinates (also called \texttt{"} intermediate world coordinates\texttt{"} .
+      These coordinates may, optionally, be embedded in a space with more
+      than two dimensions, the remaining coordinates being copied unchanged.
+      Note, however, that for consistency with other AST facilities, a
+      WcsMap handles coordinates that represent angles in radians (rather
+      than the degrees used by FITS-WCS).
+
+      The type of FITS-WCS projection to be used and the coordinates
+      (axes) to which it applies are specified when a WcsMap is first
+      created. The projection type may subsequently be determined
+      using the \htmlref{WcsType}{WcsType} attribute and the coordinates on which it acts
+      may be determined using the \htmlref{WcsAxis(lonlat)}{WcsAxis(lonlat)} attribute.
+
+      Each WcsMap also allows up to 100 \texttt{"} projection parameters\texttt{"}  to be
+      associated with each axis. These specify the precise form of the
+      projection, and are accessed using \htmlref{PVi\_m}{PVi\_m} attribute, where \texttt{"} i\texttt{"}  is
+      the integer axis index (starting at 1), and m is an integer
+      \texttt{"} parameter index\texttt{"}  in the range 0 to 99. The number of projection
+      parameters required by each projection, and their meanings, are
+      dependent upon the projection type (most projections either do not
+      use any projection parameters, or use parameters 1 and 2 associated
+      with the latitude axis). Before creating a WcsMap you should consult
+      the FITS-WCS paper for details of which projection parameters are
+      required, and which have defaults. When creating the WcsMap, you must
+      explicitly set values for all those required projection parameters
+      which do not have defaults defined in this paper.
+   }
+   \sstconstructor{
+      \htmlref{astWcsMap}{astWcsMap}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The WcsMap class inherits from the Mapping class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all Mappings, every
+      WcsMap also has the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{NatLat}{NatLat}: Native latitude of the reference point of a FITS-WCS projection
+
+         \sstitem
+          \htmlref{NatLon}{NatLon}: Native longitude of the reference point of a FITS-WCS projection
+
+         \sstitem
+          \htmlref{PVi\_m}{PVi\_m}: FITS-WCS projection parameters
+
+         \sstitem
+          PVMax: Maximum number of FITS-WCS projection parameters
+
+         \sstitem
+          \htmlref{WcsAxis(lonlat)}{WcsAxis(lonlat)}: FITS-WCS projection axes
+
+         \sstitem
+          \htmlref{WcsType}{WcsType}: FITS-WCS projection type
+      }
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The WcsMap class does not define any new functions beyond those
+      which are applicable to all Mappings.
+   }
+}
+\sstroutine{
+   WinMap
+}{
+   Map one window on to another by scaling and shifting each axis
+}{
+   \sstdescription{
+      A Winmap is a linear \htmlref{Mapping}{Mapping} which transforms a rectangular
+      window in one coordinate system into a similar window in another
+      coordinate system by scaling and shifting each axis (the window
+      edges being parallel to the coordinate axes).
+
+      A WinMap is specified by giving the coordinates of two opposite
+      corners (A and B) of the window in both the input and output
+      coordinate systems.
+   }
+   \sstconstructor{
+      \htmlref{astWinMap}{astWinMap}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The WinMap class inherits from the Mapping class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      The WinMap class does not define any new attributes beyond those
+      which are applicable to all Mappings.
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The WinMap class does not define any new functions beyond those
+      which are applicable to all Mappings.
+   }
+}
+\sstroutine{
+   XmlChan
+}{
+   I/O Channel using XML to represent Objects
+}{
+   \sstdescription{
+      A XmlChan is a specialised form of \htmlref{Channel}{Channel} which supports XML I/O
+      operations. Writing an \htmlref{Object}{Object} to an XmlChan (using
+      \htmlref{astWrite}{astWrite}) will, if the Object is suitable, generate an
+      XML description of that Object, and reading from an XmlChan will
+      create a new Object from its XML description.
+
+      Normally, when you use an XmlChan, you should provide \texttt{"} source\texttt{"}
+      and \texttt{"} sink\texttt{"}  functions which connect it to an external data store
+      by reading and writing the resulting XML text. These functions
+      should perform any conversions needed between external character
+      encodings and the internal ASCII encoding. If no such functions
+      are supplied, a Channel will read from standard input and write
+      to standard output.
+
+      Alternatively, an XmlChan can be told to read or write from
+      specific text files using the \htmlref{SinkFile}{SinkFile} and \htmlref{SourceFile}{SourceFile} attributes,
+      in which case no sink or source function need be supplied.
+   }
+   \sstconstructor{
+      \htmlref{astXmlChan}{astXmlChan}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The XmlChan class inherits from the Channel class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all Channels, every
+      XmlChan also has the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{XmlFormat}{XmlFormat}: \htmlref{System}{System} for formatting Objects as XML
+
+         \sstitem
+          \htmlref{XmlLength}{XmlLength}: Controls output buffer length
+
+         \sstitem
+          \htmlref{XmlPrefix}{XmlPrefix}: The namespace prefix to use when writing
+      }
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The XmlChan class does not define any new functions beyond those
+      which are applicable to all Mappings.
+   }
+}
+\sstroutine{
+   ZoomMap
+}{
+   Zoom coordinates about the origin
+}{
+   \sstdescription{
+      The ZoomMap class implements a \htmlref{Mapping}{Mapping} which performs a \texttt{"} zoom\texttt{"}
+      transformation by multiplying all coordinate values by the same
+      scale factor (the inverse transformation is performed by
+      dividing by this scale factor). The number of coordinate values
+      representing each point is unchanged.
+   }
+   \sstconstructor{
+      \htmlref{astZoomMap}{astZoomMap}
+   }
+   \sstdiytopic{
+      Inheritance
+   }{
+      The ZoomMap class inherits from the Mapping class.
+   }
+   \sstdiytopic{
+      Attributes
+   }{
+      In addition to those attributes common to all Mappings, every
+      ZoomMap also has the following attributes:
+
+      \sstitemlist{
+
+         \sstitem
+          \htmlref{Zoom}{Zoom}: ZoomMap scale factor
+      }
+   }
+   \sstdiytopic{
+      Functions
+   }{
+      The ZoomMap class does not define any new functions beyond those
+      which are applicable to all Mappings.
+   }
+}
+\normalsize
+
+\cleardoublepage
+\section{\label{ss:commanddescriptions}UNIX Command Descriptions}
+The commands described here are provided for use from the UNIX shell
+to assist with developing software which uses AST. To use these
+commands, you should ensure that the directory
+``/star/bin''\footnote{Or the equivalent directory if AST is installed
+in a non-standard location.} is on your PATH.
+\small
+\sstroutine{
+   ast\_link
+}{
+   Link a program with the AST library
+}{
+   \sstdescription{
+      This command should be used when building programs which use the AST
+      library, in order to generate the correct arguments to allow the compiler
+      to link your program. The arguments generated are written to standard
+      output but may be substituted into the compiler command line in the
+      standard UNIX way using backward quotes (see below).
+
+      By default, it is assumed that you are building a stand-alone program
+      which does not produce graphical output. However, switches are provided
+      for linking other types of program.
+   }
+   \sstinvocation{
+      cc program.c -L/star/lib `ast\_link [switches]` -o program
+   }
+   \sstexamples{
+      \sstexamplesubsection{
+         cc display.c -L/star/lib `ast\_link -pgplot` -o display
+      }{
+         Compiles and links a C program called ``display\texttt{'} \texttt{'}  which uses
+         the standard version of PGPLOT for graphical output.
+      }
+      \sstexamplesubsection{
+         cc plotit.c -L. -L/star/lib `ast\_link -grf` -lgrf -o plotit
+      }{
+         Compiles and links a C program ``plotit\texttt{'} \texttt{'} . The ``-grf\texttt{'} \texttt{'}
+         switch indicates that graphical output will be delivered through
+         a graphical interface which you have implemented yourself, which
+         corresponds to the interface required by the current version of AST.
+         Here, this interface is supplied by means of the ``-lgrf\texttt{'} \texttt{'}  library
+         reference.
+      }
+      \sstexamplesubsection{
+         cc plotit.c -L. -L/star/lib `ast\_link -grf\_v2.0` -lgrf -o plotit
+      }{
+         Compiles and links a C program ``plotit\texttt{'} \texttt{'} . The ``-grf\_v2.0\texttt{'} \texttt{'}
+         switch indicates that graphical output will be delivered through
+         a graphical interface which you have implemented yourself, which
+         corresponds to the interface required by version 2.0 of AST.
+         Here, this interface is supplied by means of the ``-lgrf\texttt{'} \texttt{'}  library
+         reference.
+      }
+   }
+   \sstdiytopic{
+      Switches
+   }{
+      The following switches may optionally be given to this command to
+      modify its behaviour:
+
+      \sstitemlist{
+
+         \sstitem
+          ``-csla\texttt{'} \texttt{'} : Ignored. Provided for backward compatibility only.
+
+         \sstitem
+          ``-fsla\texttt{'} \texttt{'} : Ignored. Provided for backward compatibility only.
+
+         \sstitem
+          ``-ems\texttt{'} \texttt{'} : Requests that the program be linked so that error messages
+         produced by the AST library are delivered via the Starlink EMS (Error
+         Message Service) library (Starlink \htmlref{System}{System} Note SSN/4). By default,
+         error messages are simply written to standard error.
+
+         \sstitem
+          ``-drama\texttt{'} \texttt{'} : Requests that the program be linked so that error messages
+         produced by the AST library are delivered via the DRAMA Ers (Error
+         Reporting Service) library. By default, error messages are simply
+         written to standard error.
+
+         \sstitem
+          ``-grf\texttt{'} \texttt{'} : Requests that no arguments be generated to specify which
+         2D graphics system is used to display output from the AST library. You
+         should use this option only if you have implemented an interface to a
+         new graphics system yourself and wish to provide your own arguments for
+         linking with it. This switch differs from the other ``grf\texttt{'} \texttt{'}  switches in
+         that it assumes that your graphics module implements the complete
+         interface required by the current version of AST. If future versions of
+         AST introduce new functions to the graphics interface, this switch will
+         cause ``unresolved symbol\texttt{'} \texttt{'}  errors to occur during linking, warning you
+         that you need to implement new functions in your graphics module. To
+         avoid such errors, you can use one of the other, version-specific,
+         switches in place of the ``-grf\texttt{'} \texttt{'}  switch, but these will cause run-time
+         errors to be reported if any AST function is invoked which requires
+         facilities not in the implemented interface.
+
+         \sstitem
+          ``-grf\_v2.0\texttt{'} \texttt{'} : This switch is equivalent to the ``-mygrf\texttt{'} \texttt{'}  switch.
+         It indicates that you want to link with your own graphics module
+         which implements the 2D graphics interface required by V2.0 of AST.
+
+         \sstitem
+          ``-grf\_v3.2\texttt{'} \texttt{'} : Indicates that you want to link with your own
+         graphics module which implements the 2D graphics interface required by
+         V3.2 of AST.
+
+         \sstitem
+          ``-grf\_v5.6\texttt{'} \texttt{'} : Indicates that you want to link with your own
+         graphics module which implements the 2D graphics interface required by
+         V5.6 of AST.
+
+         \sstitem
+          ``-myerr\texttt{'} \texttt{'} : Requests that no arguments be generated to specify how
+         error messages produced by the AST library should be delivered. You
+         should use this option only if you have implemented an interface to a
+         new error delivery system yourself and wish to provide your own
+         arguments for linking with it.
+
+         \sstitem
+          ``-mygrf\texttt{'} \texttt{'} : This switch has been superceeded by the ``-grf\texttt{'} \texttt{'}  switch,
+         but is retained in order to allow applications to be linked with a
+         graphics module which implements the 2D interface used by AST V2.0. It
+         is equivalent to the ``-grf\_v2.0\texttt{'} \texttt{'}  switch.
+
+         \sstitem
+          ``-pgp\texttt{'} \texttt{'} : Requests that the program be linked so that 2D
+         graphical output from the AST library is displayed via the
+         Starlink version of the PGPLOT graphics package (which uses GKS
+         for its output). By default, no 2D graphics package is linked and
+         this will result in an error at run time if AST routines are
+         invoked that attempt to generate graphical output.
+
+         \sstitem
+          ``-pgplot\texttt{'} \texttt{'} : Requests that the program be linked so that 2D
+         graphical output from the AST library is displayed via
+         the standard (or ``native\texttt{'} \texttt{'} ) version of the PGPLOT graphics
+         package. By default, no 2D graphics package is linked and this will
+         result in an error at run time if AST routines are invoked that
+         attempt to generate graphical output.
+
+         \sstitem
+          ``-grf3d\texttt{'} \texttt{'} : Requests that no arguments be generated to specify which
+         3D graphics system is used to display output from the AST library. You
+         should use this option only if you have implemented an interface to a
+         new 3D graphics system yourself and wish to provide your own arguments
+         for linking with it.
+
+         \sstitem
+          ``-pgp3d\texttt{'} \texttt{'} : Requests that the program be linked so that 3D
+         graphical output from the AST library is displayed via the
+         Starlink version of the PGPLOT graphics package (which uses GKS
+         for its output). By default, no 3D graphics package is linked and
+         this will result in an error at run time if AST routines are
+         invoked that attempt to generate graphical output.
+
+         \sstitem
+          ``-pgplot3d\texttt{'} \texttt{'} : Requests that the program be linked so that 3D
+         graphical output from the AST library is displayed via
+         the standard (or ``native\texttt{'} \texttt{'} ) version of the PGPLOT graphics
+         package. By default, no 3D graphics package is linked and this will
+         result in an error at run time if AST routines are invoked that
+         attempt to generate graphical output.
+      }
+   }
+   \sstdiytopic{
+      ERFA \& PAL
+   }{
+      The AST distribution includes bundled copies of the ERFA and PAL
+      libraries. These will be used for fundamental positional astronomy
+      calculations unless the \texttt{"} --with-external\_pal\texttt{"}  option was used when
+      AST was configured. If \texttt{"} --with-external\_pal\texttt{"}  is used, this script
+      will include \texttt{"} -lpal\texttt{"}  in the returned list of linking options, and
+      the user should then ensure that external copies of the PAL and
+      ERFA libraries are available (ERFA functions are used within PAL).
+   }
+}
+\sstroutine{
+   ast\_link\_adam
+}{
+   Link an ADAM program with the AST library
+}{
+   \sstdescription{
+      This command should only be used when building Starlink ADAM programs
+      which use the AST library, in order to generate the correct arguments
+      to allow the ADAM ``alink\texttt{'} \texttt{'}  command to link the program. The arguments
+      generated are written to standard output but may be substituted into
+      the ``alink\texttt{'} \texttt{'}  command line in the standard UNIX way using backward
+      quotes (see below).
+
+      By default, it is assumed that you are building an ADAM program which
+      does not produce graphical output. However, switches are provided for
+      linking other types of program. This command should not be used when
+      building stand-alone (non-ADAM) programs. Use the ``\htmlref{ast\_link}{ast\_link}\texttt{'} \texttt{'}  command
+      instead.
+   }
+   \sstinvocation{
+      alink program.o -L/star/lib `ast\_link\_adam [switches]`
+   }
+   \sstexamples{
+      \sstexamplesubsection{
+         alink display.o -L/star/lib `ast\_link\_adam -pgplot`
+      }{
+         Links an ADAM program ``display\texttt{'} \texttt{'}  which uses the standard
+         version of PGPLOT for graphical output.
+      }
+      \sstexamplesubsection{
+         alink plotit.o -L. -L/star/lib `ast\_link\_adam -grf` -lgrf
+      }{
+         Links an ADAM program ``plotit\texttt{'} \texttt{'} , written in C. The ``-grf\texttt{'} \texttt{'}
+         switch indicates that graphical output will be delivered through
+         a graphical interface which you have implemented yourself, which
+         corresponds to the interface required by the current version of AST.
+         Here, this interface is supplied by means of the ``-lgrf\texttt{'} \texttt{'}  library
+         reference.
+      }
+      \sstexamplesubsection{
+         alink plotit.o -L. -L/star/lib `ast\_link\_adam -grf\_v2.0` -lgrf
+      }{
+         Links an ADAM program ``plotit\texttt{'} \texttt{'} , written in C. The ``-grf\_v2.0\texttt{'} \texttt{'}
+         switch indicates that graphical output will be delivered through
+         a graphical interface which you have implemented yourself, which
+         corresponds to the interface required by version 2.0 of AST. Here,
+         this interface is supplied by means of the ``-lgrf\texttt{'} \texttt{'}  library
+         reference.
+      }
+   }
+   \sstdiytopic{
+      Switches
+   }{
+      The following switches may optionally be given to this command to
+      modify its behaviour:
+
+      \sstitemlist{
+
+         \sstitem
+          ``-csla\texttt{'} \texttt{'} : Ignored. Provided for backward compatibility only.
+
+         \sstitem
+          ``-fsla\texttt{'} \texttt{'} : Ignored. Provided for backward compatibility only.
+
+         \sstitem
+          ``-grf\texttt{'} \texttt{'} : Requests that no arguments be generated to specify which
+         2D graphics system is used to display output from the AST library. You
+         should use this option only if you have implemented an interface to a
+         new graphics system yourself and wish to provide your own arguments for
+         linking with it. This switch differs from the other ``grf\texttt{'} \texttt{'}  switches in
+         that it assumes that your graphics module implements the complete
+         interface required by the current version of AST. If future versions of
+         AST introduce new functions to the graphics interface, this switch will
+         cause ``unresolved symbol\texttt{'} \texttt{'}  errors to occur during linking, warning you
+         that you need to implement new functions in your graphics module. To
+         avoid such errors, you can use one of the other, version-specific,
+         switches in place of the ``-grf\texttt{'} \texttt{'}  switch, but these will cause run-time
+         errors to be reported if any AST function is invoked which requires
+         facilities not in the implemented interface.
+
+         \sstitem
+          ``-grf\_v2.0\texttt{'} \texttt{'} : This switch is equivalent to the ``-mygrf\texttt{'} \texttt{'}  switch.
+         It indicates that you want to link with your own graphics module which
+         implements the 2D graphics interface required by V2.0 of AST.
+
+         \sstitem
+          ``-grf\_v3.2\texttt{'} \texttt{'} : Indicates that you want to link with your own graphics
+         module which implements the 2D graphics interface required by V3.2 of AST.
+
+         \sstitem
+          ``-grf\_v5.6\texttt{'} \texttt{'} : Indicates that you want to link with your own graphics
+         module which implements the 2D graphics interface required by V5.6 of AST.
+
+         \sstitem
+          ``-myerr\texttt{'} \texttt{'} : Requests that no arguments be generated to specify how
+         error messages produced by the AST library should be delivered. You
+         should use this option only if you have implemented an interface to a
+         new error delivery system yourself and wish to provide your own
+         arguments for linking with it. By default, error messages are delivered
+         in the standard ADAM way via the EMS Error Message Service (Starlink
+         \htmlref{System}{System} Note SSN/4).
+
+         \sstitem
+          ``-mygrf\texttt{'} \texttt{'} : This switch has been superceeded by the ``-grf\texttt{'} \texttt{'}  switch,
+         but is retained in order to allow applications to be linked with a
+         graphics module which implements the interface used by AST V2.0. It is
+         equivalent to the ``-grf\_v2.0\texttt{'} \texttt{'}  switch.
+
+         \sstitem
+          ``-pgp\texttt{'} \texttt{'} : Requests that the program be linked so that 2D
+         graphical output from the AST library is displayed via the
+         Starlink version of the PGPLOT graphics package (which uses GKS
+         for its output). By default, no graphics package is linked and
+         this will result in an error at run time if AST routines are
+         invoked that attempt to generate graphical output.
+
+         \sstitem
+          ``-pgplot\texttt{'} \texttt{'} : Requests that the program be linked so that 2D
+         graphical output from the AST library is displayed via the
+         standard (or ``native\texttt{'} \texttt{'} ) version of the PGPLOT graphics
+         package. By default, no graphics package is linked and this will
+         result in an error at run time if AST routines are invoked that
+         attempt to generate graphical output.
+
+         \sstitem
+          ``-grf3d\texttt{'} \texttt{'} : Requests that no arguments be generated to specify which
+         3D graphics system is used to display output from the AST library. You
+         should use this option only if you have implemented an interface to a
+         new 3D graphics system yourself and wish to provide your own arguments
+         for linking with it.
+
+         \sstitem
+          ``-pgp3d\texttt{'} \texttt{'} : Requests that the program be linked so that 3D
+         graphical output from the AST library is displayed via the
+         Starlink version of the PGPLOT graphics package (which uses GKS
+         for its output). By default, no 3D graphics package is linked and
+         this will result in an error at run time if AST routines are
+         invoked that attempt to generate graphical output.
+
+         \sstitem
+          ``-pgplot3d\texttt{'} \texttt{'} : Requests that the program be linked so that 3D
+         graphical output from the AST library is displayed via
+         the standard (or ``native\texttt{'} \texttt{'} ) version of the PGPLOT graphics
+         package. By default, no 3D graphics package is linked and this will
+         result in an error at run time if AST routines are invoked that
+         attempt to generate graphical output.
+      }
+   }
+   \sstdiytopic{
+      SLALIB
+   }{
+      The AST distribution includes a cut down subset of the C version of
+      the SLALIB library written by Pat Wallace. This subset contains only
+      the functions needed by the AST library. It is built as part of the
+      process of building AST and is distributed under GPL (and is thus
+      compatible with the AST license). Previous version of this script
+      allowed AST applications to be linked against external SLALIB
+      libraries (either Fortran or C) rather than the internal version.
+      The current version of this script does not provide this option,
+      and always uses the internal SLALIB library. However, for backward
+      compatibility, this script still allows the \texttt{"} -fsla\texttt{"}  and \texttt{"} -csla\texttt{"}  flags
+      (previously used for selecting which version of SLALIB to use) to be
+      specified, but they will be ignored.
+   }
+}
+\normalsize
+
+\cleardoublepage
+\section{\label{ss:memoryfunctions}AST Memory Management and Utility Functions}
+AST provides a memory management layer that can be used in place of
+system functions such as \texttt{malloc}, \texttt{free}, \texttt{realloc},
+\emph{etc.} The AST replacements for these functions ( \texttt{\htmlref{astMalloc}{astMalloc}},
+\texttt{\htmlref{astFree}{astFree}} and \texttt{\htmlref{astRealloc}{astRealloc}}) add extra information to each
+allocated memory block that allows AST to check the validity of supplied
+pointers. For example, this extra information allows \texttt{astFree} to
+detect if the supplied pointer has already been freed, and if so to issue
+an appropriate error message. The existence of this extra information is
+invisible to outside callers, and stored in a header block located just
+before the returned memory block.
+
+In addition to the standard functions, AST provides other memory management
+functions, such as:
+
+\begin{description}
+\item [\texttt{\htmlref{astStore}{astStore}}] - stores data in dynamically allocated memory, allocating
+the memory (or adjusting the size of previously allocated memory) to match
+the amount of data to be stored.
+\item [\texttt{\htmlref{astGrow}{astGrow}}] - allocates and expands memory to hold an adjustable-sized array.
+\item [\texttt{\htmlref{astAppendString}{astAppendString}}] - allocates and expands memory to hold a
+concatenated string.
+\end{description}
+
+Theses are just a few of the available utilities functions in the AST
+memory management layer. Prototypes for all AST memory management
+functions are included in the header file ``\texttt{ast.h}''.
+
+An important restriction on these functions is that pointers created by
+other memory management functions, such as the system version of \texttt{malloc} \emph{etc.}, should never supplied to an AST memory management
+function. Only pointers created by AST should be used by these functions.
+
+In addition to memory management functions, AST provides various other
+utility functions, such as a basic regular expression facility, and other
+string manipulation functions. These are also documented in this appendix.
+
+The AST memory management layer is implemented on top of the usual \texttt{malloc}, {tt free} and \texttt{realloc} functions. By default these will be
+the standard functions provided by <stdlib.h>. However, the facilities of
+the STARMEM package (included in the Starlink Software Collection) can be
+used to specify alternative functions to use. This requires that AST be
+configured using the ``--with-starmem'' option when it is built.
+
+The STARMEM package provides a wrapper for the standard malloc
+implementation that enables the user to switch malloc schemes at runtime
+by setting the STARMEM\_MALLOC environment variable. Currently allowed
+values for this variable are:
+
+\begin{description}
+\item [SYSTEM] - standard system malloc/free - the default
+\item [DL] - Doug Lea's malloc/free
+\item [GC] - Hans-Boehm Garbage Collection
+\end{description}
+
+\small
+\sstroutine{
+   astAppendString
+}{
+   Append a string to another string which grows dynamically
+}{
+   \sstdescription{
+      This function appends one string to another dynamically
+      allocated string, extending the dynamic string as necessary to
+      accommodate the new characters (plus the final null).
+   }
+   \sstsynopsis{
+      char $*$astAppendString( char $*$str1, int $*$nc, const char $*$str2 )
+   }
+   \sstparameters{
+      \sstsubsection{
+         str1
+      }{
+         Pointer to the null-terminated dynamic string, whose memory
+         has been allocated using an AST memory allocation function.
+         If no space has yet been allocated for this string, a NULL
+         pointer may be given and fresh space will be allocated by this
+         function.
+      }
+      \sstsubsection{
+         nc
+      }{
+         Pointer to an integer containing the number of characters in
+         the dynamic string (excluding the final null). This is used
+         to save repeated searching of this string to determine its
+         length and it defines the point where the new string will be
+         appended. Its value is updated by this function to include
+         the extra characters appended.
+
+         If \texttt{"} str1\texttt{"}  is NULL, the initial value supplied for \texttt{"} $*$nc\texttt{"}  will
+         be ignored and zero will be used.
+      }
+      \sstsubsection{
+         str2
+      }{
+         Pointer to a constant null-terminated string, a copy of which
+         is to be appended to \texttt{"} str1\texttt{"} .
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astAppendString()
+      }{
+         A possibly new pointer to the dynamic string with the new string
+         appended (its location in memory may have to change if it has to
+         be extended, in which case the original memory is automatically
+         freed by this function). When the string is no longer required,
+         its memory should be freed using \htmlref{astFree}{astFree}.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If this function is invoked with the global error status set
+         or if it should fail for any reason, then the returned pointer
+         will be equal to \texttt{"} str1\texttt{"}  and the dynamic string contents will be
+         unchanged.
+      }
+   }
+}
+\sstroutine{
+   astAppendStringf
+}{
+   Append a string to another string, allowing printf format specifiers
+}{
+   \sstdescription{
+      This function appends one string to another dynamically
+      allocated string, extending the dynamic string as necessary to
+      accommodate the new characters (plus the final null). It is the
+      same as \htmlref{astAppendString}{astAppendString}, except that the \texttt{"} str2\texttt{"}  string ay include
+      printf format specifiers.
+   }
+   \sstsynopsis{
+      char $*$astAppendStringf( char $*$str1, int $*$nc, const char $*$str2, ... )
+   }
+   \sstparameters{
+      \sstsubsection{
+         str1
+      }{
+         Pointer to the null-terminated dynamic string, whose memory
+         has been allocated using an AST memory allocation function.
+         If no space has yet been allocated for this string, a NULL
+         pointer may be given and fresh space will be allocated by this
+         function.
+      }
+      \sstsubsection{
+         nc
+      }{
+         Pointer to an integer containing the number of characters in
+         the dynamic string (excluding the final null). This is used
+         to save repeated searching of this string to determine its
+         length and it defines the point where the new string will be
+         appended. Its value is updated by this function to include
+         the extra characters appended.
+
+         If \texttt{"} str1\texttt{"}  is NULL, the initial value supplied for \texttt{"} $*$nc\texttt{"}  will
+         be ignored and zero will be used.
+      }
+      \sstsubsection{
+         str2
+      }{
+         Pointer to a constant null-terminated string, a copy of which
+         is to be appended to \texttt{"} str1\texttt{"} . It may contain format
+         specifications such as used with the C \texttt{"} printf\texttt{"}  family of
+         functions.
+      }
+      \sstsubsection{
+         ...
+      }{
+         Additional optional arguments (as used by e.g. \texttt{"} printf\texttt{"} )
+         which specify values which are to be substituted into the \texttt{"} str2\texttt{"}
+         string in place of any format specifications.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astAppendString()
+      }{
+         A possibly new pointer to the dynamic string with the new string
+         appended (its location in memory may have to change if it has to
+         be extended, in which case the original memory is automatically
+         freed by this function). When the string is no longer required,
+         its memory should be freed using \htmlref{astFree}{astFree}.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If this function is invoked with the global error status set
+         or if it should fail for any reason, then the returned pointer
+         will be equal to \texttt{"} str1\texttt{"}  and the dynamic string contents will be
+         unchanged.
+      }
+   }
+}
+\sstroutine{
+   astCalloc
+}{
+   Allocate and initialise memory
+}{
+   \sstdescription{
+      This function allocates memory in a similar manner to the
+      standard C \texttt{"} calloc\texttt{"}  function, but with improved security
+      (against memory leaks, etc.) and with error reporting. It also
+      fills the allocated memory with zeros.
+
+      Like \htmlref{astMalloc}{astMalloc}, it allows zero-sized memory allocation
+      (without error), resulting in a NULL returned pointer value.
+   }
+   \sstsynopsis{
+      void $*$astCalloc( size\_t nmemb, size\_t size )
+   }
+   \sstparameters{
+      \sstsubsection{
+         nmemb
+      }{
+         The number of array elements for which memory is to be allocated.
+      }
+      \sstsubsection{
+         size
+      }{
+         The size of each array element, in bytes.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astCalloc()
+      }{
+         If successful, the function returns a pointer to the start of
+         the allocated memory region. If the size allocated is zero, this
+         will be a NULL pointer.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A pointer value of NULL is returned if this function is
+         invoked with the global error status set or if it fails for any
+         reason.
+      }
+   }
+}
+\sstroutine{
+   astChr2Double
+}{
+   read a double value from a string
+}{
+   \sstdescription{
+      This function reads a double from the supplied null-terminated string,
+      ignoring leading and trailing white space. AST\_\_BAD is ereturned
+      without error if the string is not a numerical value.
+   }
+   \sstsynopsis{
+      double astChr2Double( const char $*$str )
+   }
+   \sstparameters{
+      \sstsubsection{
+         str
+      }{
+         Pointer to the string.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astChr2Double()
+      }{
+         The double value, or AST\_\_BAD.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A value of AST\_\_BAD is returned if this function is invoked with
+         the global error status set or if it should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astChrCase
+}{
+   Convert a string to upper or lower case
+}{
+   \sstdescription{
+      This function converts a supplied string to upper or lower case,
+      storing the result in a supplied buffer. The \htmlref{astStringCase}{astStringCase} function
+      is similar, but stores the result in a dynamically allocated buffer.
+   }
+   \sstsynopsis{
+      void astChrCase( const char $*$in, char $*$out, int upper, int blen, int $*$status )
+   }
+   \sstparameters{
+      \sstsubsection{
+         in
+      }{
+         Pointer to the null terminated string to be converted. If this
+         is NULL, the supplied contents of the \texttt{"} out\texttt{"}  string are used as
+         the input string.
+      }
+      \sstsubsection{
+         out
+      }{
+         Pointer to the buffer to receive the converted string. The
+         length of this buffer is given by \texttt{"} blen\texttt{"} . If NULL is supplied
+         for \texttt{"} in\texttt{"} , then the supplied contents of \texttt{"} out\texttt{"}  are converted and
+         written back into \texttt{"} out\texttt{"}  over-writing the supplied contents.
+      }
+      \sstsubsection{
+         upper
+      }{
+         If non-zero, the string is converted to upper case. Otherwise it
+         is converted to lower case.
+      }
+      \sstsubsection{
+         blen
+      }{
+         The length of the output buffer. Ignored if \texttt{"} in\texttt{"}  is NULL. No
+         more than \texttt{"} blen - 1\texttt{"}  characters will be copied from \texttt{"} in\texttt{"}  to
+         \texttt{"} out\texttt{"} , and a terminating null character will then be added.
+      }
+   }
+}
+\sstroutine{
+   astChrLen
+}{
+   Determine the used length of a string
+}{
+   \sstdescription{
+      This function returns the used length of a string. This excludes any
+      trailing white space or non-printable characters (such as the
+      trailing null character).
+   }
+   \sstsynopsis{
+      size\_t astChrLen( const char $*$string )
+   }
+   \sstparameters{
+      \sstsubsection{
+         string
+      }{
+         Pointer to the string.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astChrLen()
+      }{
+         The number of characters in the supplied string, not including the
+         trailing newline, and any trailing white-spaces or non-printable
+         characters.
+      }
+   }
+}
+\sstroutine{
+   astChrMatch
+}{
+   Case insensitive string comparison
+}{
+   \sstdescription{
+      This function compares two null terminated strings for equality,
+      discounting differences in case and any trailing white space in either
+      string.
+   }
+   \sstsynopsis{
+      int astChrMatch( const char $*$str1, const char $*$str2 )
+   }
+   \sstparameters{
+      \sstsubsection{
+         str1
+      }{
+         Pointer to the first string.
+      }
+      \sstsubsection{
+         str2
+      }{
+         Pointer to the second string.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astChrMatch()
+      }{
+         Non-zero if the two strings match, otherwise zero.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A value of zero is returned if this function is invoked with the
+         global error status set or if it should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astChrMatchN
+}{
+   Case insensitive string comparison of at most N characters
+}{
+   \sstdescription{
+      This function compares two null terminated strings for equality,
+      discounting differences in case and any trailing white space in either
+      string. No more than \texttt{"} n\texttt{"}  characters are compared.
+   }
+   \sstsynopsis{
+      int astChrMatchN( const char $*$str1, const char $*$str2, size\_t n )
+   }
+   \sstparameters{
+      \sstsubsection{
+         str1
+      }{
+         Pointer to the first string.
+      }
+      \sstsubsection{
+         str2
+      }{
+         Pointer to the second string.
+      }
+      \sstsubsection{
+         n
+      }{
+         Maximum number of characters to compare.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astChrMatchN()
+      }{
+         Non-zero if the two strings match, otherwise zero.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A value of zero is returned if this function is invoked with the
+         global error status set or if it should fail for any reason.
+      }
+   }
+}
+\sstroutine{
+   astChrSplit
+}{
+   Extract words from a supplied string
+}{
+   \sstdescription{
+      This function extracts all space-separated words form the supplied
+      string and returns them in an array of dynamically allocated strings.
+   }
+   \sstsynopsis{
+      char $*$$*$astChrSplit\_( const char $*$str, int $*$n )
+   }
+   \sstparameters{
+      \sstsubsection{
+         str
+      }{
+         Pointer to the string to be split.
+      }
+      \sstsubsection{
+         n
+      }{
+         Address of an int in which to return the number of words returned.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astChrSplit()
+      }{
+         A pointer to a dynamically allocated array containing \texttt{"} $*$n\texttt{"}  elements.
+         Each element is a pointer to a dynamically allocated character
+         string containing a word extracted from the supplied string. Each
+         of these words will have no leading or trailing white space.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A NULL pointer is returned if this function is invoked with the
+         global error status set or if it should fail for any reason, or if
+         the supplied string contains no words.
+      }
+   }
+}
+\sstroutine{
+   astChrSplitC
+}{
+   Split a string using a specified character delimiter
+}{
+   \sstdescription{
+      This function extracts all sub-strings separated by a given
+      character from the supplied string and returns them in an array
+      of dynamically allocated strings. The delimiter character itself
+      is not included in the returned strings.
+
+      Delimiter characters that are preceded by \texttt{"} $\backslash$\texttt{"}  are not used as
+      delimiters but are included in the returned word instead (without
+      the \texttt{"} $\backslash$\texttt{"} ).
+   }
+   \sstsynopsis{
+      char $*$$*$astChrSplitC( const char $*$str, char c, int $*$n )
+   }
+   \sstparameters{
+      \sstsubsection{
+         str
+      }{
+         Pointer to the string to be split.
+      }
+      \sstsubsection{
+         c
+      }{
+         The delimiter character.
+      }
+      \sstsubsection{
+         n
+      }{
+         Address of an int in which to return the number of words returned.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astChrSplitC()
+      }{
+         A pointer to a dynamically allocated array containing \texttt{"} $*$n\texttt{"}  elements.
+         Each element is a pointer to a dynamically allocated character
+         string containing a word extracted from the supplied string.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A NULL pointer is returned if this function is invoked with the
+         global error status set or if it should fail for any reason, or if
+         the supplied string contains no words.
+      }
+   }
+}
+\sstroutine{
+   astChrSplitRE
+}{
+   Extract sub-strings matching a specified regular expression
+}{
+   \sstdescription{
+      This function compares the supplied string with the supplied
+      regular expression. If they match, each section of the test string
+      that corresponds to a parenthesised sub-string in the regular
+      expression is copied and stored in the returned array.
+   }
+   \sstsynopsis{
+      char $*$$*$astChrSplitRE( const char $*$str, const char $*$regexp, int $*$n,
+                            const char $*$$*$matchend )
+   }
+   \sstparameters{
+      \sstsubsection{
+         str
+      }{
+         Pointer to the string to be split.
+      }
+      \sstsubsection{
+         regexp
+      }{
+         The regular expression. See \texttt{"} Template Syntax:\texttt{"}  in the \htmlref{astChrSub}{astChrSub}
+         prologue. Note, this function differs from astChrSub in that any
+         equals signs (=) in the regular expression are treated literally.
+      }
+      \sstsubsection{
+         n
+      }{
+         Address of an int in which to return the number of sub-strings
+         returned.
+      }
+      \sstsubsection{
+         matchend
+      }{
+         A pointer to a location at which to return a pointer to the
+         character that follows the last character within the supplied test
+         string that matched any parenthesises sub-section of \texttt{"} regexp\texttt{"} . A
+         NULL pointer is returned if no matches were found. A NULL pointer
+         may be supplied if the location of the last matching character is
+         not needed.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astChrSplitRE()
+      }{
+         A pointer to a dynamically allocated array containing \texttt{"} $*$n\texttt{"}  elements.
+         Each element is a pointer to a dynamically allocated character
+         string containing a sub-string extracted from the supplied string.
+         The array itself, and the strings within it, should all be freed
+         using \htmlref{astFree}{astFree} when no longer needed.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If a parenthesised sub-string in the regular expression is matched
+         by more than one sub-string within the test string, then only the
+         first is returned. To return multiple matches, the regular
+         expression should include multiple copies of the parenthesised
+         sub-string (for instance, separated by \texttt{"} .$+$?\texttt{"}  if the intervening
+         string is immaterial).
+
+         \sstitem
+          A NULL pointer is returned if this function is invoked with the
+         global error status set or if it should fail for any reason, or if
+         the supplied string contains no words.
+      }
+   }
+}
+\sstroutine{
+   astChrSub
+}{
+   Performs substitutions on a supplied string
+}{
+   \sstdescription{
+      This function checks a supplied test string to see if it matches a
+      supplied template. If it does, specified sub-sections of the test
+      string may optionally be replaced by supplied substitution strings.
+      The resulting string is returned.
+   }
+   \sstsynopsis{
+      char $*$astChrSub( const char $*$test, const char $*$pattern,
+                       const char $*$subs[], int nsub )
+   }
+   \sstparameters{
+      \sstsubsection{
+         test
+      }{
+         The string to be tested.
+      }
+      \sstsubsection{
+         pattern
+      }{
+         The template string. See \texttt{"} Template Syntax:\texttt{"}  below.
+      }
+      \sstsubsection{
+         subs
+      }{
+         An array of strings that are to replace the sections of the test
+         string that match each parenthesised sub-string in \texttt{"} pattern\texttt{"} . The
+         first element of \texttt{"} subs\texttt{"}  replaces the part of the test string that
+         matches the first parenthesised sub-string in the template, etc.
+
+         If \texttt{"} nsub\texttt{"}  is zero, then the \texttt{"} subs\texttt{"}  pointer is ignored. In this
+         case, substitution strings may be specified by appended them to
+         the end of the \texttt{"} pattern\texttt{"}  string, separated by \texttt{"} =\texttt{"}  characters.
+         Note, if you need to include a literal \texttt{"} =\texttt{"}  character in the
+         pattern, precede it by an escape \texttt{"} $\backslash$\texttt{"}  character.
+      }
+      \sstsubsection{
+         nsub
+      }{
+         The number of substitution strings supplied in array \texttt{"} subs\texttt{"} .
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astChrSub()
+      }{
+         A pointer to a dynamically allocated string holding the result
+         of the substitutions, or NULL if the test string does not match
+         the template string. This string should be freed using \htmlref{astFree}{astFree}
+         when no longer needed. If no substituions are specified then a
+         copy of the test string is returned if it matches the template.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A NULL pointer is returned if this function is invoked with the
+         global error status set or if it should fail for any reason, or if
+         the supplied test string does not match the template.
+      }
+   }
+   \sstdiytopic{
+      Template Syntax
+   }{
+      The template syntax is a minimal form of regular expression, The
+      quantifiers allowed are \texttt{"} $*$\texttt{"} , \texttt{"} ?\texttt{"} , \texttt{"} $+$\texttt{"} , \texttt{"} \{n\}\texttt{"} , \texttt{"} $*$?\texttt{"}  and \texttt{"} $+$?\texttt{"}  (the
+      last two are non-greedy - they match the minimum length possible
+      that still gives an overall match to the template). The only
+      constraints allowed are \texttt{"} $\wedge$\texttt{"}  and \texttt{"} \$\texttt{"} . The following atoms are allowed:
+
+      \sstitemlist{
+
+         \sstitem
+          [chars]: Matches any of the specified characters.
+
+         \sstitem
+          [$\wedge$chars]: Matches anything but the specified characters.
+
+         \sstitem
+          .: Matches any single character.
+
+         \sstitem
+          x: Matches the character x so long as x has no other significance.
+
+         \sstitem
+          $\backslash$x: Always matches the character x (except for [dDsSwW]).
+
+         \sstitem
+          $\backslash$d: Matches a single digit.
+
+         \sstitem
+          $\backslash$D: Matches anything but a single digit.
+
+         \sstitem
+          $\backslash$w: Matches any alphanumeric character, and \texttt{"} \_\texttt{"} .
+
+         \sstitem
+          $\backslash$W: Matches anything but alphanumeric characters, and \texttt{"} \_\texttt{"} .
+
+         \sstitem
+          $\backslash$s: Matches white space.
+
+         \sstitem
+          $\backslash$S: Matches anything but white space.
+
+      }
+      Note, minus signs (\texttt{"} -\texttt{"} ) within brackets have no special significance,
+      so ranges of characters must be specified explicitly.
+
+      Multiple template strings can be concatenated, using the \texttt{"} $|$\texttt{"}
+      character to separate them. The test string is compared against
+      each one in turn until a match is found.
+
+      Parentheses are used within each template to identify sub-strings
+      that are to be replaced by the strings supplied in \texttt{"} sub\texttt{"} .
+
+      If \texttt{"} nsub\texttt{"}  is supplied as zero, then substitution strings may be
+      specified by appended them to the end of the \texttt{"} pattern\texttt{"}  string,
+      separated by \texttt{"} =\texttt{"}  characters. If \texttt{"} nsub\texttt{"}  is not zero, then any
+      substitution strings appended to the end of \texttt{"} pattern\texttt{"}  are ignored.
+
+      Each element of \texttt{"} subs\texttt{"}
+      may contain a reference to a token of the
+      form \texttt{"} \$1\texttt{"} , \texttt{"} \$2\texttt{"} , etc. The \texttt{"} \$1\texttt{"}  token will be replaced by the part
+      of the test string that matched the first parenthesised sub-string
+      in \texttt{"} pattern\texttt{"} . The \texttt{"} \$2\texttt{"}  token will be replaced by the part of the
+      test string that matched the second parenthesised sub-string in
+      \texttt{"} pattern\texttt{"} , etc.
+   }
+}
+\sstroutine{
+   astChrTrunc
+}{
+   Terminate a string to exclude trailing spaces
+}{
+   \sstdescription{
+      This function pokes a null character into the supplied string to
+      remove any trailing spaces.
+   }
+   \sstsynopsis{
+      void astChrTrunc( char $*$text )
+   }
+   \sstparameters{
+      \sstsubsection{
+         text
+      }{
+         The string to be truncated.
+      }
+   }
+}
+\sstroutine{
+   astFree
+}{
+   Free previously allocated memory
+}{
+   \sstdescription{
+      This function frees memory that has previouly been dynamically
+      allocated using one of the AST memory function.
+   }
+   \sstsynopsis{
+      void $*$astFree( void $*$ptr )
+   }
+   \sstparameters{
+      \sstsubsection{
+         ptr
+      }{
+         Pointer to previously allocated memory. An error will result
+         if the memory has not previously been allocated by another
+         function in this module. However, a NULL pointer value is
+         accepted (without error) as indicating that no memory has yet
+         been allocated, so that no action is required.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astFree()
+      }{
+         Always returns a NULL pointer.
+      }
+   }
+}
+\sstroutine{
+   astFreeDouble
+}{
+   Free previously double allocated memory
+}{
+   \sstdescription{
+      This function frees memory that has previouly been dynamically
+      allocated using one of the AST memory function. It assumes that
+      the supplied pointer is a pointer to an array of pointers. Each
+      of these pointers is first freed, and then the supplied pointer
+      is freed.
+
+      Note, this routine should not be used with arrays allocated
+      by \htmlref{astGrow}{astGrow} since astGrow over-allocates and so there may be
+      non-initialised pointers at the end of the array.
+   }
+   \sstsynopsis{
+      void $*$astFreeDouble( void $*$ptr )
+   }
+   \sstparameters{
+      \sstsubsection{
+         ptr
+      }{
+         Pointer to previously allocated memory. An error will result
+         if the memory has not previously been allocated by another
+         function in this module. However, a NULL pointer value is
+         accepted (without error) as indicating that no memory has yet
+         been allocated, so that no action is required.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astFreeDouble()
+      }{
+         Always returns a NULL pointer.
+      }
+   }
+}
+\sstroutine{
+   astGrow
+}{
+   Allocate memory for an adjustable array
+}{
+   \sstdescription{
+      This function allocates memory in which to store an array of
+      data whose eventual size is unknown. It should be invoked
+      whenever a new array size is determined and will appropriately
+      increase the amount of memory allocated when necessary. In
+      general, it will over-allocate in anticipation of future growth
+      so that the amount of memory does not need adjusting on every
+      invocation.
+   }
+   \sstsynopsis{
+      void $*$astGrow( void $*$ptr, int n, size\_t size )
+   }
+   \sstparameters{
+      \sstsubsection{
+         ptr
+      }{
+         Pointer to previously allocated memory (or NULL if none has
+         yet been allocated).
+      }
+      \sstsubsection{
+         n
+      }{
+         Number of array elements to be stored (may be zero).
+      }
+      \sstsubsection{
+         size
+      }{
+         The size of each array element.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astGrow()
+      }{
+         If the memory was allocated successfully, a pointer to the start
+         of the possibly new memory region is returned (this may be the
+         same as the original pointer).
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          When new memory is allocated, the existing contents are preserved.
+
+         \sstitem
+          This function does not free memory once it is allocated, so
+         the size allocated grows to accommodate the maximum size of the
+         array (or \texttt{"} high water mark\texttt{"} ). Other memory handling routines may
+         be used to free the memory (or alter its size) if necessary.
+
+         \sstitem
+          If this function is invoked with the global error status set,
+         or if it fails for any reason, the original pointer value is
+         returned and the memory contents are unchanged.
+      }
+   }
+}
+\sstroutine{
+   astIsDynamic
+}{
+   Returns a flag indicating if memory was allocated dynamically
+}{
+   \sstdescription{
+      This function takes a pointer to a region of memory and tests if
+      the memory has previously been dynamically allocated using other
+      functions from this module. It does this by checking for the
+      presence of a \texttt{"} magic\texttt{"}  number in the header which precedes the
+      allocated memory. If the magic number is not present (or the
+      pointer is invalid for any other reason), zero is returned.
+      Otherwise 1 is returned.
+   }
+   \sstsynopsis{
+      int astIsDynamic\_( const void $*$ptr )
+   }
+   \sstparameters{
+      \sstsubsection{
+         ptr
+      }{
+         Pointer to test.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astIsDynamic()
+      }{
+         Non-zero if the memory was allocated dynamically. Zero is returned
+         if the supplied pointer is NULL.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A value of zero is returned if this function is invoked with
+         the global error status set, or if it fails for any reason.
+      }
+   }
+}
+\sstroutine{
+   astMalloc
+}{
+   Allocate memory
+}{
+   \sstdescription{
+      This function allocates memory in a similar manner to the
+      standard C \texttt{"} malloc\texttt{"}  function, but with improved security
+      (against memory leaks, etc.) and with error reporting. It also
+      allows zero-sized memory allocation (without error), resulting
+      in a NULL returned pointer value.
+   }
+   \sstsynopsis{
+      void $*$astMalloc( size\_t size )
+   }
+   \sstparameters{
+      \sstsubsection{
+         size
+      }{
+         The size of the memory region required (may be zero).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astMalloc()
+      }{
+         If successful, the function returns a pointer to the start of
+         the allocated memory region. If the size allocated is zero, this
+         will be a NULL pointer.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A pointer value of NULL is returned if this function is
+         invoked with the global error status set or if it fails for any
+         reason.
+      }
+   }
+}
+\sstroutine{
+   astMemCaching
+}{
+   Controls whether allocated but unused memory is cached in this module
+}{
+   \sstdescription{
+      This function sets a flag indicating if allocated but unused memory
+      should be cached or not. It also returns the original value of the
+      flag.
+
+      If caching is switched on or off as a result of this call, then the
+      current contents of the cache are discarded.
+
+      Note, each thread has a separate cache. Calling this function
+      affects only the currently executing thread.
+   }
+   \sstsynopsis{
+      int astMemCaching( int newval )
+   }
+   \sstparameters{
+      \sstsubsection{
+         newval
+      }{
+         The new value for the MemoryCaching tuning parameter (see
+         \htmlref{astTune}{astTune} in objectc.c). If AST\_\_TUNULL is supplied, the current
+         value is left unchanged.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astMemCaching()
+      }{
+         The original value of the MemoryCaching tuning parameter.
+      }
+   }
+}
+\sstroutine{
+   astRealloc
+}{
+   Change the size of a dynamically allocated region of memory
+}{
+   \sstdescription{
+      This function changes the size of a dynamically allocated region
+      of memory, preserving its contents up to the minimum of the old
+      and new sizes. This may involve copying the contents to a new
+      location, so a new pointer is returned (and the old memory freed
+      if necessary).
+
+      This function is similar to the standard C \texttt{"} realloc\texttt{"}  function
+      except that it provides better security against programming
+      errors and also supports the allocation of zero-size memory
+      regions (indicated by a NULL pointer).
+   }
+   \sstsynopsis{
+      void $*$astRealloc( void $*$ptr, size\_t size )
+   }
+   \sstparameters{
+      \sstsubsection{
+         ptr
+      }{
+         Pointer to previously allocated memory (or NULL if the
+         previous size of the allocated memory was zero).
+      }
+      \sstsubsection{
+         size
+      }{
+         New size required for the memory region. This may be zero, in
+         which case a NULL pointer is returned (no error results). It
+         should not be negative.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astRealloc()
+      }{
+         If the memory was reallocated successfully, a pointer to the
+         start of the new memory region is returned (this may be the same
+         as the original pointer). If size was given as zero, a NULL
+         pointer is returned.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          If this function is invoked with the error status set, or if
+         it fails for any reason, the original pointer value is returned
+         and the memory contents are unchanged. Note that this behaviour
+         differs from that of the standard C \texttt{"} realloc\texttt{"}  function which
+         returns NULL if it fails.
+      }
+   }
+}
+\sstroutine{
+   astRemoveLeadingBlanks
+}{
+   Remove any leading white space from a string
+}{
+   \sstdescription{
+      This function moves characters in the supplied string to the left
+      in order to remove any leading white space.
+   }
+   \sstsynopsis{
+      void astRemoveLeadingBlanks( char $*$string )
+   }
+   \sstparameters{
+      \sstsubsection{
+         string
+      }{
+         Pointer to the string.
+      }
+   }
+}
+\sstroutine{
+   astSizeOf
+}{
+   Determine the size of a dynamically allocated region of memory
+}{
+   \sstdescription{
+      This function returns the size of a region of dynamically
+      allocated memory.
+   }
+   \sstsynopsis{
+      size\_t astSizeOf( const void $*$ptr )
+   }
+   \sstparameters{
+      \sstsubsection{
+         ptr
+      }{
+         Pointer to dynamically allocated memory (or NULL if the size
+         of the allocated memory was zero).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astSizeOf()
+      }{
+         The allocated size. This will be zero if a NULL pointer was
+         supplied (no error will result).
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A value of zero is returned if this function is invoked with
+         the global error status set, or if it fails for any reason.
+      }
+   }
+}
+\sstroutine{
+   astStore
+}{
+   Store data in dynamically allocated memory
+}{
+   \sstdescription{
+      This function stores data in dynamically allocated memory,
+      allocating the memory (or adjusting the size of previously
+      allocated memory) to match the amount of data to be stored.
+   }
+   \sstsynopsis{
+      void $*$astStore( void $*$ptr, const void $*$data, size\_t size )
+   }
+   \sstparameters{
+      \sstsubsection{
+         ptr
+      }{
+         Pointer to previously allocated memory (or NULL if none has
+         yet been allocated).
+      }
+      \sstsubsection{
+         data
+      }{
+         Pointer to the start of the data to be stored. This may be
+         given as NULL if there are no data, in which case it will be
+         ignored and this function behaves like \htmlref{astRealloc}{astRealloc}, preserving
+         the existing memory contents.
+      }
+      \sstsubsection{
+         size
+      }{
+         The total size of the data to be stored and/or the size of
+         memory to be allocated. This may be zero, in which case the
+         data parameter is ignored, any previously-allocated memory is
+         freed and a NULL pointer is returned.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astStore()
+      }{
+         If the data were stored successfully, a pointer to the start of
+         the possibly new memory region is returned (this may be the same
+         as the original pointer). If size was given as zero, a NULL
+         pointer is returned.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          This is a convenience function for use when storing data of
+         arbitrary size in memory which is to be allocated
+         dynamically. It is appropriate when the size of the data will
+         not change frequently because the size of the memory region will
+         be adjusted to fit the data on every invocation.
+
+         \sstitem
+          If this function is invoked with the error status set, or if
+         it fails for any reason, the original pointer value is returned
+         and the memory contents are unchanged.
+      }
+   }
+}
+\sstroutine{
+   astString
+}{
+   Create a C string from an array of characters
+}{
+   \sstdescription{
+      This function allocates memory to hold a C string and fills the
+      string with the sequence of characters supplied. It then
+      terminates the string with a null character and returns a
+      pointer to its start. The memory used for the string may later
+      be de-allocated using \htmlref{astFree}{astFree}.
+
+      This function is intended for constructing null terminated C
+      strings from arrays of characters which are not null terminated,
+      such as when importing a character argument from a Fortran 77
+      program.
+   }
+   \sstsynopsis{
+      char $*$astString( const char $*$chars, int nchars )
+   }
+   \sstparameters{
+      \sstsubsection{
+         chars
+      }{
+         Pointer to the array of characters to be used to fill the string.
+      }
+      \sstsubsection{
+         nchars
+      }{
+         The number of characters in the array (zero or more).
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astString()
+      }{
+         If successful, the function returns a pointer to the start of
+         the allocated string. If the number of characters is zero, a
+         zero-length string is still allocated and a pointer to it is
+         returned.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A pointer value of NULL is returned if this function is
+         invoked with the global error status set or if it fails for any
+         reason.
+      }
+   }
+}
+\sstroutine{
+   astStringArray
+}{
+   Create an array of C strings from an array of characters
+}{
+   \sstdescription{
+      This function turns an array of fixed-length character data into
+      a dynamicllay allocated array of null-terminated C strings with
+      an index array that may be used to access them.
+
+      The array of character data supplied is assumed to hold \texttt{"} nel\texttt{"}
+      adjacent fixed-length strings (without terminating nulls), each
+      of length \texttt{"} len\texttt{"}  characters. This function allocates memory and
+      creates a null-terminated copy of each of these strings. It also
+      creates an array of \texttt{"} nel\texttt{"}  pointers which point at the start of
+      each of these new strings. A pointer to this index array is
+      returned.
+
+      The memory used is allocated in a single block and should later
+      be de-allocated using \htmlref{astFree}{astFree}.
+   }
+   \sstsynopsis{
+      char $*$$*$astStringArray( const char $*$chars, int nel, int len )
+   }
+   \sstparameters{
+      \sstsubsection{
+         chars
+      }{
+         Pointer to the array of input characters. The number of characters
+         in this array should be at least equal to (nel $*$ len).
+      }
+      \sstsubsection{
+         nel
+      }{
+         The number of fixed-length strings in the input character
+         array. This may be zero but should not be negative.
+      }
+      \sstsubsection{
+         len
+      }{
+         The number of characters in each fixed-length input
+         string. This may be zero but should not be negative.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astStringArray()
+      }{
+         A pointer to the start of the index array, which contains \texttt{"} nel\texttt{"}
+         pointers pointing at the start of each null-terminated output
+         string.
+
+         The returned pointer should be passed to astFree to de-allocate
+         the memory used when it is no longer required. This will free
+         both the index array and the memory used by the strings it
+         points at.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A NULL pointer will also be returned if the value of \texttt{"} nel\texttt{"}  is
+         zero, in which case no memory is allocated.
+
+         \sstitem
+          A pointer value of NULL will also be returned if this function
+         is invoked with the global error status set or if it fails for
+         any reason.
+      }
+   }
+}
+\sstroutine{
+   astStringCase
+}{
+   Convert a string to upper or lower case
+}{
+   \sstdescription{
+      This function converts a supplied string to upper or lower case,
+      storing the result in dynamically allocated memory. The \htmlref{astChrCase}{astChrCase}
+      function is similar, but stores the result in a supplied buffer.
+   }
+   \sstsynopsis{
+      char $*$astStringCase( const char string, int upper )
+   }
+   \sstparameters{
+      \sstsubsection{
+         string
+      }{
+         Pointer to the null terminated string to be converted.
+      }
+      \sstsubsection{
+         upper
+      }{
+         If non-zero, the string is converted to upper case. Otherwise it
+         is converted to lower case.
+      }
+   }
+   \sstreturnedvalue{
+      \sstsubsection{
+         astStringCase()
+      }{
+         If successful, the function returns a pointer to the start of
+         the allocated string. The returned memory should be freed using
+         \htmlref{astFree}{astFree} when no longer needed.
+      }
+   }
+   \sstnotes{
+      \sstitemlist{
+
+         \sstitem
+          A pointer value of NULL is returned if this function is
+         invoked with the global error status set or if it fails for any
+         reason.
+      }
+   }
+}
+\normalsize
+
+\newpage
+\section{\xlabel{FitsWcsCoverage}\label{ss:fitswcscoverage}FITS-WCS Coverage}
+
+This appendix gives details of the \htmlref{FitsChan}{FitsChan} class
+implementation of the conventions described in the FITS-WCS papers
+available at
+\url{http://fits.gsfc.nasa.gov/fits_wcs.html}. These conventions are
+used only if the \htmlref{Encoding}{Encoding} attribute of the FitsChan
+has the value ``FITS-WCS'' (whether set explicitly or defaulted). It
+should always be possible for a \htmlref{FrameSet}{FrameSet} to be read
+(using the
+\htmlref{astRead}{astRead}
+function) from a FitsChan containing a header which conforms to these
+conventions. However, only those FrameSets which are compatible with the
+FITS-WCS model can be \emph{written} to a FitsChan using the
+\htmlref{astWrite}{astWrite}
+function. For instance, if the current \htmlref{Frame}{Frame} of a
+FrameSet is re-mapped using, say, an arbitrary \htmlref{MathMap}{MathMap}
+then the FrameSet will no longer be compatible with the FITS-WCS model,
+and so will not be written out successfully to a FitsChan.
+
+The following sub-sections describe the details of the implementation of
+each of the first four FITS-WCS papers. Here, the term ``pixel axes'' is
+used to refer to the FITS pixel coordinates (i.e. the centre of the
+first image pixel has a value 1.0 on each pixel axis); the term ``IWC
+axes'' is used to refer to the axes of the Intermediate World Coordinate
+system; and the term ``WCS axes'' is used to refer to the axes of the final
+physical coordinate system described by the CTYPE\emph{i} keywords.
+
+\subsection{Paper I - General Linear Coordinates}
+When reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan}, these conventions are used if the CTYPE\emph{i} keyword
+values within the FitsChan do not conform to the conventions described in
+later papers, in which case the axes are assumed to be linear. When
+writing a FrameSet to a FitsChan, these conventions are used for axes
+which are described by a simple \htmlref{Frame}{Frame} (\emph{i.e.} not a
+\htmlref{SkyFrame}{SkyFrame}, \htmlref{SpecFrame}{SpecFrame}, \emph{etc.}).
+
+\htmlref{Table}{Table} \ref{tab:fitspaper1} describes the use made by AST of each keyword
+defined by FITS-WCS paper I.
+
+\begin{table}[htbp]
+\begin{tabular}{|l|p{2.5in}|p{2.5in}|}
+\hline
+\multicolumn{1}{|c|}{\textbf{Keyword}} & \multicolumn{1}{c|}{\textbf{Read}}
+& \multicolumn{1}{c|}{\textbf{Write}} \\ \hline
+
+\fitskey{WCSAXES\emph{a}}{Ignored.}{Set to the number of axes in the WCS
+Frame - only written if different to NAXIS.}
+
+\fitskey{CRVAL\emph{ia}}{Used to create the pixel to WCS
+\htmlref{Mapping}{Mapping}.}{Always written (see ``Choice of Reference
+Point'' below).}
+
+\fitskey{CRPIX\emph{ja}}{Used to create the pixel to WCS Mapping.}{Always
+written (see ``Choice of Reference Point'' below).}
+
+\fitskey{CDELT\emph{ia}}{Used to create the pixel to WCS Mapping.}{Only
+written if the \htmlref{CDMatrix}{CDMatrix} attribute of the FitsChan is
+set to zero.}
+
+\fitskey{CROTA\emph{i}}{Used to create the pixel to WCS Mapping.}{Only
+written in FITS-AIPS and FITS-AIPS++ encodings.}
+
+\fitskey{CTYPE\emph{ia}}{Used to choose the class and attributes of the
+WCS Frame, and to create the pixel to WCS Mapping (note, ``STOKES'' and
+``COMPLEX'' axes are treated as unknown linear axes).}{Always written
+(see ``Use and Choice of CTYPE keywords'' below).}
+
+\fitskey{CUNIT\emph{ia}}{Used to set the Units attributes
+of the WCS Frame.}{Only written if the Units attribute of the WCS Frame
+has been set explicitly. If so, the Units value for each axis is used as
+the CUNIT value.}
+
+\fitskey{PC\emph{i\_j}\emph{a}}{Used to create the pixel to WCS
+Mapping.}{Only written if the CDMatrix attribute of the FitsChan is set to
+zero.}
+
+\fitskey{CD\emph{i\_j}\emph{a}}{Used to create the pixel to WCS
+Mapping.}{Only written if the CDMatrix attribute of the FitsChan is set to
+a non-zero value.}
+
+\fitskey{PV\emph{i\_ma}}{Ignored for linear axes.}{Not written if the axes
+are linear.}
+
+\fitskey{PS\emph{i\_ma}}{Ignored.}{Not used.}
+
+\fitskey{WCSNAME\emph{a}}{Used to set the \htmlref{Domain}{Domain} attribute
+of the WCS Frame.}{Only written if the Domain attribute of the WCS Frame
+has been set explicitly. If so, the Domain value is used as the WCSNAME
+value.}
+
+\fitskey{CRDER\emph{ia}}{Ignored.}{Not used.}
+
+\fitskey{CSYER\emph{ia}}{Ignored.}{Not used.}
+
+\hline
+\end{tabular}
+\vspace{3.mm}
+\caption{Use of FITS-WCS Paper I keywords}
+\label{tab:fitspaper1}
+\end{table}
+
+\subsubsection{Requirements for a Successful Write Operation}
+When writing a \htmlref{FrameSet}{FrameSet} in which the WCS
+\htmlref{Frame}{Frame} is a simple Frame to a \htmlref{FitsChan}{FitsChan},
+success depends on the \htmlref{Mapping}{Mapping} from pixel coordinates
+(the base Frame in the FrameSet) to the WCS Frame being linear. The write
+operation will fail if this is not the case.
+
+\subsubsection{Use and Choice of CTYPE\emph{i} keywords}
+When reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan} the CTYPE\emph{i} values in the FitsChan are used to set the
+Symbol attributes of the corresponding WCS \htmlref{Frame}{Frame}. The Label attributes of the WCS Frame are set from
+the CNAME\emph{i} keywords, if present in the header. Otherwise they are set
+from the CTYPE\emph{i} comments strings in the header, so long as each
+axis has a unique non-blank comment. Otherwise, the Label attributes are
+set to the CTYPE\emph{i} values. The above procedure is over-ridden if
+the axis types conform to the conventions described in paper II or III,
+as described below.
+
+When writing a FrameSet to a FitsChan, each CTYPE\emph{i} value is set to
+the value of the Symbol attribute of the corresponding axis in the Frame
+being written. If a value has been set explicitly for the axis Label
+attribute, it is used as the axis comment (except that any existing
+comments in the FitsChan take precedence if the keyword value has not
+changed). The above procedure is over-ridden if the Frame is a
+\htmlref{SkyFrame}{SkyFrame} or a \htmlref{SpecFrame}{SpecFrame}, in which
+case the CTYPE\emph{i} value is derived from the \htmlref{System}{System}
+attribute of the Frame and the nature of the pixel to WCS \htmlref{Mapping}{Mapping}
+according to the conventions of papers II and III, as described below.
+
+\subsubsection{Choice of Reference Point}
+When writing a \htmlref{FrameSet}{FrameSet} to a
+\htmlref{FitsChan}{FitsChan}, the pixel coordinates of the
+reference point for linear axes (i.e. the CRPIX\emph{j} values) are
+chosen as follows:
+
+\begin{itemize}
+\item If the FrameSet is being written to a FitsChan which previously
+contained a set of axis descriptions with the same identifying letter,
+then the previous CRVAL\emph{j}values are converted into the coordinate system
+of the \htmlref{Frame}{Frame} being written (if possible). These values are then
+transformed into the pixel Frame, and the closest integer pixel values
+are used as the CRPIX keywords.
+\item If the above step could not be performed for any reason, the
+central pixel is used as the reference point. This requires the image
+dimensions to be present in the FitsChan in the form of a set of
+NAXIS\emph{j} keyword values.
+\item If both the above two steps failed for any axis, then the pixel
+reference position is set to a value of 1.0 on the pixel axis.
+\end{itemize}
+
+The pixel to WCS \htmlref{Mapping}{Mapping} is then used to find the corresponding
+CRVAL\emph{j}values.
+
+Again, the above procedure is over-ridden if the Frame is a
+\htmlref{SkyFrame}{SkyFrame} or a \htmlref{SpecFrame}{SpecFrame}, in which
+case the conventions of papers II and III are used as described below.
+
+
+\subsubsection{Choice of Axis Ordering}
+When reading a \htmlref{FrameSet}{FrameSet} from a
+\htmlref{FitsChan}{FitsChan}, WCS axis $i$ in the current
+\htmlref{Frame}{Frame} of the
+resulting FrameSet corresponds to axis $i$ in the FITS header.
+
+When writing a FrameSet to a FitsChan, the axis ordering for the FITS
+header is chosen to make the CD\emph{i\_j} or PC\emph{i\_j} matrix
+predominately diagonal. This means that the axis numbering in the FITS
+header will not necessarily be the same as that in the AST Frame.
+
+\subsubsection{Alternate Axis Descriptions}
+When reading a \htmlref{FrameSet}{FrameSet} from a
+\htmlref{FitsChan}{FitsChan} which contains alternate axis descriptions,
+each complete set of axis descriptions results in a single \htmlref{Frame}{Frame} being added
+to the final FrameSet, connected via an appropriate
+\htmlref{Mapping}{Mapping} to the base pixel Frame. The \htmlref{Ident}{Ident} attribute of the Frame is set to hold the single alphabetical
+character which is used to identify the set of axis descriptions within
+the FITS header (a single space is used for the primary axis descriptions).
+
+When writing a FrameSet to a FitsChan, it is assumed that the base Frame
+represents pixel coordinates, and the current Frame represents the
+primary axis descriptions. If there are any other Frames present in the
+FrameSet, an attempt is made to create a complete set of ``alternate''
+set of keywords describing each additional Frame. The first character in
+the Ident attribute of the Frame is used as the single character
+descriptor to be appended to the keyword, with the proviso that a given
+character can only be used once. If a second Frame is found with an Ident
+attribute which has already been used, its Ident attribute is ignored and
+the next free character is used instead. Note, failure to write a set of
+alternate axis descriptions does not result in failure of the entire
+write operation: the primary axis descriptions are still written,
+together with any other alternate axis descriptions which can be produced
+successfully.
+
+\subsection{Paper II - Celestial Coordinates}
+These conventions are used when reading a \htmlref{FrameSet}{FrameSet}
+from a \htmlref{FitsChan}{FitsChan} containing appropriate CTYPE\emph{i}
+values, and when writing a FrameSet in which the WCS \htmlref{Frame}{Frame}
+is a \htmlref{SkyFrame}{SkyFrame}.
+
+\htmlref{Table}{Table} \ref{tab:fitspaper2} describes the use made by AST of each keyword
+whose meaning is defined or extended by FITS-WCS paper II.
+
+\begin{table}[htbp]
+\begin{tabular}{|l|p{2.5in}|p{2.5in}|}
+\hline
+\multicolumn{1}{|c|}{\textbf{Keyword}} & \multicolumn{1}{c|}{\textbf{Read}}
+& \multicolumn{1}{c|}{\textbf{Write}} \\ \hline
+
+\fitskey{CTYPE\emph{ia}}{All coordinate systems and projection types
+listed in paper II are supported (note, ``CUBEFACE'' axes are treated as
+unknown linear axes). In addition, "-HPX" (HEALPix) and "-XPH" (polar
+HEALPix) are supported.}{Determined by the \htmlref{System}{System} attribute
+of the SkyFrame and the \htmlref{WcsType}{WcsType} attribute of the
+\htmlref{WcsMap}{WcsMap} within the FrameSet.}
+
+\fitskey{CUNIT\emph{ia}}{Ignored (assumed to be 'degrees').}{Not written.}
+
+\fitskey{PV\emph{i\_ma}}{Used to create the pixel to WCS \htmlref{Mapping}{Mapping} (values
+are stored as attributes of a WcsMap within this Mapping).}{Values are
+obtained from the WcsMap in the pixel to WCS Mapping.}
+
+\fitskey{LONPOLE\emph{a}}{Used to create the pixel to WCS Mapping. Also
+stored as a \htmlref{PVi\_m}{PVi\_m} attribute for the longitude axis of the WcsMap.}{Only
+written if not equal to the default value defined in paper II (see
+``Choice of LONPOLE/LATPOLE'' below).}
+
+\fitskey{LATPOLE\emph{a}}{Used to create the pixel to WCS Mapping. Also
+stored as a PV attribute for the longitude axis of the WcsMap.}{Only
+written if not equal to the default value defined in paper II (see
+``Choice of LONPOLE/LATPOLE'' below).}
+
+\fitskey{RADESYS\emph{a}}{Used to set the attributes of the SkyFrame. All
+values supported except that ecliptic coordinates are currently always
+assumed to be FK5.}{Always written. Determined by the System attribute of
+the SkyFrame.}
+
+\fitskey{EQUINOX\emph{a}}{Used to set the \htmlref{Equinox}{Equinox} attribute
+of the SkyFrame.}{Written if relevant. Determined by the Equinox attribute of
+the SkyFrame.}
+
+\fitskey{EPOCH}{Used to set the Equinox attribute of the SkyFrame.}{Only
+written if using FITS-AIPS and FITS-AIPS++ encodings. Determined by the Equinox attribute
+of the SkyFrame.}
+
+\fitskey{MJD-OBS}{Used to set the \htmlref{Epoch}{Epoch} attribute of the
+SkyFrame. DATE-OBS is used if MJD-OBS is not present. A default value based on
+RADESYS and EQUINOX is used if used if DATE-OBS is not present
+either.}{Determined by the Epoch attribute of the SkyFrame. Only written
+if this attribute has been set to an explicit value (in which case
+DATE-OBS is also written).}
+
+\hline
+\end{tabular}
+\vspace{3.mm}
+\caption{Use of FITS-WCS Paper II keywords}
+\label{tab:fitspaper2}
+\end{table}
+
+\subsubsection{Requirements for a Successful Write Operation}
+When writing a \htmlref{FrameSet}{FrameSet} in which the WCS
+\htmlref{Frame}{Frame} is a \htmlref{SkyFrame}{SkyFrame} to a
+\htmlref{FitsChan}{FitsChan}, success depends on the following conditions
+being met:
+
+\begin{enumerate}
+\item The \htmlref{Mapping}{Mapping} from pixel coordinates (the base Frame
+in the FrameSet) to the WCS SkyFrame includes a \htmlref{WcsMap}{WcsMap}.
+\item The Mapping prior to the WcsMap (\emph{i.e.} from pixel to IWC) is linear.
+\item The Mapping after the WcsMap (\emph{i.e.} from native spherical to
+celestial coordinates) is a spherical rotation for the
+celestial axes, and linear for any other axes.
+\item The \htmlref{TabOK}{TabOK} attribute is set to a non-zero positive value in the FitsChan,
+and the longitude and latitude axes are separable. In this case the Mapping will
+be described by a pair of 1-dimensional look-up tables, using the ``-TAB''
+algorithm described in FITS-WCS paper III.
+\end{enumerate}
+
+If none of the above conditions hold, the write operation will be
+unsuccessful.
+
+\subsubsection{Choice of LONPOLE/LATPOLE}
+When writing a \htmlref{FrameSet}{FrameSet} to a \htmlref{FitsChan}{FitsChan},
+the choice of LONPOLE and LATPOLE values is determined as follows:
+
+\begin{enumerate}
+
+\item If the projection represented by the \htmlref{WcsMap}{WcsMap} is
+azimuthal, then any values set for attributes ``PV\emph{i}\_3''
+and ``PV\emph{i}\_4'' (where ``\emph{i}'' is the index of the longitude axis)
+within the WcsMap are used as the LONPOLE and LATPOLE values. Reading a
+FrameSet from a FITS-WCS header
+results in the original LONPOLE and LATPOLE values being stored within a
+WcsMap within the FrameSet. Consequently, if a FrameSet is read from a
+FITS-WCS header and it is subsequently written out to a new FITS-WCS
+header, the original LONPOLE and LATPOLE values will usually be used in
+the new header (the exception being if the WcsMap has been explicitly
+modified before being written out again). Any extra rotation of the sky
+is absorbed into the CD\emph{i\_j} or PC\emph{i\_j} matrix (this is
+possible only if the projection is azimuthal).
+
+\item If the projection represented by the WcsMap is azimuthal but no
+values have been set for the ``PV\emph{i}\_3'' and ``PV\emph{i}\_4''
+attributes within the WcsMap, then the default LONPOLE and LATPOLE values
+are used. This results in no LONPOLE or LATPOLE keywords being stored in
+the header since default values are never stored. Any extra rotation of
+the sky is absorbed into the CD\emph{i\_j} or PC\emph{i\_j} matrix (this
+is possible only if the projection is azimuthal).
+
+\item If the projection represented by the WcsMap is not azimuthal,
+then the values of LONPOLE and LATPOLE are found by transforming the
+coordinates of the celestial north pole (\emph{i.e} longitude zero,
+latitude $+\pi/2$) into native spherical coordinates using the inverse of
+the \htmlref{Mapping}{Mapping} which follows the WcsMap.
+
+\end{enumerate}
+
+\subsubsection{User Defined Fiducial Points}
+When reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan}, projection parameters
+PV\emph{i}\_0, PV\emph{i}\_1 and PV\emph{i}\_2 (for longitude axis
+``\emph{i}'') are used to indicate a user-defined fiducial point as
+described in section 2.5 of paper II. This results in a shift of IWC
+origin being applied \emph{before} the \htmlref{WcsMap}{WcsMap} which converts
+IWC into
+native spherical coordinates. The values of these projection parameters,
+if supplied, are stored as the corresponding \htmlref{PVi\_m}{PVi\_m} attributes
+of the WcsMap.
+
+When writing a FrameSet to a FitsChan, the PV attributes of the WcsMap
+determine the native coordinates of the fiducial point (the fixed
+defaults for each projection described in paper II are used if the PV
+attributes of the WcsMap have not been assigned a value). The
+corresponding celestial coordinates are used as the CRVAL\emph{i}
+keywords and the corresponding pixel coordinates as the CRPIX\emph{j}
+keywords.
+
+\subsubsection{Common Non-Standard Features}
+A collection of common non-standard features are supported when reading a
+\htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan}, in addition
+to those embodied within the
+available encodings of the FitsChan class. These are translated into the
+equivalent standard features before being used to create a FrameSet.
+Note, the reverse operation is never performed: it is not possible to
+produce non-standard features when writing a FrameSet to a FitsChan
+(other than those embodied in the available encodings of the FitsChan
+class). The supported non-standard features include:
+
+\begin{itemize}
+\item EQUINOX keywords with string values equal to a date preceded
+by the letter B or J (\emph{e.g.} ``B1995.0'').
+
+\item EQUINOX or EPOCH keywords with value zero  (these are converted to
+B1950).
+
+\item The IRAF ``ZPX'' projection is represented by a
+\htmlref{WcsMap}{WcsMap} with type of
+AST\_\_ZPN. \htmlref{Projection}{Projection} parameter values are read from any WAT\emph{i\_nnn}
+keywords, and corresponding \htmlref{PVi\_m}{PVi\_m} attributes are set in the
+WcsMap. The WAT\emph{i\_nnn} keywords may specify corrections to the basic
+ZPN projection by including ``lngcor'' or ``latcor'' terms. These are
+supported if they use half cross-terms, in either simple or Chebyshev
+representation.
+
+\item The IRAF ``TNX'' projection is represented by a WcsMap with type of
+AST\_\_TPN (a distorted TAN projection retained within the WcsMap class
+from an early draft of the FITS-WCS paper II). Projection parameter values
+are read from any WAT\emph{i\_nnn} keywords, and corresponding PV
+attributes are set in the WcsMap. If the TNX projection cannot be
+converted exactly into an AST\_\_TPN projection, ASTWARN keywords are
+added to the FitsChan containing a warning message (but only if the
+\htmlref{Warnings}{Warnings} attribute of the FitsChan is set appropriately). Currently,
+TNX projections that use half cross-terms, in either simple or Chebyshev
+representation, are supported.
+
+\item ``QV'' parameters for TAN projections (as produced by
+\xref{AUTOASTROM}{sun242}{}
+\footnote{\url{http://www.astro.gla.ac.uk/users/norman/star/autoastrom/}}
+are renamed to the equivalent ``PV'' parameters.
+
+\item TAN projections that have associated ``PV'' parameters on the
+latitude axis are converted to the corresponding TPN (distorted TAN)
+projections. This conversion can be controlled using the \htmlref{PolyTan}{PolyTan} attribute
+of the FitsChan class.
+
+\end{itemize}
+
+\subsection{Paper III - Spectral Coordinates}
+These conventions are used when reading a \htmlref{FrameSet}{FrameSet}
+from a \htmlref{FitsChan}{FitsChan} which includes appropriate
+CTYPE\emph{i} values, and when writing a FrameSet in which
+the WCS \htmlref{Frame}{Frame} is a \htmlref{SpecFrame}{SpecFrame}.
+
+\htmlref{Table}{Table} \ref{tab:fitspaper3} describes the use made by AST of each keyword
+whose meaning is defined or extended by FITS-WCS paper III.
+
+\begin{table}[htbp]
+\begin{footnotesize}
+\begin{tabular}{|l|p{2.5in}|p{2.5in}|}
+\hline
+\multicolumn{1}{|c|}{\textbf{Keyword}} & \multicolumn{1}{c|}{\textbf{Read}}
+& \multicolumn{1}{c|}{\textbf{Write}} \\ \hline
+
+\fitskey{CTYPE\emph{ia}}{All coordinate systems and projection types
+listed in paper III are supported algorithm (the ``-LOG'' algorithm may
+also be applied to non-spectral linear axes; the ``-TAB'' algorithm
+requires the \htmlref{TabOK}{TabOK} attribute to be set in the FitsChan).}{Determined by the \htmlref{System}{System} attribute of the
+SpecFrame and the nature of the pixel to SpecFrame
+\htmlref{Mapping}{Mapping}.}
+
+\fitskey{CUNIT\emph{ia}}{Used to set the Units attribute of
+the SpecFrame (note, SpecFrames always have an ``active'' Units attribute
+(see \htmlref{astSetActiveUnit}{astSetActiveUnit}).}{Always written.}
+
+\fitskey{PV\emph{i\_ma}}{Used to create the pixel to WCS Mapping (values
+are stored as attributes of a \htmlref{GrismMap}{GrismMap}).}
+{Set from the attributes of the GrismMap, if present, and if set explicitly.}
+
+\fitskey{SPECSYS\emph{a}}{Used to set the \htmlref{StdOfRest}{StdOfRest}
+attribute of the SpecFrame (all systems are supported except CMBDIPOL).}
+{Set from the StdOfRest attribute of the SpecFrame, but only if it has been
+set explicitly.}
+
+\fitskey{SSYSOBS\emph{a}}{Ignored.}{Never written.}
+
+\fitskey{OBSGEO-X/Y/Z}{Used to set the \htmlref{ObsLon}{ObsLon} and
+\htmlref{ObsLat}{ObsLat} attributes of the Frame (the observers
+height above sea level is ignored).}{Set from the ObsLon and ObsLat
+attributes of the Frame, if they have been set explicitly (it is
+assumed that the observer is at sea level).}
+
+\fitskey{MJD-AVG}{Used to set the \htmlref{Epoch}{Epoch} attributes of
+the SpecFrame.}{Set from the Epoch attribute of the SpecFrame, if it has
+been set explicitly.}
+
+\fitskey{SSYSSRC\emph{a}}{Used to set the \htmlref{SourceVRF}{SourceVRF} attribute of the
+SpecFrame
+(all systems are supported except CMBDIPOL).} {Set from the SourceVRF
+attribute of the SpecFrame.}
+
+\fitskey{ZSOURCE\emph{a}}{Used to set the \htmlref{SourceVel}{SourceVel}
+attribute of the SpecFrame (the SourceVRF attribute
+is first set to the system indicated by the SSYSSRC keyword, and the
+ZSOURCE value is then converted to an apparent radial velocity and stored
+as the SourceVel attribute).}
+{Set from the SourceVel attribute of
+the SpecFrame, if it has been set explicitly (the SourceVel value is
+first converted from apparent radial velocity to redshift).}
+
+\fitskey{VELOSYS\emph{a}}{Ignored.}{Set from the attributes of the
+SpecFrame that define the standard of rest and the observers position.}
+
+\fitskey{RESTFRQ\emph{a}}{Used to set the \htmlref{RestFreq}{RestFreq}
+attribute of the SpecFrame.}{Set from the RestFreq attribute of the
+SpecFrame, but only if the System attribute is not set to
+``WAVE'', ``VOPT'', ``ZOPT'' or ``AWAV'', and only if RestFreq has been set
+explicitly.}
+
+\fitskey{RESTWAV\emph{a}}{Used to set the RestFreq
+attribute of the SpecFrame (after conversion from wavelength to frequency).}
+{Set from the RestFreq attribute of the SpecFrame (after conversion), but only if the
+System attribute is set to ``WAVE'', ``VOPT'', ``ZOPT'' or
+``AWAV'', and only if RestFreq has been set explicitly.}
+
+\fitskey{CNAME\emph{ia}}{Used to set the Label attributes of
+the WCS Frame keywords.}{Set from the Label attributes of the WCS Frame,
+if they have been set explicitly.}
+\hline
+\end{tabular}
+\end{footnotesize}
+\vspace{3.mm}
+\caption{Use of FITS-WCS Paper III keywords}
+\label{tab:fitspaper3}
+\end{table}
+
+\subsubsection{Requirements for a Successful Write Operation}
+When writing a \htmlref{FrameSet}{FrameSet} in which the WCS \htmlref{Frame}{Frame} is a \htmlref{SpecFrame}{SpecFrame} to a
+\htmlref{FitsChan}{FitsChan}, the write operation is successful only if
+the \htmlref{Mapping}{Mapping} from pixel coordinates (the base Frame
+in the FrameSet) to the SpecFrame satisfies one of the following conditions:
+
+\begin{enumerate}
+\item It is linear.
+\item It is logarithmic.
+\item It is linear if the SpecFrame were to be re-mapped into one of the
+other spectral systems supported by FITS-WCS paper III.
+\item It contains a \htmlref{GrismMap}{GrismMap}, and the Mapping before the GrismMap (from
+pixel coordinates to grism parameter) is linear, and the Mapping after the
+GrismMap is either null or represents a change of spectral system from wavelength (air or
+vacuum) to one of the supported spectral systems.
+\item The \htmlref{TabOK}{TabOK} attribute is set to a non-zero positive value in the FitsChan.
+\end{enumerate}
+
+If none of the above conditions hold, the write operation will be
+unsuccessful. Note, if the FitsChan's TabOK attribute is set to a positive
+non-zero value then any Mapping that does not meet any of the earlier conditions
+will be written out as a look-up table, using the ``-TAB'' algorithm described
+in FITS-WCS paper III. If the TabOK attribute is to zero (the default) or
+negative in the FitsChan, then the write operation will be unsuccessful unless
+one of the eaerlier conditions is met.\footnote{If the -TAB algorithm is used, the
+positive value of the TabOK attribute is used as the table version number
+(the EXTVER header) in the associated FITS binary table.}
+
+\subsubsection{Common Non-Standard Features}
+The following non-standard features are supported when reading spectral
+axes from a \htmlref{FitsChan}{FitsChan}:
+
+\begin{itemize}
+\item Conversion of ``-WAV'', ``-FRQ'' and ``-VEL'' algorithm codes
+(specified in early drafts of paper III) to the corresponding
+``-X2P'' form.
+\item Conversion of ``RESTFREQ'' to ``RESTFRQ''
+\end{itemize}
+
+\subsection{Paper IV - Coordinate Distortions}
+
+This paper proposes that an additional 4 character code be appended to
+the end of the CTYPE\emph{i} keyword to specify the nature of any
+distortion away from the basic algorithm described by the first 8
+characters of the CTYPE\emph{i} value. Currently AST ignores all such
+codes when reading a \htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan} (except for the ``-SIP'' code
+defined by the Spitzer Space Telescope project - see below). This means that
+a FrameSet can still be read from such headers, but the \htmlref{Mapping}{Mapping} which gives
+the WCS position associated with a given pixel position will reflect only
+the basic algorithm and will not include the effects of the distortion.
+
+If such a FrameSet is then written out to a FitsChan, the resulting
+CTYPE\emph{i} keywords will include no distortion code.
+
+\subsubsection{The ``-SIP'' distortion code}
+
+The Spitzer Space Telescope project
+(\url{http://www.spitzer.caltech.edu/})
+has developed its own system for encoding 2-dimensional image distortion
+within a FITS header, based on the proposals of paper IV. A description
+of this system is available in
+\url{http://ssc.spitzer.caltech.edu/postbcd/doc/shupeADASS.pdf}. In this
+system, the presence of distortion is indicated by appending the
+distortion code ``-SIP'' to the CTYPE\emph{i} keyword values for the
+celestial axes. The distortion takes the form of a polynomial function
+which is applied to the pixel coordinates, after subtraction of the
+CRPIX\emph{j} values.
+
+This system is a strictly 2 dimensional system. When reading a
+\htmlref{FrameSet}{FrameSet} from a \htmlref{FitsChan}{FitsChan} which
+includes the ``-SIP'' distortion code, AST assumes that it
+is only applied to the first 2 WCS axes in a FITS header (i.e.
+CTYPE1 and CTYPE2). If the ``-SIP'' distortion code is attached to other
+axes, it will be ignored. The distortion itself is represented by a
+\htmlref{PolyMap}{PolyMap} within the resulting FrameSet.
+
+If a FrameSet is read from a FitsChan which includes ``-SIP''
+distortion, and an attempt is then made to write this FrameSet out to a
+FitsChan, the write operation will fail unless the distortion is
+insignificant (\emph{i.e.} is so small that the tests for linearity built
+into AST are passed). In this case, no distortion code will be appended to
+the resulting CTYPE\emph{i} keyword values.
+
+\newpage
+\section{\xlabel{changes_and_new_features}\label{ss:changes}Release Notes}
+
+\subsection{Changes Introduced in V1.1}
+
+The following describes the most significant changes which occurred in
+the AST library between versions V1.0 and V1.1 (not the most recent
+version):
+
+\begin{enumerate}
+
+\item A new ``How To\ldots'' section (\secref{ss:howto}) has been
+added to this document. It contains simple recipies for performing
+commonly-required operations using AST.
+
+\item A new \htmlref{astUnformat}{astUnformat} function has been provided to read formatted
+coordinate values for the axes of a \htmlref{Frame}{Frame}
+(\secref{ss:unformattingaxisvalues}). In essence, this function is the
+inverse of \htmlref{astFormat}{astFormat}. It may be used to decode user-supplied formatted
+values representing coordinates, turning them into numerical values
+for processing. Celestial coordinates may also be read using this
+function (\secref{ss:unformattingskyaxisvalues}) and free-format input
+is supported.
+
+\item The Format attribute string used by a \htmlref{SkyFrame}{SkyFrame} when formatting
+celestial coordinate values now allows the degrees/hours field to be
+omitted, so that celestial coordinates may be given in (\emph{e.g.})
+arc-minutes and/or arc-seconds
+(\secref{ss:formattingskyaxisvalues}). As a result, the degrees/hours
+field is no longer included by default.  A new ``t'' format specifier
+has been introduced (see the Format attribute) to allow minutes and/or
+seconds of time to be specified if required.
+
+\item A new function \htmlref{astMapBox}{astMapBox} has been introduced. This allows you to
+find the extent of a ``bounding box'' which just encloses another box
+after it has been transformed by a \htmlref{Mapping}{Mapping}. A typical use might be to
+calculate the size which an image would have if it were transformed by
+the Mapping.
+
+\item A new class of \htmlref{Object}{Object}, the \htmlref{IntraMap}{IntraMap}, has been introduced
+(\secref{ss:intramaps}). This is a specialised form of Mapping which
+encapsulates a privately-defined coordinate transformation function
+(\emph{e.g.}\ written in C) so that it may be used like any other AST
+Mapping. This allows you to create Mappings that perform any
+conceivable coordinate transformation.
+
+\item The internal integrity of a \htmlref{FrameSet}{FrameSet} is now automatically
+preserved whenever changes are made to any attributes which affect the
+current Frame (either by setting or clearing their values). This is
+accomplished by appropriately re-mapping the current Frame to account
+for any change to the coordinate system which it represents
+(\secref{ss:framesetintegrity}).
+
+\item The internal structure of a FrameSet is now automatically tidied
+to eliminate redundant nodes whenever any of its Frames is removed or
+re-mapped. Automatic simplification of any compound Mappings which
+result may also occur. The effect of this change is to prevent the
+accumulation of unnecessary structure in FrameSets which are
+repeatedly modified.
+
+\item Some improvements have been made to the algorithms for
+simplifying compound Mappings, as used by \htmlref{astSimplify}{astSimplify}.
+
+\item The textual representation used for some Objects
+(\emph{i.e.}\ when they are written to a \htmlref{Channel}{Channel}) has changed
+slightly, but remains compatible with earlier versions of AST.
+
+\item Interfaces to the internal functions and macros used by AST for
+handling memory and error conditions are now provided \emph{via} the
+``ast.h'' header file. This is for the benefit of those writing
+(\emph{e.g.}) new graphics interfaces for AST.
+
+\item A problem has been fixed which could result when using \htmlref{astRead}{astRead}
+to read FITS headers in which the CDELT value is zero. Previously,
+this could produce a Mapping whose inverse transformation was not
+defined and this could unnecessarily restrict the use to which it
+could be put. The problem has been overcome by supplying a suitable
+small CDELT value for FITS axes which have only a single pixel.
+
+\item A bug has been fixed which could occasionally cause a \htmlref{MatrixMap}{MatrixMap}
+to be used with the wrong \htmlref{Invert}{Invert} attribute value when it forms part of
+a compound Mapping which is being simplified using astSimplify.
+
+
+\item A problem has been fixed which could prevent tick marks being
+drawn on a coordinate axis close to a singularity in the coordinate
+system.
+\end{enumerate}
+
+\subsection{Changes Introduced in V1.2}
+
+The following describes the most significant changes which occurred in
+the AST library between versions V1.1 and V1.2 (not the most recent
+version):
+
+\begin{enumerate}
+\item A new function, \htmlref{astPolyCurve}{astPolyCurve}, has been introduced to allow more
+efficient plotting of multiple geodesic curves
+(\secref{ss:plottinggeodesics}).
+
+\item A new set of functions, \htmlref{astResample$<$X$>$}{astResample$<$X$>$}, has been introduced
+to perform resampling of gridded data such as images
+(\emph{i.e.}\ re-gridding) under the control of a geometrical
+transformation specified by a \htmlref{Mapping}{Mapping}.
+
+\item The command-line options ``$-$pgp'' and ``$-$pgplot'', which
+were previously synonymous when used with the ``\htmlref{ast\_link}{ast\_link}'' and
+``\htmlref{ast\_link\_adam}{ast\_link\_adam}'' commands, are no longer synonymous. The option
+``$-$pgp'' now causes linking with the Starlink version of PGPLOT
+(which uses GKS to generate its output), while ``$-$pgplot'' links
+with the standard (or ``native'') version of PGPLOT.
+
+\item The function \htmlref{astMapBox}{astMapBox} has been changed to execute more quickly,
+although this has been achieved at the cost of some loss of robustness
+when used with difficult Mappings.
+
+\item A new value of ``FITS-IRAF'' has been introduced for the
+\htmlref{Encoding}{Encoding} attribute of a \htmlref{FitsChan}{FitsChan}. This new encoding provides an
+interim solution to the problem of storing coordinate system
+information in FITS headers, until the proposed new FITS-WCS standard
+becomes stable.
+
+\item When a \htmlref{FrameSet}{FrameSet} is created from a set of FITS header cards (by
+reading from a FitsChan using a ``foreign'' encoding), the base \htmlref{Frame}{Frame}
+of the resulting FrameSet now has its \htmlref{Domain}{Domain} attribute set to
+``GRID''. This reflects the fact that this Frame represents FITS data
+grid coordinates (equivalent to FITS pixel coordinates---see
+\secref{ss:domainconventions}). Previously, this Domain value was not
+set.
+
+\item \htmlref{astFindFits}{astFindFits} now ignores trailing spaces in its keyword template.
+
+\item \htmlref{astPutFits}{astPutFits} now recognises ``D'' and ``d'' as valid exponent
+characters in floating point numbers.
+
+\item The FitsChan class is now more tolerant of common minor
+violations of the FITS standard.
+
+\item The FitsChan class now incorporates an improved test for the
+linearity of Mappings, allowing more reliable conversion of AST data
+into FITS (using ``foreign'' FITS encodings).
+
+\item Some further improvements have been made to the algorithms for
+simplifying compound Mappings, as used by \htmlref{astSimplify}{astSimplify}.
+
+\item A new \htmlref{UnitRadius}{UnitRadius} attribute has been added to the \htmlref{SphMap}{SphMap}
+class. This allows improved simplification of compound Mappings
+(CmpMaps) involving SphMaps and typically improves performance when
+handling FITS world coordinate information.
+
+\item A \htmlref{MatrixMap}{MatrixMap} no longer propagates input coordinate values of
+AST\_\_BAD automatically to all output coordinates. If certain output
+coordinates do not depend on the affected input coordinate(s) because
+the relevant matrix elements are zero, then they may now remain valid.
+
+\item A minor bug has been corrected which could cause certain
+projections which involve half the celestial sphere to produce valid
+coordinates for the other (unprojected) half of the sphere as well.
+
+\item A bug has been fixed which could occasionally cause \htmlref{astConvert}{astConvert}
+to think that conversion between a \htmlref{CmpFrame}{CmpFrame} and another Frame was
+possible when, in fact, it wasn't.
+\end{enumerate}
+
+\subsection{Changes Introduced in V1.3}
+
+The following describes the most significant changes which occurred in
+the AST library between versions V1.2 and V1.3 (not the most recent
+version):
+
+\begin{enumerate}
+\item A new set of functions, \htmlref{astResample$<$X$>$}{astResample$<$X$>$}, has been introduced to
+provide	efficient resampling of gridded data, such as spectra and
+images, under the control of a geometrical transformation specified by
+a \htmlref{Mapping}{Mapping}. A variety of sub-pixel interpolation schemes are supported.
+
+\item A new class, \htmlref{PcdMap}{PcdMap}, has been introduced. This is a specialised
+form of Mapping which implements 2-dimensional pincushion or barrel
+distortion.
+
+\item A bug has been fixed which could cause a \htmlref{FitsChan}{FitsChan} to produce too
+many digits when formatting floating point values for inclusion in a
+FITS header if the numerical value was in the range -0.00099999\ldots
+to -0.0001.
+
+\item A bug has been fixed which could cause a FitsChan to lose the
+comment associated with a string value in a FITS header.
+
+\item A FitsChan now reports an error if it reads a FITS header which
+identifies a non-standard sky projection (previously, this was
+accepted without error and a Cartesian projection used instead).
+
+\item A bug has been fixed which could prevent conversion between the
+coordinate systems represented by two CmpFrames. This could only occur
+if the CmpFrames contained a relatively large number of nested Frames.
+
+%\item A bug has been fixed which could cause a program to crash if
+%FrameSets were nested inside each other (for example, if one \htmlref{FrameSet}{FrameSet}
+%had another FrameSet added to it for use as a \htmlref{Frame}{Frame} or Mapping). The
+%problem could only occur if the nested structure was loaded from a data
+%c+
+%file (using \htmlref{astRead}{astRead}).
+%c-
+%f+
+%file (using AST\_READ).
+%f-
+%
+\item Further improvements have been made to the simplification of
+compound Mappings, including fixes for several bugs which could cause
+indefinite looping or unwanted error messages.
+
+\item Some memory leaks have been fixed.
+
+\item A small number of documentation errors have been corrected.
+\end{enumerate}
+
+\subsection{Changes Introduced in V1.4}
+
+The following describes the most significant changes which have occurred
+in the AST library between versions V1.3 and V1.4 (not the most recent
+version):
+
+\begin{enumerate}
+\item A new \htmlref{MathMap}{MathMap} class has been introduced. This is a form of
+\htmlref{Mapping}{Mapping} that allows you to define coordinate transformations in a
+flexible and transportable way using arithmetic operations and
+mathematical functions similar to those available in C.
+
+\item {\bf{WARNING---INCOMPATIBLE CHANGE.}} Transformation functions
+used with the \htmlref{IntraMap}{IntraMap} class (see, for example, \htmlref{astIntraReg}{astIntraReg}) now
+require a ``this'' pointer as their first parameter. \textbf{Existing
+implementations will not continue to work correctly with this version
+of AST unless this parameter is added.} There is no need for existing
+software to make use of this pointer, but it must be present.
+
+This change has been introduced so that transformation functions can gain
+access to IntraMap attributes.
+
+\item A new \htmlref{IntraFlag}{IntraFlag} attribute has been added to the IntraMap
+class. This allows the transformation functions used by IntraMaps to
+adapt to produce the required transformation on a per-IntraMap basis
+(\secref{ss:intraflag}).
+
+\item The \htmlref{Plot}{Plot} attributes MajTickLen and MinTickLen, which control the
+length of major and minor tick marks on coordinate axes, may now be
+subscripted using an axis number. This allows tick marks of different
+lengths to be used on each axis. It also allows tick marks to be
+suppressed on one axis only by setting the length to zero.
+
+\item The value of the Plot attribute NumLab, which controls the
+plotting of numerical labels on coordinate axes, no longer has any
+effect on whether labelling of a coordinate grid is interior or
+exterior (as controlled by the \htmlref{Labelling}{Labelling} attribute).
+
+\item The \htmlref{FitsChan}{FitsChan} class now provides some support for the
+IRAF-specific ``ZPX'' sky projection, which is converted transparently
+into the equivalent FITS ``ZPN'' projection (see the description of the
+\htmlref{Encoding}{Encoding} attribute for details).
+
+\item The FitsChan class now recognises the coordinate system ``ICRS''
+(International Celestial Reference \htmlref{System}{System}) as equivalent to
+``FK5''. This is an interim measure and full support for the
+(exceedingly small) difference between ICRS and FK5 will be added at a
+future release.
+
+Note that ``ICRS'' is not yet recognised as a coordinate system by other
+classes such as \htmlref{SkyFrame}{SkyFrame}, so this change only facilitates the
+importation of foreign data.
+
+\item A bug in the FitsChan class has been fixed which could result in
+longitude values being incorrect by 180 degrees when using cylindrical
+sky projections, such as the FITS ``CAR'' projection.
+
+\item A bug in the FitsChan class has been fixed which could result in
+the FITS sky projection parameters ProjP(0) to ProjP(9) being
+incorrectly named PROJP1 to PROJP10 when written out as FITS cards.
+
+\item A bug in the FitsChan class has been fixed which could cause
+confusion between the FITS-IRAF and FITS-WCS encoding schemes if both
+a CD matrix and a PC matrix are erroneously present in a FITS header.
+
+\item Some minor memory leaks have been fixed.
+
+\item A small number of documentation errors have been corrected.
+\end{enumerate}
+
+\subsection{Changes Introduced in V1.5}
+
+The following describes the most significant changes which have
+occurred in the AST library between versions V1.4 and V1.5 (not the most
+recent version):
+
+\begin{enumerate}
+
+\item The \htmlref{FitsChan}{FitsChan} class has been modified to support the latest draft
+FITS WCS standard, described in the two papers ``Representation of world
+coordinates in FITS'' (E.W.\,Greisen and M.\,Calabretta, dated 30th
+November, 1999), and ``Representation of celestial coordinates in FITS''
+(M.\,Calabretta and E.W.\,Greisen, dated 24th September, 1999). These are
+available at
+\url{http://www.cv.nrao.edu/fits/documents/wcs/wcs.html}.
+
+The FITS-WCS encoding now uses these updated conventions. The main
+changes are:
+
+\begin{itemize}
+\item Rotation and scaling of pixel axes is now represented by a matrix
+of \texttt{CDj\_i} keywords instead of a combination of \texttt{PCjjjiii} and
+\texttt{CDELTj} keywords.
+\item \htmlref{Projection}{Projection} parameters are now associated with particular axes and
+are represented by \texttt{\htmlref{PVi\_m}{PVi\_m}} keywords instead of the \texttt{PROJPm}
+keywords.
+\item The tangent plane projection (``TAN'') can now include optional
+polynomial correction terms.
+\item An entire set of keywords must be supplied for each set of secondary
+axis descriptions, and each such keyword must finish with a single
+character indicating which set it belongs to. This means that keywords
+which previously occupied eight characters have been shorten to seven to
+leave room for this extra character. Thus \texttt{LONGPOLE} has become \texttt{LONPOLE} and \texttt{RADECSYS} has become \texttt{RADESYS}.
+\end{itemize}
+
+\item Two new encodings have been added to the FitsChan class:
+\begin{description}
+
+\item [FITS-PC] This encoding uses the conventions of the now superseded
+FITS WCS paper by E.W.\,Greisen and M.\,Calabretta which used keywords
+\texttt{CDELTj} and \texttt{PCjjjiii} to describe axis scaling and rotation.
+These are the conventions which were used by the FITS-WCS encoding prior
+to version 1.5 of AST. This encoding is provided to allow existing data
+which use these conventions to be read. It should not in general be used
+to create new data.
+
+\item [FITS-AIPS] This encoding is based on the conventions described in the
+document ``Non-linear Coordinate Systems in AIPS'' by Eric W. Greisen
+(revised 9th September, 1994 and available by ftp from fits.cv.nrao.edu
+/fits/documents/wcs/aips27.ps.Z). This encoding uses \texttt{CROTAi} and
+\texttt{CDELTi} keywords to describe axis rotation and scaling.
+
+\end{description}
+
+\item The FitsChan class now provides some support for the IRAF-specific
+``TNX'' sky projection, which is converted transparently into the
+equivalent FITS ``TAN'' projection (see the description of the \htmlref{Encoding}{Encoding}
+attribute for details).
+
+\item FrameSets originally read from a DSS encoded FITS header can now be
+written out using the FITS-WCS encoding (a TAN projection with correction
+terms will be used) in addition to the DSS encoding. The reverse is also
+possible: FrameSets originally read from a FITS-WCS encoded FITS header
+and which use a TAN projection can now be written out using the DSS
+encoding.
+
+\item The algorithm used by the FitsChan class to verify that a \htmlref{FrameSet}{FrameSet}
+conforms to the FITS-WCS model has been improved so that FrameSets
+including more complex mixtures of parallel and serial Mappings
+can be written out using the FITS-WCS encoding.
+
+\item The FitsChan class has been changed so that long strings included in
+the description of an \htmlref{Object}{Object} can be saved and restored without truncation
+when using the NATIVE encoding. Previously, very long \htmlref{Frame}{Frame} titles,
+mathematical expressions, \emph{etc.} were truncated if they exceeded the
+capacity of a single FITS header card. They are now split over several
+header cards so that they can be restored without truncation. Note, this
+facility is only available when using NATIVE encoding.
+
+\item The FitsChan class has a new attribute called \htmlref{Warnings}{Warnings} which
+can be used to select potentially dangerous conditions under which
+warnings should be issued. These conditions include (for instance)
+unsupported features within non-standard projections, missing keywords
+for which default values will be used, \emph{etc}.
+
+\item The \htmlref{WcsMap}{WcsMap} class has been changed to support the changes made to the
+FITS-WCS encoding in the FitsChan class:
+\begin{itemize}
+\item Projection parameters are now associated with a particular axis and
+are specified using a new set of attributes called PVj\_m. Here, ``j'' is
+the index of an axis of WcsMap, and ``m'' is the index of the projection
+parameter.
+\item The old attributes ProjP(0) to ProjP(9) are still available but are
+now deprecated in favour of the new PVj\_m attributes. They are interpreted
+as aliases for PV(axlat)\_0 to PV(axlat)\_9, where ``axlat'' is the index of
+the latitude axis.
+\item The GLS projection projection has been renamed as SFL, but the
+AST\_\_GLS type has been retained as an alias for AST\_\_SFL.
+\end{itemize}
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V1.6}
+
+The following describes the most significant changes which have
+occurred in the AST library between versions V1.5 and V1.6:
+
+\begin{enumerate}
+
+\item The C interface to several methods (\htmlref{astTranN}{astTranN}, \htmlref{astMark}{astMark} and
+\htmlref{astPolyCurve}{astPolyCurve}) have been changed to make them easier to call from C++.
+Parameters which previously had type ``double (*)[]'' have been changed
+to the simpler ``double *''. Using the old types may result in non-fatal
+compiler warnings, but should not change the behaviour of the methods.
+
+\item A bug has been fixed in the \htmlref{Plot}{Plot} class which could cause groups
+of tick marks to be skipped when using very small gaps.
+
+\item A bug has been fixed in the Plot class which could cause axes to be
+labeled outside the visible window, resulting in no axes being visible.
+
+\item The FITS-WCS encoding used by the \htmlref{FitsChan}{FitsChan} class now includes the
+WCSNAME keyword. When creating a \htmlref{FrameSet}{FrameSet} from FITS headers, the values of
+the WCSNAME keywords are now used as the \htmlref{Domain}{Domain} names for the corresponding
+Frames in the returned FrameSet. When writing a FrameSet to a FITS header
+the Domain names of each \htmlref{Frame}{Frame} are stored in WCSNAME keywords in the
+header.
+
+\item The FITS-WCS encoding used by the FitsChan class now attempts to
+retain the identification letter associated with multiple axis
+descriptions. When reading a FrameSet from a FITS header, the identification
+letter is stored in the \htmlref{Ident}{Ident} attribute for each Frame. When writing a
+FrameSet to a FITS header, the identification letter is read from the
+Ident attribute of each Frame. The letter to associate with each Frame
+can be changed by assigning a new value to the Frame's Ident attribute.
+
+\item The FITS-WCS, FITS-PC, FITS-IRAF and FITS-AIPS encodings used by the
+FitsChan class now create a \htmlref{SkyFrame}{SkyFrame} with the \htmlref{System}{System} attribute set to
+``Unknown'' if the CTYPE keywords in the supplied header refers to an
+unknown celestial coordinate system. Previously, a Frame was used instead
+of a SkyFrame.
+
+\item The FITS-WCS, FITS-PC, FITS-IRAF and FITS-AIPS encodings used by the
+FitsChan class no longer report an error if the FITS header contains no
+CTYPE keywords. It is assumed that a missing CTYPE keyword implies that
+the world coordinate system is linear and identically equal to
+``intermediate world coordinates''.
+
+\item The new value ``noctype'' is now recognized by the \htmlref{Warnings}{Warnings} attribute
+of the FitsChan class. This value causes warnings to be issued if CTYPE
+keywords are missing from foreign encodings.
+
+\item A new attribute called \htmlref{AllWarnings}{AllWarnings} has been added to the FitsChan
+class. This is a read-only, space separated list of all the known condition
+names which can be specified in the Warnings attribute.
+
+\item The FitsChan class now attempts to assigns a \htmlref{Title}{Title} to each Frame in
+a FrameSet read using a foreign encoding. The Title is based on the Domain
+name of the Frame. If the Frame has no Domain name, the default Title
+supplied by the Frame class is retained.
+
+\item The FitsChan class uses the comments associated with CTYPE
+keywords as axis labels when reading a foreign encoding. This behaviour
+has been modified so that the default labels provided by the Frame class
+are retained (instead of using the CTYPE comments) if any of the CTYPE
+comments are identical.
+
+\item A new ``interpolation'' scheme identified by the symbolic constant
+AST\_\_BLOCKAVE has been added to the AST\_RESAMPLE$<$X$>$ set of
+functions. The new scheme calculates each output pixel value by finding
+the mean of the input pixels in a box centred on the output pixel.
+
+\item The SkyFrame class can now be used to represent an arbitrary spherical
+coordinate system by setting its System attribute to ``Unknown''.
+
+\item The indices of the latitude and longitude axes of a SkyFrame can
+now be found using new read-only attributes \htmlref{LatAxis}{LatAxis} and \htmlref{LonAxis}{LonAxis}. The
+effects of any axis permutation is taken into account.
+
+\item A new attribute called Ident has been added to the \htmlref{Object}{Object} class.
+This serves the same purpose as the existing \htmlref{ID}{ID} attribute, but (unlike ID)
+its value is transferred to the new Object when a copy is made.
+
+\item A bug has been fixed which could prevent complex CmpFrames
+behaving correctly (for instance, resulting in the failure of attempts
+to find a \htmlref{Mapping}{Mapping} between a \htmlref{CmpFrame}{CmpFrame} and itself).
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V1.7}
+
+The following describes the most significant changes which have
+occurred in the AST library between versions V1.6 and V1.7:
+
+\begin{enumerate}
+
+\item The \htmlref{Frame}{Frame} class has a new method called
+\htmlref{astAngle}{astAngle}
+which returns the angle subtended by two points at a third point within a
+2 or 3 dimensional Frame.
+
+\item The Frame class has a new method called
+\htmlref{astOffset2}{astOffset2}
+which calculates a position which is offset away from a given starting
+point by a specified distance along a geodesic curve which passes
+through the starting point at a given position angle. It can only be used
+with 2-dimensional Frames.
+
+\item The Frame class has a new method called
+\htmlref{astAxDistance}{astAxDistance}
+which returns the increment between two supplied axis values. For
+axes belonging to SkyFrames, the returned value is normalized into
+the range $\pm\pi$.
+
+\item The Frame class has a new method called
+\htmlref{astAxOffset}{astAxOffset}
+which returns an axis value a given increment away from a specified axis
+value. For axes belonging to SkyFrames, the returned value is normalized into
+the range $\pm\pi$ (for latitude axes) or zero to $2\pi$ (for longitude
+axes).
+
+\item The \htmlref{Plot}{Plot} class has a new method called
+\htmlref{astGenCurve}{astGenCurve}
+which allows generalised user-defined curves to be drawn. The curve is
+defined by a user-supplied \htmlref{Mapping}{Mapping} which maps distance along the curve
+into the corresponding position in the current Frame of the Plot. The new
+method then maps these current Frame position into graphics coordinates,
+taking care of any non-linearities or discontinuities in the mapping.
+
+\item The Plot class has a new method called
+\htmlref{astGrfSet}{astGrfSet}
+which allows the underlying primitive graphics functions to be selected
+at run-time. Previously, the functions used by the Plot class to produce
+graphics could only be selected at link-time, using the options of the
+\htmlref{ast\_link}{ast\_link} command. The new Plot method allows an application to over-ride
+the functions established at link-time, by specifying alternative
+primitive graphics routines. In addition, the two new Plot methods
+\htmlref{astGrfPush}{astGrfPush} and \htmlref{astGrfPop}{astGrfPop}
+allow the current graphics routines to be saved and restore on a
+first-in-last-out stack, allowing temporary changes to be made to the set
+of registered graphics routines.
+
+\item The DrawAxes attribute of the Plot class can now be specified
+independantly for each axis, by appending the axis index to the
+end of the attribute name.
+
+\item A bug has been fixed in the Plot class which could result in axis
+labels being drawn on inappropriate edges of the plotting box when using
+``interior'' labelling.
+
+\item A bug has been fixed in the \htmlref{IntraMap}{IntraMap} class which could cause IntraMaps
+to be corrupted after transforming any points.
+
+\item Bugs have been fixed in the \htmlref{FitsChan}{FitsChan} class which could cause
+inappropriate ordering of headers within a FitsChan when writing or
+reading objects using NATIVE encodings.
+
+\item A bug has been fixed in the FitsChan class which could cause the
+celestial longitude of a pixel to be estimated incorrectly by 180 degrees
+if the reference point is at either the north or the south pole.
+
+\end{enumerate}
+
+
+\subsection{Changes Introduced in V1.8-2}
+
+The following describes the most significant changes which have
+occurred in the AST library between versions V1.7 and V1.8-2:
+
+\begin{enumerate}
+
+\item The \htmlref{SkyFrame}{SkyFrame} class has a new attribute called \htmlref{NegLon}{NegLon} which allows
+   longitude values to be displayed in the range $-\pi$ to $+\pi$, instead
+   of the usual range zero to $2.\pi$.
+
+\item Some new
+functions (\htmlref{astAngle}{astAngle}, \htmlref{astAxAngle}{astAxAngle}, \htmlref{astResolve}{astResolve}, \htmlref{astOffset2}{astOffset2}, \htmlref{astAxOffset}{astAxOffset},
+\htmlref{astAxDistance}{astAxDistance})
+have been added to the \htmlref{Frame}{Frame} class to allow navigation of the coordinate space
+to be performed without needing to know the underlying geometry
+of the co-ordinate system (for instance, whether it is Cartesian or
+spherical).
+
+Note, version 1.8-1 contained many of these facilities, but
+some have been changed in version 1.8-2. Particularly, positions angles
+are now referred to the second Frame axis for \emph{all} classes of Frames
+(including SkyFrames), and the
+astBear function has been replaced by astAxAngle.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V1.8-3}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V1.8-2 and V1.8-3:
+
+\begin{enumerate}
+
+\item A new method called \htmlref{astDecompose}{astDecompose} has been added to the \htmlref{Mapping}{Mapping} class
+which enables pointers to be obtained to the component parts of \htmlref{CmpMap}{CmpMap} and
+\htmlref{CmpFrame}{CmpFrame} objects.
+
+\item Functions within proj.c and wcstrig.c have been renamed to avoid name
+clashes with functions in more recent versions of Mark Calabretta's wcslib
+library.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V1.8-4}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V1.8-3 and V1.8-4:
+
+\begin{enumerate}
+
+\item The \htmlref{FitsChan}{FitsChan} class has a new attribute called \htmlref{DefB1950}{DefB1950} which can be
+used to select the default reference frame and equinox to be used if
+a FitsChan with foreign encoding contains no indication of the
+reference frame or equinox.
+
+\item A bug has been fixed in the FitsChan class which could prevent
+\htmlref{astWrite}{astWrite} from creating a set of FITS headers from an otherwise valid
+\htmlref{FrameSet}{FrameSet}, when when using FITS-AIPS encoding.
+
+\item A bug has been fixed in the FitsChan class which could cause
+\htmlref{astRead}{astRead} to mis-interpret the FITS CROTA keyword when using FITS-AIPS
+encoding.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V1.8-5}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V1.8-4 and V1.8-5:
+
+\begin{enumerate}
+
+\item The \htmlref{Plot}{Plot} class defines new graphical elements Axis1, Axis2,
+Grid1, Grid2, NumLabs1, NumLabs2, TextLab1, TextLab2, Ticks1 and Ticks2.
+These allow graphical attributes (colour, width, etc) to be set for each
+axis individually. Previously, graphical attributes could only be set for
+both axes together, using graphical elements Axes, \htmlref{Grid}{Grid}, NumLabs,
+TextLabs and Ticks.
+
+\end{enumerate}
+
+
+\subsection{Changes Introduced in V1.8-7}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V1.8-5 and V1.8-7:
+
+\begin{enumerate}
+
+\item A new attribute called \htmlref{CarLin}{CarLin} has been added to the \htmlref{FitsChan}{FitsChan} class
+which controls the way CAR projections are handled when reading a
+\htmlref{FrameSet}{FrameSet} from a non-native FITS header. Some FITS writers use a CAR
+projection to represent a simple linear transformation between pixel
+coordinates and celestial sky coordinates. This is not consistent with
+the definition of the CAR projection in the draft FITS-WCS standard, which
+requires the resultant \htmlref{Mapping}{Mapping} to include a 3D rotation from native
+spherical coordinates to celestial spherical coordinates, thus making the
+Mapping non-linear. Setting CarLin to 1 forces
+\htmlref{astRead}{astRead}
+to ignore the FITS-WCS standard and treat any CAR projections as simple
+linear Mappings from pixel coordinates to celestial coordinates.
+
+\item A bug has been fixed which could result in axis Format attributes
+set by the user being ignored under certain circumstances.
+
+\item A bug in the way tick marks positions are selected in the \htmlref{Plot}{Plot} class
+has been fixed. This bug could result in extra ticks marks being displayed at
+inappropriate positions. This bug manifested itself, for instance, if the
+Mapping represented by the Plot was a simple Cartesian to Polar Mapping.
+In this example, the bug caused tick marks to be drawn at negative radius
+values.
+
+\item A bug has been fixed which could prevent attribute settings from
+being read correctly by
+\htmlref{astSet}{astSet},
+etc., on certain platforms (MacOS, for instance).
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V1.8-8}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V1.8-7 and V1.8-8:
+
+\begin{enumerate}
+
+\item A bug has been fixed in the \htmlref{FitsChan}{FitsChan} class which could cause
+problems when creating a \htmlref{FrameSet}{FrameSet} from a FITS header containing WCS
+information stored in the form of Digitised Digitised Sky Survey (DSS)
+keywords. These problems only occurred for DSS fields in the southern
+hemisphere, and resulted in pixel positions being mapped to sky positions
+close to the corresponding \emph{northern} hemispshere field.
+
+\item A new method called
+\htmlref{astBoundingBox}{astBoundingBox}
+has been added to the \htmlref{Plot}{Plot} class. This method returns the bounding box of
+the previous graphical output produced by a Plot method.
+
+\item A new attribute called \htmlref{Invisible}{Invisible} has been added to the Plot class
+which suppresses the graphical output normally produced by Plot methods.
+All the calculations needed to produce the normal output are still
+performed however, and so the bounding box returned by the new
+astBoundingBox
+method is still usable.
+
+\item Bugs have been fixed related to the appearance of graphical output
+produced by the Plot class. These bugs were to do with the way in which
+graphical elements relating to a specific axis (e.g. \texttt{Colour(axis1)}, etc.)
+interacted with the corresponding generic element (e.g.
+\texttt{Colour(axes)}, etc.).
+
+\end{enumerate}
+
+
+\subsection{Changes Introduced in V1.8-13}
+
+The following describes the most significant changes which occurred
+in the AST library between versions V1.8-8 and V1.8-13:
+
+\begin{enumerate}
+
+\item The \htmlref{FitsChan}{FitsChan} class has been modified so that LONPOLE keywords
+are only produced by \htmlref{astWrite}{astWrite} when necessary. For zenithal projections such as
+TAN, the LONPOLE keyword can always take its default value and so is
+not included in the FITS header produced by astWrite.
+Previously, the unnecessary production of a LONPOLE keyword could prevent
+FrameSets being written out using encodings which do not support the
+LONPOLE keyword (such as FITS-IRAF).
+
+\item The FitsChan class has been modified to retain leading and trailing
+spaces within COMMENT cards.
+
+\item The FitsChan class has been modified to only use CTYPE comments as
+axis labels if all non-celestial axes have unique non-blank comments
+(otherwise the CTYPE keyword values are used as labels).
+
+\item The FitsChan class has been modified so that it does not append a
+trailing ``Z'' character to the end of DATE-OBS keyword values.
+
+\item The FitsChan class has been modified to use latest list of FITS-WCS
+projections, as described in the FITS-WCS paper II, ``Representations of
+celestial coordinates in FITS'' (Calabretta \& Greisen, draft dated 23
+April 2002). Support has been retained for the polynomial correction
+terms which previous drafts have allowed to be associated with TAN
+projections.
+
+\item The \htmlref{WcsMap}{WcsMap} class has additional projection types of AST\_\_TPN
+(which implements a distorted TAN projection) and AST\_\_SZP. The AST\_\_TAN
+projection type now represents a simple TAN projection and has no
+associated projection parameters. In addition, the usage of projection
+parameters has been brought into line with the the FITS-WCS paper II.
+
+\item The WcsMap class has been modified so that a ``get'' operation on a
+projection parameter attribute will return the default value defined in the
+FITS-WCS paper II if no value has been set for the attribute. Previously, a
+value of AST\_\_BAD was returned in such a situation.
+
+\item The \htmlref{Frame}{Frame} class has new attributes \htmlref{Top(axis)}{Top(axis)} and \htmlref{Bottom(axis)}{Bottom(axis)} which
+allow a ``plottable range'' to be specified for each Frame axis. The grid
+produced by the \htmlref{astGrid}{astGrid} method will not extend beyond these limits.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V2.0}
+
+Note, \htmlref{Frame}{Frame} descriptions created using AST V2.0 will not be readable by
+applications linked with earlier versions of AST. This applies to Frame
+descriptions created using:
+\begin{itemize}
+\item the \htmlref{Channel}{Channel} class
+\item the \htmlref{FitsChan}{FitsChan} class if the NATIVE \htmlref{Encoding}{Encoding} is used
+\item the \htmlref{astShow}{astShow} function
+\end{itemize}
+
+Applications must be re-linked with AST V2.0 in order to be able to read
+Frame descriptions created by AST v2.0.
+
+The following describes the most significant changes which have
+occurred in the AST library between versions V1.8-13 and V2.0 (the
+current version):
+
+\begin{enumerate}
+
+\item The default value for the \htmlref{Domain}{Domain} attribute provided by the \htmlref{CmpFrame}{CmpFrame}
+class has been changed from ``CMP'' to a string formed by concatenating
+the Domain attributes of the two component Frames, separated by a minus
+sign. If both component Domains are blank, then the old default of
+``CMP'' is retained for the CmpFrame Domain.
+
+\item The implementation of the
+\htmlref{astWrite}{astWrite} function
+within the FitsChan class has been modified. It will now attempt to
+produce a set of FITS header cards to describe a \htmlref{FrameSet}{FrameSet} even if the
+number of axes in the \htmlref{Current}{Current} Frames is greater than the number in the
+\htmlref{Base}{Base} Frame (that is, if there are more WCS axes than pixel axes). This
+has always been possible with NATIVE encoding, but has not previously
+been possible for foreign encodings. The WCSAXES keyword is used to store
+the number of WCS axes in the FITS header.
+
+\item Another change to the
+astWrite function
+within the FitsChan class is that the ordering of ``foreign'' axes
+(\emph{i.e.} CTYPE keywords) is now chosen to make the CD (or PC) matrix
+as diagonal as possible - any element of axis transposition is removed by
+this re-ordering as recommended in FITS-WCS paper I. Previously the
+ordering was determined by the order of the axes in the Current Frame of
+the supplied FrameSet. This change does not affect NATIVE encoding.
+
+\item Support for spectral coordinate systems has been introduced
+throught the addition of two new classes, \htmlref{SpecFrame}{SpecFrame} and \htmlref{SpecMap}{SpecMap}.
+The SpecFrame is a 1-dimensional Frame which can be used to describe
+positions within an electromagnetic spectrum in various systems
+(wavelength, frequency, various forms of velocity,~\emph{etc.}) and referred
+to various standards of rest (topocentric, geocentric, heliocentric
+LSRK,~\emph{etc.}). The SpecMap is a \htmlref{Mapping}{Mapping} which can transform spectral
+axis values between these various systems and standards of rest. Note,
+FitsChans which have a foreign encoding (\emph{i.e.} any encoding other
+than NATIVE) are not yet able to read or write these new classes.
+
+\item Facilities have been added to the Frame class which allow
+differences in axis units to be taken into account when finding a Mapping
+between two Frames. In previous versions of AST, the Unit attribute was a
+purely descriptive item intended only for human readers - changing the
+value of Unit made no difference to the behaviour of the Frame. As of
+version 2.0, the Unit attribute can influence the nature of the Mappings
+between Frames. For instance, if the
+astFindrame or \htmlref{astConvert}{astConvert}
+method is used to find the Mapping between an \htmlref{Axis}{Axis} with Unit set to ``m''
+and another Axis with Unit set to ``km'', then the method will return a
+\htmlref{ZoomMap}{ZoomMap} which introduces a scaling factor of 0.001 between the two axes.
+These facilities assume that units are specified following the rules
+included in FITS-WCS paper I (\emph{Representation of World
+Coordinates in FITS}, Greisen \& Calabretta).
+
+In order to minimise the risk of breaking existing software, the default
+behaviour for simple Frames is to ignore the Unit attribute (\emph{i.e.}
+to retain the previous behaviour). However, the new Frame method
+\htmlref{astSetActiveUnit}{astSetActiveUnit}
+may be used to ``activate'' (or deactivate) the new facilities within a
+specific Frame. Note, the new SpecFrame class is different to the simple
+Frame class in that the new facilities for handling units are always active
+within a SpecFrame.
+
+\item The \htmlref{System}{System} and \htmlref{Epoch}{Epoch} attributes fo the \htmlref{SkyFrame}{SkyFrame} class have been
+moved to the parent Frame class. This enables all sub-classes of Frame
+(such as the new SpecFrame class) to share these attributes, and to provide
+suitable options for each class.
+
+\item The Frame class has a new attribute called \htmlref{AlignSystem}{AlignSystem}, which allows
+control over the alignment process performed by the methods
+\htmlref{astFindFrame}{astFindFrame} and astConvert.
+
+
+\item The CmpFrame class has been modified so that attributes of a
+component Frame can be accessed without needing to extract the Frame first.
+To do this, append an axis index to the end of the attribute name. For
+instance, if a CmpFrame contains a SpecFrame and a SkyFrame (in that order),
+then the \htmlref{StdOfRest}{StdOfRest} attribute of the SpecFrame can be referred to as the
+``StdOfRest(1)'' attribute of the CmpFrame. Likewise, the \htmlref{Equinox}{Equinox} attribute
+of the SkyFrame can be accessed as the ``Equinox(2)'' (or equivalently
+``Equinox(3)'') attribute of the CmpFrame. The ``System(1)'' attribute of the
+CmpFrame will refer to the System attribute of the SpecFrame, whereas the
+``System(2)'' and ``System(3)'' attributes of the CmpFrame will refer to the
+System attribute of the SkyFrame (the ``System'' attribute without an axis
+specifier will refer to the System attribute of the CmpFrame as a whole,
+since System is an attribute of all Frames, and a CmpFrame is a Frame and
+so has its own System value which is independant of the System attributes
+of its component Frames).
+
+\item The algorithms used by the \htmlref{Plot}{Plot} class for determining when to omit
+overlapping axis labels, and the abbreviation of redundant leading fields
+within sexagesimal axis labels, have been improved to avoid some anomolous
+behaviour in previous versions.
+
+\item The curve drawing algorithm used by the Plot class has been
+modified to reduce the chance of it ``missing'' small curve sections,
+such as may be produced if a grid line cuts across the plot very close to
+a corner. Previously, these missed sections could sometimes result in
+axis labels being omitted.
+
+\item A new function
+(\htmlref{astVersion}{astVersion})
+has been added to return the version of the AST library in use.
+
+\item Bugs have been fixed in the Plot class which caused serious problems
+when plotting high precision data. These problems could range from the
+omission of some tick marks to complete failure to produce a plot.
+
+\end{enumerate}
+
+Programs which are statically linked will need to be re-linked in
+order to take advantage of these new facilities.
+
+
+\subsection{Changes Introduced in V3.0}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V2.0 and V3.0:
+
+\begin{enumerate}
+
+\item Many changes have been made in the \htmlref{FitsChan}{FitsChan} class in order to bring
+the FITS-WCS encoding into line with the current versions of the FITS-WCS
+papers (see
+\url{http://www.atnf.csiro.au/people/mcalabre/WCS/}):
+
+\begin{itemize}
+
+\item The rotation and scaling of the pixel axes may now be specified using
+either CD\emph{i\_j} keywords, or PC\emph{i\_j} and CDELTj keywords. A new attribute
+called \htmlref{CDMatrix}{CDMatrix} has been added to the FitsChan class to indicate which
+set of keywords should be used when writing a \htmlref{FrameSet}{FrameSet} to a FITS-WCS
+header.
+
+\item The FITS-WCS encoding now supports most of the conventions
+described in FITS-WCS paper III for the description of spectral
+coordinates. The exceptions are that the SSYSOBS keyword is not
+supported, and WCS stored in tabular form (as indicated by the ``-TAB''
+algorithm code) is not supported.
+
+
+\item User-specified fiducial points for WCS projections are now
+supported by FitsChans which use FITS-WCS encoding. This use keywords
+PVi\_0, PVi\_1 and PVi\_2 for the longitude axis.
+
+\item  When reading a FITS-WCS header, a FitsChan will now use keywords PVi\_3
+and PVi\_4 for the longitude axis (if present) in preference to any LONPOLE
+and LATPOLE keywords which may be present. When writing a FITS-WCS header,
+both forms are written out.
+
+\item The number of WCS axes is stored in the WCSAXES keyword if its value
+would be different to that of the NAXIS keyword.
+
+\item Helio-ecliptic coordinates are now supported by FitsChans which use
+FITS-WCS encoding. This uses CTYPE codes ``HLON'' and ``HLAT''. The
+resulting \htmlref{SkyFrame}{SkyFrame} will have a \htmlref{System}{System} value of ``HELIOECLIPTIC'', and all
+the usual facilities, such as conversion to other celestial systems, are
+available.
+
+\item The FITS-WCS encoding now supports most of the conventions
+described in FITS-WCS paper III for the description of spectral
+coordinates. The exceptions are that the SSYSOBS keyword is not
+supported, and WCS stored in tabular form (as indicated by the ``-TAB''
+algorithm code) is not supported.
+
+\item When reading a FITS-WCS header, a FitsChan will now ignore any
+distortion codes which are present in CTYPE keywords. Here, a ``distortion
+code'' is the final group of four characters in a CTYPE value of the
+form ``xxxx-yyy-zzz'', as described in FITS-WCS paper IV. The exception
+to this is that the ``-SIP'' distortion code (as used by the Spitzer
+Space Telescope project - see
+\url{http://ssc.spitzer.caltech.edu/postbcd/doc/shupeADASS.pdf}) is
+interpreted correctly and results in a \htmlref{PolyMap}{PolyMap} being used to represent
+the distortion in the resulting FrameSet. Note, ``-SIP'' distortion codes
+can only be read, not written. A FrameSet which uses a PolyMap will not
+in general be able to be written out to a FitsChan using any foreign
+encoding (although NATIVE encoding can of course be used).
+
+\item The \htmlref{Warnings}{Warnings} attribute of the FitsChan class now accepts values
+``BadVal'' (which gives warnings about conversion errors when reading
+FITS keyword values), ``Distortion'' (which gives warnings about
+unsupported distortion codes within CTYPE values), and ``BadMat'' (which
+gives a warning if the rotation/scaling matrix cannot be inverted).
+
+\item When writing a FrameSet to a FitsChan which uses a non-Native
+encoding, the comment associated with any card already in the FitsChan
+will be retained if the keyword value being written is the same as the
+keyword value already in the FitsChan.
+
+\item A FrameSet which uses the non-FITS projection type AST\_\_TPN (a TAN
+projection with polynomial distortion terms) can now be written to a
+FitsChan if the \htmlref{Encoding}{Encoding} attribute is set to FITS-WCS. The standard
+``-TAN'' code is used within the CTYPE values, and the distortion
+coefficients are encoded in keywords of the form `` QVi\_ma'', which are
+directly analogous to the standard ``PVi\_ma'' projection parameter keywords.
+Thus a FITS reader which does not recognise the QV keywords will still
+be able to read the header, but the distortion will be ignored.
+
+\item The default value for \htmlref{DefB1950}{DefB1950} attribute now depends on the value
+of the Encoding attribute.
+
+\item A new appendix has been added to SUN/210 and SUN/211 giving details
+of the implementation provided by the FitsChan class of the
+conventions contained in the first four FITS-WCS papers.
+\end{itemize}
+
+\item The SkyFrame class now supports two new coordinate systems ``ICRS''
+and ``HELIOECLIPTIC''. The default for the System attribute for SkyFrames
+has been changed from ``FK5'' to ``ICRS''.
+
+\item The
+\htmlref{astRate}{astRate}
+function has been added which allows an estimate to be made of the rate of
+change of a \htmlref{Mapping}{Mapping} output with respect to one of the Mapping inputs.
+
+\item All attribute names for Frames of any class may now include an optional
+axis specifier. This includes those attributes which describe a property
+of the whole \htmlref{Frame}{Frame}. For instance, the \htmlref{Domain}{Domain} attribute may now be
+specified as ``Domain(1)'' in addition to the simpler ``Domain''. In cases
+such as this, where the attribute describes a property of the whole
+Frame, axis specifiers will usually be ignored. The exception is that a
+\htmlref{CmpFrame}{CmpFrame} will use the presence of an axis specifier to indicate that the
+attribute name relates to the primary Frame containing the specified
+axis, rather than to the CmpFrame as a whole.
+
+\item A new subclass of Mapping, the PolyMap, has been added which
+performs a general N-dimensional polynomial mapping.
+
+\item A new subclass of Mapping, the \htmlref{GrismMap}{GrismMap}, has been added which
+models the spectral dispersion produced by a grating, prism or grism.
+
+\item A new subclass of Mapping, the \htmlref{ShiftMap}{ShiftMap}, has been added which adds
+constant values onto all coordinates (this is equivalent to a \htmlref{WinMap}{WinMap}
+with unit scaling on all axes).
+
+\item Minor bugs have been fixed within the \htmlref{Plot}{Plot} class to do with the choice
+and placement of numerical axis labels.
+
+\item The \htmlref{SphMap}{SphMap} class has a new attribute called \htmlref{PolarLong}{PolarLong} which gives the
+longitude value to be returned when a Cartesian position corresponding to
+either the north or south pole is transformed into spherical coordinates.
+
+\item The \htmlref{WcsMap}{WcsMap} class now assigns a longitude of zero to output
+celestial coordinates which have a latitude of plus or minus 90 degrees.
+
+\item The \htmlref{NatLat}{NatLat} and \htmlref{NatLon}{NatLon} attributes of the WcsMap class have been
+changed so that they now return the fixed native coordinates of the
+projection reference point, rather than the native coordinates of the
+user-defined fiducial point.
+
+\item Notation has been changed in both the WcsMap and FitsChan classes to
+reflect the convention used in the FITS-WCS papers that index ``i'' refers
+to a world coordinate axis, and index ``j'' refers to a pixel axis.
+
+\item Changes have been made to several Mapping classes in order to allow
+the
+\htmlref{astSimplify}{astSimplify}
+function to make simplifications in a \htmlref{CmpMap}{CmpMap} which previously were not
+possible.
+
+\item The \htmlref{SlaMap}{SlaMap} class has been extended by the addition of conversions
+between FK5 and ICRS coordinates, and between FK5 and helio-ecliptic coordinates.
+
+\item The \htmlref{SpecMap}{SpecMap} class has been changed to use the equation for the
+refractive index of air as given in the current version of FITS-WCS paper
+III. Also, the forward and inverse transformations between frequency and
+air-wavelength have been made more compatible by using an iterative
+procedure to calculate the inverse.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V3.1}
+
+The following describes the most significant changes which have
+occurred in the AST library between versions V3.0 and V3.1 (the
+current version):
+
+\begin{enumerate}
+\item Addition of a new class called \htmlref{XmlChan}{XmlChan} - a \htmlref{Channel}{Channel} which
+reads and writes AST objects in the form of XML.
+\item A bug has been fixed in the \htmlref{Plot}{Plot} class which could cause incorrect
+graphical attributes to be used for various parts of the plot if either
+axis has no tick marks (i.e. if both major and minor tick marks have zero
+length).
+\end{enumerate}
+
+Programs which are statically linked will need to be re-linked in
+order to take advantage of these new facilities.
+
+
+\subsection{Changes Introduced in V3.2}
+
+The following describes the most significant changes which have
+occurred in the AST library between versions V3.1 and V3.2:
+
+\begin{enumerate}
+
+\item A new
+function \htmlref{astPutCards}{astPutCards}
+has been added to the \htmlref{FitsChan}{FitsChan} class. This allows multiple concatenated header
+cards to be stored in a FitsChan in a single call, providing an alternative to
+the existing
+astPutCards function.
+
+\item Some signficant changes have been made to the simplification of Mappings
+ which should resultin a greater degree of simplication taking place.Some
+ bugs have also been fixed which could result in an infinite loop being
+ entered when attempting to simplify certain Mappings.
+
+\item The FitsChan class now translates the spectral algorithm codes
+``-WAV'', ``-FRQ'' and ``-VEL'' (specified in early drafts of paper III) to
+the corresponding ``-X2P'' form when reading a spectral axis description
+from a set of FITS header cards.
+
+\item A bug has been fixed in the FitsChan class which could cause
+keywords associated with alternate axis descriptions to be mis-interpreted.
+
+\item The \htmlref{Plot}{Plot} class now provides facilities for modifying the appearance
+of sub-strings within text strings such as axis labels, titles, \emph{etc},
+by producing super-scripts, sub-scripts, changing the font colour, size,
+\emph{etc}. See attribute \htmlref{Escape}{Escape}.
+
+\item The default value of the \htmlref{Tol}{Tol} attribute of the Plot class has been
+changed from 0.001 to 0.01. This should not usually cause any significant
+visible change to the plot, but should make the plotting faster. You may
+need to set a lower value for Tol if you are producing a particularly
+large plot.
+
+\item The algorithm for finding the default value for the Gap attribute
+has been changed. This attribute specifies the gap between major axis
+values in an annotated grid drawn by the Plot class. The change in
+algorithm may cause the default value to be different to previous versions
+in cirtain circumstances.
+
+\item Some bugs have been fixed in the Plot class which could cause the
+system to hang for a long time while drawing certain all-sky grids
+(notable some of the FITS Quad-cube projections).
+
+\item The \htmlref{SkyAxis}{SkyAxis} class has extended the Format attribute by the addition
+of the ``g'' option. this option is similar to the older ``l'' option in that
+it results in characters (``h'', ``m'', ``s'', \emph{etc}) being used as
+delimiters between the sexagesimal fields of the celestial position. The
+difference is that the ``g'' option includes graphics escape sequences
+in the returned formatted string which result in the field delimiter
+characters being drawn as super-scripts when plotted as numerical axis values
+by a Plot.
+
+\item The Plot class has been extended to include facilities for producing
+logarithmic axes. See attributes LogPlot, LogTicks, LogGap and LogLabel.
+
+\item New functions astGCap and astGScales have been added to the interface
+defined by file \verb+grf.h+. The \htmlref{ast\_link}{ast\_link} command has been modified so
+that the \verb+-mygrf+ switch loads dummy versions of the new grf
+functions. This means that applications should continue to build without
+any change. However, the facilities for interpreting escape sequences
+within strings drawn by the Plot class will not be available unless the
+new grf functions are implemented. If you choose to implement them, you
+should modify your linking procedure to use the \verb+-grf+ switch in
+place of the older \verb+-mygrf+ switch. See the description of the ast\_link
+command for details of the new switches. Also note that the astGQch
+function, whilst included in verb+grf.h+ in pervious versions of AST, was
+not actually called. As of this version of AST, calls are made to the
+astGQch function, and so any bugs in the implementation of astGQch may
+cause spurious behaviour when plotting text strings.
+
+\item A new 'static' method called \htmlref{astEscapes}{astEscapes} has been added which is used
+to control and enquire whether astGetC and \htmlref{astFormat}{astFormat} will strip any graphical
+escape sequences which may be present out of the returned value.
+
+\item New attribute \htmlref{XmlPrefix}{XmlPrefix} has been added to the \htmlref{XmlChan}{XmlChan} class. It
+allows XML written by the XmlChan class to include an explicit namespace
+prefix on each element.
+
+\item New attribute \htmlref{XmlFormat}{XmlFormat} has been added to the XmlChan class. It
+specifies the format in which AST objects should be written.
+
+\item A new class of \htmlref{Mapping}{Mapping}, the \htmlref{TranMap}{TranMap}, has been introduced. A TranMap
+takes its forward transformation from an existing Mapping, and its inverse
+transformation from another existing Mapping.
+
+\item A bug has been fixed in \htmlref{WcsMap}{WcsMap} which caused error reports to
+include erroneous axis numbers when referring to missing parameter values.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V3.3}
+
+The following describes the most significant changes which have
+occurred in the AST library between versions V3.2 and V3.3:
+
+\begin{enumerate}
+
+\item Options have been added to the \htmlref{SkyFrame}{SkyFrame} class which allows the
+origin
+of celestial coordinates to be moved to any specified point. See the new
+attributes SkyRef, \htmlref{SkyRefIs}{SkyRefIs}, SkyRefP and \htmlref{AlignOffset}{AlignOffset}.
+
+\item An option has been added to the \htmlref{FitsChan}{FitsChan} class which allows extra
+Frames representing cartesian projection plane coordinates (``intermediate
+world coordinates'' in the parlance of FITS-WCS) to be created when
+reading
+WCS information from a foreign FITS header. This option is controlled by
+a new attribute called \htmlref{Iwc}{Iwc}.
+
+\item The FitsChan class which been modified to interpret FITS-WCS CAR
+projection headers correctly if the longitude reference pixel (CRPIX) is
+very large.
+
+\item The  FITS-AIPS++ encoding in the FitsChan class now recognised
+spectral axes if they conform to the AIPS convention in which the
+spectral axis is descirbed by a CTYPE keyword od the form "AAAA-BBB"
+where ``AAAA'' is one of FREQ, VELO or FELO, and ``BBB'' is one of LSR, LSD,
+HEL or OBS. Such spectral axes can be both read and written.
+
+\item The FitsChan class now has a FITS-AIPS++ encoding which represents
+WCS information using FITS header cards recognised by the AIPS++ project.
+Support for spectral axes is identical to the FITS-AIPS encoding.
+
+\item The organisation of the AST distribution and the commands for
+building it have been changed. Whereas AST used to be built and installed
+with \verb+./mk build; ./mk install+, it now builds using the more standard
+idiom \verb+./configure; make; make install+. The installation location is
+controlled by the \verb+--prefix+ argument to ./configure (as is usual
+for other packages which use this scheme).  Note that the INSTALL environment
+variable now has a \emph{different} meaning to that which it had
+before, and it should generally be \emph{unset}. Also, there is no need to
+set the SYSTEM variable.
+
+\item Shared libraries are now installed in the same directory as the
+static libraries. In addition, links to sharable libraries are installed
+with names which include version information, and ``libtool libraries''
+are also installed (see
+\url{http://www.gnu.org/software/libtool/manual.html}).
+
+\item The \verb+ast_dev+ script has been removed. Instead, the location of
+the AST include files should be specified using the -I option when
+compiling.
+
+
+\end{enumerate}
+
+
+\subsection{Changes Introduced in V3.4}
+
+The following describes the most significant changes which have
+occurred in the AST library between versions V3.3 and V3.4:
+
+\begin{enumerate}
+
+\item The \htmlref{Mapping}{Mapping} class has a new method
+(\htmlref{astLinearApprox}{astLinearApprox})
+which calculates the co-efficients of a linear approximation to a Mapping.
+
+\item The Format attribute for simple Frames and SkyFrames has been extended.
+It has always been possible, in both classes, to specify a precision by
+including a dot in the Format value followed by an integer (\emph{e.g.}
+``\verb+dms.1+'' for a \htmlref{SkyFrame}{SkyFrame}, or ``\verb+%.10g+'' for a simple \htmlref{Frame}{Frame}).
+The precision can now also be specified using an asterisk in place of the
+integer (\emph{e.g.} ``\verb+dms.*+'' or ``\verb+%.*g+''). This causes the
+precision to be derived on the basis of the Digits attribute value.
+
+\item The \htmlref{Plot}{Plot} class has been changed so that the default value used for the
+Digits attribute is chosen to be the smallest value which results in no
+pair of adjacent labels being identical. For instance, if an annotated
+grid is being drawn describing a SkyFrame, and the Format(1) value is set
+to ``\verb+hms.*g+'' (the ``g'' causes field delimiters to be drawn as
+superscripts), and the Digits(1) value is unset, then the seconds field
+will have a number of decimal places which results in no pair of labels
+being identical.
+
+\item Addition of a new class classed \htmlref{DSBSpecFrame}{DSBSpecFrame}. This is a
+sub-class of \htmlref{SpecFrame}{SpecFrame} which can be used to describe spectral axes
+associated with dual sideband spectral data.
+
+\item The \htmlref{FitsChan}{FitsChan} class will now read headers which use the old ``-GLS''
+projection code, converting them to the corresponding modern ``-SFL'' code,
+provided that the celestial axes are not rotated.
+
+\item The FitsChan class has a new \htmlref{Encoding}{Encoding}, ``FITS-CLASS'', which allows
+the reading and writing of FITS headers using the conventions of the CLASS
+package - see
+\url{http://www.iram.fr/IRAMFR/GILDAS/doc/html/class-html/class.html}).
+
+\end{enumerate}
+
+
+\subsection{Changes Introduced in V3.5}
+
+The following describes the most significant changes which have
+occurred in the AST library between versions V3.4 and V3.5:
+
+\begin{enumerate}
+
+\item AST now provides facilities for representing regions of various
+shapes within a coordinate system. The \htmlref{Region}{Region} class provides general
+facilities which are independent of the specific shape of region being
+used. Various sub-classes of Region are also now available which provide
+means of creating Regions of specific shape. Facilities provided by the
+Region class include testing points to see if they are inside the
+Region, testing two Regions for overlap, transforming Regions from one
+coordinate system to another \emph{etc}.
+
+\item A new class of 1-dimensional \htmlref{Frame}{Frame} called \htmlref{FluxFrame}{FluxFrame} has been added which
+can be used to describe various systems for describing ovserved value at a
+single fixed spectral position.
+
+\item A new class of 2-dimensional Frame called \htmlref{SpecFluxFrame}{SpecFluxFrame} has been added which
+can be used to describe a 2-d frame spanned by a spectral position axis
+and and an observed value axis.
+
+\item A new class of \htmlref{Mapping}{Mapping} called \htmlref{RateMap}{RateMap} has been added. A RateMap encapsulates
+a previously created Mapping. The inputs of the RateMap correspond to the
+inputs of the encapsulated Mapping. All RateMaps have just a single
+output which correspond to the rate of change of a specified output of
+the encapsulated Mapping with respect to a specified input.
+
+\item The \htmlref{SkyFrame}{SkyFrame} class now supports a value of ``J2000'' for \htmlref{System}{System}.
+This system is an equatorial system based on the mean dynamical equator and
+equinox at J2000, and differs slightly from an FK5(J2000) system.
+
+\item A new class called \htmlref{KeyMap}{KeyMap} has been added. A KeyMap can be used to
+store a collection of vector or scalar values or Objects, indexed by a
+character string rather than an integer.
+
+\item The parameter list for the
+\htmlref{astRate}{astRate}
+method of the Mapping class has been modified. It no longer returns a second
+derivative estimate. Existing code which uses this method will need to be
+changed.
+
+\item Methods
+(astSetFits<X>)
+have been added to the \htmlref{FitsChan}{FitsChan} class to allow values for named
+keywords to be changed or added.
+
+\end{enumerate}
+
+
+\subsection{Changes Introduced in V3.6}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V3.5 and V3.6:
+
+\begin{enumerate}
+
+\item If the Format attribute associated with an axis of a \htmlref{SkyFrame}{SkyFrame}
+starts with a percent character (``\verb+%+''), then axis values are
+now formatted and unformatted as a decimal radians value, using the
+Format syntax of a simple \htmlref{Frame}{Frame}.
+
+\item The \htmlref{Plot}{Plot} class has a new attribute called \htmlref{Clip}{Clip} which controls the
+clipping performed by AST at the plot boundary.
+
+\item The keys used to label components of the \htmlref{PolyMap}{PolyMap} structure when a
+PolyMap is written out through a \htmlref{Channel}{Channel} have been changed. The new keys
+are shorter than the old keys and so can written succesfully to a \htmlref{FitsChan}{FitsChan}.
+The new PolyMap class always writes new styles keys but can read either
+old or new style keys. Consequently, PolyMap dumps written by this
+version of AST cannot be read by older versions of AST.
+
+\item A mimimal cut down subset of the C version of SLALIB is now
+included with the AST distribution and built as part of building AST.
+This means that it is no longer necessary to have SLALIB installed
+separately at your site. The SLALIB code included with AST is distrubuted
+under the GPL. The default behaviour of the \htmlref{ast\_link}{ast\_link} script is now to
+link with this internal slalib subset. However, the ``-csla'' option can
+still be used to force linking with an external full C SLALIB library.
+A new option ``-fsla'' has been introduced which forces linking with the
+external full Fortran SLALIB library.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V3.7}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V3.6 and V3.7:
+
+\begin{enumerate}
+
+\item Support for time coordinate systems has been introduced
+throught the addition of two new classes, \htmlref{TimeFrame}{TimeFrame} and \htmlref{TimeMap}{TimeMap}.
+The TimeFrame is a 1-dimensional \htmlref{Frame}{Frame} which can be used to describe
+moments in time (either absolute or relative) in various systems (MJD,
+Julian \htmlref{Epoch}{Epoch}, \emph{etc.}) and referred to various time scales (TAI, UTC,
+UT1, GMST, \emph{etc}). The TimeMap is a \htmlref{Mapping}{Mapping} which can transform time
+values between these various systems and time scales. Note,
+FitsChans which have a foreign encoding (\emph{i.e.} any encoding other
+than NATIVE) are not able to read or write these new classes.
+
+\end{enumerate}
+
+
+\subsection{Changes Introduced in V4.0}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V3.7 and V4.0:
+
+\begin{enumerate}
+
+\item Experimental support for reading IVOA Space-Time-Coordinates (STC-X)
+descriptions using the \htmlref{XmlChan}{XmlChan} class has been added. Support is included
+for a subset of V1.20 of the draft STC specification.
+
+\item A new set of methods (AST\_REBIN<X>/astRebin<X>) has been added to
+the \htmlref{Mapping}{Mapping} class. These are flux-conserving alternatives to the existing
+AST\_RESAMPLE<X>/astResample<X> methods.
+
+\end{enumerate}
+
+
+\subsection{Changes Introduced in V4.1}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V4.0 and V4.1:
+
+\begin{enumerate}
+
+\item A new control flag has been added to the AST\_RESAMPLE<X>/astResample<X>
+functions which produces approximate flux conservation.
+
+\item New constants AST\_\_SOMB and AST\_\_SOMBCOS have been added to
+ast.h. These specify kernels for astResample and astRebin
+based on the ``Sombrero'' function ( $2*J1(x)/x$ where $J1(x)$ is the
+first order Bessel function of the first kind).
+
+\item The \htmlref{SkyFrame}{SkyFrame} class now supports a \htmlref{System}{System} value of AZEL corresponding
+to horizon (azimuth/elevation) coordinates.
+
+\item The \htmlref{FitsChan}{FitsChan} class allows the non-standard strings ``AZ--'' and
+``EL--'' to be used as axis types in FITS-WCS CTYPE keyword values.
+
+\item The \htmlref{Frame}{Frame} class now has attributes \htmlref{ObsLon}{ObsLon} and \htmlref{ObsLat}{ObsLat} to specify
+the geodetic longitude and latitude of the observer.
+
+\item The ClockLon and ClockLat attributes have been removed from the
+\htmlref{TimeFrame}{TimeFrame} class. Likewise, the GeoLon and GeoLat attributes have been
+removed from the \htmlref{SpecFrame}{SpecFrame} class. Both classes now use the ObsLon and
+ObsLat attributes of the parent Frame class instead. However, the old
+attribute names can be used as synonyms for ObsLat and ObsLon. Also,
+dumps created using the old scheme can be read succesfully by AST V4.1
+and converted to the new form.
+
+\item A new
+function \htmlref{astMapSplit}{astMapSplit}
+has been added to the \htmlref{Mapping}{Mapping} class. This splits a Mapping into two component
+Mappings which, when combined in parallel, are equivalent to the original
+Mapping.
+
+\item The default value for the \htmlref{SkyRefIs}{SkyRefIs} attribute has been changed from
+``Origin'' to ``Ignored''. This means that if you want to use a SkyFrame
+to represent offsets from some origin position, you must now set the
+SkyRefIs attribute explicitly to either ``Pole'' or ``Origin'', in
+addition to assigning the required origin position to the SkyRef attribute.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V4.2}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V4.1 and V4.2:
+
+\begin{enumerate}
+
+\item The \htmlref{SideBand}{SideBand} attribute of the \htmlref{DSBSpecFrame}{DSBSpecFrame} class can now take the
+option ``LO'' in addition to ``USB'' and ``LSB''. The new option causes the
+DSBSpecFrame to represent the offset from the local oscillator frequency,
+rather than either of the two sidebands.
+
+\item The \htmlref{FitsChan}{FitsChan} class has been changed so that it writes out a VELOSYS
+keyword when creating a FITS-WCS encoding (VELOSYS indicates the topocentric
+apparent velocity of the standard of rest). FitsChan also strips out VELOSYS
+keywords when reading a \htmlref{FrameSet}{FrameSet} from a FITS-WCS encoding.
+
+\item The FitsChan class has a new method called
+\htmlref{astRetainFits}{astRetainFits}
+that indicates that the current card in the FitsChan should not be
+stripped out of the FitsChan when an AST \htmlref{Object}{Object} is read from the FitsChan.
+Unless this method is used, all cards that were involved in the creation
+of the AST Object will be stripped from the FitsChan afte a read operation.
+
+\item A problem with unaligned memory access that could cause bus errors on
+Solaris has been fixed.
+
+\item A new read-only attribute called \htmlref{ObjSize}{ObjSize} has been added to the base
+Object \htmlref{Class}{Class}. This gives the number of bytes of memory occupied by the
+Object. Note, this is the size of the internal in-memory representation of
+the Object, not the size of the textual representation produced by
+writing the Object out through a \htmlref{Channel}{Channel}.
+
+\item A new function
+\htmlref{astTune}{astTune}
+has been added which can be used to get and set global AST tuning
+parameters. At the moment there are only two such parameter, both of
+which are concerned with memory management within AST.
+
+\item A new method called
+\htmlref{astTranGrid}{astTranGrid}
+has been added to the \htmlref{Mapping}{Mapping} class. This method creates a regular
+grid of points covering a rectangular region within the input space of a
+Mapping, and then transforms this set of points into the output space of the
+Mapping, using a piecewise-continuous linear approximation to the Mapping
+if appropriate in order to achive higher speed.
+
+\item A new subclass of Mapping has been added called \htmlref{SwitchMap}{SwitchMap}. A
+SwitchMap represents several alternate Mappings, each of which is used to
+transforms input positions within a different region of the input
+coordinate space.
+
+\item A new subclass of Mapping has been added called \htmlref{SelectorMap}{SelectorMap}. A
+SelectorMap tests each input position to see if it falls within one of
+several Regions. If it does, the index of the \htmlref{Region}{Region} containing the
+input position is returned as the Mapping output.
+
+\item The behaviour of the
+\htmlref{astConvert}{astConvert}
+method when trying to align a \htmlref{CmpFrame}{CmpFrame} with another \htmlref{Frame}{Frame} has been
+modified. If no conversion between positions in the Frame and CmpFrame
+can be found, an attempt is now made to find a conversion between the
+Frame and one of two component Frames contained within the CmpFrame. Thus
+is should now be possible to align a \htmlref{SkyFrame}{SkyFrame} with a CmpFrame containing a
+SkyFrame and a \htmlref{SpecFrame}{SpecFrame} (for instance). The returned Mapping produces bad
+values for the extra axes (i.e. for the SpecFrame axis in the above example).
+
+\item The ``\htmlref{\htmlref{ast\_link}{ast\_link}\_adam}{ast\_link\_adam}'' and ``ast\_link'' scripts now ignore the
+\verb+-fsla+ and \verb+-csla+ options, and always link against the
+minimal cut-down version of SLALIB distributed as part of AST.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V4.3}
+
+The following describes the most significant changes which occurred in the
+AST library between versions V4.2 and V4.3:
+
+\begin{enumerate}
+
+\item The
+astGetFitsS
+function now strips trailing white space from the returned string, if the
+original string contains 8 or fewer characters
+
+\item The \htmlref{SpecFrame}{SpecFrame} class has a new attribute called \htmlref{SourceSys}{SourceSys} that specified
+whether the \htmlref{SourceVel}{SourceVel} attribute (which specifies the rest frame of the
+source) should be accessed as an apparent radial velocity or a redshift.
+Note, any existing software that assumes that SourceVel always represents
+a velocity in km/s should be changed to allow for the possibility of
+SourceVel representing a redshift value.
+
+\end{enumerate}
+
+
+\subsection{Changes Introduced in V4.4}
+
+The following describes the most significant changes which occurred in
+the AST library between versions V4.3 and V4.4:
+
+\begin{enumerate}
+
+\item The
+\htmlref{astFindFrame}{astFindFrame}
+function can now be used to search a \htmlref{CmpFrame}{CmpFrame} for an instance of a more
+specialised class of \htmlref{Frame}{Frame} (\htmlref{SkyFrame}{SkyFrame}, \htmlref{TimeFrame}{TimeFrame}, \htmlref{SpecFrame}{SpecFrame}, \htmlref{DSBSpecFrame}{DSBSpecFrame}
+or \htmlref{FluxFrame}{FluxFrame}). That is, if an instance of one of these classes is used as
+the ``template'' when calling
+astFindFrame,
+and the ``target'' being searched is a CmpFrame (or a \htmlref{FrameSet}{FrameSet} in which the
+current Frame is a CmpFrame), then the component Frames within the CmpFrame
+will be searched for an instance of the supplied template Frame, and, if
+found, a suitable \htmlref{Mapping}{Mapping} (which will include a \htmlref{PermMap}{PermMap} to select the
+required axes from the CmpFrame) will be returned by
+astFindFrame.
+Note, for this to work, the \htmlref{MaxAxes}{MaxAxes} and \htmlref{MinAxes}{MinAxes} attributes of the template
+Frame must be set so that they cover a range that includes the number of axes
+in the target CmpFrame.
+
+\item The SkyFrame, SpecFrame, DSBSpecFrame, TimeFrame and FluxFrame classes
+now allow the MaxAxes and MinAxes attributes to be set freely to any value.
+In previous versions of AST, any attempt to change the value of MinAxes
+or MaxAxes was ignored, resulting in them always taking the default values.
+
+\item The DSBSpecFrame class has a new attribute called AlignSB that
+specifies whether or not to take account of the \htmlref{SideBand}{SideBand} attributes when
+aligning two DSBSpecFrames using
+\htmlref{astConvert}{astConvert}.
+
+\item The Frame class has a new attribute called \htmlref{Dut1}{Dut1} that can be used to
+store a value for the difference between the UT1 and UTC timescales at
+the epoch referred to by the Frame.
+
+\item The number of digits used to format the Frame attributes \htmlref{ObsLat}{ObsLat} and
+\htmlref{ObsLon}{ObsLon} has been increased.
+
+\item The use of the SkyFrame attribute \htmlref{AlignOffset}{AlignOffset} has been changed. This
+attribute is used to control how two SkyFrames are aligned by
+astConvert.
+If the template and target SkyFrames both have a non-zero value for
+AlignOffset, then alignment occurs between the offset coordinate systems
+(that is, a \htmlref{UnitMap}{UnitMap} will always be used to align the two SkyFrames).
+
+\item The \htmlref{Plot}{Plot} class has a new attribute called ForceExterior that can be
+used to force exterior (rather than interior) tick marks to be produced.
+By default, exterior ticks are only produced if this would result in
+more than 3 tick marks being drawn.
+
+\item The TimeFrame class now supports conversion between angle based
+timescales such as UT1 and atomic based timescales such as UTC.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V4.5}
+
+The following describes the most significant changes that
+occurred in the AST library between versions V4.4 and V4.5:
+
+\begin{enumerate}
+
+
+
+\item All FITS-CLASS headers are now created with a frequency axis. If the
+\htmlref{FrameSet}{FrameSet} supplied to
+\htmlref{astWrite}{astWrite}
+contains a velocity axis (or any other form
+of spectral axis) it will be converted to an equivalent frequency axis
+before being used to create the FITS-CLASS header.
+
+\item The value stored in the FITS-CLASS keyword ``VELO-LSR'' has been changed
+from the velocity of the source to the velocity of the reference channel.
+
+\item Addition of a new method call
+\htmlref{astPurgeWCS}{astPurgeWCS}
+to the \htmlref{FitsChan}{FitsChan}
+class. This method removes all WCS-related header cards from a FitsChan.
+
+\item The \htmlref{Plot}{Plot} class has a new attribute called GrfContext that can be used
+to comminicate context information between an application and any
+graphics functions registered with the Plot class via the
+\htmlref{astGrfSet}{astGrfSet} function.
+\item Functions registered with the Plot class using
+astGrfSet
+now take a new additional integer parameter, ``grfcon''. The Plot class
+sets this parameter to the value of the Plot's GrfContext attribute before
+calling the graphics function. NOTE, THIS CHANGE WILL REQUIRE EXISTING
+CODE THAT USES
+astGrfSet
+TO BE MODIFIED TO INCLUDE THE NEW PARAMETER.
+\item The
+astRebinSeq functions
+now have an extra parameter that is used to record the total number of input
+data values added into the output array. This is necessary to correct a
+flaw in the calculation of output variances based on the spread of input
+values. NOTE, THIS CHANGE WILL REQUIRE EXISTING CODE TO BE MODIFIED TO
+INCLUDE THE NEW PARAMETER (CALLED "NUSED").
+\item Support has been added for the FITS-WCS ``HPX'' (HEALPix) projection.
+\item A new flag ``AST\_\_VARWGT'' can be supplied to
+astRebinSeq.
+This causes the input data values to be weighted using the reciprocals of
+the input variances (if supplied).
+
+\item The \htmlref{Frame}{Frame} class has a new read-only attribute called NormUnit that
+returns the normalised value of the Unit attribute for an axis. Here,
+``normalisation'' means cancelling redundant units, etc. So for instance, a
+Unit value of ``s*(m/s)'' would result in a NormUnit value of ``m''.
+
+\item A new
+function \htmlref{astShowMesh}{astShowMesh}
+has been added to the \htmlref{Region}{Region} class. It displays a mesh of points covering
+the surface of a Region by writing out a table of axis values to standard
+output.
+
+\item The Plot class now honours the value of the LabelUp attribute even if
+numerical labels are placed around the edge of the Plot. Previously
+LabelUp was only used if the labels were drawn within the interior of
+the plot. The LabelUp attribute controls whether numerical labels are
+drawn horizontally or parallel to the axis they describe.
+
+\item A bug has been fixed that could segmentation violations when setting
+attribute values.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V4.6}
+
+The following describes the most significant changes which have
+occurred in the AST library between versions V4.5 and V4.6:
+
+\begin{enumerate}
+
+\item The \htmlref{TimeFrame}{TimeFrame} class now support Local Time as a time scale. The offset
+from UTC to Local Time is specified by a new TimeFrame attribute called
+\htmlref{LTOffset}{LTOffset}.
+
+\item A new class called \htmlref{Plot3D}{Plot3D} has been added. The Plot3D class allows
+the creation of 3-dimensional annotated coordinate grids.
+
+\item A correction for diurnal aberration is now included when
+converting between AZEL and other celestial coordinate systems. The
+correction is based on the value of the \htmlref{ObsLat}{ObsLat} \htmlref{Frame}{Frame} attribute (the
+geodetic latitude of the observer).
+
+\item A bug has been fixed which caused the DUT1 attribute to be ignored
+by the \htmlref{SkyFrame}{SkyFrame} class when finding conversions between AZEL and other
+celestial coordinate systems.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V5.0}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V4.6 and V5.0:
+
+\begin{enumerate}
+
+
+\item The AST library is now thread-safe (assuming that the POSIX pthreads
+library is available when AST is built). Many of the macros defined in
+the ast.h header file have changed. It is therefore necessary to
+re-compile all source code that includes ast.h.
+
+\item New methods \htmlref{astLock}{astLock} and \htmlref{astUnlock}{astUnlock} allow an AST \htmlref{Object}{Object} to be locked
+for exclusive use by a thread.
+
+\item The \htmlref{TimeFrame}{TimeFrame} class now support Local Time as a time scale. The offset
+from UTC to Local Time is specified by a new TimeFrame attribute called
+\htmlref{LTOffset}{LTOffset}.
+
+\item The \htmlref{Channel}{Channel} class has a new attribute called \htmlref{Strict}{Strict} which controls
+whether or not to report an error if unexpected data items are found
+within an AST Object description read from an external data source. Note,
+the default behaviour is now not to report such errors. This differs from
+previous versions of AST which always reported an error is unexpected
+input items were encountered.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V5.1}
+
+The following describes the most significant changes which occurred in the
+AST library between versions V5.0 and V5.1:
+
+\begin{enumerate}
+
+\item The \htmlref{astUnlock}{astUnlock} function now has an extra parameter that controls whether
+or not an error is reported if the \htmlref{Object}{Object} is currently locked by another
+thread.
+
+\item The \htmlref{Prism}{Prism} class has been modified so that any class of \htmlref{Region}{Region} can
+be used to define the extrusion axes. Previously, only a \htmlref{Box}{Box} or \htmlref{Interval}{Interval}
+could be used for this purpose.
+
+\item The values of the AST\_\_THREADSAFE macro (defined in ast.h) have
+been changed from ``yes'' and ``no'' to ``1'' and ``0''.
+
+\item Improvements have been made to the way that Prisms are simplified
+when
+\htmlref{astSimplify}{astSimplify}
+is called.  The changes mean that more types of Prism will now simplify
+into a simpler class of Region.
+
+\item The \htmlref{PointList}{PointList} class has a new method,
+astPoints,
+that copies the axis values from the PointList into a supplied array.
+
+\item The PointList class has a new (read-only) attribute, \htmlref{ListSize}{ListSize}, that
+gives the number of points stored in the PointList.
+
+\item The handling of warnings within different classes of \htmlref{Channel}{Channel} has
+been rationalised. The XmlStrict attribute and
+astXmlWarnings
+function have been removed. The same functionality is now available via
+the existing \htmlref{Strict}{Strict} attribute (which has had its remit widened), a new
+attribute called \htmlref{ReportLevel}{ReportLevel}, and the new
+\htmlref{astWarnings}{astWarnings}
+function. This new function can be used on any class of Channel. Teh
+\htmlref{FitsChan}{FitsChan} class retains its long standing ability to store warnings as
+header cards within the FitsChan, but it also now stores warnings in the
+parent Channel structure, from where they can be retrieved using the
+astWarnings
+function.
+
+\item A new function called
+astIntercept
+has been added to the \htmlref{Frame}{Frame} class. This function finds the point of
+intersection beteeen two geodesic curves.
+
+\item A bug in the type-checking of Objects passed as arguments to constructor
+functions has been fixed. This bug could lead to applications crashing or
+showing strange behaviour if an inappropriate class of Object was
+supplied as an argument to a constructor.
+
+\item The
+\htmlref{astPickAxes}{astPickAxes}
+function will now return a Region, if possible, when applied to a Region. If
+this is not possible, a Frame will be returned as before.
+
+\item The choice of default tick-mark for time axes has been improved, to avoid
+previous issues which could result in no suitable gap being found, or
+inappropriate tick marks when using formatted dates.
+
+\item A new function called
+\htmlref{astTestFits}{astTestFits}
+has been added to the FitsChan class. This function tests a FitsChan to
+see if it contains a defined value for specified FITS keyword.
+
+\item The AST\_\_UNDEF<X> parameters used to flag undefined FITS keyword values
+have been removed. Use the new
+astTestFits
+function instead.
+
+\item The astIsUndef<X> functions used to test FITS keyword values
+have been removed. Use the new astTestFits function instead.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V5.2}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V5.1 and V5.2:
+
+\begin{enumerate}
+
+\item A new method called
+\htmlref{astSetFitsCM}{astSetFitsCM}
+has been added to the \htmlref{FitsChan}{FitsChan} class. It stores a pure comment card in a
+FitsChan (that is, a card with no keyword name or equals sign).
+
+\item A new attribute called \htmlref{ObsAlt}{ObsAlt} has been added to the \htmlref{Frame}{Frame} class. It
+records the geodetic altitude of the observer, in metres. It defaults to
+zero. It is used when converting times to or from the TDB timescale, or
+converting spectral positions to or from the topocentric rest frame, or
+converting sky positions to or from horizon coordinates. The FitsChan
+class will include its effect when creating a set of values for the
+OBSGEO-X/Y/Z keywords, and will also assign a value to it when reading a
+set of OBSGEO-X/Y/Z keyword values from a FITS header.
+
+\item The \htmlref{TimeMap}{TimeMap} conversions ``TTTOTDB'' and ``TDBTOTT'', and the \htmlref{SpecMap}{SpecMap}
+conversions ``TPF2HL'' and ``HLF2TP'', now have an additional argument -
+the observer's geodetic altitude.
+
+\item The \htmlref{Polygon}{Polygon} class has been modified to make it consistent with the
+IVOA STC definition of a Polygon. Specifically, the inside of a polygon
+is now the area to the left of each edge as the vertices are traversed in
+an anti-clockwise manner, as seen from the inside of the celestial sphere.
+Previously, AST used the anti-clockwise convention, but viewed from the
+outside of the celestial sphere instead of the inside. Any Polygon saved
+using previous versions of AST will be identified and negated automatically
+when read by AST V5.2.
+
+\item A new class of \htmlref{Channel}{Channel}, called \htmlref{StcsChan}{StcsChan}, has been added that allows
+conversion of suitable AST Objects to and from IVOA STC-S format.
+
+\item A new method called
+\htmlref{astRemoveRegions}{astRemoveRegions}
+has been added to the \htmlref{Mapping}{Mapping} class. It searches a (possibly compound)
+Mapping (or Frame) for any instances of the AST \htmlref{Region}{Region} class, and either
+removes them, or replaces them with UnitMaps (or equivalent Frames). It
+can be used to remove the masking effects of Regions from a compound
+Mapping or Frame.
+
+\item A new method called
+\htmlref{astDownsize}{astDownsize}
+has been added to the Polygon class. It produces a new Polygon that
+contains a subset of the vertices in the supplied Polygon. The subset is
+chosen to retain the main features of the supplied Polygion, in so far
+as that is possible, within specified constraints.
+
+\item A new constructor called
+astOutline
+has been added to the Polygon class. Given a 2D data array, it identifies
+the boundary of a region within the array that holds pixels with
+specified values. It then creates a new Polygon to describe this boundary
+to a specified accuracy.
+
+\item A new set of methods, called
+astMapGetElem<X>
+has been added to the \htmlref{KeyMap}{KeyMap} class. They allow a single element of a vector
+valued entry to be returned.
+
+\item A new attribute called \htmlref{KeyError}{KeyError} has been added to the KeyMap \htmlref{Class}{Class}. It
+controls whether the
+astMapGet...
+family of functions report an error if an entry with the requested key does
+not exist in the KeyMap.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V5.3}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V5.2 and V5.3:
+
+\begin{enumerate}
+
+\item The details of how a \htmlref{Frame}{Frame} is aligned with another Frame by the
+\htmlref{astFindFrame}{astFindFrame} and \htmlref{astConvert}{astConvert}
+functions have been changed. The changes mean that a Frame can now be
+aligned with an instance of a sub-class of Frame, so long as the number
+of axes and the \htmlref{Domain}{Domain} values are consistent. For instance, a basic
+2-dimensional Frame with Domain ``SKY'' will now align succesfully with
+a \htmlref{SkyFrame}{SkyFrame}, conversion between the two Frames being achieved using a
+\htmlref{UnitMap}{UnitMap}.
+
+\item The arrays that supply input values for astMapPut1<X> are now
+declared ``const''.
+
+\item Added method
+\htmlref{astMatchAxes}{astMatchAxes}
+to the Frame class. This method allows corresponding axes within two
+Frames to be identified.
+
+\item The
+\htmlref{astAddFrame}{astAddFrame}
+method can now be used to append one or more axes to all Frames in a \htmlref{FrameSet}{FrameSet}.
+\end{enumerate}
+
+\subsection{Changes Introduced in V5.3-1}
+
+The following describes the most significant changes which have
+occurred in the AST library between versions V5.3 and V5.3-1:
+
+\begin{enumerate}
+
+\item The utility functions provided by the AST memory management layer
+are now documented in an appendix.
+
+\item The \htmlref{KeyMap}{KeyMap} class now supports entries that have undefined values. A
+new method called
+\htmlref{astMapPutU}{astMapPutU}
+will store an entry with undefined value in a keymap. Methods that
+retrieve values from a KeyMap
+(astMapGet0<X>, etc.)
+ignore entries with undefined values when searching for an entry with a given
+key.
+
+\item The KeyMap class has a new method called
+\htmlref{astMapCopy}{astMapCopy}
+that copies entries from one KeyMap to another KeyMap.
+
+\item The KeyMap class has a new boolean attribute called \htmlref{MapLocked}{MapLocked}. If
+non-zero,
+an error is reported if an attempt is made to add any new entries
+to a KeyMap (the value associated with any old entry may still be changed
+without error). The default is
+zero.
+
+\item The \htmlref{Object}{Object} class has a new method called \htmlref{astHasAttribute}{astHasAttribute}/AST\_HASATTRIBUTE
+that returns a boolean value indicating if a specified Object has a named
+attribute.
+
+\item The \htmlref{SkyFrame}{SkyFrame} class has two new read-only boolean attributes called
+IsLatAxis and IsLonAxis that can be used to determine the nature of a
+specified SkyFrame axis.
+
+\item A bug has been fixed in the
+astRebin(Seq)
+methods that could cause flux to be lost from the edges of the supplied array.
+
+\item A bug has been fixed in the
+astRebin(Seq)
+methods that caused the first user supplied parameter to be interpreted as the
+full width of the spreading kernel, rather than the half-width.
+
+\item The \htmlref{StcsChan}{StcsChan} class now ignores case when reading STC-S phrases (except
+that units strings are still case sensitive).
+
+\item A new \htmlref{Mapping}{Mapping} method,
+\htmlref{astQuadApprox}{astQuadApprox},
+produces a quadratic least-squares fit to a 2D Mapping.
+
+\item A new Mapping method,
+\htmlref{astSkyOffsetMap}{astSkyOffsetMap},
+produces a Mapping from absolute SkyFrame coordinates to offset SkyFrame
+coordinates.
+
+\item The \htmlref{Channel}{Channel} class now has an \htmlref{Indent}{Indent} attribute that controls indentation
+in the text created by
+\htmlref{astWrite}{astWrite}.
+The StcsIndent and XmlIndent attributes have been removed.
+
+\item All classes of Channel now use the string ``<bad>'' to represent the
+floating point value AST\_\_BAD, rather than the literal formatted value
+(typically ``-1.79769313486232e+308'' ).
+
+\item The KeyMap class now uses the string ``<bad>'' to represent the
+floating point value AST\_\_BAD, rather than the literal formatted value
+(typically ``-1.79769313486232e+308'' ).
+
+\item The KeyMap class has a new method called
+astMapPutElem<X>
+that allows a value to be put into a single element of a vector entry in
+a KeyMap. The vector entry is extended automatically to hold the new
+element if required.
+
+\item The \htmlref{DSBSpecFrame}{DSBSpecFrame} class now reports an error if the local oscillator
+frequency is less than the absoliute value of the intermediate frequency.
+
+\end{enumerate}
+
+
+\subsection{Changes Introduced in V5.3-2}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V5.3-1 and V5.3-2:
+
+\begin{enumerate}
+
+\item A bug has been fixed in the \htmlref{FitsChan}{FitsChan} class that could cause wavelength
+axes to be assigned the units ``m/s'' when reading WCS information from a
+FITS header.
+
+\item The
+\htmlref{astSet}{astSet} function
+now allows literal commas to be included in string attribute values. String
+attribute values that include a literal comma should be enclosed in quotation
+marks.
+
+\item A bug in FitsChan has been fixed that caused ``-SIN'' projection
+codes within FITS-WCS headers to be mis-interpreted, resulting in no
+\htmlref{FrameSet}{FrameSet} being read by \htmlref{astRead}{astRead}.
+
+\item The \htmlref{KeyMap}{KeyMap} class has a new attribute called ``\htmlref{SortBy}{SortBy}''. It controls
+the order in which keys are returned by the
+\htmlref{astMapKey}{astMapKey}
+function. Keys can be sorted alphabetically or by age, or left unsorted.
+
+\item Access to KeyMaps holding thousands of entries is now significantly
+faster.
+
+\item KeyMaps can now hold word (i.e.
+short integer)
+values.
+
+\end{enumerate}
+
+
+\subsection{Changes Introduced in V5.4-0}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V5.3-2 and V5.4-0:
+
+\begin{enumerate}
+
+\item the \htmlref{FitsChan}{FitsChan} class now has an option to support reading and writing
+of FITS-WCS headers that use the -TAB algorithm described in FITS-WCS paper
+III. This option is controlled by a new FitsChan attribute called \htmlref{TabOK}{TabOK}.
+See the documentation for TabOK for more information.
+
+\item A new class called ``\htmlref{Table}{Table}'' has been added. A Table is a \htmlref{KeyMap}{KeyMap} in
+which each entry represents a cell in a two-dimensional table.
+
+\item A new class called ``\htmlref{FitsTable}{FitsTable}'' has been added. A FitsTable is a
+Table that has an associated FitsChan holding headers appropriate to a
+FITS binary table.
+
+\item KeyMaps can now hold byte values. These are held in variables
+of type
+"unsigned char".
+
+\item KeyMaps have a new attribute called \htmlref{KeyCase}{KeyCase} that can be set to zero to
+make the handling of keys case insensitive.
+
+\item a memory leak associated with the use of the
+astMapPutElem<X>
+functions has been fixed.
+
+\item A new method called
+\htmlref{astMapRename}{astMapRename}
+has been added to rename existing entry in a KeyMap.
+\end{enumerate}
+
+\subsection{Changes Introduced in V5.5-0}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V5.4-0 and V5.5-0:
+
+\begin{enumerate}
+
+\item The \htmlref{FitsChan}{FitsChan} ``\htmlref{TabOK}{TabOK}'' attribute is now an integer value rather
+than a boolean value. If TabOK is set to a non-zero positive integer
+before invoking the
+\htmlref{astWrite}{astWrite}
+method, its value is used as the version number for any table that is
+created as a consequence of the write operation. This is the value stored
+in the PVi\_1a keyword in the IMAGE header, and the EXTVER keyword in the
+binary table header. In previous versions of AST, the value used for these
+headers could not be controlled and was fixed at 1. If TabOK is set to a
+negative or zero value, the -TAB algorithm will not be supported by
+either the
+astWrite or \htmlref{astRead}{astRead}
+methods.
+
+\end{enumerate}
+
+
+
+\subsection{Changes Introduced in V5.6-0}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V5.5-0 and V5.6-0:
+
+\begin{enumerate}
+
+\item
+New functions \htmlref{astBBuf}{astBBuf} and \htmlref{astEBuf}{astEBuf}
+have been added to the \htmlref{Plot}{Plot} class. These control the buffering of graphical
+output produced by other Plot methods.
+
+\item New functions astGBBuf and astGEBuf have been added to the interface
+defined by file \verb+grf.h+. The \htmlref{ast\_link}{ast\_link} command has been modified so
+that the \verb+-grf_v3.2+ switch loads dummy versions of the new grf
+functions. This means that applications that use the  \verb+-grf_v3.2+
+switch should continue to build without any change. However, the new public
+functions astBBuf and astEBuf
+will report an error unless the new grf functions are implemented. If you
+choose to implement them, you should modify your linking procedure to
+use the \verb+-grf+ (or  \verb+-grf_v5.6+ ) switch in place of the older
+\verb+-grf_v3.2+ switch. See the description of the ast\_link command for
+details of these switches.
+
+\item New method
+\htmlref{astGetRegionMesh}{astGetRegionMesh}
+returns a set of positions covering the boundary, or volume, of a supplied
+\htmlref{Region}{Region}.
+
+\end{enumerate}
+
+
+\subsection{ChangesIntroduced in V5.6-1}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V5.6-0 and V5.6-1:
+
+\begin{enumerate}
+
+\item Tables can now have any number of parameters describing the global
+properties of the \htmlref{Table}{Table}.
+
+\item Frames now interpret the unit string ``A'' as meaning ``Ampere''
+rather than ``Angstrom'', as specified by FITS-WCS paper I.
+
+\item A bug has been fixed in the
+\htmlref{astFindFrame}{astFindFrame}
+method that allowed a template \htmlref{Frame}{Frame} of a more specialised class to match
+a target frame of a less specialised class. For example, this bug would
+allow a template \htmlref{SkyFrame}{SkyFrame} to match a target Frame. This no longer
+happens.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V5.7-0}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V5.6-1 and V5.7-0:
+
+\begin{enumerate}
+
+\item The \htmlref{FitsChan}{FitsChan} class support for the IRAF-specific ``TNX'' projection has
+been extended to include reading TNX headers that use a Chebyshev
+representation for the distortion polynomial.
+
+\item The FitsChan class support for the IRAF-specific ``ZPX'' projection has
+been extended to include reading ZPX headers that use simple or Chebyshev
+representation for the distortion polynomial.
+
+\item A bug has been fixed in the FitsChan class that caused headers
+including the Spitzer ``-SIP'' distortion code to be read incorrectly if no
+inverse polynomial was specified in the header.
+
+\item A new attribute called \htmlref{PolyTan}{PolyTan} has been added to the FitsChan class. It
+can be used to indicate that FITS headers that specify a TAN projection
+should be interpreted according to the ``distorted TAN'' convention
+included in an early draft of FITS-WCS paper II. Such headers are created
+by (for instance) the SCAMP tool (\url{http://www.astromatic.net/software/scamp}).
+
+\item The \htmlref{PolyMap}{PolyMap} class now provides a method called
+\htmlref{astPolyTran}{astPolyTran}
+that adds an inverse transformation to a PolyMap by sampling the forward
+transformation on a regular grid, and then fitting a polynomial function
+from the resulting output values to the grid of input values.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V5.7-1}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V5.7-0 and V5.7-1:
+
+\begin{enumerate}
+
+\item - All classes of \htmlref{Channel}{Channel} can now read to and write from specified
+text files, without the need to provide source and sink functions when
+the Channel is created. The files to use are specified by the new
+attributes \htmlref{SourceFile}{SourceFile} and \htmlref{SinkFile}{SinkFile}.
+
+\item - The \htmlref{FitsChan}{FitsChan} class now ignores trailing spaces in character-valued WCS
+keywords when reading a \htmlref{FrameSet}{FrameSet} from a FITS header.
+
+\item - If the FitsChan \htmlref{astRead}{astRead} method reads a FITS header that uses the
+-SIP (Spitzer) distortion code within the CTYPE values, but which does
+not provide an inverse polynomial correction, the FitsChan class will now
+use the PolyTran method of the \htmlref{PolyMap}{PolyMap} class to create an estimate of the
+inverse polynomial correction.
+
+\end{enumerate}
+
+
+\subsection{Changes Introduced in V5.7-2}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V5.7-1 and V5.7-2:
+
+\begin{enumerate}
+
+\item The \htmlref{Object}{Object} class has a new function \htmlref{astToString}{astToString} (C only), which creates
+an in-memory textual serialisation of a given AST Object. A corresponding
+new function called \htmlref{astFromString}{astFromString} re-creates the Object from its
+serialisation.
+
+\item The \htmlref{PolyMap}{PolyMap} class can now use an iterative Newton-Raphson method to
+evaluate the inverse the inverse transformation if no inverse
+transformation is defined when the PolyMap is created.
+
+\item The \htmlref{FitsChan}{FitsChan} class has a new method
+\htmlref{astWriteFits}{astWriteFits}
+which writes out all cards currently in the FitsChan to the associated
+external data sink (specified either by the \htmlref{SinkFile}{SinkFile} attribute or the
+sink function supplied when the FitsChan was created), and then empties
+the FitsChan.
+
+\item The FitsChan class has a new read-only attribute called ``\htmlref{Nkey}{Nkey}'', which
+holds the number of keywords for which values are held in a FitsChan.
+
+\item The FitsChan
+astGetFits<X>
+methods can now be used to returned the value of the current card.
+
+\item The FitsChan class has a new read-only attribute called ``\htmlref{CardType}{CardType}'', which
+holds the data type of the keyword value for the current card.
+
+\item The FitsChan class has a new method
+\htmlref{astReadFits}{astReadFits}
+which forces the FitsChan to reads cards from the associated external
+source and appends them to the end of the FitsChan.
+
+\item - If the FitsChan \htmlref{astRead}{astRead} method reads a FITS header that uses the
+-SIP (Spitzer) distortion code within the CTYPE values, but which does
+not provide an inverse polynomial correction, and for which the PolyTran
+method of the PolyMap class fails to create an accurate estimate of the
+inverse polynomial correction, then an iterative method will be used to
+evaluate the inverse correction for each point transformed.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V6.0}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V5.7-2 and V6.0:
+
+\begin{enumerate}
+
+\item This version of AST is the first that can be used with the Python
+AST wrapper module, starlink.Ast, available at \url{http://github.com/timj/starlink-pyast}.
+
+\item When reading a FITS-WCS header, the \htmlref{FitsChan}{FitsChan} class now recognises the
+non-standard ``TPV'' projection code within a CTYPE keyword value. This
+code is used by SCAMP (see www.astromatic.net/software/scamp) to
+represent a distorted TAN projection.
+
+\item The \htmlref{Plot}{Plot} class has been changed to remove visual anomalies (such as
+incorrectly rotated numerical axis labels) if the graphics coordinates have
+unequal scales on the X and Y axes.
+
+- The graphics escape sequences used to produce graphical sky axis labels
+can now be changed using the new
+function \htmlref{astTuneC}{astTuneC}.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V6.0-1}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V6.0 and V6.0-1:
+
+\begin{enumerate}
+
+\item The \htmlref{FitsChan}{FitsChan} class now recognises the Spitzer ``-SIP'' distortion
+code within FITS headers that describe non-celestial axes, as well as
+celestial axes.
+
+\item A bug has been fixed that could cause inappropriate equinox values to
+be used when aligning SkyFrames if the \htmlref{AlignSystem}{AlignSystem} attribute is set.
+
+\item The versioning string for AST has changed from
+``$<major>.<minor>-<release>$'' to ``$<major>.<minor>.<release>$''.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V7.0.0}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V6.0-1 and V7.0.0:
+
+\begin{enumerate}
+
+\item Fundamental positional astronomy calculations are now performed
+using the IAU SOFA library where possible, and the Starlink PAL library \xref{SUN/268}{sun268}{}
+otherwise (the PAL library contains a subset of the Fortran Starlink SLALIB
+library re-written in C). Copies of these libraries are bundled with AST
+and so do not need to be obtained or built separately, although external
+copies of SOFA and PAL can be used if necessary by including the
+``\texttt{--with-external\_pal}'' option when configuring AST.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V7.0.1}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V7.0.0 and V7.0.1:
+
+\begin{enumerate}
+
+\item The levmar and wcslib code distributed within AST is now stored in the
+main AST library (libast.so) rather than in separate libraries.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V7.0.2}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V7.0.1 and V7.0.2:
+
+\begin{enumerate}
+
+\item The libast\_pal library is no longer built if the
+``--with-external\_pal'' option is used when AST is configured.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V7.0.3}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V7.0.2 and V7.0.3:
+
+\begin{enumerate}
+
+\item A bug has been fixed which could cause an incorrect axis to be used when
+accessing axis attributes within CmpFrames. This could happen if axes
+within the \htmlref{CmpFrame}{CmpFrame} have been permuted.
+
+\item A bug has been fixed in the \htmlref{SkyFrame}{SkyFrame} class that could cause the two
+values of the SkyRef and/or SkyRefP attributes to be reversed.
+
+\item Bugs have been fixed in the \htmlref{CmpRegion}{CmpRegion} class that should allow the border
+around a compound \htmlref{Region}{Region} to be plotted more quickly, and more accurately.
+Previously, component Regions nested deeply inside a CmpRegion may have
+been completely or partially ignored.
+
+\item A bug has been fixed in the \htmlref{Plot3D}{Plot3D} class that caused a segmentation
+violation if the MinTick attribute was set to zero.
+
+\item The astResampleX set of methods now includes astResampleK and
+astResampleUK that handles 64 bit integer data.
+
+\end{enumerate}
+
+
+\subsection{Changes Introduced in V7.0.4}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V7.0.3 and V7.0.4:
+
+
+\begin{enumerate}
+
+\item The previously private grf3d.h header file is now installed into
+prefix/include.
+
+\end{enumerate}
+
+
+\subsection{Changes Introduced in V7.0.5}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V7.0.4 and V7.0.5:
+
+\begin{enumerate}
+
+\item The \htmlref{FitsChan}{FitsChan} class can now read FITS headers that use the SAO
+convention for representing distorted TAN projections, based on the use
+of ``COi\_m'' keywords to hold the coefficients of the distortion polynomial.
+
+\end{enumerate}
+
+
+\subsection{Changes Introduced in V7.0.6}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V7.0.5 and V7.0.6:
+
+\begin{enumerate}
+
+\item A bug has been fixed in astRebinSeq<X> which could result in
+incorrect normalisation of the final binned data and variance values.
+
+\item When reading a \htmlref{FrameSet}{FrameSet} from a FITS-DSS header, the keywords CNPIX1
+and CNPIX2 now default to zero if absent. Previously an error was reported.
+
+\end{enumerate}
+
+
+\subsection{Changes Introduced in V7.1.0}
+
+The following describes the most significant changes which occurred in the
+AST library between versions V7.0.6 and V7.1.0:
+
+\begin{enumerate}
+
+\item IMPORTANT! The default behaviour of astRebinSeq is now NOT to conserve
+flux. To conserve flux, the AST\_\_CONSERVEFLUX flag should be supplied
+when calling
+astRebinSeq<X>.
+Without this flag, each output value is a weighted mean of the neighbouring
+input values.
+
+\item A new flag AST\_\_NONORM can be used with astRebinSeq<X> to indicate that
+normalisation of the output arrays is not required. In this case no
+weights array need be supplied.
+
+\item A bug has been fixed in
+\htmlref{astAddFrame}{astAddFrame} method
+that could result in the incorrect inversion of Mappings within the \htmlref{FrameSet}{FrameSet}
+when the AST\_\_ALLFRAMES flag is supplied for the
+"iframe" parameter.
+
+\item The
+\htmlref{astRate}{astRate} method
+has been re-written to make it faster and more reliable.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V7.1.1}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V7.1.0 and V7.1.1:
+
+\begin{enumerate}
+
+\item When a \htmlref{FitsChan}{FitsChan} is used to write an ``offset'' \htmlref{SkyFrame}{SkyFrame} (see attribute
+\htmlref{SkyRefIs}{SkyRefIs}) to a FITS-WCS encoded header, two alternate axis descriptions
+are now created - one for the offset coordinates and one for the absolute
+coordinates. If such a header is subsequently read back into AST, the
+original offset SkyFrame is recreated.
+
+\item A bug has been fixed in FitsChan that caused inappropriate CTYPE values
+to be generated when writing a \htmlref{FrameSet}{FrameSet} to FITS-WCS headers if the
+current \htmlref{Frame}{Frame} describes generalised spherical coordinates (i.e. a
+SkyFrame with \htmlref{System}{System}=Unknown).
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V7.2.0}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V7.1.1 and V7.2.0:
+
+\begin{enumerate}
+
+\item A new method call
+\htmlref{astMapDefined}{astMapDefined}
+has been added to the \htmlref{KeyMap}{KeyMap} class. It checks if a gtiven key name has
+a defined value in a given KeyMap.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V7.3.0}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V7.2.0 and V7.3.0:
+
+\begin{enumerate}
+
+\item The interface for the astRebinSeq<X> family of functions has
+been changed in order to allow a greater number of pixels to be pasted
+into the output array. The "nused" parameter is now a pointer to a
+"int64\_t" variable, instead of an "int". APPLICATION CODE SHOULD BE
+CHANGED ACCORDINGLY TO AVOID SEGMENTATION FAULTS AND OTHER ERRATIC
+BEHAVIOUR.
+
+\item Added a new facility to the \htmlref{FrameSet}{FrameSet} class to allow each \htmlref{Frame}{Frame} to be
+associated with multiple Mappings, any one of which can be used to
+connect the Frame to the other Frames in the FrameSet. The choice of
+which \htmlref{Mapping}{Mapping} to use is controlled by the new ``\htmlref{Variant}{Variant}'' attribute of the
+FrameSet class.
+
+\item Mappings (but not Frames) that have a value set for their \htmlref{Ident}{Ident}
+attribute are now left unchanged by the
+c \htmlref{astSimplify}{astSimplify} function.
+f AST\_SIMPLIFY routine.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V7.3.1}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V7.3.0 and V7.3.1:
+
+\begin{enumerate}
+
+\item Fix a bug that could cauise a segmentation violation when reading
+certain FITS headers that use a TNX projection.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V7.3.2}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V7.3.1 and V7.3.2:
+
+\begin{enumerate}
+
+\item Fix support for reading FITS header that use a GLS projection.
+Previously, an incorrect transformation was used for such projections if
+any CRVAL or CROTA value was non-zero.
+
+\item The \htmlref{KeyMap}{KeyMap} class has new sorting options ``KeyAgeUp'' and
+``KeyAgeDown'' that retain the position of an existing entry if its value
+is changed. See the \htmlref{SortBy}{SortBy} attribute.
+
+\item A bug has been fixed in the \htmlref{FitsChan}{FitsChan} class that caused CDELT keywords
+for sky axes to be treated as radians rather than degrees when reading a
+FITS header, if the corresponding CTYPE values included no projection code.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V7.3.3}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V7.3.2 and V7.3.3:
+
+\begin{enumerate}
+
+\item The \htmlref{FitsChan}{FitsChan} class has new attributes \htmlref{CardName}{CardName} and \htmlref{CardComm}{CardComm}, which hold
+the keyword name and comment of the current card.
+
+\item When using the FitsChan class to read FITS-WCS headers that include
+polynomial distortion in the SIP format, any inverse transformation specified
+in the header is now ignored and a new inverse is created to replace it based
+on the supplied forward transformation. Previously, an inverse was created
+only if the header did not include an inverse. The accuracy of the inverse
+transformation has also been improved, although it may now be slower to
+evaluate in some circumstances.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V7.3.4}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V7.3.3 and V7.3.4:
+
+\begin{enumerate}
+
+\item By default, the simplification of Polygons no longer checks that the
+edges are not bent by the simplification. A new attribute, \htmlref{SimpVertices}{SimpVertices},
+can be set to zero in order to re-instate this check.
+
+\item The \htmlref{Polygon}{Polygon} class has a new mathod,
+astConvex,
+that returns a Polygon representing the shortest polygon (i.e. convex
+hull) enclosing a specified set of pixel values within a supplied array.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V8.0.0}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V7.3.4 and V8.0.0:
+
+\begin{enumerate}
+
+\item AST is now distributed under the Lesser GPL licence.
+
+\item The \htmlref{PolyMap}{PolyMap} class now uses files copied from the C/C++ Minpack
+package (see \url{http://devernay.free.fr/hacks/cminpack/index.html}) to perform
+least squares fitting of N-dimensional polynomials.
+
+\item Use of the IAU SOFA library has been replaced by ERFA library, which is
+a re-badged copy of SOFA distributed under a less restrictive license. A
+copy of ERFA is included within AST.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V8.0.1}
+
+The following describes the most significant changes which
+occurred in the AST library between versions V8.0.0 and V8.0.1:
+
+\begin{enumerate}
+
+\item The \htmlref{Base}{Base} and \htmlref{Current}{Current} attributes of a \htmlref{FrameSet}{FrameSet} may now be set using the
+  \htmlref{Domain}{Domain} name or the index of the required \htmlref{Frame}{Frame}.
+\item The order of WCS axes within new FITS-WCS headers created by \htmlref{astWrite}{astWrite}
+  can now be controlled using a new attribute called \htmlref{FitsAxisOrder}{FitsAxisOrder}.
+\item Supported added for FITS XPH (polar HEALPIX) projection.
+\item The macro used to invoke the \htmlref{astAppendString}{astAppendString} utility function has
+  changed to allow printf-style converstions to be included in the
+  supplied text. Any code that uses this macro must be re-compiled.
+\item The astRebin and astRebinSeq family of functions now include support
+  for arrays with char (byte) and unsigned char (unsigned byte) data types.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V8.0.2}
+The following describes the most significant changes which
+occurred in the AST library between versions V8.0.1 and V8.0.2:
+
+\begin{enumerate}
+\item For security reasons, the change introduced to \htmlref{astAppendString}{astAppendString} in
+  V8.0.1 has been moved to a new function called \htmlref{astAppendStringf}{astAppendStringf}, and
+  astAppendString itself has been reverted to its V8.0.0 version.
+  Any software that has been built against V8.0.1 will need to be
+  re-compiled and re-linked against V8.0.2.
+\end{enumerate}
+
+
+\subsection{Changes Introduced in V8.0.3}
+The following describes the most significant changes which
+occurred in the AST library between versions V8.0.2 and V8.0.3:
+
+\begin{enumerate}
+
+\item Methods
+astRebin, astRebinSeq, astResample and \htmlref{astTranGrid}{astTranGrid}
+now report an error if an array is specified that has more pixels than
+can be counted by a 32 bit integer.
+\item The hypertext documentation is now generated using Tex4HT rather
+than latex2html. The format of the hypertext docs has changed significantly.
+\item Another bug fix associated with reading CAR projections from
+FITS-WCS headers.
+\item Constructor options strings of the form ``\texttt{..., "\%s", text );}''
+can now be supplied. This avoids a security issue associated with the
+alternative form ``\texttt{..., text );}''.
+\end{enumerate}
+
+\subsection{Changes Introduced in V8.0.4}
+The following describes the most significant changes which
+occurred in the AST library between versions V8.0.3 and V8.0.4:
+
+\begin{enumerate}
+
+\item The behaviour of the
+\htmlref{astAddFrame}{astAddFrame} method has been changed slightly. Previously, astAddFrame
+modified the \htmlref{FrameSet}{FrameSet} by storing references to the supplied \htmlref{Mapping}{Mapping} and
+\htmlref{Frame}{Frame} objects within the FrameSet. This meant that any subsequent changes
+to the current Frame of the modified FrameSet also affected the supplied
+Frame object. Now, deep copies of the Mapping and Frame objects (rather
+than references) are stored within the modified FrameSet. This means that
+subsequent changes to the modified FrameSet will now have no effect on
+the supplied Frame.
+
+\item The choice of default tick-mark gaps for time axes has been
+improved, to avoid a previous issue which could result in no suitable gap
+being found.
+
+- A new method called
+\htmlref{astRegionOutline}{astRegionOutline}
+has been added to the \htmlref{Plot}{Plot} class. It draws the outline of a supplied AST
+\htmlref{Region}{Region}.
+
+\item A bug has been fixed that could cause astSimplfy to enter an infinite loop.
+
+\item Some improvements have been made to the Mapping simplification process
+that allow more Mappings to be simplified.
+
+\item The Frame class has a new read-only attribute called InternalUnit,
+which gives the units used for the unformatted (i.e. floating-point) axis
+values used internally by application code. For most Frames, the
+InternalUnit value is just the same as the Unit value (i.e. formatted and
+unformatted axis values use the same units). However, the \htmlref{SkyFrame}{SkyFrame} class
+always returns ``\texttt{rad}'' for InternalUnit, regardless of the value of
+Unit, indicating that floating-point SkyFrame axis values are always in units
+of radians.
+
+\item The \htmlref{LutMap}{LutMap} class has a new attribute called \htmlref{LutEpsilon}{LutEpsilon}, which specifies
+the relative error of the values in the table. It is used to decide if
+the LutMap can be simplified to a straight line.
+
+\end{enumerate}
+
+
+\subsection{Changes Introduced in V8.0.5}
+The following describes the most significant changes which
+occurred in the AST library between versions V8.0.4 and V8.0.5:
+
+\begin{enumerate}
+
+\item The \htmlref{SkyFrame}{SkyFrame} class has a new attribute called \htmlref{SkyTol}{SkyTol}, which specifies
+the smallest significant distance within the SkyFrame. It is used to
+decide if the \htmlref{Mapping}{Mapping} between two SkyFrames can be considered a unit
+transformation. The default value is 0.001 arc-seconds.
+
+\item A bug has been fixed in the \htmlref{FitsChan}{FitsChan} class that prevented illegal
+characters within FITS keyword names (i.e. characters not allowed by the
+FITS standard) being detected. This bug could under some circumstances
+cause a subsequent segmentation violation to occur.
+
+\item A ``BadKeyName'' warning is now issued by the FitsChan class if a FITS
+keyword name is encountered that contains any illegal characters. See
+attribute ``\htmlref{Warnings}{Warnings}'' and
+function ``\htmlref{astWarnings}{astWarnings}''.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V8.1.0}
+The following describes the most significant changes which
+occurred in the AST library between versions V8.0.5 and V8.1.0:
+
+\begin{enumerate}
+
+\item The configure script has a new option ``--without-fortran'' that allows
+AST to be built in situations where no Fortran compiler is available. The
+resulting library has no Fortran interface and so cannot be used within
+Fortran applications. Also, the link scripts do not attempt to include the
+fortran runtime libraries.
+
+\end{enumerate}
+
+\subsection{\xlabel{changes}\xlabel{list_of_most_recent_changes}Changes
+Introduced in V8.2}
+The following describes the most significant changes which
+occurred in the AST library between versions V8.1.0 and V8.2.0:
+
+\begin{enumerate}
+
+\item A new class of \htmlref{Mapping}{Mapping} called \htmlref{UnitNormMap}{UnitNormMap} has been added that converts
+a vector to a unit vector relative to a specified centre, plus length. A
+UnitNormMap has N inputs and N+1 outputs.The lower N output coordinates
+represent a unit vector parallel to the supplied input vector, and the
+(N+1)'th output coordinate is the length of the input vector.
+
+\item The restriction that Mappings are immutable has been extended to all
+Mapping classes. This means that attributes representing parameters of
+a Mapping's forward or inverse transformation cannot be changed after
+the Mapping has been created. In order to minimise the risk to existing
+software, this rule does not apply to Mappings that have not yet been
+included in other objects such as CmpMaps or FrameSets, or which have not
+yet been cloned. In other words, an error is reported if an attempt is
+made to change the nature of a Mapping's transformation, but only if the
+reference count of the Mapping is greater than one. The Mapping classes
+affected include: \htmlref{GrismMap}{GrismMap}, \htmlref{LutMap}{LutMap}, \htmlref{PcdMap}{PcdMap}, \htmlref{SphMap}{SphMap}, \htmlref{WcsMap}{WcsMap} and \htmlref{ZoomMap}{ZoomMap}.
+
+\end{enumerate}
+
+
+\subsection{Changes Introduced in V8.3}
+The following describes the most significant changes which
+occurred in the AST library between versions V8.2.0 and V8.3.0:
+
+\begin{enumerate}
+
+\item A new method called \htmlref{astAxNorm}{astAxNorm}
+has been added to the \htmlref{Frame}{Frame} class that normalises an array of axis
+values. When used with SkyFrames, it allows longitude values to be
+normalised into the shortest range.
+
+
+\item A bug has been fixed in the \htmlref{astGetRegionBounds}{astGetRegionBounds} method that could
+cause the wrong bounds to be returned for regions spanning a longitude =
+zero singularity.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V8.4}
+The following describes the most significant changes which
+occurred in the AST library between versions V8.3.0 and V8.4.0:
+
+\begin{enumerate}
+
+\item The PAL library files included in the AST distribution have been updated
+to PAL version 0.9.7.
+
+\item Multiple identical NormMaps in series will now be simplified to a
+single \htmlref{NormMap}{NormMap}.
+
+\item A NormMap that encapsulates a basic \htmlref{Frame}{Frame} will now be simplified to a
+\htmlref{UnitMap}{UnitMap}.
+
+\item The \htmlref{astTimeAdd}{astTimeAdd}
+method of the \htmlref{TimeMap}{TimeMap} class now include an extra argument that gives the
+number of values supplied in the arguments array. Note, any existing code
+that uses this method will need to be changed.
+
+\item The \htmlref{astSlaAdd}{astSlaAdd}
+method of the \htmlref{SlaMap}{SlaMap} class now include an extra argument that gives the
+number of values supplied in the arguments array. Note, any existing code
+that uses this method will need to be changed.
+
+\item The \htmlref{astSpecAdd}{astSpecAdd}
+method of the \htmlref{SpecMap}{SpecMap} class now include an extra argument that gives the
+number of values supplied in the arguments array. Note, any existing code
+that uses this method will need to be changed.
+
+\item Multiple identical NormMaps in series will now be simplified to a
+single NormMap.
+
+\item A NormMap that encapsulates a basic Frame will now be simplified to a
+UnitMap.
+
+\item If the
+\htmlref{astMapRegion}{astMapRegion}
+method is used to map a \htmlref{Region}{Region} into a new Frame that has fewer axes than
+the original Region, and if the inverse transformation of the supplied
+\htmlref{Mapping}{Mapping} does not specify a value for the missing axes, then those axes
+are removed entirely from the Region. Previously they were retained, but
+automatically supplied with bad values. This affects the number of mesh
+points per axes for such Regions, and so affects the accuracy of overlap
+determination.
+
+\end{enumerate}
+
+\subsection{Changes Introduced in V8.5}
+The following describes the most significant changes which
+occurred in the AST library between versions V8.4.0 and V8.5.1:
+
+\begin{enumerate}
+
+\item - A new class of \htmlref{Mapping}{Mapping} called \htmlref{ChebyMap}{ChebyMap} has been added. This is a
+Mapping that implements Chebyshev polynomial transformations.
+
+\item A bug has been fixed in the \htmlref{PolyMap}{PolyMap} class that caused incorrect values
+to be returned for the \htmlref{TranForward}{TranForward} and \htmlref{TranInverse}{TranInverse} attributes if the PolyMap
+has been inverted.
+
+\item The \htmlref{KeyMap}{KeyMap} class has a new method called
+\htmlref{astMapGetC}{astMapGetC}
+which returns a named entry as a single string. If the entry is a vector
+the returned string is a comma-separated list of its elements, enclosed
+in parentheses.
+
+\item If the
+function that delivers error messages to the user (astPutErr)
+is re-implemented, the new version can now be registered at run-time using
+the new
+\htmlref{astSetPutErr}{astSetPutErr} function.
+Previously, the new version needed to be linked into the application at
+build time.
+
+
+\item The \htmlref{Frame}{Frame} class now has a new attribute caled DTAI, which can be used
+to specify the number of leap seconds at the moment represented by the
+Frame's \htmlref{Epoch}{Epoch} attribute. By default, the internal look-up table of leap
+seconds contained within AST is used. The DTAI attribute allows old
+versions of AST, which may not include the most recent leap seconds, to
+be used with new data.
+
+\item The \htmlref{TimeMap}{TimeMap} class has been changed so that some conversions now require
+a ``\htmlref{Dtai}{Dtai}'' value (\emph{i.e.} the number of leap seconds) to be supplied by the
+caller. If AST\_\_BAD is supplied for ``Dtai'', the internal look-up table of
+leap seconds contained withn AST will be used. The conversions affected
+are those between TAI and UTC, and those between TT and TDB.
+
+\end{enumerate}
+
+\subsection{\xlabel{changes}\xlabel{list_of_most_recent_changes}Changes
+Introduced in V8.6}
+The following describes the most significant changes which have
+occurred in the AST library between versions V8.5.1 and V8.6.2 (the
+current version):
+
+\begin{enumerate}
+
+\item The behaviour of the \htmlref{astLinearApprox}{astLinearApprox} method of the \htmlref{Mapping}{Mapping} class has
+been changed in cases where the Mapping being approximated generates bad
+(AST\_\_BAD) values for one or more of its outputs. Previously, any such
+Mapping would be deemed non-linear and no fit would be returned. Now, a
+fit is returned, provided the other outputs of the Mapping are linear,
+but the fit contains AST\_\_BAD values for the coefficients describing the
+bad Mapping output.
+
+\item The \htmlref{astWrite}{astWrite} method of the \htmlref{FitsChan}{FitsChan} class can now create FITS-WCS headers
+that include keyords describing focal plane distortion using the
+conventions of the Spitzer SIP scheme. This is however only possible if
+the \htmlref{SipOK}{SipOK} attribute of the FitsChan is set to a non-zero value (which is
+the default), and the \htmlref{FrameSet}{FrameSet} being written out contains an appropriate
+\htmlref{PolyMap}{PolyMap} that conforms to the requirements of the SIP convention.
+
+\item A new function call \htmlref{astCreatedAt}{astCreatedAt} is now available that returns the
+function name, file path and line number at which an AST object was first
+created. Note, there is no Fortran equivalent to this new C function.
+
+\item The number of digits used to format floating point values has been
+increased in order to avoid loss of precision when converting from binary
+to string and back to binary. This could cause very small changes in numerical
+values returned by AST functions.
+
+\item If a FrameSet is supplied as the ``map'' argument to \htmlref{astAddFrame}{astAddFrame}, it now
+extracts and stores the base->current Mapping from the supplied FrameSet.
+Previously, the entire FrameSet was stored as the Mapping.
+
+\end{enumerate}
+
+Programs which are statically linked will need to be re-linked in
+order to take advantage of these new facilities.
+
+\end{document}