--- a/man/xemacs/packages.texi	Mon Aug 13 11:03:09 2007 +0200
+++ b/man/xemacs/packages.texi	Mon Aug 13 11:04:06 2007 +0200
@@ -1,7 +1,7 @@
 @node Packages, Abbrevs, Running, Top
 @comment  node-name,  next,  previous,  up
 
-@section Introduction to XEmacs Packages
+@section Packages
 @cindex packages
 
 The XEmacs 21 distribution comes only with a very basic set of
@@ -12,16 +12,27 @@
 This gives an installer the ability to tailor an XEmacs installation for
 local needs with safe removal of unnecessary code.
 
+@menu
+* Package Terminology:: Understanding different kinds of packages.
+* Using Packages::      How to install and use packages.
+* Building Packages::   Building packages from sources.
+@end menu
+
+@node Package Terminology, Using Packages, , Packages
+@comment  node-name,  next,  previous,  up
+
 @subsection Package Flavors
 
 There are two main flavors of packages.
 
-@itemize @emph
+@itemize @bullet
 @item Regular Packages
+@cindex regular packages
 A regular package is one in which multiple files are involved and one
 may not in general safely remove any of them.
 
 @item Single-File Packages
+@cindex 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
@@ -37,17 +48,272 @@
 bytecompiled lisp and creating tarballs for distribution.
 
 @subsection Binary Packages
+@cindex binary packages
 Binary packages may be installed directly into an XEmacs package
 hierarchy.
 
 @subsection Source Packages
-
+@cindex 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).
 
