# Help file for xephem v2.8.
@Intro
Xephem is an interactive astronomical ephemeris program for X Windows systems.
It ..
    computes heliocentric, geocentric and topocentric information for all
        objects;

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

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

    comes with sample databases of over 20,000 user-defined objects;

    displays data in configurable tabular formats and in several interactive
	detailed graphical views including Sky View, Earth and Solar System.

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

    displays close-up views of Saturn and Jupiter moon systems which include
	correct sky backgrounds;

    can quickly find all close pairs of objects in the sky;

    can plot and list all data fields to disk files;

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

    can serve as the control point for robot telescopes in real-time;

    can connect to auxiliary database servers;

    supports the Hubble Guide Star Catalog on CD-ROM via gscdbd.

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
precessed to any epoch, local azimuth and altitude, heliocentric
coordinates, distance from sun and earth, solar elongation, angular size,
visual magnitude, illumination percentage, local rise, transit and set
times, length of time up, constellation, and angular separations between all
combinations of objects.

Observing circumstance information includes UTC and local date and time,
local sidereal time, times of astronomical twilight and length of night,
local temperature, pressure and elevation above sea level for the refraction
model and a monthly calendar.

RA/Dec calculations are geocentric and may include the effects of light
travel time, nutation, aberration and precession.  Alt/Az and
rise/set/transit and, optionally, angular separation calculations are
topocentric and include the additional effects of parallax and 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
menu.

@MainMenu
Across the top of the Main menu is a menu bar to allow selecting the
principle display menus of xephem. These may be turned on in any desired
combination.  Each menu will have its own Close button or it may be closed
by reselecting it from the main menu bar.

    The "File" pulldown is a few miscellaneous controls.

	The "Reset" entry will reread the xephem resources.
	
	The "Progress Meter" entry toggles a dialog which displays a simple
	    bar graph of xephem progress. The accuracy and usefulness of the
	    display are highly problematic at this time.

	The "Messages" entry toggles whether the general messages menu is
	displayed. Xephem may beep whenever a new message is placed in the
	messages menu, depending on the "Message Bell" preference; see below.
	
	The "Quit" entry exits xephem after asking to confirm.

    The "View" pulldown toggles any of the several xephem displays.

    The "Control" pulldown toggles the plotting, listing and searching control
    menus.

    The "Objects" pulldown entries toggle the menus which pertain to 
    managing the list of objects in memory.

        The "Data Base" menu allows you to add or replace objects in memory
	from files of database objects.
    
        The "ObjX, ObjY" pushbutton allows you to define the user-defined
	objects, ObjX and ObjY. This menu also allows you to inspect the fields
	of any object currently in memory and locate the object on the Sky View
	menu.

	The "Find Close Objects" pushbutton allows you to search the objects
	currently in memory for all pairs of objects which are separated on the
	celestial sphere by less than a desired angular amount and to also
	easily point to any such pair on the Sky View menu.

    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. Each of these
    preferences may be initialized via the XEphem resources; see the sample
    XEphem.ad resource file for details. The preference options currently
    available include:
    
        Algorithms: Accurate, Fast

            whether the algorithms are chosen for accuracy or speed. When the
            Algorithm setting is for Fast, a simpler precession algorithm is
            used and there is no correction for light travel time or nutation.

	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 menu. (The Message menu is accessible via the File menu in
	    the Main display).

        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.
            
        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 menu and the dawn/dusk times and the calendar in
	    the Main menu refer to UTC or local time.


    Finally, the "Help" pulldown provides access to several general areas of
    information.

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 menu and controlling xephem's run time behavior. See the Help for
"Triad formats" for more information on date, time and coordinate formats.

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

 UTC Date      The UTC date.
 UTC Time      The UTC time.
 Julian        The current Julian date, to about 1-second accuracy.
 Sidereal      The sidereal time for the current time and location..
 TZ Name       The local timezone name.  The name field may be changed to any
               seven-character mnemonic. Setting this manually turns off the
	       auto timezone feature, or choosing the Auto control turns it on.
 TZ Offset     Hours local time is behind UTC, i.e., positive west or negative
               east of Greenwich. Setting this manually turns off the auto
	       timezone feature or choosing the Auto control turns it on.
 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.

 Sun Dip       The number of degrees the sun is below the horizon that we wish
               to call twilight. This sets the value for 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.
 Night 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. The three fields (Dawn, Dusk and Night Length) 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.

 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 searching is on.

 Latitude      Location latitude, positive degrees north of equator.
 Longitude     Location longitude, positive degrees west of Greenwich meridian.
 Elevation     Local elevation of the ground above sea level, in feet. (see
               implementation notes). Used in refraction 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         The epoch, to the nearest 0.1 years, to which the ra/dec
               fields are precessed.  This says (OfDate) when coordinates
               are not precessed, i.e., are in the epoch of date.

Above the Latitude field is an unlabeled field which can hold the name of
the current site location. This field may be selected to present a list of
cities and observatories. The list is a file defined by the XEphem.SITES
resource which is auxil/xephem.sites by default. Selecting one entry from the
scrollable list and pressing Ok will set the Name, Latitude, Longitude and
Elevation fields in the Main menu. This may also be done my double-clicking
on a site name in the list.

The calendar on the right of the Main menu is based on local time or UTC,
depending upon the Time Zone preference. Selecting a date button will set the
date. Unlabeled 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. In no case does using the calendar change the current time
(just the date).

@Operation
When xephem starts it sets the initial values of several fields from 
corresponding X resource values. See the Help for "Initialization" for details
of the names and formats of these resources. Xephem then draws all fields on
the Main screen with their initial values.  The program then loops advancing
time each step by an amount you control and updating all fields each loop.

There are three fields that control this looping behavior. "N Steps"
controls the number of steps, "Step" the amount of time to add each
step, and "Pause" is the amount of real seconds to pause between steps. When
looping is in effect, the bottom button on the Main menu says "Stop". (Note
that Xephem does not pause between steps when plotting or searching is on.)
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, searching or
listing. This is true even if the menu that displays the information is
closed.

Most fields on the Main menu may be changed by selecting them. A prompt dialog
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 dialog goes away. Some of the dialogs 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
menu.  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 menu "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 menu "N Steps" to 1. The Main menu Stop
control can also stop the looping in the usual way.

When any time field is set using the "Now" feature it enables auto timezone
calculation. This means that the TZ Name and TZ Offset fields will be
computed and set according to local timezone information available from the
operating system, if possible, based on the time setting in the other xephem
fields. Auto timezone mode may also be turned on or off explicitly using the
short-cut commands in the TZ Name or TZ Offset timezone prompts. Note that
times zones are only supported if xephem was built with a C compiler which
defined __STDC__.

@Credits
First and foremost, I again want to thank my gorgeous and loving wife, Kathy,
for freely accepting me as I am and for encouraging and supporting my passion
for astronomy in general and writing xephem in particular.

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.

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/.

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.

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.

The libration model was provided by Steve Moshier, who in turn relied heavily
on the following references:

   Eckhardt, Donald H., "Theory of the Libration of the Moon," The Moon and the
   Planets 25, pp. 3-41 (1981)

   Eckhardt, Donald H., "Planetary and Earth Figure Perturbations in the
   Librations of the Moon," in O. Calame, ed., _High-Precision Earth Rotation
   and Earth-Moon Dynamics_, pp. 193-198 (1982) (IAU Symposium No. 63)

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

