Install ast.h and grf.h into $STARLINK/include/star

By default, the header files are also included into $STARLINK/include for
the benefit of legacy code, but this can be prevented using the new
"--without-topinclude" configure option.

Makefile.am

@@ -592,11 +592,21 @@ dist_noinst_SCRIPTS = makeh
 
 # Headers required by library users.  Both of the following lines
 # indicate headers which are installed.
-include_HEADERS = GRF_PAR grf.h grf3d.h
+cincludedir = $(includedir)/star
+cinclude_HEADERS = GRF_PAR grf.h grf3d.h
 # Following are generated, so should not be distributed.
-nodist_include_HEADERS = ast.h AST_PAR
+nodist_cinclude_HEADERS = ast.h AST_PAR
 include_MESSAGES = AST_ERR ast_err.h
 
+# Also install headers in main include directory for the benefit of
+# legacy code that does '#include "ast.h"' instead of '#include
+# "star/ast.h"'. Note, currently _MESSAGES files must be installed in
+# the main include directory.
+if TOPINCLUDE
+include_HEADERS = GRF_PAR grf.h grf3d.h
+nodist_include_HEADERS = ast.h AST_PAR
+endif
+
 if EXTERNAL_PAL
 PAL_LIB =
 else

ast.news

@@ -1,6 +1,6 @@
 AST Library
 -----------
-   A new release (V8.7.1) of the Starlink AST (astrometry) library is
+   A new release (V8.7.2) of the Starlink AST (astrometry) library is
 now available.
 
    AST provides a comprehensive range of facilities for attaching
@@ -18,6 +18,15 @@ environment-independent.
 Main Changes in this Version
 ----------------------------
 
+- By default, the AST header file "ast.h" is now installed into both
+$STARLINK_DIR/include and $STARLINK_DIR/include/star. The new configure
+option "--without-topinclude" can be used to prevent the header file
+being installed into $STARLINK_DIR/include.
+
+
+Main Changes in V8.7.1
+----------------------
+
 - The Moc class now supports version 1.1 of the the MOC recommendation.
 This includes new support for string and JSON encoded MOCs. See methods
 astGetMocString and astAddMocString in the Moc class, and also the new

component.xml

@@ -2,7 +2,7 @@
 <!DOCTYPE component SYSTEM "componentinfo.dtd">
 
 <component id="ast" support="S">
-  <version>8.7.1</version>
+  <version>8.7.2</version>
   <path>libext/ast</path>
   <description>WCS library</description>
   <abstract>

configure.ac

@@ -7,7 +7,7 @@ dnl   1.5.  It should work with autoconf versions 2.50 or better, and
 dnl   automake 1.6 or better.
 
 dnl   Initialisation: package name and version number
-AC_INIT([ast],[8.7.1],[[email protected]])
+AC_INIT([ast],[8.7.2],[[email protected]])
 AC_CONFIG_AUX_DIR([build-aux])
 
 dnl   Require autoconf-2.50 at least
@@ -21,6 +21,22 @@ AC_CONFIG_SRCDIR([ast_link.in])
 #   Include defaults for Starlink configurations
 STAR_DEFAULTS
 
