Welcome to xephem v2.5:

Xephem is an interactive astronomical ephemeris program for X Windows/Motif
systems.  It computes heliocentric, geocentric and topocentric information
for celestial objects. Xephem has built-in support for all planets; the moons of
Jupiter, Saturn and Earth; and Mars' central meridian longitude. Xephem also
supports any objects in heliocentric or Earth orbit given the appropriate
elements. A sample database of some 16000+ objects is included in the release
kit. Xephem generates data in configurable tabular forms and in graphical
schematic views.  Xephem can plot and list all data fields and can be
programmed to search for arbitrary circumstances.

XEphem requires at least X11R4 and OSF/Motif 1.1. Xephem has been built on
many UNIX systems as well as VMS. See the list of known ported systems and
building hints, below.

There is only a small manual, but there is extensive on-line help. So, the
first thing to do is to build xephem - see next - then start selecting the Help
buttons.

Building xephem:

    Building xephem is intended to be straightforward. There is nothing to
    configure in the way of options or the like. Everything is in .c and
    .h files in one directory. Just compile everything with the Motif include
    files and link it with the X and Motif libraries as you would any Motif
    application; don't forget the math library, -lm. (If you are on VMS, there
    is a sample DCL file to build xephem on VMS/DECWindows MOTIF at the end of
    this file.)
    
    If your system is fully set up for using xmkmf, including Motif, then
    try the Imakefile by just typing:

	xmkmf
	make

    There is also a Makefile.smple, which is what I use. If you use this,
    edit and uncomment the group of flags and libraries that looks close to the
    way Motif programs are built on your system. The sample Makefile.smple
    leaves all the results in the current directory so you'll want to put the
    executable (xephem), man page (xephem.1) and app defaults file (call it
    XEphem) where you want them, by hand. 

    Here are some additional hints about the Makefile.smple:

    On systems without ANSI C compilers compile with -D_NO_PROTO.

    On older USL/AT&T systems (such as SVR3.2) compile with -DSYSV.

    If you get regcmp undefined from libXm on SVR4.2 add "-lgen" to LIBS.

    On SPARC systems, if your get dlopen/dlsym/dlclose undefined try fiddling
    with whether you use static or dynamic libs; best luck seems to be with
    using all dynamic libs. It appears these three functions are never called,
    however, since I can `chmod +x xephem' and it seems to run ok.

    I've not had good luck with gcc's math. I know that at least one version
    I used on a SPARC recently caused the precession algorithm to go badly
    astray.

    I have searched carefully through the output of running all of xephem
    through lint and gcc on Ultrix and SVR4 and can rationalize all the
    warnings, so don't let these bother you too much.

    Avoid Motif 1.2.0; I know 1.2.2 works ok.

Summary of files to install:

    xephem: executable; put where you want locally installed X programs.
    xephem.hlp: help file; point at it with the XEphem.HELPFILE resource.
    ephem.db: sample astronomical database; point at it with the
	XEphem*DBPromptD.textString resource.
    xephem_sites: sample Earth sites file; point at it with the
	XEphem.SITESFILE resource.
    xephem.man: nroff source for manual; process the output with something like
	"nroff -man xephem.man" and place either/both where you want man pages
	for locally installed X programs.
    XEphem.ad: sample resource file; name it XEphem and place it where you
	want application default resources for locally installed X programs.

Running xephem:

    There are fallback resources included in the main program all set for 
    xephem to run in the directory in which it was built and to work
    on monochrome systems so don't worry about putting the resource file,
    XEphem.ad, anywhere for now. Another way to run on a black and white
    display is to use the command line arguments: "-fg white -bg black".

    Go ahead and start xephem by just typing it's name: `xephem'.

    The best way to learn xephem is to start selecting things and read some of
    the Help entries. A good order to read them is the way they are listed in
    the Help pulldown off the main menu.  Soon, you will want to edit and
    install the XEphem.ad resources file entries that contain location
    information and a few other things. Read the default resource file,
    XEphem.ad, and follow the notes in there.

Possible X compatibility problem:

    Xephem's Sky View and Solar System menus do not work using X11R4 twm with
    X11R4 X. The symptom is that when these views are selected an X error
    occurs as follows:

	X Error of failed request:  BadAccess 
	Major opcode of failed request:  28 (X_GrabButton)
	Minor opcode of failed request:  0

    The problem seems to be that R4 twm does a permanent XGrabButton if
    Button3 is bound to anything in .twmrc and this conflicts with the popups
    defined in these dialogs, which also try to use button 3. The work-around
    seems to be to remove any bindings to Button3 in your .twmrc file.

    This does not occur using X11R5 twm with either X11R4 X or X11R5 X nor
    does it occur running mwm with either X11R4 X or X11R5 X.

