xemacs-beta: man/xemacs/packages.texi comparison

comparison man/xemacs/packages.texi @ 371:cc15677e0335 r21-2b1

Import from CVS: tag r21-2b1

author	cvs
date	Mon, 13 Aug 2007 11:03:08 +0200
parents	a4f53d9b3154
children	6240c7796c7a

comparison

equal deleted inserted replaced

-:bd866891f083
+:cc15677e0335
-@c This is part of the XEmacs manual.
+@node Packages, Abbrevs, Running, Top
-@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
-@c See file xemacs.texi for copying conditions.
-@node Packages, Basic, Startup Paths, Top
 @comment  node-name,  next,  previous,  up
-@section Packages
+@section Introduction to XEmacs Packages
 @cindex packages
 The XEmacs 21 distribution comes only with a very basic set of
 built-in modes and packages.  Most of the packages that were part of
 the distribution of earlier versions of XEmacs are now separately
 available.  The installer as well as the user can choose which
 packages to install; the actual installation process is easy.
 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.
-* Creating Packages::   The basics.
-* Available Packages::  A brief, out-of-date, directory of packaged LISP.
-@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 @bullet
+@itemize @emph
 @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
 will without any loss of functionality.
 @end itemize
 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.
 @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).
-@node Using Packages, Building Packages, Package Terminology, Packages
+@subsection Prerequisites for building Source 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->Manage Packages->List & Install
-@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.
-If you can't find which package provides the feature you require, try
-using the @code{package-get-package-provider} function. Eg., if you know
-that you need @code{thingatpt}, type:
-@example
-M-x package-get-package-provider RET thingatpt
-@end example
-which will return something like (fsf-compat "1.06"). You can the use
-one of the methods above for installing the package you want.
-@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. However you can add your own mirrors
-to this list. See @code{package-get-remote}.
-The easiest way to install a package is to use the visual package
-browser and installer, using the menu pick:
-@example
-	Options->Manage Packages->List & Install
-@end example
-or
-@example
-	Options->Manage Packages->Using Custom->Select-> ...
-@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, the @kbd{Mouse-2} button or selecting "Select" from
-the (Popup) Menu.
-Once you've finished selecting the packages, you can
-press the @kbd{x} key (or use the menu) 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}
-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
-or
-@example
-	Options->Manage Packages->Using Custom->Select-> ...
-@end example
-Set their state to on, and then do:
-@example
-	Options->Manage Packages->Using Custom->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, Creating 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),
 @code{makeinfo} (1.68 from @code{texinfo-3.11} or later required), GNU
 @code{tar} and XEmacs 21.0.  The source packages will untar into a
 correct directory structure.  At the top level you must have
 @file{XEmacs.rules} and @file{package-compile.el}.  These files are
 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.
 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 @file{make} are:
+Supported operations from Make are:
 @table @code
 @item clean
 Remove all built files except @file{auto-autoloads.el} and @file{custom-load.el}.
 Bytecompile all files, build and bytecompile byproduct files like
 @file{auto-autoloads.el} and @file{custom-load.el}.  Create info version
 of TeXinfo documentation if present.
 @item srckit
