%++++++++
%.IDENTIFICATION tabmap.tex
%.AUTHOR         Francois Ochsenbein, Steve Drake
%.VERSION   1.0	 18-Dec-2002
%----------

\def\pgm{{\bf tabmap}\ }
\def\file{{\em file}}
\def\fih{{\em $\ast$.fih }}
\def\CDSdoc{{\em CDS Standards for Astronomical Catalogues},
	e.g. http://vizier.u-strasbg.fr/doc/catstd.htx}
\def\ffile{{\em Documentation File ({\tt ReadMe}) }}

\begin{manpage} {1}{tabmap}{Transform a data file to various formats}
	{Nov-2012}{TABMAP}
\syntax{ \pgm [{\bf--v}] 
	[{\bf--b}]
	{\bf --form} {\em format\_type:a,c,p,t,h,H}
	[{\bf --data\_only}]
	[{\bf --head} {\em 1u-}]
	[{\bf --help}]
	[{\bf --i} {\em output\_text}]
	[{\bf --keep\_cols}]
	[{\bf --map} {\em mapping\_instructions}]
	[{\bf --ml} {\em max\_lines}]
	[{\bf --null} {\em null\_pattern}]
	[{\bf --skip} {\em lines}]
	[{\bf --tour}]
	[{\bf +{\em n}}]
	[{\bf --t {\em table\_name}}]
	[{\em input\_file}|--]... 
	[{\bf --go} {\em other\_edition}]... }

\mansec{ Description }
The \pgm command edits a file described according to the
CDS Standards (see the \CDSdoc\ document) into several other formats:
{\bf a}scii, {\bf c}olumn-separated-values, {\bf p}arfile, 
{\bf h}tx, {\bf H}tml. The columns to edit may be additionally chosen.

\mansec{Options}

\option{--data\_only}
	edits only the data (by default, titles/comments are also
	edited)

\option{--b}
	remove all non-significant blanks (heading + trailing blanks)
	in the edited results.

\option{--keep\_cols}
	keep the original columns.
	By default, \pgm merges the related columns into a single
	column, like the limit flag ({\tt l\_col}) together with 
	the value ({\tt col}), or a value with its error.
	However, in the {\bf--b} option, the columns are separated.

\option{--form {\em format\_type}}
	specifies the format of the output, in one of the flavors
	{\bf a}ascii, {\bf c}olumn-separated-values, {\bf p}arfile,
	{\bf h}tx, {\bf H}tml. Several additional characters can
	be used:
	\begin{itemize}
	\item	{\bf\tt*} to {\em trim} the leading/trailing blanks;
		two asterisks {\bf\tt**} remove only the trailing blanks,
		and three asterisks {\bf\tt***} squeeze all blanks.
	\item	the vertical bar {\bf\tt$|$} indicates that this character
		is to be used as column separator; 
		two vertical bars {\bf\tt$||$} ask to add also a the
		separator before the first column and after the last column
	\item	other punctuations specify the character used to separate
		the columns (the {\em tab} character is used by default).
	\end{itemize}

	In addition, the {\bf par} edition may include the following options:
	\begin{itemize}
	\item	{\bf\tt0} (the number 0) asks to remove the columns which
	        have no value. 
	\item	{\bf\^{ }} (the {\em carret}) introduces the
		leftmost character (the default is {\bf\^{ }\%} (percent).
	\item	{\bf($n[,n,n]$)} specifies the width to keep for
		the 3 columns {\bf label}, {\bf value}, {\bf unit}.
		A negative value asks for a left-adjustment.
	\end{itemize}

\option{--go}
	indicates the end of directives for an edition; a new edition
	can be started with the same or other tables.

\option{--head {\em header\_lines}}
	controls the header lines, with the symbols
	\begin{itemize}
	\item	{\bf 1} to edit the {\em labels} (column headers)
	\item	{\bf u} to edit the {\em units} of each column
	\item	{\bf --} to edit a line with dashes.
	\end{itemize}

\option{--help}
	displays a detailed help.

\option{--map {\em mapping\_instructions}}
	gives the mapping instructions, designating the columns by
	{\tt\$\{}{\em name}{\tt\}} or {\tt@\{}{\em name}{\tt\}}.
	{\em name} may however be preceded by one to three asterisks
	{\bf\tt*} to ask for removing the blanks, as in the {\bf----form}
	option.

	Note that the {\em mapping\_instructions} may consist of just
	the list of columns to write --- if no {\bf\$} exists in the
	instructions. In this context, the {\bf$\ast$} represents
	all non-explicitely-quoted columns.

	A few special variables written {\tt\$\{\$}{\em name}{\tt\}}
	can be used, with the meaning:
	\begin{itemize}
	\item {\bf\fg{red4}\tt\$\{\$table\}} : the name of the table
	\item {\bf\fg{red4}\tt\$\{\$pos\}} : the position 
		(all components of the position of the object)
	\item {\bf\fg{red4}\tt\$\{\$PK\}} : the primary key (if known)
	\end{itemize}

	By default, all columns are edited.

\option{--ml {\em max\_lines}}
	asks to stop the edition after the specified number of data lines.

\option{--null {\em null\_pattern}}
	specifies how to write the {\em NULL} values. By default, no special
	action is taken for NULL values.

\option{--par}
	is a synonym to {\tt--form p} ({\em parfile} output).

\option{--skip {\em lines}}
	asks to skip (ignore) the specified number of {\em data lines}
	before starting the edition. Notice that the {\em comment 
	lines} are not counted as data lines.

\option{--t}
	specifies that the input file is formatted as the {\em table}
	described in the {\tt ReadMe}; the {\bf--} (minus)
	specifies the actual data is in the standard input

\option{--tour}
	is a testing option; which writes only 10 lines of the file
	in each of the available forms.

\option{--v}
	is a verbose option.

\option{+{\em n}}
	asks to start at $n^{th}$ line.
	The difference with the {\bf--skip} option is that
	the first $n-1$ lines are skipped, whatever their status
	(data or comment lines).

\mansec{Files}
The \file\ specified on the command line represents
the name of a data file to transform. The special value {\bf .}
(the dot) represents all files described, and {\bf--} (the minus)
represents the standard input. In this last case, the {\bf--t} option
should be specified to describe what is the contents of the standard
input.

Several files may be specified, either as a {\em comma-separated list}
({\tt\fg{red4}table1.dat,table2.dat}), or as a space-separated list.
In the space-separated list, a blank line indicates that the next
file is edited; for a comma-separated list, no blank line is issued,
i.e. no marker indicates a change of file.

\mansec{Returned Status}
The \pgm command returns 0 in case of success, 1 in case of error;
missing arguments for which defaults have been taken return a status of 2.

\mansec{Examples}
\begin{itemize}
\item	Convert the {\tt v3885sgr.dat} file of catalogue {\tt J/A+AS/101/87}
into a file usable for plotting (date and V flux): \\
{\tt 
tabmap -form a -null NaN -map '${BJED-2447000} ${V}' /ftp/cats/J/A+AS/101/87}
\end{itemize}

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