-This is ../info/xemacs.info, produced by makeinfo version 4.0 from
+This is ../info/xemacs.info, produced by makeinfo version 4.0b from
xemacs/xemacs.texi.
INFO-DIR-SECTION XEmacs Editor
translation approved by the author instead of in the original English.
\1f
-File: xemacs.info, Node: Using Packages, Next: Building Packages, Prev: Package Terminology, Up: Packages
+File: xemacs.info, Node: Lisp Libraries, Next: Lisp Eval, Prev: Lisp Modes, Up: Running
-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'.
+Libraries of Lisp Code for Emacs
+================================
- 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.
+ Lisp code for Emacs editing commands is stored in files whose names
+conventionally end in `.el'. This ending tells Emacs to edit them in
+Emacs-Lisp mode (*note Lisp Modes::).
- 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
+* Menu:
- 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).
+* Loading:: Loading libraries of Lisp code into Emacs for use.
+* Compiling Libraries:: Compiling a library makes it load and run faster.
+* Mocklisp:: Converting Mocklisp to Lisp so XEmacs can run it.
- 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:
+\1f
+File: xemacs.info, Node: Loading, Next: Compiling Libraries, Prev: Lisp Libraries, Up: Lisp Libraries
+
+Loading Libraries
+-----------------
+
+`M-x load-file FILE'
+ Load the file FILE of Lisp code.
+
+`M-x load-library LIBRARY'
+ Load the library named LIBRARY.
+
+`M-x locate-library LIBRARY &optional NOSUFFIX'
+ Show the full path name of Emacs library LIBRARY.
+
+ To execute a file of Emacs Lisp, use `M-x load-file'. This command
+reads the file name you provide in the minibuffer, then executes the
+contents of that file as Lisp code. It is not necessary to visit the
+file first; in fact, this command reads the file as found on disk, not
+the text in an Emacs buffer.
+
+ Once a file of Lisp code is installed in the Emacs Lisp library
+directories, users can load it using `M-x load-library'. Programs can
+load it by calling `load-library', or with `load', a more primitive
+function that is similar but accepts some additional arguments.
+
+ `M-x load-library' differs from `M-x load-file' in that it searches
+a sequence of directories and tries three file names in each directory.
+The three names are: first, the specified name with `.elc' appended;
+second, the name with `.el' appended; third, the specified name alone.
+A `.elc' file would be the result of compiling the Lisp file into byte
+code; if possible, it is loaded in preference to the Lisp file itself
+because the compiled file loads and runs faster.
+
+ Because the argument to `load-library' is usually not in itself a
+valid file name, file name completion is not available. In fact, when
+using this command, you usually do not know exactly what file name will
+be used.
+
+ The sequence of directories searched by `M-x load-library' is
+specified by the variable `load-path', a list of strings that are
+directory names. The elements of this list may not begin with "`~'",
+so you must call `expand-file-name' on them before adding them to the
+list. The default value of the list contains the directory where the
+Lisp code for Emacs itself is stored. If you have libraries of your
+own, put them in a single directory and add that directory to
+`load-path'. `nil' in this list stands for the current default
+directory, but it is probably not a good idea to put `nil' in the list.
+If you start wishing that `nil' were in the list, you should probably
+use `M-x load-file' for this case.
+
+ The variable is initialized by the EMACSLOADPATH environment
+variable. If no value is specified, the variable takes the default value
+specified in the file `paths.h' when Emacs was built. If a path isn't
+specified in `paths.h', a default value is obtained from the file
+system, near the directory in which the Emacs executable resides.
+
+ Like `M-x load-library', `M-x locate-library' searches the
+directories in `load-path' to find the file that `M-x load-library'
+would load. If the optional second argument NOSUFFIX is non-`nil', the
+suffixes `.elc' or `.el' are not added to the specified name LIBRARY
+(like calling `load' instead of `load-library').
+
+ You often do not have to give any command to load a library, because
+the commands defined in the library are set up to "autoload" that
+library. Running any of those commands causes `load' to be called to
+load the library; this replaces the autoload definitions with the real
+ones from the library.
+
+ If autoloading a file does not finish, either because of an error or
+because of a `C-g' quit, all function definitions made by the file are
+undone automatically. So are any calls to `provide'. As a
+consequence, the entire file is loaded a second time if you use one of
+the autoloadable commands again. This prevents problems when the
+command is no longer autoloading but is working incorrectly because the
+file was only partially loaded. Function definitions are undone only
+for autoloading; explicit calls to `load' do not undo anything if
+loading is not completed.
+
+ The variable `after-load-alist' takes an alist of expressions to be
+evaluated when particular files are loaded. Each element has the form
+`(FILENAME forms...)'. When `load' is run and the filename argument is
+FILENAME, the forms in the corresponding element are executed at the
+end of loading.
+
+ FILENAME must match exactly. Normally FILENAME is the name of a
+library, with no directory specified, since that is how load is
+normally called. An error in `forms' does not undo the load, but it
+does prevent execution of the rest of the `forms'.
- Options->Manage Packages->List & Install
+\1f
+File: xemacs.info, Node: Compiling Libraries, Next: Mocklisp, Prev: Loading, Up: Lisp Libraries
+
+Compiling Libraries
+-------------------
+
+ Emacs Lisp code can be compiled into byte-code which loads faster,
+takes up less space when loaded, and executes faster.
+
+`M-x batch-byte-compile'
+ Run byte-compile-file on the files remaining on the command line.
+
+`M-x byte-compile-buffer &optional BUFFER'
+ Byte-compile and evaluate contents of BUFFER (default is current
+ buffer).
+
+`M-x byte-compile-file'
+ Compile a file of Lisp code named FILENAME into a file of byte
+ code.
+
+`M-x byte-compile-and-load-file FILENAME'
+ Compile a file of Lisp code named FILENAME into a file of byte
+ code and load it.
+
+`M-x byte-recompile-directory DIRECTORY'
+ Recompile every `.el' file in DIRECTORY that needs recompilation.
+
+`M-x disassemble'
+ Print disassembled code for OBJECT on (optional) STREAM.
+
+`M-x make-obsolete FUNCTION NEW'
+ Make the byte-compiler warn that FUNCTION is obsolete and NEW
+ should be used instead.
+
+ `byte-compile-file' creates a byte-code compiled file from an
+Emacs-Lisp source file. The default argument for this function is the
+file visited in the current buffer. The function reads the specified
+file, compiles it into byte code, and writes an output file whose name
+is made by appending `c' to the input file name. Thus, the file
+`rmail.el' would be compiled into `rmail.elc'. To compile a file of
+Lisp code named FILENAME into a file of byte code and then load it, use
+`byte-compile-and-load-file'. To compile and evaluate Lisp code in a
+given buffer, use `byte-compile-buffer'.
+
+ To recompile all changed Lisp files in a directory, use `M-x
+byte-recompile-directory'. Specify just the directory name as an
+argument. Each `.el' file that has been byte-compiled before is
+byte-compiled again if it has changed since the previous compilation.
+A numeric argument to this command tells it to offer to compile each
+`.el' file that has not been compiled yet. You must answer `y' or `n'
+to each offer.
+
+ You can use the function `batch-byte-compile' to invoke Emacs
+non-interactively from the shell to do byte compilation. When you use
+this function, the files to be compiled are specified with command-line
+arguments. Use a shell command of the form:
+
+ emacs -batch -f batch-byte-compile FILES...
+
+ Directory names may also be given as arguments; in that case,
+`byte-recompile-directory' is invoked on each such directory.
+`batch-byte-compile' uses all remaining command-line arguments as file
+or directory names, then kills the Emacs process.
+
+ `M-x disassemble' explains the result of byte compilation. Its
+argument is a function name. It displays the byte-compiled code in a
+help window in symbolic form, one instruction per line. If the
+instruction refers to a variable or constant, that is shown, too.
- Or, you can get to it via the keyboard:
+\1f
+File: xemacs.info, Node: Mocklisp, Prev: Compiling Libraries, Up: Lisp Libraries
- M-x pui-list-packages
+Converting Mocklisp to Lisp
+---------------------------
- 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.
+ XEmacs can run Mocklisp files by converting them to Emacs Lisp first.
+To convert a Mocklisp file, visit it and then type `M-x
+convert-mocklisp-buffer'. Then save the resulting buffer of Lisp file
+in a file whose name ends in `.el' and use the new file as a Lisp
+library.
- 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:
+ You cannot currently byte-compile converted Mocklisp code. The
+reason is that converted Mocklisp code uses some special Lisp features
+to deal with Mocklisp's incompatible ideas of how arguments are
+evaluated and which values signify "true" or "false".
- M-x package-get-package-provider RET thingatpt
+\1f
+File: xemacs.info, Node: Lisp Eval, Next: Lisp Debug, Prev: Lisp Libraries, Up: Running
+
+Evaluating Emacs-Lisp Expressions
+=================================
+
+ Lisp programs intended to be run in Emacs should be edited in
+Emacs-Lisp mode; this will happen automatically for file names ending in
+`.el'. By contrast, Lisp mode itself should be used for editing Lisp
+programs intended for other Lisp systems. Emacs-Lisp mode can be
+selected with the command `M-x emacs-lisp-mode'.
+
+ For testing of Lisp programs to run in Emacs, it is useful to be able
+to evaluate part of the program as it is found in the Emacs buffer. For
+example, if you change the text of a Lisp function definition and then
+evaluate the definition, Emacs installs the change for future calls to
+the function. Evaluation of Lisp expressions is also useful in any
+kind of editing task for invoking non-interactive functions (functions
+that are not commands).
+
+`M-<ESC>'
+ Read a Lisp expression in the minibuffer, evaluate it, and print
+ the value in the minibuffer (`eval-expression').
+
+`C-x C-e'
+ Evaluate the Lisp expression before point, and print the value in
+ the minibuffer (`eval-last-sexp').
+
+`C-M-x'
+ Evaluate the defun containing point or after point, and print the
+ value in the minibuffer (`eval-defun').
+
+`M-x eval-region'
+ Evaluate all the Lisp expressions in the region.
+
+`M-x eval-current-buffer'
+ Evaluate all the Lisp expressions in the buffer.
+
+ `M-<ESC>' (`eval-expression') is the most basic command for
+evaluating a Lisp expression interactively. It reads the expression
+using the minibuffer, so you can execute any expression on a buffer
+regardless of what the buffer contains. When evaluation is complete,
+the current buffer is once again the buffer that was current when
+`M-<ESC>' was typed.
+
+ `M-<ESC>' can easily confuse users, especially on keyboards with
+autorepeat, where it can result from holding down the <ESC> key for too
+long. Therefore, `eval-expression' is normally a disabled command.
+Attempting to use this command asks for confirmation and gives you the
+option of enabling it; once you enable the command, you are no longer
+required to confirm. *Note Disabling::.
+
+ In Emacs-Lisp mode, the key `C-M-x' is bound to the function
+`eval-defun', which parses the defun containing point or following point
+as a Lisp expression and evaluates it. The value is printed in the echo
+area. This command is convenient for installing in the Lisp environment
+changes that you have just made in the text of a function definition.
+
+ The command `C-x C-e' (`eval-last-sexp') performs a similar job but
+is available in all major modes, not just Emacs-Lisp mode. It finds
+the sexp before point, reads it as a Lisp expression, evaluates it, and
+prints the value in the echo area. It is sometimes useful to type in an
+expression and then, with point still after it, type `C-x C-e'.
+
+ If `C-M-x' or `C-x C-e' are given a numeric argument, they print the
+value by inserting it into the current buffer at point, rather than in
+the echo area. The argument value does not matter.
+
+ The most general command for evaluating Lisp expressions from a
+buffer is `eval-region'. `M-x eval-region' parses the text of the
+region as one or more Lisp expressions, evaluating them one by one.
+`M-x eval-current-buffer' is similar, but it evaluates the entire
+buffer. This is a reasonable way to install the contents of a file of
+Lisp code that you are just ready to test. After finding and fixing a
+bug, use `C-M-x' on each function that you change, to keep the Lisp
+world in step with the source file.
- which will return something like (fsf-compat "1.06"). You can the use
-one of the methods above for installing the package you want.
+\1f
+File: xemacs.info, Node: Lisp Debug, Next: Lisp Interaction, Prev: Lisp Eval, Up: Running
+
+The Emacs-Lisp Debugger
+=======================
+
+ XEmacs contains a debugger for Lisp programs executing inside it.
+This debugger is normally not used; many commands frequently get Lisp
+errors when invoked in inappropriate contexts (such as `C-f' at the end
+of the buffer) and it would be unpleasant to enter a special debugging
+mode in this case. When you want to make Lisp errors invoke the
+debugger, you must set the variable `debug-on-error' to non-`nil'.
+Quitting with `C-g' is not considered an error, and `debug-on-error'
+has no effect on the handling of `C-g'. However, if you set
+`debug-on-quit' to be non-`nil', `C-g' will invoke the debugger. This
+can be useful for debugging an infinite loop; type `C-g' once the loop
+has had time to reach its steady state. `debug-on-quit' has no effect
+on errors.
+
+ You can make Emacs enter the debugger when a specified function is
+called or at a particular place in Lisp code. Use `M-x debug-on-entry'
+with argument FUN-NAME to have Emacs enter the debugger as soon as
+FUN-NAME is called. Use `M-x cancel-debug-on-entry' to make the
+function stop entering the debugger when called. (Redefining the
+function also does this.) To enter the debugger from some other place
+in Lisp code, you must insert the expression `(debug)' there and
+install the changed code with `C-M-x'. *Note Lisp Eval::.
+
+ When the debugger is entered, it displays the previously selected
+buffer in one window and a buffer named `*Backtrace*' in another
+window. The backtrace buffer contains one line for each level of Lisp
+function execution currently going on. At the beginning of the buffer
+is a message describing the reason that the debugger was invoked, for
+example, an error message if it was invoked due to an error.
+
+ The backtrace buffer is read-only and is in Backtrace mode, a special
+major mode in which letters are defined as debugger commands. The
+usual Emacs editing commands are available; you can switch windows to
+examine the buffer that was being edited at the time of the error, and
+you can switch buffers, visit files, and perform any other editing
+operations. However, the debugger is a recursive editing level (*note
+Recursive Edit::); it is a good idea to return to the backtrace buffer
+and explicitly exit the debugger when you don't want to use it any
+more. Exiting the debugger kills the backtrace buffer.
+
+ The contents of the backtrace buffer show you the functions that are
+executing and the arguments that were given to them. It also allows you
+to specify a stack frame by moving point to the line describing that
+frame. The frame whose line point is on is considered the "current
+frame". Some of the debugger commands operate on the current frame.
+Debugger commands are mainly used for stepping through code one
+expression at a time. Here is a list of them:
+
+`c'
+ Exit the debugger and continue execution. In most cases,
+ execution of the program continues as if the debugger had never
+ been entered (aside from the effect of any variables or data
+ structures you may have changed while inside the debugger). This
+ includes entry to the debugger due to function entry or exit,
+ explicit invocation, and quitting or certain errors. Most errors
+ cannot be continued; trying to continue an error usually causes
+ the same error to occur again.
+
+`d'
+ Continue execution, but enter the debugger the next time a Lisp
+ function is called. This allows you to step through the
+ subexpressions of an expression, and see what the subexpressions
+ do and what values they compute.
+
+ When you enter the debugger this way, Emacs flags the stack frame
+ for the function call from which you entered. The same function
+ is then called when you exit the frame. To cancel this flag, use
+ `u'.
+
+`b'
+ Set up to enter the debugger when the current frame is exited.
+ Frames that invoke the debugger on exit are flagged with stars.
+
+`u'
+ Don't enter the debugger when the current frame is exited. This
+ cancels a `b' command on a frame.
+
+`e'
+ Read a Lisp expression in the minibuffer, evaluate it, and print
+ the value in the echo area. This is equivalent to the command
+ `M-<ESC>', except that `e' is not normally disabled like `M-<ESC>'.
-XEmacs and Installing Packages
-------------------------------
+`q'
+ Terminate the program being debugged; return to top-level Emacs
+ command execution.
- 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:
+ If the debugger was entered due to a `C-g' but you really want to
+ quit, not to debug, use the `q' command.
- (setq package-get-remote (cons (list nil "/my/path/to/package/binaries")
- package-get-remote))
+`r'
+ Return a value from the debugger. The value is computed by
+ reading an expression with the minibuffer and evaluating it.
- 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).
+ The value returned by the debugger makes a difference when the
+ debugger was invoked due to exit from a Lisp call frame (as
+ requested with `b'); then the value specified in the `r' command
+ is used as the value of that frame.
- If you are installing from a temporary, one-time directory, you can
-also add these directory names to `package-get-remote' using:
+ The debugger's return value also matters with many errors. For
+ example, `wrong-type-argument' errors will use the debugger's
+ return value instead of the invalid argument; `no-catch' errors
+ will use the debugger value as a throw tag instead of the tag that
+ was not found. If an error was signaled by calling the Lisp
+ function `signal', the debugger's return value is returned as the
+ value of `signal'.
- M-x pui-add-install-directory
+\1f
+File: xemacs.info, Node: Lisp Interaction, Next: External Lisp, Prev: Lisp Debug, Up: Running
- Note, however, that any directories added using this function are not
-saved; this information will be lost when you quit XEmacs.
+Lisp Interaction Buffers
+========================
- 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 buffer `*scratch*', which is selected when Emacs starts up, is
+provided for evaluating Lisp expressions interactively inside Emacs.
+Both the expressions you evaluate and their output goes in the buffer.
+
+ The `*scratch*' buffer's major mode is Lisp Interaction mode, which
+is the same as Emacs-Lisp mode except for one command, <LFD>. In
+Emacs-Lisp mode, <LFD> is an indentation command. In Lisp Interaction
+mode, <LFD> is bound to `eval-print-last-sexp'. This function reads
+the Lisp expression before point, evaluates it, and inserts the value
+in printed representation before point.
+
+ The way to use the `*scratch*' buffer is to insert Lisp expressions
+at the end, ending each one with <LFD> so that it will be evaluated.
+The result is a complete typescript of the expressions you have
+evaluated and their values.
+
+ The rationale for this feature is that Emacs must have a buffer when
+it starts up, but that buffer is not useful for editing files since a
+new buffer is made for every file that you visit. The Lisp interpreter
+typescript is the most useful thing I can think of for the initial
+buffer to do. `M-x lisp-interaction-mode' will put any buffer in Lisp
+Interaction mode.
- The easiest way to install a package is to use the visual package
-browser and installer, using the menu pick:
+\1f
+File: xemacs.info, Node: External Lisp, Prev: Lisp Interaction, Up: Running
- Options->Manage Packages->List & Install
- or
- Options->Manage Packages->Using Custom->Select-> ...
+Running an External Lisp
+========================
- You can also access it using the keyboard:
+ Emacs has facilities for running programs in other Lisp systems.
+You can run a Lisp process as an inferior of Emacs, and pass
+expressions to it to be evaluated. You can also pass changed function
+definitions directly from the Emacs buffers in which you edit the Lisp
+programs to the inferior Lisp process.
+
+ To run an inferior Lisp process, type `M-x run-lisp'. This runs the
+program named `lisp', the same program you would run by typing `lisp'
+as a shell command, with both input and output going through an Emacs
+buffer named `*lisp*'. In other words, any "terminal output" from Lisp
+will go into the buffer, advancing point, and any "terminal input" for
+Lisp comes from text in the buffer. To give input to Lisp, go to the
+end of the buffer and type the input, terminated by <RET>. The
+`*lisp*' buffer is in Inferior Lisp mode, which has all the special
+characteristics of Lisp mode and Shell mode (*note Shell Mode::).
+
+ Use Lisp mode to run the source files of programs in external Lisps.
+You can select this mode with `M-x lisp-mode'. It is used automatically
+for files whose names end in `.l' or `.lisp', as most Lisp systems
+usually expect.
+
+ When you edit a function in a Lisp program you are running, the
+easiest way to send the changed definition to the inferior Lisp process
+is the key `C-M-x'. In Lisp mode, this key runs the function
+`lisp-send-defun', which finds the defun around or following point and
+sends it as input to the Lisp process. (Emacs can send input to any
+inferior process regardless of what buffer is current.)
+
+ Contrast the meanings of `C-M-x' in Lisp mode (for editing programs
+to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp
+programs to be run in Emacs): in both modes it has the effect of
+installing the function definition that point is in, but the way of
+doing so is different according to where the relevant Lisp environment
+is found. *Note Lisp Modes::.
- M-x pui-list-packages
+\1f
+File: xemacs.info, Node: Packages, Next: Basic, Prev: Startup Paths, Up: Top
- 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:
+Packages
+========
-`-'
- The package has not been installed.
+ 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 available
+separately. 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.
-`*'
- The package has been installed, but a newer version is available.
- The current version is out-of-date.
+* Menu:
-`+'
- The package has been marked for installation/update.
+* Package Terminology:: Understanding different kinds of packages.
+* Installing Packages:: How to install packages.
+* Building Packages:: Building packages from CVS sources.
+* Local.rules File:: This is an important file don't forget to create/edit it.
+* Creating Packages:: The basics.
+* Available Packages:: A brief directory of packaged LISP.
- If there is no character in the first column, the package has been
-installed and is up-to-date.
+\1f
+File: xemacs.info, Node: Package Terminology, Next: Installing Packages, Up: Packages
- 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.
+Package Terminology:
+====================
- Key summary:
+Package Flavors
+---------------
-`?'
- Display simple help.
+ There are two main flavors of packages.
-`<RET>'
-`<Mouse-2>'
- Toggle between selecting and unselecting a package for
- installation.
+ * Regular Packages A regular package is one in which multiple files
+ are involved and one may not in general safely remove any of them.
-`x'
- Install selected packages.
+ * 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 be deleted at will without any loss of
+ functionality. However, we would recommend that you follow this
+ rule of thumb: "When in doubt, don't delete".
-`<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.
+Package Distributions
+---------------------
-`v'
- Toggle between verbose and non-verbose package display.
+ XEmacs Lisp packages are distributed in two ways, depending on the
+intended use. Binary Packages are for installers and end-users that can
+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.
-`g'
- Refresh the package display.
+Binary Packages
+---------------
-`q'
- Kill the package buffer.
+ Binary packages may be installed directly into an XEmacs package
+hierarchy.
- Moving the mouse over a package will also cause additional
-information about the package to be displayed in the minibuffer.
+Source Packages
+---------------
-Other package installation interfaces
--------------------------------------
+ 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,
+gzipped for space savings).
- For an alternative package interface, you can select packages from
-the customize menus, under:
+ Currently, source packages are only available via CVS. See
+<http://cvs.xemacs.org/> for details.
- Options->Customize->Emacs->Packages-> ...
- or
- Options->Manage Packages->Using Custom->Select-> ...
+\1f
+File: xemacs.info, Node: Installing Packages, Next: Building Packages, Prev: Package Terminology, Up: Packages
- Set their state to on, and then do:
+Installing Packages:
+====================
- Options->Manage Packages->Using Custom->Update Packages
+Getting Started
+---------------
- 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.
+ When you first download XEmacs 21, you will usually first grab the
+"core distribution", a file called `xemacs-21.x.x.tar.gz'. (Replace the
+21.x.x 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.
- You can also install packages using a semi-manual interface:
+Choosing the Packages You Need
+------------------------------
- M-x package-get-all <return>
+ The *Note 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'. Package file names follow the
+naming convention `<package-name>-<version>-pkg.tar.gz'.
- 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.
+ 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.
-Manual Binary Package Installation
-----------------------------------
+ The file `etc/PACKAGES' in the core distribution contains a list of
+the *Note Available Packages:: at the time of the XEmacs release.
+Packages are also listed on the `Options' menu under:
- 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:
+ Options -> Customize -> Emacs -> Packages
- ~/.xemacs/mule-packages
- ~/.xemacs/xemacs-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).
- Packages in the former directory will only be found by a Mule-enabled
-XEmacs.
+ 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:
- 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.
+ Options -> Manage Packages -> List & Install
- To install binary packages manually:
+ Or, you can get to it via the keyboard:
- 1. Download the package(s) that you want to install. Each binary
- package will typically be a gzip'd tarball.
+ M-x pui-list-packages
- 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.
+ 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.
- 3. Next, `cd' to the directory under which you want to install the
- package(s).
+ 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:
- 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:
+ M-x package-get-package-provider RET thingatpt
- gunzip < package.tar.gz | tar xvf -
+ which will return something like (fsf-compat "1.08"). You can the use
+one of the methods above for installing the package you want.
- Above, replace `package.tar.gz' with the filename of the package
- that you downloaded in step 1.
+XEmacs and Installing Packages
+------------------------------
- Of course, if you use GNU `tar', you could also use:
+ There are three main ways to install packages:
- tar xvzf package.tar.gz
+* Menu:
- 5. That's it. Quit and restart XEmacs to get it to recognize any new
- or changed packages.
+* Sumo:: All at once, using the 'Sumo Tarball'.
+* Manually:: Using individual package tarballs.
+* Automatically:: Using the package tools from XEmacs.
+* Which Packages:: Which packages to install.
+* Removing Packages:: Removing packages.
+ But regardless of the method you use to install packages, they can
+only be used by XEmacs after a restart.
\1f
-File: xemacs.info, Node: Building Packages, Prev: Using Packages, Up: Packages
+File: xemacs.info, Node: Sumo, Next: Manually, Up: Installing 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.
+Installing the Sumo Packages:
+=============================
-Prerequisites for Building Source Packages
-------------------------------------------
+ Those with little time, cheap connections and plenty of disk space
+can install all the packages at once using the sumo tarballs. Download
+the file: `xemacs-sumo.tar.gz'
- 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.
+ For an XEmacs compiled with Mule you also need:
+`xemacs-mule-sumo.tar.gz'
-What You Can Do With Source Packages
-------------------------------------
+ N.B. They are called 'Sumo Tarballs' for good reason. They are
+currently about 19MB and 4.5MB (gzipped) respectively.
- NB: A global build operation doesn't exist yet as of 13 January
-1998.
+ Install them by:
- Source packages are most useful for creating XEmacs package tarballs
-for installation into your own XEmacs installations or for distributing
-to others.
+ `cd $prefix/lib/xemacs ; gunzip -c <tarballname> | tar xvf - RET'
- Supported operations from `make' are:
+ Or, if you have GNU tar:
-`clean'
- Remove all built files except `auto-autoloads.el' and
- `custom-load.el'.
+ `cd $prefix/lib/xemacs ; tar zxvf /path/to/<tarballname> RET'
-`distclean'
- Remove XEmacs backups as well as the files deleted by `make clean'.
+ As the Sumo tarballs are not regenerated as often as the individual
+packages, it is recommended that you use the automatic package tools
+afterwards to pick up any recent updates.
-`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.
+\1f
+File: xemacs.info, Node: Manually, Next: Automatically, Prev: Sumo, Up: Installing Packages
-`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.
+Manual Package Installation:
+============================
-`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.
+ Fetch the packages from the FTP site, CD-ROM whatever. The filenames
+have the form `name-<version>-pkg.tar.gz' and are gzipped tar files. For
+a fresh install it is sufficient to untar the file at the top of the
+package hierarchy.
-`dist'
- Runs the rules `srckit' followed by `binkit'. This is primarily
- of use by XEmacs maintainers producing files for distribution.
+ Note: If you are upgrading packages already installed, it's best to
+remove the old package first *Note Removing Packages::.
-\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::.
+ For example if we are installing the `xemacs-base' package (version
+1.48):
-* Menu:
+ mkdir $prefix/lib/xemacs/xemacs-packages RET # if it does not exist yet
+ cd $prefix/lib/xemacs/xemacs-packages RET
+ gunzip -c /path/to/xemacs-base-1.48-pkg.tar.gz | tar xvf - RET
+
+ Or if you have GNU tar, the last step can be:
+
+ tar zxvf /path/to/xemacs-base-1.48-pkg.tar.gz RET
-* 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.
+ For MULE related packages, it is best to untar into the mule-packages
+hierarchy, i.e. for the `mule-base' package, version 1.37:
-\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.
+ mkdir $prefix/lib/xemacs/mule-packages RET # if it does not exist yet
+ cd $prefix/lib/xemacs/mule-packages RET
+ gunzip -c /path/to/mule-base-1.37-pkg.tar.gz | tar xvf - RET
+
+ Or if you have GNU tar, the last step can be:
+
+ tar zxvf /path/to/mule-base-1.37-pkg.tar.gz RET
\1f
-File: xemacs.info, Node: Expanding Abbrevs, Next: Editing Abbrevs, Prev: Defining Abbrevs, Up: Abbrevs
-
-Controlling Abbrev Expansion
-============================
+File: xemacs.info, Node: Automatically, Next: Which Packages, Prev: Manually, Up: Installing Packages
- 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.
+Automatic Package Installation:
+===============================
-\1f
-File: xemacs.info, Node: Editing Abbrevs, Next: Saving Abbrevs, Prev: Expanding Abbrevs, Up: Abbrevs
+ XEmacs comes with some tools to make the periodic updating and
+installing easier. It will notice if new packages or versions are
+available and will fetch them from the FTP site.
-Examining and Editing Abbrevs
-=============================
+ Unfortunately this requires that a few packages are already in place.
+You will have to install them by hand as above or use a SUMO tarball.
+This requirement will hopefully go away in the future. The packages you
+need are:
-`M-x list-abbrevs'
- Print a list of all abbrev definitions.
+ efs - To fetch the files from the FTP site or mirrors.
+ xemacs-base - Needed by efs.
+
+ and optionally:
+
+ mule-base - Needed if you want to use XEmacs with MULE.
-`M-x edit-abbrevs'
- Edit a list of abbrevs; you can add, alter, or remove definitions.
+ After installing these by hand, fire up XEmacs and follow these
+steps.
- The output from `M-x list-abbrevs' looks like this:
+ Note: The menus in XEmacs 21.2.x and up have changed slightly, so
+where I mention "Options -> Manage Packages", substitute "Tools ->
+Packages".
- (lisp-mode-abbrev-table)
- "dk" 0 "define-key"
- (global-abbrev-table)
- "dfn" 0 "definition"
+ 1. Choose a download site. via menu: Options -> Manages Packages ->
+ Add Download Site via keyb: `M-x customize-variable RET
+ package-get-remote RET' (put in the details of remote host and
+ directory)
-(Some blank lines of no semantic significance, and some other abbrev
-tables, have been omitted.)
+ If the package tarballs _AND_ the package-index file are in a
+ local directory, you can: `M-x pui-add-install-directory RET'
- 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.
+ 2. Obtain a list of packages and display the list in a buffer named
+ `*Packages*'. menu: Options -> Manage Packages -> List & Install
+ keyb: `M-x pui-list-packages RET'
- 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.
+ XEmacs will now connect to the remote site and download the latest
+ package-index file. If you see an error about the package-index
+ entries not being PGP signed, you can safely ignore this because
+ PGP has not been integrated into the XEmacs package tools yet.
- `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.
+ 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:
- `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.
+ `-'
+ The package has not been installed.
-\1f
-File: xemacs.info, Node: Saving Abbrevs, Next: Dynamic Abbrevs, Prev: Editing Abbrevs, Up: Abbrevs
+ `*'
+ The package has been installed, but a newer version is
+ available. The current version is out-of-date.
-Saving Abbrevs
-==============
+ `+'
+ The package has been marked for installation/update.
- These commands allow you to keep abbrev definitions between editing
-sessions.
+ If there is no character in the first column, the package has been
+ installed and is up-to-date.
-`M-x write-abbrev-file'
- Write a file describing all defined abbrevs.
+ 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.
-`M-x read-abbrev-file'
- Read such an abbrev file and define abbrevs as specified there.
+ Key summary:
-`M-x quietly-read-abbrev-file'
- Similar, but do not display a message about what is going on.
+ `?'
+ Display simple help.
-`M-x define-abbrevs'
- Define abbrevs from buffer.
+ `<RET>'
+ `<Mouse-2>'
+ Toggle between selecting and unselecting a package for
+ installation.
-`M-x insert-abbrevs'
- Insert all abbrevs and their expansions into the buffer.
+ `x'
+ Install selected packages.
- 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'.
+ `<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.
- `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"'.
+ `v'
+ Toggle between verbose and non-verbose package display.
- 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.
+ `g'
+ Refresh the package display.
- 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.
+ `q'
+ Kill the package buffer.
-\1f
-File: xemacs.info, Node: Dynamic Abbrevs, Prev: Saving Abbrevs, Up: Abbrevs
+ Moving the mouse over a package will also cause additional
+ information about the package to be displayed in the minibuffer.
-Dynamic Abbrev Expansion
-========================
+ 3. Choose the packages you wish to install. mouse: Click button 2 on
+ the package name. keyb: `RET' on the package name
- 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.
+ 4. Make sure you have everything you need. menu: Packages -> Add
+ Required keyb: `r'
-\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'.
+ XEmacs will now search for packages that are required by the ones
+ that you have chosen to install and offer to select those packages
+ also.
-* Menu:
+ For novices and gurus alike, this step can save your bacon. It's
+ easy to forget to install a critical package.
-* 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.
+ 5. Download and install the packages. menu: Packages ->
+ Install/Remove Selected keyb: `x'
-\1f
-File: xemacs.info, Node: Basic Picture, Next: Insert in Picture, Prev: Picture, Up: Picture
+ You can also install packages using a semi-manual interface:
-Basic Editing in Picture Mode
-=============================
+ M-x package-get-all <return>
- Most keys do the same thing in Picture mode that they usually do,
-but do it in a quarter-plane style. For example, `C-f' is rebound to
-run `picture-forward-column', which moves point one column to the
-right, by inserting a space if necessary, so that the actual end of the
-line makes no difference. `C-b' is rebound to run
-`picture-backward-column', which always moves point left one column,
-converting a tab to multiple spaces if necessary. `C-n' and `C-p' are
-rebound to run `picture-move-down' and `picture-move-up', which can
-either insert spaces or convert tabs as necessary to make sure that
-point stays in exactly the same column. `C-e' runs
-`picture-end-of-line', which moves to after the last non-blank
-character on the line. There was no need to change `C-a', as the choice
-of screen model does not affect beginnings of lines.
-
- Insertion of text is adapted to the quarter-plane screen model
-through the use of Overwrite mode (*note Minor Modes::).
-Self-inserting characters replace existing text, column by column,
-rather than pushing existing text to the right. <RET> runs
-`picture-newline', which just moves to the beginning of the following
-line so that new text will replace that line.
-
- Text is erased instead of deleted and killed. <DEL>
-(`picture-backward-clear-column') replaces the preceding character with
-a space rather than removing it. `C-d' (`picture-clear-column') does
-the same in a forward direction. `C-k' (`picture-clear-line') really
-kills the contents of lines, but never removes the newlines from a
-buffer.
-
- To do actual insertion, you must use special commands. `C-o'
-(`picture-open-line') creates a blank line, but does so after the
-current line; it never splits a line. `C-M-o', `split-line', makes
-sense in Picture mode, so it remains unchanged. <LFD>
-(`picture-duplicate-line') inserts another line with the same contents
-below the current line.
-
- To actually delete parts of the picture, use `C-w', or with `C-c
-C-d' (which is defined as `delete-char', as `C-d' is in other modes),
-or with one of the picture rectangle commands (*note Rectangles in
-Picture::).
+ Enter the name of the package (e.g., `prog-modes'), and XEmacs will
+search for the latest version and install it and any packages that it
+depends upon.
\1f
-File: xemacs.info, Node: Insert in Picture, Next: Tabs in Picture, Prev: Basic Picture, Up: Picture
+File: xemacs.info, Node: Which Packages, Next: Removing Packages, Prev: Automatically, Up: Installing Packages
-Controlling Motion After Insert
-===============================
+Which Packages to Install:
+==========================
- Since "self-inserting" characters just overwrite and move point in
-Picture mode, there is no essential restriction on how point should be
-moved. Normally point moves right, but you can specify any of the eight
-orthogonal or diagonal directions for motion after a "self-inserting"
-character. This is useful for drawing lines in the buffer.
+ This is difficult to say. When in doubt install a package. If you
+administrate a big site it might be a good idea to just install
+everything. A good minimal set of packages for XEmacs-latin1 would be
-`C-c <'
- Move left after insertion (`picture-movement-left').
+ xemacs-base, xemacs-devel, c-support, cc-mode, debug, dired, efs,
+edit-utils, fsf-compat, mail-lib, net-utils, os-utils, prog-modes,
+text-modes, time
-`C-c >'
- Move right after insertion (`picture-movement-right').
+ If you are using the XEmacs package tools, don't forget to do:
-`C-c ^'
- Move up after insertion (`picture-movement-up').
+ Packages -> Add Required
-`C-c .'
- Move down after insertion (`picture-movement-down').
+ To make sure you have everything that the packages you have chosen to
+install need.
-`C-c `'
- Move up and left ("northwest") after insertion
- (`picture-movement-nw').
+ See also *Note Available Packages:: for further descriptions of the
+individual packages.
-`C-c ''
- Move up and right ("northeast") after insertion
- (`picture-movement-ne').
+\1f
+File: xemacs.info, Node: Removing Packages, Prev: Which Packages, Up: Installing Packages
-`C-c /'
- Move down and left ("southwest") after insertion
- (`picture-movement-sw').
+Removing Packages:
+==================
-`C-c \'
- Move down and right ("southeast") after insertion
- (`picture-movement-se').
+ Because the exact files and their locations contained in a package
+may change it is recommended to remove a package first before
+installing a new version. In order to facilitate removal each package
+contains an `pgkinfo/MANIFEST.pkgname' file which list all the files
+belonging to the package.
- Two motion commands move based on the current Picture insertion
-direction. The command `C-c C-f' (`picture-motion') moves in the same
-direction as motion after "insertion" currently does, while `C-c C-b'
-(`picture-motion-reverse') moves in the opposite direction.
+ No need to panic, you don't have to go through the
+`pkinfo/MANIFEST.pkgname' and manually delete the files. Instead, use
+`M-x package-admin-delete-binary-package RET'.
-\1f
-File: xemacs.info, Node: Tabs in Picture, Next: Rectangles in Picture, Prev: Insert in Picture, Up: Picture
-
-Picture Mode Tabs
-=================
-
- Two kinds of tab-like action are provided in Picture mode.
-Context-based tabbing is done with `M-<TAB>' (`picture-tab-search').
-With no argument, it moves to a point underneath the next "interesting"
-character that follows whitespace in the previous non-blank line.
-"Next" here means "appearing at a horizontal position greater than the
-one point starts out at". With an argument, as in `C-u M-<TAB>', the
-command moves to the next such interesting character in the current
-line. `M-<TAB>' does not change the text; it only moves point.
-"Interesting" characters are defined by the variable
-`picture-tab-chars', which contains a string of characters considered
-interesting. Its default value is `"!-~"'.
-
- <TAB> itself runs `picture-tab', which operates based on the current
-tab stop settings; it is the Picture mode equivalent of
-`tab-to-tab-stop'. Without arguments it just moves point, but with a
-numeric argument it clears the text that it moves over.
-
- The context-based and tab-stop-based forms of tabbing are brought
-together by the command `C-c <TAB>' (`picture-set-tab-stops'.) This
-command sets the tab stops to the positions which `M-<TAB>' would
-consider significant in the current line. If you use this command with
-<TAB>, you can get the effect of context-based tabbing. But `M-<TAB>'
-is more convenient in the cases where it is sufficient.
+ Note that the interactive package tools included with XEmacs already
+do this for you.
\1f
-File: xemacs.info, Node: Rectangles in Picture, Prev: Tabs in Picture, Up: Picture
+File: xemacs.info, Node: Building Packages, Next: Local.rules File, Prev: Installing Packages, Up: Packages
-Picture Mode Rectangle Commands
-===============================
+Building Packages:
+==================
- Picture mode defines commands for working on rectangular pieces of
-the text in ways that fit with the quarter-plane model. The standard
-rectangle commands may also be useful (*note Rectangles::).
+ Currently, source packages are only available via anonymous CVS. See
+<http://cvs.xemacs.org/> for details of checking out the
+`xemacs-packages' module.
-`C-c C-k'
- Clear out the region-rectangle (`picture-clear-rectangle'). With
- argument, kill it.
+Prerequisites for Building Source Packages
+------------------------------------------
-`C-c C-w R'
- Similar but save rectangle contents in register R first
- (`picture-clear-rectangle-to-register').
+`GNU cp'
-`C-c C-y'
- Copy last killed rectangle into the buffer by overwriting, with
- upper left corner at point (`picture-yank-rectangle'). With
- argument, insert instead.
+`GNU ginstall'
+ (or a BSD compatible install program).
-`C-c C-x R'
- Similar, but use the rectangle in register R
- (`picture-yank-rectangle-from-register').
+`GNU make'
+ (3.75 or later preferred).
- The picture rectangle commands `C-c C-k' (`picture-clear-rectangle')
-and `C-c C-w' (`picture-clear-rectangle-to-register') differ from the
-standard rectangle commands in that they normally clear the rectangle
-instead of deleting it; this is analogous with the way `C-d' is changed
-in Picture mode.
+`makeinfo'
+ (1.68 from texinfo-3.11 or later required).
- However, deletion of rectangles can be useful in Picture mode, so
-these commands delete the rectangle if given a numeric argument.
+`GNU tar'
+ (or equivalent).
- The Picture mode commands for yanking rectangles differ from the
-standard ones in overwriting instead of inserting. This is the same
-way that Picture mode insertion of other text is different from other
-modes. `C-c C-y' (`picture-yank-rectangle') inserts (by overwriting)
-the rectangle that was most recently killed, while `C-c C-x'
-(`picture-yank-rectangle-from-register') does for the rectangle found
-in a specified register.
+`GNU gzip'
+ (or equivalent).
- Since most region commands in Picture mode operate on rectangles,
-when you select a region of text with the mouse in Picture mode, it is
-highlighted as a rectangle.
+`A properly configured `Local.rules' file.'
+ *Note Local.rules File::. And of course, XEmacs 21.0 or higher.
-\1f
-File: xemacs.info, Node: Sending Mail, Next: Reading Mail, Prev: Picture, Up: Top
+What You Can Do With Source Packages
+------------------------------------
-Sending Mail
-************
+ The packages CVS sources are most useful for creating XEmacs package
+tarballs for installation into your own XEmacs installations or for
+distributing to others.
- To send a message in Emacs, start by typing the command (`C-x m') to
-select and initialize the `*mail*' buffer. You can then edit the text
-and headers of the message in the mail buffer, and type the command
-(`C-c C-c') to send the message.
+ Supported operations from `make' are:
-`C-x m'
- Begin composing a message to send (`mail').
+`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.
-`C-x 4 m'
- Likewise, but display the message in another window
- (`mail-other-window').
+`bindist'
+ Does a `make all' as well as create a binary package tarball in the
+ staging directory.
-`C-c C-c'
- In Mail mode, send the message and switch to another buffer
- (`mail-send-and-exit').
+`install'
+ Bytecompile all files, build and bytecompile byproduct files like
+ `auto-autoloads.el' and `custom-load.el'. Create info version of
+ TeXinfo documentation if present. And install everything into the
+ staging directory.
- The command `C-x m' (`mail') selects a buffer named `*mail*' and
-initializes it with the skeleton of an outgoing message. `C-x 4 m'
-(`mail-other-window') selects the `*mail*' buffer in a different
-window, leaving the previous current buffer visible.
+`srckit'
+ Usually aliased to `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.
- Because the buffer for mail composition is an ordinary Emacs buffer,
-you can switch to other buffers while in the middle of composing mail,
-and switch back later (or never). If you use the `C-x m' command again
-when you have been composing another message but have not sent it, a
-new mail buffer will be created; in this way, you can compose multiple
-messages at once. You can switch back to and complete an unsent
-message by using the normal buffer selection mechanisms.
+`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.
- `C-u C-x m' is another way to switch back to a message in progress:
-it will search for an existing, unsent mail message buffer and select
-it.
+`dist'
+ Runs the rules `srckit' followed by `binkit'. This is primarily
+ of use by XEmacs maintainers producing files for distribution.
-* Menu:
+`clean'
+ Remove all built files except `auto-autoloads.el' and
+ `custom-load.el'.
-* Format: Mail Format. Format of the mail being composed.
-* Headers: Mail Headers. Details of allowed mail header fields.
-* Mode: Mail Mode. Special commands for editing mail being composed.
+`distclean'
+ Remove all created files.
\1f
-File: xemacs.info, Node: Mail Format, Next: Mail Headers, Prev: Sending Mail, Up: Sending Mail
+File: xemacs.info, Node: Local.rules File, Next: Creating Packages, Prev: Building Packages, Up: Packages
-The Format of the Mail Buffer
-=============================
+The Local.rules File:
+=====================
- In addition to the "text" or contents, a message has "header
-fields", which say who sent it, when, to whom, why, and so on. Some
-header fields, such as the date and sender, are created automatically
-after the message is sent. Others, such as the recipient names, must
-be specified by you in order to send the message properly.
+ This file is used when building and installing packages from source.
+In the top level of the CVS module, `xemacs-packages', contains the
+file, `Local.rules.template'. Simply copy that to `Local.rules' and
+edit it to suit your needs.
- Mail mode provides a few commands to help you edit some header
-fields, and some are preinitialized in the buffer automatically at
-times. You can insert or edit any header fields using ordinary editing
-commands.
+ These are the variables in 'Local.rules' that you will need to
+address.
- The line in the buffer that says:
+SYMLINK =
+ Set this to 't' if you want to do a "run in place". Setting this
+ doesn't work well with 'make bindist'
- --text follows this line--
+XEMACS_PACKAGES =
+ This is where you set the normal packages that you want to
+ install. eg:
+ XEMACS_PACKAGES = libs/xemacs-base comm/bbdb
-is a special delimiter that separates the headers you have specified
-from the text. Whatever follows this line is the text of the message;
-the headers precede it. The delimiter line itself does not appear in
-the message actually sent. The text used for the delimiter line is
-controlled by the variable `mail-header-separator'.
+XEMACS_STAGING = ${XEMACS_PACKAGES_BASE}/../PACKAGES
+ Set this to where you want normal packages to be installed to.
- Here is an example of what the headers and text in the `*mail*'
-buffer might look like.
+PACKAGE_INDEX = PACKAGE-INDEX
+ If you want the package-index file to have a different name,
+ change this.
- To: rms@mc
- CC: mly@mc, rg@oz
- Subject: The XEmacs User's Manual
- --Text follows this line--
- Please ignore this message.
+BUILD_WITHOUT_MULE =
+ Building from CVS defaults to building the Mule packages. Set
+ this to 't' if you don't want/have Mule
-\1f
-File: xemacs.info, Node: Mail Headers, Next: Mail Mode, Prev: Mail Format, Up: Sending Mail
+MULE_PACKAGES =
+ Same as for 'XEMACS_PACKAGES' except you list the Mule packages
+ you want to install here. eg:
+ MULE_PACKAGES = mule/mule-base mule/skk
-Mail Header Fields
-==================
+MULE_STAGING = ${XEMACS_PACKAGES_BASE}/../MULE-PACKAGES
+ Set this to where you want Mule packages installed to. Note:
+ 'make bindist' does not use this variable.
- There are several header fields you can use in the `*mail*' buffer.
-Each header field starts with a field name at the beginning of a line,
-terminated by a colon. It does not matter whether you use upper or
-lower case in the field name. After the colon and optional whitespace
-comes the contents of the field.
-
-`To'
- This field contains the mailing addresses of the message.
-
-`Subject'
- The contents of the `Subject' field should be a piece of text that
- says what the message is about. Subject fields are useful because
- most mail-reading programs can provide a summary of messages,
- listing the subject of each message but not its text.
-
-`CC'
- This field contains additional mailing addresses to send the
- message to, but whose readers should not regard the message as
- addressed to them.
-
-`BCC'
- This field contains additional mailing addresses to send the
- message to, but which should not appear in the header of the
- message actually sent.
-
-`FCC'
- This field contains the name of one file (in Unix mail file
- format) to which a copy of the message should be appended when the
- message is sent.
-
-`From'
- Use the `From' field to say who you are, when the account you are
- using to send the mail is not your own. The contents of the
- `From' field should be a valid mailing address, since replies will
- normally go there.
-
-`Reply-To'
- Use the `Reply-To' field to direct replies to a different address,
- not your own. `From' and `Reply-To' have the same effect on where
- replies go, but they convey a different meaning to the person who
- reads the message.
-
-`In-Reply-To'
- This field contains a piece of text describing a message you are
- replying to. Some mail systems can use the information to
- correlate related pieces of mail. This field is normally filled
- in by your mail handling package when you are replying to a
- message and you never need to think about it.
-
-The `To', `CC', `BCC' and `FCC' fields can appear any number of times,
-to specify many places to send the message.
-
-The `To', `CC', and `BCC', fields can have continuation lines. All the
-lines starting with whitespace, following the line on which the field
-starts, are considered part of the field. For example,
-
- To: foo@here, this@there,
- me@gnu.cambridge.mass.usa.earth.spiral3281
-
-If you have a `~/.mailrc' file, Emacs scans it for mail aliases the
-first time you try to send mail in an Emacs session. Emacs expands
-aliases found in the `To', `CC', and `BCC' fields where appropriate.
-You can set the variable `mail-abbrev-mailrc-file' to the name of the
-file with mail aliases. If `nil', `~/.mailrc' is used.
-
- Your `.mailrc' file ensures that word-abbrevs are defined for each
-of your mail aliases when point is in a `To', `CC', `BCC', or `From'
-field. The aliases are defined in your `.mailrc' file or in a file
-specified by the MAILRC environment variable if it exists. Your mail
-aliases expand any time you type a word-delimiter at the end of an
-abbreviation.
-
- In this version of Emacs, what you see is what you get: in contrast
-to some other versions, no abbreviations are expanded after you have
-sent the mail. This means you don't suffer the annoyance of having the
-system do things behind your back--if the system rewrites an address
-you typed, you know it immediately, instead of after the mail has been
-sent and it's too late to do anything about it. For example, you will
-never again be in trouble because you forgot to delete an old alias
-from your `.mailrc' and a new local user is given a userid which
-conflicts with one of your aliases.
-
- Your mail alias abbrevs are in effect only when point is in an
-appropriate header field. The mail aliases will not expand in the body
-of the message, or in other header fields. The default mode-specific
-abbrev table `mail-mode-abbrev-table' is used instead if defined. That
-means if you have been using mail-mode specific abbrevs, this code will
-not adversely affect you. You can control which header fields the
-abbrevs are used in by changing the variable `mail-abbrev-mode-regexp'.
-
- If auto-fill mode is on, abbrevs wrap at commas instead of at word
-boundaries, and header continuation lines will be properly indented.
-
- You can also insert a mail alias with
-`mail-interactive-insert-alias'. This function, which is bound to `C-c
-C-a', prompts you for an alias (with completion) and inserts its
-expansion at point.
-
- In this version of Emacs, it is possible to have lines like the
-following in your `.mailrc' file:
-
- alias someone "John Doe <doe@quux.com>"
-
- That is, if you want an address to have embedded spaces, simply
-surround it with double-quotes. The quotes are necessary because the
-format of the `.mailrc' file uses spaces as address delimiters.
-
- Aliases in the `.mailrc' file may be nested. For example, assume you
-define aliases like:
- alias group1 fred ethel
- alias group2 larry curly moe
- alias everybody group1 group2
-
- When you now type `everybody' on the `To' line, it will expand to:
- fred, ethyl, larry, curly, moe
-
- Aliases may contain forward references; the alias of `everybody' in
-the example above can precede the aliases of `group1' and `group2'.
-
- In this version of Emacs, you can use the `source' `.mailrc' command
-for reading aliases from some other file as well.
-
- Aliases may contain hyphens, as in `"alias foo-bar foo@bar"', even
-though word-abbrevs normally cannot contain hyphens.
-
- To read in the contents of another `.mailrc'-type file from Emacs,
-use the command `M-x merge-mail-aliases'. The `rebuild-mail-aliases'
-command is similar, but deletes existing aliases first.
-
- If you want multiple addresses separated by a string other than `,'
-(a comma), then set the variable `mail-alias-seperator-string' to it.
-This has to be a comma bracketed by whitespace if you want any kind of
-reasonable behavior.
-
- If the variable `mail-archive-file-name' is non-`nil', it should be
-a string naming a file. Each time you start to edit a message to send,
-an `FCC' field is entered for that file. Unless you remove the `FCC'
-field, every message is written into that file when it is sent.
+XEMACS = XEMACS
+ If your XEmacs isn't in your path, change this.
-\1f
-File: xemacs.info, Node: Mail Mode, Prev: Mail Headers, Up: Sending Mail
-
-Mail Mode
-=========
-
- The major mode used in the `*mail*' buffer is Mail mode. Mail mode
-is similar to Text mode, but several commands are provided on the `C-c'
-prefix. These commands all deal specifically with editing or sending
-the message.
-
-`C-c C-s'
- Send the message, and leave the `*mail*' buffer selected
- (`mail-send').
-
-`C-c C-c'
- Send the message, and select some other buffer
- (`mail-send-and-exit').
-
-`C-c C-f C-t'
- Move to the `To' header field, creating one if there is none
- (`mail-to').
-
-`C-c C-f C-s'
- Move to the `Subject' header field, creating one if there is none
- (`mail-subject').
-
-`C-c C-f C-c'
- Move to the `CC' header field, creating one if there is none
- (`mail-cc').
-
-`C-c C-w'
- Insert the file `~/.signature' at the end of the message text
- (`mail-signature').
-
-`C-c C-y'
- Yank the selected message (`mail-yank-original').
-
-`C-c C-q'
- Fill all paragraphs of yanked old messages, each individually
- (`mail-fill-yanked-message').
-
-`<button3>'
- Pops up a menu of useful mail-mode commands.
-
- There are two ways to send a message. `C-c C-c'
-(`mail-send-and-exit') is the usual way to send the message. It sends
-the message and then deletes the window (if there is another window) or
-switches to another buffer. It puts the `*mail*' buffer at the lowest
-priority for automatic reselection, since you are finished with using
-it. `C-c C-s' (`mail-send') sends the message and marks the `*mail*'
-buffer unmodified, but leaves that buffer selected so that you can
-modify the message (perhaps with new recipients) and send it again.
-
- Mail mode provides some other special commands that are useful for
-editing the headers and text of the message before you send it. There
-are three commands defined to move point to particular header fields,
-all based on the prefix `C-c C-f' (`C-f' is for "field"). They are
-`C-c C-f C-t' (`mail-to') to move to the `To' field, `C-c C-f C-s'
-(`mail-subject') for the `Subject' field, and `C-c C-f C-c' (`mail-cc')
-for the `CC' field. These fields have special motion commands because
-they are edited most frequently.
-
- `C-c C-w' (`mail-signature') adds a standard piece of text at the
-end of the message to say more about who you are. The text comes from
-the file `.signature' in your home directory.
-
- When you use an Rmail command to send mail from the Rmail mail
-reader, you can use `C-c C-y' `mail-yank-original' inside the `*mail*'
-buffer to insert the text of the message you are replying to. Normally
-Rmail indents each line of that message four spaces and eliminates most
-header fields. A numeric argument specifies the number of spaces to
-indent. An argument of just `C-u' says not to indent at all and not to
-eliminate anything. `C-c C-y' always uses the current message from the
-`RMAIL' buffer, so you can insert several old messages by selecting one
-in `RMAIL', switching to `*mail*' and yanking it, then switching back
-to `RMAIL' to select another.
-
- After using `C-c C-y', you can use the command `C-c C-q'
-(`mail-fill-yanked-message') to fill the paragraphs of the yanked old
-message or messages. One use of `C-c C-q' fills all such paragraphs,
-each one separately.
-
- Clicking the right mouse button in a mail buffer pops up a menu of
-the above commands, for easy access.
-
- Turning on Mail mode (which `C-x m' does automatically) calls the
-value of `text-mode-hook', if it is not void or `nil', and then calls
-the value of `mail-mode-hook' if that is not void or `nil'.
+XEMACS_NATIVE_NT =
+ Set this to 't' if you are building on WinNT.
-\1f
-File: xemacs.info, Node: Reading Mail, Next: Calendar/Diary, Prev: Sending Mail, Up: Top
-
-Reading Mail
-************
-
- XEmacs provides three separate mail-reading packages. Each one
-comes with its own manual, which is included standard with the XEmacs
-distribution.
-
- The recommended mail-reading package for new users is VM. VM works
-with standard Unix-mail-format folders and was designed as a replacement
-for the older Rmail.
-
- XEmacs also provides a sophisticated and comfortable front-end to the
-MH mail-processing system, called `mh-e'. Unlike in other mail
-programs, folders in MH are stored as file-system directories, with
-each message occupying one (numbered) file. This facilitates working
-with mail using shell commands, and many other features of MH are also
-designed to integrate well with the shell and with shell scripts. Keep
-in mind, however, that in order to use mh-e you must have the MH
-mail-processing system installed on your computer.
-
- Finally, XEmacs provides the Rmail package. Rmail is (currently) the
-only mail reading package distributed with FSF GNU Emacs, and is
-powerful in its own right. However, it stores mail folders in a special
-format called `Babyl', that is incompatible with all other
-frequently-used mail programs. A utility program is provided for
-converting Babyl folders to standard Unix-mail format; however, unless
-you already have mail in Babyl-format folders, you should consider
-using VM or mh-e instead. (If at times you have to use FSF Emacs, it is
-not hard to obtain and install VM for that editor.)
+INSTALL = INSTALL -C
+ The path to your BSD compatible install program.
+
+TAR = TAR
+ The path to your tar program
+
+BZIP2 =
+ If you want bzip2 tarballs, set this.
+
+MAKEINFO = MAKEINFO
+ The path to your makeinfo program
\1f
-File: xemacs.info, Node: Calendar/Diary, Next: Sorting, Prev: Reading Mail, Up: Top
-
-Calendar Mode and the Diary
-===========================
-
- Emacs provides the functions of a desk calendar, with a diary of
-planned or past events. To enter the calendar, type `M-x calendar';
-this displays a three-month calendar centered on the current month, with
-point on the current date. With a numeric argument, as in `C-u M-x
-calendar', it prompts you for the month and year to be the center of the
-three-month calendar. The calendar uses its own buffer, whose major
-mode is Calendar mode.
-
- `Button2' in the calendar brings up a menu of operations on a
-particular date; `Buttons3' brings up a menu of commonly used calendar
-features that are independent of any particular date. To exit the
-calendar, type `q'. *Note Customizing the Calendar and Diary:
-(elisp)Calendar, for customization information about the calendar and
-diary.
+File: xemacs.info, Node: Creating Packages, Next: Available Packages, Prev: Local.rules File, Up: Packages
-* Menu:
+Creating Packages:
+==================
+
+ Creating a package from an existing Lisp library is not very
+difficult.
+
+ In addition to the Lisp libraries themselves, you need a
+`package-info.in' file and a simple `Makefile'. The rest is done by
+`XEmacs.rules', part of the packaging system infrastructure.
+
+ `package-info.in' contains a single Lisp form like this:
+
+ (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
+ ))
+
+ You must fill in the four commented lines. The value of `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 `xemacs' and `mule'. Write them as unquoted
+symbols. The `description' is a quoted Lisp string; use the usual
+conventions. The value for `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 `provides' line is desirable, but as yet
+undone.
+
+ The variables in upper-case are references to variables set in the
+`Makefile' or automatically generated. Do not change them; they are
+automatically filled in by the build process.
+
+ The remaining lines refer to implementation constants
+(`standards-version'), or features that are unimplemented or have been
+removed (`priority' and `dump'). The `type' line is not normally
+relevant to external maintainers; the alternate value is `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
+`prog-modes'. Single-file packages are basically for administrative
+convenience, and new packages should generally be created as regular
+packages.
+
+ The `Makefile' is quite stylized. The idea is similar to an
+`Imakefile' or an `automake' file: the complexity is hidden in generic
+rules files, in this case the `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' `Makefile's
+contain a copyright notice, a few variable definitions, an include for
+`XEmacs.rules', and a couple of standard targets.
+
+ The first few `make' variables defined are `VERSION',
+`AUTHOR_VERSION', `MAINTAINER', `PACKAGE', `PKG_TYPE', `REQUIRES', and
+`CATEGORY'. All but one were described in the description of
+`package-info.in'. The last is an admistrative grouping. Current
+categories include `comm', `games', `libs', `mule', `oa', `os', `prog',
+and `wp'. *Note Available Packages::, for a list of categories.
+
+ Next, define the variable `ELCS'. This contains the list of the
+byte-compiled Lisp files used by the package. These files and their
+`.el' versions will be included in the binary package. If there are
+other files (such as extra Lisp sources or an upstream `Makefile') that
+are normally placed in the installed Lisp directory, but not
+byte-compiled, they can be listed as the value of `EXTRA_SOURCES'.
+
+ The include is simply
+ include ../../XEmacs.rules
+
+ The standard targets follow. These are
+
+ all:: $(ELCS) auto-autoloads.elc
+
+ srckit: srckit-alias
+
+ binkit: binkit-alias
+
+ Other targets (such as Texinfo sources) may need to be added as
+dependencies for the `all' target. Dependencies for `srckit' and
+`binkit' (that is, values for SRCKIT-ALIAS and BINKIT-ALIAS) are
+defined in `XEmacs.rules'. The most useful of these values are given
+in the following table.
+
+SRCKIT-ALIAS
+ Usually set to `srckit-std'.
+
+BINKIT-ALIAS
+ May be set 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.
-* Calendar Motion:: Moving through the calendar; selecting a date.
-* Scroll Calendar:: Bringing earlier or later months onto the screen.
-* Mark and Region:: Remembering dates, the mark ring.
-* General Calendar:: Exiting or recomputing the calendar.
-* LaTeX Calendar:: Print a calendar using LaTeX.
-* Holidays:: Displaying dates of holidays.
-* Sunrise/Sunset:: Displaying local times of sunrise and sunset.
-* Lunar Phases:: Displaying phases of the moon.
-* Other Calendars:: Converting dates to other calendar systems.
-* Diary:: Displaying events from your diary.
-* Calendar Customization:: Altering the behavior of the features above.
+ Data files include things like pixmaps for a package-specific
+toolbar, and are normally installed in `etc/PACKAGE_NAME'. A few
+packages have needs beyond the basic templates. See `XEmacs.rules' or
+a future revision of this manual for details.
projects / chise / xemacs-chise.git- / blobdiff