-Usually aliased to @code{srckit-std}.  This does a @code{make
+Usually aliased to @code{make srckit-std}.  This does a @code{make
 distclean} and creates a package source tarball in the staging
 directory.  This is generally only of use for package maintainers.
 @item binkit
 May be aliased to @code{binkit-sourceonly}, @code{binkit-sourceinfo},
 @item dist
 Runs the rules @code{srckit} followed by @code{binkit}.  This is
 primarily of use by XEmacs maintainers producing files for distribution.
 @end table
-@node Creating Packages, Available Packages, Building Packages, Packages
-@comment  node-name,  next,  previous,  up
-Creating a package from an existing Lisp library is not very difficult.
-In addition to the Lisp libraries themselves, you need a
-@file{package-info.in} file and a simple @file{Makefile}.  The rest is
-done by @file{XEmacs.rules}, part of the packaging system
-infrastructure.
-@file{package-info.in} contains a single Lisp form like this:
-@example
-(name                               ; your package's name
-(standards-version 1.1
-version VERSION
-author-version AUTHOR_VERSION
-date DATE
-build-date BUILD_DATE
-maintainer MAINTAINER
-distribution xemacs              ; change to "mule" if MULE is needed
-priority high
-category CATEGORY
-dump nil
-description "description"        ; a one-line description string
-filename FILENAME
-md5sum MD5SUM
-size SIZE
-provides (feature1 feature2)     ; one for every `provides' form
-requires (REQUIRES)
-type regular
-))
-@end example
-You must fill in the four commented lines.  The value of @code{name} is
-the name of your package as an unquoted symbol.  Normally it is the name
-of the main Lisp file or principal feature provided.  The allowed values
-for distribution are @code{xemacs} and @code{mule}.  Write them as
-unquoted symbols.  The @code{description} is a quoted Lisp string; use
-the usual conventions.  The value for @code{provides} is a list of
-feature symbols (written unquoted).  All of the features provided by
-libraries in your package should be elements of this list.  Implementing
-an automatic method for generating the @file{provides} line is
-desirable, but as yet undone.
-The variables in upper-case are references to variables set in the
-@file{Makefile} or automatically generated.  Do not change them; they
-are automatically filled in by the build process.
-The remaining lines refer to implementation constants
-(@code{standards-version}), or features that are unimplemented or have
-been removed (@code{priority} and @code{dump}).  The @code{type} line is
-not normally relevant to external maintainers; the alternate value is
-@code{single-file}, which refers to packages consed up out of a number
-of single-file libraries that are more or less thematically related.  An
-example is @code{prog-modes}.  Single-file packages are basically for
-administrative convenience, and new packages should generally be created
-as regular packages.
-The @file{Makefile} is quite stylized.  The idea is similar to an
-@file{Imakefile} or an @code{automake} file: the complexity is hidden in
-generic rules files, in this case the @file{XEmacs.rules} include file
-in the top directory of the packages hierarchy.  Although a number of
-facilities are available for complex libraries, most simple packages'
-@file{Makefile}s contain a copyright notice, a few variable definitions,
-an include for @file{XEmacs.rules}, and a couple of standard targets.
-The first few @code{make} variables defined are @code{VERSION},
-@code{AUTHOR_VERSION}, @code{MAINTAINER}, @code{PACKAGE},
-@code{PKG_TYPE}, @code{REQUIRES}, and @code{CATEGORY}.  All but one were
-described in the description of @file{package-info.in}.  The last is an
-admistrative grouping.  Current categories include @code{comm},
-@code{games}, @code{libs}, @code{mule}, @code{oa}, @code{os},
-@code{prog}, and @code{wp}.  @ref{Available Packages}, for a list of
-categories.
-Next, define the variable @code{ELCS}.  This contains the list of the
-byte-compiled Lisp files used by the package.  These files and their
-@file{.el} versions will be included in the binary package.  If there
-are other files (such as extra Lisp sources or an upstream
-@file{Makefile}) that are normally placed in the installed Lisp
-directory, but not byte-compiled, they can be listed as the value of
-@code{EXTRA_SOURCES}.
-The include is simply
-@example
-include ../../XEmacs.rules
-@end example
-The standard targets follow.  These are
-@example
-all:: $(ELCS) auto-autoloads.elc
-srckit: srckit-alias
-binkit: binkit-alias
-@end example
-Other targets (such as Texinfo sources) may need to be added as
-dependencies for the @code{all} target.  Dependencies for @code{srckit}
-and @code{binkit} (that is, values for @var{srckit-alias} and
-@var{binkit-alias}) are defined in @file{XEmacs.rules}.  The most useful
-of these values are given in the following table.
-@table @var
-@item srckit-alias
-Usually set to @code{srckit-std}.
-@item binkit-alias
-May be set to @code{binkit-sourceonly}, @code{binkit-sourceinfo},
-@code{binkit-sourcedata}, or
-@code{binkit-sourcedatainfo}.  @code{sourceonly} indicates there is
-nothing to install in a data directory or info directory.
-@code{sourceinfo} indicates that source and info files are to be
-installed.  @code{sourcedata} indicates that source and etc (data) files
-are to be installed.  @code{sourcedatainfo} indicates source, etc
-(data), and info files are to be installed.
-@end table
-Data files include things like pixmaps for a package-specific toolbar,
-and are normally installed in @file{etc/@var{PACKAGE_NAME}}.  A few
-packages have needs beyond the basic templates.  See @file{XEmacs.rules}
-or a future revision of this manual for details.
-@node Available Packages,  , Creating Packages, Packages
-@comment  node-name,  next,  previous,  up
-This section is surely out-of-date.  If you're sure that XEmacs is
-able to do something, but your installed XEmacs won't do it for you,
-it's probably in a package.  If you can't find it in this section,
-that's a bug---please report it.  It is very hard to keep this section
-up-to-date; your reports, comments, and questions will help a lot.
-This data is up-to-date as of 10 February 1999.  (Ouch!  I told you!)
-@subsection 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.
-@table @file
-@item Sun
-Support for Sparcworks.
-@item apel
-A Portable Emacs Library.  Used by XEmacs MIME support.
-@item edebug
-A Lisp debugger.
-@item dired
-The DIRectory EDitor is for manipulating, and running commands on
-files in a directory.
-@item efs
-Treat files on remote systems the same as local files.
-@item mail-lib
-Fundamental lisp files for providing email support.
-@item tooltalk
-Support for building with Tooltalk.
-@item xemacs-base
-Fundamental XEmacs support.  Install this unless you wish a totally
-naked XEmacs.
-@item 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.
-@end table
-@subsection Communications Packages (comm)
-These packages provide support for various communications, primarily
-email and usenet.
-@table @file
-@item footnote
-Footnoting in mail message editing modes.
-@item gnats
-XEmacs bug reports.
-@item gnus
-The Gnus Newsreader and Mailreader.
-@item mailcrypt
-Support for messaging encryption with PGP.
-@item mh-e
-Front end support for MH.
-@item net-utils
-Miscellaneous Networking Utilities.  This is a single-file package and
-files may be deleted at will.
-@item ph
-Emacs implementation of the ph client to CCSO/qi directory servers.
-@item rmail
-An obsolete Emacs mailer.  If you do not already use it, don't start.
-@item supercite
-An Emacs citation tool.  Useful with all Emacs Mailers and Newsreaders.
-@item tm
-Emacs MIME support.
-@item vm
-An Emacs mailer.
-@item w3
-A Web browser.
-@end table
-@subsection Games and Amusements (games)
-@table @file
-@item cookie
-Spook and Yow (Zippy quotes).
-@item games
-Tetris, Sokoban, and Snake.
-@item mine
-Minehunt.
-@item misc-games
-Other amusements and diversions.
-@end table
-@subsection Mule Support (mule)
-@table @file
-@item egg-its
-Wnn (4.2 and 6) support.  SJ3 support.  Must be installed prior to
-XEmacs build.
-@item leim
-Quail.  Used for everything other than English and Japanese.
-@item locale
-Used for localized menubars (French and Japanese) and localized splash
-screens (Japanese).
-@item mule-base
-Basic Mule support.  Must be installed prior to building with Mule.
-@item skk
-Another Japanese Language Input Method.  Can be used without a
-separate process running as a dictionary server.
-@end table
-@subsection Productivity Packages (oa)
-@table @file
-@item calendar
-Calendar and diary support.
-@item edit-utils
-Single file lisp packages for various XEmacs goodies.  Load this and
-weed out the junk you don't want.
-@item forms
-Forms editing support (obsolete, use the builtin Widget instead).
-@item frame-icon
-Provide a WM icon based on major mode.
-@item hm--html-menus
-HTML editing.
-@item ispell
-Spell-checking with ispell.
-@item pc
-PC style interface emulation.
-@item psgml
-Validated HTML/SGML editing.
-@item sgml
-SGML/Linuxdoc-SGML editing.
-@item slider
-User interface tool.
-@item speedbar
-??? Document me.
-@item strokes
-Mouse enhancement utility.
-@item text-modes
-Various single file lisp packages for editing text files.
-@item time
-Display time & date on the modeline.
-@end table
-@subsection Operating System Utilities (os)
-@table @file
-@item eterm
-Terminal emulator.
-@item igrep
-Enhanced front-end for Grep.
-@item ilisp
-Front-end for Inferior Lisp.
-@item os-utils
-Miscellaneous single-file O/S utilities, for printing, archiving,
-compression, remote shells, etc.
-@item view-process
-A Unix process browsing tool.
-@end table
-@subsection Program Editing Support (prog)
-@table @file
-@item ada
-Ada language support.
-@item c-support
-Basic single-file add-ons for editing C code.
-@item cc-mode
-C, C++ and Java language support.
-@item debug
-GUD, gdb, dbx debugging support.
-@item ediff
-Interface over patch.
-@item emerge
-Another interface over patch.
-@item pcl-cvs
-CVS frontend.
-@item prog-modes
-Miscellaneous single-file lisp files for various programming languages.
-@item scheme
-Front-end support for Inferior Scheme.
-@item sh-script
-Support for editing shell scripts.
-@item vc
-Version Control for Free systems.
-@item vc-cc
-Version Control for ClearCase.  This package must be installed prior
-to building XEmacs [broken as of XEmacs 20.5-beta19].
-@item vhdl
-Support for VHDL.
-@end table
-@subsection Word Processing (wp)
-@table @file
-@item auctex
-Basic TeX/LaTeX support.
-@item crisp
-Crisp/Brief emulation.
-@item edt
-DEC EDIT/EDT emulation.
-@item texinfo
-XEmacs TeXinfo support.
-@item textools
-Single-file TeX support.
-@item tpu
-DEC EDIT/TPU support.
-@item viper
-VI emulation support.
-@end table

Mercurial > hg > xemacs-beta

comparison man/xemacs/packages.texi @ 371:cc15677e0335 r21-2b1