Earth satellite support is based on the `orbit' program, v3.9, which contains
the following notice:
   Copyright (c) 1986,1987,1988,1989,1990 Robert W. Berger N3EMO
   May be freely distributed, provided this notice remains intact. 
Any errors in applying the code from orbit to xephem are strictly my own.

Thanks to Gary Morris, KK6YB, for supplying timely Shuttle orbital elements to
anyone interested. For more information on his mailing list send the command
"info elements" to listserv@thomsoft.com or read http://www.cts.com/browse/
graym/elements. Two-line orbital element sets for many satellites may also be
obtained from ftp://archive.afit.af.mil/pub/space and popular updates are
posted regularly to sci.space.news. Elements for Mir in particularly
easy-to-use form are at ftp://archive.afit.af.mil/pub/space/mir.tle.

A great source of comet information is http://encke.jpl.nasa.gov. Keep your
fingers crossed for a really good show from Hale-Bopp!

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@tamu.edu. 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).

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.

The sample spacecraft elements were furnished by Ron Baalke.

The sample cities in the "xephem_sites" 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_sites" 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.

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 coordiality and cooperation it fostered in its 
formative years.

Thanks to the Institute for Theoretical Astronomy, St. Petersburg, Russia,
for the asteroids elements as retrieved Nov 1, 1995, from
ftp://medusa.uio.no//pub/bgranslo/asteroid/ast1996f.ele.gz.

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
xephem.edb format are strictly mine.

Thanks to Chris Beecroft <chrisb@netcom.com> for his encouragement and
technical assistance in adding postscript. The 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 xephem.edb
format are strictly mine.

I learned most of what I know of X Windows and Motif programming from 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. I started xephem as a simple learning exercise
in these tools and now I consider them essential for all my GUI applications,
professional and personal.

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.

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 friends from around the world.

@Initialization
Many things about XEphem may be established using X resources. See the sample
XEphem.ad file for a complete example of all that can initialized.

Follows is a list particularly important resources for initialing the fields in
the Main menu. Of course, you may also change any field interactively once
xephem is running too; these just set the initial conditions.

Because of the way unspecified triad components in dates, times and coordinates
are left unchanged (see help on Triad Formats) always specify all three for all
such entries. For example, to initialize the longitude to zero degrees, say
0:0:0, not just 0.

 UD        initial UTC date, such as 10/20/1988, or "Now" to use the computer
           clock.
 UT        initial UTC time, such as 12:0:0, or "Now" to use the computer clock.
 JD        time specified as a Julian Date.
 TZone     hours the local time is behind utc, such as 5:0:0.  You need not set
           this if you use "Now" for UT or UD. Setting this field turns off the
	   auto timezone feature or setting it to "Auto on" turns it on.
 TZName    name of the local time zone, such as CDT. 7 chars max.  You need
           not set this if you use "Now" for UT or UD. This is purely a text
           label; xephem makes no attempt to compute anything from this label,
           such as a UTC offset. Setting this field turns off the auto timezone
	   feature or setting it to "Auto on" turns it on.
 Long      longitude, in degrees west of Greenwich, in the form d:m:s.
 Lat       latitude, in degrees north of the equator, in the form d:m:s.
 Elevation height above sea level, in feet or meters, such as 800. Used to
           compute parallax of solar system objects.
 Temp      air temperature, in degrees F or C, such as 60.
 Pressure  air pressure, in inches of mercury or mBar, such as 29.50.
           Temp and Pressure are used to compute refraction when the AdpHzrn
           option is active; see the Help for the Data setup table.
 StepSize  the time increment between screen updates, such as "1" to give
           one hour updates. this can be a specific amount or RTC to use
           the system clock as a real-time source. You may also specify a
           time in days by appending a D (or d) after the number or a time
           in sidereal days by appending an s (or S) after the number.
 NSteps    number of times program will loop automatically.
           see the discussion under Program Operation.
 Epoch     this sets the desired ra/dec precession epoch. you can put any
           date here (use decimal form, such as 1992.5) or "EOD" to use the
           current instant ("Epoch of Date").
 Pause     The number of seconds to pause between calculation steps.
 TwilightDip Number of degrees the sun is below the horizon that you want to
           define as being the end of "twilight"; must be at least 0.
 Sitename  species a site from the list in the file named by xephem.SITESFILE.
           This will automatically set the Long, Lat and Elevation fields.

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


Times are entered in h:m:s format. If you pick 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.

For typing convenience, the colon (:) used in a time field may also be entered
as a slash (/), semicolon (;) or comma (,).


Dates are displayed and entered in any one of month/day/year, year/month/day
or day/month/year form. A preference selection on the main menu, 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.

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


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 longitude, latitude and "Step" 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.

@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 xephem can not be specifically stated since the Duffett-
Smith book does not warrant its planet position polynomials to any given
degree. I know for sure that better accuracy could be achieved if xephem
used TDT but I have not yet decided on a suitable algorithm.  Allowing for
this manually, comparisons with the Astronomical Almanac are often within a
very few arcseconds for geocentric positions.

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 calendar shows UTC or local time, depending upon the Time Zone
preference, including dates of new and full moon.

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

6) TODO:
 + add tick marks (third axis?) to plots.
 + write a tool to find g/k from a set of predicted magnitudes.
 + add explicit searching for solar and lunar eclipses.
 + do more moons -- code welcome!
 + incorporate Terrestrial Dynamical Time (known as Ephemeris Time prior to
   1984).  TDT is about 57 seconds ahead of UT1 in 1990.
 + account for lunar augmentation.
 + add undo for plot and listing selections.
 + use interruptible work procs for long operations, not just the watch cursor.
 + let xephem put things in the root window.
 + generate postscript skyview and earth files
 + automatically time/date stamp listing files.
 + switch to topLevelShells rather than DialogShells?
 + display occultation path between *any* two objects in the earth view
   (contingent upon getting perturbation theory installed)
 + show correct moon phase and orientation in Sky View.
 + user preference for geocentric or topocentric RA/Dec everywhere.
 + round "eyepiece" or "finder" sky view overlays.
 + square "ccd chip" sky view overlays.
 + support elliptical sizes and position angle.
 + allow saving/restoring skyview history to file.
 + add a local skyview horizon map.

Bugs:
 - the built-in elements for Pluto need to be updated.

@Plot
This menu 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
menus 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 menu. 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 menus 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.

The default plot file name may be specified as the value of the resource
named "XEphem*Plot*Filename.value". If this resource is not specified then
the file name will be "ephem.plt".

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 "Plot to 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 menus 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 menu 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
menus 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
menus 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 menu. Once all the column choices have
been made you may return all the menus 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.

The default listing file name may be specified as the value of the resource
named "XEphem*List*Filename.value". If this resource is not specified then
the file name will be "ephem.lst".

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 "List to 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 menu controls the automatic searching 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 search for the goal.

To perform a search:
   enter a function,
   compile it,
   select a goal,
   set the desired accuracy,
   enable searching,
   start the search 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 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 menus. 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. Whenever a search function has been successfully
compiled, the message will read <no compile errors>. 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 searching.

Selecting a search goal:

You may choose from any of three evaluation algorithms, as selected by the
trio of radio buttons. "Find extreme" will search for a maxima or minima of
the function. "Find 0" will search for a time when the function evaluates to
zero.  "Binary" will keep incrementing time by "Step" (in the main
menu) 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 dialog.

Performing the search:

Once the function is defined and it compiles without errors, you may enable
searching by selecting the button at the top labeled "Searching is Active".
Then, each time "Update" is selected on the main menu the search proceeds until
either "N Steps" iterations have occurred or until "Step" becomes less
than Accuracy. The initial search time and step size are set from the main
menu, and are adjusted automatically as the search proceeds. Note that by
setting "N Steps" to 1 and repeatedly selecting Update you can effectively
single-step the search process. Search control 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 "Search is Active" back off.

Additional notes on searching:

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

The menus that contain each of the fields used in the search function need
not be visible for the fields to used for searching.

The "Close" button removes the search control menu from the screen; it does
not effect actual search operation in any way.

A successfully compiled search function is evaluated each time xephem updates.
Whenever a search function is compiled it is also evaluated using freshly
updated values. In this way, the Search menu can actually be used as an
arbitrary "astronomical calculator" at any time. In each of these cases you
need not be actually `searching' to use these feature.

