X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-46;h=49474f73654169a0f5cc3d3827115c7641159d06;hb=61497f9cef18fa17ac20cdc9e7435d9f1dd9ef95;hp=7a6e6ca932f6c29bf4838aea2463561493e22020;hpb=f52a96980ed9280f8f906a20d4b899dc0b027644;p=chise%2Fxemacs-chise.git diff --git a/info/lispref.info-46 b/info/lispref.info-46 index 7a6e6ca..49474f7 100644 --- a/info/lispref.info-46 +++ b/info/lispref.info-46 @@ -1,4 +1,4 @@ -This is ../info/lispref.info, produced by makeinfo version 4.0 from +This is ../info/lispref.info, produced by makeinfo version 4.0b from lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor @@ -50,811 +50,1150 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -File: lispref.info, Node: Standard Buffer-Local Variables, Next: Standard Keymaps, Prev: Standard Errors, Up: Top +File: lispref.info, Node: Style Tips, Next: Compilation Tips, Up: Tips -Buffer-Local Variables -********************** +Writing Clean Lisp Programs +=========================== - The table below lists the general-purpose Emacs variables that are -automatically local (when set) in each buffer. Many Lisp packages -define such variables for their internal use; we don't list them here. + Here are some tips for avoiding common errors in writing Lisp code +intended for widespread use: + + * Since all global variables share the same name space, and all + functions share another name space, you should choose a short word + to distinguish your program from other Lisp programs. Then take + care to begin the names of all global variables, constants, and + functions with the chosen prefix. This helps avoid name conflicts. + + This recommendation applies even to names for traditional Lisp + primitives that are not primitives in XEmacs Lisp--even to `cadr'. + Believe it or not, there is more than one plausible way to define + `cadr'. Play it safe; append your name prefix to produce a name + like `foo-cadr' or `mylib-cadr' instead. + + If you write a function that you think ought to be added to Emacs + under a certain name, such as `twiddle-files', don't call it by + that name in your program. Call it `mylib-twiddle-files' in your + program, and send mail to `bug-gnu-emacs@prep.ai.mit.edu' + suggesting we add it to Emacs. If and when we do, we can change + the name easily enough. + + If one prefix is insufficient, your package may use two or three + alternative common prefixes, so long as they make sense. + + Separate the prefix from the rest of the symbol name with a hyphen, + `-'. This will be consistent with XEmacs itself and with most + Emacs Lisp programs. + + * It is often useful to put a call to `provide' in each separate + library program, at least if there is more than one entry point to + the program. + + * If a file requires certain other library programs to be loaded + beforehand, then the comments at the beginning of the file should + say so. Also, use `require' to make sure they are loaded. + + * If one file FOO uses a macro defined in another file BAR, FOO + should contain this expression before the first use of the macro: + + (eval-when-compile (require 'BAR)) + + (And BAR should contain `(provide 'BAR)', to make the `require' + work.) This will cause BAR to be loaded when you byte-compile + FOO. Otherwise, you risk compiling FOO without the necessary + macro loaded, and that would produce compiled code that won't work + right. *Note Compiling Macros::. + + Using `eval-when-compile' avoids loading BAR when the compiled + version of FOO is _used_. + + * If you define a major mode, make sure to run a hook variable using + `run-hooks', just as the existing major modes do. *Note Hooks::. + + * If the purpose of a function is to tell you whether a certain + condition is true or false, give the function a name that ends in + `p'. If the name is one word, add just `p'; if the name is + multiple words, add `-p'. Examples are `framep' and + `frame-live-p'. + + * If a user option variable records a true-or-false condition, give + it a name that ends in `-flag'. + + * Please do not define `C-c LETTER' as a key in your major modes. + These sequences are reserved for users; they are the *only* + sequences reserved for users, so we cannot do without them. + + Instead, define sequences consisting of `C-c' followed by a + non-letter. These sequences are reserved for major modes. -`abbrev-mode' - *note Abbrevs:: + Changing all the major modes in Emacs 18 so they would follow this + convention was a lot of work. Abandoning this convention would + make that work go to waste, and inconvenience users. -`auto-fill-function' - *note Auto Filling:: - -`buffer-auto-save-file-name' - *note Auto-Saving:: - -`buffer-backed-up' - *note Backup Files:: - -`buffer-display-table' - *note Display Tables:: - -`buffer-file-format' - *note Format Conversion:: - -`buffer-file-name' - *note Buffer File Name:: - -`buffer-file-number' - *note Buffer File Name:: - -`buffer-file-truename' - *note Buffer File Name:: - -`buffer-file-type' - *note Files and MS-DOS:: - -`buffer-invisibility-spec' - *note Invisible Text:: - -`buffer-offer-save' - *note Saving Buffers:: - -`buffer-read-only' - *note Read Only Buffers:: - -`buffer-saved-size' - *note Point:: - -`buffer-undo-list' - *note Undo:: - -`cache-long-line-scans' - *note Text Lines:: - -`case-fold-search' - *note Searching and Case:: - -`ctl-arrow' - *note Usual Display:: - -`comment-column' - *note Comments: (emacs)Comments. - -`default-directory' - *note System Environment:: - -`defun-prompt-regexp' - *note List Motion:: - -`fill-column' - *note Auto Filling:: - -`goal-column' - *note Moving Point: (emacs)Moving Point. - -`left-margin' - *note Indentation:: - -`local-abbrev-table' - *note Abbrevs:: - -`local-write-file-hooks' - *note Saving Buffers:: - -`major-mode' - *note Mode Help:: - -`mark-active' - *note The Mark:: - -`mark-ring' - *note The Mark:: - -`minor-modes' - *note Minor Modes:: - -`modeline-format' - *note Modeline Data:: - -`modeline-buffer-identification' - *note Modeline Variables:: - -`modeline-format' - *note Modeline Data:: - -`modeline-modified' - *note Modeline Variables:: - -`modeline-process' - *note Modeline Variables:: - -`mode-name' - *note Modeline Variables:: - -`overwrite-mode' - *note Insertion:: - -`paragraph-separate' - *note Standard Regexps:: - -`paragraph-start' - *note Standard Regexps:: - -`point-before-scroll' - Used for communication between mouse commands and scroll-bar - commands. - -`require-final-newline' - *note Insertion:: - -`selective-display' - *note Selective Display:: - -`selective-display-ellipses' - *note Selective Display:: - -`tab-width' - *note Usual Display:: - -`truncate-lines' - *note Truncation:: - -`vc-mode' - *note Modeline Variables:: + * Sequences consisting of `C-c' followed by `{', `}', `<', `>', `:' + or `;' are also reserved for major modes. + + * Sequences consisting of `C-c' followed by any other punctuation + character are allocated for minor modes. Using them in a major + mode is not absolutely prohibited, but if you do that, the major + mode binding may be shadowed from time to time by minor modes. + + * You should not bind `C-h' following any prefix character (including + `C-c'). If you don't bind `C-h', it is automatically available as + a help character for listing the subcommands of the prefix + character. + + * You should not bind a key sequence ending in except following + another . (That is, it is ok to bind a sequence ending in + ` '.) + + The reason for this rule is that a non-prefix binding for in + any context prevents recognition of escape sequences as function + keys in that context. + + * Applications should not bind mouse events based on button 1 with + the shift key held down. These events include `S-mouse-1', + `M-S-mouse-1', `C-S-mouse-1', and so on. They are reserved for + users. + + * Modes should redefine `mouse-2' as a command to follow some sort of + reference in the text of a buffer, if users usually would not want + to alter the text in that buffer by hand. Modes such as Dired, + Info, Compilation, and Occur redefine it in this way. + + * When a package provides a modification of ordinary Emacs behavior, + it is good to include a command to enable and disable the feature, + Provide a command named `WHATEVER-mode' which turns the feature on + or off, and make it autoload (*note Autoload::). Design the + package so that simply loading it has no visible effect--that + should not enable the feature. Users will request the feature by + invoking the command. + + * It is a bad idea to define aliases for the Emacs primitives. Use + the standard names instead. + + * Redefining an Emacs primitive is an even worse idea. It may do + the right thing for a particular program, but there is no telling + what other programs might break as a result. + + * If a file does replace any of the functions or library programs of + standard XEmacs, prominent comments at the beginning of the file + should say which functions are replaced, and how the behavior of + the replacements differs from that of the originals. + + * Please keep the names of your XEmacs Lisp source files to 13 + characters or less. This way, if the files are compiled, the + compiled files' names will be 14 characters or less, which is + short enough to fit on all kinds of Unix systems. + + * Don't use `next-line' or `previous-line' in programs; nearly + always, `forward-line' is more convenient as well as more + predictable and robust. *Note Text Lines::. + + * Don't call functions that set the mark, unless setting the mark is + one of the intended features of your program. The mark is a + user-level feature, so it is incorrect to change the mark except + to supply a value for the user's benefit. *Note The Mark::. + + In particular, don't use these functions: + + * `beginning-of-buffer', `end-of-buffer' + + * `replace-string', `replace-regexp' + + If you just want to move point, or replace a certain string, + without any of the other features intended for interactive users, + you can replace these functions with one or two lines of simple + Lisp code. + + * Use lists rather than vectors, except when there is a particular + reason to use a vector. Lisp has more facilities for manipulating + lists than for vectors, and working with lists is usually more + convenient. + + Vectors are advantageous for tables that are substantial in size + and are accessed in random order (not searched front to back), + provided there is no need to insert or delete elements (only lists + allow that). + + * The recommended way to print a message in the echo area is with + the `message' function, not `princ'. *Note The Echo Area::. + + * When you encounter an error condition, call the function `error' + (or `signal'). The function `error' does not return. *Note + Signaling Errors::. + + Do not use `message', `throw', `sleep-for', or `beep' to report + errors. + + * An error message should start with a capital letter but should not + end with a period. + + * Try to avoid using recursive edits. Instead, do what the Rmail `e' + command does: use a new local keymap that contains one command + defined to switch back to the old local keymap. Or do what the + `edit-options' command does: switch to another buffer and let the + user switch back at will. *Note Recursive Editing::. + + * In some other systems there is a convention of choosing variable + names that begin and end with `*'. We don't use that convention + in Emacs Lisp, so please don't use it in your programs. (Emacs + uses such names only for program-generated buffers.) The users + will find Emacs more coherent if all libraries use the same + conventions. + + * Indent each function with `C-M-q' (`indent-sexp') using the + default indentation parameters. + + * Don't make a habit of putting close-parentheses on lines by + themselves; Lisp programmers find this disconcerting. Once in a + while, when there is a sequence of many consecutive + close-parentheses, it may make sense to split them in one or two + significant places. + + * Please put a copyright notice on the file if you give copies to + anyone. Use the same lines that appear at the top of the Lisp + files in XEmacs itself. If you have not signed papers to assign + the copyright to the Foundation, then place your name in the + copyright notice in place of the Foundation's name.  -File: lispref.info, Node: Standard Keymaps, Next: Standard Hooks, Prev: Standard Buffer-Local Variables, Up: Top - -Standard Keymaps -**************** - - The following symbols are used as the names for various keymaps. -Some of these exist when XEmacs is first started, others are loaded -only when their respective mode is used. This is not an exhaustive -list. - - Almost all of these maps are used as local maps. Indeed, of the -modes that presently exist, only Vip mode and Terminal mode ever change -the global keymap. - -`bookmark-map' - A keymap containing bindings to bookmark functions. - -`Buffer-menu-mode-map' - A keymap used by Buffer Menu mode. - -`c++-mode-map' - A keymap used by C++ mode. - -`c-mode-map' - A keymap used by C mode. A sparse keymap used by C mode. - -`command-history-map' - A keymap used by Command History mode. - -`ctl-x-4-map' - A keymap for subcommands of the prefix `C-x 4'. - -`ctl-x-5-map' - A keymap for subcommands of the prefix `C-x 5'. - -`ctl-x-map' - A keymap for `C-x' commands. - -`debugger-mode-map' - A keymap used by Debugger mode. - -`dired-mode-map' - A keymap for `dired-mode' buffers. - -`edit-abbrevs-map' - A keymap used in `edit-abbrevs'. - -`edit-tab-stops-map' - A keymap used in `edit-tab-stops'. - -`electric-buffer-menu-mode-map' - A keymap used by Electric Buffer Menu mode. - -`electric-history-map' - A keymap used by Electric Command History mode. - -`emacs-lisp-mode-map' - A keymap used by Emacs Lisp mode. - -`help-map' - A keymap for characters following the Help key. - -`Helper-help-map' - A keymap used by the help utility package. - It has the same keymap in its value cell and in its function cell. - -`Info-edit-map' - A keymap used by the `e' command of Info. - -`Info-mode-map' - A keymap containing Info commands. - -`isearch-mode-map' - A keymap that defines the characters you can type within - incremental search. - -`itimer-edit-map' - A keymap used when in Itimer Edit mode. - -`lisp-interaction-mode-map' - A keymap used by Lisp mode. - -`lisp-mode-map' - A keymap used by Lisp mode. - - A keymap for minibuffer input with completion. - -`minibuffer-local-isearch-map' - A keymap for editing isearch strings in the minibuffer. - -`minibuffer-local-map' - Default keymap to use when reading from the minibuffer. - -`minibuffer-local-must-match-map' - A keymap for minibuffer input with completion, for exact match. - -`mode-specific-map' - The keymap for characters following `C-c'. Note, this is in the - global map. This map is not actually mode specific: its name was - chosen to be informative for the user in `C-h b' - (`display-bindings'), where it describes the main use of the `C-c' - prefix key. - -`modeline-map' - The keymap consulted for mouse-clicks on the modeline of a window. - -`objc-mode-map' - A keymap used in Objective C mode as a local map. - -`occur-mode-map' - A local keymap used by Occur mode. - -`overriding-local-map' - A keymap that overrides all other local keymaps. - -`query-replace-map' - A local keymap used for responses in `query-replace' and related - commands; also for `y-or-n-p' and `map-y-or-n-p'. The functions - that use this map do not support prefix keys; they look up one - event at a time. - -`read-expression-map' - The minibuffer keymap used for reading Lisp expressions. - -`read-shell-command-map' - The minibuffer keymap used by shell-command and related commands. - -`shared-lisp-mode-map' - A keymap for commands shared by all sorts of Lisp modes. - -`text-mode-map' - A keymap used by Text mode. - -`toolbar-map' - The keymap consulted for mouse-clicks over a toolbar. - -`view-mode-map' - A keymap used by View mode. +File: lispref.info, Node: Compilation Tips, Next: Documentation Tips, Prev: Style Tips, Up: Tips + +Tips for Making Compiled Code Fast +================================== + + Here are ways of improving the execution speed of byte-compiled Lisp +programs. + + * Use the `profile' library to profile your program. See the file + `profile.el' for instructions. + + * Use iteration rather than recursion whenever possible. Function + calls are slow in XEmacs Lisp even when a compiled function is + calling another compiled function. + + * Using the primitive list-searching functions `memq', `member', + `assq', or `assoc' is even faster than explicit iteration. It may + be worth rearranging a data structure so that one of these + primitive search functions can be used. + + * Certain built-in functions are handled specially in byte-compiled + code, avoiding the need for an ordinary function call. It is a + good idea to use these functions rather than alternatives. To see + whether a function is handled specially by the compiler, examine + its `byte-compile' property. If the property is non-`nil', then + the function is handled specially. + + For example, the following input will show you that `aref' is + compiled specially (*note Array Functions::) while `elt' is not + (*note Sequence Functions::): + + (get 'aref 'byte-compile) + => byte-compile-two-args + + (get 'elt 'byte-compile) + => nil + + * If calling a small function accounts for a substantial part of + your program's running time, make the function inline. This + eliminates the function call overhead. Since making a function + inline reduces the flexibility of changing the program, don't do + it unless it gives a noticeable speedup in something slow enough + that users care about the speed. *Note Inline Functions::.  -File: lispref.info, Node: Standard Hooks, Next: Index, Prev: Standard Keymaps, Up: Top - -Standard Hooks -************** - - The following is a list of hook variables that let you provide -functions to be called from within Emacs on suitable occasions. - - Most of these variables have names ending with `-hook'. They are -"normal hooks", run by means of `run-hooks'. The value of such a hook -is a list of functions. The recommended way to put a new function on -such a hook is to call `add-hook'. *Note Hooks::, for more information -about using hooks. - - The variables whose names end in `-function' have single functions -as their values. Usually there is a specific reason why the variable is -not a normal hook, such as the need to pass arguments to the function. -(In older Emacs versions, some of these variables had names ending in -`-hook' even though they were not normal hooks.) - - The variables whose names end in `-hooks' or `-functions' have lists -of functions as their values, but these functions are called in a -special way (they are passed arguments, or else their values are used). - -`activate-menubar-hook' - -`activate-popup-menu-hook' - -`ad-definition-hooks' - -`adaptive-fill-function' - -`add-log-current-defun-function' - -`after-change-functions' - -`after-delete-annotation-hook' - -`after-init-hook' - -`after-insert-file-functions' - -`after-revert-hook' - -`after-save-hook' - -`after-set-visited-file-name-hooks' - -`after-write-file-hooks' - -`auto-fill-function' - -`auto-save-hook' - -`before-change-functions' - -`before-delete-annotation-hook' - -`before-init-hook' - -`before-revert-hook' - -`blink-paren-function' - -`buffers-menu-switch-to-buffer-function' - -`c++-mode-hook' - -`c-delete-function' - -`c-mode-common-hook' - -`c-mode-hook' - -`c-special-indent-hook' - -`calendar-load-hook' - -`change-major-mode-hook' - -`command-history-hook' - -`comment-indent-function' - -`compilation-buffer-name-function' - -`compilation-exit-message-function' - -`compilation-finish-function' - -`compilation-parse-errors-function' - -`compilation-mode-hook' - -`create-console-hook' - -`create-device-hook' - -`create-frame-hook' - -`dabbrev-friend-buffer-function' - -`dabbrev-select-buffers-function' - -`delete-console-hook' - -`delete-device-hook' - -`delete-frame-hook' - -`deselect-frame-hook' - -`diary-display-hook' - -`diary-hook' - -`dired-after-readin-hook' - -`dired-before-readin-hook' - -`dired-load-hook' - -`dired-mode-hook' - -`disabled-command-hook' - -`display-buffer-function' - -`ediff-after-setup-control-frame-hook' - -`ediff-after-setup-windows-hook' - -`ediff-before-setup-control-frame-hook' - -`ediff-before-setup-windows-hook' - -`ediff-brief-help-message-function' - -`ediff-cleanup-hook' - -`ediff-control-frame-position-function' - -`ediff-display-help-hook' - -`ediff-focus-on-regexp-matches-function' - -`ediff-forward-word-function' - -`ediff-hide-regexp-matches-function' - -`ediff-keymap-setup-hook' - -`ediff-load-hook' - -`ediff-long-help-message-function' - -`ediff-make-wide-display-function' - -`ediff-merge-split-window-function' - -`ediff-meta-action-function' - -`ediff-meta-redraw-function' +File: lispref.info, Node: Documentation Tips, Next: Comment Tips, Prev: Compilation Tips, Up: Tips + +Tips for Documentation Strings +============================== + + Here are some tips for the writing of documentation strings. + + * Every command, function, or variable intended for users to know + about should have a documentation string. + + * An internal variable or subroutine of a Lisp program might as well + have a documentation string. In earlier Emacs versions, you could + save space by using a comment instead of a documentation string, + but that is no longer the case. + + * The first line of the documentation string should consist of one + or two complete sentences that stand on their own as a summary. + `M-x apropos' displays just the first line, and if it doesn't + stand on its own, the result looks bad. In particular, start the + first line with a capital letter and end with a period. + + The documentation string can have additional lines that expand on + the details of how to use the function or variable. The + additional lines should be made up of complete sentences also, but + they may be filled if that looks good. + + * For consistency, phrase the verb in the first sentence of a + documentation string as an infinitive with "to" omitted. For + instance, use "Return the cons of A and B." in preference to + "Returns the cons of A and B." Usually it looks good to do + likewise for the rest of the first paragraph. Subsequent + paragraphs usually look better if they have proper subjects. + + * Write documentation strings in the active voice, not the passive, + and in the present tense, not the future. For instance, use + "Return a list containing A and B." instead of "A list containing + A and B will be returned." + + * Avoid using the word "cause" (or its equivalents) unnecessarily. + Instead of, "Cause Emacs to display text in boldface," write just + "Display text in boldface." + + * Do not start or end a documentation string with whitespace. + + * Format the documentation string so that it fits in an Emacs window + on an 80-column screen. It is a good idea for most lines to be no + wider than 60 characters. The first line can be wider if + necessary to fit the information that ought to be there. + + However, rather than simply filling the entire documentation + string, you can make it much more readable by choosing line breaks + with care. Use blank lines between topics if the documentation + string is long. + + * *Do not* indent subsequent lines of a documentation string so that + the text is lined up in the source code with the text of the first + line. This looks nice in the source code, but looks bizarre when + users view the documentation. Remember that the indentation + before the starting double-quote is not part of the string! + + * A variable's documentation string should start with `*' if the + variable is one that users would often want to set interactively. + If the value is a long list, or a function, or if the variable + would be set only in init files, then don't start the + documentation string with `*'. *Note Defining Variables::. + + * The documentation string for a variable that is a yes-or-no flag + should start with words such as "Non-nil means...", to make it + clear that all non-`nil' values are equivalent and indicate + explicitly what `nil' and non-`nil' mean. + + * When a function's documentation string mentions the value of an + argument of the function, use the argument name in capital letters + as if it were a name for that value. Thus, the documentation + string of the function `/' refers to its second argument as + `DIVISOR', because the actual argument name is `divisor'. + + Also use all caps for meta-syntactic variables, such as when you + show the decomposition of a list or vector into subunits, some of + which may vary. + + * When a documentation string refers to a Lisp symbol, write it as it + would be printed (which usually means in lower case), with + single-quotes around it. For example: `lambda'. There are two + exceptions: write t and nil without single-quotes. (In this + manual, we normally do use single-quotes for those symbols.) + + * Don't write key sequences directly in documentation strings. + Instead, use the `\\[...]' construct to stand for them. For + example, instead of writing `C-f', write `\\[forward-char]'. When + Emacs displays the documentation string, it substitutes whatever + key is currently bound to `forward-char'. (This is normally `C-f', + but it may be some other character if the user has moved key + bindings.) *Note Keys in Documentation::. + + * In documentation strings for a major mode, you will want to refer + to the key bindings of that mode's local map, rather than global + ones. Therefore, use the construct `\\<...>' once in the + documentation string to specify which key map to use. Do this + before the first use of `\\[...]'. The text inside the `\\<...>' + should be the name of the variable containing the local keymap for + the major mode. + + It is not practical to use `\\[...]' very many times, because + display of the documentation string will become slow. So use this + to describe the most important commands in your major mode, and + then use `\\{...}' to display the rest of the mode's keymap. -`ediff-mode-hook' - -`ediff-prepare-buffer-hook' - -`ediff-quit-hook' - -`ediff-registry-setup-hook' - -`ediff-select-hook' - -`ediff-session-action-function' - -`ediff-session-group-setup-hook' - -`ediff-setup-diff-regions-function' - -`ediff-show-registry-hook' - -`ediff-show-session-group-hook' - -`ediff-skip-diff-region-function' - -`ediff-split-window-function' - -`ediff-startup-hook' - -`ediff-suspend-hook' - -`ediff-toggle-read-only-function' - -`ediff-unselect-hook' - -`ediff-window-setup-function' - -`edit-picture-hook' - -`electric-buffer-menu-mode-hook' - -`electric-command-history-hook' - -`electric-help-mode-hook' - -`emacs-lisp-mode-hook' - -`fill-paragraph-function' - -`find-file-hooks' - -`find-file-not-found-hooks' - -`first-change-hook' - -`font-lock-after-fontify-buffer-hook' - -`font-lock-beginning-of-syntax-function' - -`font-lock-mode-hook' - -`fume-found-function-hook' - -`fume-list-mode-hook' - -`fume-rescan-buffer-hook' - -`fume-sort-function' - -`gnus-startup-hook' - -`hack-local-variables-hook' - -`highlight-headers-follow-url-function' - -`hyper-apropos-mode-hook' - -`indent-line-function' - -`indent-mim-hook' - -`indent-region-function' - -`initial-calendar-window-hook' - -`isearch-mode-end-hook' - -`isearch-mode-hook' - -`java-mode-hook' - -`kill-buffer-hook' - -`kill-buffer-query-functions' - -`kill-emacs-hook' - -`kill-emacs-query-functions' - -`kill-hooks' - -`LaTeX-mode-hook' - -`latex-mode-hook' - -`ledit-mode-hook' - -`lisp-indent-function' - -`lisp-interaction-mode-hook' - -`lisp-mode-hook' - -`list-diary-entries-hook' - -`load-read-function' - -`log-message-filter-function' - -`m2-mode-hook' - -`mail-citation-hook' - -`mail-mode-hook' - -`mail-setup-hook' - -`make-annotation-hook' - -`makefile-mode-hook' - -`map-frame-hook' - -`mark-diary-entries-hook' - -`medit-mode-hook' - -`menu-no-selection-hook' - -`mh-compose-letter-hook' - -`mh-folder-mode-hook' - -`mh-letter-mode-hook' - -`mim-mode-hook' - -`minibuffer-exit-hook' - -`minibuffer-setup-hook' - -`mode-motion-hook' - -`mouse-enter-frame-hook' - -`mouse-leave-frame-hook' - -`mouse-track-cleanup-hook' - -`mouse-track-click-hook' - -`mouse-track-down-hook' - -`mouse-track-drag-hook' - -`mouse-track-drag-up-hook' - -`mouse-track-up-hook' - -`mouse-yank-function' - -`news-mode-hook' - -`news-reply-mode-hook' - -`news-setup-hook' - -`nongregorian-diary-listing-hook' - -`nongregorian-diary-marking-hook' - -`nroff-mode-hook' - -`objc-mode-hook' - -`outline-mode-hook' - -`perl-mode-hook' - -`plain-TeX-mode-hook' - -`post-command-hook' - -`post-gc-hook' - -`pre-abbrev-expand-hook' - -`pre-command-hook' - -`pre-display-buffer-function' - -`pre-gc-hook' - -`pre-idle-hook' - -`print-diary-entries-hook' - -`prolog-mode-hook' - -`protect-innocence-hook' - -`remove-message-hook' - -`revert-buffer-function' - -`revert-buffer-insert-contents-function' - -`rmail-edit-mode-hook' - -`rmail-mode-hook' - -`rmail-retry-setup-hook' - -`rmail-summary-mode-hook' - -`scheme-indent-hook' - -`scheme-mode-hook' - -`scribe-mode-hook' - -`select-frame-hook' - -`send-mail-function' - -`shell-mode-hook' - -`shell-set-directory-error-hook' - -`special-display-function' - -`suspend-hook' - -`suspend-resume-hook' - -`temp-buffer-show-function' - -`term-setup-hook' - -`terminal-mode-hook' - -`terminal-mode-break-hook' - -`TeX-mode-hook' - -`tex-mode-hook' - -`text-mode-hook' - -`today-visible-calendar-hook' - -`today-invisible-calendar-hook' - -`tooltalk-message-handler-hook' - -`tooltalk-pattern-handler-hook' - -`tooltalk-unprocessed-message-hook' - -`unmap-frame-hook' - -`vc-checkin-hook' - -`vc-checkout-writable-buffer-hook' - -`vc-log-after-operation-hook' - -`vc-make-buffer-writable-hook' - -`view-hook' - -`vm-arrived-message-hook' - -`vm-arrived-messages-hook' - -`vm-chop-full-name-function' - -`vm-display-buffer-hook' - -`vm-edit-message-hook' - -`vm-forward-message-hook' - -`vm-iconify-frame-hook' - -`vm-inhibit-write-file-hook' - -`vm-key-functions' - -`vm-mail-hook' - -`vm-mail-mode-hook' - -`vm-menu-setup-hook' - -`vm-mode-hook' - -`vm-quit-hook' - -`vm-rename-current-buffer-function' + +File: lispref.info, Node: Comment Tips, Next: Library Headers, Prev: Documentation Tips, Up: Tips + +Tips on Writing Comments +======================== + + We recommend these conventions for where to put comments and how to +indent them: + +`;' + Comments that start with a single semicolon, `;', should all be + aligned to the same column on the right of the source code. Such + comments usually explain how the code on the same line does its + job. In Lisp mode and related modes, the `M-;' + (`indent-for-comment') command automatically inserts such a `;' in + the right place, or aligns such a comment if it is already present. + + This and following examples are taken from the Emacs sources. + + (setq base-version-list ; there was a base + (assoc (substring fn 0 start-vn) ; version to which + file-version-assoc-list)) ; this looks like + ; a subversion + +`;;' + Comments that start with two semicolons, `;;', should be aligned to + the same level of indentation as the code. Such comments usually + describe the purpose of the following lines or the state of the + program at that point. For example: + + (prog1 (setq auto-fill-function + ... + ... + ;; update modeline + (redraw-modeline))) + + Every function that has no documentation string (because it is use + only internally within the package it belongs to), should have + instead a two-semicolon comment right before the function, + explaining what the function does and how to call it properly. + Explain precisely what each argument means and how the function + interprets its possible values. + +`;;;' + Comments that start with three semicolons, `;;;', should start at + the left margin. Such comments are used outside function + definitions to make general statements explaining the design + principles of the program. For example: + + ;;; This Lisp code is run in XEmacs + ;;; when it is to operate as a server + ;;; for other processes. + + Another use for triple-semicolon comments is for commenting out + lines within a function. We use triple-semicolons for this + precisely so that they remain at the left margin. + + (defun foo (a) + ;;; This is no longer necessary. + ;;; (force-mode-line-update) + (message "Finished with %s" a)) + +`;;;;' + Comments that start with four semicolons, `;;;;', should be aligned + to the left margin and are used for headings of major sections of a + program. For example: + + ;;;; The kill ring + +The indentation commands of the Lisp modes in XEmacs, such as `M-;' +(`indent-for-comment') and (`lisp-indent-line') automatically +indent comments according to these conventions, depending on the number +of semicolons. *Note Manipulating Comments: (xemacs)Comments. -`vm-reply-hook' + +File: lispref.info, Node: Library Headers, Prev: Comment Tips, Up: Tips + +Conventional Headers for XEmacs Libraries +========================================= + + XEmacs has conventions for using special comments in Lisp libraries +to divide them into sections and give information such as who wrote +them. This section explains these conventions. First, an example: + + ;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers + + ;; Copyright (C) 1992 Free Software Foundation, Inc. + + ;; Author: Eric S. Raymond + ;; Maintainer: Eric S. Raymond + ;; Created: 14 Jul 1992 + ;; Version: 1.2 + ;; Keywords: docs + + ;; This file is part of XEmacs. + COPYING PERMISSIONS... + + The very first line should have this format: + + ;;; FILENAME --- DESCRIPTION + +The description should be complete in one line. + + After the copyright notice come several "header comment" lines, each +beginning with `;; HEADER-NAME:'. Here is a table of the conventional +possibilities for HEADER-NAME: + +`Author' + This line states the name and net address of at least the principal + author of the library. + + If there are multiple authors, you can list them on continuation + lines led by `;;' and a tab character, like this: + + ;; Author: Ashwin Ram + ;; Dave Sill + ;; Dave Brennan + ;; Eric Raymond + +`Maintainer' + This line should contain a single name/address as in the Author + line, or an address only, or the string `FSF'. If there is no + maintainer line, the person(s) in the Author field are presumed to + be the maintainers. The example above is mildly bogus because the + maintainer line is redundant. + + The idea behind the `Author' and `Maintainer' lines is to make + possible a Lisp function to "send mail to the maintainer" without + having to mine the name out by hand. + + Be sure to surround the network address with `<...>' if you + include the person's full name as well as the network address. + +`Created' + This optional line gives the original creation date of the file. + For historical interest only. + +`Version' + If you wish to record version numbers for the individual Lisp + program, put them in this line. + +`Adapted-By' + In this header line, place the name of the person who adapted the + library for installation (to make it fit the style conventions, for + example). + +`Keywords' + This line lists keywords for the `finder-by-keyword' help command. + This field is important; it's how people will find your package + when they're looking for things by topic area. To separate the + keywords, you can use spaces, commas, or both. + + Just about every Lisp library ought to have the `Author' and +`Keywords' header comment lines. Use the others if they are +appropriate. You can also put in header lines with other header +names--they have no standard meanings, so they can't do any harm. + + We use additional stylized comments to subdivide the contents of the +library file. Here is a table of them: + +`;;; Commentary:' + This begins introductory comments that explain how the library + works. It should come right after the copying permissions. + +`;;; Change log:' + This begins change log information stored in the library file (if + you store the change history there). For most of the Lisp files + distributed with XEmacs, the change history is kept in the file + `ChangeLog' and not in the source file at all; these files do not + have a `;;; Change log:' line. + +`;;; Code:' + This begins the actual code of the program. + +`;;; FILENAME ends here' + This is the "footer line"; it appears at the very end of the file. + Its purpose is to enable people to detect truncated versions of + the file from the lack of a footer line. -`vm-resend-bounced-message-hook' + +File: lispref.info, Node: Building XEmacs and Object Allocation, Next: Standard Errors, Prev: Tips, Up: Top -`vm-resend-message-hook' +Building XEmacs; Allocation of Objects +************************************** -`vm-retrieved-spooled-mail-hook' + This chapter describes how the runnable XEmacs executable is dumped +with the preloaded Lisp libraries in it and how storage is allocated. -`vm-select-message-hook' + There is an entire separate document, the `XEmacs Internals Manual', +devoted to the internals of XEmacs from the perspective of the C +programmer. It contains much more detailed information about the build +process, the allocation and garbage-collection process, and other +aspects related to the internals of XEmacs. -`vm-select-new-message-hook' +* Menu: -`vm-select-unread-message-hook' +* Building XEmacs:: How to preload Lisp libraries into XEmacs. +* Pure Storage:: A kludge to make preloaded Lisp functions sharable. +* Garbage Collection:: Reclaiming space for Lisp objects no longer used. -`vm-send-digest-hook' + +File: lispref.info, Node: Building XEmacs, Next: Pure Storage, Up: Building XEmacs and Object Allocation + +Building XEmacs +=============== + + This section explains the steps involved in building the XEmacs +executable. You don't have to know this material to build and install +XEmacs, since the makefiles do all these things automatically. This +information is pertinent to XEmacs maintenance. + + The `XEmacs Internals Manual' contains more information about this. + + Compilation of the C source files in the `src' directory produces an +executable file called `temacs', also called a "bare impure XEmacs". +It contains the XEmacs Lisp interpreter and I/O routines, but not the +editing commands. + + Before XEmacs is actually usable, a number of Lisp files need to be +loaded. These define all the editing commands, plus most of the startup +code and many very basic Lisp primitives. This is accomplished by +loading the file `loadup.el', which in turn loads all of the other +standardly-loaded Lisp files. + + It takes a substantial time to load the standard Lisp files. +Luckily, you don't have to do this each time you run XEmacs; `temacs' +can dump out an executable program called `xemacs' that has these files +preloaded. `xemacs' starts more quickly because it does not need to +load the files. This is the XEmacs executable that is normally +installed. + + To create `xemacs', use the command `temacs -batch -l loadup dump'. +The purpose of `-batch' here is to tell `temacs' to run in +non-interactive, command-line mode. (`temacs' can _only_ run in this +fashion. Part of the code required to initialize frames and faces is +in Lisp, and must be loaded before XEmacs is able to create any frames.) +The argument `dump' tells `loadup.el' to dump a new executable named +`xemacs'. + + The dumping process is highly system-specific, and some operating +systems don't support dumping. On those systems, you must start XEmacs +with the `temacs -batch -l loadup run-temacs' command each time you use +it. This takes a substantial time, but since you need to start Emacs +once a day at most--or once a week if you never log out--the extra time +is not too severe a problem. (In older versions of Emacs, you started +Emacs from `temacs' using `temacs -l loadup'.) + + You are free to start XEmacs directly from `temacs' if you want, +even if there is already a dumped `xemacs'. Normally you wouldn't want +to do that; but the Makefiles do this when you rebuild XEmacs using +`make all-elc', which builds XEmacs and simultaneously compiles any +out-of-date Lisp files. (You need `xemacs' in order to compile Lisp +files. However, you also need the compiled Lisp files in order to dump +out `xemacs'. If both of these are missing or corrupted, you are out +of luck unless you're able to bootstrap `xemacs' from `temacs'. Note +that `make all-elc' actually loads the alternative loadup file +`loadup-el.el', which works like `loadup.el' but disables the +pure-copying process and forces XEmacs to ignore any compiled Lisp +files even if they exist.) + + You can specify additional files to preload by writing a library +named `site-load.el' that loads them. You may need to increase the +value of `PURESIZE', in `src/puresize.h', to make room for the +additional files. You should _not_ modify this file directly, however; +instead, use the `--puresize' configuration option. (If you run out of +pure space while dumping `xemacs', you will be told how much pure space +you actually will need.) However, the advantage of preloading +additional files decreases as machines get faster. On modern machines, +it is often not advisable, especially if the Lisp code is on a file +system local to the machine running XEmacs. + + You can specify other Lisp expressions to execute just before dumping +by putting them in a library named `site-init.el'. However, if they +might alter the behavior that users expect from an ordinary unmodified +XEmacs, it is better to put them in `default.el', so that users can +override them if they wish. *Note Start-up Summary::. + + Before `loadup.el' dumps the new executable, it finds the +documentation strings for primitive and preloaded functions (and +variables) in the file where they are stored, by calling +`Snarf-documentation' (*note Accessing Documentation::). These strings +were moved out of the `xemacs' executable to make it smaller. *Note +Documentation Basics::. + + - Function: dump-emacs to-file from-file + This function dumps the current state of XEmacs into an executable + file TO-FILE. It takes symbols from FROM-FILE (this is normally + the executable file `temacs'). + + If you use this function in an XEmacs that was already dumped, you + must set `command-line-processed' to `nil' first for good results. + *Note Command Line Arguments::. + + - Function: run-emacs-from-temacs &rest args + This is the function that implements the `run-temacs' command-line + argument. It is called from `loadup.el' as appropriate. You + should most emphatically _not_ call this yourself; it will + reinitialize your XEmacs process and you'll be sorry. + + - Command: emacs-version &optional arg + This function returns a string describing the version of XEmacs + that is running. It is useful to include this string in bug + reports. + + When called interactively with a prefix argument, insert string at + point. Don't use this function in programs to choose actions + according to the system configuration; look at + `system-configuration' instead. + + (emacs-version) + => "XEmacs 20.1 [Lucid] (i586-unknown-linux2.0.29) + of Mon Apr 7 1997 on altair.xemacs.org" + + Called interactively, the function prints the same information in + the echo area. + + - Variable: emacs-build-time + The value of this variable is the time at which XEmacs was built + at the local site. + + emacs-build-time "Mon Apr 7 20:28:52 1997" + => + + - Variable: emacs-version + The value of this variable is the version of Emacs being run. It + is a string, e.g. `"20.1 XEmacs Lucid"'. + + The following two variables did not exist before FSF GNU Emacs +version 19.23 and XEmacs version 19.10, which reduces their usefulness +at present, but we hope they will be convenient in the future. + + - Variable: emacs-major-version + The major version number of Emacs, as an integer. For XEmacs + version 20.1, the value is 20. + + - Variable: emacs-minor-version + The minor version number of Emacs, as an integer. For XEmacs + version 20.1, the value is 1. -`vm-summary-mode-hook' + +File: lispref.info, Node: Pure Storage, Next: Garbage Collection, Prev: Building XEmacs, Up: Building XEmacs and Object Allocation + +Pure Storage +============ + + XEmacs Lisp uses two kinds of storage for user-created Lisp objects: +"normal storage" and "pure storage". Normal storage is where all the +new data created during an XEmacs session is kept; see the following +section for information on normal storage. Pure storage is used for +certain data in the preloaded standard Lisp files--data that should +never change during actual use of XEmacs. + + Pure storage is allocated only while `temacs' is loading the +standard preloaded Lisp libraries. In the file `xemacs', it is marked +as read-only (on operating systems that permit this), so that the +memory space can be shared by all the XEmacs jobs running on the machine +at once. Pure storage is not expandable; a fixed amount is allocated +when XEmacs is compiled, and if that is not sufficient for the preloaded +libraries, `temacs' aborts with an error message. If that happens, you +must increase the compilation parameter `PURESIZE' using the +`--puresize' option to `configure'. This normally won't happen unless +you try to preload additional libraries or add features to the standard +ones. + + - Function: purecopy object + This function makes a copy of OBJECT in pure storage and returns + it. It copies strings by simply making a new string with the same + characters in pure storage. It recursively copies the contents of + vectors and cons cells. It does not make copies of other objects + such as symbols, but just returns them unchanged. It signals an + error if asked to copy markers. + + This function is a no-op except while XEmacs is being built and + dumped; it is usually called only in the file + `xemacs/lisp/prim/loaddefs.el', but a few packages call it just in + case you decide to preload them. + + - Variable: pure-bytes-used + The value of this variable is the number of bytes of pure storage + allocated so far. Typically, in a dumped XEmacs, this number is + very close to the total amount of pure storage available--if it + were not, we would preallocate less. + + - Variable: purify-flag + This variable determines whether `defun' should make a copy of the + function definition in pure storage. If it is non-`nil', then the + function definition is copied into pure storage. + + This flag is `t' while loading all of the basic functions for + building XEmacs initially (allowing those functions to be sharable + and non-collectible). Dumping XEmacs as an executable always + writes `nil' in this variable, regardless of the value it actually + has before and after dumping. + + You should not change this flag in a running XEmacs. -`vm-summary-pointer-update-hook' + +File: lispref.info, Node: Garbage Collection, Prev: Pure Storage, Up: Building XEmacs and Object Allocation + +Garbage Collection +================== + + When a program creates a list or the user defines a new function +(such as by loading a library), that data is placed in normal storage. +If normal storage runs low, then XEmacs asks the operating system to +allocate more memory in blocks of 2k bytes. Each block is used for one +type of Lisp object, so symbols, cons cells, markers, etc., are +segregated in distinct blocks in memory. (Vectors, long strings, +buffers and certain other editing types, which are fairly large, are +allocated in individual blocks, one per object, while small strings are +packed into blocks of 8k bytes. [More correctly, a string is allocated +in two sections: a fixed size chunk containing the length, list of +extents, etc.; and a chunk containing the actual characters in the +string. It is this latter chunk that is either allocated individually +or packed into 8k blocks. The fixed size chunk is packed into 2k +blocks, as for conses, markers, etc.]) + + It is quite common to use some storage for a while, then release it +by (for example) killing a buffer or deleting the last pointer to an +object. XEmacs provides a "garbage collector" to reclaim this +abandoned storage. (This name is traditional, but "garbage recycler" +might be a more intuitive metaphor for this facility.) + + The garbage collector operates by finding and marking all Lisp +objects that are still accessible to Lisp programs. To begin with, it +assumes all the symbols, their values and associated function +definitions, and any data presently on the stack, are accessible. Any +objects that can be reached indirectly through other accessible objects +are also accessible. + + When marking is finished, all objects still unmarked are garbage. No +matter what the Lisp program or the user does, it is impossible to refer +to them, since there is no longer a way to reach them. Their space +might as well be reused, since no one will miss them. The second +("sweep") phase of the garbage collector arranges to reuse them. + + The sweep phase puts unused cons cells onto a "free list" for future +allocation; likewise for symbols, markers, extents, events, floats, +compiled-function objects, and the fixed-size portion of strings. It +compacts the accessible small string-chars chunks so they occupy fewer +8k blocks; then it frees the other 8k blocks. Vectors, buffers, +windows, and other large objects are individually allocated and freed +using `malloc' and `free'. + + Common Lisp note: unlike other Lisps, XEmacs Lisp does not call + the garbage collector when the free list is empty. Instead, it + simply requests the operating system to allocate more storage, and + processing continues until `gc-cons-threshold' bytes have been + used. + + This means that you can make sure that the garbage collector will + not run during a certain portion of a Lisp program by calling the + garbage collector explicitly just before it (provided that portion + of the program does not use so much space as to force a second + garbage collection). + + - Command: garbage-collect + This command runs a garbage collection, and returns information on + the amount of space in use. (Garbage collection can also occur + spontaneously if you use more than `gc-cons-threshold' bytes of + Lisp data since the previous garbage collection.) + + `garbage-collect' returns a list containing the following + information: + + ((USED-CONSES . FREE-CONSES) + (USED-SYMS . FREE-SYMS) + (USED-MARKERS . FREE-MARKERS) + USED-STRING-CHARS + USED-VECTOR-SLOTS + (PLIST)) + + => ((73362 . 8325) (13718 . 164) + (5089 . 5098) 949121 118677 + (conses-used 73362 conses-free 8329 cons-storage 658168 + symbols-used 13718 symbols-free 164 symbol-storage 335216 + bit-vectors-used 0 bit-vectors-total-length 0 + bit-vector-storage 0 vectors-used 7882 + vectors-total-length 118677 vector-storage 537764 + compiled-functions-used 1336 compiled-functions-free 37 + compiled-function-storage 44440 short-strings-used 28829 + long-strings-used 2 strings-free 7722 + short-strings-total-length 916657 short-string-storage 1179648 + long-strings-total-length 32464 string-header-storage 441504 + floats-used 3 floats-free 43 float-storage 2044 markers-used 5089 + markers-free 5098 marker-storage 245280 events-used 103 + events-free 835 event-storage 110656 extents-used 10519 + extents-free 2718 extent-storage 372736 + extent-auxiliarys-used 111 extent-auxiliarys-freed 3 + extent-auxiliary-storage 4440 window-configurations-used 39 + window-configurations-on-free-list 5 + window-configurations-freed 10 window-configuration-storage 9492 + popup-datas-used 3 popup-data-storage 72 toolbar-buttons-used 62 + toolbar-button-storage 4960 toolbar-datas-used 12 + toolbar-data-storage 240 symbol-value-buffer-locals-used 182 + symbol-value-buffer-local-storage 5824 + symbol-value-lisp-magics-used 22 + symbol-value-lisp-magic-storage 1496 + symbol-value-varaliases-used 43 + symbol-value-varalias-storage 1032 opaque-lists-used 2 + opaque-list-storage 48 color-instances-used 12 + color-instance-storage 288 font-instances-used 5 + font-instance-storage 180 opaques-used 11 opaque-storage 312 + range-tables-used 1 range-table-storage 16 faces-used 34 + face-storage 2584 glyphs-used 124 glyph-storage 4464 + specifiers-used 775 specifier-storage 43869 weak-lists-used 786 + weak-list-storage 18864 char-tables-used 40 + char-table-storage 41920 buffers-used 25 buffer-storage 7000 + extent-infos-used 457 extent-infos-freed 73 + extent-info-storage 9140 keymaps-used 275 keymap-storage 12100 + consoles-used 4 console-storage 384 command-builders-used 2 + command-builder-storage 120 devices-used 2 device-storage 344 + frames-used 3 frame-storage 624 image-instances-used 47 + image-instance-storage 3008 windows-used 27 windows-freed 2 + window-storage 9180 lcrecord-lists-used 15 + lcrecord-list-storage 360 hash-tables-used 631 + hash-table-storage 25240 streams-used 1 streams-on-free-list 3 + streams-freed 12 stream-storage 91)) + + Here is a table explaining each element: + + USED-CONSES + The number of cons cells in use. + + FREE-CONSES + The number of cons cells for which space has been obtained + from the operating system, but that are not currently being + used. + + USED-SYMS + The number of symbols in use. + + FREE-SYMS + The number of symbols for which space has been obtained from + the operating system, but that are not currently being used. + + USED-MARKERS + The number of markers in use. + + FREE-MARKERS + The number of markers for which space has been obtained from + the operating system, but that are not currently being used. + + USED-STRING-CHARS + The total size of all strings, in characters. + + USED-VECTOR-SLOTS + The total number of elements of existing vectors. + + PLIST + A list of alternating keyword/value pairs providing more + detailed information. (As you can see above, quite a lot of + information is provided.) + + - User Option: gc-cons-threshold + The value of this variable is the number of bytes of storage that + must be allocated for Lisp objects after one garbage collection in + order to trigger another garbage collection. A cons cell counts + as eight bytes, a string as one byte per character plus a few + bytes of overhead, and so on; space allocated to the contents of + buffers does not count. Note that the subsequent garbage + collection does not happen immediately when the threshold is + exhausted, but only the next time the Lisp evaluator is called. + + The initial threshold value is 500,000. If you specify a larger + value, garbage collection will happen less often. This reduces the + amount of time spent garbage collecting, but increases total + memory use. You may want to do this when running a program that + creates lots of Lisp data. + + You can make collections more frequent by specifying a smaller + value, down to 10,000. A value less than 10,000 will remain in + effect only until the subsequent garbage collection, at which time + `garbage-collect' will set the threshold back to 10,000. (This does + not apply if XEmacs was configured with `--debug'. Therefore, be + careful when setting `gc-cons-threshold' in that case!) + + - Variable: pre-gc-hook + This is a normal hook to be run just before each garbage + collection. Interrupts, garbage collection, and errors are + inhibited while this hook runs, so be extremely careful in what + you add here. In particular, avoid consing, and do not interact + with the user. + + - Variable: post-gc-hook + This is a normal hook to be run just after each garbage collection. + Interrupts, garbage collection, and errors are inhibited while + this hook runs, so be extremely careful in what you add here. In + particular, avoid consing, and do not interact with the user. + + - Variable: gc-message + This is a string to print to indicate that a garbage collection is + in progress. This is printed in the echo area. If the selected + frame is on a window system and `gc-pointer-glyph' specifies a + value (i.e. a pointer image instance) in the domain of the + selected frame, the mouse cursor will change instead of this + message being printed. + + - Glyph: gc-pointer-glyph + This holds the pointer glyph used to indicate that a garbage + collection is in progress. If the selected window is on a window + system and this glyph specifies a value (i.e. a pointer image + instance) in the domain of the selected window, the cursor will be + changed as specified during garbage collection. Otherwise, a + message will be printed in the echo area, as controlled by + `gc-message'. *Note Glyphs::. + + If XEmacs was configured with `--debug', you can set the following +two variables to get direct information about all the allocation that +is happening in a segment of Lisp code. + + - Variable: debug-allocation + If non-zero, print out information to stderr about all objects + allocated. + + - Variable: debug-allocation-backtrace + Length (in stack frames) of short backtrace printed out by + `debug-allocation'. -`vm-summary-redo-hook' + +File: lispref.info, Node: Standard Errors, Next: Standard Buffer-Local Variables, Prev: Building XEmacs and Object Allocation, Up: Top -`vm-summary-update-hook' +Standard Errors +*************** -`vm-undisplay-buffer-hook' + Here is the complete list of the error symbols in standard Emacs, +grouped by concept. The list includes each symbol's message (on the +`error-message' property of the symbol) and a cross reference to a +description of how the error can occur. -`vm-visit-folder-hook' + Each error symbol has an `error-conditions' property that is a list +of symbols. Normally this list includes the error symbol itself and +the symbol `error'. Occasionally it includes additional symbols, which +are intermediate classifications, narrower than `error' but broader +than a single error symbol. For example, all the errors in accessing +files have the condition `file-error'. -`window-setup-hook' + As a special exception, the error symbol `quit' does not have the +condition `error', because quitting is not considered an error. -`write-contents-hooks' + *Note Errors::, for an explanation of how errors are generated and +handled. -`write-file-data-hooks' +`SYMBOL' + STRING; REFERENCE. -`write-file-hooks' +`error' + `"error"' + *Note Errors::. -`write-region-annotate-functions' +`quit' + `"Quit"' + *Note Quitting::. -`x-lost-selection-hooks' +`args-out-of-range' + `"Args out of range"' + *Note Sequences Arrays Vectors::. -`x-sent-selection-hooks' +`arith-error' + `"Arithmetic error"' + See `/' and `%' in *Note Numbers::. -`zmacs-activate-region-hook' +`beginning-of-buffer' + `"Beginning of buffer"' + *Note Motion::. -`zmacs-deactivate-region-hook' +`buffer-read-only' + `"Buffer is read-only"' + *Note Read Only Buffers::. + +`cyclic-function-indirection' + `"Symbol's chain of function indirections contains a loop"' + *Note Function Indirection::. + +`domain-error' + `"Arithmetic domain error"' +`end-of-buffer' + `"End of buffer"' + *Note Motion::. + +`end-of-file' + `"End of file during parsing"' + This is not a `file-error'. + *Note Input Functions::. + +`file-error' + This error and its subcategories do not have error-strings, + because the error message is constructed from the data items alone + when the error condition `file-error' is present. + *Note Files::. + +`file-locked' + This is a `file-error'. + *Note File Locks::. + +`file-already-exists' + This is a `file-error'. + *Note Writing to Files::. + +`file-supersession' + This is a `file-error'. + *Note Modification Time::. + +`invalid-byte-code' + `"Invalid byte code"' + *Note Byte Compilation::. + +`invalid-function' + `"Invalid function"' + *Note Classifying Lists::. + +`invalid-read-syntax' + `"Invalid read syntax"' + *Note Input Functions::. + +`invalid-regexp' + `"Invalid regexp"' + *Note Regular Expressions::. + +`mark-inactive' + `"The mark is not active now"' +`no-catch' + `"No catch for tag"' + *Note Catch and Throw::. + +`overflow-error' + `"Arithmetic overflow error"' +`protected-field' + `"Attempt to modify a protected field"' +`range-error' + `"Arithmetic range error"' +`search-failed' + `"Search failed"' + *Note Searching and Matching::. + +`setting-constant' + `"Attempt to set a constant symbol"' + *Note Variables that Never Change: Constant Variables. + +`singularity-error' + `"Arithmetic singularity error"' +`tooltalk-error' + `"ToolTalk error"' + *Note ToolTalk Support::. + +`undefined-keystroke-sequence' + `"Undefined keystroke sequence"' +`void-function' + `"Symbol's function definition is void"' + *Note Function Cells::. + +`void-variable' + `"Symbol's value as variable is void"' + *Note Accessing Variables::. + +`wrong-number-of-arguments' + `"Wrong number of arguments"' + *Note Classifying Lists::. + +`wrong-type-argument' + `"Wrong type argument"' + *Note Type Predicates::. + + These error types, which are all classified as special cases of +`arith-error', can occur on certain systems for invalid use of +mathematical functions. + +`domain-error' + `"Arithmetic domain error"' + *Note Math Functions::. + +`overflow-error' + `"Arithmetic overflow error"' + *Note Math Functions::. + +`range-error' + `"Arithmetic range error"' + *Note Math Functions::. + +`singularity-error' + `"Arithmetic singularity error"' + *Note Math Functions::. + +`underflow-error' + `"Arithmetic underflow error"' + *Note Math Functions::. -`zmacs-update-region-hook'