+File: xemacs.info, Node: Using Packages, Next: Building Packages, Prev: Package Terminology, Up: Packages
+
+Getting Started
+---------------
+
+ When you first download XEmacs 21, you will usually first grab the
+"core distribution", a file called `xemacs-21.0.tar.gz'. (Replace the
+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 `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.
+
+Choosing the Packages You Need
+------------------------------
+
+ The available packages can currently be found in the same ftp
+directory where you grabbed the core distribution from, and are located
+in the subdirectory `packages/binary-packages'. Package file names
+follow the naming convention `<package-name>-<version>-pkg.tar.gz'.
+
+ If you have EFS *Note (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 `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 `Options' menu under:
+
+ Options->Customize->Emacs->Packages
+
+ 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:
+
+ Options->Manage Packages->List & Install
+
+ Or, you can get to it via the keyboard:
+
+ M-x pui-list-packages
+
+ 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 `package-get-package-provider' function. Eg., if you know
+that you need `thingatpt', type:
+
+ M-x package-get-package-provider RET thingatpt
+
+ which will return something like (fsf-compat "1.06"). You can the use
+one of the methods above for installing the package you want.
+
+XEmacs and Installing Packages
+------------------------------
+
+ Normally, packages are installed over the network, using EFS *Note
+(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 init file:
+
+ (setq package-get-remote (cons (list nil "/my/path/to/package/binaries")
+ package-get-remote))
+
+ *Note Init File::.
+
+ Here, you'd change `/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 `package-get-remote' using:
+
+ M-x pui-add-install-directory
+
+ 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 *Note (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 `package-get-remote'.
+
+ The easiest way to install a package is to use the visual package
+browser and installer, using the menu pick:
+
+ Options->Manage Packages->List & Install
+ or
+ Options->Manage Packages->Using Custom->Select-> ...
+
+ You can also access it using the keyboard:
+
+ M-x pui-list-packages
+
+ 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 `?' to get the
+same help. From this buffer, you can tell the package status by the
+character in the first column:
+
+`-'
+ The package has not been installed.
+
+`*'
+ The package has been installed, but a newer version is available.
+ The current version is out-of-date.
+
+`+'
+ The package has been marked for installation/update.
+
+ 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 <RET> key, the `Mouse-2' button or selecting "Select" from the
+(Popup) Menu. Once you've finished selecting the packages, you can
+press the `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:
+
+`?'
+ Display simple help.
+
+`<RET>'
+`<Mouse-2>'
+ Toggle between selecting and unselecting a package for
+ installation.
+
+`x'
+ Install selected packages.
+
+`<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.
+
+`v'
+ Toggle between verbose and non-verbose package display.
+
+`g'
+ Refresh the package display.
+
+`q'
+ Kill the package buffer.
+
+ Moving the mouse over a package will also cause additional
+information about the package to be displayed in the minibuffer.
+
+Other package installation interfaces
+-------------------------------------
+
+ For an alternative package interface, you can select packages from
+the customize menus, under:
+
+ Options->Customize->Emacs->Packages-> ...
+ or
+ Options->Manage Packages->Using Custom->Select-> ...
+
+ Set their state to on, and then do:
+
+ Options->Manage Packages->Using Custom->Update Packages
+
+ 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:
+
+ M-x package-get-all <return>
+
+ Enter the name of the package (e.g., `prog-modes'), and XEmacs will
+search for the latest version (as listed in the lisp file
+`lisp/package-get-base.el'), and install it and any packages that it
+depends upon.
+
+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
+one of the following subdirectories of your `$HOME' directory:
+
+ ~/.xemacs/mule-packages
+ ~/.xemacs/xemacs-packages
+
+ Packages in the former directory will only be found by a Mule-enabled
+XEmacs.
+
+ 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:
+
+ 1. Download the package(s) that you want to install. Each binary
+ package will typically be a gzip'd tarball.
+
+ 2. Decide where to install the packages: in the system package
+ directory, or in `~/.xemacs/mule-packages' or
+ `~/.xemacs/xemacs-packages', respectively. 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 `$HOME'
+ directory, create the directory, `~/.xemacs/mule-packages' or
+ `~/.xemacs/xemacs-packages', respectively.
+
+ 3. Next, `cd' to the directory under which you want to install the
+ package(s).
+
+ 4. 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:
+
+ gunzip < package.tar.gz | tar xvf -
+
+ Above, replace `package.tar.gz' with the filename of the package
+ that you downloaded in step 1.
+
+ Of course, if you use GNU `tar', you could also use:
+
+ tar xvzf package.tar.gz
+
+ 5. That's it. Quit and restart XEmacs to get it to recognize any new
+ or changed packages.
+
+
+\1f
+File: xemacs.info, Node: Building Packages, Prev: Using Packages, Up: Packages
+
+ Source packages are available from the `packages/source-packages'
+subdirectory of your favorite XEmacs distribution site. Alternatively,
+they are available via CVS from `cvs.xemacs.org'. Look at
+`http://cvs.xemacs.org' for instructions.
+
+Prerequisites for Building Source Packages
+------------------------------------------
+
+ You must have GNU `cp', GNU `install' (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 21.0. 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'
+ Bytecompile 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.
+
+\1f
+File: xemacs.info, Node: Abbrevs, Next: Picture, Prev: Packages, Up: Top
+
+Abbrevs
+*******
+
+ An "abbrev" is a word which "expands" into some different text.
+Abbrevs are defined by the user to expand in specific ways. For
+example, you might define `foo' as an abbrev expanding to `find outer
+otter'. With this abbrev defined, you would be able to get `find outer
+otter ' into the buffer by typing `f o o <SPC>'.
+
+ Abbrevs expand only when Abbrev mode (a minor mode) is enabled.
+Disabling Abbrev mode does not cause abbrev definitions to be discarded,
+but they do not expand until Abbrev mode is enabled again. The command
+`M-x abbrev-mode' toggles Abbrev mode; with a numeric argument, it
+turns Abbrev mode on if the argument is positive, off otherwise. *Note
+Minor Modes::. `abbrev-mode' is also a variable; Abbrev mode is on
+when the variable is non-`nil'. The variable `abbrev-mode'
+automatically becomes local to the current buffer when it is set.
+
+ Abbrev definitions can be "mode-specific"--active only in one major
+mode. Abbrevs can also have "global" definitions that are active in
+all major modes. The same abbrev can have a global definition and
+various mode-specific definitions for different major modes. A
+mode-specific definition for the current major mode overrides a global
+definition.
+
+ You can define Abbrevs interactively during an editing session. You
+can also save lists of abbrev definitions in files and reload them in
+later sessions. Some users keep extensive lists of abbrevs that they
+load in every session.
+
+ A second kind of abbreviation facility is called the "dynamic
+expansion". Dynamic abbrev expansion happens only when you give an
+explicit command and the result of the expansion depends only on the
+current contents of the buffer. *Note Dynamic Abbrevs::.
+
+* Menu:
+
+* Defining Abbrevs:: Defining an abbrev, so it will expand when typed.
+* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
+* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs.
+* Saving Abbrevs:: Saving the entire list of abbrevs for another session.
+* Dynamic Abbrevs:: Abbreviations for words already in the buffer.
+
+\1f
+File: xemacs.info, Node: Defining Abbrevs, Next: Expanding Abbrevs, Prev: Abbrevs, Up: Abbrevs
+
+Defining Abbrevs
+================
+
+`C-x a g'
+ Define an abbrev to expand into some text before point
+ (`add-global-abbrev').
+
+`C-x a l'
+ Similar, but define an abbrev available only in the current major
+ mode (`add-mode-abbrev').
+
+`C-x a i g'
+ Define a word in the buffer as an abbrev
+ (`inverse-add-global-abbrev').
+
+`C-x a i l'
+ Define a word in the buffer as a mode-specific abbrev
+ (`inverse-add-mode-abbrev').
+
+`M-x kill-all-abbrevs'
+ After this command, no abbrev definitions remain in effect.
+
+ The usual way to define an abbrev is to enter the text you want the
+abbrev to expand to, position point after it, and type `C-x a g'
+(`add-global-abbrev'). This reads the abbrev itself using the
+minibuffer, and then defines it as an abbrev for one or more words
+before point. Use a numeric argument to say how many words before point
+should be taken as the expansion. For example, to define the abbrev
+`foo' as in the example above, insert the text `find outer otter', then
+type
+`C-u 3 C-x a g f o o <RET>'.
+
+ An argument of zero to `C-x a g' means to use the contents of the
+region as the expansion of the abbrev being defined.
+
+ The command `C-x a l' (`add-mode-abbrev') is similar, but defines a
+mode-specific abbrev. Mode-specific abbrevs are active only in a
+particular major mode. `C-x a l' defines an abbrev for the major mode
+in effect at the time `C-x a l' is typed. The arguments work the same
+way they do for `C-x a g'.
+
+ If the text of an abbrev you want is already in the buffer instead of
+the expansion, use command `C-x a i g' (`inverse-add-global-abbrev')
+instead of `C-x a g', or use `C-x a i l' (`inverse-add-mode-abbrev')
+instead of `C-x a l'. These commands are called "inverse" because they
+invert the meaning of the argument found in the buffer and the argument
+read using the minibuffer.
+
+ To change the definition of an abbrev, just add the new definition.
+You will be asked to confirm if the abbrev has a prior definition. To
+remove an abbrev definition, give a negative argument to `C-x a g' or
+`C-x a l'. You must choose the command to specify whether to kill a
+global definition or a mode-specific definition for the current mode,
+since those two definitions are independent for one abbrev.
+
+ `M-x kill-all-abbrevs' removes all existing abbrev definitions.
+
+\1f
+File: xemacs.info, Node: Expanding Abbrevs, Next: Editing Abbrevs, Prev: Defining Abbrevs, Up: Abbrevs
+
+Controlling Abbrev Expansion
+============================
+
+ An abbrev expands whenever it is in a buffer just before point and
+you type a self-inserting punctuation character (<SPC>, comma, etc.).
+Most often an abbrev is used by inserting the abbrev followed by
+punctuation.
+
+ Abbrev expansion preserves case; thus, `foo' expands into `find
+outer otter', `Foo' into `Find outer otter', and `FOO' into `FIND OUTER
+OTTER' or `Find Outer Otter' according to the variable
+`abbrev-all-caps' (a non-`nil' value chooses the first of the two
+expansions).
+
+ Two commands are available to control abbrev expansion:
+
+`M-''
+ Separate a prefix from a following abbrev to be expanded
+ (`abbrev-prefix-mark').
+
+`C-x a e'
+ Expand the abbrev before point (`expand-abbrev'). This is
+ effective even when Abbrev mode is not enabled.
+
+`M-x unexpand-abbrev'
+ Undo last abbrev expansion.
+
+`M-x expand-region-abbrevs'
+ Expand some or all abbrevs found in the region.
+
+ You may wish to expand an abbrev with a prefix attached. For
+example, if `cnst' expands into `construction', you may want to use it
+to enter `reconstruction'. It does not work to type `recnst', because
+that is not necessarily a defined abbrev. Instead, you can use the
+command `M-'' (`abbrev-prefix-mark') between the prefix `re' and the
+abbrev `cnst'. First, insert `re'. Then type `M-''; this inserts a
+minus sign in the buffer to indicate that it has done its work. Then
+insert the abbrev `cnst'. The buffer now contains `re-cnst'. Now
+insert a punctuation character to expand the abbrev `cnst' into
+`construction'. The minus sign is deleted at this point by `M-''. The
+resulting text is the desired `reconstruction'.
+
+ If you actually want the text of the abbrev in the buffer, rather
+than its expansion, insert the following punctuation with `C-q'. Thus,
+`foo C-q -' leaves `foo-' in the buffer.
+
+ If you expand an abbrev by mistake, you can undo the expansion
+(replace the expansion by the original abbrev text) with `M-x
+unexpand-abbrev'. You can also use `C-_' (`undo') to undo the
+expansion; but that will first undo the insertion of the punctuation
+character.
+
+ `M-x expand-region-abbrevs' searches through the region for defined
+abbrevs, and offers to replace each one it finds with its expansion.
+This command is useful if you have typed text using abbrevs but forgot
+to turn on Abbrev mode first. It may also be useful together with a
+special set of abbrev definitions for making several global
+replacements at once. The command is effective even if Abbrev mode is
+not enabled.
+
+\1f
+File: xemacs.info, Node: Editing Abbrevs, Next: Saving Abbrevs, Prev: Expanding Abbrevs, Up: Abbrevs
+
+Examining and Editing Abbrevs
+=============================
+
+`M-x list-abbrevs'
+ Print a list of all abbrev definitions.
+
+`M-x edit-abbrevs'
+ Edit a list of abbrevs; you can add, alter, or remove definitions.
+
+ The output from `M-x list-abbrevs' looks like this:
+
+ (lisp-mode-abbrev-table)
+ "dk" 0 "define-key"
+ (global-abbrev-table)
+ "dfn" 0 "definition"
+
+(Some blank lines of no semantic significance, and some other abbrev
+tables, have been omitted.)
+
+ A line containing a name in parentheses is the header for abbrevs in
+a particular abbrev table; `global-abbrev-table' contains all the global
+abbrevs, and the other abbrev tables that are named after major modes
+contain the mode-specific abbrevs.
+
+ Within each abbrev table, each non-blank line defines one abbrev.
+The word at the beginning is the abbrev. The number that appears is
+the number of times the abbrev has been expanded. Emacs keeps track of
+this to help you see which abbrevs you actually use, in case you want
+to eliminate those that you don't use often. The string at the end of
+the line is the expansion.
+
+ `M-x edit-abbrevs' allows you to add, change or kill abbrev
+definitions by editing a list of them in an Emacs buffer. The list has
+the format described above. The buffer of abbrevs is called
+`*Abbrevs*', and is in Edit-Abbrevs mode. This mode redefines the key
+`C-c C-c' to install the abbrev definitions as specified in the buffer.
+The `edit-abbrevs-redefine' command does this. Any abbrevs not
+described in the buffer are eliminated when this is done.
+
+ `edit-abbrevs' is actually the same as `list-abbrevs', except that
+it selects the buffer `*Abbrevs*' whereas `list-abbrevs' merely
+displays it in another window.
+
+\1f
+File: xemacs.info, Node: Saving Abbrevs, Next: Dynamic Abbrevs, Prev: Editing Abbrevs, Up: Abbrevs
+
+Saving Abbrevs
+==============
+
+ These commands allow you to keep abbrev definitions between editing
+sessions.
+
+`M-x write-abbrev-file'
+ Write a file describing all defined abbrevs.
+
+`M-x read-abbrev-file'
+ Read such an abbrev file and define abbrevs as specified there.
+
+`M-x quietly-read-abbrev-file'
+ Similar, but do not display a message about what is going on.
+
+`M-x define-abbrevs'
+ Define abbrevs from buffer.
+
+`M-x insert-abbrevs'
+ Insert all abbrevs and their expansions into the buffer.
+
+ Use `M-x write-abbrev-file' to save abbrev definitions for use in a
+later session. The command reads a file name using the minibuffer and
+writes a description of all current abbrev definitions into the
+specified file. The text stored in the file looks like the output of
+`M-x list-abbrevs'.
+
+ `M-x read-abbrev-file' prompts for a file name using the minibuffer
+and reads the specified file, defining abbrevs according to its
+contents. `M-x quietly-read-abbrev-file' is the same but does not
+display a message in the echo area; it is actually useful primarily in
+the init file. *Note Init File::. If you give an empty argument to
+either of these functions, the file name Emacs uses is the value of the
+variable `abbrev-file-name', which is by default `"~/.abbrev_defs"'.
+
+ Emacs offers to save abbrevs automatically if you have changed any of
+them, whenever it offers to save all files (for `C-x s' or `C-x C-c').
+Set the variable `save-abbrevs' to `nil' to inhibit this feature.
+
+ The commands `M-x insert-abbrevs' and `M-x define-abbrevs' are
+similar to the previous commands but work on text in an Emacs buffer.
+`M-x insert-abbrevs' inserts text into the current buffer before point,
+describing all current abbrev definitions; `M-x define-abbrevs' parses
+the entire current buffer and defines abbrevs accordingly.
+
+\1f
+File: xemacs.info, Node: Dynamic Abbrevs, Prev: Saving Abbrevs, Up: Abbrevs
+
+Dynamic Abbrev Expansion
+========================
+
+ The abbrev facility described above operates automatically as you
+insert text, but all abbrevs must be defined explicitly. By contrast,
+"dynamic abbrevs" allow the meanings of abbrevs to be determined
+automatically from the contents of the buffer, but dynamic abbrev
+expansion happens only when you request it explicitly.
+
+`M-/'
+ Expand the word in the buffer before point as a "dynamic abbrev",
+ by searching in the buffer for words starting with that
+ abbreviation (`dabbrev-expand').
+
+ For example, if the buffer contains `does this follow ' and you type
+`f o M-/', the effect is to insert `follow' because that is the last
+word in the buffer that starts with `fo'. A numeric argument to `M-/'
+says to take the second, third, etc. distinct expansion found looking
+backward from point. Repeating `M-/' searches for an alternative
+expansion by looking farther back. After the entire buffer before
+point has been considered, the buffer after point is searched.
+
+ Dynamic abbrev expansion is completely independent of Abbrev mode;
+the expansion of a word with `M-/' is completely independent of whether
+it has a definition as an ordinary abbrev.
+
+\1f
+File: xemacs.info, Node: Picture, Next: Sending Mail, Prev: Abbrevs, Up: Top
+
+Editing Pictures
+****************
+
+ If you want to create a picture made out of text characters (for
+example, a picture of the division of a register into fields, as a
+comment in a program), use the command `edit-picture' to enter Picture
+mode.
+
+ In Picture mode, editing is based on the "quarter-plane" model of
+text. In this model, the text characters lie studded on an area that
+stretches infinitely far to the right and downward. The concept of the
+end of a line does not exist in this model; the most you can say is
+where the last non-blank character on the line is found.
+
+ Of course, Emacs really always considers text as a sequence of
+characters, and lines really do have ends. But in Picture mode most
+frequently-used keys are rebound to commands that simulate the
+quarter-plane model of text. They do this by inserting spaces or by
+converting tabs to spaces.
+
+ Most of the basic editing commands of Emacs are redefined by Picture
+mode to do essentially the same thing but in a quarter-plane way. In
+addition, Picture mode defines various keys starting with the `C-c'
+prefix to run special picture editing commands.
+
+ One of these keys, `C-c C-c', is pretty important. Often a picture
+is part of a larger file that is usually edited in some other major
+mode. `M-x edit-picture' records the name of the previous major mode.
+You can then use the `C-c C-c' command (`picture-mode-exit') to restore
+that mode. `C-c C-c' also deletes spaces from the ends of lines,
+unless you give it a numeric argument.
+
+ The commands used in Picture mode all work in other modes (provided
+the `picture' library is loaded), but are only bound to keys in
+Picture mode. Note that the descriptions below talk of moving "one
+column" and so on, but all the picture mode commands handle numeric
+arguments as their normal equivalents do.
+
+ Turning on Picture mode calls the value of the variable
+`picture-mode-hook' as a function, with no arguments, if that value
+exists and is non-`nil'.
+
+* Menu:
+
+* Basic Picture:: Basic concepts and simple commands of Picture Mode.
+* Insert in Picture:: Controlling direction of cursor motion
+ after "self-inserting" characters.
+* Tabs in Picture:: Various features for tab stops and indentation.
+* Rectangles in Picture:: Clearing and superimposing rectangles.
+
+\1f