update ast 8.6.2

1 files changed, 0 insertions, 52927 deletions

diff --git a/ast/sun211.tex b/ast/sun211.tex
deleted file mode 100644
index 9618cab..0000000
--- a/ast/sun211.tex
+++ /dev/null
@@ -1,52927 +0,0 @@
-\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.27}
-\stardocauthors     {R.F. Warren-Smith \& D.S. Berry}
-\stardocdate        {26th October 2016}
-\stardoctitle     {AST\linebreak%
-                                A Library for Handling\linebreak%
-                                World Coordinate Systems\linebreak%
-                                in Astronomy}
-\stardoccopyright   {Copyright (C) 2014 Science \& Technology Facilities Council}
-\stardocversion     {V8.4}
-\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}).
-
-\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
-      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
-      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{
-   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{
-   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{
-   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
-         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{
-   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 which a character variable
-      which 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{
-   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, an iterative method can be used
-      to evaluate the inverse based only on the forward transformation.
-   }
-   \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
-         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{
-         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, an 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{"} .
-      }
-   }
-   \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{
-   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.
-      }
-      \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): Convert a TAI MJD to a UTC MJD.
-
-         \sstitem
-         \texttt{"} UTCTOTAI\texttt{"}  (MJDOFF): 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): Convert a TT MJD to a TDB MJD.
-
-         \sstitem
-         \texttt{"} TDBTOTT\texttt{"}   (MJDOFF, OBSLON, OBSLAT, OBSALT): 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
-         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.
-
-      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.
-
-      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{
-   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{
-   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.
-   }
-   \sstattributetype{
-      Integer (boolean).
-   }
-   \sstapplicability{
-      \sstsubsection{
-         PolyMap
-      }{
-         All PolyMaps have this attribute.
-      }
-   }
-   \sstnotes{
-      \sstitemlist{
-
-         \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, headers that
-      use this convention are still to be found, for instance the SCAMP
-      utility (http://www.astromatic.net/software/scamp) creates them.
-
-      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{
-   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 teh 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{
-   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{TabOK}{TabOK}: Should the FITS \texttt{"} -TAB\texttt{"}  algorithm be recognised?
-
-         \sstitem
-         \htmlref{PolyTan}{PolyTan}: Use \htmlref{PVi\_m}{PVi\_m} keywords to define distorted TAN projection?
-
-         \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{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{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{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, an iterative method can be used
-      to evaluate the inverse based only on the forward transformation.
-   }
-   \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{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.
-
-      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.
-
-      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{\xlabel{changes}\xlabel{list_of_most_recent_changes}Changes
-Introduced in V8.4}
-The following describes the most significant changes which have
-occurred in the AST library between versions V8.3.0 and V8.4.0 (the
-current version):
-
-\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}
-
-Programs which are statically linked will need to be re-linked in
-order to take advantage of these new facilities.
-
-\end{document}