Hint:

Searching 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 automatic searching feature to zero in.
@Data Table
This is a table of information about each planet, Sol, Luna, and any two
user defined objects, ObjX and ObjY. Each data item occupies one column in
the table and each object occupies one row.

Select the "Setup" button to configure the table rows and columns as
desired.  The initial configuration can be set from the X resources
DataSelRows and DataSelMiscCols. See the sample XEphem.ad resource file for
examples.

When any columns related to rising or setting are active boxes at the bottom
will indicate whether the Standard or Adaptive refraction model is in
effect and whether the times refer to the center or the upper limb of the
object. Similarly, when 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. See the help for the "Setup" menu for more
information about these modes.

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

See the help for the "Setup" menu for a description of each column.
@DataSelection Table
This menu lets you configure which rows and columns will be in the Data
Table.  When this menu 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 menu. "Close" just
closes this menu 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 menu 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 or ObjY are defined then they will also be present and
controllable from this column. See the help for the "ObjX/Y" menu for more
information about user defined objects.

Entries in the remaining three columns in this menu 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. Note
               that this is based on the geocentric location of the object,
               not topocentric.

 RA            apparent geocentric right ascension of object, precessed to
               the epoch of the Main menu.

 HA            apparent geocentric hour angle of object, computed as LST-RA
               from the RA precessed to the epoch of date. Positive angles
	       are west of the meridian.

 Dec           apparent geocentric declination of object, precessed to
               the epoch of the Main menu.

 Az            topocentric degrees eastward of true north for object.

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

 Air           Number of relative airmasses through which light from the object
               passes to the topocentric observer. Computed as 1/sin(Alt),
	       clamped so all values of Alt < 0.1 Radian (~5:44) show as 99.

 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.

 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. This field is not generally
	       useful in searching for eclipses because of this discontinuous
	       sign change. occurs at conjunction. For that, use the various
	       Separations fields.

 Size          angular size of object, in arc seconds.

 VMag          visual magnitude of object.

 Phase         percent of visible surface in sunlight.

Column three controls information related to rising, transiting, and
setting.  These may be computed according to two options.

"StdRefr", which stands for "standard refraction", computes rising and setting
based on the standard horizon refraction of 32 arc minutes. This agrees well
will standard publications. "AdpRefr", which stands for "adaptive refraction",
computes rising and setting based on a refraction model that uses the actual
atmospheric and topocentric circumstances displayed on the Main menu. This
generally leads to accuracies well within one minute if all conditions are
carefully entered. When using the adaptive model, a text entry field is
available in which you may specify a number of degrees the local horizon is
above horizontal.

"Limb" 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. (In fact, these allowances
are only taken into account for the Sun and moon.)

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

 RiseTm
 RiseAz   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   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. This is NOT AVAILABLE for Earth satellites.
 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 timezones:

    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 menu,
    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 menu, 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.
 XX:XX+       "+" appended to rise, transit or set times means the event occurs
                  twice TODAY; the time given is the time of the first event.
              "+" appended to "Hours Up" means it is still up at midnight.



The last column in the Data Table setup menu 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 may be chosen. "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 menu.

When ObjX or ObjY 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:

Searching 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 the six
Apollo landing sites.

The coordinate system of the moon is such that north is up and west is to the
left, as viewed by the unaided eye. The origin is at the nominal center of the
face pointed towards Earth. Latitude increases to the north, and longitude
increases to the east. Letters are placed at each edge of the image to show the
current orientation.

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 image is read from a file in FITS format. The file name is stored in
the X resource XEphem.MoonFile; the default name is auxil/fullmoon.fts. 

The moon tilts slightly as it moves through the sky. This motion is called
libration. A dot on the circumference of the image indicates the limb position
that is currently tilted 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..." dialog. See Help for View for more
	information about this dialog.

    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 km, location
	and solar altitude at its center are displayed in the menu. If the
	location is not near a feature, then only location and solar altitude
	are displayed in the menu. 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 of the object.

    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:

    Set Earthshine...:

	This brings up a dialog 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 sunlight. Full sunlight is useful when you would
	like to puruse the Lunar surface but would rather not change the Xephem
	date to a full moon. The default scale value may be set from the X
	resource XEphem*MoonES*Earthshine.value; the default is 4.

	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.

    Close:

	This closes the main Moon display and, if open, the More info dialog.
	The image is never updated while it is closed. However, if any of the
	fields in the More info dialog are being used for listing, plotting
	or searching, they are updated.

@Moon - view

Views options:

    Apollo sites:

	This sets whether the six Apollo landing sites are marked and
	labeled on the image.

    More labels:

	This sets whether more Lunar features are labeled on the image. The
	features come from a file named by the X resource XEphem.MoonDB, which
	by default is set to auxil/moon_db. Not all entries in the file are
	labeled; only those with a size greater than some minimum which
	depends on the current display Scale factor. Even at the largest
	scale, all of the features are not labeled. However, all features are
	searched at all scales when using the mouse to interrogate a location.

	The font used for all Moon view labels is specified by the X resource
	XEphem.viewsFont.

    Fake stars:

	This sets whether a random set of stars is drawn behind the image. These
	stars have no value other than to create a pleasing effect.

    Sky background:

	This sets whether to show objects within the current field of view
	that are in the xephem database memory. The size and symbol used
	for the object matches that of the Sky view when the faintest
	magnitude filter is set to 6.

    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.

    More info...:

	This brings up a separate dialog with additional information.

	The top portion of the dialog reports the location of the cursor as it
	is moved over the image while the left button is pressed. It also shows
	the altitude of the sun from that location.

	The lower portion of the dialog shows the lunar longitude of sunrise
	and libration information. 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 searching 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.

    The initial scale factor may be controlled by setting exactly one of
    the X resources XEphem*Moon*Scale1X, 2X, 3X or 6x to True. See the sample
    XEphem resource file, XEphem.ad, for an example.
@Mars
This menu displays the central meridian longitude of Mars, that is, the
Martian meridian currently facing towards Earth.  This value may be selected
for plotting, listing and searching as described in the help for these
functions. While looping with Pause set to 0, only the graphical display is
updated (though numeric information is always updated internally each step).

Also included in this menu is a simple schematic display of the Martian
surface at the current time. I would like to find a map with a bit more
detail.

@Earth
+Earth - intro
+Earth - control
+Earth - view
+Earth - object
+Earth - mouse
+Earth - misc

@Earth - intro
This view displays simple maps of the Earth with continent outlines.  The
controls available from the menu bar across the top allow additional
information or views to be drawn. The scales along the bottom and right edges
display, and may be used to control, the current center location.

Either ObjX or ObjY from the xephem database may be displayed on the map.
The subobject location of the 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.

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

If a solar eclipse it occurring any place 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.

@Earth - control
Control options:

    Set Main:

        This sets the Latitude and Longitude of the Main menu 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 menu.

    Movie Demo:

        This sets up an automatic display movie of the Earth. This is
	done by setting the N Steps entry in the Main menu to a large value,
	setting the Step to one half hour and starting xephem looping. The
	movie can be stopped by selecting this option again or by selecting
	Stop from the Main menu.

    Close:

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

