1 XEPHEM 
An interactive astronomical ephemeris for X

Syntax:

 $ xephem

2 Description
Xephem version 2.7.1 is an interactive astronomical ephemeris program for 
X Windows systems. It ...

    o
computes heliocentric, geocentric and topocentric information for
celestial objects;
    o
has built-in support for all planets; the moons of Jupiter, Saturn and
Earth; and Mars' central meridian longitude;
    o
supports user-defined objects in heliocentric or Earth orbit;
    o
comes with sample databases of over 20,000 objects in the release kit;
    o
can access the Hubble Guide Star Catalog from CD-ROM using gscdbd;
    o
can quickly locate all pairs of objects which are closer than a specified
maximum;
    o
displays data in configurable tabular forms and in several detailed
graphical formats;
    o
can plot and list all data fields to disk files;
    o
can be programmed to search for arbitrary circumstances;
    o
can serve as the control point for robot telescopes in real-time via
named streams pipes (UNIX fifos).

2 Getting Started
Xephem contains extensive context-sensitive on-line help. Virtually none of
that help is duplicated here so go ahead and run xephem to learn more.
In order for xephem to find this help text the resource XEphem.HELPFILE
must be set properly. If you are running xephem
from the source directory of the distribution kit this should be set to
auxil/xephem.hlp.

When you first run xephem you may hear a beep.
This means xephem has added a message to the message box menu.
This menu is not shown by default.

Whether the message box is displayed may be toggled by using the Messages
entry in the File pulldown menu off the Main menu.
Whether xephem beeps when it adds a message may be toggled using the
Message Bell option in the Preferences pulldown menu.

2 Quick Menu Tour
The Help pulldown at the top right of the main menu provides access to 
several categories of assistance applicable to the overall operation of 
xephem. Those unfamiliar with xephem might begin by reading the 
Introduction help section first and reading the additional help information 
in the order in which it is listed in the pulldown Examples
for several useful operations are now included as well.

The Main menu of xephem provides control and display of three basic
services: observing circumstances, looping, and access to additional
displays.

Observing circumstances includes location, time and atmospheric
conditions (used for the refraction model). Looping refers to the
ability to set up xephem so that it automatically increments time at a
desired step size and rate.

Additional displays provide all of the tabular and graphical information
available, and always refer to the circumstances defined in the main
menu. These additional displays are activated from the  Views pulldown.

Xephem has information about the Solar system built in and can be
accessed without the need to access an external database. 

Xephem can read files of additional objects into memory as well.
Database files are read in using the Data Base button in the Objects
pulldown or via the DBFIFO fifo (see the Help for the Data Base menu for
more details on formats and the fifo). All of the information about each
object in memory may be inspected and manipulated in detail and assigned
to so-called `user defined objects' X and Y using the ObjX, ObjY button
in the same pulldown.

All of the data that  xephem presents in numeric form may be written to
a file and later plotted; written to a file as a tabular listing; or
used to formulate an arbitrary mathematical expression that may be
solved for a maximum, minimum or zero. These facilities are accessed
from the Control pulldown.

Several options related to performance and display formatting may be
controlled from the Preferences pulldown.

The Files pulldown in the main menu allows one to reset the main menu
from the initial resource settings; toggle whether the general messages
menu is displayed; and quit the program. 

2 X_Resources 

Xephem has many X resources, some of which you will soon want to tune to
your taste and circumstances; many others may be left unchanged. Look
through the XEphem.ad sample distribution for full details. If no
resources are available

xephem contains internal fallback resources that are suitable for a
black-and-white X terminal.

Of course, in addition to all the custom resources, xephem supports the
usual Xt command line arguments such as -display, -xrm, -synchronous,
-fg and -bg.

The application class of xephem is XEphem.

A list of widgets in xephem would be enormous. If you really want such a
list, build xephem to use the editres protocol then inspect the widget
hierarchy using the standard X tool editres. The necessary code to
support the editres protocol is already in xephem.c surrounded by #ifdef
WANT_EDITRES.

2 Time_zones

If __STDC__ was defined by the compiler when xephem was compiled and at
runtime the gmtime() ANSI C function returns non-NULL, then xephem will
attempt to support time zone control. The time zone name and offset is
obtained from the operating system whenever the "Now" option is used
from the various Main menu time fields or resources or at each time step
if Auto Time Zone mode is in effect. Otherwise, xephem never attempts to
automatically change the time zone name or offset. In any case, the time
zone offset and name may always be set manually at any time from the
Main menu, or they may be initialized from the XEphem.TZName and
XEphem.TZone resources, respectively.

2 Files_and_Fifos
 
Xephem can use and create several files and communicate via several
fifos. The following table lists the name of the defining resource, the
default value and a short description of each. Full details for each may
be found in the appropriate run-time Help available from within xephem.

Also look in the sample application defaults file,  XEphem.ad, for
examples of settings these and many other resources. The initial default
settings define everything relative to the source tree directory of the
xephem distribution kit. Many file names may begin with tilde (~) to
refer to the user's HOME directory.

X Resource Name          Default                Usage
---------------          -------                -----
List*Filename.value      work/ephem.lst         Listing file
Plot*Filename.value      work/ephem.plt         Plot file
DBFIFO                   fifos/xephem_db_fifo   auto database input
DBdirectory              edb                    database directory
DBinitialFiles           basic.edb              db files auto loaded
DBpattern                *.edb                  datebase file pattern
HELPFILE                 auxil/xephem.hlp       Help text
SITESFILE                auxil/xephem_sites     Earth view sites
SKYINFIFO                fifos/xephem_in_fifo   Sky View aim input
SKYLOCFIFO               fifos/xephem_loc_fifo  Sky View Button2 report
SKYOUTFIFO               fifos/xephem_out_fifo  Sky View re-aim output

2 Author
 
Elwood Downey, ecdowney@noao.edu. Although they graciously provide me
with email and other services, neither I nor xephem are associated in
any way with the National Optical Astronomical Observatory. 

2 References 

Ephem is the ancestor of xephem. It is suitable for "dumb"
24x80 character displays, including VMS and DOS as well as UNIX. The
latest version may be found on at
ftp://iraf.noao.edu/contrib/xephem/ephem.
 
The latest version of Xephem is maintained at
ftp://iraf.noao.edu/contrib/xephem.

Source code, the SAO catalog and several sample executables are also
available near that address. A WWW page is also available at
http://iraf.noao.edu/~ecdowney/xephem.
 
The online Help entry on Credits lists some of the many texts,
individuals and organizations that have contributed to xephem.
