X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Fxemacs.info-13;h=7e434aac210cc61b537ce6d17aa50459b1c25f1f;hb=2779fcb5d524d6b7de5a6ef9ebfd6662433a4a07;hp=d59e716a5525f9aab86f6d588f3cc24a01015bb9;hpb=430e0db85cc37821320fe27da9feeacc7961003f;p=chise%2Fxemacs-chise.git- diff --git a/info/xemacs.info-13 b/info/xemacs.info-13 index d59e716..7e434aa 100644 --- a/info/xemacs.info-13 +++ b/info/xemacs.info-13 @@ -1,5 +1,5 @@ -This is Info file ../../info/xemacs.info, produced by Makeinfo version -1.68 from the input file xemacs.texi. +This is ../info/xemacs.info, produced by makeinfo version 4.0b from +xemacs/xemacs.texi. INFO-DIR-SECTION XEmacs Editor START-INFO-DIR-ENTRY @@ -30,1177 +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: Basic Picture, Next: Insert in Picture, Prev: Picture, Up: Picture +File: xemacs.info, Node: Lisp Libraries, Next: Lisp Eval, Prev: Lisp Modes, Up: Running -Basic Editing in Picture Mode -============================= +Libraries of Lisp Code for Emacs +================================ - 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::.). + 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::). - -File: xemacs.info, Node: Insert in Picture, Next: Tabs in Picture, Prev: Basic Picture, Up: Picture +* Menu: -Controlling Motion After Insert -=============================== +* 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. - 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. + +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'. -`C-c <' - Move left after insertion (`picture-movement-left'). + +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. -`C-c >' - Move right after insertion (`picture-movement-right'). + +File: xemacs.info, Node: Mocklisp, Prev: Compiling Libraries, Up: Lisp Libraries -`C-c ^' - Move up after insertion (`picture-movement-up'). +Converting Mocklisp to Lisp +--------------------------- -`C-c .' - Move down after insertion (`picture-movement-down'). + 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. -`C-c `' - Move up and left ("northwest") after insertion - (`picture-movement-nw'). + 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". -`C-c '' - Move up and right ("northeast") after insertion - (`picture-movement-ne'). + +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. -`C-c /' - Move down and left ("southwest") after insertion - (`picture-movement-sw'). + +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. -`C-c \' - Move down and right ("southeast") after insertion - (`picture-movement-se'). +`u' + Don't enter the debugger when the current frame is exited. This + cancels a `b' command on a frame. - 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. +`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-'. - -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. +`q' + Terminate the program being debugged; return to top-level Emacs + command execution. - -File: xemacs.info, Node: Rectangles in Picture, Prev: Tabs in Picture, Up: Picture + If the debugger was entered due to a `C-g' but you really want to + quit, not to debug, use the `q' command. -Picture Mode Rectangle Commands -=============================== +`r' + Return a value from the debugger. The value is computed by + reading an expression with the minibuffer and evaluating it. - 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::.). + 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. -`C-c C-k' - Clear out the region-rectangle (`picture-clear-rectangle'). With - argument, kill it. + 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'. -`C-c C-w R' - Similar but save rectangle contents in register R first - (`picture-clear-rectangle-to-register'). + +File: xemacs.info, Node: Lisp Interaction, Next: External Lisp, Prev: Lisp Debug, Up: Running + +Lisp Interaction Buffers +======================== + + 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. -`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. + +File: xemacs.info, Node: External Lisp, Prev: Lisp Interaction, Up: Running + +Running an External Lisp +======================== + + 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::. -`C-c C-x R' - Similar, but use the rectangle in register R - (`picture-yank-rectangle-from-register'). + +File: xemacs.info, Node: Packages, Next: Basic, Prev: Startup Paths, Up: Top - 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. +Packages +======== - However, deletion of rectangles can be useful in Picture mode, so -these commands delete the rectangle if given a numeric argument. + 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 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. +* Menu: - 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. +* 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: Sending Mail, Next: Reading Mail, Prev: Picture, Up: Top +File: xemacs.info, Node: Package Terminology, Next: Installing Packages, Up: Packages -Sending Mail -************ +Package Terminology: +==================== - 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. +Package Flavors +--------------- -`C-x m' - Begin composing a message to send (`mail'). + There are two main flavors of packages. -`C-x 4 m' - Likewise, but display the message in another window - (`mail-other-window'). + * Regular Packages A regular package is one in which multiple files + are involved and one may not in general safely remove any of them. -`C-c C-c' - In Mail mode, send the message and switch to another buffer - (`mail-send-and-exit'). + * 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". - 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. +Package Distributions +--------------------- - 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. + 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. - `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. +Binary Packages +--------------- -* Menu: + Binary packages may be installed directly into an XEmacs package +hierarchy. -* 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. +Source Packages +--------------- + + Source packages contain all of the Package author's (where +appropriate in regular packages) source code plus all of the files +necessary to build distribution tarballs (Unix Tar format files, +gzipped for space savings). + + Currently, source packages are only available via CVS. See + for details.  -File: xemacs.info, Node: Mail Format, Next: Mail Headers, Prev: Sending Mail, Up: Sending Mail +File: xemacs.info, Node: Installing Packages, Next: Building Packages, Prev: Package Terminology, Up: Packages -The Format of the Mail Buffer -============================= +Installing Packages: +==================== - 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. +Getting Started +--------------- - 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. + 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. - The line in the buffer that says: +Choosing the Packages You Need +------------------------------ - --text follows this line-- + 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'. -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'. + 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. - Here is an example of what the headers and text in the `*mail*' -buffer might look like. + 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: - To: rms@mc - CC: mly@mc, rg@oz - Subject: The XEmacs User's Manual - --Text follows this line-- - Please ignore this message. + Options -> Customize -> Emacs -> Packages - -File: xemacs.info, Node: Mail Headers, Next: Mail Mode, Prev: Mail Format, Up: Sending Mail + 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). -Mail Header Fields -================== + 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: - 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-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. + Options -> Manage Packages -> List & Install - -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'). - -`' - 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'. + Or, you can get to it via the keyboard: - -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.) + M-x pui-list-packages - -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. + 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. -* Menu: + 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: -* 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. + M-x package-get-package-provider RET thingatpt - -File: xemacs.info, Node: Calendar Motion, Next: Scroll Calendar, Prev: Calendar/Diary, Up: Calendar/Diary + which will return something like (fsf-compat "1.08"). You can the use +one of the methods above for installing the package you want. -Movement in the Calendar ------------------------- +XEmacs and Installing Packages +------------------------------ - Calendar mode lets you move through the calendar in logical units of -time such as days, weeks, months, and years. If you move outside the -three months originally displayed, the calendar display "scrolls" -automatically through time to make the selected date visible. Moving to -a date lets you view its holidays or diary entries, or convert it to -other calendars; moving longer time periods is also useful simply to -scroll the calendar. + There are three main ways to install packages: * Menu: -* Calendar Unit Motion:: Moving by days, weeks, months, and years. -* Move to Beginning or End:: Moving to start/end of weeks, months, and years. -* Specified Dates:: Moving to the current date or another - specific date. +* 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.  -File: xemacs.info, Node: Calendar Unit Motion, Next: Move to Beginning or End, Prev: Calendar Motion, Up: Calendar Motion +File: xemacs.info, Node: Sumo, Next: Manually, Up: Installing Packages -Motion by Integral Days, Weeks, Months, Years -............................................. +Installing the Sumo Packages: +============================= - The commands for movement in the calendar buffer parallel the -commands for movement in text. You can move forward and backward by -days, weeks, months, and years. + 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' -`C-f' - Move point one day forward (`calendar-forward-day'). + For an XEmacs compiled with Mule you also need: +`xemacs-mule-sumo.tar.gz' -`C-b' - Move point one day backward (`calendar-backward-day'). + N.B. They are called 'Sumo Tarballs' for good reason. They are +currently about 19MB and 4.5MB (gzipped) respectively. -`C-n' - Move point one week forward (`calendar-forward-week'). + Install them by: -`C-p' - Move point one week backward (`calendar-backward-week'). + `cd $prefix/lib/xemacs ; gunzip -c | tar xvf - RET' -`M-}' - Move point one month forward (`calendar-forward-month'). + Or, if you have GNU tar: -`M-{' - Move point one month backward (`calendar-backward-month'). + `cd $prefix/lib/xemacs ; tar zxvf /path/to/ RET' -`C-x ]' - Move point one year forward (`calendar-forward-year'). + 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. -`C-x [' - Move point one year backward (`calendar-backward-year'). + +File: xemacs.info, Node: Manually, Next: Automatically, Prev: Sumo, Up: Installing Packages + +Manual Package Installation: +============================ - The day and week commands are natural analogues of the usual Emacs -commands for moving by characters and by lines. Just as `C-n' usually -moves to the same column in the following line, in Calendar mode it -moves to the same day in the following week. And `C-p' moves to the -same day in the previous week. + 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. - The arrow keys are equivalent to `C-f', `C-b', `C-n' and `C-p', just -as they normally are in other modes. + Note: If you are upgrading packages already installed, it's best to +remove the old package first *Note Removing Packages::. - The commands for motion by months and years work like those for -weeks, but move a larger distance. The month commands `M-}' and `M-{' -move forward or backward by an entire month's time. The year commands -`C-x ]' and `C-x [' move forward or backward a whole year. + For example if we are installing the `xemacs-base' package (version +1.48): - The easiest way to remember these commands is to consider months and -years analogous to paragraphs and pages of text, respectively. But the -commands themselves are not quite analogous. The ordinary Emacs -paragraph commands move to the beginning or end of a paragraph, whereas -these month and year commands move by an entire month or an entire -year, which usually involves skipping across the end of a month or year. + 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 - All these commands accept a numeric argument as a repeat count. For -convenience, the digit keys and the minus sign specify numeric -arguments in Calendar mode even without the Meta modifier. For example, -`100 C-f' moves point 100 days forward from its present location. + For MULE related packages, it is best to untar into the mule-packages +hierarchy, i.e. for the `mule-base' package, version 1.37: + + 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  -File: xemacs.info, Node: Move to Beginning or End, Next: Specified Dates, Prev: Calendar Unit Motion, Up: Calendar Motion +File: xemacs.info, Node: Automatically, Next: Which Packages, Prev: Manually, Up: Installing Packages -Beginning or End of Week, Month or Year -....................................... +Automatic Package Installation: +=============================== - A week (or month, or year) is not just a quantity of days; we think -of weeks (months, years) as starting on particular dates. So Calendar -mode provides commands to move to the beginning or end of a week, month -or year: + 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. -`C-a' - Move point to start of week (`calendar-beginning-of-week'). + 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: -`C-e' - Move point to end of week (`calendar-end-of-week'). + 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-a' - Move point to start of month (`calendar-beginning-of-month'). + After installing these by hand, fire up XEmacs and follow these +steps. -`M-e' - Move point to end of month (`calendar-end-of-month'). + Note: The menus in XEmacs 21.2.x and up have changed slightly, so +where I mention "Options -> Manage Packages", substitute "Tools -> +Packages". -`M-<' - Move point to start of year (`calendar-beginning-of-year'). + 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) -`M->' - Move point to end of year (`calendar-end-of-year'). + If the package tarballs _AND_ the package-index file are in a + local directory, you can: `M-x pui-add-install-directory RET' - These commands also take numeric arguments as repeat counts, with the -repeat count indicating how many weeks, months, or years to move -backward or forward. + 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' - By default, weeks begin on Sunday. To make them begin on Monday -instead, set the variable `calendar-week-start-day' to 1. + 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. - -File: xemacs.info, Node: Specified Dates, Prev: Move to Beginning or End, Up: Calendar Motion + 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: -Particular Dates -................ + `-' + The package has not been installed. - Calendar mode provides commands for moving to a particular date -specified in various ways. + `*' + The package has been installed, but a newer version is + available. The current version is out-of-date. -`g d' - Move point to specified date (`calendar-goto-date'). + `+' + The package has been marked for installation/update. -`o' - Center calendar around specified month (`calendar-other-month'). + If there is no character in the first column, the package has been + installed and is up-to-date. -`.' - Move point to today's date (`calendar-goto-today'). + 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. - `g d' (`calendar-goto-date') prompts for a year, a month, and a day -of the month, and then moves to that date. Because the calendar -includes all dates from the beginning of the current era, you must type -the year in its entirety; that is, type `1990', not `90'. + Key summary: - `o' (`calendar-other-month') prompts for a month and year, then -centers the three-month calendar around that month. + `?' + Display simple help. - You can return to today's date with `.' (`calendar-goto-today'). + `' + `' + Toggle between selecting and unselecting a package for + installation. - -File: xemacs.info, Node: Scroll Calendar, Next: Mark and Region, Prev: Calendar Motion, Up: Calendar/Diary - -Scrolling the Calendar through Time ------------------------------------ - - The calendar display scrolls automatically through time when you -move out of the visible portion. You can also scroll it manually. -Imagine that the calendar window contains a long strip of paper with -the months on it. Scrolling it means moving the strip so that new -months become visible in the window. - -`C-x <' - Scroll calendar one month forward (`scroll-calendar-left'). - -`C-x >' - Scroll calendar one month backward (`scroll-calendar-right'). - -`C-v' -`' - Scroll calendar three months forward - (`scroll-calendar-left-three-months'). - -`M-v' -`' - Scroll calendar three months backward - (`scroll-calendar-right-three-months'). - - The most basic calendar scroll commands scroll by one month at a -time. This means that there are two months of overlap between the -display before the command and the display after. `C-x <' scrolls the -calendar contents one month to the left; that is, it moves the display -forward in time. `C-x >' scrolls the contents to the right, which -moves backwards in time. - - The commands `C-v' and `M-v' scroll the calendar by an entire -"screenful"--three months--in analogy with the usual meaning of these -commands. `C-v' makes later dates visible and `M-v' makes earlier -dates visible. These commands take a numeric argument as a repeat -count; in particular, since `C-u' multiplies the next command by four, -typing `C-u C-v' scrolls the calendar forward by a year and typing `C-u -M-v' scrolls the calendar backward by a year. - - The function keys and are equivalent to `C-v' and -`M-v', just as they are in other modes. + `x' + Install selected packages. - -File: xemacs.info, Node: Mark and Region, Next: General Calendar, Prev: Scroll Calendar, Up: Calendar/Diary - -The Mark and the Region ------------------------ - - The concept of the mark applies to the calendar just as to any other -buffer, but it marks a *date*, not a *position* in the buffer. The -region consists of the days between the mark and point (including the -starting and stopping dates). - -`C-SPC' - Set the mark to today's date (`calendar-set-mark'). - -`C-@' - The same. - -`C-x C-x' - Interchange mark and point (`calendar-exchange-point-and-mark'). - -`M-=' - Display the number of days in the current region - (`calendar-count-days-region'). - - You set the mark in the calendar, as in any other buffer, by using -`C-@' or `C-SPC' (`calendar-set-mark'). You return to the marked date -with the command `C-x C-x' (`calendar-exchange-point-and-mark') which -puts the mark where point was and point where mark was. The calendar -is scrolled as necessary, if the marked date was not visible on the -screen. This does not change the extent of the region. - - To determine the number of days in the region, type `M-=' -(`calendar-count-days-region'). The numbers of days printed is -*inclusive*; that is, it includes the days specified by mark and point. - - The main use of the mark in the calendar is to remember dates that -you may want to go back to. To make this feature more useful, the mark -ring (*note Mark Ring::.) operates exactly as in other buffers: Emacs -remembers 16 previous locations of the mark. To return to a marked -date, type `C-u C-SPC' (or `C-u C-@'); this is the command -`calendar-set-mark' given a numeric argument. It moves point to where -the mark was, restores the mark from the ring of former marks, and -stores the previous point at the end of the mark ring. So, repeated -use of this command moves point through all the old marks on the ring, -one by one. + `' + 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. - -File: xemacs.info, Node: General Calendar, Next: LaTeX Calendar, Prev: Mark and Region, Up: Calendar/Diary + `v' + Toggle between verbose and non-verbose package display. -Miscellaneous Calendar Commands -------------------------------- + `g' + Refresh the package display. -`p d' - Display day-in-year (`calendar-print-day-of-year'). + `q' + Kill the package buffer. -`?' - Briefly describe calendar commands (`describe-calendar-mode'). + Moving the mouse over a package will also cause additional + information about the package to be displayed in the minibuffer. -`C-c C-l' - Regenerate the calendar window (`redraw-calendar'). + 3. Choose the packages you wish to install. mouse: Click button 2 on + the package name. keyb: `RET' on the package name -`SPC' - Scroll the next window (`scroll-other-window'). + 4. Make sure you have everything you need. menu: Packages -> Add + Required keyb: `r' -`q' - Exit from calendar (`exit-calendar'). + 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. + + For novices and gurus alike, this step can save your bacon. It's + easy to forget to install a critical package. + + 5. Download and install the packages. menu: Packages -> + Install/Remove Selected keyb: `x' + + You can also install packages using a semi-manual interface: - If you want to know how many days have elapsed since the start of -the year, or the number of days remaining in the year, type the `p d' -command (`calendar-print-day-of-year'). This displays both of those -numbers in the echo area. + M-x package-get-all - To display a brief description of the calendar commands, type `?' -(`describe-calendar-mode'). For a fuller description, type `C-h m'. + 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: Which Packages, Next: Removing Packages, Prev: Automatically, Up: Installing Packages + +Which Packages to Install: +========================== - You can use `SPC' (`scroll-other-window') to scroll the other -window. This is handy when you display a list of holidays or diary -entries in another window. + 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 - If the calendar window text gets corrupted, type `C-c C-l' -(`redraw-calendar') to redraw it. (This can only happen if you use -non-Calendar-mode editing commands.) + 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 - In Calendar mode, you can use `SPC' (`scroll-other-window') to -scroll the other window. This is handy when you display a list of -holidays or diary entries in another window. + If you are using the XEmacs package tools, don't forget to do: - To exit from the calendar, type `q' (`exit-calendar'). This buries -all buffers related to the calendar, selecting other buffers. (If a -frame contains a dedicated calendar window, exiting from the calendar -iconifies that frame.) + Packages -> Add Required + + To make sure you have everything that the packages you have chosen to +install need. + + See also *Note Available Packages:: for further descriptions of the +individual packages.  -File: xemacs.info, Node: LaTeX Calendar, Next: Holidays, Prev: General Calendar, Up: Calendar/Diary +File: xemacs.info, Node: Removing Packages, Prev: Which Packages, Up: Installing Packages -LaTeX Calendar -============== +Removing Packages: +================== - The Calendar LaTeX commands produce a buffer of LaTeX code that -prints as a calendar. Depending on the command you use, the printed -calendar covers the day, week, month or year that point is in. + 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. -`t m' - Generate a one-month calendar (`cal-tex-cursor-month'). + 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'. -`t M' - Generate a sideways-printing one-month calendar - (`cal-tex-cursor-month-landscape'). + Note that the interactive package tools included with XEmacs already +do this for you. -`t d' - Generate a one-day calendar (`cal-tex-cursor-day'). + +File: xemacs.info, Node: Building Packages, Next: Local.rules File, Prev: Installing Packages, Up: Packages -`t w 1' - Generate a one-page calendar for one week (`cal-tex-cursor-week'). +Building Packages: +================== -`t w 2' - Generate a two-page calendar for one week (`cal-tex-cursor-week2'). + Currently, source packages are only available via anonymous CVS. See + for details of checking out the +`xemacs-packages' module. -`t w 3' - Generate an ISO-style calendar for one week - (`cal-tex-cursor-week-iso'). +Prerequisites for Building Source Packages +------------------------------------------ -`t w 4' - Generate a calendar for one Monday-starting week - (`cal-tex-cursor-week-monday'). +`GNU cp' -`t f w' - Generate a Filofax-style two-weeks-at-a-glance calendar - (`cal-tex-cursor-filofax-2week'). +`GNU ginstall' + (or a BSD compatible install program). -`t f W' - Generate a Filofax-style one-week-at-a-glance calendar - (`cal-tex-cursor-filofax-week'). +`GNU make' + (3.75 or later preferred). -`t y' - Generate a calendar for one year (`cal-tex-cursor-year'). +`makeinfo' + (1.68 from texinfo-3.11 or later required). -`t Y' - Generate a sideways-printing calendar for one year - (`cal-tex-cursor-year-landscape'). +`GNU tar' + (or equivalent). -`t f y' - Generate a Filofax-style calendar for one year - (`cal-tex-cursor-filofax-year'). +`GNU gzip' + (or equivalent). - Some of these commands print the calendar sideways (in "landscape -mode"), so it can be wider than it is long. Some of them use Filofax -paper size (3.75in x 6.75in). All of these commands accept a prefix -argument which specifies how many days, weeks, months or years to print -(starting always with the selected one). +`A properly configured `Local.rules' file.' + *Note Local.rules File::. And of course, XEmacs 21.0 or higher. - If the variable `cal-tex-holidays' is non-`nil' (the default), then -the printed calendars show the holidays in `calendar-holidays'. If the -variable `cal-tex-diary' is non-`nil' (the default is `nil'), diary -entries are included also (in weekly and monthly calendars only). +What You Can Do With Source Packages +------------------------------------ - -File: xemacs.info, Node: Holidays, Next: Sunrise/Sunset, Prev: LaTeX Calendar, Up: Calendar/Diary + The packages CVS sources are most useful for creating XEmacs package +tarballs for installation into your own XEmacs installations or for +distributing to others. -Holidays --------- + Supported operations from `make' are: - The Emacs calendar knows about all major and many minor holidays, -and can display them. +`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. -`h' - Display holidays for the selected date - (`calendar-cursor-holidays'). +`bindist' + Does a `make all' as well as create a binary package tarball in the + staging directory. -`Button2 Holidays' - Display any holidays for the date you click on. +`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. -`x' - Mark holidays in the calendar window (`mark-calendar-holidays'). +`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. -`u' - Unmark calendar window (`calendar-unmark'). - -`a' - List all holidays for the displayed three months in another window - (`list-calendar-holidays'). - -`M-x holidays' - List all holidays for three months around today's date in another - window. - -`M-x list-holidays' - List holidays in another window for a specified range of years. - - To see if any holidays fall on a given date, position point on that -date in the calendar window and use the `h' command. Alternatively, -click on that date with `Button2' and then choose `Holidays' from the -menu that appears. Either way, this displays the holidays for that -date, in the echo area if they fit there, otherwise in a separate -window. - - To view the distribution of holidays for all the dates shown in the -calendar, use the `x' command. This displays the dates that are -holidays in a different face (or places a `*' after these dates, if -display with multiple faces is not available). The command applies both -to the currently visible months and to other months that subsequently -become visible by scrolling. To turn marking off and erase the current -marks, type `u', which also erases any diary marks (*note Diary::.). - - To get even more detailed information, use the `a' command, which -displays a separate buffer containing a list of all holidays in the -current three-month range. You can use in the calendar window to -scroll that list. - - The command `M-x holidays' displays the list of holidays for the -current month and the preceding and succeeding months; this works even -if you don't have a calendar window. If you want the list of holidays -centered around a different month, use `C-u M-x holidays', which -prompts for the month and year. - - The holidays known to Emacs include United States holidays and the -major Christian, Jewish, and Islamic holidays; also the solstices and -equinoxes. - - The command `M-x list-holidays' displays the list of holidays for a -range of years. This function asks you for the starting and stopping -years, and allows you to choose all the holidays or one of several -categories of holidays. You can use this command even if you don't have -a calendar window. - - The dates used by Emacs for holidays are based on *current -practice*, not historical fact. Historically, for instance, the start -of daylight savings time and even its existence have varied from year to -year, but present United States law mandates that daylight savings time -begins on the first Sunday in April. When the daylight savings rules -are set up for the United States, Emacs always uses the present -definition, even though it is wrong for some prior years. +`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. - -File: xemacs.info, Node: Sunrise/Sunset, Next: Lunar Phases, Prev: Holidays, Up: Calendar/Diary +`dist' + Runs the rules `srckit' followed by `binkit'. This is primarily + of use by XEmacs maintainers producing files for distribution. -Times of Sunrise and Sunset ---------------------------- +`clean' + Remove all built files except `auto-autoloads.el' and + `custom-load.el'. - Special calendar commands can tell you, to within a minute or two, -the times of sunrise and sunset for any date. - -`S' - Display times of sunrise and sunset for the selected date - (`calendar-sunrise-sunset'). - -`Button2 Sunrise/Sunset' - Display times of sunrise and sunset for the date you click on. - -`M-x sunrise-sunset' - Display times of sunrise and sunset for today's date. - -`C-u M-x sunrise-sunset' - Display times of sunrise and sunset for a specified date. - - Within the calendar, to display the *local times* of sunrise and -sunset in the echo area, move point to the date you want, and type `S'. -Alternatively, click `Button2' on the date, then choose -`Sunrise/Sunset' from the menu that appears. The command `M-x -sunrise-sunset' is available outside the calendar to display this -information for today's date or a specified date. To specify a date -other than today, use `C-u M-x sunrise-sunset', which prompts for the -year, month, and day. - - You can display the times of sunrise and sunset for any location and -any date with `C-u C-u M-x sunrise-sunset'. This asks you for a -longitude, latitude, number of minutes difference from Coordinated -Universal Time, and date, and then tells you the times of sunrise and -sunset for that location on that date. - - Because the times of sunrise and sunset depend on the location on -earth, you need to tell Emacs your latitude, longitude, and location -name before using these commands. Here is an example of what to set: - - (setq calendar-latitude 40.1) - (setq calendar-longitude -88.2) - (setq calendar-location-name "Urbana, IL") - -Use one decimal place in the values of `calendar-latitude' and -`calendar-longitude'. - - Your time zone also affects the local time of sunrise and sunset. -Emacs usually gets time zone information from the operating system, but -if these values are not what you want (or if the operating system does -not supply them), you must set them yourself. Here is an example: - - (setq calendar-time-zone -360) - (setq calendar-standard-time-zone-name "CST") - (setq calendar-daylight-time-zone-name "CDT") - -The value of `calendar-time-zone' is the number of minutes difference -between your local standard time and Coordinated Universal Time -(Greenwich time). The values of `calendar-standard-time-zone-name' and -`calendar-daylight-time-zone-name' are the abbreviations used in your -time zone. Emacs displays the times of sunrise and sunset *corrected -for daylight savings time*. *Note Daylight Savings::, for how daylight -savings time is determined. - - As a user, you might find it convenient to set the calendar location -variables for your usual physical location in your `.emacs' file. And -when you install Emacs on a machine, you can create a `default.el' file -which sets them properly for the typical location of most users of that -machine. *Note Init File::. +`distclean' + Remove all created files.  -File: xemacs.info, Node: Lunar Phases, Next: Other Calendars, Prev: Sunrise/Sunset, Up: Calendar/Diary +File: xemacs.info, Node: Local.rules File, Next: Creating Packages, Prev: Building Packages, Up: Packages -Phases of the Moon ------------------- +The Local.rules File: +===================== - These calendar commands display the dates and times of the phases of -the moon (new moon, first quarter, full moon, last quarter). This -feature is useful for debugging problems that "depend on the phase of -the moon." + 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. -`M' - Display the dates and times for all the quarters of the moon for - the three-month period shown (`calendar-phases-of-moon'). + These are the variables in 'Local.rules' that you will need to +address. -`M-x phases-of-moon' - Display dates and times of the quarters of the moon for three - months around today's date. +SYMLINK = + Set this to 't' if you want to do a "run in place". Setting this + doesn't work well with 'make bindist' - Within the calendar, use the `M' command to display a separate -buffer of the phases of the moon for the current three-month range. The -dates and times listed are accurate to within a few minutes. +XEMACS_PACKAGES = + This is where you set the normal packages that you want to + install. eg: + XEMACS_PACKAGES = libs/xemacs-base comm/bbdb - Outside the calendar, use the command `M-x phases-of-moon' to -display the list of the phases of the moon for the current month and the -preceding and succeeding months. For information about a different -month, use `C-u M-x phases-of-moon', which prompts for the month and -year. +XEMACS_STAGING = ${XEMACS_PACKAGES_BASE}/../PACKAGES + Set this to where you want normal packages to be installed to. - The dates and times given for the phases of the moon are given in -local time (corrected for daylight savings, when appropriate); but if -the variable `calendar-time-zone' is void, Coordinated Universal Time -(the Greenwich time zone) is used. *Note Daylight Savings::. +PACKAGE_INDEX = PACKAGE-INDEX + If you want the package-index file to have a different name, + change this. - -File: xemacs.info, Node: Other Calendars, Next: Calendar Systems, Prev: Lunar Phases, Up: Calendar/Diary +BUILD_WITHOUT_MULE = + Building from CVS defaults to building the Mule packages. Set + this to 't' if you don't want/have Mule -Conversion To and From Other Calendars --------------------------------------- +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 - The Emacs calendar displayed is *always* the Gregorian calendar, -sometimes called the "new style" calendar, which is used in most of the -world today. However, this calendar did not exist before the sixteenth -century and was not widely used before the eighteenth century; it did -not fully displace the Julian calendar and gain universal acceptance -until the early twentieth century. The Emacs calendar can display any -month since January, year 1 of the current era, but the calendar -displayed is the Gregorian, even for a date at which the Gregorian -calendar did not exist. +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. - While Emacs cannot display other calendars, it can convert dates to -and from several other calendars. +XEMACS = XEMACS + If your XEmacs isn't in your path, change this. -* Menu: +XEMACS_NATIVE_NT = + Set this to 't' if you are building on WinNT. + +INSTALL = INSTALL -C + The path to your BSD compatible install program. -* Calendar Systems:: The calendars Emacs understands - (aside from Gregorian). -* To Other Calendar:: Converting the selected date to various calendars. -* From Other Calendar:: Moving to a date specified in another calendar. -* Mayan Calendar:: Moving to a date specified in a Mayan calendar. +TAR = TAR + The path to your tar program - If you are interested in these calendars, you can convert dates one -at a time. Put point on the desired date of the Gregorian calendar and -press the appropriate keys. The `p' is a mnemonic for "print" since -Emacs "prints' the equivalent date in the echo area. +BZIP2 = + If you want bzip2 tarballs, set this. + +MAKEINFO = MAKEINFO + The path to your makeinfo program  -File: xemacs.info, Node: Calendar Systems, Next: To Other Calendar, Prev: Other Calendars, Up: Other Calendars +File: xemacs.info, Node: Creating Packages, Next: Available Packages, Prev: Local.rules File, Up: Packages -Supported Calendar Systems -========================== +Creating Packages: +================== - The ISO commercial calendar is used largely in Europe. - - The Julian calendar, named after Julius Caesar, was the one used in -Europe throughout medieval times, and in many countries up until the -nineteenth century. - - Astronomers use a simple counting of days elapsed since noon, Monday, -January 1, 4713 B.C. on the Julian calendar. The number of days elapsed -is called the *Julian day number* or the *Astronomical day number*. - - The Hebrew calendar is used by tradition in the Jewish religion. The -Emacs calendar program uses the Hebrew calendar to determine the dates -of Jewish holidays. Hebrew calendar dates begin and end at sunset. - - The Islamic calendar is used in many predominantly Islamic countries. -Emacs uses it to determine the dates of Islamic holidays. There is no -universal agreement in the Islamic world about the calendar; Emacs uses -a widely accepted version, but the precise dates of Islamic holidays -often depend on proclamation by religious authorities, not on -calculations. As a consequence, the actual dates of observance can vary -slightly from the dates computed by Emacs. Islamic calendar dates begin -and end at sunset. - - The French Revolutionary calendar was created by the Jacobins after -the 1789 revolution, to represent a more secular and nature-based view -of the annual cycle, and to install a 10-day week in a rationalization -measure similar to the metric system. The French government officially -abandoned this calendar at the end of 1805. - - The Maya of Central America used three separate, overlapping calendar -systems, the *long count*, the *tzolkin*, and the *haab*. Emacs knows -about all three of these calendars. Experts dispute the exact -correlation between the Mayan calendar and our calendar; Emacs uses the -Goodman-Martinez-Thompson correlation in its calculations. - - The Copts use a calendar based on the ancient Egyptian solar -calendar. Their calendar consists of twelve 30-day months followed by -an extra five-day period. Once every fourth year they add a leap day -to this extra period to make it six days. The Ethiopic calendar is -identical in structure, but has different year numbers and month names. - - The Persians use a solar calendar based on a design of Omar Khayyam. -Their calendar consists of twelve months of which the first six have 31 -days, the next five have 30 days, and the last has 29 in ordinary years -and 30 in leap years. Leap years occur in a complicated pattern every -four or five years. - - The Chinese calendar is a complicated system of lunar months arranged -into solar years. The years go in cycles of sixty, each year containing -either twelve months in an ordinary year or thirteen months in a leap -year; each month has either 29 or 30 days. Years, ordinary months, and -days are named by combining one of ten "celestial stems" with one of -twelve "terrestrial branches" for a total of sixty names that are -repeated in a cycle of sixty. + 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.