Usenet 1994 October/usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso/misc/volume11/starchart/part22

Text File | 1990-03-25 | 35KB | 933 lines

Newsgroups: comp.sources.misc
subject: v11i050: starchart 3.2 Part 22/32
from: [e-mail]
Sender: [e-mail] (Brandon S. Allbery - comp.sources.misc)

Posting-number: Volume 11, Issue 50
Submitted-by: [e-mail]
Archive-name: starchart/part22

#! /bin/sh
# This is a shell archive.  Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file".  To overwrite existing
# files, type "sh file -c".  You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g..  If this archive is complete, you
# will see the following message at the end:
#        "End of archive 22 (of 32)."
# Contents:  doc/as.ms.ab
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'doc/as.ms.ab' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'doc/as.ms.ab'\"
else
echo shar: Extracting \"'doc/as.ms.ab'\" \(32244 characters\)
sed "s/^X//" >'doc/as.ms.ab' <<'END_OF_FILE'
XCurrently defined command line arguments are described below.
XAdditional flag interpretation may be done by the device driver:
Xunidentified flags are passed to a driver-specific function which
Xattempts to interpret the flag. All others are undefined, and produce a
Xusage message and error exit.
X.PP
X.nf
X.br
X
XFlag    Additional argument type(s)   Mnemonic
X-r    float               Right ascension
X-d    float               Declination
X-s    float               Scale
X-m    float               Magnitude limit
X-l    float               name Label magnitude limit
X-g    float               Greek label magnitude limit
X-p    [string]           Polar,
X                   or Projection = string
X                   Possible values ``sansons'',
X                   ``stereographic'',
X                   ``orthographic'',
X                   ``gnomonic'', ``rectangular''.
X-b    --none--           Big map: full page map
X-i    --none--           Invert: flip map top to bottom
X-t    string               Title
X-y    string               Yale.star: star data file
X-h    string               Harvard index.indx index file
X-n    string               Neb.star: nebula data file
X-w    string               Wanderers: planet.star planet data file
X-f    string               File: user file
X-c    string [string]           Constellation: a three or four character
X                   mnemonic followed by an optional file name;
X                   the file is searched for an entry
X                   corresponding to that mnemonic: the entry
X                   specifies the RA DEC Scale and Title.
X-v    float float           Variable finder: labels stars with their
X                   magnitudes if they are within
X                   arg2 mags. of arg1
X-x    float float [float float]  X grid: grid in RA and DEC,
X                   spacing arg1 and arg2, origin at arg3 arg4
X-e    string               Extra: chart control file.
X-u    --none--           User input.  Allow keyboard-based user input
X-a    string               Additional Argument string:
X                   passed to driver for additional control.
X.fi
X.PP
X.NH 3
XControl\ and\ Specification\ Files
X.br
X.PP
XThe controlling variables of the chart are set by default at compile
Xtime, and many may be overridden by command line arguments.  However,
Xmore control is afforded by \f(CW\`.starrc\'\fR and \f(CW\`-e \fIextra\fR\'\fR
Xfiles.  The starchart programs attempt to read an initialization file,
Xwhose name is set at compile time (default \f(CW\`./.starrc\'\fR).
XAdditional such files may be read through the \f(CW\`-e\'\fR commandline
Xargument.  The file contains lines of the form \f(CW\`\fIvariable\fR
X\&\fIvalue\fR\'\fR or \f(CW\`\fIvariable\fR=\fIvalue\fR\'\fR, with comments
Xbeginning with \f(CW\`#\'\fR ignored.  The variables and their values are
Xgiven below.  These definitions reset the values of program variables,
Xoverriding their current value.  These may in turn be overridden by
Xlater command line arguments or additional \f(CW\`.starrc\'\fR files
Xspecified with \f(CW\`-e\'\fR.  Any variables not understood by the main
Xprogram are passed to a driver specific function which may interpret it.
X.PP
X.nf
X.br
X
XVariable        Value type(s)     comment
Xra            float      # same as -r
Xdec            float      # same as -d
Xscale            float      # same as -s
Xtitle            string      # same as -t
Xfindconst        string      # same as first argument of -c
Xconstfile        string      # same as second argument of -c
Xnamelim            float      # same as -l
Xlbllim            float      # same as -l
Xmaglim            float      # same as -m
Xgklim            float      # same as -g
Xstarfile        string      # same as -y
Xindexfile        string      # same as -h
Xnebfile            string      # same as -n
Xplanetfile        string      # same as -w
Xuserfile        string      # same as -f
Xmapfile            string string # set mapfile array in main routines:
X                  #       sets elements in order
X                  #       overrides previous settings
X                  #    overrides default yale.star, etc.
X                  #    second arg is type of file
X                  #    as specified in index.indx
Xboundfile        string      # sets file for "boundaries" layer
Xpatternfile        string      # sets file for "patterns" layer
Xconstlnamefile        string      # sets file for "constlnames" layer
Xlayers            string      # same as all_layer:
Xall_layer        string      # sets array of layers in main routines:
X                  #     sets elements in order
X                  #     overrides previous settings
X                  # possible values :
X                  # "outline" "ra_grid" "dec_grid" "ecliptic"
X                  # "boundaries" "patterns" "constlnames"
X                  # "allfiles" "allglyphs" "allnames"
X                  # "allmaglbls" "allvectors" "allareas"
X                  # "legends"
Xpolarmode        logical      # same as -p if logical is nonzero or is TRUE
Xbigflag            logical      # same as -b if logical is nonzero or is TRUE
Xprojection_mode        string      # set projection mode
X                  # may be "sansons", "stereographic"
X                  # "orthographic", "gnomonic" or "rectangular"
Xinvert            logical      # same as -i if logical is nonzero or is TRUE
Xprecess_to          float      # Precess to equinox and ecliptic of year.
Xchart_type        string      # set chart type: "fullpage" or "threepart"
X                  # "threepart" is default: Large window,
X                  # thumbnail, and legend
X                  # "fullpage'' is same as -b flag
Xvrange            float float      # same as -v
Xvmags            float float      # set magnitude labeling maximum
X                  # and minimum magnitudes
Xgrid            float float [float float]
X                  # same as -x
Xnogrid            logical      # turn off display of all grids
Xnogrid_ra        logical      # turn off display of RA grid
Xnogrid_dec        logical      # turn off display of DEC grid
Xnomaglbls        logical      # turn off display of magnitude labels
Xdrivercontrol        string      # same as -a flag
Xdriver_control        string      # same as -a flag
Xadditional        string      # same as -a flag
X
XFor interactive control, the following commands are also active:
X
Xexit            --none--      # Exit the program
Xquit            --none--      # Exit the program
Xend_input        --none--      # End input, display chart
Xdone_input        --none--      # End input, display chart
Xdone            --none--      # End input, display chart
Xdraw            --none--      # End input, display chart
Xhelp            --none--      # Give help
X?            --none--      # Give help
Xshow            --none--      # Show value of variables
Xwrite_rc_file        string      # Write current state to .starrc file
Xwrite_mapwin_file   string      # Write detailed specification of
X                  # chart to given filename
Xread_mapwin_file    string      # Read detailed specification of
X                  # chart from given filename
X.fi
X.PP
X.PP
X.PP
X.PP
X.PP
X.NH 3
XInteractive\ Controls
X.br
X.PP
XThe \f(CW\`-u\'\fR option activates interactive mode, where the same commands
Xas in the \f(CW\`.starrc\'\fR file may be typed to control the program
Xoptions.  In addition, \f(CW\`end_input\'\fR ends interactive input and draws
Xthe chart.  After the chart is drawn, control returns to the keyboard.
XThe \f(CW\`quit\'\fR command exits the program.  The command \f(CW\`show\'\fR
Xshows the current state of the control variables.  The command
X\&\f(CW\`help\'\fR may be used to get a brief description of the commands and
Xcontrols available.
X.PP
XSome, especially window based, versions will allow the user final
Xcontrol over each map of the chart.  The chart is specified by an
Xarray of large \fBC\fR structures, one for each map on the page.  The
X\&\f(CW\`mapwin\'\fR file contains the values in this structure.  Advanced
Xinteractive versions of starchart, such as \fBstarXaw\fR, allow the
Xcomponents of the structures to be edited individually, providing full
Xaccess to the flexible controls of the program.
X.PP
XThe sequence of control of the program is:
X.PP
X1) read the \f(CW\`./.starrc\'\fR file.
X.PP
X2) process the command line: options are processed in order, later
Xarguments may override earlier arguments, additional \f(CW\`.starrc\'\fR
Xformat files are read as they are encountered in \f(CW\`-e\'\fR options.
XHowever, if the file specified in the \f(CW\`-e\'\fR option is in \f(CW\`mapwin\'\fR
Xformat, it is read later.  After the command line is processed, if the
X\&\f(CW\`-u\'\fR option is active, keyboard interaction is performed.  Next,
Xany \f(CW\`mapwin\'\fR format files are read.  If there is more interaction
Xavailable (e.g. as in \fBstarXaw\fR), the details of the chart may now be
Xcontrolled.  If a \f(CW\`mapwin\'\fR file is to be written, it is written now.
XThen the chart is drawn to specification.  Finally, after the chart is
Xdrawn, the program returns to the first interaction (i.e. returns to
Xthe point after the command line has been processed).
X.PP
XOne more form of interaction is available on some systems:  A mouse or
Xother pointing device may be used to either select points on a map and
Xthe coordinates of that point are displayed, or the databases may be
Xsearched for objects near the selected point and the database entries
Xfor the objects found are displayed.
X.PP
X.NH 2
XStandard\ Data\ Files
X.br
X.PP
XAll are in equinox 2000.0 coordinates, and should also be in epoch
X2000.0.
X.PP
X.IP \f(CW\`yale.star\'\fR\
Xstellar information (mandatory)
X.IP
X.IP \f(CW\`neb.star\'\fR\
Xnebulae (optional)
X.IP
X.IP \f(CW\`planet.star\'\fR\
Xplanets (optional)
X.IP
X.IP \f(CW\`boundaries.star\'\fR\
Xconstellation boundaries (optional)
X.IP
X.IP \f(CW\`cnames.star\'\fR\
Xconstellation names (optional)
X.IP
X.IP \f(CW\`patterns.star\'\fR\
Xconstellation patterns (optional)
X.IP
X.IP \f(CW\`index.indx\'\fR\
Xindex file for additional star files (optional)
X.IP
X.IP \f(CW\`con.locs\'\fR\
Xdefault mnemonic locations
X.IP
X.PP
X.NH 2
XParticular\ Starchart\ Programs
X.br
X.PP
XSome starchart programs have coadditional driver-specific controls
Xwhich are accessed throught the \f(CW\`-a\'\fR command line option, or the
X\&\f(CW\`additional\'\fR (= \f(CW\`driver_control\'\fR) variable.
X.PP
XThese programs and other versions of starchart with special needs are
Xdocumented in this section.
X.PP
X.PP
X.NH 3
X\&\fBstarX11\fR
X.br
X.PP
X\&\fBstarX11\fR is the X11 version of starchart.  It has the following
Xspecial arguments which are accessed through \f(CW\`-a\'\fR, e.g.
X.br
X\&\f(CW\`-a p\'\fR.
X.PP
X.IP \f(CW\`p\'\fR\
XPostScript preview: use screen size and shape to approximate coverage of
X\&\fBstarpost\fR chart.
X.IP \f(CW\`l\'\fR\
XPostScript landscape preview: use screen size and shape to approximate
Xcoverage of \fBstarpost\fR landscape format chart.
X.IP \f(CW\`h\'\fR\
Xhide: display is generated invisibly, which may save time.
X.IP \f(CW\`b\'\fR\
Xbackup: use backup pixmap, allows window to be hidden and redrawn.
X.IP \f(CW\`m\'\fR\
Xmonochrome: prevents use of color on displays otherwise capable of it.
X.PP
XUsage example:
X.br
X\&\f(CW\`starX11 -c ori -g 5 -a p\'\fR.
X.PP
X.NH 3
X\&\fBstarXaw\fR
X.br
X.PP
X\&\fBstarXaw\fR is the X11 version of starchart with interactive control
Xusing Athena Widgets.  In addition to the controls for \fBstarX11\fR,
Xit has the following special arguments which are accessed through
X\&\f(CW\`-a\'\fR, e.g.
X.br
X\&\f(CW\`-a "t -geometry -0-0"\'\fR.
X.PP
X.IP \f(CW\`t\'\fR\
X" toolkit_args" for access to the standard X toolkit controls, such as
Xfor geometry, fonts, etc.
X.PP
XUsage example:
X.br
X\&\f(CW\`starXaw -c sgr -a p -a "t -geometry -0-0 -bg red"\'\fR.
X.PP
X.NH 3
X\&\fBstarpost\fR
X.br
X.PP
X\&\fBstarpost\fR is the PostScript version of starchart.  It has the
Xfollowing special arguments which are accessed through \f(CW\`-a\'\fR, e.g.
X.br
X\&\f(CW\`-a "m9 8 7 6 5 4 3.5 2.5 2 1.5 1 0.5"\'\fR.
X.PP
X.IP \f(CW\`n\'\fR\
Xnotebook: The chart is shifted to the right on the page, and the
X``thumbnail'' map is replaced with prompts and space for recording
Xobserving conditions.  The rest of the argument string is taken to be a
Xlist of floating point numbers separated by `:' or ` '.  These are taken
Xto be the radii in degrees of fields of view of the instrument or
Xfinder.  Circles with these radii are drawn, centered on the center of
Xthe chart.
X.IP \f(CW\`m\'\fR\
Xmagnitude: 0.1 magnitude quanta are to be used (the default is 1.0
Xmagnitude, e.g. a 4.6 magnitude star is represented by the same symbol
Xas a star of magnitude 5.4).  The rest of the argument string is taken
Xto be a list of floating point numbers separated by `:' or ` '.  These
Xare taken to be the radii of the symbols for stars of magnitude -1, 0,
X1, 2, 3 etc. The sizes of symbols for stars with magnitudes between
Xthese magnitudes are determined by linear interpolation.  Note that the
Xlast value given is the value assigned to all magnitudes fainter than
Xthat magnitude.  Current default sizes are "9 8 7 6 5 4 3.25 2.5 2 1.5 1
X0.5".
X.IP \f(CW\`s\'\fR\
Xsize: this argument provides an alternative way of specifying
Xmagnitude symbol sizes, using a formula proposed by Andrew Young in
XSky and Telescope, March 1990, p. 311, D = D0 * 10^(k*(v0 - v)).
XHe proposes a k of between 0.07 and 0.16, with 0.11 as probably the
Xbest.  If \f(CW\`s\'\fR uses 0.1 magnitude quanta as does \f(CW\`m\'\fR.  The
Xdefault values for \fID0\fR, \fIv0\fR, and \fIk\fR are 0.5 (points),
Xthe limiting magnitude of the first main map, and 0.11, respectively.
XThese may be altered with the optional arguments to \f(CW\`s\'\fR, which set
X\&\fID0\fR, \fIv0\fR and \fIk\fR in that order, e.g. \f(CW\`s 0.7 6.6\'\fR sets
X\&\fID0\fR to 0.7 point, and \fIv0\fR to magnitude 6.6 so that a magnitude
X6.6 star will be printed as 0.7 point in diameter, and \fIk\fR will
Xremain 0.11.  \f(CW\`s 0.7 6.6 0.07\'\fR will set \fID0\fR and \fIv0\fR as
Xabove, and also set \fIk\fR to 0.07.
X.IP \f(CW\`f\'\fR\
X\&\f(CW\`f \fIfile\fR\'\fR may be used to specify an output file, otherwise the
XPostScript produced is sent to the standard output.
X.IP \f(CW\`c\'\fR\
Xmay be used to produce color postscript output.
X.IP \f(CW\`l\'\fR\
Xmay be used to specify landscape mode (as opposed to the default
Xportrait orientation).  Landscape mode can only used with a
Xfullpage map.
X.PP
XSince the resolution of PostScript is much higher than other common
Xdevices, \f(CW\`mapwin\'\fR files must be edited when transferred between
Xstarpost and other drivers.  The controls for window \f(CW\`width\'\fR,
X\&\f(CW\`height\'\fR, \f(CW\`x_offset\'\fR and \f(CW\`y_offset\'\fR must be changed.
X.PP
XThe \f(CW\`-a p\'\fR or \f(CW\`-a l\'\fR option used with \fBstarX11\fR or
X\&\fBstarXaw\fR can be used to produce a \f(CW\`mapwin\'\fR file which can be
Xconverted for use in \fBstarpost\fR through an \fBawk\fR script named
X\&\fBpostconv.awk\fR, provided with the source to this program.
X.PP
XUsage example:
X.br
X\&\f(CW\`starpost -a "n 6:1.5:.5" -a "m9 8 7 6 5 4 3.5 2.5 2 1.5 1 0.5" -a "f orion.PS" -c ori -g 5\'\fR.
X.PP
X.NH 3
X\&\fBstartool\fR
X.br
X.PP
X\&\fBstartool\fR uses the \fBtooltool\fR program, not included in the
Xstarchart distribution, to provide an interface to \fBstarsunv\fR.
X\&\fBttooltool\fR is available from your local Sun sources archive.
X.PP
X.NH 2
XWriting\ a\ New\ Version\ for\ a\ New\ Device
X.br
X.NH 3
XOrganization
X.br
X.PP
XThere are several layers of functions in starchart.  The top level is in
X\&\f(CW\`starmain.c\'\fR, \f(CW\`starm2.c\'\fR, and \f(CW\`readfile.c\'\fR.  It is (I
Xhope) general enough to enable any additions to be made by users in the
Xform of modified drivers, leaving these files stable.  \f(CW\`starmain.c\'\fR
Xand \f(CW\`starm2.c\'\fR are in charge of the user interface and file
Xreading, with \f(CW\`readfile.c\'\fR.  Generally, this top level controls
X\&\fIwhat\fR is to be drawn, and \fIwhere\fR it appears.  The device
Xspecific section controls \fIhow\fR it appears.
X.PP
XInformation is passed to the drivers via externs and function
Xparameters.  The externs are for runtime values, the function parameters
Xare for values taken from the data files.  Information is passed from
Xthe driver to the starchart.c routines via externs.
X.PP
XThere are three layers of functions, in several source files.  The top
Xlevel functions are in \f(CW\`starmain.c\'\fR and \f(CW\`starm2.c\'\fR.  You
Xshould not have to change anything in this file, except perhaps #defines
Xfor default file names and file types, and these may also be set in the
XMakefile.
X.PP
XThe \f(CW\`starcust.c\'\fR file contains customizing functions, including functions
Xto define additional command line flags, which may apply to several
Xdrivers.
X.PP
XThe \f(CW\`starXXXX.c\'\fR or \f(CW\`starimages.c\'\fR + \f(CW\`starXXXX.c\'\fR files
Xdefine the more device dependent functions.  There is one function,
Xcalled \f(CW\`drawobj\'\fR, which is the interface between the top level
Xfunctions and the device for drawing the stars, planets, and other
Xobjects read from a database file.  In addition, standard functions to
Xopen and close the device, draw a line, move without drawing, etc. are
Xrequired.  These may then call the lowest level device dependent
Xfunctions.  The \f(CW\`starimages.c\'\fR file provides a standard definition
Xfor \fBdrawobj\fR and supporting functions for bitmapped devices; the
Xdevice dependent code remaining (e.g. line drawing), is in the file
X\&\f(CW\`starXXXX.c\'\fR.
X.PP
XUser input functions also may be defined in \f(CW\`starXXXX.c\'\fR.
X.PP
XThe layer currently being drawn and/or the subroutine currently active
Xis passed to the driver in an extern.  This allows the driver to for
Xexample draw vectors differently for the constellation boundaries.
XAdditionally, each window has a map type field which is for efficiency
Xalso passed as an extern, which may be used by the driver to for example
Xdraw certain layers differently in certain windows.
X.PP
XThe source to other drivers, especially \fBstarXaw\fR and
X\&\fBstarpost\fR, should be a valuable reference to developing new
Xdrivers.
X.PP
X.NH 3
XCustomization
X.br
X.PP
XFor the drivers distributed, there are many \f(CW\`#defines\'\fR and global
Xvariables whose values may be altered to suit your tastes and your
Xparticular piece of hardware.  Default file names are \f(CW\`#defined\'\fR in
Xthe code, and may also be set in the Makefile.
X.PP
XIt is easy to write a driver for other devices, based on the drivers and
Xthe driver skeleton provided.
X.PP
XMore extensive customization is possible through modifying the driver
Xfunctions to take fullest advantage of the device you are using.  It is
Xalso possible to add controls accessed through the \f(CW\`-a\'\fR command
Xline option and the \f(CW\`additional\'\fR (= \f(CW\`driver_control\'\fR) variables.
X.PP
XPlease try to send me (ccount) a note before writing any new drivers, so
XI can let you know if a driver for that device is in the works.  Any
Ximprovements to drivers should be sent to me or the author (if they are
Xnot the same), when you're sure they work and are happy with the
Xchanges.
X.PP
XThings you define in \f(CW\`starcust.c\'\fR, if you think they are generally
Xuseful, should be sent to me.  If possible, they may be incorporated in
Xfuture releases.
X.PP
XImprovements to top level routines should be made with great caution.
XSuch changes will make it harder for you to use future refinements.  If
Xyou're sure you're change (a) works and (b) is better/stronger/faster,
Xplease send it to me.
X.PP
XDo report any bugs/problems.
X.PP
X.bp
X.NH
XThe\ Data\ Files\ and\ Their\ Formats
X.br
X.PP
XThis section discusses file formats used by the programs.
X.PP
X.PP
X.NH 2
XContents\ of\ Data\ Files
X.br
X.PP
XEach line of file contains:
X.IP \fIra,\ dec,\ mag\fR\
XRequired.  Right ascension, Declination, and magnitude (V or visual).  6
Xchars for RA, one for sign of DEC, 4 for DEC, 3 for mag.
X.IP
X.IP \fIobject\ type\fR\
XDefines what the object is: star, galaxy, cluster, nebula, planet,
Xother, unknown, vector, area, comment, or invisible, with subtypes for
Xeach (Two chars).  Defaults to type star subtype single.
X.IP
X.IP \fIspectral\ class\ or\ color\fR\
XDefines the color of the object, as spectral class for stars or directly
Xfor other objects (Two chars).
X.IP
X.IP \fIletter\ or\ flamsteed\ number\ or\ size\fR\
XDefines either the Bayer letter or Flamsteed number of a star, or the
Xsize of an extended object encoded in two chars.
X.IP
X.IP \fIconstellation\fR\
XThe constellation field contains the IAU designation of the
Xconstellation the object is in (three chars).
X.IP
X.IP \fIname\fR\
XName or other labeling string.  Terminated by comma.
X.IP
X.IP \fIcomment\ field\fR\
XRemainder of line after the comma which terminates the name.  This
Xcomment field may be used for special information about the object, e.g.
Xthe phase of the moon.
X.PP
XMagnitude is encoded into three fields as follows: the first character
Xmay be a \f(CW\`-\'\fR, in which case the next two characters are the magnitude
Xtimes 10, e.g. \f(CW\`-16\'\fR means \f(CW\`-1.6\'\fR.  The first character is a digit,
Xthe three characters are the magnitude times 100, e.g. \f(CW\`563\'\fR means
X\&\f(CW\`5.63\'\fR.  Finally, if the first character is a capital letter, this is
Xtaken as the base-36 value of the integral part of the magnitude, and
Xthe remaining two characters are the fractional part times 100, e.g.
X\&\f(CW\`B34\'\fR means \f(CW\`11.34\'\fR.
X.PP
XThe Bayer letter or Flamsteed numbers are applicable only to stars.  The
Xfield is two characters wide.  Greek letters are a single lowercase
Xletter followed by a space or a number, encoded as in the PostScript
XSymbol font:
X.PP
X.nf
X.br
X
Xalpha    - a    beta    - b    gamma    - g    delta    - d
Xepsilon    - e    zeta    - z    eta    - h    theta    - q
Xiota    - i    kappa    - k    lambda    - l    mu    - m
Xnu    - n    xi    - x    omicron - o    pi    - p
Xrho    - r    sigma    - s    tau    - t    upsilon    - u
Xphi    - f    chi    - c    psi    - y    omega    - w
X.fi
X.PP
XNote that theta, xi, phi, chi, and psi have changed from the original
Xdefinitions, which were @, E, 0, x, and % respectively.  Note also that
Xa variant version of phi is mapped to j.
X.PP
XAn uppercase letter followed by any character or two non-numeric
Xcharacters is the roman letter designation for the star, e.g. \f(CW\`CY\'\fR.
XTwo numbers or a space and a number is the Flamsteed number of the star.
X.PP
XThe size of nonstellar objects is encoded in seconds of arc in the size
Xfield to two significant digits.  The second character is always a
Xdecimal digit.  Sizes from 0 to 99 arc seconds are encoded as two
Xdecimal digits.  For larger objects the first character is a capital
Xletter, interpreted as follows, with the second character as the next
Xdigit:
X.PP
X.nf
X.br
X
XFirst character        Value
X0 - 9            00 - 90
XA - I            100 - 900
XJ - R            1000 - 9000
XS - Z            10000 - 80000
X.fi
X.PP
XExamples:
X.PP
X.nf
X.br
X
XSize field    Value
X 6        6
X09        9
X73        73
XA0        100
XC3        330
XD5        450
XI6        960
XJ2        1200
XR3        9300
XS6        16000
XZ0        80000
XZ9        89000
X.fi
X.PP
XThe types and subtypes implemented are:
X.PP
X.nf
X.br
X
XType[0]        main type    type[1]        subtype
XC        cluster
X                G        globular
X                O        open
X                (other)     other
X
XG        galaxy
X                a        spiral Sa
X                b        spiral Sb
X                c        spiral Sc
X                d        spiral Sd
X                p        spiral Sp
X                Z        spiral S0
X                s        spiral unspecified
X                A        barred spiral SBa
X                B        barred spiral SBb
X                C        barred spiral SBc
X                D        barred spiral SBd
X                P        barred spiral SBp
X                S        barred spiral unspecified
X                0-7        elliptical E0-E7
X                E        elliptical
X                I        irregular I
X                Q        quasar
X                U        unknown
X                !        peculiar
X                         unspecified
X                (other)     other
X
XN        nebula
X                D        diffuse
X                P        planetary
X                (other)     other
X
XP        planet
X                M        Mercury
X                V        Venus
X                m        Mars
X                J        Jupiter
X                s        Saturn
X                U        Uranus
X                N        Neptune
X                P        Pluto
X                A        Asteroid
X                C        Comet
X                S        Sun (Sol)
X                L        Moon (Luna)
X                (other)     other
X
XS        star
X                S        single
X                D        double
X                V        variable
X
XO        other
X                (any)        other object
X
XU        unknown
X                (any)        unknown object
X
XV        vector
X                M        moveto (begin, no line drawn)
X                S        solid lineto via great circle
X                D        dotted lineto via great circle
X                H        hyphened (dashed) lineto g. c.
X                m        moveto linear
X                s        solid lineto linear
X                d        dotted lineto linear
X                h        hyphened lineto linear
X
XI        invisible
X                (any)        for labels
X
X#        data comment
X                (any)        for comment in file
X
XA        area
X                M        moveto (begin)
X                A        add great circle border segment
X                F        fill region and end region
X                m        moveto (begin)
X                a        add linear border segment
X                f        fill region and end region
X.fi
X.PP
X.PP
XThe magnitude of an object determines what information is displayed.
XThree magnitude limits are defined for each file in each map window.  If
Xthe magnitude is greater (dimmer) than the first limit, nothing is
Xdrawn.  If the object is brighter than a second limit, the label (Bayer
Xor Flamsteed) is printed (if present).  If it is brighter than the third
Xlimit, the name is printed (if present; if not, the label is printed if
Xpresent).  These text strings generally appear to the right of the
Xobject, but the driver can change this.  Note: the label string only
Xapplies to stars.
X.PP
XFor nonstellar objects, the label field defines the size of the object
Xin arc seconds.
X.PP
XFor magnitudes within a range defined for the mapwindow, a magnitude
Xtag, the magnitude to one decimal place as in variable star and asteroid
Xfinding charts, may be displayed.  This will generally be below and to
Xthe right of the object, but this is controlled by the driver.
X.PP
XThe symbol drawn for the object is determined by the type field.
X.PP
XFor devices supporting color, the spectral class or color field defines
Xthe color of the object, and perhaps the associated text.  The spectral
Xclass of stars is mapped to display color, and for other objects, this
Xfield may contain direct color specifications, e.g. 'r3' for an object
Xcolored red level 3.  All this is controlled by the device driver.
XStandards for color definitions are yet to be defined.
X.PP
XThe constellation field is not currently used in the display.
X.PP
XThe comment field is also not generally used, but some drivers may use
Xit to contain special information such as the phase of the moon or
Xposition angle of a comet's tail.
X.PP
X.NH 2
XData\ file\ formats
X.br
X.PP
X.PP
X.NH 3
X\&\f(CW\`lineread\'\fR
X.br
X.PP
XThis text format, called \fIlineread\fR, is the original data file format.
XData for each object is on a single line, stored in character fields.
XCurrently, an older variant is also supported, one which has 4
Xcharacters for the magnitude and omits the color and letter/number
Xfields.  Both of these formats are designated as type \fIlineread\fR,
Xsince each line is read individually and these two types are easily
Xdistinguished on a line by line basis.  In all formats, if a value is
Xunknown, it should be spaces, or a null string in the case of the name
Xand comment fields.  The RA, DEC and mag. must always be provided for an
Xobject.
X.PP
XSince it is a text format, it may be mailed safely and be used on many
Xdifferent computer architectures without change.  However, it is slow,
Xand uses more file space than it ought.
X.PP
X.PP
X.NH 3
X\&\f(CW\`sif\'\fR:\ Starchart\ Interchange\ Format
X.br
X.PP
XThe \fIsif\fR format was introduced to allow data to be exchanged as text,
Xwith greater precision in the location and magnitude fields, and greater
Xreadability compared to the \fIlineread\fR format.  The format is too slow
Xfor use as input to the starchart programs.  A data conversion program
Xis provided to convert between formats, and to precess coordinates
Xduring the conversion.
X.PP
XEach object is represented by a single line in the file.  This line
Xcontains fields each of which corresponds to a field in the
X\&\fIlineread\fR format.  The fields are separated by a single character,
Xusually \f(CW\`;\'\fR.  Fields may be omitted from the end of the line;
Xomitted fields are assigned their default values.  Fields may be empty,
Xand again are assigned their default values.  As with the other formats,
Xthe RA, DEC, and mag. must be present.
X.PP
XThe RA may be given as a decimal hour, hour and decimal minute, or hour
Xminute and decimal second.  The DEC may be given in the same format.
XThe magnitude is a floating point number.
X.PP
XThe type, and color, fields are empty or one or two characters, as in
Xthe \fIlineread\fR format.
X.PP
XThe label field is also the same as in the \fIlineread\fR format, and
Xencodes the size of non-stellar objects in two characters.  There is a
Xbit of ``magic'' in this field.  Since \f(CW\`X \'\fR or \f(CW\` X\'\fR are both
Xvalid, and whitespace is normally ignored, iff this field is two
Xcharacters wide, and both characters are printing characters, it is
Xtaken verbatim as the label field.  That is, \f(CW\`... ; X; ...\'\fR is
X\&\f(CW\` X\'\fR, while \f(CW\`... ; X ; ...\'\fR is read as one character and left
Xjustified to become \f(CW\`X \'\fR.
X.PP
XThe constellation field is the IAU abbreviation for the constellation
Xand is always blank or three characters.
X.PP
XThe name and comment are two separate fields.  Commas should not be used
Xin the name field, since when this name is placed in the other formats a
Xcomma is used to separate the name from comments.
X.PP
X.NH 3
XBinary\ Formats
X.br
X.PP
XThree binary input formats are supported.  These formats provide greater
Xposition and magnitude accuracy, with faster input, and varying degrees
Xof storage space reduction.  The files are inherently unportable,
Xhowever, and should not be exchanged between machines and operating
Xsystems, or even different compilers.  The \fIsif\fR format, described
Xabove, provides a general data exchange format.
X.PP
XThe three formats provide different storage sizes.  The most general
Xformat, which contains all the data in the \fIlineread\fR format, is the
X\&\fIbinfull\fR format.  A smaller format, \fIbinobj\fR stores only the
XRA, DEC, mag. and object type fields, all other fields become their
Xdefaults (usually spaces).  The smallest format, \fIbinstar\fR stores
Xonly the RA, DEC and mag., all other fields become their defaults,
Xnotably the \fIobject type\fR is \f(CW\`SS\'\fR.
X.PP
XThe binary formats are described as \fBC\fR structures.  How the data in
Xthe structure is stored is therefore highly variable between compilers,
Xoperating systems and machines.  However, most machines should be able
Xto take advantage of these formats for local storage.
X.PP
X.NH 3
XThe\ Guide\ Star\ Catalog
X.br
X.PP
XThe Hubble Space Telescope Guide Star Catalog, available on 2 CD-ROMs,
Xmay be used as a stellar database.  This format may be read by
X\&\fBdataconv\fR and the starchart programs, but now written.  An index
Xfile is used to specify which files on which CD-ROM should be read.
X.PP
X.NH 3
XThe\ Index\ File\ index.indx,\ \f(CW\`indextype\'\fR
X.br
X.PP
XThe \fIindextype\fR file is a special file format added to support larger
Xdatabases of dimmer stars.  It provides an index mapping location to
Xfilenames of files containing star data as above.  Each indexed file
Xcovers a rectangle of sky in RA and DEC.  The areas may be different
Xsizes for different files.  The area covered is given as the RA and DEC
Xof the upper left and lower right corners, followed by the filename and
Xa string indicating the type of the file.  This is all on one line in
Xthe file.  The format is then:
X.PP
X.nf
X.br
X
Xupper left   upper left   lower right   lower right   filename   filetype
XRA         DEC      RA        DEC          filename     filetype
X
Xe.g.
X02.0         -30.0       00.0            -90.0          SAO00-90     lineread
X04.0         -30.0       02.0            -90.0          SAO02-90     lineread
X06.0         -30.0       04.0            -90.0          SAO04-90     lineread
X08.0         -30.0       06.0            -90.0          SAO06-90     lineread
X10.0         -30.0       08.0            -90.0          SAO08-90     lineread
X.fi
X.PP
X.PP
X.bp
X.NH
XThe\ Support\ Programs
X.br
X.PP
XSeveral support programs are provided for use with the primary
X\&\fBobserve\fR and starchart programs.
X.PP
X.PP
X.NH 2
X\&\fBdataconv\fR
X.br
X.PP
XThis program is used to convert between file formats, especially to
Xgenerate binary format files.  It can precess coordinates as desired.
XRemember, input data files for starchart programs should be in 2000.0
Xcoordinates.
X.PP
X.NH 2
X\&\fBsif-to-text\fR
X.br
X.PP
XThe \fBsif-to-text\fR or \fBsif_to_text\fR program converts sif format
Xfiles to more readable text tables.
X.PP
X.NH 2
X\&\fBtosize\fR
X.br
X.PP
XThis program is used to encode the size of objects, for development of
Xnew databases.
X.PP
X.bp
X.NH
XAcknowledgements
X.br
X.PP
XThe previous versions of starchart were developed by Alan Paeth.
X.PP
XSteve Kennedy contributed to \f(CW\`starimages.c\'\fR.
X.PP
XRobert Tidd provided the original \f(CW\`yale.star\'\fR and the format.
X.PP
XDave Van't Hof provided most of the other databases (in particular boundaries,
Xpatterns, and names).
X.PP
XMichael Campanella provided vms support.
X.PP
XThe Atari ST version was developed by Holger Zessel and Markus Kempf.
X.PP
XTom Horsley contributed the ibm PC driver.
X.PP
XMike Daly helped with the Macintosh version.
X.PP
XJoe Wang helped with the X11 version.
X.PP
XDean Payne provided the original code for \f(CW\`.starrc\'\fR processing.
X.PP
XOther contributions are from Petri Launiainen, Jyrki Yli-Nokari, Sjoerd
XMullender, David Smith, Tim Pointing, and others.
X.PP
X.PP
X.bp
X.SH
XProgram\ Index
X.br
X.PP
X.PP
X.bp
X.SH
XConcept\ Index
X.br
X.PP
X.PP
X.PP
END_OF_FILE
if test 32244 -ne `wc -c <'doc/as.ms.ab'`; then
    echo shar: \"'doc/as.ms.ab'\" unpacked with wrong size!
fi
# end of 'doc/as.ms.ab'
fi
echo shar: End of archive 22 \(of 32\).
cp /dev/null ark22isdone
MISSING=""
for I in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 ; do
    if test ! -f ark${I}isdone ; then
    MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked all 32 archives.
    rm -f ark[1-9]isdone ark[1-9][0-9]isdone
else
    echo You still need to unpack the following archives:
    echo "        " ${MISSING}
fi
##  End of shell archive.
exit 0