xephem v2.4e was known to run on the following systems; check with the author
for availability of statically linked binary executables and for assistance
with porting.

    OS                      CPU                     X
    -----------             ---------------         ---------------------------
    SVR3.2/Venix            i486                    Metrolink X11R4/Motif 1.1.3
    SVR4.0.3/Consensys      i486                    MIT X11R5/Motif 1.1.4, 1.2.2
    Ultrix 4.2              DECstation 5000         DEC's (?)
    SunOS 4.1.2             Sun 4c                  TeleUSE development system*
    hpux 8.07               HP 9000/720             X11R4, Motif 1.1.?
    IRIX 4.0.5              SGI                     X11R4
    OSF/1 1.2               DEC Alpha               X11R5, Motif 1.1.3
    AIXv3.2                 IBM RS/6000             AIXwindows
    VMS                     VAX                     DECwindows
    SCO v3.2                i486                    ODT 2.0
    Linux                   i486                    MetroLink

*  requires Sun's X server patch 100444-35.


If you would like to gut xephem for just its astronomical functionality, start
with obj_cir(). This is basically the dividing line between the user interface
and the astronomical functions. Also, the following files are pretty much just
pure transliterations from BASIC into C from machine-readable copies of the
programs in Duffett-Smith's book.  They have nothing to do with the rest of
ephem so they may be used for completely different applications if so desired.

    aa_hadec.c anomaly.c astro.h cal_mjd.c comet.c eq_ecl.c moon.c moonnf.c
    nutation.c obliq.c parallax.c pelement.c plans.c reduce.c refract.c
    sex_dec.c sun.c utc_gst.c