@Earth - view
View options:

    Cylindrical or Spherical:

        These mutually-exclusive options select whether
	the Earth is displayed as though it was an unwrapped tin can wrapper or
	as a globe, respectively. The former is useful in that the entire
	Earth's surface is visible at once, although distortion increases near
	the poles. The ideal width-to-height ratio for the cylindrical
	projection, pi, is enforced each time this mode is selected, based on
	maintaining the total window area of the spherical projection at the
	time of the change. Similarly, the spherical projection resizes to
	become a square. Once the change is complete, the window size may be
	directly manipulated manually as desired.

    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 a file of site names. The resource XEphem.SITEFILE specifies this
	file name. By default, it is "aux/xephem_sites". The sample file
	includes a description of the format.

    Sunlight:

        This toggles whether the portion of the earth's surface currently in
	sunlight is displayed.

    Course+Fast:

        When this toggle is on the display is drawn with less resolution but
	about five times faster.

    More Info...:

        This toggles whether a separate dialog box is displayed which contains
	quantitative information about the currently displayed objects as
	follows.

	The sub latitude and longitude of the object is always displayed. If
	the object is an Earth satellite, then additional information is
	displayed. The Range and Range Rate values are always with respect to
	the location defined in the Main menu. These values may be used for
	plotting, searching 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).

@Earth - object
Object options:

    Create Trail...

        This button will bring up a dialog to set up making a trail of the
	current object as it travels from its current position. Each trail time
	is drawn connected with a solid line with each point indicated with a
	small tick mark. The time stamps shown with the trail, if any, are
	always in UTC.  Only one trail is supported at a time. For the trail to
	be visible, the Show Trail option must be on.

	Creating a new trail will delete the old one. The trail will also be
	deleted if the current object is changed, or an Update occurs from
	the Main menu while the Show Trail option is off.
	
	See the Help from the trail setup dialog itself for more details on how
	it operates.

    Track Object:

        The direction of the map may be controlled manually or be set
	to track the current object, depending on this toggle button. When the
	toggle is activated, the Earth view will always be reoriented such that
	the center of the map is located at the the subobject point. When the
	toggle is off, then the Earth view will remain fixed unless changed
	manually. Tracking will automatically be turned off if the orientation
	is changed manually in any way, i.e., via the scales, setting from
	Main, or the right mouse button popup Point option.

    Show Object:

        This toggles whether the object is shown on the map 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 down from the zenith.

    Show Trail:

	This toggles whether a trail, if currently defined, is displayed. The
	trail may be turned on and off as desired without loss but the trail
	is permanently deleted at the next Update from the Main menu if
	this option is off.

    <current object name>:

        At any one time one object is current. The object is chosen using the
	cascade button at the bottom of this control.  Selecting this button
	will bring up a list of the planets and two user objects, ObjX and
	ObjY, if defined.  The name of the current object is always shown on
	the cascade button label.

@Earth - mouse
Mouse functions:

    Left button:

	As long as the left mouse button is depressed and the pointer is over
	the Earth, the local mean time, local sidereal time, latitude and
	longitude of the location will be displayed in the corners of the view.

    Right button:

	If the right mouse button is depressed while over the Earth, a popup
	appears with information related to the location under the cursor.
	If the location is near a site, information is presented with respect
	to that site and the current location of the object. If the location is
	far from any site, information is presented for the latitude and
	longitude of the location under the cursor and the current location
	of the object. If the location is near the current or trailed location
	of the object, information is presented with respect to the location
	under the cursor and for the object at the time of the trail mark.

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

@Earth - misc
Additional Notes:

All computations for Earth satellites are based on the code in the "Orbit"
program by Robert W. Berger, v3.9. This code was used as-is and produces the
exact same output as that program. 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 of a few
degrees.
@Sky View
+Sky View - intro
+Sky View - control
+Sky View - locate
+Sky View - view
+Sky View - fifos
+Sky View - history
+Sky View - mouse
+Sky View - trails
+Sky View - scales
+Sky View - misc

@Sky View - intro
This menu presents a graphical view of the sky including each object currently
loaded in the xephem database. There are several format and control options and
a subset of the database objects may be selected subject to filtering by type
and magnitude range.

Note that while looping with Pause set to 0 the display is not updated (though
all information is always updated internally each step). Thus, creating plots
other procedures that use many time increments run much more quickly
if the Sky View is unmanaged or with Pause set to 0.

The dominant center circular area is the sky display of objects. It displays
each object that meets the brightness and type selection filter criteria. The
left and right mouse buttons can be used inside this area for additional
functionality.

@Sky View - mouse
Mouse operations:

Left button:
    If the cursor is within the central circle and the left mouse button is
    depressed the coordinates of the cursor are displayed in the corners of the
    circular sky area. These coordinates will continue to be updated as
    long as the left button remains depressed as the cursor roams about
    the display. 

    Also, the great-circle angular separation between the point at which the
    cursor was located when the left button was first depressed and its
    location as it is moved around is displayed in the upper right corner
    beneath the Azimuth.

    NOTE: The numeric values displayed during cursor tracking are topocentric
    if the current mode is Alt/Az and geocentric if the current mode is RA/Dec.
    This is different from the data presented elsewhere by xephem which always
    presents Alt/Az as topocentric and RA/Dec as geocentric.

Right button:
    If the cursor is placed over the central region and the third button is
    depressed a popup will appear. The popup contains information and controls
    depending on whether the cursor was near an object.

    If the cursor was near a visible object data is shown which are exactly the
    same as that which is available in the Data Table menu; see its Help for
    more information. In particular, RA/Dec are always geocentric and Alt/Az
    are always topocentric.  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, the location of the cursor is shown.
    The values displayed are topocentric if the current mode is Alt/Az and
    geocentric if the current mode is RA/Dec. This is different from the data
    presented elsewhere by xephem which always presents Alt/Az as topocentric
    and RA/Dec as geocentric.

    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.

        Point:

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

        Point + 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.

        Make ObjX/Y:

	    This will assign the given object to become ObjX or ObjY, depending
	    on which one is currently being displayed in the ObjX/Y menu. See
	    the help for the ObjX/Y menu for more information on that menu.

	Send to LOCFIFO:

	    This will cause the coordinates of the cursor to be sent to a file
	    or fifo. This button is only present if the "Enable LOCFIFO"
	    toggle button is active. See the description of the "Enable
	    LOCFIFO" toggle button, below, for more details.

        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. 

        Persistent label:

	    This will toggle whether a label is drawn next to this object on
	    the display. The label will consist of the name and/or the
	    magnitude, depending on which options are selected in the
	    View->Labels cascade menu.

	    Persistent labels are not subject to faint or bright magnitude
	    filter limits.
	    
	    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).

	Trail:

	    This toggle is only present if the selected object has a trail
	    established. If it has a trail, the toggle state indicates whether
	    the trail is being displayed. The toggle may be selected to
	    change the state. Note that turning off a trail does not actually
	    discard the trail until the next Update occurs from the Main menu.

        Create Trail (or Change Trail) ...

	    This pushbutton will bring up a dialog 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 selection allows writing a short description of each object that
	is currently displayed in the Sky View to a file.

	A dialog 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 two line header. The first line
	describes the current circumstances of the Sky View. The second line
	consists of column headers. The header is always written. Following
	these two lines, there is one line per object. RA and Dec are
	geocentric, Alt and Az are topocentric.

	Note from the author: I am not sure how much work should go into this
	feature. If you like this feature but wish you had more control over
	which columns are printed, would like the header to be optional, or
	have other ideas please feel free to contact me with your comments:
	ecdowney@noao.edu.

    Save...

	This selection allows creating a postscript file of the current Sky
	View.

    Print...

	This selection allows printing the current Sky 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 menu 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 menu to go away.

