-*- mode:outline -*-
* Introduction to XEmacs Packages
=================================

As of XEmacs 20.5, XEmacs is no longer distributed in a large
monolithic distribution.  The distribution has been broken up into
separate units called packages.  In the general case, one may install
and uninstall various packages freely without having to modify the
XEmacs binary.  This gives an installer the ability to tailor an
XEmacs installation for local needs with safe removal of unnecessary
code.

There are two main flavors of packages.

** Regular Packages
===================

A regular package is one in which multiple files are involved and one
may not in general safely remove any of them.

** Single-File Packages
=======================

A single-file package is an aggregate collection of thematically
related but otherwise independent lisp files.  These files are bundled 
together for download convenience and individual files may deleted at
will without any loss of functionality.

* Package mechanics
===================

This section describes how package hierarchy directories are put
together and how they may be configured into XEmacs.

** Package Path
===============

For backwards compatibility and for ease of transition to XEmacs
20.5+, it is possible to use previous XEmacs installations as package
directories.  Specify something like
--package-path="~/.xemacs::/usr/local/lib/xemacs-20.3" to configure
when building.  You will have extra messages at dump time relating to
lisp shadows which you may ignore.  The magical null directory `::' is 
a marker indicating where Lisp bundled with the running XEmacs gets
put into the load path.  By specifing the older directories after the
current one, the newer lisp overrides the older lisp.

** The anatomy of an XEmacs Package hierarchy
=============================================

An XEmacs package is laid out just like a normal installed XEmacs lisp
directory.  It may have lisp, etc, info, and lib-src subdirectories.
These directories get added at XEmacs startup to whatever directories
it was already using.

There may be any number of Package hierarchy directories.

* Package Distributions
=======================

XEmacs lisp packages are distributed in two ways depending on the
intended use.  Binary Packages are for installers and end-users and
may be installed directly into an XEmacs package directory.  Source
Packages are for developers and include all files necessary for
rebuilding bytecompiled lisp and creating tarballs for distribution.

** Binary Packages
==================

Binary packages may be installed directly into an XEmacs package
directory.  XEmacs package directories are determined at the time
XEmacs is configured for building.  The default is
${prefix}/lib/xemacs/packages.  `prefix' defaults to /usr/local unless 
changed by the XEmacs configurer.  This may be changed by specifying a 
path of the form --package-path=directory:directory:directory... (all
directories separated by colons).  There is no restriction on the
number of directories.  There may be no package directories, but
XEmacs won't be very useful.

** Source Packages
==================

Source packages contain all of the Package author's (where appropriate
in regular packages) source code plus all of the files necessary to
build distribution tarballs (Unix Tar format files and gzipped for
space savings).

*** Prerequisites for building Source Packages

You must have GNU cp, GNU ginstall (or a BSD compatible install
program) GNU make (3.75 or later preferred), makeinfo (1.68 from
texinfo-3.11 or later required), GNU tar and XEmacs 20.5 :-).  The
source packages will untar into a correct directory structure.  At
the top level you must have XEmacs.rules and package-compile.el.
These files are available from the XEmacs FTP site from the same
place you obtained your source package distributions.

*** What you can do with Source Packages

NB:  A global build operation doesn't exist yet as of 13 January 1998.

Source packages are most useful for creating XEmacs package tarballs
for installation into your own XEmacs installations or for
distributing to others.

Supported operations from Make are:

**** clean

Remove all built files except auto-autoloads.el and custom-load.el.

**** distclean

Remove XEmacs backups as well as the files deleted by `make clean'.

**** all

Byte compile all files, build and bytecompile byproduct files like
auto-autoloads.el and custom-load.el.  Create info version of TeXinfo
documentation if present.

**** srckit

Usually aliased to `make srckit-std'.  This does a `make distclean'
and creates a Package source tarball in the staging directory.  This
is generally only of use for package maintainers.

**** binkit

May be aliased to binkit-sourceonly, binkit-sourceinfo,
binkit-sourcedata, or binkit-sourcedatainfo. `sourceonly' indicates
there is nothing to install in a data directory or info directory.
`sourceinfo' indicates that source and info files are to be
installed.  `sourcedata' indicates that source and etc (data) files
are to be installed.  `sourcedatainfo' indicates source, etc (data),
and info files are to be installed.  A few packages have needs beyond
the basic templates so this is not yet complete.

**** dist

Runs the rules `srckit' followed by `binkit'.  This is primarily of
use by XEmacs maintainers producing files for distribution.

* Description of available packages by category
===============================================

This data is up-to-date as of 13 January 1998.

** Library Packages (libs)
==========================