The sample database, ephem.db:

    This is a sample collection of astroids, stars and deep-sky objects to
    get you started. References, when I had them, are included in the file.

    There are a few sample earth satellites, STS-58-4 and STS-60-3 (the
    prelaunch elements for shuttle flights STS-58 and STS-60), to use as 
    examples with this new feature.

    This database is compatible with ephem v4.28 EXCEPT that ephem requires
    entries to start with an alpha character. Either add one to all such
    entries in this db or modify the function nxt_db() to allow a leading digit
    as well (isn't having source nice?). And, of course, ephem does not support
    the earth satellite object type, E.
    
    Asteroids are given by their common name, if it has been assigned, followed
    by their numeric sequence number. Those that do not yet have a common
    name assigned are given by sequence number followed by year and designation
    of discovery. The list goes to 4848.

    The stars are from the Yale Bright star catalogue. Only those entries with
    at least a constellation name and either a common name or some sort of
    designator are included. Bayer designations are given as the Greek letter
    spelled out (I know -- I could have used Greek letters in X but that would
    break compatability with ephem).

    The deep-sky entries are from the Saguaro Astronomy Club database Version
    5.0. The Messier objects are entered twice; once by M number and once
    by NGC number. This makes it possible to find them by either name, but
    causes both labels to appear and overlap when "All labels" is used in
    the Sky view display; you are free to remove either name as you wish.
    Some objects in the SAC database do not have well-accepted magnitudes.
    These entries are included but have special magnitude values of 99.9 or
    79.9; 99.9 means no magnitude was available and 79.9 applies to dark
    nebulae.

    Work on the database is a project in itself. Authoritative contributions
    welcome.

    I have worked up several awk scripts to convert various database formats
    files into ephem format. Contact the author if you need one or have one.
    The distribution kit does contain one, nasa2xdb.awk, for converting the
    NASA "2-line" earth satellite format into xephem format. See the Help
    on Credits from the Main menu for how to get timely shuttle elements.

    Finally, I have the entire SAO database from NSSDC broken down it into 10
    files in ephem format. There are total of 258,997 entries. The complete
    set is 11,332,256 bytes, 3,034,691 compressed. Look on ftp.x.org in
    contrib/xephem.

Please tell me what you think of xephem, good and bad. If you drop me a quick
note I will save your email address and directly send you announcements of
changes.

Thank you for your interest in xephem.

Elwood Downey
419 36th Street NE
Cedar Rapids, IA USA 52402-6119

ecdowney@noao.edu

December, 1993

PS:

I do not have access to VMS/DECwindows but the following DCL file, courtesy
fisica@astrpd.DNET.NASA.GOV (Max Calvani - Italy) should build xephem for
VMS/DECwindows MOTIF. In addition, drucker@Csa2.LBL.Gov (Bob Drucker,
Berkeley/LBL) writes:

    For VMS users the default settings file can be pointed to in one of
    two ways.  The default name for the resource file on VMS is
    SYS$LOGIN:DECW$XDEFAULTS.DAT.  If you don't wish to use this
    you can define the logical XENVIRONMENT to point to the file (this
    allows you to keep the file anywhere you want with any name).

$!
$!	Makefile.com -- Command file to compile and link Xephem
$!
$!	A simple minded command file to compile and link Xephem under VAX/VMS
$!	and DECwindows MOTIF 
$!
$!      when            who                     what
$!
$!      2-feb-1992      Ethan VanMatre          original from unix makefile
$!      13-mar-1993	Max Calvani		updated for xephem v2.4.
$!      9-sep-1993	Elwood Downey		updated for xephem v2.5.
$!
$ set ver
$ cc	aa_hadec/opt/obj
$ cc	anomaly	/opt/obj
$ cc	cal_mjd	/opt/obj
$ cc	calmenu	/opt/obj
$ cc	circum	/opt/obj
$ cc	comet	/opt/obj
$ cc	compiler/opt/obj
$ cc	constel	/opt/obj
$ cc	datamenu/opt/obj
$ cc	db      /opt/obj
$ cc	dbmenu  /opt/obj
$ cc	earthmap/opt/obj
$ cc	earthmenu/opt/obj
$ cc	earthsat/opt/obj
$ cc	eq_ecl	/opt/obj
$ cc	formats	/opt/obj
$ cc	helpmenu/opt/obj
$ cc	jupmenu	/opt/obj
$ cc	libration/opt/obj
$ cc	listmenu/opt/obj
$ cc	mainmenu/opt/obj
$ cc	marsmenu/opt/obj
$ cc    marsmap/opt/obj
$ cc	misc    /opt/obj
$ cc	moon	/opt/obj
$ cc	moonmenu/opt/obj
$ cc	moonnf	/opt/obj
$ cc	msgmenu /opt/obj
$ cc	nutation/opt/obj
$ cc	objmenu	/opt/obj
$ cc	obliq	/opt/obj
$ cc	parallax/opt/obj
$ cc	pelement/opt/obj
$ cc	plans	/opt/obj
$ cc	plot_aux/opt/obj
$ cc	plotmenu/opt/obj
$ cc	precess	/opt/obj
$ cc    preferences/opt/obj
$ cc	query	/opt/obj
$ cc	reduce	/opt/obj
$ cc	refract	/opt/obj
$ cc	riset	/opt/obj
$ cc	riset_cir/opt/obj
$ cc	satmenu	/opt/obj
$ cc	sex_dec	/opt/obj
$ cc	skyfiltmenu/opt/obj
$ cc	skyviewmenu/opt/obj
$ cc	solsysmenu/opt/obj
$ cc	srchmenu/opt/obj
$ cc	sun	/opt/obj
$ cc	time	/opt/obj
$ cc	utc_gst	/opt/obj
$ cc	versionmenu/opt/obj
$ cc	xephem	/opt/obj
$!
$ LINK	xephem.obj,	-
	aa_hadec.obj,	-
	anomaly.obj,	-
	cal_mjd.obj,	-
	calmenu.obj,	-
	circum.obj,	-
	comet.obj,	-
	compiler.obj,	-
	constel.obj,	-
	datamenu.obj,	-
	db.obj,	-
	dbmenu.obj,	-
	earthmap.obj,	-
	earthmenu.obj,	-
	earthsat.obj,	-
	eq_ecl.obj,	-
	formats.obj,	-
	helpmenu.obj,	-
	jupmenu.obj,	-
	libration.obj,	-
	listmenu.obj,	-
	mainmenu.obj,	-
	marsmenu.obj,	-
        marsmap.obj,    -
	misc.obj,	-
	moon.obj,	-
	moonmenu.obj,	-
	moonnf.obj,	-
	msgmenu.obj,	-
	nutation.obj,	-
	objmenu.obj,	-
	obliq.obj,	-
	parallax.obj,	-
	pelement.obj,	-
	plans.obj,	-
	plot_aux.obj,	-
	plotmenu.obj,	-
	precess.obj,	-
        preferences.obj, -
	query.obj,	-
	reduce.obj,	-
	refract.obj,	-
	riset.obj,	-
	riset_cir.obj,	-
	satmenu.obj,	-
	sex_dec.obj,	-
	skyfiltmenu.obj,	-
	skyviewmenu.obj,	-
	solsysmenu.obj,	-
	srchmenu.obj,	-
	sun.obj,	-
	time.obj,	-
	utc_gst.obj,	-
	versionmenu.obj,	-
	sys$input/opt
sys$share:decw$dxmlibshr/share
sys$share:decw$xmlibshr/share
sys$share:decw$xlibshr/share
sys$share:vaxcrtl/share
$!
$!clean:
$	purge
$!
$ set nover