@Sky View - view
View Options:

    Alt-Az / RA-Dec:

	This radio box selects whether the display coordinate system is
	Altitude-Azimuth or Right Ascension-Declination.  Whenever the Alt-Az
	system is used, nothing is displayed that would lie below the current
	horizon (except trails; see note under Sky).

	The orientation of the display circle is always without reflections. In
	Alt-Az mode, left, right, up and down as are they would appear to the
	otherwise unaided eye. In RA-Dec mode, up is always celestial north,
	left is always celestial East. The meridian named by the horizontal
	scale is always the line between the center of the field-of-view and
	the nearest pole.

	NOTE: While in Alt/Az mode the display is topocentric; while in RA/Dec
	mode the display is geocentric. Thus, a close object will appear to move
	due to parallax.

    Grid:

	The toggle button labeled "Grid" controls whether a calibration grid
	will overlay the display. When the grid is displayed, the step sizes
	are displayed below the toggle button and selected gradations are
	labeled around the outside of the circle. The gradations for
	Declination or Altitude are labeled in the upper left and lower right
	of the view; the gradations for RA or Azimuth are in the upper right
	and lower left. Each label is drawn only if it fits entirely within the
	display area; thus, more grid labels tend to be shown if the sky view
	is somewhat wider than it is high.

    Just dots:

	This toggle selects how objects are drawn.

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

	When the toggle is released, each type of object is displayed with a
	unique schematic symbol. These symbols may be viewed from the Filter
	menu.
      
	The diameter of the dots or symbol 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
	drawn 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 (recall that RA-Dec mode displays geocentric
	views) and set to Track either the sun or the moon (whichever you wish
	to be centered during the movie).

	In either form, the color of the object is displayed according to the
	value established for each basic type in the X resource database. See
	the sample XEphem.ad resource file for examples of setting object
	colors.

    Flip L/R and Flip T/B:

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

    Ecliptic:

	This toggle selects whether a dotted line is drawn 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.

    Magnitude Key:

	This toggle selects whether a chart is drawn to indicate the size of
	dots used for several magnitude values. Even if this toggle is set, the
	key is not drawn if it does not fit.

    Labels ->

	This submenu controls whether to label all or just the brightest
	objects within the current field of view with their name and/or their
	magnitudes. Trailed entries do not contribute towards the brightest
	count and the "Persistent labels" option for individual objects is not
	lost. Magnitudes are shown to the nearest 1/10 with the decimal point
	removed. If names and magnitudes are both enabled then the magnitudes
	are shown to the right of the name surrounded by parentheses.

	If the font named by the X resource XEphem.viewsGreekFont can be
	loaded, then names which begin with a constellation abbreviation
	followed by a Greek Bayer designation and drawn using the actual
	Greek font character and the constellation name is suppressed.

	The All and Brightest toggle buttons work together as a radio box,
	though it is allowed for them both to be off. The Names and Magnitudes
	toggle buttons may be set in any combination except both off. If this
	condition ever does occur, the Names option will be set on
	automatically.

    Constellation -> Boundaries:

	This toggle controls whether constellation boundaries are drawn.

    Constellation -> Figures:

	This toggle controls whether constellation figures are drawn.

    Constellation -> Names:

	This toggle controls whether constellation names are drawn. The names
	will be centered within the extent of the constellation figure.

    Filter:

	The Filter button along the bottom brings up a menu of several classes
	of objects. Using the Filter menu, one may select which classes of
	objects are displayed on the Sky view menu. Several controls appear
	across the bottom of the Filter menu 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 menu. The buttons labeled "All" and "Toggle All" allow you to
	easily change the state of all of the filter types.

	For reference, the Filter menu 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.

	The two scales across the top of the Filter menu set the brightness
	range being displayed. Only objects which are currently within the
	selected range will be shown on the display. Note that trails and
	persistent labels are not subject to magnitude limits.

@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 horizon the view will not be changed and a dialog will appear
    with a message suggesting the mode first be changed to RA-Dec.

    To locate any other object in the xephem database, please use the ObjX/Y
    menu accessible from the Main menu.

