%++++++++
%.IDENTIFICATION tofits.tex
%.PURPOSE        Man page of tofits, can be edited in LaTeX
%.AUTHOR         Francois Ochsenbein
%.VERSION   1.0	 15-Jul-1993: C-shell version(mods 1.1 to 1.9 deleted)
%.VERSION   2.0  15-Aug-1994: New C Version
%.VERSION   2.6  25-Mar-1997
%----------

\def\ifhtx{\iffalse}	% Ignored in HTX context
\ifhtx\else\def\A#1#2{#2}\fi
\def\pgm{{\bf tofits}\ }
\def\file{{\em file}}
\def\fih{{\em $\ast$.fih }}
\def\CDSdoc{{\em\A{http://vizier.u-strasbg.fr/doc/catstd.htx}
	{Standards for Astronomical Catalogues}}}
\def\ffile{{\em Documentation File ({\tt ReadMe}) }}

\begin{manpage} {1}{tofits}{Transform a set of documented files into FITS.}
	{Mar-1997}{FITS}
\syntax{ \pgm [{\bf--v}] 
	[{\bf--z$|$Z}]
	[{\bf--u}[{\bf1}$|${\bf2}]] 
	[{\bf--fih}] [{\bf--noh}] 
	[{\bf--nodata}] 
	[{\bf --m} {\em max\_records}]
	[{\bf --d} {\em data\_directory}]
	[{\bf --r} {\em description\_file}]
	[{\bf --h} {\em SIMPLEheader\_file}]
	[{\bf --o} {\em output\_file}]
	[{\bf--w}[{\bf.fih}]] 
	[[{\bf--t} {\em table\_structure}] {\em input\_file...}] }

\mansec{ Description }
The \pgm command translates a set of files described according to the
CDS Standards (see the \CDSdoc\ document) into FITS tables. 

The result may consist of either plain FITS files (bulk files including
data description and the corresponding values), or of only the
{\em headers}, i.e. the description of the data as plain ascii files;
the latter files are normally named \fih files.

The creation of the plain FITS files follows the following algorithm:
\begin{itemize}
\item	With the {\bf--fih} option, from a set of {\em FITS headers}
	files (\fih files) and of data files as follows:
	\begin{enumerate}
	\item	the basic {\em FITS header} (on top of all tables) 
		is specified via the {\bf --h} option; its
		default name is {\tt SIMPLE.fih}
	\item	for each table, the {\em TABLE header} and the data file,
		files named \file{\tt.fih} and \file.
	\end{enumerate}
	The complete FITS creation for a set of $n$ tables therefore
	requires $2n+1$ files, the data tables plus $n+1$ \fih files.
\item	Without the {\bf--fih} option, the \ffile (see also anafile(1)) 
	is used to generate 
	the missing \fih files. A full FITS generation may if
	necessary be driven by a special shell script stored in 
	a file named {\tt.MakeFITS}.
\end{itemize}

Note that some files (e.g. tex files, HTML, postscript files) are not
converted to FITS.

\mansec{Options}
Without any option, \pgm uses the {\tt ReadMe} file and the data files 
in the current directory and transforms all files described in {\tt ReadMe}
into a single FITS file displayed on the terminal.

\option{--d {\em data\_directory}}
	indicates the directory containing the relevant files
	(data files, \fih files, the {\tt ReadMe} if not specified
	by the {\bf--r} option).
	The default {\em data\_directory} is the current directory.
\option{--fih}
	tells that no {\tt ReadMe} file is required, all descriptions
	do exist as \fih files; the top header is named {\tt SIMPLE.fih},
	unless another name is specified via the {\bf--h} option.
\option{--h {\em SIMPLEheader\_file}}
	provides an alternative name to {\tt SIMPLE.fih}
	(see option {\bf--fih})
\option{--help}
	displays a detailed help.
\option{--r {\em description\_file}}
	provides the non-standard ({\tt Intro} or {\tt ReadMe}) name
	of the {\em Description file};
\option{--m {\em max\_records}}
	asks to limit the generated {\em FITS} file to the specified
	number of records.
	By default, all records are converted to {\em FITS}.
\option{--nodata}
	asks to generate only {\em FITS headers} (similar to \fih files);
	the data files are ignored.
\option{--noh}
	asks not to generate the top ({\em SIMPLE}) header; this option
	is especially useful to append a new FITS table to an
	existing FITS data set.
\option{--o {\em output\_file}}
	designates the file replacing the default {\em stdout} (terminal).
	The usage of a disk file allows to rewrite the actual number
	of records (the {\tt NAXIS2} parameter), when the number
	of records stored in the {\tt ReadMe} is not correct
	(e.g. with the {\bf--t} option). 
	{\em Note that this option is not compatible with the compression.}
\option{--t {\em table\_structure}}
	indicates that the next {\em file} argument designates a
	data file which contains data {\em structured like
	table\_structure} (for instance an excerpt of a table).
	{\em table\_structure} is therefore a name which must exist
	in one of the {\em Byte-by-byte Description ...} section in the
	{\tt ReadMe} file. \\
	A value of {\tt-} for {\em table\_structure} asks to stop this
	behaviour.
\option{--u}
	allows to select how to write the comments related to the units:
	the {\bf--u1} option comments each unit with its SI ({\em Syst\`eme
	International}) value, while {\bf--u2} option comments each unit
	with both litteral and SI counterpart.
\option{--v}
	is a verbose option.
\option{--w.fit}
	asks to write a new file for each FITS table; with this option,
	there are as many FITS files generated as data files, each being
	a complete FITS file including the {\em top header}, a
	{\em table header} and the corresponding data. 
	The names of the files generated this way have a {\tt.fit}
	extension.
\option{--w.fih}
	asks to write a new file for each {\em table header}
	(generation of \fih files).
	The names of the files generated this way have a {\tt.fih}
	extension.
\option{--Z}
	compresses the resulting files with the standard Unix
	{\bf compress}(1) routine. The output cannot be put in a file
	(incompatible with {\bf--o} option)
\option{--z}
	compresses the resulting files with the {\bf gzip}(1) utility. 
	The output cannot be put in a file
	(incompatible with {\bf--o} option)

\mansec{Files}
The \file... specified on the command line represent the files
which should be converted to FITS. If a \file\ was preceded
by a {\bf--t} option, \file\ is assumed to have the same structure
as the {\bf--t} {\em table\_structure} argument ({\bf--} stands
for the standard input).

The default is to convert 
{\em all described files}, i.e. all files included in the
{\em File Summary} section of the {\tt ReadMe} file, with the
exception of the non-convertable files.

A dash {\bf--} or a dollar sign {\bf\$} 
as a file name asks to stop the conversion;
this is useful if one wants to generate only the {\em top header},
as in

\begin{verbatim}
tofits -nodata -r DescriptionFile - > SIMPLE.fih
\end{verbatim}

Note that if the  \file\ argument is a directory, it has the same
effect as it were preceded by the{\bf--d} flag.

\mansec{Non-converted files}
The extension of filenames is used to decide that a file should not
be converted into FITS. Files with names ending by {\tt.fih}, {\tt.fis}, 
{\tt.tex}, {\tt.dvi}, {\tt.ps}, {\tt.pdf}, {\tt.doc}, {\tt.sty},
{\tt.htm}, {\tt.html}, {\tt.tar} and {\tt.tgz}
are not converted.

\mansec{.MakeFITS script}
When a {\tt.MakeFITS} file exists, it is called from \pgm (via the
{\em Bourne shell} {\tt/bin/sh}) to generate {\em all} FITS files:
this can be executed only when \pgm\ is called without any
\file\ argument.

This script may use (and change) the following numeric environment variables
which are set by \pgm before calling {\tt.MakeFITS}:
\begin{itemize}
\item	{\tt toFITSd}=0 \quad to generate only the headers (option 
	{\bf--nodata})
\item	{\tt toFITSh}=0 \quad to skip the SIMPLE header
	(option {\bf--noh})
\item	{\tt toFITSm}=1 \quad to use the {\tt FILEMARK} extension
	(which separates two FITS files)
\item	{\tt toFITSr}=1 \quad is the recursivity count, incremented
	each time \pgm is called. 
\end{itemize}

The {\tt.MakeFITS} script may (recursively) call \pgm.

\mansec{Returned Status}
The \pgm command returns 0 in case of success, and
non-zero when errors are found.

\mansec{Examples}
\begin{itemize}
\item	Convert the files in current directory which are documented in
	the standard way: \\
	{\tt tofits > catalog.fits}
\item	Convert the files of catalogue I/219 into a single compressed 
	FITS file: \\
	{\tt tofits -z /ftp/cats/I/219 > 1219.fgz}
\item	Extract the correlation coefficients (indicated by the {\tt CORR} 
	string) from the Hipparcos catalogue stored on a CD-ROM 
	(the description file is named {\tt tofits.dat}, the
	correlation coefficients table is described by {\tt h\_dm\_cor.dat}):\\
	{\tt grep CORR /cd/cats/hip\_dm\_c.dat \b \\
	| tofits -r /cd/fits/tofits.dat -t h\_dm\_cor.dat -o h\_dm\_cor.fit}
	
\end{itemize}

\seealso{anafile(1)    compress(1)   gzip(1)  ``\CDSdoc''}
\end{manpage}
