1 files changed, 122 insertions, 0 deletions
diff --git a/funtools/doc/pod/funmerge.pod b/funtools/doc/pod/funmerge.pod
new file mode 100644
index 0000000..0cb9216
--- /dev/null
+++ b/funtools/doc/pod/funmerge.pod
@@ -0,0 +1,122 @@
+=pod
+
+=head1 NAME
+
+
+
+B<funmerge - merge one or more Funtools table files>
+
+
+
+=head1 SYNOPSIS
+
+
+
+
+
+funmerge  [-w|-x] -f [colname] <iname1> <iname2>  ... <oname>
+
+
+
+
+
+=head1 OPTIONS
+
+
+
+
+
+  -f    # output a column specifying file from which this event came
+  -w    # adjust position values using WCS info
+  -x    # adjust position values using WCS info and save old values
+
+
+
+
+=head1 DESCRIPTION
+
+
+
+
+B<funmerge> merges FITS data from one or more
+FITS Binary Table files
+or raw event files.
+
+The first argument to the program specifies the first input FITS table
+or raw event file. If "stdin" is specified, data are read from the
+standard input.  Use Funtools Bracket
+Notation to specify FITS extensions and row filters.  Subsequent
+arguments specify additional event files and tables to merge. (NB: Stdin
+cannot not be used for any of these additional input file arguments.)
+The last argument is the output FITS file. The columns in each input table
+must be identical.
+
+
+If an input file begins with the '@' character, it is processed as an
+include file, i.e., as a text file containing event file names (as
+well as blank lines and/or comment lines starting with the '#' sign).
+If standard input is specified as an include file ('@stdin'), then
+file names are read from the standard input until EOF (^D).  Event
+files and include files can be mixed on a command line.
+
+
+Rows from each table are written sequentially to the output
+file.  If the switch B<-f [colname]> is specified on the command
+line, an additional column is added to each row containing the number
+of the file from which that row was taken (starting from one). In
+this case, the corresponding file names are stored in the header
+parameters having the prefix B<FUNFIL>, i.e., FUNFIL01,
+FUNFIL02, etc.
+
+
+Using the B<-w> switch (or B<-x> switch as described
+below), B<funmerge> also can adjust the position column values
+using the WCS information in each file. (By position columns, we mean
+the columns that the table is binned on, i.e., those columns defined
+by the B<bincols=> switch, or (X,Y) by default.) To perform WCS
+alignment, the WCS of the first file is taken as the base WCS.  Each
+position in subsequent files is adjusted by first converting it to the
+sky coordinate in its own WCS coordinate system, then by converting
+this sky position to the sky position of the base WCS, and finally
+converting back to a pixel position in the base system. Note that in
+order to perform WCS alignment, the appropriate WCS and TLMIN/TLMAX
+keywords must already exist in each FITS file.
+
+When performing WCS alignment, you can save the original positions in
+the output file by using the B<-x> (for "xtra") switch instead
+of the B<-w> switch (i.e., using this switch also implies using
+B<-w>) The old positions are saved in columns having the same
+name as the original positional columns, with the added prefix "OLD_".
+
+Examples:
+
+
+Merge two tables, and preserve the originating file number for
+each row in the column called "FILE" (along with the corresponding
+file name in the header):
+
+  [sh] funmerge -f "FILE" test.ev test2.ev merge.ev
+
+
+
+Merge two tables with WCS alignment, saving the old position values in
+2 additional columns:
+
+  [sh] funmerge -x test.ev test2.ev merge.ev
+
+
+
+This program only works on raw event files and binary tables. We have
+not yet implemented image and array merging.
+
+
+
+
+=head1 SEE ALSO
+
+
+
+See funtools(n) for a list of Funtools help pages
+
+
+=cut