--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/etc/PACKAGES	Mon Aug 13 10:17:07 2007 +0200
@@ -0,0 +1,463 @@
+						-*- 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.