# Help file for XEphem v3.4

# For RCS Only -- Do Not Edit -- Leave at top of file so it doesn't show.
# @(#) $RCSfile: xephem.hlp,v $ $Date: 2000/12/04 15:36:37 $ $Revision: 1.178 $ $Name:  $

@Intro
XEphem is an interactive astronomical ephemeris program for X Windows systems.

XEphem ...

    computes heliocentric, geocentric and topocentric information for all
    objects;

    has built-in support for all planets; the moons of Mars, Jupiter, Saturn,
    Uranus and Earth; central meridian longitude of Mars and Jupiter;
    Saturn's rings; and Jupiter's Great Red Spot.

    supports user-defined objects in heliocentric or Earth orbit, including
    satellites;

    supports many databases including Tycho, Hipparcos, GSC, USNO.

    displays data in configurable tabular formats and in several interactive
    graphical views including Sky View, Earth, Moon, Mars, Jupiter, Saturn,
    Uranus and Solar System.

    displays a map spanning an entire day of when selected objects are up;

    supports 3-D stereo views of the Solar System particularly well suited
    for investigating comet trajectories;

    quickly finds all close pairs of objects in the sky;

    flexible catalog sorting and printing capabilities for making specialized
    observing lists;

    flexible plotting capability that can access all data fields;

    accesses AAVSO light curves online;

    displays seti@home client progress and show position being processed on
    Sky View map;

    solves for arbitrary circumstances by solving user-written functions of
    any data fields;

    serves as the control point for robot telescopes in real-time via simple
    ASCII command fifos;

    connects to auxiliary database servers via fifos;

    retrieves Digitized Sky Survey FITS files via the Internet from STScI or
    ESO;

    displays FITS files and DSS images overlayed with database symbols.

XEphem can compute information on demand or time can be set to increment
automatically. In this way a series of computations and movies can be
generated unattended.

Quantitative information available about each object includes:

    RA and Dec,
    local azimuth and altitude,
    distance from sun and earth,
    light travel times,
    heliocentric coordinates,
    galactic coordinates,
    ecliptic coordinates,
    solar elongation,
    angular size,
    visual magnitude,
    illumination percentage,
    local rise and set times and azimuths,
    local transit times and altitude,
    length of time up,
    constellation,
    angular separations between all combinations of objects.

Local observing circumstance information includes

    UTC and local date and time,
    local sidereal time,
    times astronomical twilight and length of night,
    local temperature and pressure (for refraction),
    elevation above sea level (for parallax),
    a monthly calendar.

RA/Dec calculations may be topocentric or geocentric, and apparent or
astrometric. When the Epoch is set to a fixed date the values are astrometric,
that is, corrected only for precession and light travel time. When the Epoch is
set for EOD (Epoch of Date) the values are apparent and are also corrected for
nutation, aberration and deflection. Topocentric values are also corrected for
parallax and augmentation. All Alt/Az values are, of course, always topocentric
and are corrected for refraction.

Plot and listing files of selected field values may be generated as the
program runs.  The plot files are full precision floating point values in
ASCII intended for export to other plotting programs. XEphem includes simple
quick-look facilities to view plot files. The listing files are tables
formatted for more general human reading.

XEphem can read databases of objects. The objects may be fixed; specified
via heliocentric elliptical, hyperbolic or parabolic orbital elements to
accommodate solar system objects such as asteroids or comets; or specified
via geocentric elliptical orbital elements to accommodate Earth satellites.
These are then available as candidate values for the user defined objects and
all of them can be displayed in the sky map subject to type and magnitude
filters.  The format of the database file is described in the Help for the DB
window.

@MainMenu

This describes the features of the Main XEphem window.

Across the top is a menu bar to allow selecting the principle functions of
XEphem. Each window opened from the menu bar has its own Help.

Next down is the XEphem logo image.

The next row is a status line that contains a short description of what
XEphem is doing at the moment with regards to its looping behavior.

Below that is room for the NEW CIRCUMSTANCES message. When you change any
field that could invalidate any of the other fields or views this message
flashes until at least one screen Update occurs.

See the Help for "Operation" for more information on changing the fields in
the Main window and controlling XEphem's run time behavior. See the Help for
"Triad formats" for more information on date, time and coordinate formats.

"Help->on Context" turns the cursor into a Question Mark. Roaming the cursor
over any control in XEphem will show its bubble help tip. Press the left
mouse button to end this behavior and resume normal operation.

Follows is a description of each of the display fields in the Main window.

 [Site name]   See below.
 Latitude      Local geocentric latitude, positive degrees north of equator.
	       Changing this will disable automatic computation of Daylight
	       Savings Time.
 Longitude     Local longitude, positive degrees west of Greenwich meridian.
	       Changing this will disable automatic computation of Daylight
	       Savings Time. A sensible Timezone is created based on one hour
	       for each 15 degrees from 0.
 Elevation     Local elevation of the ground above sea level, in feet or
               meters. (see implementation notes). Used in topocentric
               parallax correction.
 Temperature   Local surface air temperature, in degrees F. Used in refraction
               correction.
 Atm Pressure  Local surface air pressure, in inches of mercury. Used in
               refraction correction.
 Epoch         When set to a year, this is the desired epoch to which the
               RA/Dec fields are precessed, referred to as the astrometric
               place. When this is set to EOD, all RA/Dec values are precessed
               to the current XEphem time, and corrected for nutation,
	       aberration and deflection, referred to as the apparent place.


 UTC Date      The UTC date. UTC is "Coordinated Universal Time", the basis,
               after adjusting for time zones, for the official "civil" time
	       people set their clocks to.  Every year or two it is adjusted
	       via a "leap second" so it stays within 0.9 seconds of "UT1",
	       which varies continuously with the slight irregularities
	       of the rotational motion of the Earth.
 UTC Time      The UTC time.
 Julian        The current Julian date, to about 1-second accuracy.
 Sidereal      The apparent sidereal time for the current time and location.
 TZ Name       The local time zone name.  The name may be fixed to any short
               mnemonic. Setting this manually turns off automatic computation
               of Daylight Savings Time. When auto DST is on, a small clock is
	       shown at the top right of the Time section.
 TZ Offset     Hours local time is behind UTC, i.e., positive west or negative
               east of Greenwich. Setting this manually turns off automatic
	       computation of Daylight Savings Time.
 Local Date    The local date. This is UTC minus the value of TZ Offset.
 Local Time    The local time. This is UTC minus the value of TZ Offset.
 Delta T       TT-UT1. Number of seconds by which Terrestrial Time (aka
               Ephemeris Time prior to 1982) leads UT1.  TT is generally of
	       interest when calculating the positions of solar system
	       objects because it is a continuous time scale unaffected by
	       the Earth's rotational vagaries.  The term "Terrestrial"
	       means it is adjusted for the relativistic effects of gravity
	       and the Earth's revolution around the Sun.  UT1 or UTC is of
	       interest when relating those positions to the horizon to
	       produce altitudes and azimuths.  The value may be computed
	       automatically based on the current time or entered manually
	       (in which case it will not change). The algorithm uses values
	       tabulated in the Astronomical Almanac for years 1620.0
	       through 1998.0, and is accurate to within a few seconds over
	       that interval. Dates prior are from Stephenson and Morrison
	       or K. M. Borkowski, with an estimated error of 15 minutes at
	       1500 B.C. A linear extrapolation formula predicts future values.


 Sun Dip       The number of degrees the Sun is below the horizon that we wish
               to call twilight. Common definitions include:
	       Civil = Sun 6 degrees down (headlights barely show on pavement),
	       Nautical = Sun is 12 degrees down (sky and ocean merge),
	       Astronomical = Sun is 18 degrees down (dark as it gets).
	       The Sun Dip setting applies to the following fields:

 Dawn          Local or UTC time when the Sun center is "Sun dip" degrees
               below the horizon before sunrise today.
 Dusk          Local or UTC time when the Sun center is "Sun dip" degrees
               below the horizon after sunset today.
 Length        Length of astronomical night, i.e., Dawn - Dusk.  If this and the
               display for Dawn and Dusk are shown as "-----", it means the Sun
               is either always below or always above "Sun dip" degrees
               below the horizon on this particular day. N.B. These three
	       fields always apply to the local current day.  Difficulties
	       arise when these events occur within 4 minutes of local
	       "midnight" with respect to the time zone defined by TZ Offset.
	       In particular, if these fields are not behaving as you would
	       expect, check that the TZ Offset is set commensurate with the
	       current Longitude.


 LST@0         Local Sidereal Time at next local Midnight, as per the time zone.


 N Steps       The number of times the display will be updated (time advanced
               by Step each step) automatically.
 Step          The amount of time UTC (and its derivatives) is incremented
               each loop. 
 Pause         Number of seconds to pause between screen updates. This is
               used mainly to set up for free-running unattended operation.
               Pausing is not done when plotting or solving is active. When
	       looping, time is maintained at a whole multiple of pause length.


Site name:

