X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Fxemacs.info-13;h=7e434aac210cc61b537ce6d17aa50459b1c25f1f;hb=16d0840d3eada757f529c34fddc0c2fb8f17b9de;hp=bfce027ac85145fd35f2d621558887d6243b09ac;hpb=1d9bc86590766427e2431876a50d78206a99edd5;p=chise%2Fxemacs-chise.git diff --git a/info/xemacs.info-13 b/info/xemacs.info-13 index bfce027..7e434aa 100644 --- a/info/xemacs.info-13 +++ b/info/xemacs.info-13 @@ -1,4 +1,4 @@ -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 @@ -30,1309 +30,1095 @@ versions, except that the sections entitled "The GNU Manifesto", translation approved by the author instead of in the original English.  -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 `--pkg.tar.gz'. - - If you have EFS *Note (EFS)::, packages can be installed over the -network. Alternatively, if you have copies of the packages locally, -you can install packages from a local disk or CDROM. - - The file `etc/PACKAGES' in the core distribution contains a list of -the packages available at the time of the XEmacs release. Packages are -also listed on the `Options' menu under: - - Options->Customize->Emacs->Packages - - However, don't select any of these menu picks unless you actually -want to install the given package (and have properly configured your -system to do so). - - You can also get a list of available packages, and whether or not -they are installed, using the visual package browser and installer. -You can access it via the menus: - - Options->Manage Packages->List & Install - - Or, you can get to it via the keyboard: - - M-x pui-list-packages +Libraries of Lisp Code for Emacs +================================ - Hint to system administrators of multi-user systems: it might be a -good idea to install all packages and not interfere with the wishes of -your users. - - If you can't find which package provides the feature you require, try -using the `package-get-package-provider' function. Eg., if you know -that you need `thingatpt', type: - - M-x package-get-package-provider RET thingatpt - - which will return something like (fsf-compat "1.06"). You can the use -one of the methods above for installing the package you want. - -XEmacs and Installing Packages ------------------------------- - - Normally, packages are installed over the network, using EFS *Note -(EFS)::. However, you may not have network access, or you may already -have some or all of the packages on a local disk, such as a CDROM. If -you want to install from a local disk, you must first tell XEmacs where -to find the package binaries. This is done by adding a line like the -following to your init file: - - (setq package-get-remote (cons (list nil "/my/path/to/package/binaries") - package-get-remote)) + 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::). - *Note Init File::. - - Here, you'd change `/my/path/to/package/binaries' to be the path to -your local package binaries. Next, restart XEmacs, and you're ready to -go (advanced users can just re-evaluate the sexp). - - If you are installing from a temporary, one-time directory, you can -also add these directory names to `package-get-remote' using: - - M-x pui-add-install-directory - - Note, however, that any directories added using this function are not -saved; this information will be lost when you quit XEmacs. - - If you're going to install over the network, you only have to insure -that EFS *Note (EFS):: works, and that it can get outside a firewall, if -you happen to be behind one. You shouldn't have to do anything else; -XEmacs already knows where to go. However you can add your own mirrors -to this list. See `package-get-remote'. - - The easiest way to install a package is to use the visual package -browser and installer, using the menu pick: - - Options->Manage Packages->List & Install - or - Options->Manage Packages->Using Custom->Select-> ... - - You can also access it using the keyboard: - - M-x pui-list-packages - - The visual package browser will then display a list of all packages. -Help information will be displayed at the very bottom of the buffer; you -may have to scroll down to see it. You can also press `?' to get the -same help. From this buffer, you can tell the package status by the -character in the first column: - -`-' - The package has not been installed. +* Menu: -`*' - The package has been installed, but a newer version is available. - The current version is out-of-date. +* 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. -`+' - The package has been marked for installation/update. + +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'. - If there is no character in the first column, the package has been -installed and is up-to-date. + +File: xemacs.info, Node: Compiling Libraries, Next: Mocklisp, Prev: Loading, Up: Lisp Libraries - From here, you can select or unselect packages for installation using -the 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. +Compiling Libraries +------------------- - Key summary: + 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. -`?' - Display simple help. + +File: xemacs.info, Node: Mocklisp, Prev: Compiling Libraries, Up: Lisp Libraries -`' -`' - Toggle between selecting and unselecting a package for - installation. +Converting Mocklisp to Lisp +--------------------------- -`x' - Install selected packages. + 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. -`' - 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. + 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". -`v' - Toggle between verbose and non-verbose package display. + +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-' + 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-' (`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-' was typed. + + `M-' can easily confuse users, especially on keyboards with +autorepeat, where it can result from holding down the 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. -`g' - Refresh the package display. + +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-', except that `e' is not normally disabled like `M-'. `q' - Kill the package buffer. - - Moving the mouse over a package will also cause additional -information about the package to be displayed in the minibuffer. - -Other package installation interfaces -------------------------------------- - - For an alternative package interface, you can select packages from -the customize menus, under: - - Options->Customize->Emacs->Packages-> ... - or - Options->Manage Packages->Using Custom->Select-> ... - - Set their state to on, and then do: - - Options->Manage Packages->Using Custom->Update Packages - - This will automatically retrieve the packages you have selected from -the XEmacs ftp site or your local disk, and install them into XEmacs. -Additionally it will update any packages you already have installed to -the newest version. Note that if a package is newly installed you will -have to restart XEmacs for the change to take effect. - - You can also install packages using a semi-manual interface: - - M-x package-get-all - - Enter the name of the package (e.g., `prog-modes'), and XEmacs will -search for the latest version (as listed in the lisp file -`lisp/package-get-base.el'), and install it and any packages that it -depends upon. - -Manual Binary Package Installation ----------------------------------- + Terminate the program being debugged; return to top-level Emacs + command execution. - 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: + If the debugger was entered due to a `C-g' but you really want to + quit, not to debug, use the `q' command. - ~/.xemacs/mule-packages - ~/.xemacs/xemacs-packages +`r' + Return a value from the debugger. The value is computed by + reading an expression with the minibuffer and evaluating it. - Packages in the former directory will only be found by a Mule-enabled -XEmacs. + 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. - 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. + 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'. - To install binary packages manually: + +File: xemacs.info, Node: Lisp Interaction, Next: External Lisp, Prev: Lisp Debug, Up: Running - 1. Download the package(s) that you want to install. Each binary - package will typically be a gzip'd tarball. +Lisp Interaction Buffers +======================== - 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. + 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, . In +Emacs-Lisp mode, is an indentation command. In Lisp Interaction +mode, 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 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. - 3. Next, `cd' to the directory under which you want to install the - package(s). + +File: xemacs.info, Node: External Lisp, Prev: Lisp Interaction, Up: Running - 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: +Running an External Lisp +======================== - gunzip < package.tar.gz | tar xvf - + 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 . 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::. - Above, replace `package.tar.gz' with the filename of the package - that you downloaded in step 1. + +File: xemacs.info, Node: Packages, Next: Basic, Prev: Startup Paths, Up: Top - Of course, if you use GNU `tar', you could also use: +Packages +======== - tar xvzf package.tar.gz + 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. - 5. That's it. Quit and restart XEmacs to get it to recognize any new - or changed packages. +* Menu: +* 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.  -File: xemacs.info, Node: Building Packages, Next: Available Packages, Prev: Using Packages, Up: Packages +File: xemacs.info, Node: Package Terminology, Next: Installing Packages, Up: Packages - Source packages are available from the `packages/source-packages' -subdirectory of your favorite XEmacs distribution site. Alternatively, -they are available via CVS from `cvs.xemacs.org'. Look at -`http://cvs.xemacs.org' for instructions. +Package Terminology: +==================== -Prerequisites for Building Source Packages ------------------------------------------- - - You must have GNU `cp', GNU `install' (or a BSD compatible `install' -program) GNU `make' (3.75 or later preferred), `makeinfo' (1.68 from -`texinfo-3.11' or later required), GNU `tar' and XEmacs 21.0. The -source packages will untar into a correct directory structure. At the -top level you must have `XEmacs.rules' and `package-compile.el'. These -files are available from the XEmacs FTP site from the same place you -obtained your source package distributions. +Package Flavors +--------------- -What You Can Do With Source Packages ------------------------------------- + There are two main flavors of packages. - NB: A global build operation doesn't exist yet as of 13 January -1998. + * Regular Packages A regular package is one in which multiple files + are involved and one may not in general safely remove any of them. - Source packages are most useful for creating XEmacs package tarballs -for installation into your own XEmacs installations or for distributing -to others. + * 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". - Supported operations from `make' are: +Package Distributions +--------------------- -`clean' - Remove all built files except `auto-autoloads.el' and - `custom-load.el'. + 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. -`distclean' - Remove XEmacs backups as well as the files deleted by `make clean'. +Binary Packages +--------------- -`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. + Binary packages may be installed directly into an XEmacs package +hierarchy. -`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. +Source Packages +--------------- -`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. + 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). -`dist' - Runs the rules `srckit' followed by `binkit'. This is primarily - of use by XEmacs maintainers producing files for distribution. + Currently, source packages are only available via CVS. See + for details.  -File: xemacs.info, Node: Available Packages, Prev: Building Packages, Up: Packages - - This section is surely out-of-date. If you're sure that XEmacs is -able to do something, but your installed XEmacs won't do it for you, -it's probably in a package. If you can't find it in this section, -that's a bug--please report it. It is very hard to keep this section -up-to-date; your reports, comments, and questions will help a lot. - - This data is up-to-date as of 10 February 1999. (Ouch! I told you!) - -Library Packages (libs) ------------------------ - - These packages are required to build and support most of the rest of -XEmacs. By design, xemacs-base is a `regular' package. Use restraint -when adding new files there as it is required by almost everything. - -`Sun' - Support for Sparcworks. - -`apel' - A Portable Emacs Library. Used by XEmacs MIME support. - -`edebug' - A Lisp debugger. - -`dired' - The DIRectory EDitor is for manipulating, and running commands on - files in a directory. - -`efs' - Treat files on remote systems the same as local files. +File: xemacs.info, Node: Installing Packages, Next: Building Packages, Prev: Package Terminology, Up: Packages -`mail-lib' - Fundamental lisp files for providing email support. +Installing Packages: +==================== -`tooltalk' - Support for building with Tooltalk. - -`xemacs-base' - Fundamental XEmacs support. Install this unless you wish a totally - naked XEmacs. +Getting Started +--------------- -`xemacs-devel' - XEmacs Lisp developer support. This package contains utilities for - supporting Lisp development. It is a single-file package so it - may be tailored. + 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. -Communications Packages (comm) +Choosing the Packages You Need ------------------------------ - These packages provide support for various communications, primarily -email and usenet. - -`footnote' - Footnoting in mail message editing modes. - -`gnats' - XEmacs bug reports. - -`gnus' - The Gnus Newsreader and Mailreader. - -`mailcrypt' - Support for messaging encryption with PGP. - -`mh-e' - Front end support for MH. - -`net-utils' - Miscellaneous Networking Utilities. This is a single-file package - and files may be deleted at will. - -`ph' - Emacs implementation of the ph client to CCSO/qi directory servers. + 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 `--pkg.tar.gz'. -`rmail' - An obsolete Emacs mailer. If you do not already use it don't - start. - -`supercite' - An Emacs citation tool. Useful with all Emacs Mailers and - Newsreaders. - -`tm' - Emacs MIME support. - -`vm' - An Emacs mailer. - -`w3' - A Web browser. - -Games and Amusements (games) ----------------------------- - -`cookie' - Spook and Yow (Zippy quotes). - -`games' - Tetris, Sokoban, and Snake. - -`mine' - Minehunt. + 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. -`misc-games' - Other amusements and diversions. + 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: -Mule Support (mule) -------------------- + Options -> Customize -> Emacs -> Packages -`egg-its' - Wnn (4.2 and 6) support. SJ3 support. Must be installed prior to - XEmacs build. + 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). -`leim' - Quail. Used for everything other than English and Japanese. + 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: -`locale' - Used for localized menubars (French and Japanese) and localized - splash screens (Japanese). + Options -> Manage Packages -> List & Install -`mule-base' - Basic Mule support. Must be installed prior to building with Mule. + Or, you can get to it via the keyboard: -`skk' - Another Japanese Language Input Method. Can be used without a - separate process running as a dictionary server. + M-x pui-list-packages -Productivity Packages (oa) --------------------------- + 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. -`calendar' - Calendar and diary support. + 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: -`edit-utils' - Single file lisp packages for various XEmacs goodies. Load this - and weed out the junk you don't want. + M-x package-get-package-provider RET thingatpt -`forms' - Forms editing support (obsolete, use the builtin Widget instead). + which will return something like (fsf-compat "1.08"). You can the use +one of the methods above for installing the package you want. -`frame-icon' - Provide a WM icon based on major mode. +XEmacs and Installing Packages +------------------------------ -`hm--html-menus' - HTML editing. + There are three main ways to install packages: -`ispell' - Spell-checking with ispell. +* Menu: -`pc' - PC style interface emulation. +* 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. -`psgml' - Validated HTML/SGML editing. + But regardless of the method you use to install packages, they can +only be used by XEmacs after a restart. -`sgml' - SGML/Linuxdoc-SGML editing. + +File: xemacs.info, Node: Sumo, Next: Manually, Up: Installing Packages -`slider' - User interface tool. +Installing the Sumo Packages: +============================= -`speedbar' - ??? Document me. + 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' -`strokes' - Mouse enhancement utility. + For an XEmacs compiled with Mule you also need: +`xemacs-mule-sumo.tar.gz' -`text-modes' - Various single file lisp packages for editing text files. + N.B. They are called 'Sumo Tarballs' for good reason. They are +currently about 19MB and 4.5MB (gzipped) respectively. -`time' - Display time & date on the modeline. + Install them by: -Operating System Utilities (os) -------------------------------- + `cd $prefix/lib/xemacs ; gunzip -c | tar xvf - RET' -`eterm' - Terminal emulator. + Or, if you have GNU tar: -`igrep' - Enhanced front-end for Grep. + `cd $prefix/lib/xemacs ; tar zxvf /path/to/ RET' -`ilisp' - Front-end for Inferior Lisp. + 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. -`os-utils' - Miscellaneous single-file O/S utilities, for printing, archiving, - compression, remote shells, etc. + +File: xemacs.info, Node: Manually, Next: Automatically, Prev: Sumo, Up: Installing Packages -`view-process' - A Unix process browsing tool. +Manual Package Installation: +============================ -Program Editing Support (prog) ------------------------------- + Fetch the packages from the FTP site, CD-ROM whatever. The filenames +have the form `name--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. -`ada' - Ada language support. + Note: If you are upgrading packages already installed, it's best to +remove the old package first *Note Removing Packages::. -`c-support' - Basic single-file add-ons for editing C code. + For example if we are installing the `xemacs-base' package (version +1.48): -`cc-mode' - C, C++ and Java language support. + 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 -`debug' - GUD, gdb, dbx debugging support. + For MULE related packages, it is best to untar into the mule-packages +hierarchy, i.e. for the `mule-base' package, version 1.37: -`ediff' - Interface over patch. + 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 -`emerge' - Another interface over patch. + +File: xemacs.info, Node: Automatically, Next: Which Packages, Prev: Manually, Up: Installing Packages -`pcl-cvs' - CVS frontend. +Automatic Package Installation: +=============================== -`prog-modes' - Miscellaneous single-file lisp files for various programming - languages. + 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. -`scheme' - Front-end support for Inferior Scheme. + 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: -`sh-script' - Support for editing shell scripts. + 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. -`vc' - Version Control for Free systems. + After installing these by hand, fire up XEmacs and follow these +steps. -`vc-cc' - Version Control for ClearCase. This package must be installed - prior to building XEmacs [broken as of XEmacs 20.5-beta19]. + Note: The menus in XEmacs 21.2.x and up have changed slightly, so +where I mention "Options -> Manage Packages", substitute "Tools -> +Packages". -`vhdl' - Support for VHDL. + 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) -Word Processing (wp) --------------------- + If the package tarballs _AND_ the package-index file are in a + local directory, you can: `M-x pui-add-install-directory RET' -`auctex' - Basic TeX/LaTeX support. + 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' -`crisp' - Crisp/Brief emulation. + 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. -`edt' - DEC EDIT/EDT emulation. + 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: -`texinfo' - XEmacs TeXinfo support. + `-' + The package has not been installed. -`textools' - Single-file TeX support. + `*' + The package has been installed, but a newer version is + available. The current version is out-of-date. -`tpu' - DEC EDIT/TPU support. + `+' + The package has been marked for installation/update. -`viper' - VI emulation support. + If there is no character in the first column, the package has been + installed and is up-to-date. - -File: xemacs.info, Node: Abbrevs, Next: Picture, Prev: Running, 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 '. - - 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::. + From here, you can select or unselect packages for installation + using the 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. -* Menu: + Key summary: -* 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. + `?' + Display simple help. - -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 '. - - 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. + `' + `' + Toggle between selecting and unselecting a package for + installation. - -File: xemacs.info, Node: Expanding Abbrevs, Next: Editing Abbrevs, Prev: Defining Abbrevs, Up: Abbrevs + `x' + Install selected packages. -Controlling Abbrev Expansion -============================ + `' + 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. - An abbrev expands whenever it is in a buffer just before point and -you type a self-inserting punctuation character (, 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. + `v' + Toggle between verbose and non-verbose package display. - -File: xemacs.info, Node: Editing Abbrevs, Next: Saving Abbrevs, Prev: Expanding Abbrevs, Up: Abbrevs + `g' + Refresh the package display. -Examining and Editing Abbrevs -============================= + `q' + Kill the package buffer. -`M-x list-abbrevs' - Print a list of all abbrev definitions. + Moving the mouse over a package will also cause additional + information about the package to be displayed in the minibuffer. -`M-x edit-abbrevs' - Edit a list of abbrevs; you can add, alter, or remove definitions. + 3. Choose the packages you wish to install. mouse: Click button 2 on + the package name. keyb: `RET' on the package name - The output from `M-x list-abbrevs' looks like this: + 4. Make sure you have everything you need. menu: Packages -> Add + Required keyb: `r' - (lisp-mode-abbrev-table) - "dk" 0 "define-key" - (global-abbrev-table) - "dfn" 0 "definition" + 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. -(Some blank lines of no semantic significance, and some other abbrev -tables, have been omitted.) + For novices and gurus alike, this step can save your bacon. It's + easy to forget to install a critical package. - 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. + 5. Download and install the packages. menu: Packages -> + Install/Remove Selected keyb: `x' - 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. + You can also install packages using a semi-manual interface: - `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. + M-x package-get-all - `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. + 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.  -File: xemacs.info, Node: Saving Abbrevs, Next: Dynamic Abbrevs, Prev: Editing Abbrevs, Up: Abbrevs - -Saving Abbrevs -============== - - These commands allow you to keep abbrev definitions between editing -sessions. - -`M-x write-abbrev-file' - Write a file describing all defined abbrevs. - -`M-x read-abbrev-file' - Read such an abbrev file and define abbrevs as specified there. - -`M-x quietly-read-abbrev-file' - Similar, but do not display a message about what is going on. - -`M-x define-abbrevs' - Define abbrevs from buffer. +File: xemacs.info, Node: Which Packages, Next: Removing Packages, Prev: Automatically, Up: Installing Packages -`M-x insert-abbrevs' - Insert all abbrevs and their expansions into the buffer. +Which Packages to Install: +========================== - 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'. + 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 - `M-x read-abbrev-file' prompts for a file name using the minibuffer -and reads the specified file, defining abbrevs according to its -contents. `M-x quietly-read-abbrev-file' is the same but does not -display a message in the echo area; it is actually useful primarily in -the init file. *Note Init File::. If you give an empty argument to -either of these functions, the file name Emacs uses is the value of the -variable `abbrev-file-name', which is by default `"~/.abbrev_defs"'. + 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 - 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. + If you are using the XEmacs package tools, don't forget to do: - 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. + Packages -> Add Required - -File: xemacs.info, Node: Dynamic Abbrevs, Prev: Saving Abbrevs, Up: Abbrevs - -Dynamic Abbrev Expansion -======================== + To make sure you have everything that the packages you have chosen to +install need. - 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. + See also *Note Available Packages:: for further descriptions of the +individual packages.  -File: xemacs.info, Node: Picture, Next: Sending Mail, Prev: Abbrevs, Up: Top - -Editing Pictures -**************** - - If you want to create a picture made out of text characters (for -example, a picture of the division of a register into fields, as a -comment in a program), use the command `edit-picture' to enter Picture -mode. - - In Picture mode, editing is based on the "quarter-plane" model of -text. In this model, the text characters lie studded on an area that -stretches infinitely far to the right and downward. The concept of the -end of a line does not exist in this model; the most you can say is -where the last non-blank character on the line is found. - - Of course, Emacs really always considers text as a sequence of -characters, and lines really do have ends. But in Picture mode most -frequently-used keys are rebound to commands that simulate the -quarter-plane model of text. They do this by inserting spaces or by -converting tabs to spaces. - - Most of the basic editing commands of Emacs are redefined by Picture -mode to do essentially the same thing but in a quarter-plane way. In -addition, Picture mode defines various keys starting with the `C-c' -prefix to run special picture editing commands. - - One of these keys, `C-c C-c', is pretty important. Often a picture -is part of a larger file that is usually edited in some other major -mode. `M-x edit-picture' records the name of the previous major mode. -You can then use the `C-c C-c' command (`picture-mode-exit') to restore -that mode. `C-c C-c' also deletes spaces from the ends of lines, -unless you give it a numeric argument. - - The commands used in Picture mode all work in other modes (provided -the `picture' library is loaded), but are only bound to keys in -Picture mode. Note that the descriptions below talk of moving "one -column" and so on, but all the picture mode commands handle numeric -arguments as their normal equivalents do. - - Turning on Picture mode calls the value of the variable -`picture-mode-hook' as a function, with no arguments, if that value -exists and is non-`nil'. - -* Menu: +File: xemacs.info, Node: Removing Packages, Prev: Which Packages, Up: Installing Packages -* 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. +Removing Packages: +================== - -File: xemacs.info, Node: Basic Picture, Next: Insert in Picture, Prev: Picture, Up: Picture + 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. -Basic Editing in Picture Mode -============================= + 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'. - 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. 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. -(`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. -(`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::). + Note that the interactive package tools included with XEmacs already +do this for you.  -File: xemacs.info, Node: Insert in Picture, Next: Tabs in Picture, Prev: Basic Picture, Up: Picture +File: xemacs.info, Node: Building Packages, Next: Local.rules File, Prev: Installing Packages, Up: Packages -Controlling Motion After Insert -=============================== - - 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. - -`C-c <' - Move left after insertion (`picture-movement-left'). +Building Packages: +================== -`C-c >' - Move right after insertion (`picture-movement-right'). + Currently, source packages are only available via anonymous CVS. See + for details of checking out the +`xemacs-packages' module. -`C-c ^' - Move up after insertion (`picture-movement-up'). +Prerequisites for Building Source Packages +------------------------------------------ -`C-c .' - Move down after insertion (`picture-movement-down'). +`GNU cp' -`C-c `' - Move up and left ("northwest") after insertion - (`picture-movement-nw'). +`GNU ginstall' + (or a BSD compatible install program). -`C-c '' - Move up and right ("northeast") after insertion - (`picture-movement-ne'). +`GNU make' + (3.75 or later preferred). -`C-c /' - Move down and left ("southwest") after insertion - (`picture-movement-sw'). +`makeinfo' + (1.68 from texinfo-3.11 or later required). -`C-c \' - Move down and right ("southeast") after insertion - (`picture-movement-se'). +`GNU tar' + (or equivalent). - 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. +`GNU gzip' + (or equivalent). - -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-' (`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-', the -command moves to the next such interesting character in the current -line. `M-' 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 `"!-~"'. - - 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 ' (`picture-set-tab-stops'.) This -command sets the tab stops to the positions which `M-' would -consider significant in the current line. If you use this command with -, you can get the effect of context-based tabbing. But `M-' -is more convenient in the cases where it is sufficient. +`A properly configured `Local.rules' file.' + *Note Local.rules File::. And of course, XEmacs 21.0 or higher. - -File: xemacs.info, Node: Rectangles in Picture, Prev: Tabs in Picture, Up: Picture +What You Can Do With Source Packages +------------------------------------ -Picture Mode Rectangle Commands -=============================== + The packages CVS sources are most useful for creating XEmacs package +tarballs for installation into your own XEmacs installations or for +distributing to others. - 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::). + Supported operations from `make' are: -`C-c C-k' - Clear out the region-rectangle (`picture-clear-rectangle'). With - argument, kill it. +`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-c C-w R' - Similar but save rectangle contents in register R first - (`picture-clear-rectangle-to-register'). +`bindist' + Does a `make all' as well as create a binary package tarball in the + staging directory. -`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. +`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. -`C-c C-x R' - Similar, but use the rectangle in register R - (`picture-yank-rectangle-from-register'). +`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. - 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. +`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. - However, deletion of rectangles can be useful in Picture mode, so -these commands delete the rectangle if given a numeric argument. +`dist' + Runs the rules `srckit' followed by `binkit'. This is primarily + of use by XEmacs maintainers producing files for distribution. - 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. +`clean' + Remove all built files except `auto-autoloads.el' and + `custom-load.el'. - 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. +`distclean' + Remove all created files.  -File: xemacs.info, Node: Sending Mail, Next: Reading Mail, Prev: Picture, Up: Top +File: xemacs.info, Node: Local.rules File, Next: Creating Packages, Prev: Building Packages, Up: Packages -Sending Mail -************ +The Local.rules File: +===================== - 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. + 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. -`C-x m' - Begin composing a message to send (`mail'). + These are the variables in 'Local.rules' that you will need to +address. -`C-x 4 m' - Likewise, but display the message in another window - (`mail-other-window'). +SYMLINK = + Set this to 't' if you want to do a "run in place". Setting this + doesn't work well with 'make bindist' -`C-c C-c' - In Mail mode, send the message and switch to another buffer - (`mail-send-and-exit'). +XEMACS_PACKAGES = + This is where you set the normal packages that you want to + install. eg: + XEMACS_PACKAGES = libs/xemacs-base comm/bbdb - 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. +XEMACS_STAGING = ${XEMACS_PACKAGES_BASE}/../PACKAGES + Set this to where you want normal packages to be installed to. - 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. +PACKAGE_INDEX = PACKAGE-INDEX + If you want the package-index file to have a different name, + change this. - `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. +BUILD_WITHOUT_MULE = + Building from CVS defaults to building the Mule packages. Set + this to 't' if you don't want/have Mule -* Menu: - -* 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. +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 - -File: xemacs.info, Node: Mail Format, Next: Mail Headers, Prev: Sending Mail, Up: Sending Mail +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. -The Format of the Mail Buffer -============================= +XEMACS = XEMACS + If your XEmacs isn't in your path, change this. - 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. +XEMACS_NATIVE_NT = + Set this to 't' if you are building on WinNT. - 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. +INSTALL = INSTALL -C + The path to your BSD compatible install program. - The line in the buffer that says: +TAR = TAR + The path to your tar program - --text follows this line-- +BZIP2 = + If you want bzip2 tarballs, set this. -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'. - - Here is an example of what the headers and text in the `*mail*' -buffer might look like. - - To: rms@mc - CC: mly@mc, rg@oz - Subject: The XEmacs User's Manual - --Text follows this line-- - Please ignore this message. +MAKEINFO = MAKEINFO + The path to your makeinfo program  -File: xemacs.info, Node: Mail Headers, Next: Mail Mode, Prev: Mail Format, Up: Sending Mail +File: xemacs.info, Node: Creating Packages, Next: Available Packages, Prev: Local.rules File, Up: Packages -Mail Header Fields +Creating Packages: ================== - 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 " - - 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-separator-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. + 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. + + 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.