-@subsection Prerequisites for building Source Packages
+@node Using Packages, Building Packages, Package Terminology, Packages
+@comment  node-name,  next,  previous,  up
+
+@subsection Getting Started
+
+When you first download XEmacs 21, you will usually first grab the
+@dfn{core distribution},
+@cindex core distribution
+a file called
+@file{xemacs-21.0.tar.gz}. (Replace the @t{21.0} by the current version
+number.)  The core distribution contains the sources of XEmacs and a
+minimal set of Emacs Lisp files, which are in the subdirectory named
+@file{lisp}.  This subdirectory used to contain all Emacs Lisp files
+distributed with XEmacs.  Now, to conserve disk space, most
+non-essential packages were made optional.
+
+@subsection Choosing the Packages You Need
+
+The available packages can currently be found in the same ftp directory
+where you grabbed the core distribition from, and are located in the
+subdirectory @file{packages/binary-packages}.  Package file names follow
+the naming convention @file{<package-name>-<version>-pkg.tar.gz}.
+
+If you have EFS @ref{(EFS)}, packages can be installed over the network.
+Alternatively, if you have copies of the packages locally, you can
+install packages from a local disk or CDROM.
+
+The file @file{etc/PACKAGES} in the core distribution contains a list of
+the packages available at the time of the XEmacs release.  Packages are
+also listed on the @code{Options} menu under:
+
+@example
+	Options->Customize->Emacs->Packages
+@end example
+
+However, don't select any of these menu picks unless you actually want 
+to install the given package (and have properly configured your system 
+to do so).
+
+You can also get a list of available packages, and whether or not they
+are installed, using the visual package browser and installer.  You can
+access it via the menus:
+
+@example
+	Options->Customize->List Packages
+@end example
+
+Or, you can get to it via the keyboard:
+
+@example
+M-x pui-list-packages
+@end example
+
+Hint to system administrators of multi-user systems: it might be a good
+idea to install all packages and not interfere with the wishes of your
+users.
+
+@subsection XEmacs and Installing Packages
+
+Normally, packages are installed over the network, using EFS
+@ref{(EFS)}.  However, you may not have network access, or you may
+already have some or all of the packages on a local disk, such as a
+CDROM.  If you want to install from a local disk, you must first tell
+XEmacs where to find the package binaries.  This is done by adding a line
+like the following to your @file{.emacs} file:
+
+@example
+(setq package-get-remote (cons (list nil "/my/path/to/package/binaries")
+                               package-get-remote))
+@end example
+
+Here, you'd change @file{/my/path/to/package/binaries} to be the path
+to your local package binaries.  Next, restart XEmacs, and you're ready
+to go (advanced users can just re-evaluate the sexp).
+
+If you are installing from a temporary, one-time directory, you can also 
+add these directory names to @code{package-get-remote} using:
+
+@example
+	M-x pui-add-install-directory
+@end example
+
+Note, however, that any directories added using this function are not
+saved; this information will be lost when you quit XEmacs.
+
+If you're going to install over the network, you only have to insure
+that EFS @ref{(EFS)} works, and that it can get outside a firewall, if
+you happen to be behind one.  You shouldn't have to do anything else;
+XEmacs already knows where to go.
+
+The easiest way to install a package is to use the visual package
+browser and installer, using the menu pick:
+
+@example
+	Options->Customize->List Packages
+@end example
+
+You can also access it using the keyboard:
+
+@example
+M-x pui-list-packages
+@end example
+
+The visual package browser will then display a list of all packages.
+Help information will be displayed at the very bottom of the buffer; you
+may have to scroll down to see it.  You can also press @kbd{?} to get
+the same help.  From this buffer, you can tell the package status by the
+character in the first column:
+
+@table @kbd
+@item -
+The package has not been installed.
+@item *
+The package has been installed, but a newer version is available.  The
+current version is out-of-date.
+@item +
+The package has been marked for installation/update.
+@end table
+
+If there is no character in the first column, the package has been
+installed and is up-to-date.
+
+From here, you can select or unselect packages for installation using
+the @key{RET} key, or using the @kbd{Mouse-2} or @kbd{Mouse-3} buttons.
+Once you've finished selecting the packages, you can press the @kbd{x}
+key to actually install the packages.  Note that you will have to
+restart XEmacs for XEmacs to recognize any new packages.
+
+Key summary:
+
+@table @kbd
+@item ?
+Display simple help.
+@item @key{RET}
+@itemx @key{Mouse-2}
+@itemx @key{Mouse-3}
+Toggle between selecting and unselecting a package for installation.
+@item x
+Install selected packages.
+@item @key{SPC}
+View, in the minibuffer, additional information about the package, such
+as the package date (not the build date) and the package author.  Moving 
+the mouse over a package name will also do the same thing.
+@item v
+Toggle between verbose and non-verbose package display.
+@item g
+Refresh the package display.
+@item q
+Kill the package buffer.
+@end table
+
+Moving the mouse over a package will also cause additional information
+about the package to be displayed in the minibuffer.
+
+@subsection Other package installation interfaces
+
+For an alternative package interface, you can select packages from the
+customize menus, under:
+
+@example
+	Options->Customize->Emacs->Packages-> ...
+@end example
+
+Set their state to on, and then do:
+
+@example
+	Options->Customize->Update Packages
+@end example
+
+This will automatically retrieve the packages you have selected from the
+XEmacs ftp site or your local disk, and install them into
+XEmacs.  Additionally it will update any packages you already have
+installed to the newest version.  Note that if a package is newly
+installed you will have to restart XEmacs for the change to take effect.
+
+You can also install packages using a semi-manual interface:
+
+@example
+M-x package-get-all <return>
+@end example
+
+Enter the name of the package (e.g., @code{prog-modes}), and XEmacs
+will search for the latest version (as listed in the lisp file
+@file{lisp/package-get-base.el}), and install it and any packages that
+it depends upon.
+
+@subsection Manual Binary Package Installation
+
+Pre-compiled, binary packages can be installed in either a system
+package directory (this is determined when XEmacs is compiled), or in a
+subdirectory off your @file{$HOME} directory:
+
+@example
+~/.xemacs/packages
+@end example
+
+XEmacs does not have to be running to install binary packages, although
+XEmacs will not know about any newly-installed packages until you
+restart XEmacs.  Note, however, that installing a newer version of a
+package while XEmacs is running could cause strange errors in XEmacs;
+it's best to exit XEmacs before upgrading an existing package.
+
+To install binary packages manually:
+
+@enumerate
+@item
+Download the package(s) that you want to install.  Each binary package
+will typically be a gzip'd tarball.
+
+@item
+Decide where to install the packages: in the system package directory,
+or in @file{~/.xemacs/packages}.  If you want to install the
+packages in the system package directory, make sure you can write into
+that directory.  If you want to install in your @file{$HOME} directory,
+create the directory, @file{~/.xemacs/packages}.
+
+@item
+Next, @code{cd} to the directory under which you want to install the
+package(s).
+
+@item
+From this directory, uncompress and extract each of the gzip'd tarballs
+that you downloaded in step 1.  Unix and Cygnus cygwin users will
+typically do this using the commands:
+
+@example
+	gunzip < package.tar.gz | tar xvf -
+@end example
+
+Above, replace @file{package.tar.gz} with the filename of the
+package that you downloaded in step 1.
+
+Of course, if you use GNU @code{tar}, you could also use:
+
+@example
+	tar xvzf package.tar.gz
+@end example
+
+@comment What about native MS Windows users???
+
+@item
+That's it.  Quit and restart XEmacs to get it to recognize any new or
+changed packages.
+
+@end enumerate
+
+@node Building Packages, , Using Packages, Packages
+@comment  node-name,  next,  previous,  up
+
+Source packages are available from the @file{packages/source-packages}
+subdirectory of your favorite XEmacs distribution site.  Alternatively,
+they are available via CVS from @file{cvs.xemacs.org}.  Look at
+@file{http://cvs.xemacs.org} for instructions.
+
+@subsection Prerequisites for Building Source Packages
 
 You must have GNU @code{cp}, GNU @code{install} (or a BSD compatible
 @code{install} program) GNU @code{make} (3.75 or later preferred),
@@ -58,7 +324,7 @@
 available from the XEmacs FTP site from the same place you obtained your
 source package distributions.
 
-@subsection What you can do with Source Packages
+@subsection What You Can Do With Source Packages
 
 NB:  A global build operation doesn't exist yet as of 13 January 1998.
 
@@ -66,7 +332,7 @@
 for installation into your own XEmacs installations or for
 distributing to others.
 
-Supported operations from Make are:
+Supported operations from @file{make} are:
 
 @table @code
 @item clean