@Sky View - fifos
Fifos controls:

    Enable OUTFIFO:

	Whenever the sky view is redrawn and this toggle button is pushed in the
	coordinates of the center are sent to a file or fifo. The name of this
	fifo may be specified using the resource "XEphem.SKYOUTFIFO". The
	default name provided by the sample resource file and the fallback
	resources is "fifos/xephem_out_fifo". A leading `~' in the filename
	will get expanded to the value of your HOME environment variable.  The
	format of the record generated is as follows:

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

	The RA/Dec values are in radians and are with respect to the given
	epoch, which is specified in decimal years. Southern declination is
	negative. The epoch will be the same as that shown in the Main menu.
	The values are geocentric if the current display mode is RA/Dec; or
	topocentric if the current display mode is Alt/Az.

    Enable INFIFO:

	If this toggle button is pushed in the central pointing direction of
	the display may be set from a fifo. The name of the fifo may be
	specified using the resource "XEphem.SKYINFIFO".  The default name
	provided by the sample resource file and the fallback resources is
	"fifos/xephem_in_fifo".  A leading `~' in the filename will get
	expanded to the value of your HOME environment variable. The format of
	the record expected is as follows:

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

	The RA/Dec values should be geocentric, be specified in radians, and
	be for the specified epoch, which is specified in decimal years.
	Southern declination should be negative.

    Enable LOCFIFO:

	If this toggle button is pushed in when the cursor is within the central
	circle, the right button is depressed, and the "Send to LOCFIFO"
	control is depressed from the popup then the coordinates of the cursor
	are sent to a file or fifo. The fifo is opened and closed each time
	this selection is made.
    
	The name of the fifo is specified using the resource
	"XEphem.SKYLOCFIFO". The default name provided by the sample resource
	file and the fallback resources is "fifos/xephem_loc_fifo".  A leading
	`~' in the filename will get expanded to the value of your HOME
	environment variable.
    
	The format of the record sent to the fifo is as follows:

          RA:XX.XXXXXX Dec:XX.XXXXXX Epoch:XXXXX.XXX FOV:X.XXXXX Mag:XXX

	The RA/Dec values are in radians and are with respect to the given
	epoch, which is specified in decimal years. Southern declination is
	negative. The epoch will be the same as that shown in the Main menu.
	The values are geocentric if the current display mode is RA/Dec; or
	topocentric if the current display mode is Alt/Az. FOV is the current
	field of view, in radians. MAG is the current limiting magnitude, to
	the nearest integer.

	REMINDER: if you are using the DBFIFO for return of database objects, be
	sure it is enabled in the Data Base menu, that a server process is
	running and connected to the two fifos, and the Filter... criteria are
	set to permit seeing the objects.

@Sky View - history
History controls;

The Sky View history facility maintains a list of up to 10 basic viewing
conditions. Any entry in the list may then be quickly reinstated by selecting
it from the list provided in the pulldown menu. The list is initialized with
one entry which describes the conditions of the Sky View as it first appears.

    Add:

	This button adds the current display mode, RA (or Azimuth), Dec (or
	Altitude) and Field-of-View to the Sky View history list.

    Delete All:

	This button removes all of the currently defined history items, after
	asking for a confirmation. This button is sensitive only if there
	is currently at least one entry in the list.

    Delete One:

	To delete one item from the history list, push this button once to turn
	on delete mode then pull down the History menu again and select the
	item to delete.

	Pushing this button again while in delete mode turns off delete mode
	and nothing is deleted.  Using any other feature of the History menu
	also turns off delete mode.

	While the menu is pulled down for deletion, this button and the history
	list are shown in reverse colors to emphasize that selecting an item
	from the history list will delete it, not reinstate it. This button is
	sensitive only if there is currently at least one entry in the list.

    The items in the bottom portion of the pulldown menu, if any, are the
    history of conditions. The information listed for each is which display
    mode (Alt-Az or RA-Dec), the RA (or Altitude), Dec (or Azimuth) and the
    field of view. The values are printed as they appear in the corresponding
    scale controls. To return Sky view to a particular history entry, either
    select it from the list with the mouse or type the accelerator indicted to
    the right of the entry.

@Sky View - scales
Scale controls:

    FOV:

	The left vertically-oriented scale controls the field-of-view of the
	display circle. This can be varied from 0.1 through 180 degrees.

    Alt / Dec:

	The right vertically-oriented scale displays and controls one of two
	axes that defines the direction in which the display points. In Alt-Az
	mode this controls altitude and can be varied from 0 to 90 degrees. In
	RA-Dec mode this controls Declination and can be varied from -90 to +90.

    Az / RA:

	The bottom horizontally-oriented scale displays and controls one of two
	axes that defines the direction in which the display points. In Alt-Az
	mode this controls azimuth and can be varied from 0 to 359 degrees. 
	Azimuth 0 is north and increases eastward. In RA-Dec mode this controls
	Right Ascension and can be varied from 0 to 23.99 hours.

@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 dialog
to select the interval, number of steps, formatting details and which steps you
would like annotated. The trail setup dialog 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.

[Note to previous users of xephem: The method of creating sky trails based
on Main menu time Updates using N Steps and Steps is no longer supported.]

The trail is created by computing the location of the object at several
intervals.  Each new location will be drawn with a tick 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 menu 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.

Note that in Alt-Az mode, if an object goes below the horizon the line segments
and tick marks of the trail are displayed but they are not pickable and names
are not drawn.  Also, trail information is not subject to filtering.
@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.

@Solsys - mouse
Any feature 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. The RA/Dec given for the Earth is
that of the sun.  All RA/Dec info displayed is for the epoch as it was set
on the Main menu when the dot was computed.

@Solsys - control
Control options:

    Save...

	This selection allows creating a postscript file of the current Solar
	System view.

    Print...

	This selection allows printing the current Solar System view.

    Movie Demo:

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

    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 visual 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 menu
	is on, it will reappear when the Solar System menu is reactivated.

@Solsys - view
View options:

    Create Trails...

        This button will bring up a dialog to set up making a trail for each
	solar system 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 menu while
	the Trails option is off.
	
	See the Help from the trail setup dialog itself for more details on how
	it operates.

    Trails:

	This toggles whether trails, if currently defined, are displayed. 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 menu if this
	option is off.

    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.

    Names:

	This option causes each object's name to appear.

    Legs:

	This toggle button controls whether a line is drawn from each
	object to the ecliptic. This aids in visualizing the 3D location of the
	objects.

@Solsys - objects
Objects:

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

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

@Database - intro
This menu allows you to manage the collection of objects that are currently in
memory. These objects form what is referred to as the xephem database.

The top half of the dialog displays a count of each major type of object in
the database. The counts do not include the planets, sun or moon.

The lower half allows you to browse the directory structure on your system for
database files in xephem format and read them into memory. By convention, the
names of these files end with .edb.

A database file may be read in and added to the current database by selecting
the file then pressing Append them from the File Selection Box towards the
bottom of the menu. A file may also be appended by double-clicking its name in
the right-hand column. The default file directory is the edb directory and the
default pattern is *.edb.  These values may be changed as desired using the
XEphem.DBdirectory and XEphem.DBpattern X resources; see the sample XEphem.ad
for an example.

The Filter control in the lower right forces the current directory to be
rescanned for all files which match the filter pattern.

Xephem may also read objects from another process via a fifo. Please refer
to the description of this facility under the Controls help category.

@Database - control
Control:

    No dups:

	When this toggle is first activated, it scans all Fixed objects in
	memory searching for pairs which are separated by 1 arc second or less,
	and have the same class, magnitude and spectral type. If any are found,
	the object most recently added is deleted, although no object loaded
	prior to the current checkpoint is ever deleted. Then while this toggle
	remains active objects which are added, either by reading files or via
	the DBFIFO fifo, are also deleted according to these rules. When this
	toggle is off, no checks or requirements are imposed on new objects.
	
	Turning this feature on will increase the time to load new objects.

	This feature is particularly useful when reading objects from a remote
	process from which overlapping regions may be requested, such as the
	Hubble GSC.

	In no case are the user-defined objects, OBJX and OBJY, ever rejected
	regardless of their positions. Checking for duplicates is never
	performed until this menu has been opened at least once.

    Open DBFIFO:

	When pressed, this button tells xephem to listen for database objects
	arriving via a fifo from another process. Xephem attempts to reopen the
	fifo each time the "Open DBFIFO" button is pressed.

	The file name of this fifo is contained in the X resource named
	"XEphem.DBFIFO". The default name provided by the sample resource file
	and the fallback resources is "fifos/xephem_db_fifo". A leading `~' in
	the filename will get expanded to the value of your HOME environment
	variable. 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.

    Close:

	Closes the Data Base dialog.

@Database - delete
Delete:

These controls are used to delete all or some of the objects in memory.

A checkpoint may be set at any time to mark the set of objects currently in
memory. Special features are provided to avoid deleting these marked objects.
Checkpointing is handy when repeatedly adding and deleting highly detailed
lists of objects near a region of interest and yet retaining a broad list of
general objects. See the discussion of the SKYLOCFIFO in the Sky View menu for
an application of this related to receiving new objects from a
remote process.

    Set Checkpoint:

	Tag each object currently in memory.

    Clear Checkpoint:

	Clear the tags set on objects in memory. If "No Dups" is active, then
	all duplicate objects are also discarded.

    Delete to Checkpoint:

	Delete all objects in memory which have not been tagged.

    Delete All:

	After asking for a confirmation, this deletes all objects in the xephem
	database memory (except the planets, sun and moon).

@Database - files
Follows is the description of the format of an xephem database file. On an
historical note, this format remains compatible with ephem, the character-based
ancestor of xephem, to the extent possible.

Note that the "Filter" menu accessible from the "Sky View" menu also includes
a list of the type codes for each object, for easy reference.

Each object occupies one line in the file. Fields are separated with 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. Objects may be in any order.

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

  1) month/day/year, where day may contain a trailing decimal portion.
    examples: 1/1/1993 and 1/1.234/1993
    NOTE: this is always the format of dates in database files, regardless of
    the current xephem run time Data format preference setting.

  2) a real-number, such as 1993.123.

The first two fields are always Name and Type. Remaining fields depend on the
form of the object's motion.

The Name field is the object's name.

The Type field always starts with a single letter designating the form of
the object's motion:
  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 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 in the next subfield:
      O, B, A, F, G, K, M, N, C, S

For other object types, the remaining fields are defined as follows:

fixed format:
       RA, hours
       Declination, degrees
       magnitude
       reference epoch, optional, assumed to be 2000 if absent
       s = angular size, arc seconds, optional

elliptical format (e < 1):
       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 = magnitude model; select which by preceding the first field

hyperbolic format (e > 1):
       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 = magnitude model
       s = angular size at 1 AU, arc seconds, optional

parabolic format (e == 1):
       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 model
       s = angular size at 1 AU, arc seconds, optional

Earth satellite format:
      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
@Database - notes

The xephem distribution kit includes several database files that contain more
than 15,000 objects of all types.

Also, the entire Smithsonian Astrophysical Observatory list of some 259,000
stars is available in xephem format on ftp://iraf.noao.edu/contrib/xephem/SAO/.
The list has been sorted into ten sky regions. There is one file per region.
The entire set is some 11MB. 

Also, the complete Hubble Guide Star Catalog is available on CD-ROM and, using
the auxiliary process gscdbd, xephem may also read any portion of this catalog
into memory (subject to available process memory). See the information in
gscdbd directory for more details.