+#   See if the --without-topinclude option has been provided. This sets the
+#   automake conditional TOPINCLUDE. By default header files are installed
+#   into both includedir and includedir/star. If --without-topinclude is
+#   specified when running configure, then the header files are only
+#   installed into includedir/star.
+AC_ARG_WITH(
+      [topinclude],
+      AS_HELP_STRING([--without-topinclude],[install headers only in includedir/star - not includedir]),
+      if test "$withval" = "yes"; then
+         topinclude="1"
+      else
+         topinclude="0"
+      fi,
+      topinclude="1")
+AM_CONDITIONAL(TOPINCLUDE, test x$topinclude = x1)
+
 #   See if the --with-starmem option has been provided. This sets the
 #   preprocesor macro HAVE_STAR_MEM_H.
 AC_ARG_WITH(

sun_master.tex

@@ -18,12 +18,12 @@
 \stardocnumber      {210.28}
 f-
 \stardocauthors     {R.F. Warren-Smith \& D.S. Berry}
-\stardocdate        {6th December 2018}
+\stardocdate        {7th August 2019}
 \stardoctitle     {AST\linebreak%
                                 A Library for Handling\linebreak%
                                 World Coordinate Systems\linebreak%
                                 in Astronomy}
-\stardoccopyright   {Copyright (C) 2017 East Asian Observatory}
+\stardoccopyright   {Copyright (C) 2019 East Asian Observatory}
 \stardocversion     {V<VERSION_NUMBER>}
 c+
 \stardocmanual      {Programmer's Guide\\(C Version)}
@@ -231,7 +231,7 @@ \subsection{Other Design Objectives}
 \begin{small}
 \begin{terminalv}
 extern "C" {
-#include "ast.h"
+#include "star/ast.h"
 }
 \end{terminalv}
 \end{small}
@@ -771,7 +771,7 @@ \subsection{\ldots Structure an AST Program}
 \begin{small}
 \begin{terminalv}
 /* Include the interface to the AST library. */
-#include "ast.h"
+#include "star/ast.h"
 
 /* Main program (or could be any function). */
 main () {
@@ -2642,7 +2642,7 @@ \subsection{\label{ss:objectcreation}Object Creation and Pointers}
 c+
 \small
 \begin{terminalv}
-#include "ast.h"
+#include "star/ast.h"
 AstZoomMap *zoommap;
 
 ...
@@ -4504,7 +4504,7 @@ \subsection{Input and Output Coordinate Numbers}
 c+
 \small
 \begin{terminalv}
-#include "ast.h"
+#include "star/ast.h"
 AstZoomMap *zoommap;
 int nout;
 
@@ -5076,7 +5076,7 @@ \subsection{\label{ss:seriescmpmap}Combining Mappings in Series}
 c+
 \small
 \begin{terminalv}
-#include "ast.h"
+#include "star/ast.h"
 AstCmpMap *cmpmap;
 AstPermMap *permmap;
 AstZoomMap *zoommap;
@@ -5595,7 +5595,7 @@ \subsection{\label{ss:creatingframes}Creating a Frame}
 c+
 \small
 \begin{terminalv}
-#include "ast.h"
+#include "star/ast.h"
 astFrame *frame;
 
 ...
@@ -7634,7 +7634,7 @@ \subsection{Creating a SkyFrame}
 c+
 \small
 \begin{terminalv}
-#include "ast.h"
+#include "star/ast.h"
 AstSkyFrame *skyframe;
 
 ...
@@ -8299,7 +8299,7 @@ \subsection{Creating a SpecFrame}
 c+
 \small
 \begin{terminalv}
-#include "ast.h"
+#include "star/ast.h"
 AstSpecFrame *specframe;
 
 ...
@@ -8776,7 +8776,7 @@ \subsection{Creating a TimeFrame}
 c+
 \small
 \begin{terminalv}
-#include "ast.h"
+#include "star/ast.h"
 AstTimeFrame *timeframe;
 
 ...
@@ -9067,7 +9067,7 @@ \subsection{\label{ss:convertingskyframes}Converting between Celestial Coordinat
 c+
 \small
 \begin{terminalv}
-#include "ast.h"
+#include "star/ast.h"
 AstSkyFrame *skyframe1, *skyframe2;
 
 ...
@@ -9374,7 +9374,7 @@ \subsection{\label{ss:convertingspecframes}Converting between Spectral Coordinat
 c+
 \small
 \begin{terminalv}
-#include "ast.h"
+#include "star/ast.h"
 AstSpecFrame *specframe1, *specframe2;
 
 ...
@@ -9923,7 +9923,7 @@ \subsection{\label{ss:creatingaframeset}Creating a FrameSet}
 c+
 \small
 \begin{terminalv}
-#include "ast.h"
+#include "star/ast.h"
 AstFrame *frame1;
 
 ...
@@ -10598,7 +10598,7 @@ \subsection{\label{ss:framesetsfromconvert}Creating FrameSets with AST\_CONVERT}
 c+
 \small
 \begin{terminalv}
-#include "ast.h"
+#include "star/ast.h"
 AstFrameSet *cvt;
 AstSkyFrame *skyframe1, *skyframe2;
 
@@ -11727,7 +11727,7 @@ \subsection{\label{ss:creatingachannel}Creating a Channel}
 
 \small
 \begin{terminalv}
-#include "ast.h"
+#include "star/ast.h"
 AstChannel *channel;
 
 ...
@@ -12503,7 +12503,7 @@ \subsection{\label{ss:mixingchanneltext}Mixing Objects with other Text}
 
 \small
 \begin{terminalv}
-#include "ast.h"
+#include "star/ast.h"
 main() {
    AstChannel *channel;
    AstObject *object;
@@ -13126,7 +13126,7 @@ \subsection{\label{ss:creatingafitschan}Creating a FitsChan}
 c+
 \small
 \begin{terminalv}
-#include "ast.h"
+#include "star/ast.h"
 AstFitsChan *fitschan;
 
 ...
@@ -14337,7 +14337,7 @@ \subsection{\label{ss:identifyingfitsencoding}Identifying Foreign Encodings on I
 c+
 \small
 \begin{terminalv}
-#include "ast.h"
+#include "star/ast.h"
 #define MAXCARD 100
 AstFitsChan *fitschan;
 char *cards[ MAXCARD ];
@@ -15244,7 +15244,7 @@ \subsection{\label{ss:transformationfunctions}Writing a Transformation Routine}
 c+
 \small
 \begin{terminalv}
-#include "ast.h"
+#include "star/ast.h"
 #include <math.h>
 
 void SqrTran( AstMapping *this, int npoint, int ncoord_in,
@@ -16514,7 +16514,7 @@ \subsection{Plotting Symbols}
 c+
 \small
 \begin{terminalv}
-#include "ast.h"
+#include "star/ast.h"
 #define NCOORD 2
 #define NMARK 10
 double in[ NCOORD ][ NMARK ];
@@ -17319,8 +17319,17 @@ \subsection{\label{ss:accessingheaderfile}Accessing AST Include Files}
 
 c+
 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
+including all constants, function prototypes, macros, \emph{etc.}. It
+should usually be include into a C source file using the statement:
+
+\small
+\begin{terminalv}
+#include "star/ast.h"
+\end{terminalv}
+\normalsize
+
+The header file is usually stored within the directory ``/star/include/star''
+and should be located using the usual compiler options for finding C
 include files, for instance:
 
 \small
@@ -17331,6 +17340,14 @@ \subsection{\label{ss:accessingheaderfile}Accessing AST Include Files}
 
 This is preferable to specifying the file's absolute name within your
 software.
+
+Note, the default installation procedure places a copy of ``ast.h'' into
+both ``/star/include'' and ``/star/include/star''. This is for the benefit of
+legacy software that expects to find the AST header file in ``/star/include''
+rather than ``/star/include/star''. The installation of ``ast.h'' into
+``/star/include'' can be disabled at build-time by specifying the
+``--without-topinclude'' option when running the configure script.
+
 c-
 f+
 
@@ -21922,11 +21939,9 @@ \subsection{Changes Introduced in V8.7.0}
 
 \end{enumerate}
 
-\subsection{\xlabel{changes}\xlabel{list_of_most_recent_changes}Changes
-Introduced in V8.7.1}
-The following describes the most significant changes which have
-occurred in the AST library between versions V8.7.0 and V8.7.1 (the
-current version):
+\subsection{Changes Introduced in V8.7.1}
+The following describes the most significant changes which
+occurred in the AST library between versions V8.7.0 and V8.7.1:
 
 \begin{enumerate}
 
@@ -21938,6 +21953,22 @@ \subsection{\xlabel{changes}\xlabel{list_of_most_recent_changes}Changes
 \item The FitsChan class will now read FITS-WCS headers that have
 alternate axis descriptions but no primary axis descriptions.
 
+\end{enumerate}
+
+\subsection{\xlabel{changes}\xlabel{list_of_most_recent_changes}Changes
+Introduced in V8.7.2}
+The following describes the most significant changes which have
+occurred in the AST library between versions V8.7.1 and V8.7.2 (the
+current version):
+
+\begin{enumerate}
+
+\item By default, the AST header file ``ast.h'' is now installed into both
+\texttt{STARLINK\_DIR/include} and \texttt{STARLINK\_DIR/include/star}. The
+new configure option ``\texttt{--without-topinclude}'' can be used to prevent
+the header file being installed into \texttt{STARLINK\_DIR/include}.
+
+
 \end{enumerate}
 
 Programs which are statically linked will need to be re-linked in