Above the Latitude field is an button which can display the current site
name. Pressing this button will bring up a list of cities and observatories.
(The list is from the file named "auxil/xephem.sit" in the shared
directory. Click on one entry in the list then press Set to set the Name,
Latitude, Longitude, Elevation and Time Zone fields in the Main window. The
same may also be done in one step my double-clicking on a site name in the
list. If Set is pressed and the text field does not exactly match any entry
in the list, the Name field in the Main Window is simply set the string
without effecting the other fields. The text field may also contain a search
pattern. Type Enter or activate the Search button to scroll the list to the
next item which contains the text, ignoring case, punctuation and spaces.

Calendar:

The calendar on the right of the Main window is based on local time or UTC,
depending upon the Time Zone preference. Selecting a date button will set the
date. Buttons before the first of the month and after the last of the month
work as expected, that is, they also imply a change in month or year as
necessary. The month and year buttons pop up selections that allow these to be
changed as well. At the bottom are buttons to set the time and date to the
computer clock, or move backwards or forwards by one day or week. Except for
Now, using the calendar does not change the current time (just the date). New
and Full Moons are marked on the day on which they occur in the selected time
zone.


@MainMenu -- file

    The "File" pulldown contains a few miscellaneous controls.

	Messages...
	
	    displays a scrolled list of informational messages. XEphem may beep
	    whenever a new message is added, depending on the "Message Bell"
	    preference; see below. Messages appearing immediately in 
	    attention boxes are also stored here for reference.

	Network setup...

	    displays a window offering choices for how XEphem accesses
	    the Internet.

	External Time/Loc...

	    drives XEphem from a file containing times and latitude/longitude
	    locations. See its own help for details.

	Progress Meter...

	    displays a simple bar graph of XEphem progress. The accuracy and
	    usefulness of the display are highly problematic at this time.

	Update

	    performs the same action as the Update button across the bottom of
	    the Main window. This can also be performed by typing Ctrl-u
	    in any XEphem window.

	Update in reverse

	    performs the same action as the Update button across the bottom of
	    the Main window except goes in reverse. This can also be
	    performed by typing Ctrl-r in any XEphem window.
	
	Quit...
	
	    exits XEphem.

@MainMenu -- view

    The "View" pulldown brings up any of the several XEphem specialized
    displays. Each has its own Help so please refer to it for additional
    information on a particular function.

@MainMenu -- tools

    The "Tools" pulldown can bring up the tools for

	plotting data,
	listing data,
	equation solving,
	finding close pairs,
	seeing the night at a glance,
	retrieving AAVSO light curves
	and monitoring your local SETI@home client.
	
	Each tool has its own Help so please refer to that for complete
	information on a particular tool.

@MainMenu -- objects

    The "Data" pulldown brings up windows which pertain to managing the
    objects in memory.

        Load/Delete...

	    adds and deletes objects in memory from files of database objects.
	    The window also displays overall statistics of the number of each
	    type of object in memory.

        Search, ObjX,Y,Z...

	    selects any given object in memory and views or modifies all of its
	    defining parameters. Also can be used to center the Sky View over
	    any object and to define the user-defined objects, ObjX, Y and Z.

	Field stars...
	
	    sets up to read the various sources of faint stars which XEphem
	    refers to as "field stars," including the Hubble GSC, USNO,
	    Hipparcos, Tycho and PPM catalogs.

	Update Earth satellites...

	    allows fast and easy updates of TLEs from web sites. This window
	    has its own help.

@MainMenu -- preferences

    The "Preferences" pulldown lists the available preferences that may be
    changed at run time. Whenever any are changed, all effected fields are
    immediately recalculated and redisplayed throughout XEphem. The
    preference include:

	Equatorial: Topocentric, Geocentric

	    controls whether the RA and Dec values displayed throughout XEphem
	    are for the current local surface location (topocentric) or from
	    the center of the Earth. (Alt/Az values are, of course, always
	    topocentric.)

	Precision: Hi, Low

	    controls how much precision is shown for most angles. This is a
	    change in display format only and does NOT imply a change in
	    accuracy.

	Message Bell: On, Off

	    whether to ring the bell each time a new message is added to the
	    Message window. The Message window is accessible via the File menu
	    in the Main menu bar.

	Prompt Prefill: Yes, No

	    whether prompt strings from the Main window and Search windows
	    are filled with the current value or blanked out. This is also
	    handy to allow copy/paste of these values.

        Units: English, Metric

            whether local topocentric circumstances are given in English or
            Metric units of measure.

        Time zone: UTC, Local

            whether the time stamp below each major view, the rise/transit/set
	    times in the Data Table window and the dawn/dusk times and the
	    calendar in the Main window refer to UTC or local time.

	Show help tips: Yes, No

	    whether additional help is available immediately for all selectable
	    buttons and controls using small brief windows near the control.

	Confirmations; Yes, No

	    whether operations which basically can not be undone or which
	    might have irreversible consequences will be preceded with a
	    confirmation window. Examples include exiting XEphem or
	    overwriting an existing file.

        Date formats: M/D/Y, Y/M/D, D/M/Y

            whether dates are shown and entered in month/day/year,
            year/month/day or day/month/year format.

	Fonts...

	    displays a window to experiment with fonts while you watch.
	    See its own help for details.

	Colors...

	    displays a window to experiment with colors while you watch.
	    See its own help for details.

	Save...

	    displays a window which shows how the current functional
	    settings differ from their defaults and allows them to be saved.
	    See its own help for details.

@MainMenu -- sites dialog
This window allows you to load, search and select one of a collection of
predefined sites.

The scrolled list at the top lists the complete set of currently defined sites.
Clicking on one will copy it to the Set text field. Double clicking on one
will also install it to the Main window, as will clicking on Set or typing
Enter over the select text field.

To search for a particular site, either scroll through the list or enter any
part of the site designation in the Search text field. Clicking on Search or
typing Enter in the search text field will scroll the list to the next site
that contains the search text, ignoring case and blanks.

A new file of site definitions may be installed at any time. Type in the name
of the file test field then type Enter or click on File to read in the file.
Or click on Browse and use the File Selection Dialog to locate the desired
site file. Pressing Ok in the FSB or double clicking on a file name will load
the new file and close the FSB window.


File format:

XEphem sites files use the suffix ".sit". Each site entry consists of 5 fields
on one line each separated by a semicolon (;) as follows:

    Name ; Latitude ; Longitude ; Elevation ; Timezone

where:

    Name is the City, State, Country or other designation, up to 40 characters.

    Latitude is DD MM SS, followed by an N or S to indicate north or south
    of the equator. Each portion is separated by a blank.

    Longitude is in DDD MM SS, followed by an E or W to indicate east or west
    of the prime meridian in Greenwich, England. Each portion is separated by
    a blank.

    Elevation is in meters. If you do not know your elevation, put "-1.0".

    Timezone indicates the offset from GMT and savings time information. The
    format matches that of the POSIX standard fully described in the manual
    page for the tzset(3) function. The format is basically summarized as:

      std offset dst [offset],start[/time],end[/time]

Here are a few examples:

Munich, Germany    ; 48 14 0 N ;  11 57  0 E ;  523 ; MET-1METDST,M3.5.0,M10.5.0
New York, New York ; 40 45 6 N ;  73 59 39 W ; 16.8 ; EST5EDT
Sydney, Australia  ; 33 52 0 S ; 151 12  0 E ;  7.6 ; EST-10EST,M10.5.0,M3.5.0

Lines in the file which do not conform to this structure are ignored.

@Operation
When XEphem is launched it looks for a file named .xephemrc in the $HOME
directory. This file is optional. If it exists, it should contain a line
with the following form:

    XEphem.PrivateDir: ~/.xephem

The directory named on the right is where XEphem will create and use per-user,
or "Private" files. A leading "~" in the file name can be used to refer to
$HOME, your login directory. The example above causes the Private directory
to be .xephem in the users $HOME directory. If .xephemrc does not exist or
does not contain this line the default Private directory is ~/XEphem. The
private directory will be created if it does not already exist.

XEphem then also searches for another directory. This one can be shared among
all XEphem users on a system. Files in this directory are never modified by
XEphem. They include databases of objects, supporting images and other files.
This directory is specified in a file named 'XEphem', which is located in
turn within the Private directory (see above). It should contain a line with
the following form:

    XEphem.ShareDir: /usr/local/xephem

The directory named on the right is where XEphem will look for all "Shared"
files. A leading "~" in the file name can be used to refer to $HOME.

Next XEphem sets the initial values of most options and settings from X
Resource values. These are found in all the standard places defined by the X
Windows protocols. In addition, a file named `XEphem' in the per-user
directory (see above) is also searched for resources. Entries in this file
have highest priority.

XEphem now displays the Main screen with its initial values and waits for
instructions. It can loop advancing time each step by an amount you control
and update all fields at each loop.

There are three fields that control this looping behavior.
    N Steps
	is controls the number of steps
    Step
	is the amount of time to add each step
    Pause
	is the amount of real seconds to pause between steps.
	
When looping is in effect, the bottom button on the Main window says "Stop".
When the number of steps goes to 0 or the "Stop" button is selected, the
looping stops and the button is relabeled "Update".

Note that when looping with Pause set to 0, most numeric field data are not
drawn in order to speed up the display. These values are always updated
internally, however. and may safely be used for plotting, solving or
listing. This is true even if the window that displays the information is
closed.

Most fields on the Main window may be changed by selecting them. A prompt window
with a brief explanation of the field will be presented. A new value may be
typed into the text field provided. If "Ok" is selected the new value will be
used; if "Cancel" is selected the field will be left unchanged. In either case,
the prompt window goes away. Some of the windows have an extra button which
offers a handy way to enter frequently used values for the field.

When you have changed a field that would invalidate any of the other fields
or displays the message NEW CIRCUMSTANCES flashes near the top of the Main
window.  This will continue until at least one screen update loop occurs.  If
you change any field that causes new circumstances, the "Step" value is
not added to the current time before the next loop. Note also that after a
series of loops, "N Steps" is automatically reset to 1 from 0 so "Update" will
do exactly one loop again.

Some graphical views have a push button marked "Movie Demo". This is a
convenient way to start and stop a sample movie sequence. If XEphem is
currently idle then pushing the button will set the Main window "Step" to a
value that will yield a pleasing motion effect and start looping with a very
large number of steps. If XEphem is already looping then pushing the button
will cause it to stop and set Main window "N Steps" to 1. The Main window Stop
control can also stop the looping in the usual way.

@Credits
First and foremost, many thanks to my wonderful wife, Kathy, for her
unwavering trust, acceptance and love.

Thanks to Fridger Schrempp, fridger.schrempp@desy.de, for his long term
encouragement of the project, and particularly for many suggestions to
improve ease of use.

Thanks to Aaron Price, aaronp@mira.aavso.org, for his work and enthusiasm to
support accessing AAVSO data directly from within XEphem.

Earth satellite orbit propagation is based on the NORAD SGP4/SDP4 code, as
converted from FORTRAN to C by Magnus Backstrom, b@eta.chalmers.se. See
"Spacetrack Report Number 3: Models for Propagation of NORAD Element Sets"
at http://www.celestrak.com/NORAD/documentation/spacetrk.pdf.

Improvements to Delta T code, help and wording contributed by Neal McBurnett,
nealmcb@bell-labs.com.

Any parts of the USNO SA2.0 catalog that are included with XEphem
distributions are done so with the following understandings:

    It may not be the latest version, check with http://ad.usno.navy.mil.

    If you paid for XEphem, you paid for the software, not this catalog. The
    catalog is available free from the USNO.

    Inclusion of the SA2.0 catalog does not imply an endorsement of XEphem
    by USNO; nor did I have privileged access to the catalog; nor does the
    US Government affirm or guarantee that XEphem works properly in any way.

Thanks to Atsuo Ohki, ohki@gssm.otsuka.tsukuba.ac.jp, for numerous fixes
and features.

The near real-time weather map in the Earth view is provided by the Space
Science and Engineering Center at the University of Wisconsin. See their
web site at http://www.ssec.wisc.edu/ssec.html.

The XEphem logo was contributed by Jonathan Adams, jfadams@mail.arc.nasa.gov.
The galaxy background image is from Galaxy Photography, www.galaxyphoto.com.

For the years 1999-2010 the natural satellite ephemerides for Mars, Jupiter,
Saturn and Uranus are based on developments in mixed functions computed and
contributed at Bureau Des Longitudes, http://www.bdl.fr, by J.-E. Arlot, Ch.
Ruatti and W. Thuillot. Many thanks! The authors state these are generally
good to 1/2 arcsecond accuracy. In my test against JPL DE405 I would say this
is true about 50% of the time, with a worst case of about 4 AS.

Outside this range, Jupiter's moons based on information in "Astronomical
Formulae for Calculators" by Jean Meeus. Richmond, Va., U.S.A.,
Willmann-Bell, (c) 1982. Saturn's moons based on code and ideas supplied by
Dan Bruton, Texas A&M, astro@sfasu.edu. For all dates, ring tilts based on
"RINGS OF SATURN" program by Olson, et al, Sky & Telescope, May 1995, page
95. C code as converted from BASIC by pmartz@dsd.es.com (Paul Martz).

Thanks to Monty Brandenberg, mcbinc@world.std.com, for his assistance
and solution to the unaligned access messages on Digital UNIX.

Thanks to Jean-Etienne.LAMIAUD@tcc.thomson-csf.com for a fix to prevent
gif color tables from hogging more than their share of X colormap entries
and many corrections to xephem.sit.

Thanks to Stuart Levy, slevy@ncsa.uiuc.edu, for his work converting the Tycho
ESA mission database adc.gsfc.nasa.gov:/pub/adc/archives/catalogs/1/1239 into
xe format.

Many formulas and tables are based, with permission, on material found in:
"Astronomy with your Personal Computer" by Dr. Peter Duffett-Smith,
Cambridge University Press, (c) 1985.

The high precision planet positions were implemented for XEphem by Michael
Sternberg <sternberg@physik.tu-chemnitz.de> based on the papers

    "Planetary Theories in rectangular and spherical variables:  VSOP87
    solution" by Bretagnon P., Francou G., in Astron. Astrophys. 202,
    309 (1988), ftp://ftp.bdl.fr/pub/ephem/planets/vsop87/, and

    "Representation of planetary ephemerides by frequency analysis.
    Application to the five outer planets" by Chapront J., Astron.
    Astrophys. Suppl. Ser. 109, 181 (1995), ftp://adc.gsfc.nasa.gov/\
    pub/adc/archives/journal_tables/A+AS/109/181.

    See the comments in chap25.h and vsop87.h for accuracy estimates.

The high precision Moon code was also implemented for XEphem by Mr. Sternberg
based on code supplied by Stephen L. Moshier <moshier@world.std.com> at
ftp://ftp.std.com/pub/astronomy/selenog.zip. Mr. Sternberg also incorporated
the algorithm for deltaT, based on code also provided by Mr. Moshier. See the
comments in deltat.c for full references. My greatest thanks to Messrs.
Sternberg and Moshier for their generous and kind assistance in making XEphem
a program of first-class accuracy.

The improved lunar libration trig series fit to JPL DE403 was provided by
Stephen L. Moshier, <moshier@world.std.com>.

Many thanks to Michael Naumann, Michael.Naumann@eso.org, and Miguel Albrecht,
malbrech@eso.org, at ESO and Tim Kimball, archive@stsci.edu, at STScI for their
help and support accessing the DSS at their institutions. And thanks to ESO
and STScI in general for offering this service at all.

Thanks to Seiichi Yoshida, seiichi@muraoka.info.waseda.ac.jp, for a subtle
fix to the constellation code in 3.1.

The sample spacecraft elements were furnished by Ron Baalke,
baalke@jpl.nasa.gov.  

Thanks to Vance Haemmerle, vance@toyvax.Tucson.AZ.US, for his updated and
appended lists of spacecraft elements, and work on improvements to the
solar system plotting of long-period trail sequences.

Thanks to Jeroen Valkonet (jeroenv@cvi.ns.nl) for planting the seed which 
grew into the new bitmap clipmask approach of drawing the stars.

Thanks to Jim Bell, jimbo@cuspif.tn.cornell.edu, and the team at Mars Watch for
encourage, support and ideas for the first Mars albedo map in XEphem. The
map as of Version 3.3 is from http://maps.jpl.nasa.gov/mars.html.

Thanks to Dimitromanolakis Apostolos <apdim@grecian.net> for his contribution
leading to support for fetching DSS in gzipped form.

Thanks to Miguel Albrecht, malbrech@serv2.hq.eso.org, at ESO for his assistance
and support of their fine Web access facilities to the GSC.

Rotated trail text uses the xvertext package. Here is the copyright:

    xvertext 5.0, Copyright (c) 1993 Alan Richardson (mppa3@uk.ac.sussex.syma)

    Permission to use, copy, modify, and distribute this software and its
    documentation for any purpose and without fee is hereby granted, provided
    that the above copyright notice appear in all copies and that both the
    copyright notice and this permission notice appear in supporting
    documentation.  All work developed as a consequence of the use of
    this program should duly acknowledge such use. No representations are
    made about the suitability of this software for any purpose.  It is
    provided "as is" without express or implied warranty.

IC.edb was submitted by Christos Siopis, siopis@astro.ufl.edu.

Constellation algorithm is from a paper by Nancy G. Roman, "Identification
of a constellation from a position", Publications of the Astronomical
Society of the Pacific, Vol.  99, p.  695-699, July 1987. Further contributions
from Chris Marriott and Ernie Wright. The list of boundaries is derived from
the three files constell.1875.data, constell.1875.hdr and constell.doc at
ftp://explorer.arc.nasa.gov/pub/SPACE/FAQ/.

Thanks to Dr. Harald Fischer (fischer@vs-ulm.dasa.de) for the GPS awk routine
and sample position database.

The high-precision precession routine is from 1989 Astronomical Almanac, as
interpreted by Craig Counterman. Mr. Counterman also deserves the credit for
providing the initial encouragement to write an astronomical tool specifically
for X Windows, and for significant assistance while developing the heliocentric
models.

The Earth map is derived from data supplied with xearth which included the
following notice:

   Copyright (C) 1989, 1990, 1993, 1994 Kirk Lauritz Johnson

   Permission to use, copy, modify, distribute, and sell this
   software and its documentation for any purpose is hereby granted
   without fee, provided that the above copyright notice appear in
   all copies and that both that copyright notice and this
   permission notice appear in supporting documentation. The author
   makes no representations about the suitability of this software
   for any purpose. It is provided "as is" without express or
   implied warranty.

   THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
   INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS,
   IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, INDIRECT
   OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
   LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
   NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
   CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

The pulsar and Radio databases are based on lists supplied by Robert Payne,
rpayne@nrao.edu. Errors in converting to XEphem are mine.

The lunar image is based on one I found surfing at: ftp://seds.lpl.arizona.edu
/pub/images/planets/moon/fullmoon.gif. The calculations for the longitude
of the terminator and the solar altitude are based on the program colong.bas
by David Bruning and Richard Talcott, published in _Astronomy_, October 1995,
page 76.

Thanks to Richard Clark (rclark@lpl.arizona.edu) for an improved version
of anomaly.c.

A great source of comet information is http://encke.jpl.nasa.gov.

Special thanks to Uwe Bonnes, bon@LTE.E-TECHNIK.uni-erlangen.de, and
Ralphe Neill, ran@rdt.monash.edu.au, for their many ideas and support.

Many test cases were gleaned from the pages of Sky and Telescope, (C) Sky
Publishing Corp.

Most of the sample cities in the "xephem.sit" file are from the xsat program,
which included the following notice:

    Copyright 1992 by David A. Curry

    Permission to use, copy, modify, distribute, and sell this software and its
    documentation for any purpose is hereby granted without fee, provided that
    the above copyright notice appear in all copies and that both that copyright
    notice and this permission notice appear in supporting documentation.  The
    author makes no representations about the suitability of this software for
    any purpose.  It is provided "as is" without express or implied warranty.

Most of the sample observatories in the "xephem.sit" file are transcribed,
with permission, from the table beginning on page 28 in the July 1993 issue of
Sky and Telescope. Any errors in transcription are strictly my own.

Thanks to Lowell Observatory and the Minor Planet Center for maintaining
their huge lists of asteroids. See ftp://ftp.lowell.edu/pub/elgb/astorb.html
and http://cfa-www.harvard.edu/cfa/ps/mpc.html, respectively.

Thanks to the National Space Science Data Center and the Smithsonian
Astrophysical Observatory for the SAO star catalogue.

Thanks to the members of the Saguaro Astronomy Club for the preparation and
free distribution of their deep-sky database. Any errors in conversion to the
.edb format are strictly mine.

Thanks to Chris Beecroft <aldebaransys@home.com> for his encouragement and
technical assistance in adding postscript. The limited results in no way
reflect on his capabilities. Initial encouragement was also received from Frank
M. Siegert <frank@miranda.tue.schwaben.de>. And thanks to everyone who has
asked for printing over the years -- I now admit that I like it too!

Bright stars are based on the 5th Revised edition of the Yale Bright Star
Catalog, 1991, from ftp://adc.gsfc.nasa.gov/pub/adc/archives/catalogs/5/5050.
Common names supplied by Robert Tidd (inp@violet.berkeley.edu) and Alan Paeth
(awpaeth@watcgl.waterloo.edu). Any errors in conversion to the .edb
format are strictly mine.

I wish to thank all the organizations behind the incredible Internet for its
maintenance and free and easy access. I also wish to express my hope that
it retains the spirit of cordial cooperation it fostered in its formative
years.

I learned most of what I know of X Windows and Motif programming from ICS
courses and material found in the various excellent texts from O'Reilly &
Associates, Inc.

Thanks to MIT and the X Consortium for inventing, championing and maintaining
the X Window system, and the various contributing organizations to the Open
Software Foundation for Motif. Their vision of network-aware graphics is
still unmatched.

Similarly, I will be forever indebted to all who contributed to UNIX. My
passion and appreciation for this remarkable operating system matured while I
enjoyed four wonderful years at Kitt Peak National Observatory (now the National
Optical Astronomical Observatory), Tucson, AZ, in the early 80's. As with X,
UNIX plays a central role in my enjoyment of a career in scientific computing.

It was at KPNO where I met the late Mr. W. Richard Stevens, a fellow champion
of the elegance of the UNIX architecture, life-long friend and mentor.

Special thanks to all the folks over the years who have provided innumerable
ideas, suggestions and bug reports, both for XEphem and its ancestor, ephem. A
major benefit to writing and distributing these programs has been the chance to
make many friends from around the world.

Elwood Downey
ecdowney@ClearSkyInstitute.com

@Date/time
XEphem uses many values that get entered in some variation of A/B/C form.
Examples include date, time, longitude and step size. We call this a "triad"
input format.


Times and RA are entered and displayed in h:m:s format. If you pick such a time
field to change it, any of the h, m, and s components that are not specified
are left unchanged from their current value.  For example, 0:5:0 set hours to
0, minutes to 5, seconds to 0, whereas :5 sets minutes to 5 but leaves hours
and seconds unchanged.  A negative time is indicated by a minus sign (-)
anywhere before the first digit.


Dates are entered and displayed in any one of month/day/year, year/month/day
or day/month/year form. A Preference selection on the Main menubar, and
controlled by the XEphem resource DateFormat, selects which form is currently
being used.

As with time, components omitted when entering a new date retain the current
value.  For example, if the current date is 10/20/1988 and you type 20/30
the new date will become 20/30/1988. If you then type //2000 the new date will
become 20/30/2000. Note you must type the full year since the program is
accurate over several centuries either side of 1900.

If you change the date, the time (i.e., partial day) will not change.

Negative years indicate BC dates. For example, Jan 1, 1 BC is given as
1/1/-1.  There is no year 0.


Two other ways to set the date are supported for compatibility with some
published comet ephemerides.  You may enter the day portion as a floating
point number. When you set the day this way, the time will also change to
correspond to the fractional portion of the day. For example, noon on Jan 2,
1995, may be entered as 1/2.5/1995.

You may also enter a date as a decimal year, as in 1990.12345. Also, when
the date format preference is set to M/D/Y or D/M/Y the decimal point may be
omitted if the value is not a reasonable month or date value, respectively.
Decimal years are useful in interpreting plot files that include a date field,
since date fields are stored in plot files as decimal years. Any input that
includes exactly one decimal point is assumed to be a decimal year.


Other parameters such as declination, azimuth, altitude, longitude, latitude
and "Step" are entered and displayed in d:m:s format and also fall into the
general triad format. The same rules apply to these with respect to only having
to set the portions that are being changed and the typing conveniences.


For typing convenience, the slash (/) and colon (:) used in any field may also
be entered as a hyphen (-), semicolon (;) or comma (,). (Yes, "1-1--1" works
for 1 BC.)

@Notes
1) The program uses a horizontal plane tangent to the Earth Elev feet above
sea level as the horizon for all altitude calculations, rise/set events, etc. 
Due to Earth's curvature, this is not the same as the angle up from the local
horizon unless the observer is directly on the ground. The effect can be found
from:

     sin(a)**2 = (h**2 + 2Rh) / (R+h)**2
 where:
     R = radius of earth
     h = height above ground (same units as R)
     a = increase in altitude

The effect can be significant. For example, the effect is more than two arc
minutes at a height of 5 feet.

2) The accuracy of the planetary predictions, including the Moon, is 
consistently much better than one arc second within a few hundred years of
today, and of order of one arc second or better for a few thousand years. See
the comments in chap95.c, vsop87.c and moon.c. Other heliocentric objects are
well within one arc minute at the time of the epoch of their elements; this
steadily worsens with time since XEphem does not apply perturbations.

Using a GPS position locator and transit, I have independently verified
Sun and Moon limb rise and set times are accurate to within one minute and
azimuths are with about 0.1 degree.

3) The Sun-Moon distance is the solution for the third side of a planar
triangle whose two other sides are the Earth-Moon distance and Earth-Sun
distance separated by the angle of elongation.

4) The visual magnitudes for the planets take into account the phase of the
illumination; the magnitudes for other solar system objects do not.

5) Futures...

TODO:
 + add tick marks (third axis?) to plots.
 + write a tool to find g/k from a set of predicted magnitudes.
 + add undo for plot and listing selections.
 + let xephem put things in the root window.
 + display occultation path between *any* two objects in the Earth view
 + show correct Moon phase and orientation in Sky View.
 + be able to assign valid time spans to orbital elements.
 + actually use dimmer dots, not smaller dots (cut in half for each mag step).
 + support for RealSky CDROM set worth it? I prefer waiting for DVD version.
 + add sidereal day and month trail intervals.
 + just show month/year in trails when they change
 + comet tail pointer
 + include support for meteor showers, eg, dedalus
 + resizable/pannable FITS image
 + be able to paste Data Table and other fields to X clipboard
 + allow using a tracked object as the reference for a trail
 + command line version which generates a skyview gif
 + arbitrary solar system perspective
 + option for rise/set info to be Today or Next.
 + add "Plot JD as years" to plot display
 + add H:M:S trails Format option
 + add option to retain screen background color in skyview printing.
 + close pairs auto listing with update too

Known Bugs:
 - Pref->Zone should probably apply everywhere.
 - Pref->Zone does not update dates of FM/NM if they happen to squirm.
 - constellation figures could stand some improvement.
 - length of night wrong when savings time causes dusk after midnight
 - center constellation names based on boundaries rather than on figures
 - solar trails don't account for long-term (10's of years) precession
 - changing font shrinks sky and Earth views unless their view has changed once
 - plot View settings not Saveable.

@Plot
This window controls the plot generation and display functionality of XEphem.
You may select most numeric information displayed by XEphem, in pairs, to
form x/y coordinates of a plot. You may select up to ten such pairs. You
then select a file to contain the plot information. XEphem adds one line of
information to the file for each x/y pair each time iteration step. XEphem
can also plot any such file on the screen. The file format is compatible
with the character version of XEphem, ephem.

Selecting data to plot:

    Select the "Select fields" toggle button to make each field in the other
    windows that are eligible for plotting appear as a pushbutton. Select each
    such button as desired to form the x or y component of a plot. As you make
    the selections, they are listed in the table. You may also associate a
    one-character tag with each line. These tags will be included in the plot
    display for identification later. Once all the field choices have been made
    you may return all the windows to their normal operational appearance by
    reselecting the same toggle button.

Specifying the plot file name:

    Type the name of the file to be used to contain the plot information in the
    text field provided. When XEphem first needs to write to the file, it will
    first check for the existence of the file and, if it already exists, ask
    whether you wish to append to the file or overwrite it.

    A leading `~' in the filename will get expanded to the value of your HOME
    environment variable.

Specifying a plot file title:

    Enter a short title for the plot information in the text are provided.  When
    XEphem first writes to a plot file, it will place the contents of the title
    text area, if it is not empty, into the file as a comment. All lines within
    a plot file that do not begin with an alphanumeric character are considered
    comments and are ignored. If the first line of a file is a comment, XEphem
    will use it as the title for the plot when it displays the plot.

Generating the plot entries:

    Once the fields have been specified and the plot file named and titled, you
    may select the "Create plot file" toggle button when ready. Now each time
    XEphem goes through one iteration the values you have selected and their
    tags will be written to the plot file. Note that when plotting is
    activated, XEphem does not update the screen until the "N Steps" count
    goes to 1. This greatly speeds the creation of plot files by avoiding
    screen updates. If you wish to watch each iteration, set "N Steps" to 1
    and select the "Update" button manually for each iteration. Once all the
    desired data has been entered into the plot file, toggle the plot button
    back off to flush all data and close the file.

    The windows that contain each of the fields used in the plot need not be
    visible while the plot is being generated.

Viewing plot files:

    Existing plot files may be viewed by entering their name into the text field
    provided and selecting the "Show plot file" pushbutton. As many different
    plot files may be viewed simultaneously as desired. Each plot has separate
    controls for flipping the X and Y axes and for turning on and off a
    reference coordinate grid.

    The XEphem distribution kit includes a sample plot file of the analemma.
@Listing
This window controls the list generation functionality of XEphem.  The fields
you select define columns of a table written to a file as XEphem runs.
These columns look exactly like their corresponding fields on the XEphem
windows and so are more familiar and readable than the entries in plot files.
They are designed to be used in further text processing operations or
printed as-is. Two spaces are placed between each column.

Selecting data to list:

    Select the "Select fields" toggle button to make each field in the other
    windows that are eligible for listing appear as a pushbutton. Select each
    such button as desired to form each column of the listing. As you make the
    selections, they are listed in the table. Once all the column choices have
    been made you may return all the windows to their normal operational
    appearance by reselecting the same toggle button.

Specifying the listing file:

    Type the name of the file to be used to contain the listing in the text
    field provided. When XEphem first needs to write to the file, it will first
    check for the existence of the file and, if it exists, ask whether you wish
    to append to the file or overwrite it.

    A leading `~' in the filename will get expanded to the value of your HOME
    environment variable.

    You may also elect to print the file in LaTeX table format by pressing
    the given button before beginning to list to the file.

Choosing to include column headings:

    When this option is selected, column headings are written to the output
    file each time the file is opened.

Specifying a listing file title:

    All lines within a listing file that do not begin with an alphanumeric
    character are considered comments and are ignored.  When XEphem first writes
    to a listing file, it will place the contents of the title text area, if it
    is not empty, into the file as a comment for your convenience.

Generating the listing entries:

    Once the fields have been specified and the listing file named and titled,
    if desired, select the "Create list file" toggle button. Now each time
    XEphem goes through one iteration the values you have selected will be
    written to the file. Note that when listing is activated, XEphem does not
    update the screen until the "N Steps" count goes to 1. This greatly
    speeds the creation of listing files by avoiding screen updates. If you
    wish to watch each iteration, set "N Steps" to 1 and select the "Update"
    button manually for each iteration. Once all the desired data have been
    entered into the listing file, toggle the list button back off to flush
    all data and close the file.

    Menus that contain each of the fields used in the listing need not be
    visible for the fields to be listable.
@Search
This window controls the automatic equation solving facility. You define an
arithmetic or boolean function, using most of the fields XEphem displays, then
XEphem will automatically evaluate the function and adjust the time on each
iteration to solve for the goal.

To set up a function to solve, follow these steps:

   Enter a function,
   Compile it,
   Select a goal,
   Set the desired accuracy,
   Enable solving,
   Start the solving process.

Each of these steps is described below.

Entering the function:

    The function may be any arithmetic expression, in C-language syntax.  All
    of C's comparison, logical and arithmetic operators are supported as well
    as several common arithmetic functions. Here is the complete list:

	  + - * / && || > >= == != < <=
	  abs floor sin cos tan asin acos atan degrad raddeg pi log
	  log10 exp sqrt pow atan2

    The function is entered into the text line provided. It may utilize most of
    the fields from the other XEphem windows. Press the "Enable field buttons"
    button to make each available field a button. Where ever a field is desired
    in the function, position the text insertion cursor at the desired position
    and select the field; its name will be inserted into the function text. When
    you are finished defining the function, turn off the field button appearance
    by selecting the "Enable..." button again.  Once you get to know the names
    of the fields you may also enter them manually, if you prefer.

Compiling the function:

    Once the function has been entered as desired, it must be compiled by
    selecting the "Compile" button (or by pressing the Return or Enter key on
    your keyboard).  If there are any errors, a diagnostic message will appear
    just below the function. Once a function has been successfully compiled,
    the message will read No compile errors. If the function is modified, a
    message will remind you that it has not been compiled. Each time a
    function is successfully compiled, XEphem updates all fields and evaluates
    the function. As explained below, this can be used as a sort of
    "astronomical calculator" even when not actually solving anything.

Selecting a goal:

    You may choose from any of three evaluation algorithms, as selected by the
    trio of radio buttons. "Find extreme" will solve for a maxima or minima of
    the function. "Find 0" will solve for a time when the function evaluates to
    zero.  "Binary" will keep incrementing time by "Step" (in the Main
    window) until the state of the function changes, then do a binary search to
    find the exact time when the function changes state. Binary search
    interprets a function that evaluates to zero to be in one state and all
    other values to be the opposite state. Generally, binary functions are
    comprised of logical operators at their outermost expression levels.

Specifying the desired accuracy:

    Searching will automatically stop when the time changes by less than the the
    accuracy value. Note that this method of detecting convergence is not based
    on the value of the search function itself. To change the desired accuracy
    press the pushbutton showing the current accuracy next to the "Accuracy"
    label and enter a new value in the window.

Enabling the solver:

    Once the function is defined and it compiles without errors, you may enable
    searching for a solution by selecting the button at the top labeled
    "Solving is Active". Then, each time "Update" is selected on the Main
    window the solution advances by one time step until either "N Steps"
    iterations have occurred or until "Step" becomes less than Accuracy. The
    initial time and step size are set from the Main window, and are adjusted
    automatically as the solution proceeds. Note that by setting "N Steps" to 1
    and repeatedly selecting Update you can effectively single-step the
    process. Solving will automatically turn off when convergence is detected,
    the function is edited or you may turn it off manually at any time by
    toggling the button labeled "Solving is Active" back
    off.

Additional notes on using the equation solver:

    When selecting fields for plotting or listing a button appears labeled "Use
    for plotting". You may select this button to use the evaluated function as
    an item in the plot or listing feature. Note that the function may be used
    in plotting and listing whether or not actually solving is enabled.

    The windows which contain the fields used in the function being solved need
    not be visible while solving is in progress.

    The "Close" button removes the Solving window from the screen; it does
    not effect actual solver operation in any way.

    A successfully compiled function is evaluated each time XEphem updates.
    Whenever the function is compiled it is also evaluated using freshly
    updated values. In this way, the Solve window can actually be used as an
    arbitrary "astronomical calculator" at any time, whether or not solving
    is actually active.

Hint:

    Solving periodic functions can lead to solutions far from the intended
    range. You will get best results if you can start the search near the
    expected answer and with a small step size that bounds the solution. You
    can use the plotting feature to study a function and get an idea of the
    solution, then use the solver feature to zero in.
@Data Table
This is a table of information about each planet, the Sun, Moon, and any three
user defined objects, ObjX, Y and Z. Each data item occupies one column in
the table and each object occupies one row.

The Control pulldown menu contains the following options:

    Setup ...

	This button brings up a configure window to specify the table rows and
	columns as desired.

    List ...

	This button allows the current data table to be saved in a text
	file.

When any columns related to rising or setting are active a box at the bottom
will indicate whether the times refer to the center or the upper limb of the
object. Similarly, when either the RA or Dec columns are active or any of the
separation columns are active a box will be present to indicate whether the
separation is from a geocentric or topocentric point of view. The box will
also indicate the precession epoch. See the help for the "Setup" window for
more information about these modes.

Any of the information in this table may be plotted, listed or used in a
solver algorithm. See the help for these control functions for more details.

See the help for the "Setup" window for a description of each column.
@DataSelection Table
This window lets you configure which rows and columns will be in the Data
Table.  When this window first comes up it will be set to indicate the state
of the Data Table. You may then manipulate the toggle buttons as desired. To
actually change the Data Table to a new configuration select the "Apply"
button.  "Ok" does the same thing but also closes this window. "Close" just
closes this window without making any permanent changes. In addition to
manipulating each item individually, each columns includes handy shortcut
controls at the top to make changes to column as a whole.

The first column of this window selects which rows will be present in the Data
Table. The planets and the Sun and Moon are always in this column. If user
defined objects ObjX, Y or Z are defined then they will also be present and
controllable from this column. See the help for the "Set ObjXYZ" window for
more information about user defined objects.

Entries in the remaining three columns in this window control which columns
will be present in the Data Table. They are grouped into three categories
for convenience.

Column two controls miscellaneous basic information. The descriptions of
each entry are as follows:

 Cns           name of the constellation in which the object appears.

 RA            Right ascension: if Main Epoch is set to EOD this is the
               apparent place, otherwise it is the astrometric (mean) place.
	       If Main Preference Equatorial is Topocentric, it is further
	       corrected for parallax.

 HA            geocentric or topocentric hour angle of object, computed as
               LST-RA precessed to EOD. Positive angles are west of the
	       meridian.

 Dec           Declination: if Main Epoch is set to EOD this is the
               apparent place, otherwise it is the astrometric (mean) place.
	       If Main Preference Equatorial is Topocentric, it is further
	       corrected for parallax.

 Az            topocentric degrees eastward of true north for object.

 Alt           topocentric degrees up from a horizontal plane that is Elevation
               feet above sea level. Corrected for refraction.

 Zenith        topocentric Zenith distance, degrees; corrected for refraction.

 Air           Number of relative air masses through which light from the object
               passes to the topocentric observer. Computed by the method of
	       Hardie, clamped to a max at 3 degrees altitude.

 HeLong        true heliocentric longitude, in degrees.  Earth's is displayed
               on the Sun's line.  For the Moon this is the geocentric
               longitude.

 HeLat         true heliocentric latitude, in degrees.  For the Moon this is
               the geocentric latitude.

 GLong         galactic longitude, in degrees.

 GLat          galactic latitude, in degrees.

 EcLong        ecliptic longitude, in degrees.

 EcLat         ecliptic latitude, in degrees.

 EaDst         true distance from Earth center to object center, in AU, except
               distance to the Moon is in miles or km depending on the Units
               preference.

 EaLght        time for light to travel from Earth to object. Format is hh:mm
               for all solar system objects, except the Moon is in decimal
               seconds.

 SnDst         true distance from Sun center to object center, in AU.

 SnLght        time for light to travel from Sun to object. Format is hh:mm.

 Elong         spherical angular separation between the Sun and given object,
               calculated from the their geocentric ecliptic coordinates. Note
	       this is not just the difference in ecliptic longitude, as is
	       sometimes used. The sign is positive for an evening object or
	       negative for a morning object. Thus, this field is not generally
	       useful in searching for eclipses because of the discontinuous
	       sign change which occurs at conjunction. For that, use the
	       individual Separations fields.

 Size          angular size of object, in arc seconds. If not otherwise given,
	       estimated for objects in heliocentric orbits from the absolute
	       magnitude parameter H and by assuming an albedo of 0.10, for
	       which H is 18 for an object of 1.06 km diameter at 1.0 AU.

 VMag          visual magnitude of object.

 Phase         percent of visible surface in sun light.

Column three controls information related to rising, transitting, and
setting. These are computed based on a refraction model that uses the actual
atmospheric and topocentric circumstances displayed on the Main window. A text
entry field is available in which you may specify a number of decimal degrees
the local horizon is above horizontal to account for local effects.

The "Limb" option means that the rise and set circumstances are based on the
location of the upper limb of the object. "Center" means that the circumstances
are based on the location of the center of the object.

Follows is a description of the Data Table columns controlled by the third
Data Selection column:

 RisTm
 RisAz    The local or UTC time and azimuth when the upper limb (or center) of
          the object rises TODAY. See note below for Earth satellites.

 TrnTm
 TrnAlt   For all but Earth satellites, this is the local or UTC time and
          altitude when the object crosses the meridian TODAY, i.e., when its
	  azimuth is true south or, if no precession, when the local sidereal
	  time equals the object's right ascension. If the object is an Earth
	  satellite, this is the time and highest altitude the satellite ever
	  reaches above the local horizon (at whatever azimuth).
 SetTm
 SetAz    The local or UTC time and azimuth when the upper limb (or center) of
          the object sets TODAY. See note below for Earth satellites.

 HrsUp    The number of hours the object is up TODAY, that is, the difference
          between the set and rise times. See note below for Earth satellites.

Note for time zones:

    Rise and set circumstances are all computed in local time. If the Zone
    Display preference (from the Main menubar) is set to UTC then the times are
    converted to UTC. Thus, when reference is made to TODAY it means the
    current local date, not UTC date.

Note for Earth satellites:

    Due to their generally rapid motions Earth satellites often have many
    rising and setting events per day. For this reason, the rise and set time
    for satellites are not restrained to be during the current local day.
    Rather, for satellites, XEphem displays the very next rising and setting
    events that occur strictly later than the current time on the Main window,
    provided they occur within 24 hours. This means that if the rise or set
    time displayed is earlier than the current local time on the Main window, it
    actually refers to the next day. This doesn't happen for the other objects
    because their times are restricted to events that happen just today.
    Similarly, we can only compute the HrsUp column if the set time is
    strictly later than the rise time.

    The upshot of all this is that the best way to really understand the
    visibility of a satellite in your area is by graphing its altitude over
    the desired time interval.

Various "odd ball" rising, transit and setting conditions are accounted for
and marked when they occur as in the following table. Note that in the case of
Earth satellites, "TODAY" really means within the next 24 hours.

 NoRise       up some time but never rises, as such, TODAY.
 NoSet        up some time but never sets, as such, TODAY.
 NoTran       up some time but doesn't transit, as such, TODAY.
 CirPol       object is circumpolar (never goes below horizon) TODAY.
 NvrUp        object is never above the horizon TODAY.


The last column in the Data Table setup window controls for which objects
angular separation is computed.  Each entry in the Data Table will be the
angular separations between each pair of objects, in degrees.

The vantage point for the Separation values depends on the Equatorial
preference in the Main window. "Geocentric" ignores local conditions and gives
the separation as seen from Earth center. "Topocentric" uses the local
conditions known to XEphem. The choice is particularly critical for lunar
occultations and Earth satellites, of course, but the effect can be significant
for the planets as well. Geocentric separations between objects and the Sun
will match the magnitude of the elongation given in the Data Table window.

When ObjX, Y or Z are defined, these will appear in the last column and
separations between them and the other objects (in column 1) may be selected
for display.

Note:

Solving over a period that will include the rise or set times of either
object is generally better performed from the geocentric viewpoint.  The
refraction effect of the topocentric viewpoint causes many arc minutes of
rapid whiplash displacement as the objects rise and set that overlays the
smooth celestial motion of the objects.  This rapid position variation can
confuse the solver algorithms that expect fairly smooth functions.
@Moon
+Moon - intro
+Moon - mouse
+Moon - control
+Moon - view
+Moon - scale
@Moon - intro
This is an image of the Moon, shaded to indicate phase. It may be flipped and
scaled as desired and many Lunar features may be labeled, including most
spacecraft landing sites. During a Lunar eclipse, the edges of the umbra and
penumbra regions are drawn as solid and dashed lines, respectively.

The coordinate system on the Moon is such that latitude increases towards
the north and longitude increases towards the east. When facing the Moon with
the unaided eye, lunar east is towards the right. The lunar image in XEphem 
is oriented with the polar axis vertical on the screen. Letters are placed at
each edge of the image to show nominal celestial directions.

If at least three colors can be allocated the image is rendered with at most 30
shades of gray; if only two colors can be allocated it is dithered into a
black and white image.

The Moon nods and rocks slightly as it moves through the sky. This motion is
called libration. A dot is placed on the circumference of the image to indicate
the limb position that is currently tilted most towards Earth due to libration.
The angular position of the dot is placed accurately but the image rendering
is not adjusted for libration effects. Thus, the surface features over which
the dot and the terminator appear in the image are only approximate. See the
Help for "More info..." under View for more information on libration.

@Moon - mouse
Mouse controls:

    Left button:

	Activating the left mouse button while over the lunar image will
	display a small magnified 2x view of the lunar surface under the
	cursor. The magnified image will track the cursor as it is moved around
	the image. The latitude, longitude and solar altitude of the location
	are displayed in the "More info..." window. See Help for View for more
	information about this window.

    Right button:

	Activating the right mouse button while over the lunar image will bring
	up a popup menu. If the location is near an item in the lunar features
	database, the name of the feature, its type, diameter in miles or km
	(depending on Preferences->Units), location and solar altitude at its
	center are displayed in the window. A toggle button will also be present
	which controls whether the label for the feature will be persistent,
	that is, shown regardless of whether View->Features is activated.
	Persistency is automatically reset if the Scale is changed. If the
	location is not near a feature, then only location and solar altitude
	are displayed in the window. The algorithm chooses the smallest and
	closest feature about which to report.  

	Activating the right mouse button while not over the lunar image but
	near a sky background object will bring up a popup menu containing the
	name and magnitude of the object. One of the following two options
	will also be available:

	Assign ->
	    To ObjX
	    To ObjY
	    To ObjZ

	    This cascade allows you to assign the given object to become ObjX,
	    Y or Z, as desired. This will also cause all other views which are
	    currently making use of this object to be updated and the object
	    will be added to and selected by the Data table. Also, since this
	    makes the object one of the User-Defined objects it will now appear
	    directly in the Sky View->Locate pulldown menu.

	Show in Data Table:

	    This option is only offered when the object chosen under the cursor
	    is a planet, the Sun or the Moon. Selecting this option forces the
	    object to be enabled in the Data Table.

    The two features may be activated together if desired by first pressing
    the left button then the right button. This is helpful when trying to
    locate a particular feature in the magnified view. Try to always release
    the right button to dismiss the popup before releasing the left button. If
    you release the left button before the right button, the magnifying glass
    will remain on the image. If you run into this, you can activate the glass
    again and mop up the remains of the old glass.

@Moon - control

Control options:

    Print...

	This selection allows printing the current Moon view or saving it to
	a file.

    Field Stars...

	This selection activates the Field Star setup window. For more 
	information about this facility, see the Help for the Field Star
	window itself.

    Set Earthshine...

	This brings up a window containing a scale which allows you to set how
	bright the Earthshine is in the Moon image. The value ranges from 0,
	black, to 10, full sun light. Full sun light is useful when you would
	like to peruse the Lunar surface but would rather not change the XEphem
	date to a full Moon.

	This value depends on the gamma of your display. A fine discussion of
	display gamma and a test image with which you can determine the gamma
	value of your own display may be found at the URL:

	    http://www.cs.cmu.edu/afs/cs.cmu.edu/user/rwb/www/gamma.html.

    Movie Demo:

        This sets up an automatic display movie of the Moon. This is
	done by setting the N Steps entry in the Main window to a large value;
	setting the Step to two hours if Sky background is Off or to one
	minute if it is On; and starting XEphem looping. The movie can be
	stopped by selecting this option again or by selecting Stop from the
	Main window.

    Close:

	This closes the main Moon display and, if open, the More info window.
	The image is never updated while it is closed. However, for
	convenience, if any of the fields in the More Info window are being
	used for listing, plotting or solving, the continue to be updated even
	when the window is closed.

@Moon - view

Views options:

    Spacecraft:

	If set and the Scale is at 6, then all spacecraft landing sites are
	marked and labeled on the image. If the Scale is less than 6, then
	only the Apollo sites are marked.

    Features:

	This sets whether additional (non-spacecraft) Lunar features are
	labeled on the image. More features are labeled at larger scales.
	Even at the largest scale, all of the features are not labeled.
	However, all features are searched at all scales when using the 
	right-mouse click to interrogate a location.

    Sky background:

	This sets whether to show objects within the current field of view
	that are in the XEphem database memory or available from the Field Star
	facility. The size and symbol used for the object matches that of the
	Sky view when set for a minimum magnitude of 12. While this option is
	on, XEphem will continue to retrieve field stars as required.

    Use real image:

	This sets whether to render the Moon using a real image, or just a
	simple schematic drawing of the sun lit and earth lit portions. The
	latter option is primarily just for simpler printing. Even while
	this option is on, the magnifying glass will still show the real
	image, and the lunar features database is still accessible via
	the right mouse button.

    {Pen}Umbra:

	This sets whether to show circles at the edges of the umbra and
	penumbra during a Lunar eclipse.

    Flip T/B:

	This sets whether the image is flipped top-to-bottom.

    Flip L/R:

	This sets whether the image is flipped left-to-right.

    Grid:

	This sets whether a coordinate grid is drawn over the image. Each
	line is spaced at an interval of 15 degrees.

	Also, the current subearth location is marked with an X; the subsolar
	point is marked with a small open circle; and the anti-subsolar point
	is marked with a small filled circle.

    More info...:

	This brings up a separate window with additional information.

	The top portion of the window reports the location of the cursor as it
	is moved over the image, if the left button is pressed. It also shows
	the altitude of the Sun and the times when the Sun will next rise and
	set at that location. The times are in accord with the "Time zone"
	Preference in the Main window.

	The lower portion of the window shows the lunar longitude of sunrise,
	the lunar latitude of the subsolar point, and libration information.

	The longitude of the subsolar point is at +90 from the sunrise
	longitude, and the longitude of the anti-subsolar point is at -90.
	The libration in longitude is positive towards lunar east; latitude is
	positive towards lunar north. The Limb angle is zero at lunar north and
	increases towards lunar west. The Tilt is the number of degrees the
	Moon is tilted towards Earth around an axis defined by the librations
	in latitude and longitude. The limb location that is titled most
	towards Earth is indicated on the image by a small dot.

	Any of the values in the lower portion may be used for plotting,
	listing and solving in the usual way as described in the Help entries
	for these Control options. The values are always current when used in
	this way, even if the main Moon view is closed. For faster looping,
	close the main Moon display to prevent it from being redrawn each time.

@Moon - scale

Scale options:

    This pulldown menu presents a list of factors by which the lunar
    image may be scaled.  The image is presented in a scrolled window for
    panning if it is larger than the overall window.

@Mars
+Mars - intro
+Mars - mouse
+Mars - control
+Mars - view
+Mars - more info

@Mars - intro
This window displays an image of Mars as it currently appears from Earth center.
The resolution is 2/3 degree per pixel. The orientation is always parallel to
the Martian rotation axis. The NSEW markings are directions on the celestial
sphere.

@Mars - mouse

Left Button: 

    If the View->More Info window is open, then moving the mouse around over
    the image while holding the left button will display the Martian latitude
    and longitude under the cursor location.

    A magnifying glass also appears attached to the cursor.

Right Button:

    Pressing the right button while over the planet will present a popup menu. 
    Sliding down and releasing on the Point button in the popup will
    reposition the view so the current location is centered. This will also
    disable the shadow and the subearth marker until the next Update from the
    Main window. If over a feature, the popup will also contain its name,
    type, diameter (or largest dimension) and location. If not over a
    feature, the cursor location is shown.

@Mars - control

    Print...

	This selection allows printing the current Mars view or saving it
	as a Postscript file.

    Close

	This selection will remove the Mars view from the screen. If it is
	open it will also remove the More Info window.

@Mars - view

    Flip T/B

	This sets whether the image is flipped top-to-bottom.

    Flip L/R

	This sets whether the image is flipped left-to-right.

    Grid

	This sets whether a coordinate grid is drawn over the image. Each
	line is spaced at an interval of 15 degrees. Also, unless the image
	has been repositioned by hand, an X marks the center of the image, that
	is, the subearth location.

    Features...

	This brings up a separate window containing categories of surface
	features. Buttons across the bottom allow turning all features on,
	off or toggling. "Apply" puts the choices into effect, as will "Ok"
	which also closes the window.

    More info...

	This brings up a separate window with additional Mars information and
	control capabilities. Please see the help from that window for
	more information.

    Moon view...

	This brings up a separate window which depicts the two Martian moons.
	Please see the help from that window for more information.

@Mars - more info

    The top portion of this window reports the location of the cursor as it
    is moved over the image, if the left button is pressed.

    The lower portion of this window shows the Martian latitude and
    longitude which currently face the Earth. These values are computed
    each time an Update is performed from the Main Menu.

    Also provided is a scale by which you may set the size of your local
    seeing disk. The image will be blurred to roughly simulate the
    resolution under those conditions. The computing time will increase
    with larger seeing values.

    For browsing purposes, the values may be changed as desired. Adjust any
    or all scales, then press Apply to put the changes into effect. Forcing
    changes in this way will also temporarily disable the shadow. At the time
    of the next Update, the correct current values and the shadow will be
    reinstated. The Apply button is made insensitive if the scale values are
    correct for the current time; the button becomes sensitive only when the
    scales have been moved manually.

    The values in the lower portion may be used for plotting, listing and
    solving in the usual way as described in the Help entries for these
    Control options from the Main window. The values are always current when
    used in this way, even if the main Mars view is closed. For faster
    looping, close the main Mars display to prevent it from being redrawn
    each time.

@Mars Moons
+Mars Moons - intro
+Mars Moons - mouse
+Mars Moons - control
+Mars Moons - view

@Mars Moons - intro
This is a schematic view of Mars and its moons at the indicated date and
time. In addition, background sky objects may also be displayed.

The scale at the left controls relative magnification.

The scale at the right controls the dimmest magnitude which will be displayed.
Mars is always displayed. The values range from 20 at the top and 0 at the
bottom. Objects dimmer than the value specified are not shown.

Nominal celestial directions are indicated at the top and right edges.

Moons are displayed only if they are geometrically visible. Use the top
view to see whether they are also in sun light.

@Mars Moons - mouse
Mouse functions:

The mouse may be used to identify any object in the Mars view. Position
the cursor near the object of interest and select the right mouse button. A
popup menu will appear with the objects name, current location and magnitude.

@Mars Moons - control
Control options:

    Field Stars...

	This selection activates the Field Star setup window. For more 
	information about this facility, see the Help for the Field Star
	window itself.

    Telescope command:

	This option causes the location of Mars to be sent to a fifo. The
	fifo is opened and closed each time this selection is made. The
	intent is for the fifo to be connected to a telescope control process.

	This mechanism is the same as that provided by the Telescope 
	facility within the Sky view. Please refer to its help for more
	details.

    Movie Demo:

	This option will set up the Main window time step controls for a 15
	minute step size and start a loop which dramatically displays the
	motions of the moons as they orbit Mars. This selection automatically
	disables the View->Sky Background selection to insure reasonable speed.
	Push the button again to stop the movie.

    Close:

	This removes the Mars moon display, and the additional information
	window if present, from the screen.

@Mars Moons - view
View Options:

    Top view:

	Selects whether to also display another window, looking down on
	the Mars system from above the N celestial pole. This window will
	tend to remain aligned above the main view when either is resized.
	Moons are displayed only if they are in sun light.

    Sky background:

	Selects whether to also show objects within the current field of view
	that are in the XEphem database memory or available from the Field Star
	facility. The size of the object is determined by the limiting
	magnitude as specified by the scale at the right. Objects are drawn
	using the same symbols as used by the Sky view. While this option is
	on, XEphem will continue to retrieve field stars as required.

    Bright moons:

	If this option is in effect, then the diameter of all moons will be
	increased by 3 pixels. This option also insures that even those moons
	which are dimmer than the limiting magnitude, as specified by the scale
	to the right, will be drawn with a circle of diameter 3 pixels.

    Tags:

	Search whether to show the Roman numeral designation beneath each moon
	and a 1 arc-minute scale calibration line.

    Flip T/B:
    Flip L/R:

	These allow the scene to be flipped vertically and horizontally, 
	respectively.

    More info...

	This button brings up a separate window which contains quantitative
	information about Mars's moons. All values may be used in plotting,
	listing and solving.

	The E and S columns are 1 if the moon is visible from the Earth and
	Sun, respectively.
	
	The locations of the moons are given in two coordinate systems. The
	first three columns are the displacements of the moons in Mars
	radii with respect to the celestial plane. The next two columns
	give the RA and Dec location of the moons in the current epoch (as 
	specified on the Main window).

@Earth
+Earth - intro
+Earth - mouse
+Earth - control
+Earth - view
+Earth -- control dialog

@Earth - intro
This view displays a simple map of the Earth with continent outlines.  The
controls available from the menu bar across the top control the view,
additional information and the ability to overlay the ground positions of up
to three objects. The scales along the bottom and right edges display, and
may be used to control, the center location.

Any of basic Planets, Sun and Moon as well as ObjX, Y or Z from the XEphem
database may be displayed on the map. The surface location of an object is
marked with a bulls eye. The concentric circles indicate the locus of points
at which the object appears to be 0, 30, and 60 degrees above the local horizon.
When the Earth view is first displayed, the ObjX,Y,Z objects will automatically
be preselected and the view centered on ObjX, if they are defined. After
that, you are free to change things as desired. Note that these can be preset
directly at startup by using .edb database files containing exactly one
object each; see Data -> Load -> Help -> on Control for more information.

The location defined in the Main window is marked on the map with a plus (+).

If a solar eclipse is occurring on the Earth a small X will mark the location
of central totality. Try July 11, 1991 around 18:00 UT or May 10, 1994 around
16:00 UT.

All computations for Earth satellites are based on the NORAD SGP4/SDP4 code.
This code produces the exact same output as their test collection. This
means, however, that it is not integrated particularly tightly with the rest
of XEphem. For example, its computations use a different model for Earth
flattening and for refraction. These and other differences can lead to
modest inconsistencies.

@Earth - control
Control options:

    Print...

	This selection allows printing the current Earth view or saving it as
	a Postscript file.

    Objects...

	This brings up a window to control which of the User Defined Objects,
	OBJX, Y, Z, are displayed. See its own Help for full details.

    Set Main:

        This sets the Latitude and Longitude of the Main window to that of
	the current position of the Earth view. This also causes all other
	information and views to be updated to reflect the new location.

    Set From Main:

        This sets the Earth view position to that of the Main window.

    Movie Demo:

        This sets up an automatic display movie of the Earth. This is
	done by setting the N Steps entry in the Main window to a large value;
	setting the Step to 5 minutes; and starting XEphem looping. The movie
	can be stopped by selecting this option again or by selecting Stop
	from the Main window.

    Close:

        This causes both the Earth view and the extra statistics window to
	be closed.

@Earth - view
View options:

    Cylindrical
    Spherical
    Weather map

	These radio buttons select from several possible Earth projections.

	Cylindrical: Displays the entire Earth surface projected onto
	a cylinder. Primary advantage is the entire surface is visible at
	once. Particularly good for plotting satellite ground tracks.
	Major detraction is distortion near the poles.

	Spherical: Displays the Earth as it would really appear from space.
	The primary advantage is the sense of reality and lack of distortion.

	Weather map: Displays a global montage of satellite cloud imagery,
	ice, sea and land temperatures, courtesy Space Science and Engineering
	Center at the University of Wisconsin. The image is a gif file
	retrieved from http://www.ssec.wisc.edu/data/comp/latest_cmoll.gif.
	It is updated once every six hours. All other graphical features of
	the Earth view remain available as overlays to this image. Primary
	advantage is ease in determining whether weather will effect
	visibility of a satellite pass. If you have trouble accessing the
	image directly from XEphem, the program will also use the file
	/tmp/latest_cmoll.gif if it exists.

	The preferred width-to-height ratio for the cylindrical projection is
	3.14:1. This ratio is enforced each time this projection is selected
	by changing the width and maintaining the current window height,
	subject to remaining fully on screen. Similarly, the spherical
	projection resizes to become a square by setting the  width equal to
	the height. The weather map forces itself to become 640x480 pixels.
	After any projection is selected, the window size may be directly
	manipulated manually from then on as desired.

    Reload map

	This button is only present when the Weather map projection is
	enabled. Pressing it will cause a fresh weather map to be
	retrieved.

    -------------

    Grid:

        This toggles showing grids lines every 15 degrees in latitude and
	longitude.

    Sites:

	This toggles whether a tiny square will be drawn at each location
	found in the currently loaded Sites file

    Sunlight:

        This toggles whether the portion of the Earth's surface currently in
	sun light is highlighted in some fashion. When using the Weather map
	projection, the map is darkened where the Sun is currently down, and
	only cloud cover and continent outlines are shown.

    Live dragging:

	This toggles whether the display graphics are updated immediately
	as the sliders are moved, or whether graphics are only drawn after
	the sliders are released. Also, if this option is on, moving the mouse
	while holding down the middle button will cause the display to 
	rotate about the pole when moved left-and-right or about a horizontal
	line centered on the window when moved up-and-down. If your system
	is sufficiently fast, the effect in quite dramatic.

@Earth - mouse
Mouse functions:

    As long as the cursor is over the Earth, the four corners of the View
    will display the following information about the position beneath
    the cursor:

	Upper left:  Latitude
	Upper right: Longitude
	Lower left:  Local Mean Time
	Lower right: Local Sidereal Time

    Middle button:

	If View->Live dragging is On then while the middle button is depressed
	and located over the Earth map, the cursor is changed to a fleur
	pattern. Moving the mouse left and right is like moving the scale at
	the bottom; moving it up and down is like moving scale at the right.
	This provides a simple method to pan the display.

    Right button:

	If the right mouse button is depressed while over the Earth, a popup
	menu appears with information related to the location under the
	cursor as follows:

	    If the location is near a Site, information is presented with
	    respect to the exact location of that site, otherwise it is with
	    respect to the latitude and longitude of the location under the
	    cursor.

	    If the location is near the current or a trailed location of one
	    of the displayed objects, information is presented with respect
	    to the location under the cursor and for that object at the time
	    of the trail mark.

	In either case, there will also be a button labeled Point that, if
	activated, will center the orientation on the selected location.

@Earth -- control dialog
This window allows you to display up to three objects on the Earth view
simultaneously, with optional ground tracks.

There are three columns, one for each object. Click on an Option menu then
slide and release over the desired object. The list will always contain the
major Planets, Sun and Moon, as well as the three User Defined Objects, known
as ObjX, Y, Z, if they are defined (see Main -> Data -> ObjXYZ for more
information).

Several controls and information values are available for each object as
follows:

    Display:

	This controls whether the selected object is shown at all. If it
	is visible, the object is drawn with a bulls eye pattern. Each circle
	of the bulls eye indicates the locus of points where the object 
	appears in the sky 0, 30, 60 and 90 degrees from the zenith.

    Label:

	This controls whether the name of the object is drawn above it
	current location.

    Trail:

        This control will bring up a window to define a ground track of the
	given object as it travels along its orbit. Each trail time is drawn
	connected with a solid line with each point indicated with a small
	mark. The time stamps shown with the trail, if any, are always
	in UTC.

	Once a trail is defined, this toggle just turns the trail On or
	Off on the display. It will not bring up the Trail window again
	unless the trail gets deleted.

	The trail will be deleted if the object is changed, or an Update
	occurs from the Main window while this toggle is Off. Creating a new
	trail will also delete the old one.

	See the Help from the trail setup window itself for more details on
	how it operates.

    Center:

	As long as this toggle is On, the given object will remain centered
	in the display (to the extent possible). Only one object may be
	in control at a time. When all of these toggles are Off, the Earth
	view will remain fixed unless changed manually (via the Scales on
	the edges, setting from Main, or using the Mouse controls). This toggle
	is automatically turned off if any of these manual methods are used.

    Popup obj:

	This toggle selects the object to which the Button-3 popup's Alt/Az
	info refers, as seen from the current Main menu position.

    SubLat:
    SubLong:

	The latitude and longitude of the ray connecting the object with the
	center of the Earth. These values are shown for all types of objects.

The following data are only available for Earth satellites:

    Alt:

	Height above sea level.

    Range:

	Distance from the Main location to the given satellite.

    Range Rate:

	The rate of change of the Range distance, with positive moving towards
	the Main location.

    Sun lit:

	1 if the given satellite is currently in sun light, else 0 if it is
	eclipsed.

    Age:

	The difference between the current XEphem Main time and the epoch
	of the TLE orbital elements, in days. The larger this value, the
	more the satellite location will be in error. Errors depend on
	drag, maneuvers and initial state vector quality.

Each of these values may be used for plotting, solving and listing in the
usual way (see the help items for these features). While looping with Pause
set to 0, only the graphical display is updated (though numeric information
is always updated internally each step).

If a User Defined object is set elsewhere in XEphem and an unused column is
available it will automatically be selected and Center will be activated
as a convenience.

@Sky View
+Sky View - intro
+Sky View - control
+Sky View - locate
+Sky View - ops
+Sky View - filter
+Sky View - telescope
+Sky View - history
+Sky View - mouse
+Sky View - trails
+Sky View - scales
+Sky View - misc

@Sky View - intro
This window presents a graphical view of the sky, potentially showing each
object currently loaded in the XEphem database subject to several filtering
and display criteria.

The dominant center area is the sky display of objects. It displays each object
that meets the brightness and type selection filter criteria. A menu bar across
the top offers access to all functions. Around it is a tool bar offering several
handy shortcuts to some of the Control Options and Filters.

The mouse buttons can be used inside the display area for additional
functionality.

Complete details on each control are found in the specific Help choices.

Note that while looping with Pause set to 0 the Sky View is not updated
(although all quantitative information is always updated internally each
step). This is to permit creating plots and using other XEphem features that
use many time increments to run much more quickly if the Sky View is
unmanaged or with Pause set to 0.

@Sky View - mouse
Mouse operations:

All the time:

    Basic position data are displayed in the upper corners. These include:

	Upper left corner:

	    RA, Dec and Hour angle equatorial coordinates;

	    the great-circle distance between the current position and the
	    point at which the left button was last depressed;

	    constellation name;

	Upper right corner:

	    Alt, Az and Zenith distance horizon coordinates;

	    the volume and page number in the Uranometria and Millennium star
	    catalogs.

    To see the Sky View without these potentially intruding data, click the
    left button once, release and do not move; the data will disappear until
    the mouse is moved again. HINT: Pick the mouse up and click. Or, move the
    cursor outside the Sky View map (but see NOTE 2).

    NOTE 1: The coordinates are derived directly from the screen location and
    know nothing of the displayed objects. Thus, they neglect parallax (i.e.,
    assume everything is at infinity).

    NOTE 2: If the Telescope->Marker is active and a telescope control process
    is reporting telescope position information, then when the cursor is
    outside the Sky View the data in the corners refer to the telescope
    marker position, not the cursor position. This information is not
    displayed if any keyboard keys or mouse buttons are pressed.

Left button:

    Pressing and holding the left mouse button draws a Region of Interest
    box. This ROI offers another way to quickly zoom in and out. It is used
    in conjunction with the Tool bar at the top. Also, while roaming with
    the left button down the data in the corners show the changes from the
    starting position.

    When the left button is released, the ROI becomes fixed into position.
    To perform the zoom, press "Zoom In" in the tool bar. The current size,
    position, and ROI are saved and the new area is displayed. The "Zoom
    Back" tool bar button then becomes available to restore the display to its
    previous size and position. The Zoom In and Zoom Back buttons work as a
    pair for arbitrary levels of undo and redo. All zoom information is reset
    whenever the Sky View is resized, flipped or reoriented.

    Zooming is performed in the same way as if the sliding scales had been
    used. Thus, the selected area may be rotated after the zoom due to a
    change in perspective in the map projection. This is a feature.

Middle button:
    
    While the middle button is depressed, the cursor is changed to a fleur
    pattern. Moving the mouse left and right is like moving the scale at
    the bottom; moving it up and down is like moving scale at the right.
    This provides a simple method to pan the display.

    If the "Live dragging" option is turned on, the panning occurs
    immediately. If this is painfully slow on your system then turn this
    off so the screen is only redrawn one time when the button is released.

    This feature is disabled while displaying an image in order to make it
    more difficult to accidently loose the image.

Right button:

    If the right button is depressed then a popup will appear. The popup
    contains information and controls depending on whether the cursor was near
    an object.

    If the cursor is near a visible object, data is shown which are exactly the
    same as that which is available in the Data Table window; see its Help for
    more information. If a trailed object is selected, the data will be
    as it was at the time the position was created.

    If the cursor was not near an object, basic information based on the
    location of the cursor itself is shown.

    In addition, the popup offers several control operations, as follows. Those
    options which pertain to a particular object are only presented if the
    cursor was depressed near an object.

        Center:

	    This will change the display orientation to place the given object
	    or location at the center of the field of view.

        Center + Zoom ->

	    This will change the display orientation to place the given object
	    (or location) at the center of the field of view and, at the same
	    time, zoom in or out the amount selected in the pullright cascade
	    menu.

	Place eyepiece:

	    This will cause an eyepiece symbol to be drawn centered under the
	    mouse location. The eyepiece shape and size is defined in the
	    Eyepiece Setup window, available via Control->Eyepieces.

	Set telescope

	    This will cause the coordinates of the cursor to be sent to a fifo,
	    which is typically connected to a telescope control process. The
	    command is not issued if the coordinates are below the horizon.
	    This button is only present if the "Enable Telescope Control"
	    toggle button is active in the Telescope pulldown menu, described
	    below.

	AAVSO:

	    This will search the AAVSO database for the nearest objects and
	    place them in the list of the AAVSO tool. See the Help for the
	    AAVSO Tool for more information on downloading the light curve.

	Assign ->
	    to ObjX
	    to ObjY
	    to ObjZ

	    This cascade allows you to assign the given object to become ObjX,
	    Y or Z, as desired. This will also cause all other views which are
	    currently making use of this object to be updated and the object
	    will be added to and selected by the Data table. Also, since this
	    makes the object one of the User-Defined objects it will now appear
	    directly in the Sky View->Locate pulldown menu.

	Show in Data Table:

	    This option is only offered when the object chosen under the cursor
	    is a planet, the Sun or the Moon. Selecting this option forces the
	    object to be enabled in the Data Table.

        Persistent Label ->
	    on Left
	    on Right

	    This cascade will toggle whether a label is drawn on the left or
	    right side of the current object. The label will consist of the
	    name and/or the magnitude, depending on which options are
	    selected in the SkyView->Options Labeling section. If neither
	    are selected, the label will consist of the name. To turn off
	    persistency, toggle the direction button back off.

	    Persistent labels are always on, that is, they are not subject to
	    magnitude limits, options, or object type filtering.
	    
	    Note this option is maintained separately for trailed objects and
	    for the untrailed objects; that is, you have independent control
	    over labeling for a trailed object and its currently displayed
	    object since the latter also always appears in the trailed list.
	    This can be somewhat confusing for trails which begin "Now" since,
	    in effect, the first item is drawn twice (once just because it is
	    an object like any other, and again as a member of the set of
	    trail history points).

        Track:

	    This will toggle object tracking for this object. If a trail
	    object is chosen, the tracking will apply to the current position
	    of the object.  See the discussion for the "Tracking" toggle button
	    for more details. 

	Trail:

	    This toggle is only present if the selected object has a trail
	    defined. If it has a trail, the toggle state indicates whether
	    the trail is being displayed. Note that turning off a trail does
	    not actually discard the trail until the next Update occurs from
	    the Main window.

        Create Trail (or Change Trail) ...

	    This pushbutton will bring up a window from which a trail may be
	    defined, computed and displayed. The button is labeled "Change
	    Trail" if the selected object already has a defined trail. Only one
	    trail per object is supported.

@Sky View - control
Control options:

    List...

	This brings up a window that allows saving the objects currently
	displayed in the Sky View to a file. It has its own Help.

    Print...

	This allows printing the current Sky view or saving it to a file. If
	an image is currently being displayed, it will also be part of the
	print image. It has its own Help.

    Filter...

	This allows selecting the types and magnitude ranges of objects to
	display. This window has its own Help.

    Image...

	This brings up a window which allows a FITS file or a remote DSS
	image to be displayed within the Sky View. See the Help in that
	window for complete information.

    Options...

    	This brings up a window with several choices effecting the way the
	scene is drawn. It has its own Help.

    Horizon...

	This activates the Horizon setup window. To display the Horizon
	profile, turn on the toggle under Option. For more information about
	this facility, see the Help from the Horizon window.

    Field Stars...

	This activates the Field Star setup window. To display Field Stars,
	turn on the toggle under Options. For more information about this
	facility, see the Help from the Field Star window itself.

    Eyepieces...

    	This brings up a window which allows you to specify the shape, size
	and style of the next eyepiece to be created. It has its own help.
	Whether eyepieces are shown at all is controlled by the
	Control->Options->Eyepieces option.

    Manual...

	This brings up a simple dialog which allows you to enter an RA and
	Dec position manually and mark it on the Sky View, reorienting if the
	position is not currently in the field of view.

    Tracking:

	Tracking refers to "object tracking" and means that the pointing
	direction of the display will automatically be changed each time an
	Update occurs from the Main window such that the tracked object will
	remain centered on the display. The object to be tracked is selected by
	using the "Track" option in its popup menu, as described elsewhere.

	When this toggle button is sensitive and pushed-in it means that
	tracking is active for one object. The tracked object will be marked
	with an "X" on the display after each Update. If this toggle button is
	selected while it is sensitive, it turns tracking off. This is a
	convenient alternate method to turn off object tracking without having
	to find the exact object being tracked and use its popup Track control.

	When this toggle button is insensitive and popped-out, it means that
	object tracking is not active; it does nothing when selected while
	insensitive.

    Close:

	This causes the Sky view and all supporting windows to go away.

@Sky View -- Eyepieces
This window allows you to specify the shape, size and style of the next
eyepiece marker to be created. These markers are useful to show the view
through your eyepiece, but can also be used to simulate the view of a CCD
camera, or as any number of miscellaneous markers on the map. Symbology on the
map will show through the eyepieces, even when they are specified as
solid.

Note that this window controls the style of the next eyepiece to be created.
To actually create an eyepiece, place the mouse over the Sky view where you
want the center to be located and press the right button. Slide down the
popup menu and release over "Place eyepiece".

Across the top are two sliders which set the width and height of the next
eyepiece. These are shown in units of degrees:minutes. Below them is a toggle
which, when pushed in, will lock the two sliders so they move together. This
is to make it easy to create eyepiece shapes that are perfectly round or
square.

As a special convenience, there is a toggle which will create three
open circles spaced to match the view through the venerable Telrad finder.
The circles are 0.5, 2 and 4 degrees in diameter. As long as this special
toggle is pushed in, all other controls are made insensitive to avoid
interfering with the preset values for the Telrad.

Next below are pairs of toggle buttons to select the Shape and Style of
the next eyepiece. Elliptical and Rectangular refer to circles and
squares. Solid and Outline refer to whether the shape will be filled in
or just drawn as a border.

Next down is a button which will permanently erase all eyepieces. This
button is only active if at least one eyepiece has been created. If you
just want to temporarily turn Eyepieces off and on use the
Control->Options->Eyepieces option.

Across the bottom are buttons to Close the window and get more information.
Closing the window has no effect on existing eyepieces.

@Sky View - ops
This is a description of the controls in the Sky Options window.

Note that some of these options are also available via the tool bars across
the top and down the side of the Sky View. The top tool bar offers shortcuts
to "What" is being displayed such as grid overlay, annotation, galaxies; the
one down the left controls "How" it is displayed, such as brightness,
display mode, flipping. To learn what each icon in the tool bars does, use
Help->Context from the Main window and move the cursor over each icon to
cause it to display its help tip bubble.

Options:

Display mode:

    Alt-Az:
    RA-Dec:

	This radio box selects whether the display coordinate system is
	Altitude-Azimuth or Right Ascension-Declination.

	NOTE: While in Alt/Az mode the display is always topocentric; while in
	RA/Dec mode the display coordinate system depends on the Equatorial
	preference and Epoch settings in the Main window.

    Sphere:
    Cylinder:

	This radio box selects whether the display is projected onto a sphere
	on a cylinder. The advantage of the sphere is that it mimics the real
	sky. The advantage of the cylinder is it shows the entire universe at
	once.


Grid Control

	This group of controls allows you to specify the details of an overlay
	coordinate grid. "Grid" itself toggles the grid on or off.
	
	If "Auto" is on, then the size of the grid steps will be determined
	automatically and shown in the text fields beneath; if it is off, then
	step sizes are determined from the values in the text fields. Typing
	into either field then pressing Enter will also turn off Auto and
	immediately display the grid with the new step size.

	"Alt-Az" and "RA-Dec" selects in which coordinate system the grid
	will be drawn.
	
	"Label" selects whether the grid will be labeled.

View Options

    Just dots:

	This toggle effects how stars are shown.

	When the toggle is pushed in, all stars are displayed simply as dots
	of various sizes.

	When the toggle is released, each type of star is displayed with a
	unique schematic symbol. These symbols may be reviewed from the Filter
	window.

	In either case, the diameter of the symbol shown is the larger of the
	object's actual size at the current window scale (if a size is
	specified in the database entry for the object) or a size that is
	proportional to the difference between the object's magnitude and the
	current faintest magnitude setting.
	
	This means that, at suitably small fields of view, the Sun and Moon are
	shown to scale.  This is ideal for watching solar eclipses or
	occultations. For example, watch the solar eclipse over Hawaii by
	setting the date to July 11, 1991, time to 17:00 UTC, location to
	Latitude 19:50 Longitude 155:28, and starting a loop with a Step of
	1:00 and Pause 1. Be sure to use the Alt-Az display mode to get
	topocentric positions or set the Main Preferences for Equatorial to
	Topocentric. It is also very handy to set to Track either the Sun or
	the Moon (whichever you wish to be centered during the movie).

    Flip Left/Right:
    Flip Top/Bottom:

	These toggle whether the display is shown with a flip in the left/right
	or the top/bottom directions, respectively.

    Equatorial plane:

	This toggle selects whether a red 3:6 dashed line is shown along the
	Earth's equator projected onto the celestial sphere.

    Ecliptic plane:

	This toggle selects whether a red 2:2 dotted line is shown along the
	ecliptic. The ecliptic is the plane of the Earth's orbit or, as seen
	from Earth, the path of the Sun and the approximate path of the
	planets across the sky. The anti-solar point is marked with a small
	open circle. The edges of umbra/penumbra of Earth are marked with
	open circles. If Preferences->Equatorial is set to Topocentric, the
	umbra/penumbra are projected at the current distance of the Moon
	and corrected for parallax; if set to Geocentric they are projected
	at infinity.

    Galactic plane:

	This toggle selects whether a red 1:4 dotted line is shown along the
	galactic equator and small +'s are placed at the galactic poles.

    Eyepieces:

	This toggle selects whether eyepieces are drawn on the Sky view, if 
	and when any are placed. Eyepieces are placed on the Sky view by using
	the "Place eyepiece" control in the popup menu activated by the right
	mouse button. The shape and style of eyepieces is defined in the
	Control->Eyepieces window. Eyepieces are only drawn if they fit
	entirely within the Sky View. This selection is automatically
	activated when an eyepiece is placed.

    Magnitude key:

    	This toggles whether to display a chart in the lower left corner
	showing the correspondence between dot size and star magnitude.
	The scale is automatically turned off each time an image is first
	displayed.

    Auto magnitude:

	When this toggle is active, the faintest magnitudes and dot step
	size will automatically be set to something reasonable based on
	the field of view. This option is automatically turned on whenever
	the FOV changes for any reason, unless it was turned off manually.

    Field Stars:

	This toggles whether field stars are automatically loaded and displayed
	if the position, field of view, limiting magnitude or time changes
	significantly.

	This selection turns itself off if any difficulties ever arise in
	retrieving field stars.

	See Control -> Field Stars -> Help for more info about field stars.

    Live dragging:

	This toggle button selects whether the graphics are redrawn in
	real time as the various scale controls are being slid, or whether the
	graphics are not redrawn until the mouse is released. The decision
	depends on the speed of the computer, display and data bandwidth.
	If the system is fast enough, turning this on can produce dramatic
	results.

    Horizon map:

	This controls whether to overlay the local horizon profile on the
	Sky View and, when in Cylindrical + Alt-Az mode, whether objects
	below the horizon are drawn. The profile is drawn at azimuth steps
	of 1 degree.

	See Options -> Horizon -> Help for more information.

Constellation

    Boundaries:

	This toggle controls whether constellation boundaries are shown.

    Figures:

	This toggle controls whether constellation figures are shown.

    Full Names:

	This toggle controls whether full constellation names are shown. The
	names will be centered within the extent of the constellation figure.
	This control and Abbreviations can not be both on at once.

    Abbreviations:

	This toggle controls whether abbreviated constellation names are
	shown. The names will be centered within the extent of the
	constellation figure. This control and Full Names can not be both
	on at once.


Labeling

	This portion controls labeling options. The three sliders select how
	many of the brightest objects to label in each of three categories.
	The label itself may consist of the Name or Magnitude or both,
	depending on which of the two buttons are depressed adjacent to
	each scale. If Names and Magnitudes are both enabled then the
	magnitudes are shown to the right of the name surrounded by
	parentheses. Magnitudes are shown to the nearest 1/10 with the
	decimal point removed.
	
	Other labeling facts:

	    Trailed entries do not contribute towards the brightest count.

	    The Persistent Label option for individual objects is never
	    disabled. 

	    Greek characters are used in Bayer names when YBS.edb is loaded.

@Sky View - filter
Filter controls:

	This window lists all classes of objects supported by XEphem. Using the
	Filter window, one may select which classes of objects are displayed on
	the Sky view window.

	For reference, the Filter window also contains the schematic symbol for
	each type of object, and its code when used in a database file. The
	symbol displayed for each class of object is that which will be used to
	represent the object in the Sky view, unless "Just dots" is selected.

	Three scales near the bottom of the Filter window control the faintest
	magnitude limit to be displayed for Stars, Solar system and Deep sky
	objects. Note that trails and persistent labels are not subject to
	the faint magnitude limits.
	
	The fourth scale in the lower left selects the number of magnitudes
	binned in each dot size.

	Several push buttons appear across the bottom of the Filter window
	which have the obvious effects: Selecting "Apply" updates the sky
	display according to the desired selection. Selecting "Ok" does the
	same thing but also closes the Filter window. "All" turns on all
	types. "Toggle" toggles each filter type.

@Sky View - locate
Locate controls:

    This selection will pop up a list of the basic objects and the currently
    defined user objects, if any. Selecting an entry will place a cross-hair
    over the object. If the object is not within the field of view the object
    will first be centered. If Alt-Az mode is currently active and the object
    is below the horizontal the view will not be changed and a window will
    appear with a message suggesting the mode first be changed to RA-Dec.

    To aim the Sky View at any other object in the XEphem database, please use
    the Search window accessible from the Main window.

@Sky View - telescope
Telescope controls:

    Enable Telescope Marker:

	This toggle button lets XEphem listen for and mark sky coordinates
	from a fifo. This facility is intended to mark the current location
	of a telescope. Each time a set of coordinates is received a circle-x
	will be drawn on the Sky View at those coordinates, based on the
	current XEphem time. The Sky View will be recentered if necessary to
	keep the marker visible. If the cursor is outside the Sky View, the 
	coordinates of the marker are shown in the upper corners.

	Note the current XEphem time is /not/ updated; it is expected that the
	Main looping facility will be used for that. Do not loop too quickly
	or XEphem will get very far behind and you may lose control until
	the fifo writer is stopped.

	The fifo is opened and closed each time this toggle is changed. The
	name of the fifo is "fifos/xephem_in_fifo" off the shared directory.
	
	The format of the command expected is as follows:

          RA:XX.XXXXXX Dec:XX.XXXXXX Epoch:XXXXX.XXX

	The RA/Dec values must be astrometric, precessed to the indicated
	epoch, geocentric or topocenter to match the current Equatorial
	Preference, and be specified in radians. Epoch is in decimal years.
	Southern declination should be negative.

    Enable Telescope Control:

	If this toggle button is pushed in then XEphem can send the current
	mouse coordinates to a remote process via a fifo. A pushbutton will
	be added to the popup menu (activated when the right button is
	depressed) called "Set telescope". The fifo is opened and closed each
	time this selection is made. The intended purpose of this is to connect
	to a telescope control process.

	Each (unique) target is added to the pulldown. Selecting it will send
	the telescope to the same place again. The list is deleted whenever
	the Enable control is turned Off.

	The name of the fifo is "fifos/xephem_loc_fifo" off the shared
	directory.

	The format of the record sent to the fifo is the same as that used
	in the .edb files. In addition, the planets are supported with a
	format consisting of the name of the planet with a type of P, as

	  Mars,P

@Sky View - history
This is the Sky View History control window. Most of the Sky View settings
may be saved and restored as entries in the History list. This is handy for
saving your favorite views for easy display.

The top pushbutton in the History pulldown menu brings up this window to Edit
the list. Additional pushbuttons in the pulldown menu allow any one history
entry to be applied immediately.

The control window shows the current set of History entries, one per line.
Each line has the following format:

    Apply will engage the given entry, in the same way as choosing it from
    the pulldown menu.

    Up and Down allow the entries to be rearranged as desired. Remember
    to Save (see below) to keep the changes permanently for next time.

    Delete will remove the given entry.

    Replace acts as a combination Delete and Add (see below).

    The next section shows the basic display modes, the center coordinates and
    field of view.

    The field on the right allows you to enter a short descriptive label for
    the entry.

Buttons across the bottom allow for additional control of the History list:

    Add will capture the current Sky View settings and create a new 
    History entry. A default label will be created but you should probably
    change it to something more descriptive if you plan to Save the list.

    Save will write all of the current History entries to a file. The file
    name is "xephem_skyhist" and will be created in the per-user directory.

    Load will read an existing file of History entries that has been
    previously Saved and make them the current set. First the per-user
    directory is searched then "auxil/" off the shared directory.

    Close closes the History window.

    Help displays this information.

@Sky View - scales
Scale controls:

    FOV:

	The vertical scale on the left side sets the vertical field of
	view of the display. The horizontal field of view is determined by
	the width of the window at the same scale. The FOV can be varied in 5
	minute increments from 0:05 through 180 degrees. The buttons below
	present a quick way to set the scale to exactly 90 degrees and to
	resize the window (by changing the width) to 1:1 and 2:1 W:H aspect
	ratios.

    Alt / Dec:

	The vertical scale on the right side sets either the center altitude
	or declination, depending on the display mode. The value can be
	varied from -90 to +90 in increments of 5 minutes. The buttons below
	presents a quick way to center the scale at exactly 45, 0 or -45
	degrees.

    Az / RA:

	The horizontal scale across the bottom sets either the center azimuth
	or RA, depending on the display mode. In Alt-Az mode this sets azimuth
	and can be varied from 0 to 359:55 degrees in steps of 5 minutes.
	In RA-Dec mode this sets Right Ascension and can be varied from 0 to
	23:59:40 hours, in steps of 20 seconds.

@Sky View - misc

    Date/Time Stamp:

	The date and time for which the display is valid is always shown
	beneath the sky view.

@Sky View - trails
Trails:

The location of any object on the Sky view may be computed at regular intervals
and displayed by setting up a sky trail. Use the Sky View Trails Setup window
to select the interval, number of steps, formatting details and which steps you
would like annotated. The trail setup window is accessed from the popup which
appears when the third mouse button is activated when the cursor is near an
object. Any number of objects may have trails.

The trail is created by computing the location of the object at several
intervals.  Each new location will be drawn with a small mark and connected
with a line to its previous location. The trails remain correct if the display
coordinate system is changed. Trails may be turned on or off without loss of
trail information.  Trail information is discarded if a trail is turned off
when a new Main window Update is performed.  If any point on a trail is selected
using the third mouse button the information displayed is as per the object at
that time.  The times displayed next to trailed objects are always in UTC.
Trail information is not subject to the constraints in the Control->Filter
window, i.e., trailed objects are always shown.

Note that in Alt-Az mode, each trailed location is positioned on the display
according to the sky at the current moment. But because of diurnal motion
these trails are not useful for comparison with the background of fixed
stars. Use the RA-Dec mode for that.  This is so important (and easily
overlooked) that you will see a reminder notice to this effect the first (and
only) time you create and display a trail in Alt-Az mode.

Finally, be sure to recompute any trails if you change any of the preferences
or circumstances in the Main window.

@Sky View - list
This window lists, sorts and allows saving the objects currently displayed in
the Sky View to a file.

Basing the list on the Sky View means the selection criteria uses the power of
the Options and Filters controls as well as the region of the sky as defined
by the center and field of view. If you wish to include all objects without
regard to position, use the Cylindrical project mode, set RA-Dec, FOV 180,
Dec 0 and resize the Sky View window to show the entire universe.

At the top, the format of the file created may be specified in either of two
formats.

    The .edb format saves the objects in the XEphem catalog format.  This is
    handy for using the XEphem filtering options to create custom catalogs.

    The text format is a columnar listing. The columns that are printed are
    the same as those currently selected in the Data Table, printed to the
    precision specified in the Preferences. A convenient button is provided
    to bring up the Date Table setup window. Note that a column need not be
    printed to be used for sorting, although it would seem unusual to do so.

The center section lists several fields that may used for sorting the list.
Pick each field in the order you wish to sort the list. If you wish to make a
change to the order, you may Undo one at a time back to the beginning or
Clear the entire sequence and begin again.

The bottom section is a text field which (will) show the results of the
sort. This text field is fully editable, so you may delete specific objects,
add comments and so on as desired. N.B. If you have chosen the .edb format,
no checks are made that your edits have made the format illegal.

Pressing the right mouse button over the text field will bring up a popup menu,
if a valid object name is found at the beginning of the line under the cursor.
This popup has buttons to Delete the object on the current line from the list
and Mark the object on the Sky View.

Across the bottom are several controls:

    Save

	This writes the text field exactly as it now appears to the file named
	at the right of the format checked at the top.
	
	N.B. No check is made that the format and the extension agree.

    Sort

	This rebuilds the list according to the current settings. Use this
	after changing something in the Sky View, or after changing the
	format or sort settings here.

    Close

	Closes this window.

    Help

	Shows this help.
@Sky FITS
This window allows you to read a local FITS file, or access the Digital Sky
Survey, DSS, via the Internet, and display the image in the Sky View where
it can be overlayed with all the features available therein. The image will
remain until the Sky View is repositioned or resized. While an image is in
the Sky View, all coordinates are based on the information in the FITS header.

The Internet connection may be made directly, or via a Proxy or SOCKS server.
These may be configured in the File->Network setup window.

In order to be displayed, the FITS header must either contain the standard
DSS headers or the World Coordinate System fields CTYPE, CROTA, CRPIX, CDELT
and CRVAL, 1 and 2. If the file contains only the former fields, XEphem will
compute and add the corresponding WCS fields automatically. Only 16 bit integer
files (BITPIX 16) are supported.

The DSS is maintained by the Space Telescope Science Institute, STScI, in the
United States or the European Southern Observatory, ESO, research facility in
Germany. The image data from either site is identical, so the decision is
only a matter of your local availability and access speeds.

To access the DSS:

    1) Make sure your live Internet network connection is working.
    2) Select the desired institution;
    3) Select the desired survey (Survey 2 is higher res but not yet completed);
    4) Choose whether to use compression; always turn On if you have gunzip.
    5) Press Get at the top to start retrieving the image. The size of the
       image is currently limited to 20 arc minutes. During the network access,
       the Main->File->Progress meter is active to indicate relative progress,
       and a Stop window is available to abort the transfer. The header of the
       http server response message is in the Main->File->Messages window;
       check here if an error occurs.
    6) If the image is successfully retrieved, it will appear in the Sky View.

To read a local FITS file:

    1) Use the File Selection Box at the bottom to choose the desired file.
    2) If the file is successfully read, the image will appear in the Sky View.

Image controls:

    1) The FITS header is displayed in the scrolling text area at the top.

    2) If the header contains any of the fields EPOCH, JD or DATE-OBS 
       then the date of the observation is displayed above the header. A
       button will also come alive which allows setting the main XEphem time
       and date to this value. This is handy when checking for asteroids,
       comets or using the proper motion catalogs with an image.

    3) Below the header are two plots on one graph. The horizontal axis for
       each plot is the same: the full range of pixel values within
       the image, with lowest on the left. The yellow line is a histogram of
       the number of pixels with each value. The orange line indicates the
       brightness at which each pixel value will be displayed on the screen.

       Pixel values may be mapped to a set of gray colors spanning black to
       white using either of two methods. One is Histogram Equalization,
       which arranges for an equal number of pixels at each level of display
       brightness within the selected range. The other is a power function
       similar to the Gamma factor for CRT compensation. Values of gamma less
       than one emphasize dark pixels, gamma values greater than one
       emphasize only bright pixels. You may directly control the black and
       white limits of either mapping function by dragging the red arrows at
       the top of the diagram, or by using the convenience buttons for making
       predefined changes.

    4) The current image may be saved to disk as a FITS file as named with
       the text field near the center. This is particularly handy if the image
       was retrieved over the net. If "Auto name" enabled, a filename is
       created automatically derived from the RA and Dec of the center of the
       image. In an attempt to preserve any existing directory and filename
       extensions, the filename is constructed between the right-most '/' and
       the right-most '.' characters, if any.  

Once an image is displayed, all graphical features of the Sky View are
available, including drawing and labeling all objects in the XEphem database
and printing.

For example, to label the field stars over an image, follow these steps (if
not already):

    1) Select the source of field stars, using Control->Field Stars.
    2) Set the faintest magnitude to about 16, using Control->Filter.
    3) Enable Field Stars using Control->Options->Field Stars.
    4) Enable Field Star labels using Control->Options->Labels->Stars.

Note that what is meant by "up" and "left" will now depend on the FITS image
headers and may be different from what was in effect before the image was
loaded.

@Solsys
+Solsys - intro
+Solsys - misc
+Solsys - mouse
+Solsys - control
+Solsys - view
+Solsys - objects
@Solsys - intro
This is a graphical representation of the solar system. The Sun is always at
the center of the screen, marked with a small circle.

@Solsys - misc
The three scales at the edges control the position of the observer. The
vertical scale on the left controls the distance from the Sun -- you are
closer as the scale is slid further up. The horizontal scale under the view
controls the heliocentric longitude -- think of it as a rotation about the
central axis. The value of the scale is the heliocentric longitude towards
you. The vertical scale on the right controls the heliocentric latitude --
your angle above the ecliptic plane.

Changes to the scales take effect as you drag, unless the View->All Objects
option is on in which case the change does not take effect until you release
the scale.

@Solsys - mouse
Any object may be identified by pointing near it and clicking the right
mouse button. This will bring down a temporary popup menu with additional
information until the button is released. RA and Dec are displayed as of the
time the dot was computed. The RA, Dec and Mag given for the Earth is that of
the Sun.

Several controls may also be present on the popup menu, as follows.

    Persistent Label:
	
	This toggles whether the label for the object is displayed regardless
	of whether the View->Labels option is activated.

    Assign ->
	To ObjX
	To ObjY
	To ObjZ

	This cascade allows you to assign the given object to become ObjX,
	Y or Z, as desired. This will also cause all other views which are
	currently making use of this object to be updated and the object
	will be added to and selected by the Data table.

	Since this makes the object one of the User-Defined objects it will now
	appear directly in the Solar System->Objects pulldown menu.

    Show in Data Table:

	This option is only offered when the object chosen under the cursor
	is a planet, the Sun or the Earth. Selecting this option forces the
	object to be enabled in the Data Table. Both the Sun and the Earth
	actually enable the Sun in the Data Table.

@Solsys - control
Control options:

    Print...

	This selection allows printing the current Solar System view or
	saving it to a file.

    Create Trails...

        This button will bring up a window to set up making a trail for each
	planet and user-defined object as they travel from their current
	positions. Each trail time is drawn connected together with a solid
	line with each point indicated with a small dot. The time stamps shown
	with the trails, if any, are always in UTC. For the trail to be
	visible, the Trails option must be activated.

	Only one set of trails is supported at a time. Creating new trails will
	delete the old ones. The trails will also be discarded if a user
	defined object is changed or an Update occurs from the Main window.

	Only the basic planets and user-defined objects, if defined, are
	trailed. The other solar system objects, if any, are always shown in
	their current positions.
	
	See the Help from the trail setup window itself for more details on how
	it operates.

    Movie Demo:

	This push button will set the Main window Step to 5 days and start
	looping with a very large number of steps. Press the button again or
	use Stop control in the Main window to stop the movie.

    Live Dragging:

	This toggle button selects whether the graphics are redrawn in
	real time as the various scale controls are being slid, or whether the
	graphics are not redrawn until the mouse is released. The decision
	depends on the speed of the computer, display and data bandwidth.
	If the system is fast enough, turning this on can produce dramatic
	depth queues for complex solar system views; also try it in Stereo.

    Stereo:

	This toggle button is used to bring up another image of the solar
	system from a slightly displaced vantage point. Adjusting your gaze to
	fuse the two images together will reveal a 3D image. This effect is
	most pronounced if fairly lengthy trails are created and legs are
	enabled. This effect was designed primarily to help visualize the
	orbits of comets.

	At the bottom of the stereo display is a scale to control the amount of
	parallax to introduce. The parallax is only introduced in the plane of
	the ecliptic.  This works well for low latitudes but has the odd effect
	of just moving everything as a whole when viewing from near the poles.
	If you prefer focusing your eyes in front of the screen, move the
	parallax control somewhat to the left; if you prefer to relax your eyes
	and focus at infinity then move the parallax control to the right.

    Close:

	This push button will close both the main Solar system view and the
	Stereo view. If the Solar System view is closed while the Stereo window
	is on, it will reappear when the Solar System window is reactivated.

@Solsys - view
View options:


    Trails:

	This toggles whether trails, if currently defined, are displayed for
	the basic planet objects and the three user-defined objects (if any).
	The trails may be turned on and off as desired without loss but the
	trails are permanently discarded at the next Update from the Main
	window.

    Ecliptic:

	This toggle button controls the display of a set of circles in the
	ecliptic plane, spaced at regular intervals. The interval between each
	circle is displayed at the upper left of the view.

    Labels:

	This option causes each object's name to appear.

    Basic Legs:

	This toggle button controls whether a line is drawn from each
	planet and any ObjXYZ user objects to the ecliptic. This aids in
	visualizing the 3D location of the objects.

    DB Legs:

	This toggle button controls whether a line is drawn from each
	Database object (other than planets and user ObjXYZ objects) to the
	ecliptic. This aids in visualizing the 3D location of the objects.

@Solsys - objects
Objects:

    The planets and the user-defined objects ObjX, Y and Z, if they are solar
    system objects, may be individually turned on and off, without loss of any
    trail data associated with them, by using the toggle buttons in this
    "Objects" pulldown menu.

    All Basic:

	This pushbutton is a shortcut to turn on all the basic planets and
	user defined objects which are in the solar system.

    Just S+E+ObjXYZ:
	
	This pushbutton is a shortcut to turn on only the Sun, Earth and
	any user-defined objects which are solar system objects. It does not
	effect whether the other database objects at large are displayed.

	For that, use the next control ...

    All DB too:

	This toggles whether /all/ solar system objects in the data base are
	also displayed. This is great when the asteroids database has been
	loaded.

	In expectation of increased drawing time with all these objects, when
	this option is on the scales switch so they only cause an update when
	they are released at their new net position.

	Note: these objects are never trailed. If you want to include one of
	these objects in a trail, first assign it to ObjX, Y or Z.

    Note: Trail data is discarded at the time of the next Update from the Main
    window, regardless of whether the object is displayed at that time or not.

@DataBase
+Database - intro
+Database - control
+Database - delete
+Database - files
+Database - notes

@Database - intro
This window allows you to load, delete and inspect the collection of objects
that are currently in memory. These objects form what is referred to as the
XEphem database.

The top section of the window displays a count of each major type of object
and the total number in the database. The counts do not include the planets,
Sun, Moon or the user-defined objects ObjX, Y and Z.

The center section lists the catalogs which are currently loaded and the number
of objects they contributed. The objects loaded from a catalog may be deleted
using the button to the left of the count. This list may be saved at any time
so this set of catalogs is automated loaded when XEphem starts. To do so, go
to Preferences->Save and Save the XEphem.DBInitialFiles resource under the
Data Base category.

The lower section allows you to browse the directory structure on your system
for database files in XEphem format and load them into memory. The Filter
field sets the directory and file name pattern to qualify being included in
the list of Files. Any directory may be searched but handy buttons at the
bottom right allow setting the directory to the values of the Shared and
Private directories. The Filter button in the lower center forces the directory
given in the Filter field to be rescanned for all files which match the
filter pattern therein. Double-click on a directory to show the files which
match the pattern.

A database file is loaded into memory by selecting the file name in the list
at right then pressing Load at the bottom of the window, or by double-clicking
its name in the list. If the file is already loaded, it will first be deleted.
If the file contains exactly one entry, the object may also be automatically
assigned to a user-defined object; see Help->on Control for more details.

Or rather than browsing, any file name may be simply explicitly typed in the
Selection field and loaded by typing Enter or pressing Load.

The sash in the center of the window controls the proportion of space allocated
to the Catalogs and Browse sections as desired.

XEphem may also load objects from another process via a fifo. Please refer
to the separate description of this facility in Help->on Control.

@Database - control
Control:

    Delete all

	Deletes all file and their objects from memory. The files on disk are
	not effected.

    Open DB Fifo

	Listen for database objects arriving via a fifo from another process.
	XEphem attempts to reopen the fifo each time the button is pressed.

	The file name of this fifo is "fifos/xephem_db_fifo" off
	the shared directory.

	All relevant displays are automatically updated when data arrives via
	this fifo. The format of the fifo data is exactly the same as for any
	XEphem database file. Due to the way the fifo data is read and
	processed, it is important that each line be terminated with a newline;
	incomplete last lines can result in loss of information.

    No Dups

	If this toggle is on then when a new database file is loaded, objects
	from other catalogs whose name already exists in memory will be
	silently skipped. This option does /not/ check for duplicates among
	the user defined objects, ObjX/Y/Z, nor entries within the new file
	itself.

    Load Obj when 1

	If this toggle is on then when a new database file is loaded and it
	defines exactly one object, it will also be assigned to one of the
	user defined objects, ObjX, Y or Z. The one affected is the first
	which is either undefined, whose name matches the new object, or
	ObjZ. This feature is also available for files loaded when XEphem
	first starts.

    Close

	Closes the Data Base window.

@Database - files
Follows is the description of the format of an XEphem database file. The
file name extension is .edb.

General Information:

    Each object occupies one line in the file. Lines are separated into Fields
    using commas (,). Some fields are further subdivided into Subfields with
    vertical bars (|). Lines beginning with anything other than a-z, A-Z or 0-9
    are ignored and may be used for comments. The order of objects in a file
    does not matter.

    Where they appear, all date fields may be in either of two forms:

      1) month/day/year, where day may contain a fractional portion.
	    examples: 1/1/1993 and 1/1.234/1993

	NOTE: the format of dates in database files is always M/D/Y,
	regardless of the current XEphem Date format Preference setting.

      2) year as a real-number, such as 1993.123.

Field Definitions:

The first two fields are always Name and Type. Remaining fields depend on Type.

The Name field is the object's name. Any number of characters may be
present but only the first 13 are retained as significant.

The Type field consists of a single letter designating the form of the
object's motion and must be one from the following set:

  f: fixed (no proper motion)
  e: heliocentric elliptical orbit
  h: heliocentric hyperbolic orbit
  p: heliocentric parabolic orbit
  E: geocentric elliptical orbit, i.e., Earth satellite

If Type is "f" (fixed), an object class code may follow in the next subfield:

      A: Cluster of galaxies
      B: Star, binary
      C: Cluster, globular
      D: Star, double
      F: Nebula, diffuse
      G: Galaxy, spiral
      H: Galaxy, spherical
      J: Radio
      K: Nebula, dark
      L: Pulsar
      M: Star, multiple
      N: Nebula, bright
      O: Cluster, open
      P: Nebula, planetary
      Q: Quasar
      R: Supernova remnant
      S: Star
      T: Stellar object
      U: Cluster, with nebulosity
      V: Star, variable

      if class is one of T, B, D, S or V, the spectral class and possibly the
      numerical subclass designation may follow as 1 or 2 characters in the next
      subfield.

      if class is G or H, the size field (described next) may include minor axis
      and position angle as subfields.

  The remaining fields for Type f are as follows:

       RA, hours
       Declination, degrees
       magnitude
       reference epoch, optional, assumed to be 2000 if absent
       size = angular size, arc seconds, optional.
       
	   For elliptical objects such as galaxies, this field may be 
	   divided into 3 subfields if desired: the size of the major axis,
	   the size of the minor axis (both in arc seconds), and the position
	   angle, in degrees E of N.

	   These 3 subfields can also apply to double stars, where the first
	   subfield is the separation in arc seconds, the second subfield
	   is set to 0, and the third field is the position angle.

If the Type is "e" (elliptical heliocentric, eccentricity < 1) the remaining
fields are defined as follows:

       i = inclination, degrees
       O = longitude of ascending node, degrees
       o = argument of perihelion, degrees
       a = mean distance (aka semi-major axis), AU
       n = mean daily motion, degrees per day (computed from a**3/2 if omitted)
       e = eccentricity,
       M = mean anomaly (i.e., degrees from perihelion),
       E = epoch date (i.e., time of M),
       D = the equinox year (i.e., time of i/O/o).
       g,k or H,G = two fields which define the magnitude model; select which
	   by preceding the first field with a "g" or an "H" (2 parameters)

If the Type is "h" (hyperbolic heliocentric, eccentricity > 1) the remaining
fields are defined as follows:

       T = epoch of perihelion
       i = inclination, degrees
       O = longitude of ascending node, degrees
       o = argument of perihelion, degrees
       e = eccentricity,
       q = perihelion distance, AU
       D = the equinox year (i.e., time of i/O/o).
       g,k = two fields which specify the magnitude model
       s = angular size at 1 AU, arc seconds, optional

If the Type is "p" (parabolic heliocentric, eccentricity == 1) the remaining
fields are defined as follows:

       T = epoch of perihelion
       i = inclination, degrees
       o = argument of perihelion, degrees
       q = perihelion distance, AU
       O = longitude of ascending node, degrees
       D = the equinox year (i.e., time of i/O/o).
       g,k = magnitude two fields which specify the model
       s = angular size at 1 AU, arc seconds, optional

If the Type is "E" (Earth satellite) the remaining fields are defined as
follows:

      Epoch
      inclination, degrees
      RA of ascending node, degrees
      eccentricity, must be < 1
      argument of perigee, degrees
      mean anomaly, degrees
      mean motion, revolutions/day
      orbit decay rate, revolutions/day^2
      integral reference orbit number at Epoch
      drag coefficient, 1/(earth radii); optional

      The venerable Two-Line-Element (TLE) format is also automatically
      detected and supported. For a complete discussion of TLE format see
      http://www.celestrak.com.

@Database - notes
XEphem does not use the facility controlled by this window for so-called
Field Star catalogs. See the Help for Data->Field Stars for more
information on managing these special catalogs.

XEphem ships with a few perl scripts which might be helpful for converting
databases in other formats into XEphem format. These scripts are in the
tools/ directory of the XEphem source distribution tree.  
@Object
This window allows you to select, inspect and modify any object currently
in memory. It also allows you to control the user defined objects, ObjX,
ObjY and ObjZ.  

XEphem supports three user-defined objects, denoted ObjX, Y and Z. These may
be fixed objects; objects in elliptical, hyperbolic or parabolic heliocentric
orbits; or objects in geocentric elliptical orbits. The ObjX/Y window allows
you to define these objects.

XEphem maintains a working copy of these objects for use with the ObjX/Y/Z
window that is separate from the real ObjX and ObjY and ObjZ. The ObjX/Y/Z
window always works on these working copies. The working copies and the real
ObjX/Y/Z only interact when using the Ok, Apply and Reset control, as
described shortly.

This window is always displaying information from one of these working copies
as indicated by the small radio box in the top center of the window. The radio
box may also be used to change whether ObjX, Y or Z is being displayed and
manipulated. We will refer to the one selected as the "current working object."

The radio box in the upper left displays the basic type of the current
working object. This can be changed by selecting another of the collection
of toggle buttons.

In the left and center of the window is an area that lists each field for the
current working object and its present value. The list is adjusted to
correspond to the fields that are associated with the type of the current
working object. These fields may be changed by selecting the button that
contains their value. This will bring up a small text entry window. A new
entry may be typed into the window box and applied by typing Enter or
selecting the "Ok" button. The value may be left unchanged by selecting
"Cancel".

Along the right edge of the window is a list of each object currently loaded
into the XEphem database. (See the Help for the "Database Load and Delete"
window for more information on manipulating this data base.) If there are
more than 20 items then a scroll bar may be used to browse through the list.
The entries are sorted in numeric and alphabetic order, ignoring case, for easy
browsing.  If one of these objects is picked, then it is copied to the
current working object.  You may then edit the values for this working object,
if desired, without effecting the original.

Below the list of names is a text field with which you may select an object by
name. Enter a string and type Enter or press the Search: pushbutton. All
objects in memory will be searched for one with a name that contains the
string. Whitespace and case are ignored. To anchor the string to be at the
beginning of the object's name precede the string with a caret (^). If a match
is found, the list is scrolled so the object is at the top and the object is
copied to the current working object. To select again with the same string,
type Enter or press the Search: pushbutton again. XEphem beeps if no matches
are found.

When the current working object is as you want it, select "Apply" to copy it
into the real ObjX (or ObjY or Z) used throughout the other functions of
XEphem. "Ok" will do the same thing and also close the window.

Other controls include:

    Reset
    
	load the current working object with a copy of the real ObjX (or ObjY
	or Z).

    Sky Point
    
	mark the current working object on the Sky View with a cross-hair,
	re-aiming if it is not currently in the field. The object is marked
	even if the object does not match the Sky View filter or is outside
	the magnitude range. The only time the object will /not/ be marked is
	if the display mode is set to Alt-Az mode and the current working
	object is below the horizon.

    Sky Mark

	will draw a cross-hair on the Sky View window at the location of the
	current working object but only if it is already within the Sky View
	field of view. The Sky View window is never re-aimed with this command.

    Set Tel
    
	will cause the coordinates of the current object to be sent to the
	xephem_loc_fifo fifo, which is typically connected to a telescope
	control process. The command is not issued if the object is currently
	below the horizon. See the discussion at Sky_View->Help->on_Telescope
	for more information.

Follows is a description of each field for the type of the current working
object. To get a description of the fields for other types of objects,
change the type of the current working object and reselect Help.

@Fixed Object
+Object
Fixed objects are characterized by five parameters:

    RA,
    Dec,
    magnitude,
    the reference epoch for the coordinates and
    angular size in arc seconds, optional

Note:

In order to conserve memory usage, XEphem stores the astrometric RA and Dec for
a fixed object only once with each object. These values are always precessed
*in place* to the current display epoch. Thus, you will find that the RA and
Dec displayed for a given object may change if the epoch is changed in the
Main window and the object information is redisplayed here.
@Elliptical Object
+Object
Elliptical objects are characterized by 12 parameters: the parameters that
define a heliocentric elliptic orbit and the coefficients for either of two
magnitude models.  These elements are the same ones often listed in the
Astronomical Almanac.  The elements are, in order:

    i = inclination, degrees
    O = longitude of ascending node, degrees
    o = argument of perihelion, degrees
    a = mean distance (aka semi-major axis), AU
    n = mean daily motion, degrees per day
    e = eccentricity
    M = mean anomaly (i.e., degrees from perihelion)
    E = epoch date (i.e., time of M)
    D = the equinox year (i.e., time of i/O/o)
    g,k or H,G  = two fields to specify either of two magnitude models; see
	below
    s = angular size at 1 AU, arc seconds, optional


You might have other parameters available that can be converted into these. 
The following relationships might be useful:

    P = sqrt(a*a*a)
    p = O + o
    n = 0.9856076686/P
    T = E - M/n
    q = a*(1-e)
    AU = 149,597,870 km = 92,955,621 U.S. statute miles
 where
    P = the orbital period, years;
    p = longitude of perihelion, degrees
    T = epoch of perihelion (add multiples of P for desired range)
    q = perihelion distance, AU

Note that if you know T you can then set E = T and M = 0.

XEphem supports two different magnitude models for elliptical objects. One,
denoted here as g,k, is generally used for comets in elliptical objects. The
other, denoted H/G, is generally used for asteroids in the Astronomical
Almanac.

+OBJXY_gkMAGNITUDE
When using this model for elliptical objects, the first of the two magnitude
fields must be preceded by a letter "g". This applies in both the .edb
database file and the corresponding elliptical object definition prompt;
otherwise the default magnitude model for elliptical objects is the H/G model.

+OBJXY_HGMAGNITUDE

The H/G model is the default magnitude model for elliptical objects but it can
also be explicitly indicated when the first of the two magnitude fields is
preceded by a letter "H". This works in both the .edb database file and
the corresponding elliptical object definition prompt.
@Hyperbolic Object
+Object
Hyperbolic objects are characterized by 10 parameters: the parameters that
define a heliocentric hyperbolic orbit and the magnitude model coefficients. 
These orbital parameters are, in order:

    T = epoch of perihelion
    i = inclination, degrees
    O = longitude of ascending node, degrees
    o = argument of perihelion, degrees
    e = eccentricity,
    q = perihelion distance, AU
    D = the equinox year (i.e., time of i/O/o).
    g,k = two fields for the magnitude model
    s = angular size at 1 AU, arc seconds, optional

As with elliptical elements, other parameters might be available.  The
relationships are generally the same, except for:

    q = a*(e-1)

+OBJXY_gkMAGNITUDE
@Parabolic Object
+Object
Parabolic objects are characterized by 9 parameters: the parameters that
define a heliocentric parabolic orbit and the magnitude model coefficients.
These orbital parameters are, in order:

    T = epoch of perihelion
    i = inclination, degrees
    o = argument of perihelion, degrees
    q = perihelion distance, AU
    O = longitude of ascending node, degrees
    D = the equinox year (i.e., time of i/O/o).
    g,k = two fields for the magnitude model
    s = angular size at 1 AU, arc seconds, optional

+OBJXY_gkMAGNITUDE
@OBJXY_gkMAGNITUDE
The g,k magnitude model requires two parameters to be specified. One, the
absolute magnitude, g, is the visual magnitude of the object if it were one
AU from both the Sun and the Earth.  The other, the luminosity index, k,
characterizes the brightness change of the object as a function of its
distance from the Sun. This is generally zero, or very small, for inactive
objects like asteroids.  The model may be expressed as:

    m = g + 5*log10(D) + 2.5*k*log10(r)
 where:
    m = resulting visual magnitude;
    g = absolute visual magnitude;
    D = comet-earth distance, in AU;
    k = luminosity index; and
    r = comet-sun distance.

Note that this model does not take into account the phase angle of sun light.

@OBJXY_HGMAGNITUDE
The H/G model also requires two parameters. The first, H, is the magnitude of
the object when one AU from the Sun and the Earth. The other, G, attempts to
model the reflection characteristics of a passive surface, such as an
asteroid. The model may be expressed with the following code fragment:

    beta = acos((rp*rp + rho*rho - rsn*rsn)/ (2*rp*rho));
    psi_t = exp(log(tan(beta/2.0))*0.63);
    Psi_1 = exp(-3.33*psi_t);
    psi_t = exp(log(tan(beta/2.0))*1.22);
    Psi_2 = exp(-1.87*psi_t);
    m = H + 5.0*log10(rp*rho) - 2.5*log10((1-G)*Psi_1 + G*Psi_2);
 where:
    m   = resulting visual magnitude
    rp  = distance from sun to object
    rho = distance from earth to object
    rsn = distance from sun to earth

Note that this model does not take into account the phase angle of sun light.
@Earth satellite
+Object
Objects in Earth orbit are characterized by 9 parameters: the parameters that
define a geocentric elliptical orbit. These orbital parameters are, in order:

   Epoch of the measured values
   inclination, degrees
   RA of ascending node, degrees
   eccentricity, must be < 1
   argument of perigee, degrees
   mean anomaly, degrees
   mean motion, revolutions/day
   orbit decay rate, revolutions/day^2
   integral reference orbit number at Epoch

XEphem treats all Earth satellites as if they had a visual magnitude of 2.0.

@Close Objects
+Close Objects - intro
+Close Objects - control
+Close Objects - options
+Close Objects - misc

@Close Objects - intro
This window allows you to scan the list of objects currently in memory for all
pairs which are separated by less than a given angular distance.

First set up the desired maximum separation, in degrees, and faintest magnitude
using the Close Pairs window. Note that larger separations result in larger
lists and hence longer sorting times. Also set other options via the Options
menu. Separations will be topocentric or geocentric depending on the Equatorial
preference in the Main menubar. Then start the scan via the Go button in the
Control menu.

When the scan completes, all pairs meeting the criteria will appear in the
scrolled list. The columns in the list are as follows:

	  Magnitude_1 Name_1     Magnitude_2 Name_2       Separation

The entries are sorted in increasing order of separation. The total number of
pairs and current conditions are reported above the list and the time when the
scan was performed is indicated in the time stamp label below the list. The
scan does not include field stars.

@Close Objects - control

Controls:

    Go

	This performs the scan one time. The XEphem cursor will change to the
	Watch shape until the scan is complete. The results are listed in the
	scrolled list when complete.

    Auto Update

	This causes the scan for close objects to be performed automatically
	each time an Update is commanded from the Main window. The prior list
	is discarded each time. The list is never updated when the window is
	not open.

    Sky Point

	This will place a cross-hair over the first object of the selected
	pair on the Sky View, re-aiming if it is currently not in the field.
	Either select the pair in the list then press this button, or
	double-click on the pair in the list. (These commands do nothing if
	the Sky View is not currently up.)

    List to file...

	This selection allows writing the current collection of close objects
	to a file.

	A window is presented which allows you to enter a file name. If the
	file does not exist, the file is written as soon as you select Ok. If
	the file already exists, you are first asked whether you wish to append
	to the file or overwrite existing contents.

	The format of the file begins with a header line that captures the
	conditions in effect when the set of close objects was built. Following
	the header, there is one line per pair with exactly the same
	information as appears in the window list.

    Close
	
	This closes the Close Objects window. The list is not modified in any
	way while it is closed.

@Close Objects - options

Options:

    Omit fixed pairs

	When this option is active, then one or both objects of a pair must be
	wanderers (any object that is not of type Fixed).

@Close Objects - misc
Algorithm:

    The sky dome is broken into bands of constant Dec with height equal to the
    given separation. The database is scanned once and each object is dealt
    into its corresponding band and the one adjacent in the direction of the
    North pole. Each band is then sorted by RA. Each band is then scanned for
    close pairs, with rapid cutoff detection due to the sort.  The final list
    is then sorted by separation, and displayed.

@Saturn
+Saturn - intro
+Saturn - mouse
+Saturn - control
+Saturn - view
@Saturn - intro
This is a schematic view of Saturn, its rings and moons at the indicated date
and time. In addition, background sky objects may also be displayed.

The scale at the left controls relative magnification.

The scale at the right controls the dimmest magnitude which will be displayed.
Saturn and its rings are always displayed. The values range from 20 at the
top and 0 at the bottom. Objects dimmer than the value specified are not shown.

Nominal celestial directions are indicated at the top and right edges.

Moons are displayed only if they are geometrically visible. Use the top
view to see whether they are also in sun light.

@Saturn - mouse
Mouse functions:

The mouse may be used to identify any object in the Saturn view. Position
the cursor near the object of interest and select the right mouse button. A
popup menu will appear with the objects name, current location and magnitude.

@Saturn - control
Control options:

    Field Stars...

	This selection activates the Field Star setup window. For more 
	information about this facility, see the Help for the Field Star
	window itself.

    Telescope command:

	This option causes the location of Saturn to be sent to a fifo. The
	fifo is opened and closed each time this selection is made. The
	intent is for the fifo to be connected to a telescope control process.

	This mechanism is the same as that provided by the Telescope 
	facility within the Sky view. Please refer to its help for more
	details.

    Movie Demo:

	This option will set up the time step controls in the Main window for
	a 15 minute step size and start a loop which dramatically displays the
	motions of the moons as they orbit Saturn. This selection automatically
	disables the View->Sky Background selection to insure reasonable speed.
	Push the button again to stop the movie.

    Close:

	This removes the Saturn display, and the additional information window
	if present, from the screen.

@Saturn - view
View Options:

    Top view:

	Selects whether to also display another window, looking down on
	the Saturnian system from above the celestial N pole. This window will
	tend to remain aligned above the main view when either is resized.
	Moons are displayed only if they are in sun light.

    Sky background:

	Selects whether to also show objects within the current field of view
	that are in the XEphem database memory or available from the Field Star
	facility. The size of the object is determined by the limiting
	magnitude as specified by the scale at the right. Objects are drawn
	using the same symbols as used by the Sky view. While this option is
	on, XEphem will continue to retrieve field stars as required.

    Bright moons:

	If this option is in effect, then the diameter of all moons will be
	increased by 3 pixels. This option also insures that even those moons
	which are dimmer than the limiting magnitude, as specified by the scale
	to the right, will be drawn with a circle of diameter 3 pixels.

    Tags:

	Selects whether to show the Roman numeral designation beneath each moon
	and a 1 arc-minute scale calibration line.

    Flip T/B:
    Flip L/R:

	These allow the scene to be flipped vertically and horizontally, 
	respectively.

    More info...

	This button brings up a separate window which contains quantitative
	information about Saturn's moons and its rings. All values may be used
	in plotting, listing and solving.

	The E and S columns are 1 if the moon is visible from the Earth and
	Sun, respectively.
	
	The ring tilt is displayed as the angle above or below the line of
	sight to Saturn from the Sun and the Earth. A positive value means the
	front of the rings are tilted southward.

	The locations of the moons are given in two coordinate systems. The
	first three columns are the displacements of the moons in Saturn
	radii with respect to the celestial plane. The next two columns
	give the RA and Dec location of the moons in the current epoch (as 
	specified on the Main window).

@Jupiter
+Jupiter - intro
+Jupiter - mouse
+Jupiter - control
+Jupiter - view
@Jupiter - intro
This is a view of Jupiter and its Galilean moons at the indicated date and
time. In addition, background sky objects may also be displayed.

The scale at the left controls relative magnification.

The scale at the right controls the dimmest magnitude which will be displayed.
Jupiter is always displayed. The values range from 20 at the top and 0 at the
bottom. Objects dimmer than the value specified are not shown.

Equatorial directions are indicated at the top and right edges.

Moons are displayed only if they are geometrically visible from Earth. Use
the top view to see whether they are also in sun light.

The default longitude of the GRS is set to 61 degrees, where it was in late May
of 1997. This may be changed interactively in the More Info window.

@Jupiter - mouse
Mouse functions:

The mouse may be used to identify any object in the Jupiter view. Position
the cursor near the object of interest and select the right mouse button. A
popup menu will appear with the objects name, current location and magnitude.

@Jupiter - control
Control options:

    Field Stars...

	This selection activates the Field Star setup window. For more 
	information about this facility, see the Help for the Field Star
	window itself.

    Telescope command:

	This option causes the location of Jupiter to be sent to a fifo. The
	fifo is opened and closed each time this selection is made. The
	intent is for the fifo to be connected to a telescope control process.

	This mechanism is the same as that provided by the Telescope 
	facility within the Sky view. Please refer to its help for more
	details.

    Movie Demo:

	This option will set up the time step controls in the Main window for
	a 15 minute step size and start a loop which dramatically displays the
	motions of the moons as they orbit Jupiter. This selection automatically
	disables the View->Sky Background selection to insure reasonable speed.
	Push the button again to stop the movie.

    Close:

	This removes the Jupiter display, and the additional information window
	if present, from the screen.

@Jupiter - view
View Options:

    Top view:

	Selects whether to display another window located over the pole
	that is on top in the front view. This window will try to remain
	aligned above the main view when either is resized. Moons are
	displayed only if they are in sun light.

    Sky background:

	Selects whether to also show objects within the current field of view
	that are in the XEphem database memory or available from the Field Star
	facility. The size of the object is determined by the limiting
	magnitude as specified by the scale at the right. Objects are drawn
	using the same symbols as used by the Sky view. While this option is
	on, XEphem will continue to retrieve field stars as required.

    Bright moons:

	If this option is in effect, then the diameter of all moons will be
	increased by 3 pixels. This option also insures that even those moons
	which are dimmer than the limiting magnitude, as specified by the scale
	to the right, will be drawn with a circle of diameter 3 pixels.

    Tags:

	Search whether to show the Roman numeral designation beneath each moon
	and a 1 arc-minute scale calibration line.

    Flip T/B:
    Flip L/R:

	These allow the scene to be flipped vertically and horizontally, 
	respectively.

    More info...

	This button brings up a separate window which contains quantitative
	information about Jupiter's moons and central meridian longitude. All
	values may be used in plotting, listing and solving.

	The E and S columns are 1 if the moon is visible from the Earth and
	Sun, respectively.
	
	The locations of the moons are given in two coordinate systems. The
	first three columns are the displacements of the moons in Jupiter
	radii with respect to the celestial plane. The next two columns
	give the RA and Dec location of the moons in the current epoch (as 
	specified on the Main window).

	Value of the System II longitude of the Great Red Spot is displayed.
	The value may be changed according to current information. Pressing
	Enter will update the Jupiter display with the new value.

@Uranus
+Uranus - intro
+Uranus - mouse
+Uranus - control
+Uranus - view
@Uranus - intro
This is a schematic view of Uranus and its moons at the indicated date and
time. In addition, background sky objects may also be displayed.

The scale at the left controls relative magnification.

The scale at the right controls the dimmest magnitude which will be displayed.
Uranus is always displayed. The values range from 20 at the top and 0 at the
bottom. Objects dimmer than the value specified are not shown.

Nominal celestial directions are indicated at the top and right edges.

Moons are displayed only if they are geometrically visible. Use the top
view to see whether they are also in sun light.

@Uranus - mouse
Mouse functions:

The mouse may be used to identify any object in the Uranus view. Position
the cursor near the object of interest and select the right mouse button. A
popup menu will appear with the objects name, current location and magnitude.

@Uranus - control
Control options:

    Field Stars...

	This selection activates the Field Star setup window. For more 
	information about this facility, see the Help for the Field Star
	window itself.

    Telescope command:

	This option causes the location of Uranus to be sent to a fifo. The
	fifo is opened and closed each time this selection is made. The
	intent is for the fifo to be connected to a telescope control process.

	This mechanism is the same as that provided by the Telescope 
	facility within the Sky view. Please refer to its help for more
	details.

    Movie Demo:

	This option will set up the Main window time step controls for a 15
	minute step size and start a loop which dramatically displays the
	motions of the moons as they orbit Uranus. This selection automatically
	disables the View->Sky Background selection to insure reasonable speed.
	Push the button again to stop the movie.

    Close:

	This removes the Uranus display, and the additional information window
	if present, from the screen.

@Uranus - view
View Options:

    Top view:

	Selects whether to also display another window, looking down on
	the Uranus system from above the N celestial pole. This window will
	tend to remain aligned above the main view when either is resized.
	Moons are displayed only if they are in sun light.

    Sky background:

	Selects whether to also show objects within the current field of view
	that are in the XEphem database memory or available from the Field Star
	facility. The size of the object is determined by the limiting
	magnitude as specified by the scale at the right. Objects are drawn
	using the same symbols as used by the Sky view. While this option is
	on, XEphem will continue to retrieve field stars as required.

    Bright moons:

	If this option is in effect, then the diameter of all moons will be
	increased by 3 pixels. This option also insures that even those moons
	which are dimmer than the limiting magnitude, as specified by the scale
	to the right, will be drawn with a circle of diameter 3 pixels.

    Tags:

	Search whether to show the Roman numeral designation beneath each moon
	and a 1 arc-minute scale calibration line.

    Flip T/B:
    Flip L/R:

	These allow the scene to be flipped vertically and horizontally, 
	respectively.

    More info...

	This button brings up a separate window which contains quantitative
	information about Uranus's moons. All values may be used in plotting,
	listing and solving.

	The E and S columns are 1 if the moon is visible from the Earth and
	Sun, respectively.
	
	The locations of the moons are given in two coordinate systems. The
	first three columns are the displacements of the moons in Uranus
	radii with respect to the celestial plane. The next two columns
	give the RA and Dec location of the moons in the current epoch (as 
	specified on the Main window).

@Trails
This window allows you to define a set of time values spaced at regular
intervals beginning at the current XEphem time and define which and in what
manner values will be annotated with a time stamp.

This is a general purpose facility used in several places throughout XEphem,
generally for the purpose of establishing a trail of object motion. This
description will be of a general nature. For the specific information on how a
given XEphem view uses these time values, please refer to the Help information
associated with that view.

Seven parameters must be specified:

    Orientation:

    	This choice determines where the stamps appear in relation to their
	corresponding position mark.

	The radio box in the upper left corner provides several strategies for
	placing the time stamps near each mark. The first several options
	should be obvious. The last two, "Path-left" and "Path-right", cause
	the time stamps to be placed to the left or right side of the trail
	path, as one would perceive these directions when traversed in forward
	order. In no case are the time stamps ever drawn to require you to turn
	your head more than 90 degrees left or right.

    Interval:

	This is the time interval between each step.
	
	Choose from among the several handy intervals in the upper central
	radio box, or choose Custom and enter any desired interval in the space
	provided. It is okay to specify more than 24 hours to achieve intervals
	of several days. It is also okay to specify negative values to run time
	backwards.

    Label:

        This choice determines which intervals will to be label with a time
	stamp.
	
	Choose from among several options in the upper right radio box, or
	choose None if no labeling is desired.

    Format:

        This choice determines how to display each time-stamp.
	
	The lower left radio box offers either Hour:Minute format or the
	current date Preference (as set in the Preferences->Date formats option
	in the Main menubar).

    Font:

	This choice sets the size of the annotation text font.

	The bottom central radio box allows you to choose from several
	character sizes for the time stamps.

    Start:

    	This choice specifies how the first time value is derived from the
	current XEphem time.

	The lower right radio box offers several methods of determining the
	beginning of the first time interval. "Whole min" rounds the current
	XEphem time forward to the next whole minute, if necessary; "Whole day"
	rounds to the next whole day. "Whole interval" rounds to the next whole
	multiple of whatever time interval is set (as specified in the Intervals
	choices). "Now" means to begin with the current XEphem time without
	any initial changes.

	The idea here is generally to match the time values of each time mark
	with the precision implied by the format, but to allow other options
	as necessary.

    Number of tick marks:

	This is specified by setting the scale near the bottom of the window
	to the desired number.


Once the choices are set up as desired, Ok will create the trail and the
window will disappear. Apply will create the trail but the window will remain
up for further use. Close just dismisses the window without creating a trail.
Help brings up this message.

Even with all this flexibility pleasingly annotated trails are not trivial to
generate. It is hoped that a little experimentation can yield acceptable
results in most cases.

Note that this general trail facility does not provide close coupling with the
view being supported. For example, some views do not support setting a trail
for an object which has changed while the Trail Setup is up. Also, views may
vary in their support of having trails defined while they are not visible. 
Each view may establish its own initial default values but changes usually
remain in effect for subsequent instances of Trail Setup windows from the same
view. Some views permit more than one Trail Setup to be active at one time. In
short, the operational boundary conditions vary by view.

@Example - sky trail
This example will use the Sky View to display a trail of the appulse between
asteroid 121 Hermione and NGC 7293 which occurs about July 28, 1995. We also
demonstrate displaying stars from the Hubble GSC catalog in the sky background
(you will need either the GSC CDROMs or a live internet connection for this).
This example is taken from Sky and Tel, July 1995, page 72.

    for convenience, use UTC for all time displays:
	Main->Preferences->Time zone->UTC

    set time to 00:00 using shortcut:
	Main->UTC Time:->00:00:00

    set date to 24 July 1995 using the interactive calendar:
	Main->(Year)->1996
	Main->(Year)->1995
	Main->(Month)->July
	Main->24

    commit to new date and time:
	Main->Update		// note NEW CIRCUMSTANCES stops flashing

    read in asteroid and NGC databases:
	Main->Data->Load/Delete ...
	    in lower right corner, double-click on "asteroids.edb"
		(or could have single-clicked and then pushed Append)
	    similarly, double click on "NGC.edb" (scrolling a bit if necessary)
	    Control->Close

    select 121 Hermione to be Object X:
	Main->Data->Search, ObjX,Y,Z...
	in the upper center, click on ObjX
	in the lower right, type "hermi" then Enter in the Search text field
	    (this finds 121 Hermione in memory and stages it to become ObjX)
	    (you may also browse by scrolling through the list at right and
	     selecting the candidate object's button).
	load this into Object X and dismiss the window:
	    Ok

    display asteroid trail on sky view:
	Main->View->Sky View...
	    Locate->121 Hermione
	    set Field of View to about 1.5 degrees using scale on left
	    Control->Filter..
		set "Sol Sys Lim Mag" to 16 using scale
		Ok
	    place cursor over the central dot (Hermione!) and press button 3:
		Create Trail...
		    Orientation: Left
		    Interval: 1 Day
		    Label: Every 2
		    Format: Date
		    Font: Small
		    Number of tick marks: slide to 8
		    Ok
	    center the trail by placing cursor near dot for 7/28/95 and press
	    button 3, then scroll down and release on:
		Center

    add nearby Hubble Guide Star Catalog entries:

	If you have not already done so, set up the source for the GSC stars:
	    Sky View->Control->Field Stars...

	Enable viewing Field Stars and load an initial set:
	    Sky View->Control->Options->Field Stars

	The GSC stars will now be read in and displayed.

    if desired, overlay with a coordinate grid:
	Sky View->Control->Options->Grid
	(making the Sky View wider will allow room for more grid labels)



As another example, investigate the appulse between M21 and 241 Germania near
July 15, 1995. Use ObjY for the asteroid so you can leave ObjX as Hermione.
If you have your Sky & Tel handy, this is also described on the same page as
the above reference. From the picture in that article, you can see that the
elements shipped with XEphem for 241 Germania no longer quite match the epoch
of the image, and the Saguaro Astro Club entry for M21 is slightly too far
south and east. This emphasizes an important note: XEphem is only as good as
its databases.

@Example - eclipse path
This example displays the location of totality on the Earth for the solar
eclipse of July 11, 1991.

    for convenience, use UTC for all time displays:
	Main->Preferences->Time zone->UTC

    set time to 17:25:00
	Main->UTC Time
	    enter 17:25:00 then Ok (or just Enter).
	    note you may use almost any punctuation character instead of ":"
	        and you need not give leading zeros. for example: "17;25;0".

    set date to 11 July 1991:
	Main->UTC Date
	    enter 7/11/1991
	    note this should be entered according to the current date format
		preference. for example, after
		    Main->Preferences->Date formats->Y/M/D
		you would enter the same date as "1991/7/11".

    commit to new date and time:
	Main->Update		(note NEW CIRCUMSTANCES stops flashing)

    display the Earth:
	Main->View->Earth...

    A black cross should appear a little southwest of Hawaii. That is the
	current center of totality.

    display the subearth point of the Moon, i.e., the point on the Earth's
	surface at which the Moon is directly over head:

	Set Moon as current object:

	    Control->Objects...

	Click on Display and Label.

    One may now easily read off the local altitude of the Moon by comparing
	with the circles of 0, 30, 60 and 90 degree altitudes. More precise
	values for altitude, and azimuth, may be obtained for any location
	using the right mouse button.

    change Main location to Mauna Kea Observatory:
	move cursor near southeast edge of Hawaii, hunt around clicking right
	    button until the popup says Mauna Kea, slide down and let go over
	    "Point"
	Earth->Control->Set Main
	    the white Plus on the Earth should move over Mauna Kea and the
	    central longitude should shift to approximately 155 degrees west.
	    Note the Latitude and Longitude in the Main view are also updated.

    Zoom the view to show the sky from Hawaii:
	Main->View->Sky View...
	    Sky View->FOV->1	(move left scale up until it says about 1.0)
	    Sky View->Locate->Sun
	    move cursor over the center of the Sun, select right button, pull
		down and let go over "Track"
	    make sure Sky View->Control->Options->Alt-Az is selected
		(or Main->Preferences-> Equatorial->Topocentric is set)
		to get a topocentric point of view.


    set up a movie showing the path of totality for the next two hours:
	Main->N Steps-> enter "24", then Enter
	Main->Step->0:05:00
	Main->Pause->1
	Main->Update

@Example - sun plot
In this example, we will plot the times of local dawn, sunrise, sunset, and
dusk over the course of 2001.

    Set the date to Jan 1 2001:
        Main->Local Date-> 1/1/2001
            you might have to enter this differently depending on your current
                Date Formats preference.

            you could also set the date by using the interactive calendar at
            the right: select the current month, slide and release over January.
            then push the "1" date on the calendar.

     Show times in local timezone:
        Main->Preferences->Time zone->Local

    Set the time to local midnight:
        Main->Local Time-> select 00:00:00 shortcut

    commit to the new date and time:
        Main->Update            (note NEW CIRCUMSTANCES stops flashing)

    bring up the data table:
        Main->View->Data Table...

        (if the RisTm and SetTm columns and the Sun row are not visible, use
        the Setup option to enable at these columns and rows.)

    bring up the plot control window:
        Main->Tools->Plot...

    define a plot with four independent traces with local date on their X axis:
        Plot->Select fields
            (note how all labels which can be used for plotting now look and
            operate like buttons. as you press them, they form the definition
            of what will be saved for plotting; watch the X and Y columns of
            the Plot window be filled in as you define the variables to plot).

        Main->Local Date
        Main->Dawn

        Main->Local Date
        Data->Sun.RisTm

        Main->Local Date
        Data->Sun.SetTm

        Main->Local Date
        Main->Dusk

        Plot->Select fields     (turns buttons back to labels)

        When you are finished, the lower portion of the Plot window should look
        like this:

            Tag         X          Y
            A           LD        Dawn
            B           LD      Sun.RisTm
            C           LD       Sun.SetTm
            D           LD        Dusk

        If you make a mistake, you must start over (Undo is on my list :-)

        If you wish, you may edit the Tags to more accurately denote their
        meaning, such as D, R, S and d. Case is significant, but you only get
        one character.

    Set up Main to generate data every other day for 182 steps, i.e., span about
    one year:

        Main->N Steps->182
        Main->Step-> enter 2d, then select Ok (or type Enter)

    Give the plot a title in the text field provided:

        Type: Local Sun Dawn/Rise/Set/Dusk time for 2001

    Define a file to contain the plot values:

        Plot-> enter a file name in the text field, such as sun2001.plt

    Start capturing XEphem plot data to the plot file:

        Plot->Create plot file

    Let XEphem run:

        Main->Update

        Note that as it runs, XEphem does not update many values and they are
        made to look unusual. This is for speed. It only does this if
        Main->Pause is set to 0. If Pause is anything greater than 0, all
        values are drawn. In any case, internal values are always updated; it's
        just the display that is eliminated for a little more efficiency.

        Also, things will go fastest if the Data Table is only showing what
        is necessary, such as turning off all but the Sun row in this case..

    When it stops, display the year of plot data:

        Plot->Show plot file

    Note how the "Plot->Create plot file" option is automatically disabled.
    Also note the spring and fall discontinuities in the plot if you observe
    Daylight Savings time in your time zone.

    Change the X axis label to be a little easier to relate to:

        Plot->View->Show X-Axis as Dates
@Example - ring plane
This example will demonstrate the programmable equation solving feature by
solving for the time when the Earth crosses the ring plane of Saturn. 

Generally when using the solving feature of XEphem, a plot of the function
should be made first to investigate the general behavior of the function over
time and to form an initial estimate of the solution. Hence, our first step is
to make a plot of ring plane angle throughout 1995.

    Use UTC for all time displays:

	Main->Preferences->Time zone->UTC

    Set the date to Jan 1 1995:

	Main->Local Date-> 1/1/1995
	    You might have to enter this differently depending on your current
		Date Formats preference.

	    You could also set the date by using the interactive calendar at
	    the right: select the current month, slide and release over January.
	    then push the "1" date on the calendar. Do the same sort of thing
	    to set the year.

    Set the time to UTC midnight:

	Main->UTC Time->00:00:00

    Bring up the Saturn diagram and supporting information views:

	Main->View->Saturn...
	    Saturn->View->More info..

    Bring up the plot control window:

	Main->Tools->Plot

    Select one function to plot, UTC Date vs. Earth ring tilt:

	Plot->Select fields	// turn on
	    Main->UTC Date
	    Saturn info->From Earth
	Plot->Select fields	// turn off

    Specify plot file name and give it a title:

	Plot->File name: rings.plt
	Plot->Title: Saturn Earth Ring Tilt for 1995

    Enable plot file capture:

	Plot->Create plot file

    Accumulate 180 steps, each 2 days:

	Main->N Steps 		enter "180" then Enter
	Main->Step		enter "2d" then Enter
	Main->Update		// runs through 180 steps, rather subdued. it
				// runs faster if you close the Saturn view.

    Display plot file, 

	Plot->Show plot file
	Plot file->View->Show X-Axis as Dates

    There are evidently two crossing, one in late May and one in early August.
    Lets solve for the one in August:

	Main->December->August
	Main->Update				// to engage NEW CIRCUMSTANCES

    Open the Solve control window, set up to solve for when the Earth ring
    tilt goes to zero:

	Main->Control->Solve...
	    Solve->Enable field buttons	// turn on
		Saturn info->From Earth
	    Solve->Enable field buttons	// turn off
	    Solve->Compile
	    Solve->Find 0
	    Solve->Solving is Active

    And go:

	Main->N Steps->1000000
	Main->Update

    The looping stops at Aug 10, 1995, at about 19:54 UT. The August 1995 Sky
    and Tel, page 72, says it occurs at about 21h +- 2.
@Example - whats up
This example will take us through a session which explores the sky tonight at
midnight. Of course, you can do this for any night by setting the desired date
first on the Main window.

    Set time to midnight tonight:

	Main->Local Time->Midnight Tonight
	Main->Update

    Display the available database files:

	Main->Data->Load and Delete...

    Load up several database files, as desired, by double-clicking in the
    list at at the bottom:

	    Data Base->YBS.edb		// Yale Bright Star catalog
	    Data Base->Messier.edb	// Messier catalog
	    Data Base->NGC.edb		// RNGC objects (all but Messier)
	    Data Base->SAC.edb		// even more deep-sky objects
	    Data Base->asteroids.edb	// many asteroids 

    Bring up the sky view:

	Main->View->Sky View...

    Explore around using mouse pointing and/or by sliding field-of-view and
    pointing controls as desired.

    Save the objects in the Sky View in a file:

	Sky View->Control->List...

    Make a printed copy:

	Sky View->Control->Print...

    Now let's focus in on some close encounters. Let's switch to RA and Dec
    coordinates, tighten up the field and increase the limiting magnitude so
    we can see fainter things:

	Sky View->Control->Options->Coord:RA-Dec
	Sky View->FOV->  slide to 2.0
	Sky View->Control->Filter...
	    Sol Sys Lim Mag ->  slide to 14
	    Stars Lim Mag ->  slide to 14
	    Deep Sky Sys Lim Mag ->  slide to 14
	    Ok

    You'll probably want to use the Topocentric preference from the Main window:

	Main->Preferences->Equatorial->Topocentric

    Open the Close objects window, build a list of all moving objects within,
    say, 1 degree of each other:

	Main->Tools->Find close pairs ...
	    Close->Max sep->    enter 1.0
	    Close->Mag limit->  enter, say, 13
	    Close->Options->Omit fixed pairs	// if not already on
	    Close->Control->Go			// might take a moment..

    Now scroll through your set and find something that looks good. For 
    example, tonight I happened to find asteroid 702 Alauda passing within 16
    arc minutes of the bright open cluster NGC 6416. Double click on the
    row and the Sky View will swing around and show it to you. You might want
    to tweak up the field-of-view a bit.

    If you've chosen an asteroid, let's plot its motion over several hours. Put
    the mouse near the asteroid, click button 3, pull down to "Create Trail..."
    and let go. You'll get a trail setup window:

	Trail->1 Hour
	Trail->First+Mid+Last
	Trail->Number of intervals:  enter 24
	Trail->Ok

    If you get a wild array of lines, be sure Sky View->Control->
    Options->RA-Dec is set.  You may click on any of the tick marks with
    mouse button 3 to get the circumstances of the asteroid at the
    various times along the trail. You can change the trail parameters
    by using "Change Trail..." and proceeding as before.

    With luck, you'll have a pretty appulse to watch.

@Example - lunar occultation
This example was taken from the lunar occultation of Spica (Alpha Vir) which
occurred January 23, 1995, UTC, as reported in Sky and Telescope, January 1995.

    If the YBS.edb database is not already loaded, load it now so that Spica
    is loaded in the XEphem database:

	Main->Data->Load/Delete...
	    YBS.edb
	    Append
	    Control->Close

    Set UTC Zone preferences:

	Main->Preferences->Time zone->UTC

    Set the Topocentric Equatorial preference:

	Main->Preferences->Equatorial->Topocentric

    Set Epoch to EOD (occultations must always be computed using EOD in order
	to incorporate the effect of aberration):

	Main->Epoch

	select EOD

    Set up the date and time to Jan 23, 1995, 11:45:00 UT, using the calendar
	and the "UTC Time:" selections in the Main window.

    Set the Step size to one minute (0:1:0) using the Step selection in the
	Main window.

    Set the location to Chicago, using the Site selections in the Main window:

	Main-><Site>
	    type "chicago" into the Search field,
	    type Enter,
	    type Set
	    select Close

	    or

	    scroll down to "Chicago, Illinois" and double-click on it.

	Main -> Update

    Display the Moon:

	Main->View->Moon..

    Make sure the true Sky background option is enabled:

	Moon->View->Sky background

    Spica is just behind the dark western limb, ready to emerge. To see it,
    press Main->Update to advance the time by 1 minute. Spica appears at 11:47
    and near the craters depicted in the schematic on page 83.

    An analytical method is to use the Main->Tools->Solve method to find the
    time when the following equation evaluates to zero:

    	"Spica.Moon"-"Moon.Size"/7200

    Set the Desired Accuracy to 0:0:1 and one finds the occultation occurs at
    11:46:10 UTC.

@Example - images
This example will go through displaying an image in the Sky View. The image
may be either a FITS file on your local disk, or may be retrieved via the
Internet.

    Bring up the Sky View display:

	Main->View->Sky View...

    Bring up the Image control window:

	Sky View->Control->Image...

    To display a FITS file, use the file selection window at the bottom to
	browse your local file system. When the you have found the file,
	select it in the list and press the Open button. The image will be
	displayed in the Sky View.

	Note: In order to be displayable by XEphem, the FITS file must be in
	16 bit image format (BITPIX 16) and contain either the WCS keywords
	(CTYPE, CRPIX, CRVAL, CROTA, CDELT, 1 and 2), or the standard DSS
	coordinate fields.

    Or, to retrieve a Digitized Sky Survey image, use the Sky View scales
	to center the view on the desired sky location, set the field of
	view scale as desired, and press either of the buttons at the top
	of the FITS window labeled STScI or the ESO. Of course, for these
	to work you must have a live Internet connection.

	STScI is located in Maryland, USA. ESO is in Germany. They both
	provide identical service so use whichever gives you better network
	performance. The maximum size of an image retrieved in this manner
	is currently restricted to 20 arcminutes.

    Once an image is displayed by either method, all Sky View features are
    available. So, you may add a grid overlay, load and display field
    stars, track the coordinates with the cursor, etc etc, as with any Sky
    View. Investigate the various Controls from the menubar of the Sky View
    to see what all is available. For example, to display field stars
    over the image:

	Set up a source for the field stars (if not already set up):

	    Sky View->Control->Field Stars

		(follow the directions in the Help)

	Turn on the following options (if not already on):

	    Sky View->Options...

		Auto mag
		Field Stars

    The image will remain in the Sky View until the center or field of view is
    changed. If you loaded a DSS image, you may want to save it to your local
    disk for easier access next time. 

	In Options->Image...
	    Type in a name for the file (the field is near the center)
	    Press Save.

    As for the image itself, you may adjust the brightness and contrast using
    the controls near the center of the FITS window.

@Example - ISS
This example will show how to display the ground track for the International
Space Station in the Earth View, find when it will next be visible in your
location, and display its path through the sky overhead in the Sky View.

First be sure XEphem has a working connection to the Internet.
Use Main->Network Setup

    Get fresh elements from the web:

	bring up Main -> Data -> Update Earth Satellites
	press "Get" next to ISS
	press "Assign to ObjX"

    Show the current position of the ISS in the Earth view:

	bring up Main -> View -> Earth, then Control -> Objects
	press any of the menu bars at the top, slide down to ISS and release.

    Create a ground track for the next few hours:

	press the Trail button in the column used for ISS.
	slide Number of tick marks to about 50
	select Orientation->Up, Font->Small
	press Apply

    Show "mission control" format:

	press Earth->View->Cylindrical


    To see the next time ISS will rise in your location:

	press Main -> View -> Data table

	The next rise time is in the RisTm column. If this column is not
	visible:

	    bring up Control -> Setup
	    toggle Rise/Set -> RisTm so it is On
	    press Apply

	The highest it will get on this pass is in the TrnAlt column. If this
	column is not visible:

	    bring up Control -> Setup
	    toggle Rise/Set -> TrnAlt so it is On
	    press Apply

    Note the RisTm (from above) and set the the Date and Time in the Main
    window to about 30 seconds or so later. Be sure to use UTC or Local
    depending on Main -> Preferences -> Time zone.

    Show the path overhead in the Sky View:

	check that Main -> Preferences -> Equatorial is set to Topocentric
	press Main -> View -> Sky View...
	check that Sky View -> Control -> Options -> Orientation set to Alt-Az
	slide the FOV to a full 180 degrees
	press Sky View -> Locate -> ISS to mark the ISS on the sky map
	move the mouse over the ISS, press the right mouse button, slide down
	    and release over Create trail...
	select Interval/Custom and type in one minute as 0:01
	also set these options for starters:
	    Orientation/Up
	    Format/H:M
	    Font/Small
	    Label/Every 2
	    Start/Whole interval
	slide Number of tick marks to about 10
	press Apply

@Print
This window lets you print the current view or save it to a file. In either
case the format used is Postscript. 

If you enter a string in the text field labeled Title, the string will be 
printed centered across the top of the page.

The top two toggle buttons allow you to choose whether color commands will
be included in the Postscript generated.

If you choose to Save to a file, turn on that toggle button and type the
desired file name in the text box to the right of the toggle button. The file
name will be relative to the directory from which XEphem was executed or
you may precede the file name with "~/" to refer to your home directory.

If you choose to print directly to the printer, turn on that toggle button and
type a command which will print a Postscript file on your system. The command
should expect the name of a file to print as its first and only argument. A
temporary file will automatically be created for this command and deleted when
printing is completed.

When ready, press Ok. To avoid printing, press Cancel.

If your current viewing fonts are not available for printing, error recovery
will depend upon your local print system.

@FieldStars
This window allows you to control which field star sources you wish
to use. The window is accessible from the Main window as well as from the
Control menus of most graphical views.

XEphem uses the term "field star" to refer to the huge numbers of faint
stars visible in any real world view of the sky. Field stars are generally
far more numerous than could be reasonably accommodated in the XEphem *.edb
database format. For this reason they are stored and made available in their
own special compact forms for utmost efficiency. The downside to this approach
is that field stars are not included in the totals presented by the Data->Load
window nor are they available for searching or inspection using the Data->Search
window. This results in little loss of generality, however, since (once
found!) they may be assigned to the user defined objects (ObjX, Y or Z) by
using the popup menu in the Sky view and thus be further investigated via the
Data table window.

The controls in the Field Stars setup window are grouped into categories,
depending on the basic source of the stars, as follows:

Hubble GSC:

    The Hubble Guide Star Catalog is a seminal work created by the Space
    Telescope Science Institute to support the Hubble Space telescope. It
    contains from 13 million unique stars, or about 300 stars per square
    degree of sky.

    ASP CDROM Directory:

	This choice enables reading field stars from the Hubble Guide Star
	Catalog available on two CDROMs published by the Astronomical Society
	of the Pacific.

	Mount a CDROM somewhere onto your filesystem, type the name of the
	mount directory in the text field provided then turn this option on
	and press Apply. Note that XEphem assumes your CDROM driver removes
	the trailing ";1" from all filenames.

    Local Cache Directory:

	This choice enables reading GSC field stars from your local disk. If
	this option is on along with the CDROM option, then as requests are
	satisfied from the CDROM a compact form of the same data will be
	written to files below the directory named in this option. Then the
	next time the same field stars are needed, and this option is on, they
	will be obtained from the local disk files rather than the CDROM. In
	fact, the CDROM is not needed or used if the local disk contains all
	the stars for any given access. The entire 2 CDROM set loads onto disk
	in this format in some 180 MB.

	The default path of the directory which holds the disk version is
	"catalogs/gsc" off the shared directory.

	Note: There is also a utility in the tools/gsc directory, gscload, with
	which you may preload any entire CDROM segment at once if desired.

	These files are already included in the commercial version of XEphem.

    Internet to xephemdbd:

	This choice is to use the Internet to access an XEphem GSC server. See
	the XEphem home page for the current list of GSC server hosts.

	To use this source, select this option and type the host name followed
	by its path to xephemdbd.pl in the text field provided in typical URL
	fashion (but minus the usual "http:/" thingy).

	If you would like to build this server process and run it more locally
	to your enterprise, the source is in tools/xephemdbd. See the README
	there in for full details. If you would like to give others access,
	let me know and I will add your site to those listed on the XEphem
	home page. Thank you.

    Internet to ESO:

	This choice accesses the GSC catalog service maintained by the
	European Southern Observatory. This choice emulates a web browser
	query and uses the Proxy or SOCKS facilities (described below) which
	should make it accessible to user behind firewalls.

	The CDROM or the cache options may not be used at the same time as the
	network options.

	Note that the ESO GSC server (apparently) arbitrarily and (certainly)
	silently restricts the total number of stars it will return, so larger
	and/or deeper fields may not contain all stars.

	You may also access this service directly from your Web browser at
	http://archive.eso.org/cgi-bin/gsc.

USNO A or SA catalogs:

    Root directory:

	This choice of field stars supports the SA or even the A series of
	astrometric catalogs produced in recent years by the US Naval
	Observatory. The SA2.0 for example, includes some 54 million stars,
	spatially sampled so there is about 1,300 stars per square degree of
	sky. Note that such a uniform distribution does not "look" much like
	the real sky, but it is great for its intended use as an astrometric
	mesh for comet hunters or such.

	To order these catalogs, see http://psyche.usno.navy.mil/pmm.

	If you have such a catalog, simply enter the name of its base
	directory and toggle this switch on. The default assumes a
	symbolic link, "catalogs/usno" off the shared directory.

	The suggested citation for SA1.0 follows:

	    Monet, D., Bird, A., Canzian, B., Harris, H., Reid, N., Rhodes,
	    A., Sell, S., Ables, H., Dahn, C., Guetter, H., Henden, A.,
	    Leggett, S., Levison, H., Luginbuhl, C., Martini, J., Monet, A.,
	    Pier, J., Riepe, B., Stone, R., Vrba, F., Walker, R. 1996,
	    USNO-SA1.0, (U.S. Naval Observatory, Washington DC).

    This catalog has been included with permission of USNO as long as we
    mention the follow stipulations

	It may not be the latest version, check with http://ad.usno.navy.mil.

	If you paid for XEphem, you paid for the software, not this catalog. The
	catalog is available free from the USNO.

	Inclusion of the SA2.0 catalog does not imply an endorsement of XEphem
	by USNO; nor did I have privileged access to the catalog; nor does the
	US Government affirm or guarantee that XEphem works properly in any way.

Proper Motion catalogs:

    These catalogs include information regarding proper motion. The position
    of the star is moved to its location according to the current XEphem time
    when the stars are loaded. In order to see a movement, change the time,
    and watch carefully.

    Two such catalogs are currently available ready for XEphem. You may only
    use one at a time, by choosing the corresponding toggle.

    PPM catalog:

	This is the Positions and Proper Motion catalog of S. Roeser and U.
	Bastian, Astronomisches Rechen-Institut, Heidelberg, published in
	1990. The PPM includes 468,586 stars rather evenly distributed
	throughout both hemispheres. This averages out to more than 10 stars
	per square degree. The set includes the original North and South
	editions plus the extended supplement. The set includes more than 99%
	of the stars in the original SAO catalog and some 70% of the Henry
	Draper Catalogue (HD).   While the SAO catalog is more or less
	complete to V=9, with stars as faint as V=10, the PPM catalog is
	fairly complete to V=9.5, and goes somewhat deeper than V=10.

    Hipparcos and Tycho-2:

	This catalog is a combination of the Hipparcos and the Tycho-2
	astrometric catalogs published by the European Space Agency. These
	are now considered the best proper motion catalog in available.

	This catalog contains all Hipparcos stars for which astrometric and
	magnitude values are assigned, and all additional non-redundant
	entries from the Tycho-2 catalog except multiple-component entries.
	There is a total of some 2.5 million stars, or about 60 stars per
	square degree.

    One example of a star with high proper motion is Groombridge 1830 (HD
    103095), in Ursa Major, near 11h53m 37d44m. For a nice discussion
    see Burnham's Celestial Handbook, Volume III, page 1978. By comparing
    its position in either PM catalog with the same entry from the GSC
    one can deduce this particular GSC field was evidently taken in early
    1983.

    Skip likely duplicates:

	All of the above may be used together with the regular database
	facility of XEphem. If this option is on, XEphem eliminates what
	appears to be redundant entries for the same star from the various
	catalogs. Two stars are considered the same if their positions match
	within 4 arcseconds and their magnitudes differ by less than 3. (The
	generous magnitude tolerance is because the GSC and the PPM use
	varying filters). When deciding on the final selection for such
	duplicate entries the highest priority is the local database, then
	the HD or SAO entry, then the PPM entry, then Hipparcos, then Tycho
	and finally the GSC entry.

When you have made the desired entries, pressing Apply will attempt to check
each filename, directory and Internet choice, as appropriate. The cursor
will be a Watch while the tests are in progress. If something does not seem
correct, a warning window will appear and the option will be turned back off.
If everything seems to be operating correctly, you are in business.
The Ok button does the same thing but then also closes the window if they all
succeed. If at any time during normal operation something goes wrong during
the acquisition of any Field Stars or FITS files from any View, the
responsible option in that view is also turned off automatically.

All field star sources will silently enforce limits on the total number of stars
they yield for any query. As of this writing, local queries are limited to
15 degrees; network queries impose their own limits; FITS and DSS images are
limited to sizes of 20 arcminutes or smaller.

@NetSetup
Network Setup:

This window allows you to define a proxy or SOCKS server to use for the
various XEphem features that utilize the Internet. One of the following
three choices must be enabled for Internet access to be available.

    Direct connect:

	This choice just means to use the direct DNS/IP TCP/IP sockets as
	necessary. Use this one unless you are behind a firewall.

    via Proxy:

	This choice attempts to access the Internet via a Proxy. Type the
	port address and the host name of the proxy in the field provided.

    via SOCKS:

	This choice attempts to access the Internet via a version 4 SOCKS
	server. Type the port address and the host name of the server in the
	field provided. These values can be initialized using the environment
	variables SOCKS_PORT and SOCKS_NS.

@ExternalInput
XEphem can read a file (or fifo) containing sets of time, latitude and
longitude values and automatically install these values sequentially
unattended. Enter the name of the file in the window and press OK. To pause
between updates, set the desired delay in the Pause field of the Main window.
All features of XEphem, such as plotting and listing, are available while this
feature is running.

The format of each line of the file is as follows:

	JD Lat Long

    Where JD   = Julian Date
	  Lat  = Latitude, radians, +north
	  Long = Longitude, radians, +west

    The fields are separated by one or more blanks or tabs.

All lines not having exactly three floating point values are ignored and
may be used for comments, etc.

@NightAtAGlance
This window displays the current day, with local midnight in the center. Across
the bottom is a scale marking local dates and time and UTC time, at each even
hour. The current XEphem time is marked with a thin vertical line.

The background gray shading shows when the Sun is up, down and periods of
twilight. The twilight period matches the Sun Dip setting in the main XEphem
window.

Overlayed on the gray background is one thick line for each basic object and
any of the user objects ObjX,Y,Z that are defined. The lines show when the
object is above the horizon, as defined in the Data View->Control->Setup
horizon parameter. Clicking with the right mouse button near a line will
display quantitative rise and set information for that object.

The window may be printed using the Control->Print menu option.

An interesting exercise is to set up a time loop with a Step size of a few
days and watch how the rise and set times of objects and the amount and
timing of night time are effected throughout the year.

@AAVSO
This window provides easy access to the database of variable star light curves
maintained by the American Association of Variable Star Observers, AAVSO.
Many thanks to AAVSO for their support of XEphem.

First make sure your Internet connection is functioning. The connection may
be made directly, or via a Proxy or SOCKS server. These may be configured in
the File->Network setup window.

To display a light curve:

    1. Enter the AAVSO Name or Designation in the fields in the upper left.
       For example, OMI CET for Mira. If both are entered, the Designation
       has priority.

    2. Enter a range of dates for the data to be retrieved. These may be
       given as a Julian Date or in the current Date format as set in the
       Main Preference menu. The Starting date may also be given as "default"
       which is about 2 years of data; the Ending date may also be given as
       "latest" which means the newest data available from AAVSO.

    3. Press Enter or the "Get Curve" button at the bottom.

To print the current light curve, press Print.

The Sky View may also be used to specify an object as follows:

    1. Position the cursor near the desired sky location in the Sky View.
    
    2. Press and hold down the right mouse button.
    
    3. Slide down the popup menu to AAVSO and release.
    
    4. The 5 stars in the AAVSO that are nearest to the cursor position are
       shown in the list in the upper right sorted by ascending order of
       distance.

    5. Click on one entry in the list to move it to the Name and Designation
       fields on the left and proceed as above to display a light curve. Or
       if the date ranges are already set as desired, double-click the
       entry in the list and the curve will be fetched immediately.

The database AAVSO.edb is specially tailored to match the official names
of stars maintained in the databases at AAVSO. Using this database will
facilitate the selection and retrieval of AAVSO light curves. Databases
can be changed from the Data -> Load/Delete menu in the Main window.

@Save
This window displays all of the options, settings and controls throughout
XEphem which may be saved and reinstated next time the program is started.
These are collectively referred to as "Resources" and in fact are saved
using the standard X Windows resource database mechanism. XEphem uses many
resources, so they are separated into categories in this window for easier
management. Each category may be expanded or collapsed using the +/- control
toggle to show each individual resource, if desired.

Resources have been divided into two classes. Most resources are deemed
suitably interesting that they can be automatically Saved whenever they
change. These are called Major resources. Other resources are considered
Minor in nature, meaning the user is likely to change them frequently while
operating the program and saving them at any one particular setting is not
especially compelling. These are basically window size and position, scale
settings which only effect viewing angle and all of the Sky View Filter and
Option settings. This distinction is of course rather arbitrary however so
please take care when changing and saving resources so just the ones you want
are saved.

In the expanded view, each resource and its value are shown exactly as it
would appear in the disk file if Saved. Those resources which differ from the
last time they were Saved, or since XEphem was started if no Save has yet
occurred, are marked with a bullet. A toggle next to each resource allows
individual selection over whether the resource will be written to disk on the
next Save.

After each Refresh, Major resources which are found to be out of date are
marked with a bold bullet and automatically selected to be Saved if the
Autoselect option on top is active. Minor resources are marked with a hollow
bullet mark and are never selected for Saving by default. If at least one
Major resource is out of date in a category, a bold bullet is placed next
to the category heading; otherwise if at least one Minor resource is out of
date a hollow bullet is used. 

Whether or not any resource is in fact Saved may always be independently set
as desired using its toggle. The discussion above refers only to whether the
toggle for each resource is set automatically after each Refresh.

A key is provided at the top to remind you to what the two styles of bullets
refer, along with a count of the total resources that are out of date in each
class.

Note that the information in this window does NOT automatically track changes
in resources as XEphem is used. You must use Refresh (see below) to update the
status here when desired. In particular, the values which are Saved are what
they were the last time Refresh was performed, not what they actually are
at the moment Save is activated.

If the Autosave option is both on (located in the upper left) all Major
resources that are out of date and selected when XEphem is Quit will
automatically be Saved without first being asked to confirm using this window.

The controls along the bottom behave as follows:

    Save

	Each resource with its toggle button depressed is written to the
	per-user resource file named at the top. If the file already
	exists, it will first be copied to XEphem.bak in the same directory.
	If a resource already exists in the file it will be edited in-place,
	otherwise a new entry is added at the bottom. Other lines in the file
	are left unchanged.

	After using Save, all resources will be considered up to date, even
	if they were not selected to be written to the resource file.

	N.B. The values saved are as they appear in this window, which may be
	different from their current value if they have changed since the
	last Refresh.

    Refresh

	Updates the changed and save status of each resource in this window.
	Each Major resource found to be out of date is selected to be
	saved by default. This refresh action also happens automatically
	after a Save is performed and just before the automatic Saving if
	AutoSave is on when quitting.

    Close

	Closes the Save window.

    Help

	Shows this information.

@Save - fonts
This window lets you inspect and change many of the fonts used by XEphem.

Across the top is a list of all fonts currently installed on your system.
Selecting one will copy the name to the Font text field and show a sample.
You can select with the mouse, or by browsing with the Up and Down keyboard
arrow keys.

Below that is a list of the fonts recently used in this window for 
convenient reuse if required. Selections operate the same way.

In the center is a text field in which a Font name may be entered. The name
is in the X Logical Font Description format, including wild cards if desired.
Press Enter or the Search button to find and display a sample of the font.
The font named here also applies to the table of context push buttons,
described next.

The lower portion of this window is a table of push buttons referring to
separate font contexts. The four toggle buttons just above this table
determines what happens when one of these context push buttons is pressed,
as follows:

    Get current:

	When this toggle is active, pressing a context button will cause the
	name of the current font for that context to be displayed in the 
	text field and history list above.

    Get default:

	When this toggle is active, pressing a context button will cause the
	name of the last saved default font for that context to be displayed
	in the text field and history list above.

    Set:

	When this toggle is active, pressing a context button will cause
	the font named in the central text field of this window to be applied
	to that context throughout XEphem.

    Restore default:

	When this toggle is active, pressing a context button will cause its
	last saved font value to be reinstated.

Across the bottom are two control buttons:

    Close will close with window.

    Help will show this information.

When a context push button is pressed, it also changes the corresponding
resource. In the Preferences->Save window you will notice that the resource
becomes marked as Modified (after you do a Refresh). This allows you Save the
new font choice permanently. If you do not Save it, the change only effects
XEphem until you exit.

There are a few situations scattered around within XEphem for which changing
fonts at runtime from this window does not work perfectly. For example,
changing to a smaller font does not shrink some windows as much as you
might expect. Such anomalies are known challenges and do not indicate serious
problems. After Saving the fonts and restarting XEphem, all will work again
as expected.

Your system likely also has other tools to browse your installed fonts, such
as xfontsel or tkfont. XEphem is designed to interface with these as well.
Use the tool of your choice to browse and preview fonts as desired then use
its Select, Paste or similar feature to put the name into the Font text field
in this window. For example using xfontsel:

    use the menus to narrow the categories to find the font you want;

    press its "Select" button;

    press Clear here;

    position the cursor over the Font text field;

    press the middle mouse button to paste the name into the Font text field.

This is easier to do than describe.
@Save - colors
This window lets you inspect and change many of the colors used by XEphem.

The lower portion of this window is a table of push buttons referring to
separate color contexts. The four toggle buttons above determines what
happens when one of these buttons is pressed.

    Get current:

	When this toggle is active, pressing a context button will cause the
	current color for that context to be displayed in the top portion of
	this window.

    Get default:

	When this toggle is active, pressing a context button will cause the
	last saved default color for that context to be displayed in the top
	portion of this window.

    Set:

	When this toggle is active, pressing a context button will cause
	the color currently being displayed in the top portion of this
	window to be applied to that context elsewhere in XEphem.

    Restore default:

	When this toggle is active, pressing a context button will cause its
	last saved color to be reinstated.

The top portion of this window allows you to see and set colors.

    The three sliding scales in the upper right allow you to set the color
    using either Red/Green/Blue or Hue/Saturation/Value, depending on the
    toggle above. Hue is the pure spectral color, where 0 is red, 33 is
    green, 66 is blue and 100 is back to red.  Saturation is the amount of
    color purity, where lower values mix in more white. Value is like
    brightness, where 0 is totally black.

    Below the scales is a patch showing the current color.

    The text field at left center allows you to type a color using one of the
    standard descriptive names (typically stored in /usr/lib/X11/rgb.txt), or
    in hex RGB notation, for example #ff0000 for pure red or #0f0 for pure
    green. After typing the desired value, press Enter to set the scales and
    see the color in the patch. This field is also set automatically when
    the scales are used to set a color, during Grabbing (see next), and when
    a color context is retrieved.

    Just above the text field is a button labeled Grab. It may be used to
    capture any color on the screen. Press this button, then move the cursor
    around on the screen and the color of the pixel under the crosshair
    cursor will be displayed; press Button1 to capture the color and resume
    normal cursor operation.

    The history list in the upper left stores each color name that is used
    from the text field, making it easier to reuse a color. Selecting a name
    will copy it to the Color text field and show a sample. You can select 
    with the mouse, or by browsing with the Up and Down keyboard arrow keys.

Snuck in below the color patch is a toggle which allows setting the Shadow
thickness to 1 or 2 pixels.

Across the bottom are two control buttons:

    Close will close this window.

    Help will show this information.

When a context button is pressed, it also changes the corresponding resource.
In the Preferences->Save window you will notice that the resource becomes
marked as Modified (after you do a Refresh). This allows you Save the new
color choice permanently. If you do not Save it, the change only effects
XEphem until you exit.

Note that some contexts are subsets of others. For example, "Text boxes bg"
is a subset of Background. To Apply a color to a smaller context, set the
larger context first (if necessary), then the smaller context. Night works
the same as Background but allows you to store a separate color.

Note also that there are a few situations scattered around within XEphem for
which changing colors at runtime from this window does not work perfectly.
For example, toggle button indicators do not follow color changes. Such
anomalies are known challenges and do not indicate serious problems. After
Saving the colors and restarting XEphem, all will work again as expected.
@SETIathome
This window can read and interpret the various log files which accompany
the SETI@home client, version 2 and 3. For full details about this remarkable
project, see http://setiathome.ssl.berkeley.edu.

Enter into the text field at the top the path to the directory in which the
setiathome client is running.

The controls operate as follows:

    Refresh

	Reread the log files in the SETI@home directory specified about and
	produce a new report. An error is reported if any of the required
	files can not be read.

    Sky Point:

	This will center the Sky View at the position of the work unit
	currently being processed. It also assigns the location of the work
	unit to user-definable object OBJZ; doing so will add it to the Locate
	pulldown menu of the Sky View and add it to the View->Data table for
	easy reference.

    Sky Mark:

	This will mark the position of the work unit currently being
	processed on the Sky View, but only if it is already within the
	Sky View field of view. The Sky View is never re-aimed with this
	command. This always also assigns the location of the work unit to
	user-definable object OBJZ; doing so will add it to the Locate
	pulldown menu of the Sky View and add it to the View->Data table for
	easy reference.

    Auto refresh

	When this toggle is active, a Refresh is performed automatically
	every 10 seconds. This toggle is turned off when the window is closed.

The large text box contains some report details. Most entries are taken
directly from the setiathome status files. The Refreshed: entry is the time
and date at which the display info was produced; its time zone is as per
Preferences->Time zone.

At the bottom are controls to Close the window and see this Help information.

@WebTLE
This window provides a means to access orbital element data sets for Earth
satellites in NORAD Two-Line-Element (TLE) format from the Web and install
them immediately into XEphem's active database.

The top rows specify the name of a satellite to look for and a URL which
contains its defining TLE. The given name may appear anywhere in the satellite
name. The URL must use http; ftp is not supported. The default names and URLs
may be edited as desired, and saved using Main -> Preferences -> Save.

When a name and URL are set, press Get to fetch the elements.

If the search is successful, the first matching TLE found in the URL will be
shown in the text box. This may be Selected and Copied to another program
using the mouse if desired in the usual way. Or a TLE may be written into
this box, either manually with the keyboard or by a Paste operation using the
mouse. Leading and trailing blanks and tabs are ignored but the result must
consist of three lines of text.

Once a valid TLE is present in the text box, the satellite may be assigned
to one of XEphem's User Defined Objects: ObjX, ObjY or ObjZ. Press the
button for the desired object. Assigning a satellite to a UDO makes it
available for quick selection in many other XEphem windows, such as the Data
Table and the Earth view.

The bottom section of this window lets you save the TLE shown in the text
box to a file. Simply type the desired name of the file in the field
provided and press Save. If the "Auto file name" toggle is set, then whenever
a TLE is successfully pulled from the web or assigned, the file name will be
automatically set to match the name of the satellite, making it especially
convenient to save if so desired.
@Horizon
XEphem allows you to choose between two ways to display your local horizon.

One way, the simplest, is to define one altitude that will be used at all
azimuths. To use this method, type the desired altitude in the field
provided, then press Enter or toggle the button On.

The other is to create a file containing a table of the altitude and azimuth
around your entire horizon. To use this method, type the name of the file
containing the table in the text field provided, then press Enter or toggle
the button On. The Browse button will bring up a File Selection Dialog for
convenient interactive selection of available files if desired. This is handy
if you find yourself setting XEphem to one of several different Sites and you
have a horizon table prepared for each.



The Horizon profile file format (suffix .hzn) and its use by XEphem are
defined as follows:

    [] Each line should contain exactly two numbers separated by spaces. The
       first number is the azimuth, expressed as degrees East of North. The
       second number is degrees above horizontal. Lines of any other form are
       ignored.

    [] The azimuth ranges from 0 up to 360 degrees. Any values outside this
       range have 360 added or subtracted until they fall in this range.

    [] The lines need not be sorted by Azimuth, although they will be sorted
       when used; thus the horizon map can never cross itself.

    [] If the file does not include the full range of Azimuths, the end
       points will be connected automatically.

    [] It is ok to specify just one point (at any Azimuth). This will result
       in a flat horizon all the way around at the specified Altitude. (This
       is functionally equivalent to using the Fixed Displacement method).

    [] Values in between those in the file are computed by linearly
       interpolating the two nearest surrounding points.

For example:

    0   10
    20  15
    50  25
    100 20
    180 25
    182 45
    185 10
    300 15