Xephem also ships with several awk 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
Xephem supports two user-defined objects, denoted ObjX and ObjY. These may
be fixed objects; objects in elliptical, hyperbolic or parabolic heliocentric
orbits; or objects in geocentric elliptical orbits. The ObjX/Y dialog allows
you to define these objects.

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

The ObjX/Y menu is always displaying information from one or the other of
these working copies as indicated by the small radio box in the center of
the menu at the top. This box may also be used to changed whether ObjX or
ObjY 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 menu 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 dialog. A new
entry may be typed into the dialog box and applied by typing RETURN or
selecting the "Ok" button. The value may be left unchanged by selecting
"Cancel".

Along the right edge of the ObjX/Y menu is a list of each object currently
loaded into the xephem database. (See the Help for the "Data Base" menu 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 selection. 
If one of these objects is selected, then it is copied to the current working
object.  You may then further edit the values for this working object as
desired.

Below the list of names is a text field with which you may search for an
object by name. Enter a string and type RETURN 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 require 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 search for another match, leave the
string unchanged and just type RETURN 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
the real ObjX (or ObjY) used throughout the other functions of xephem. "Ok"
will do the same thing and also close the ObjX/Y menu.

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

Selecting "Sky Point" will move the center of the field of view on the "Sky
View" menu so that the current working object is centered and a cross-hair
is drawn over the object. This change in pointing direction and marking will
take place even if the object is not in the Sky View type filter or within
the magnitude range. Note that the Sky View display will _not_ be changed if
it is set to Alt-Az mode and the current working object is below the
horizon.

Selecting "Sky Mark" will draw a cross-hair on the Sky View menu at the
location of the current working object if it is within the Sky View field of
view. The Sky View menu is never reaimed with this command.

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 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 on the main
menu and the object information is redisplayed here on the ObjX/Y menu.
@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  = 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 xephem.edb
database file and the corresponding menu 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 xephem.edb database file and
the corresponding menu 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 = 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 = 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 sunlight.

@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 sunlight.
@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 menu allows you to search 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 main dialog. Also set other options via the Options menu. Then start
the search via the Go button in the Control menu.

When the search completes, all suitable pairs will appear in the scrolled list.
The magnitude and name of each object in the pair and their separation, to the
current precision, are listed. 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 search was performed is indicated in the time
stamp label below the list. There may be duplicates in the list if and only if
there are duplicates in the database (see the "No dups" option in the Data Base
dialog).

@Close Objects - control

Controls:

    Go:

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

    Auto Update:

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

    Sky Point:

	This will center the Sky View on the first object of the selected pair
	in the list. 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 dialog 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 dialog list.

    Close:
	
	This closes the Close Objects menu. 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). To make this the
	default, set the X resource: XEphem*CloseObjs*OmitFixedPairs.set: True

    Topocentric separation
    Geocentric separation
    
	Choose whether the separation is based on your current location
	(topocentric) or the center of the Earth (geocentric). When using
	topocentric separation objects which are currently below the horizon
	are not included. Note that using topocentric is particularly well
	suited for lunar occultations because of the large parallax effects of
	the close moon.

	To select a default, place one or the other of the following lines in
	your X resource file for XEphem:

	    XEphem*CloseObjs*True.set: True
	    XEphem*CloseObjs*Geo.set: True

@Close Objects - misc
Algorithm:

    The sky dome is broken into bands of constant Dec (or Alt) 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 (or Az). 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.

    Let N be the number of candidate objects, and B the number of bands. B is
    computed as ceil(180/separation). The dealing of the database objects into
    their bands takes O(N) time and requires O(N+B) memory. The sort time for
    each band, on average, is O(N(log(N/B)). Scanning each band can take as
    long as O(N**2) but this should be very rare due to the cutoff scan
    technique. The final list preparation require an additional sort, whose
    time and memory depend on the number of pairs found.

    In general, very small separations tend to require excessive overhead while
    large separations cause long sort times. The program enforces, quite
    arbitrarily, a lower limit of 0.1 for the separation. In practice, values
    from .5 to 1.5 seem to work best. A lower limit results in no loss of
    functionality since all smaller separations are, of course, still in the
    resulting list.

@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.
This scale may be initialized via the X resource XEphem*Saturn*LimMag.value.

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

@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:

    Send to LOCFIFO:

	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. It is
	expected that a server process is listening to this fifo and that it
	will subsequently emit lists of objects near Saturn back to xephem
	via DBFIFO. Thus, if the "Sky background" Option is also enabled, this
	option will cause background objects near Saturn to be loaded and
	hence displayed.

	Be sure that xephem is listening to DBFIFO. This is controlled in
	the Data Base menu.

	This mechanism is the same as that provided within the Sky view. Please
	refer to its help on the "Enable LOCFIFO" Fifo control and the "Send to
	LOCFIFO" popup for further details.
    
	The name of the fifo is specified using the X resource
	"XEphem.SKYLOCFIFO". The default name provided by the sample resource
	file and the fallback resources is "fifos/xephem_loc_fifo".  A leading
	`~' in the filename will get expanded to the value of your HOME
	environment variable.

    Movie Demo:

	This option will set up the Main menu time step controls 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 dialog
	if present, from the screen.

@Saturn - view
View Options:

    Sky background:

	Selects whether to also show objects within the current field of view
	that are in the xephem database memory. 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.

    Tags:

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

    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.

    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 dialog which contains quantitative
	information about Saturn's moons and its rings. All values may be used
	in plotting, listing and searching.
	
	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 Saturn equatorial plane. The next two columns
	give the RA and Dec location of the moons in the current epoch (as 
	specified on the Main menu).
	
	Note: Xephem does not allow for precession of the axis of Saturn
	rotation so the RA and Dec values will gradually degrade over time.
	The axis is specified as the constants POLE_RA and POLE_DEC in
	satmenu.c if you would like to update them.

@Jupiter
+Jupiter - intro
+Jupiter - mouse
+Jupiter - control
+Jupiter - view
@Jupiter - intro
This is a schematic view of Jupiter, the Galilean moons and the Great Red Spot
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. This scale may
be initialized via the X resource XEphem*Jupiter*LimMag.value.

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

The default longitude of the GRS is set to 42 degrees. This may be changed
by setting a different value in the X resource XEphem.JupiterGRSLongitude.

@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:

    Send to LOCFIFO:

	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. It is
	expected that a server process is listening to this fifo and that it
	will subsequently emit lists of objects near Jupiter back to xephem
	via DBFIFO. Thus, if the "Sky background" Option is also enabled, this
	option will cause background objects near Jupiter to be loaded and
	hence displayed.

	Be sure that xephem is listening to DBFIFO. This is controlled in
	the Data Base menu.

	This mechanism is the same as that provided within the Sky view. Please
	refer to its help on the "Enable LOCFIFO" Fifo control and the "Send to
	LOCFIFO" popup for further details.
    
	The name of the fifo is specified using the X resource
	"XEphem.SKYLOCFIFO". The default name provided by the sample resource
	file and the fallback resources is "fifos/xephem_loc_fifo".  A leading
	`~' in the filename will get expanded to the value of your HOME
	environment variable.

    Movie Demo:

	This option will set up the Main menu time step controls 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 dialog
	if present, from the screen.

@Jupiter - view
View Options:

    Sky background:

	Selects whether to also show objects within the current field of view
	that are in the xephem database memory. 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.

    Tags:

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

    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.

    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 dialog which contains quantitative
	information about Jupiter's moons and central meridian longitude. All
	values may be used in plotting, listing and searching.
	
	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 Jupiter equatorial plane. The next two columns
	give the RA and Dec location of the moons in the current epoch (as 
	specified on the Main menu).
	
	Note: Xephem does not allow for precession of the axis of Jupiter
	rotation so the RA and Dec values will gradually degrade over time.
	The axis is specified as the constants POLE_RA and POLE_DEC in
	jupmenu.c if you would like to update them.

@Trails
This dialog 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 tick mark.

	The radio box in the upper left corner provides several strategies for
	placing the time stamps near each tick 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 ok to specify more than 24 hours to achieve intervals
	of several days. It is also ok to specify negative values to run time
	backwards.

    Time stamp:
    
        This choice determines which intervals will to be time-stamped.
	
	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).

    Size:

	This choice sets the size of the annotation text.

	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 typing the desired number into the space provided
	near the bottom of the dialog.