These packages are required to build and support most of the rest of
XEmacs.  By design, xemacs-base is a `regular' package.  Use restraint 
when adding new files there as it is required by almost everything.

*** Sun

Support for Sparcworks.  Must be installed prior to XEmacs build to be 
effective.

*** apel

A Portable Emacs Library.  Used by XEmacs MIME support.

*** edebug

A Lisp debugger.

*** efs

Treat files on remote systems the same as local files.  Also contains
dired.

*** mail-lib

Fundamental lisp files for providing email support.

*** tooltalk

Support for building with Tooltalk.  Must be installed prior to XEmacs 
build to be effective.

*** xemacs-base

Fundamental XEmacs support.  Install this unless you wish a totally
naked XEmacs.

*** xemacs-devel

XEmacs Lisp developer support.  This package contains utilities for
supporting Lisp development.  It is a single-file package so it may be 
tailored.

** Communications Packages (comm)
=================================

These packages provide support for various communications, primarily
email and usenet.

*** footnote

Footnoting in mail message editing modes.

*** gnats

XEmacs bug reports.

*** gnus

The Gnus Newsreader and Mailreader.

*** mailcrypt

Support for messaging encryption with PGP.

*** mh-e

Front end support for MH.

*** net-utils

Miscellaneous Networking Utilities.  This is a single-file package and 
files may be deleted at will.

*** ph

Emacs implementation of the ph client to CCSO/qi directory servers.

*** rmail

An obsolete Emacs mailer.  If you do not already use it don't start.

*** supercite

An Emacs citation tool.  Useful with all Emacs Mailers and Newsreaders.

*** tm

Emacs MIME support.

*** vm

An Emacs mailer.  This package must be installed prior to building XEmacs.

*** w3

A Web browser.

** Games and Amusements (games)
===============================

*** cookie

Spook and Yow (Zippy quotes).

*** games

Tetris, Sokoban, and Snake.

*** mine

Minehunt.

*** misc-games

Other amusements and diversions.

** Mule Support (mule)
======================

*** egg-its

Wnn (4.2 and 6) support.  SJ3 support.  Must be installed prior to
XEmacs build.

*** leim

Quail.  Used for everything other than English and Japanese.

*** locale

Used for localized menubars (French and Japanese) and localized splash
screens (Japanese).

*** mule-base

Basic Mule support.  Must be installed prior to building with Mule.

*** skk

Another Japanese Language Input Method.  Can be used without a
separate process running as a dictionary server.

** Productivity Packages (oa)
=============================

*** calendar

Calendar and diary support.

*** edit-utils

Single file lisp packages for various XEmacs goodies.  Load this and
weed out the junk you don't want.

*** forms

Forms editing support (obsolete, use the builtin Widget instead).

*** frame-icon

Provide a WM icon based on major mode.

*** hm--html-menus

HTML editing.

*** ispell

Spell-checking with ispell.

*** pc

PC style interface emulation.

*** psgml

Validated HTML/SGML editing.

*** sgml

SGML/Linuxdoc-SGML editing.

*** slider

User interface tool.

*** speedbar

??? Document me.

*** strokes

Mouse enhancement utility.

*** text-modes

Various single file lisp packages for editing text files.

*** time

Display time & date on the modeline.

** Operating System Utilities (os)
==================================

*** eterm

Terminal emulator.

*** igrep

Enhanced front-end for Grep.

*** ilisp

Front-end for Inferior Lisp.

*** os-utils

Miscellaneous single-file O/S utilities.

*** view-process

A Unix process browsing tool.

** Program Editing Support (prog)
=================================

*** ada

Ada language support.

*** c-support

Basic single-file add-ons for editing C code.

*** cc-mode

C, C++ and Java language support.

*** debug

GUD, gdb, dbx debugging support.

*** ediff

Interface over patch.

*** emerge

Another interface over patch.

*** pcl-cvs

CVS frontend.

*** prog-modes

Miscellaneous single-file lisp files for various programming languages.

*** scheme

Front-end support for Inferior Scheme.

*** sh-script

Support for editing shell scripts.

*** vc

Version Control for Free systems.  This package must be installed
prior to building XEmacs.

*** vc-cc

Version Control for ClearCase.  This package must be installed prior
to building XEmacs [broken as of XEmacs 20.5-beta19].

*** vhdl

Support for VHDL.

** Word Processing (wp)
=======================

*** auctex

Basic TeX/LaTeX support.

*** crisp

Crisp/Brief emulation.

*** edt

DEC EDIT/EDT emulation.

*** texinfo

XEmacs TeXinfo support.

*** textools

Single-file TeX support.

*** tpu

DEC EDIT/TPU support.

*** viper

VI emulation support.