-\1f
-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 `.emacs' file:
-
- (setq package-get-remote (cons (list nil "/my/path/to/package/binaries")
- package-get-remote))
-
- 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 `.emacs' 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.
-