!  Catalog data file -- example and explanation
! Any line beginning with the ! character is a comment
# So is any line beginning with the # character
! And, anything in a line starting with ! or # is commentary.
!
! The FIRST character in a line is treated specially, it
! identifies the type of object.  A @ character denotes an
! observed object, and a * character denotes a reference
! or position alignment star.
!
! Fields within a line are separated by "whitespace" which is
! any number of contiguous spaces or tabs.  This means that no
! field can contain any space or tab character!
!
! There are 3 required fields immediately following the initial
! character in a line:  name, right ascension, declination
!
! All fields following the [name, right ascension, declination] set
! are optional.  If they are not present, default values are used.
! These optional fields are described below.
!
! Any characters starting with the first ! or # following the first
! character in the line, and continuing to the end of the line are
! an in-line comment.  Such a comment is associated with the object,
! and is repeated at the end of the object line associated with that
! object in other files generated by the software system, such as
! the .SMF, .obw and .obx files.  Anything associated with the object
! may be put in such a comment and passed through the software system.
!   (NOTE that this is a release 2.08 feature)
!
! Often, one begins the file with some comments indicating what the
! object list is for, how it was made, other files which it may be
! used with, the center position to be used in the .obs file,
! and any other things which might be needed later.
!
#  This is a test file with no scientific purpose
#  center about 2.50  -0.000
!
! We will need at least a few reference stars:
*ref1  02:30:38  0:11:32
*ref2  02:29:22  0:11:31
*ref3  02:29:21 -0:11:16
!
! The right ascension is in hours, and declination in degrees.
! We can use colons to separate hours:minutes:seconds and
! degrees:minutes:seconds.  These sub-fields may also have
! decimal fractions within them.  Or, we can have decimal hours
! and decimal degrees.  The program is smart enough to mix
! these, as long as there are no spaces in the field.
!
*ref4  02.499850 -0.165235
*ref5  02.501323 -0:00:12.44
!
! If your list has right ascension in degrees, that can be used,
! but all positions in the file must be done in the same way, with
! all the right ascensions in degrees.  To do that, put a line at the
! start of the file (at least before any data) which has starting in
! the first column, "&RADEGREE" - less the quotes, of course.  The
! special character & is used for advanced features.
!
! If your list has right ascension in degrees, it can be used, by
! adding a special line before those objects:
&RADEGREE
*ref6  37.50443 -0.01153
! and lines following it have the right ascension in degrees
! rather than the usual hours.  If later objects, or files, will
! be in hours scale, use the special line
&RAHOUR
! which will cause reading to take positions as hours again.
! If you mix several files with some using degrees and others
! using hours, put the correct special line at the start of
! each file to get things right.
!
! When positions are written to .obw, .obx or .SMF files, the
! right ascensions will always be in hours, the default scale,
! even if the object input for those positions was degrees.
!
! Now, we need to add some objects which are potentially to be
! observed.  Following the position, we can add the first optional
! field, a priority.
!
@ob002  02:30:02  -0:01:12 -2.0
@ob003  02:29:37  -0:03:13  5.0
@ob004  02:30:30  +0:05:01  Pri=6.2
!
! The @ character denotes an observed object.  We can use a + sign
! on the declination, or leave it off.  The priority is a decimal
! number, and operates sorta like magnitudes, with numerically smaller
! values denoting the more important objects; a first priority object
! is more desirable than a second priority object and a priority 1.0 
! will be used instead of a 2.0 if they conflict and other things
! are equal.  If priority is omitted, a default value is assigned.
!
! The object ob002 above has a negative priority, so it must be very
! important indeed.  A sufficiently negative priority may be used to
! indicate a "must have" object which will not be removed from the
! data even if it conflicts with another object or reference star.
!
!  NOTE -- Keyword input format documented here is a new feature
!  of software release 2.08 and later.
!  It DOES NOT WORK on release 2.07 and former programs.
!
! The priority of the "ob004" object is given by a keyword, and
! all output files from release 2.08 will take this input, and
! also produce output files using the keyword form.  Files in the
! older positional (non-keyword) form will also be accepted.
! In any object line, any legacy positional parameters must precede
! any keyword parameters.  Keyword parameters may be in any order,
! and the keywords themselves are read in a case-independent manner.
!
! The use count field is written by the maskgen program in a file
! with the object catalog format to allow creation of multiple masks
! for a single position and catalog set.  It looks somewhat like this:
!
@ob005  02:30:21.435  -0:08:16.22  Pri=12.33
@ob006  02:30:21.437  -0:08:21.03  Pri=10.11  Use=1
!
! The above shows that ob006 was used in a mask, and ob005 was not.
!
! The default use count is zero, and will be omitted in the output
! if it is zero.
!
!  Here are the  keyword parameters  currently available:
!
!  Pri    Priority, as a floating point value
!  Use    Use count, an integer
!  Width  Slit width, arc seconds
!  Shape  Slit shape, an integer or name (see below)
!  Alen   Slit length, arc seconds in slit position direction
!  Blen   Slit length, arc seconds in the other direction
!  Tilt   Slit tilt, in degrees, counterclockwise from dispersion normal
!  PA     Slit Position Angle, from North toward East, on sky.
!
! These keywords are case independent, and currently only the first two
! characters of each keyword are needed.  The keyword is separated from
! its value by the "=" sign, and no spaces are allowed within the
! keyword=value item.  If any new keywords are added, they will be
! documented here.
!
! The use count is written in the .obw file for each object which is used
! in a mask, and increments its previous value.
!
! The shapes allowed are:  0 = Circle,  1 = Square,  2 = Rectangle
! For the first two, only a width is defined, for the rectangle the
! alen and blen are lengths with respect to the "object" position.
! For the symmetric shapes, the object is always in the center.
! Reference objects are always square.
! Other objects are by default rectangle (slit) shape, but may be
! set to circle or square as needed; use the "shape" pulldown in
! intgui to set "slit" (rectangle), "hole" (circle) or "box" (square).
! The shape=xxx keyword=value pair will also recognize the names
! "circle" (or "hole"), "square" (or "box") and "rectangle" (or "slit")
! in addition to the integers.  Those names are case-insensitive, and
! may be abbreviated to the first 2 characters.  (Release 2.09+ only).
!
! Slits are by default at a tilt of zero degrees, and are normal to
! the dispersion direction.  The slit orientation on the sky is a
! parameter of the observation (in the intgui window) and selects the
! dispersion direction which is in the .obs file.  The tilt parameter
! allows the slit to be tilted with respect to this default.  The
! positive tilt is counter-clockwise on the sky, corresponding to an
! increase in sky position angle. 
!
! The default values for slit width, shape, alen, blen and tilt are
! all set in the .obs file by inputs in the intgui program.  There is
! no intgui window for tilt, but it can be edited into the .obs file,
! see the "faq.txt" file for how to do this.
!
! The PA parameter is another way to specify a tilted slit, and instead
! of being relative to the instrument position angle in the .obs file,
! it is the actual position angle desired for the slit on the sky,
! measured in degrees from North toward East.  The Position Angle should
! not be zero or negative, use values from 0.01 through 360.0; this
! range is not (yet) enforced by the reading program.
! Some examples:
!
@ob007 2:29:55.855 -0:02:22.44 Pri=3 width=0.75 alen=4.5 blen=3.5
@ob031 2:30:12.664 0:05:14.32 Pri=-8 alen=18.5 blen=17 pa=46.35
@ob008 2:29:53.766 -0:05:33.80 pr=9 blen=6 alen=6
@ob009 2.499873 -0.12765 width=0.8 pri=9  # Magnitude 10.7
@ob654 2:30:15.678 0:07:12.32 7.5 0.58 2 5.0 5.0 pa=38.6 ! Double star
!
! Here object "ob007" requires a non-standard slit width, and the
! slit lengths are also non-standard.  Object "ob031" has a very
! high priority (decimal point is optional), is longer than the
! others, and needs to be oriented with the sky position angle
! of 46.35 degrees.  Object "ob008" has a "low" priority (note that
! the keyword can be abbreviated "pr" to 2 letters) and also has
! non-default slit lengths.  Object "ob009" has probably been entered
! from another list as R.A. and Dec. are in decimal hours and degrees,
! and we want a non-standard slit width for it.
! Object "ob654" is an ancient entry from an old file in which the
! data is in positional form, it should be written as:
@ob654 2:30:15.678 0:07:12.32 pri=7.5 wid=0.58 alen=5 blen=5 pa=38.6
! but the program is smart enough to read the older data that it
! could read before and put the values in the right places.  Note
! that a position angle was added at the end.  Keyword parameters may
! follow legacy positional parameters, but no positional parameter
! can follow a keyword.  And comments must come last in the line.
! Object lines can be up to 1000 characters long in release 2.08.
!
! Also, if a keyword is repeated, or both tilt and PA are given, the
! last one processed in the line (left to right) is the value used.
!
! As previously stated, keyword parameters may be in any order, and
! the keywords themselves are not case sensitive.
!
! If you have older data in positional format, the values were read
! in this order:
!   Priority, use count (if no decimal point), slit width (with decimal),
!   shape integer, A-len, B-len, tilt.
! This is now obsolete, but older files will be read correctly until
! further improvements would create a conflict.
!
!
! That's all there is to it.  Naturally, a real object catalog file
! would have many (perhaps thousands) of objects in it, and relatively
! few comments.  You can put in as many as you want (the sky's the
! limit), and multiple object catalog files may be used.  They are all
! combined into a single list in the program.
!