Once the choices are set up as desired, Ok will create the trail and the
dialog will disappear. Apply will create the trail but the dialog will remain
up for further use. Close just dismisses the dialog 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 dialogs 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 do not need the CD-ROM for this example because the appropriate cache file
for the field is included with the xephem distribution kit). This example is
taken from Sky and Tel, July 1995, page 72.

    for convenience, use UTC for all time displays:
	Main->Preferences->Zone Display->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)->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->Objects->Data Base...
	    in lower right corner, double-click on "asteroids.edb"
		(could also 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->Objects->ObjX, ObjY
	in the lower right Search text field, type "hermi" then RETURN
	    (this finds 121 Hermione in memory and stages it to become ObjX)
	    (you may also search by scrolling through the list at right and
	     selecting the candidate object's button).
	load this into Object X and dismiss the dialog:
	    Ok

    display asteroid trail on sky view:
	Main->View->Sky View...
	    View->RA-Dec
	    Locate->121 Hermione
	    set Field of View to about 1.5 degrees using scale on left
	    View->Filter...
		set Faintest Magnitude to 16 using scale
		Ok
	    place cursor over the central dot (Hermione!) and press button 3:
		Create Trail...
		    Interval: 1 Day
		    Time stamp: Every 2
		    Format: Date
		    Number of tick marks: type "8"
		    Ok
	    center the trail by placing cursor near dot for 7/28/95 and press
	    button 3, then scroll down and release on:
		Point

    add nearby Hubble Guide Star Catalog entries:
	if you have not already done so, create the xephem fifos by going to
	    the "fifos" directory and typing "make";
	if you have not already done so, build the GSC database daemon by going
	    to the "gscdbd" directory and typing "make";
	if gscdbd is not already running, go to the gscdbd directory and start
	    it by typing "gscdbd".

	enable listening for database objects via the DBFIFO:
	    Data Base dialog->Control->Open DBFIFO

	enable sending mouse locations to LOCFIFO:
	    Sky View->Fifos->Enable LOCFIFO

	read in GSC objects near Hermione:
	    place cursor over any Hermione dot, press button 3->Send to LOCFIFO

    if desired, overlay with a coordinate grid:
	Sky View->View->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 for 241 Germania and getting a little old, 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->Zone Display->UTC

    set time to 17:25:00
	Main->UTC Time
	    enter 17:25:00 then Ok (or just RETURN).
	    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->Views->Earth...

    display the subsolar point of the moon, i.e., the point on the earth surface
        directly in line with the sun:

	earth->Object->Sun->Moon
	earth->Object->Show Object

	Note: after the Moon is selected, "Moon" is the label at the bottom of
	    the Object pulldown menu.
	A black cross should appear a little southwest of Hawaii. That is the
	    current center of totality.

    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.

    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->View->Alt-Az is selected to get topocentric
		view point.

    set up a movie showing the path of totality for the next two hours:
	Main->N Steps-> enter "24", then RETURN
	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 this year.

    Set the date to Jan 1 this year:
	Main->Local Date-> 1/1
	    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.

    Set the time to local midnight:
	Main->Local Time-> enter 0:0:0

    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 RiseTm 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 dialog:
	Main->Control->Plot...

    define a plot with four independent traces:
	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 menu be filled in as you define the variables to plot).

	Main->Local Date
	Main->Dawn

	Main->Local Date
	Data->Sun.RiseTm

	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 menu should look
	like this:

	    Tag		X	   Y
	    A		LD	  Dawn
	    B		LD	Sun.RiseTm
	    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 180 days, i.e., span about
    one year:

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

    Define a file to contain the plot values:

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

    Start capturing xephem plot data to the plot file:

	Plot->Plot to fileo
    
    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.

    When it stops, display the year of plot data:

	Plot->Show plot file

	Note how the Plot->Plot to file option is automatically disabled. If
	xephem was built on a POSIX-compliant system with ANSI C, you should
	see local timezone changes, as appropriate, as discontinuities in the
	plot.

    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 search 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->Zone Display->UTC

    Set the date to Jan 1 this year:

	Main->Local Date-> 1/1
	    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.

    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 dialog:

	Main->Control->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: work/rings.plt
	Plot->Title: Saturn Earth Ring Tilt for 1995

    Enable plot file capture:

	Plot->Plot to file

    Accumulate 180 steps, each 2 days:

	Main->N Steps 		enter "180" then RETURN
	Main->Step		enter "2d" then RETURN
	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 May:

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

    Open the search control dialog, set up to solve for when the earth ring
    tilt goes to zero:

	Main->Control->Search...
	    Search->Enable field buttons	// turn on
		Saturn info->From Earth
	    Search->Enable field buttons	// turn off
	    Search->Compile
	    Search->Find 0
	    Search->Searching is Active
    
    And go:

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

    The Main menu 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 menu.

    Set time to midnight tonight:

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

    Load up more than just the basic.edb set:

	Main->Objects->Data Base...
	    Data Base->asteroids.edb	// some 5000 asteroids 
	    Data Base->Append
	    Data Base->ngc.edb		// RNGC objects
	    Data Base->Append
	    Data Base->sac.edb		// even more deep-sky objects
	    Data Base->Append

    Bring up the sky view:

	Main->View->Sky View...

    Explore around using mouse pointing and/or sliding field-of-view and
    pointing controls as desired.
    
    Now let's focus in on some close encounters. Let's tighten up the field
    and increase the limiting magnitude so we can see faint things:

	Sky View->FOV->  slide to 2.0
	Sky View->View->Filter...
	    Faintest Magnitude->  slide to 14
	    Ok
	Sky View->View->All labels
	Sky View->View->RA-Dec

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

	Main->Objects->Close Objs...
	    Close->Max sep->    enter 1.0
	    Close->Mag limit->  enter, say, 13
	    Close->Options->Omit fixed pairs	// if not already on
	    Close->Options->Topocentric		// 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
    item 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 dialog:

	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->View->RA-Dec is set.
    As usual, you can click on any of the tick marks with the mouse button 3
    to get the circumstances of the asteroid at the various moments in time.
    You can change the trail parameters by using "Change Trail..." as before.

    With luck, you'll have a pretty appulse to watch. To make a permanent
    record, make a file of objects in the Sky view:

	Sky View->Control->List to file...

    Or use general X Windows tools such as xwd or xv to save and print the Sky
    View.
@Example - lunar occultation
This example was taken from the lunar occultation of Spica (Alpha Vir) which
occured January 23, 1995, UTC, as reported in Sky and Telescope, January 1995.

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

	Main->Objects->Data Base...
	    basic.edb
	    Append
	    Control->Close

    Set UTC Zone preferences:

	Main->Preferences->UTC

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

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

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

	Main-><Site>
	    type "Chicago" into the text field,
	    hit RETURN,
	    select Ok

	    or

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

    Display the moon and watch the reappearance of Spica:

	Main->View->Moon..

	Spica is just ready to emerge from the dark Northeastern limb.
	Press Main->Update to advance the time by 1 minute. Spica appears at
	11:44, within a minute of the published value, and near the craters
	depicted in the schematic on page 83.
