1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: CCL Expressions, Next: Calling CCL, Prev: CCL Statements, Up: CCL
58 CCL, unlike Lisp, uses infix expressions. The simplest CCL
59 expressions consist of a single OPERAND, either a register (one of `r0',
60 ..., `r0') or an integer. Complex expressions are lists of the form `(
61 EXPRESSION OPERATOR OPERAND )'. Unlike C, assignments are not
64 In the following table, X is the target resister for a "set". In
65 subexpressions, this is implicitly `r7'. This means that `>8', `//',
66 `de-sjis', and `en-sjis' cannot be used freely in subexpressions, since
67 they return parts of their values in `r7'. Y may be an expression,
68 register, or integer, while Z must be a register or an integer.
70 Name Operator Code C-like Description
71 CCL_PLUS `+' 0x00 X = Y + Z
72 CCL_MINUS `-' 0x01 X = Y - Z
73 CCL_MUL `*' 0x02 X = Y * Z
74 CCL_DIV `/' 0x03 X = Y / Z
75 CCL_MOD `%' 0x04 X = Y % Z
76 CCL_AND `&' 0x05 X = Y & Z
77 CCL_OR `|' 0x06 X = Y | Z
78 CCL_XOR `^' 0x07 X = Y ^ Z
79 CCL_LSH `<<' 0x08 X = Y << Z
80 CCL_RSH `>>' 0x09 X = Y >> Z
81 CCL_LSH8 `<8' 0x0A X = (Y << 8) | Z
82 CCL_RSH8 `>8' 0x0B X = Y >> 8, r[7] = Y & 0xFF
83 CCL_DIVMOD `//' 0x0C X = Y / Z, r[7] = Y % Z
84 CCL_LS `<' 0x10 X = (X < Y)
85 CCL_GT `>' 0x11 X = (X > Y)
86 CCL_EQ `==' 0x12 X = (X == Y)
87 CCL_LE `<=' 0x13 X = (X <= Y)
88 CCL_GE `>=' 0x14 X = (X >= Y)
89 CCL_NE `!=' 0x15 X = (X != Y)
90 CCL_ENCODE_SJIS `en-sjis' 0x16 X = HIGHER_BYTE (SJIS (Y, Z))
91 r[7] = LOWER_BYTE (SJIS (Y, Z)
92 CCL_DECODE_SJIS `de-sjis' 0x17 X = HIGHER_BYTE (DE-SJIS (Y, Z))
93 r[7] = LOWER_BYTE (DE-SJIS (Y, Z))
95 The CCL operators are as in C, with the addition of CCL_LSH8,
96 CCL_RSH8, CCL_DIVMOD, CCL_ENCODE_SJIS, and CCL_DECODE_SJIS. The
97 CCL_ENCODE_SJIS and CCL_DECODE_SJIS treat their first and second bytes
98 as the high and low bytes of a two-byte character code. (SJIS stands
99 for Shift JIS, an encoding of Japanese characters used by Microsoft.
100 CCL_ENCODE_SJIS is a complicated transformation of the Japanese
101 standard JIS encoding to Shift JIS. CCL_DECODE_SJIS is its inverse.)
102 It is somewhat odd to represent the SJIS operations in infix form.
105 File: lispref.info, Node: Calling CCL, Next: CCL Examples, Prev: CCL Expressions, Up: CCL
110 CCL programs are called automatically during Emacs buffer I/O when
111 the external representation has a coding system type of `shift-jis',
112 `big5', or `ccl'. The program is specified by the coding system (*note
113 Coding Systems::). You can also call CCL programs from other CCL
114 programs, and from Lisp using these functions:
116 - Function: ccl-execute ccl-program status
117 Execute CCL-PROGRAM with registers initialized by STATUS.
118 CCL-PROGRAM is a vector of compiled CCL code created by
119 `ccl-compile'. It is an error for the program to try to execute a
120 CCL I/O command. STATUS must be a vector of nine values,
121 specifying the initial value for the R0, R1 .. R7 registers and
122 for the instruction counter IC. A `nil' value for a register
123 initializer causes the register to be set to 0. A `nil' value for
124 the IC initializer causes execution to start at the beginning of
125 the program. When the program is done, STATUS is modified (by
126 side-effect) to contain the ending values for the corresponding
129 - Function: ccl-execute-on-string ccl-program status str &optional
131 Execute CCL-PROGRAM with initial STATUS on STRING. CCL-PROGRAM is
132 a vector of compiled CCL code created by `ccl-compile'. STATUS
133 must be a vector of nine values, specifying the initial value for
134 the R0, R1 .. R7 registers and for the instruction counter IC. A
135 `nil' value for a register initializer causes the register to be
136 set to 0. A `nil' value for the IC initializer causes execution
137 to start at the beginning of the program. An optional fourth
138 argument CONTINUE, if non-nil, causes the IC to remain on the
139 unsatisfied read operation if the program terminates due to
140 exhaustion of the input buffer. Otherwise the IC is set to the end
141 of the program. When the program is done, STATUS is modified (by
142 side-effect) to contain the ending values for the corresponding
143 registers and IC. Returns the resulting string.
145 To call a CCL program from another CCL program, it must first be
148 - Function: register-ccl-program name ccl-program
149 Register NAME for CCL program PROGRAM in `ccl-program-table'.
150 PROGRAM should be the compiled form of a CCL program, or nil.
151 Return index number of the registered CCL program.
153 Information about the processor time used by the CCL interpreter can
154 be obtained using these functions:
156 - Function: ccl-elapsed-time
157 Returns the elapsed processor time of the CCL interpreter as cons
158 of user and system time, as floating point numbers measured in
159 seconds. If only one overall value can be determined, the return
160 value will be a cons of that value and 0.
162 - Function: ccl-reset-elapsed-time
163 Resets the CCL interpreter's internal elapsed time registers.
166 File: lispref.info, Node: CCL Examples, Prev: Calling CCL, Up: CCL
171 This section is not yet written.
174 File: lispref.info, Node: Category Tables, Prev: CCL, Up: MULE
179 A category table is a type of char table used for keeping track of
180 categories. Categories are used for classifying characters for use in
181 regexps--you can refer to a category rather than having to use a
182 complicated [] expression (and category lookups are significantly
185 There are 95 different categories available, one for each printable
186 character (including space) in the ASCII charset. Each category is
187 designated by one such character, called a "category designator". They
188 are specified in a regexp using the syntax `\cX', where X is a category
189 designator. (This is not yet implemented.)
191 A category table specifies, for each character, the categories that
192 the character is in. Note that a character can be in more than one
193 category. More specifically, a category table maps from a character to
194 either the value `nil' (meaning the character is in no categories) or a
195 95-element bit vector, specifying for each of the 95 categories whether
196 the character is in that category.
198 Special Lisp functions are provided that abstract this, so you do not
199 have to directly manipulate bit vectors.
201 - Function: category-table-p obj
202 This function returns `t' if ARG is a category table.
204 - Function: category-table &optional buffer
205 This function returns the current category table. This is the one
206 specified by the current buffer, or by BUFFER if it is non-`nil'.
208 - Function: standard-category-table
209 This function returns the standard category table. This is the
210 one used for new buffers.
212 - Function: copy-category-table &optional table
213 This function constructs a new category table and return it. It
214 is a copy of the TABLE, which defaults to the standard category
217 - Function: set-category-table table &optional buffer
218 This function selects a new category table for BUFFER. One
219 argument, a category table. BUFFER defaults to the current buffer
222 - Function: category-designator-p obj
223 This function returns `t' if ARG is a category designator (a char
224 in the range `' '' to `'~'').
226 - Function: category-table-value-p obj
227 This function returns `t' if ARG is a category table value. Valid
228 values are `nil' or a bit vector of size 95.
231 File: lispref.info, Node: Tips, Next: Building XEmacs and Object Allocation, Prev: MULE, Up: Top
236 This chapter describes no additional features of XEmacs Lisp.
237 Instead it gives advice on making effective use of the features
238 described in the previous chapters.
242 * Style Tips:: Writing clean and robust programs.
243 * Compilation Tips:: Making compiled code run fast.
244 * Documentation Tips:: Writing readable documentation strings.
245 * Comment Tips:: Conventions for writing comments.
246 * Library Headers:: Standard headers for library packages.
249 File: lispref.info, Node: Style Tips, Next: Compilation Tips, Up: Tips
251 Writing Clean Lisp Programs
252 ===========================
254 Here are some tips for avoiding common errors in writing Lisp code
255 intended for widespread use:
257 * Since all global variables share the same name space, and all
258 functions share another name space, you should choose a short word
259 to distinguish your program from other Lisp programs. Then take
260 care to begin the names of all global variables, constants, and
261 functions with the chosen prefix. This helps avoid name conflicts.
263 This recommendation applies even to names for traditional Lisp
264 primitives that are not primitives in XEmacs Lisp--even to `cadr'.
265 Believe it or not, there is more than one plausible way to define
266 `cadr'. Play it safe; append your name prefix to produce a name
267 like `foo-cadr' or `mylib-cadr' instead.
269 If you write a function that you think ought to be added to Emacs
270 under a certain name, such as `twiddle-files', don't call it by
271 that name in your program. Call it `mylib-twiddle-files' in your
272 program, and send mail to `bug-gnu-emacs@prep.ai.mit.edu'
273 suggesting we add it to Emacs. If and when we do, we can change
274 the name easily enough.
276 If one prefix is insufficient, your package may use two or three
277 alternative common prefixes, so long as they make sense.
279 Separate the prefix from the rest of the symbol name with a hyphen,
280 `-'. This will be consistent with XEmacs itself and with most
283 * It is often useful to put a call to `provide' in each separate
284 library program, at least if there is more than one entry point to
287 * If a file requires certain other library programs to be loaded
288 beforehand, then the comments at the beginning of the file should
289 say so. Also, use `require' to make sure they are loaded.
291 * If one file FOO uses a macro defined in another file BAR, FOO
292 should contain this expression before the first use of the macro:
294 (eval-when-compile (require 'BAR))
296 (And BAR should contain `(provide 'BAR)', to make the `require'
297 work.) This will cause BAR to be loaded when you byte-compile
298 FOO. Otherwise, you risk compiling FOO without the necessary
299 macro loaded, and that would produce compiled code that won't work
300 right. *Note Compiling Macros::.
302 Using `eval-when-compile' avoids loading BAR when the compiled
303 version of FOO is _used_.
305 * If you define a major mode, make sure to run a hook variable using
306 `run-hooks', just as the existing major modes do. *Note Hooks::.
308 * If the purpose of a function is to tell you whether a certain
309 condition is true or false, give the function a name that ends in
310 `p'. If the name is one word, add just `p'; if the name is
311 multiple words, add `-p'. Examples are `framep' and
314 * If a user option variable records a true-or-false condition, give
315 it a name that ends in `-flag'.
317 * Please do not define `C-c LETTER' as a key in your major modes.
318 These sequences are reserved for users; they are the *only*
319 sequences reserved for users, so we cannot do without them.
321 Instead, define sequences consisting of `C-c' followed by a
322 non-letter. These sequences are reserved for major modes.
324 Changing all the major modes in Emacs 18 so they would follow this
325 convention was a lot of work. Abandoning this convention would
326 make that work go to waste, and inconvenience users.
328 * Sequences consisting of `C-c' followed by `{', `}', `<', `>', `:'
329 or `;' are also reserved for major modes.
331 * Sequences consisting of `C-c' followed by any other punctuation
332 character are allocated for minor modes. Using them in a major
333 mode is not absolutely prohibited, but if you do that, the major
334 mode binding may be shadowed from time to time by minor modes.
336 * You should not bind `C-h' following any prefix character (including
337 `C-c'). If you don't bind `C-h', it is automatically available as
338 a help character for listing the subcommands of the prefix
341 * You should not bind a key sequence ending in <ESC> except following
342 another <ESC>. (That is, it is ok to bind a sequence ending in
345 The reason for this rule is that a non-prefix binding for <ESC> in
346 any context prevents recognition of escape sequences as function
347 keys in that context.
349 * Applications should not bind mouse events based on button 1 with
350 the shift key held down. These events include `S-mouse-1',
351 `M-S-mouse-1', `C-S-mouse-1', and so on. They are reserved for
354 * Modes should redefine `mouse-2' as a command to follow some sort of
355 reference in the text of a buffer, if users usually would not want
356 to alter the text in that buffer by hand. Modes such as Dired,
357 Info, Compilation, and Occur redefine it in this way.
359 * When a package provides a modification of ordinary Emacs behavior,
360 it is good to include a command to enable and disable the feature,
361 Provide a command named `WHATEVER-mode' which turns the feature on
362 or off, and make it autoload (*note Autoload::). Design the
363 package so that simply loading it has no visible effect--that
364 should not enable the feature. Users will request the feature by
365 invoking the command.
367 * It is a bad idea to define aliases for the Emacs primitives. Use
368 the standard names instead.
370 * Redefining an Emacs primitive is an even worse idea. It may do
371 the right thing for a particular program, but there is no telling
372 what other programs might break as a result.
374 * If a file does replace any of the functions or library programs of
375 standard XEmacs, prominent comments at the beginning of the file
376 should say which functions are replaced, and how the behavior of
377 the replacements differs from that of the originals.
379 * Please keep the names of your XEmacs Lisp source files to 13
380 characters or less. This way, if the files are compiled, the
381 compiled files' names will be 14 characters or less, which is
382 short enough to fit on all kinds of Unix systems.
384 * Don't use `next-line' or `previous-line' in programs; nearly
385 always, `forward-line' is more convenient as well as more
386 predictable and robust. *Note Text Lines::.
388 * Don't call functions that set the mark, unless setting the mark is
389 one of the intended features of your program. The mark is a
390 user-level feature, so it is incorrect to change the mark except
391 to supply a value for the user's benefit. *Note The Mark::.
393 In particular, don't use these functions:
395 * `beginning-of-buffer', `end-of-buffer'
397 * `replace-string', `replace-regexp'
399 If you just want to move point, or replace a certain string,
400 without any of the other features intended for interactive users,
401 you can replace these functions with one or two lines of simple
404 * Use lists rather than vectors, except when there is a particular
405 reason to use a vector. Lisp has more facilities for manipulating
406 lists than for vectors, and working with lists is usually more
409 Vectors are advantageous for tables that are substantial in size
410 and are accessed in random order (not searched front to back),
411 provided there is no need to insert or delete elements (only lists
414 * The recommended way to print a message in the echo area is with
415 the `message' function, not `princ'. *Note The Echo Area::.
417 * When you encounter an error condition, call the function `error'
418 (or `signal'). The function `error' does not return. *Note
421 Do not use `message', `throw', `sleep-for', or `beep' to report
424 * An error message should start with a capital letter but should not
427 * Try to avoid using recursive edits. Instead, do what the Rmail `e'
428 command does: use a new local keymap that contains one command
429 defined to switch back to the old local keymap. Or do what the
430 `edit-options' command does: switch to another buffer and let the
431 user switch back at will. *Note Recursive Editing::.
433 * In some other systems there is a convention of choosing variable
434 names that begin and end with `*'. We don't use that convention
435 in Emacs Lisp, so please don't use it in your programs. (Emacs
436 uses such names only for program-generated buffers.) The users
437 will find Emacs more coherent if all libraries use the same
440 * Indent each function with `C-M-q' (`indent-sexp') using the
441 default indentation parameters.
443 * Don't make a habit of putting close-parentheses on lines by
444 themselves; Lisp programmers find this disconcerting. Once in a
445 while, when there is a sequence of many consecutive
446 close-parentheses, it may make sense to split them in one or two
449 * Please put a copyright notice on the file if you give copies to
450 anyone. Use the same lines that appear at the top of the Lisp
451 files in XEmacs itself. If you have not signed papers to assign
452 the copyright to the Foundation, then place your name in the
453 copyright notice in place of the Foundation's name.
456 File: lispref.info, Node: Compilation Tips, Next: Documentation Tips, Prev: Style Tips, Up: Tips
458 Tips for Making Compiled Code Fast
459 ==================================
461 Here are ways of improving the execution speed of byte-compiled Lisp
464 * Use the `profile' library to profile your program. See the file
465 `profile.el' for instructions.
467 * Use iteration rather than recursion whenever possible. Function
468 calls are slow in XEmacs Lisp even when a compiled function is
469 calling another compiled function.
471 * Using the primitive list-searching functions `memq', `member',
472 `assq', or `assoc' is even faster than explicit iteration. It may
473 be worth rearranging a data structure so that one of these
474 primitive search functions can be used.
476 * Certain built-in functions are handled specially in byte-compiled
477 code, avoiding the need for an ordinary function call. It is a
478 good idea to use these functions rather than alternatives. To see
479 whether a function is handled specially by the compiler, examine
480 its `byte-compile' property. If the property is non-`nil', then
481 the function is handled specially.
483 For example, the following input will show you that `aref' is
484 compiled specially (*note Array Functions::) while `elt' is not
485 (*note Sequence Functions::):
487 (get 'aref 'byte-compile)
488 => byte-compile-two-args
490 (get 'elt 'byte-compile)
493 * If calling a small function accounts for a substantial part of
494 your program's running time, make the function inline. This
495 eliminates the function call overhead. Since making a function
496 inline reduces the flexibility of changing the program, don't do
497 it unless it gives a noticeable speedup in something slow enough
498 that users care about the speed. *Note Inline Functions::.
501 File: lispref.info, Node: Documentation Tips, Next: Comment Tips, Prev: Compilation Tips, Up: Tips
503 Tips for Documentation Strings
504 ==============================
506 Here are some tips for the writing of documentation strings.
508 * Every command, function, or variable intended for users to know
509 about should have a documentation string.
511 * An internal variable or subroutine of a Lisp program might as well
512 have a documentation string. In earlier Emacs versions, you could
513 save space by using a comment instead of a documentation string,
514 but that is no longer the case.
516 * The first line of the documentation string should consist of one
517 or two complete sentences that stand on their own as a summary.
518 `M-x apropos' displays just the first line, and if it doesn't
519 stand on its own, the result looks bad. In particular, start the
520 first line with a capital letter and end with a period.
522 The documentation string can have additional lines that expand on
523 the details of how to use the function or variable. The
524 additional lines should be made up of complete sentences also, but
525 they may be filled if that looks good.
527 * For consistency, phrase the verb in the first sentence of a
528 documentation string as an infinitive with "to" omitted. For
529 instance, use "Return the cons of A and B." in preference to
530 "Returns the cons of A and B." Usually it looks good to do
531 likewise for the rest of the first paragraph. Subsequent
532 paragraphs usually look better if they have proper subjects.
534 * Write documentation strings in the active voice, not the passive,
535 and in the present tense, not the future. For instance, use
536 "Return a list containing A and B." instead of "A list containing
537 A and B will be returned."
539 * Avoid using the word "cause" (or its equivalents) unnecessarily.
540 Instead of, "Cause Emacs to display text in boldface," write just
541 "Display text in boldface."
543 * Do not start or end a documentation string with whitespace.
545 * Format the documentation string so that it fits in an Emacs window
546 on an 80-column screen. It is a good idea for most lines to be no
547 wider than 60 characters. The first line can be wider if
548 necessary to fit the information that ought to be there.
550 However, rather than simply filling the entire documentation
551 string, you can make it much more readable by choosing line breaks
552 with care. Use blank lines between topics if the documentation
555 * *Do not* indent subsequent lines of a documentation string so that
556 the text is lined up in the source code with the text of the first
557 line. This looks nice in the source code, but looks bizarre when
558 users view the documentation. Remember that the indentation
559 before the starting double-quote is not part of the string!
561 * A variable's documentation string should start with `*' if the
562 variable is one that users would often want to set interactively.
563 If the value is a long list, or a function, or if the variable
564 would be set only in init files, then don't start the
565 documentation string with `*'. *Note Defining Variables::.
567 * The documentation string for a variable that is a yes-or-no flag
568 should start with words such as "Non-nil means...", to make it
569 clear that all non-`nil' values are equivalent and indicate
570 explicitly what `nil' and non-`nil' mean.
572 * When a function's documentation string mentions the value of an
573 argument of the function, use the argument name in capital letters
574 as if it were a name for that value. Thus, the documentation
575 string of the function `/' refers to its second argument as
576 `DIVISOR', because the actual argument name is `divisor'.
578 Also use all caps for meta-syntactic variables, such as when you
579 show the decomposition of a list or vector into subunits, some of
582 * When a documentation string refers to a Lisp symbol, write it as it
583 would be printed (which usually means in lower case), with
584 single-quotes around it. For example: `lambda'. There are two
585 exceptions: write t and nil without single-quotes. (In this
586 manual, we normally do use single-quotes for those symbols.)
588 * Don't write key sequences directly in documentation strings.
589 Instead, use the `\\[...]' construct to stand for them. For
590 example, instead of writing `C-f', write `\\[forward-char]'. When
591 Emacs displays the documentation string, it substitutes whatever
592 key is currently bound to `forward-char'. (This is normally `C-f',
593 but it may be some other character if the user has moved key
594 bindings.) *Note Keys in Documentation::.
596 * In documentation strings for a major mode, you will want to refer
597 to the key bindings of that mode's local map, rather than global
598 ones. Therefore, use the construct `\\<...>' once in the
599 documentation string to specify which key map to use. Do this
600 before the first use of `\\[...]'. The text inside the `\\<...>'
601 should be the name of the variable containing the local keymap for
604 It is not practical to use `\\[...]' very many times, because
605 display of the documentation string will become slow. So use this
606 to describe the most important commands in your major mode, and
607 then use `\\{...}' to display the rest of the mode's keymap.
610 File: lispref.info, Node: Comment Tips, Next: Library Headers, Prev: Documentation Tips, Up: Tips
612 Tips on Writing Comments
613 ========================
615 We recommend these conventions for where to put comments and how to
619 Comments that start with a single semicolon, `;', should all be
620 aligned to the same column on the right of the source code. Such
621 comments usually explain how the code on the same line does its
622 job. In Lisp mode and related modes, the `M-;'
623 (`indent-for-comment') command automatically inserts such a `;' in
624 the right place, or aligns such a comment if it is already present.
626 This and following examples are taken from the Emacs sources.
628 (setq base-version-list ; there was a base
629 (assoc (substring fn 0 start-vn) ; version to which
630 file-version-assoc-list)) ; this looks like
634 Comments that start with two semicolons, `;;', should be aligned to
635 the same level of indentation as the code. Such comments usually
636 describe the purpose of the following lines or the state of the
637 program at that point. For example:
639 (prog1 (setq auto-fill-function
645 Every function that has no documentation string (because it is use
646 only internally within the package it belongs to), should have
647 instead a two-semicolon comment right before the function,
648 explaining what the function does and how to call it properly.
649 Explain precisely what each argument means and how the function
650 interprets its possible values.
653 Comments that start with three semicolons, `;;;', should start at
654 the left margin. Such comments are used outside function
655 definitions to make general statements explaining the design
656 principles of the program. For example:
658 ;;; This Lisp code is run in XEmacs
659 ;;; when it is to operate as a server
660 ;;; for other processes.
662 Another use for triple-semicolon comments is for commenting out
663 lines within a function. We use triple-semicolons for this
664 precisely so that they remain at the left margin.
667 ;;; This is no longer necessary.
668 ;;; (force-mode-line-update)
669 (message "Finished with %s" a))
672 Comments that start with four semicolons, `;;;;', should be aligned
673 to the left margin and are used for headings of major sections of a
674 program. For example:
678 The indentation commands of the Lisp modes in XEmacs, such as `M-;'
679 (`indent-for-comment') and <TAB> (`lisp-indent-line') automatically
680 indent comments according to these conventions, depending on the number
681 of semicolons. *Note Manipulating Comments: (emacs)Comments.
684 File: lispref.info, Node: Library Headers, Prev: Comment Tips, Up: Tips
686 Conventional Headers for XEmacs Libraries
687 =========================================
689 XEmacs has conventions for using special comments in Lisp libraries
690 to divide them into sections and give information such as who wrote
691 them. This section explains these conventions. First, an example:
693 ;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers
695 ;; Copyright (C) 1992 Free Software Foundation, Inc.
697 ;; Author: Eric S. Raymond <esr@snark.thyrsus.com>
698 ;; Maintainer: Eric S. Raymond <esr@snark.thyrsus.com>
699 ;; Created: 14 Jul 1992
703 ;; This file is part of XEmacs.
704 COPYING PERMISSIONS...
706 The very first line should have this format:
708 ;;; FILENAME --- DESCRIPTION
710 The description should be complete in one line.
712 After the copyright notice come several "header comment" lines, each
713 beginning with `;; HEADER-NAME:'. Here is a table of the conventional
714 possibilities for HEADER-NAME:
717 This line states the name and net address of at least the principal
718 author of the library.
720 If there are multiple authors, you can list them on continuation
721 lines led by `;;' and a tab character, like this:
723 ;; Author: Ashwin Ram <Ram-Ashwin@cs.yale.edu>
724 ;; Dave Sill <de5@ornl.gov>
725 ;; Dave Brennan <brennan@hal.com>
726 ;; Eric Raymond <esr@snark.thyrsus.com>
729 This line should contain a single name/address as in the Author
730 line, or an address only, or the string `FSF'. If there is no
731 maintainer line, the person(s) in the Author field are presumed to
732 be the maintainers. The example above is mildly bogus because the
733 maintainer line is redundant.
735 The idea behind the `Author' and `Maintainer' lines is to make
736 possible a Lisp function to "send mail to the maintainer" without
737 having to mine the name out by hand.
739 Be sure to surround the network address with `<...>' if you
740 include the person's full name as well as the network address.
743 This optional line gives the original creation date of the file.
744 For historical interest only.
747 If you wish to record version numbers for the individual Lisp
748 program, put them in this line.
751 In this header line, place the name of the person who adapted the
752 library for installation (to make it fit the style conventions, for
756 This line lists keywords for the `finder-by-keyword' help command.
757 This field is important; it's how people will find your package
758 when they're looking for things by topic area. To separate the
759 keywords, you can use spaces, commas, or both.
761 Just about every Lisp library ought to have the `Author' and
762 `Keywords' header comment lines. Use the others if they are
763 appropriate. You can also put in header lines with other header
764 names--they have no standard meanings, so they can't do any harm.
766 We use additional stylized comments to subdivide the contents of the
767 library file. Here is a table of them:
770 This begins introductory comments that explain how the library
771 works. It should come right after the copying permissions.
774 This begins change log information stored in the library file (if
775 you store the change history there). For most of the Lisp files
776 distributed with XEmacs, the change history is kept in the file
777 `ChangeLog' and not in the source file at all; these files do not
778 have a `;;; Change log:' line.
781 This begins the actual code of the program.
783 `;;; FILENAME ends here'
784 This is the "footer line"; it appears at the very end of the file.
785 Its purpose is to enable people to detect truncated versions of
786 the file from the lack of a footer line.
789 File: lispref.info, Node: Building XEmacs and Object Allocation, Next: Standard Errors, Prev: Tips, Up: Top
791 Building XEmacs; Allocation of Objects
792 **************************************
794 This chapter describes how the runnable XEmacs executable is dumped
795 with the preloaded Lisp libraries in it and how storage is allocated.
797 There is an entire separate document, the `XEmacs Internals Manual',
798 devoted to the internals of XEmacs from the perspective of the C
799 programmer. It contains much more detailed information about the build
800 process, the allocation and garbage-collection process, and other
801 aspects related to the internals of XEmacs.
805 * Building XEmacs:: How to preload Lisp libraries into XEmacs.
806 * Pure Storage:: A kludge to make preloaded Lisp functions sharable.
807 * Garbage Collection:: Reclaiming space for Lisp objects no longer used.
810 File: lispref.info, Node: Building XEmacs, Next: Pure Storage, Up: Building XEmacs and Object Allocation
815 This section explains the steps involved in building the XEmacs
816 executable. You don't have to know this material to build and install
817 XEmacs, since the makefiles do all these things automatically. This
818 information is pertinent to XEmacs maintenance.
820 The `XEmacs Internals Manual' contains more information about this.
822 Compilation of the C source files in the `src' directory produces an
823 executable file called `temacs', also called a "bare impure XEmacs".
824 It contains the XEmacs Lisp interpreter and I/O routines, but not the
827 Before XEmacs is actually usable, a number of Lisp files need to be
828 loaded. These define all the editing commands, plus most of the startup
829 code and many very basic Lisp primitives. This is accomplished by
830 loading the file `loadup.el', which in turn loads all of the other
831 standardly-loaded Lisp files.
833 It takes a substantial time to load the standard Lisp files.
834 Luckily, you don't have to do this each time you run XEmacs; `temacs'
835 can dump out an executable program called `xemacs' that has these files
836 preloaded. `xemacs' starts more quickly because it does not need to
837 load the files. This is the XEmacs executable that is normally
840 To create `xemacs', use the command `temacs -batch -l loadup dump'.
841 The purpose of `-batch' here is to tell `temacs' to run in
842 non-interactive, command-line mode. (`temacs' can _only_ run in this
843 fashion. Part of the code required to initialize frames and faces is
844 in Lisp, and must be loaded before XEmacs is able to create any frames.)
845 The argument `dump' tells `loadup.el' to dump a new executable named
848 The dumping process is highly system-specific, and some operating
849 systems don't support dumping. On those systems, you must start XEmacs
850 with the `temacs -batch -l loadup run-temacs' command each time you use
851 it. This takes a substantial time, but since you need to start Emacs
852 once a day at most--or once a week if you never log out--the extra time
853 is not too severe a problem. (In older versions of Emacs, you started
854 Emacs from `temacs' using `temacs -l loadup'.)
856 You are free to start XEmacs directly from `temacs' if you want,
857 even if there is already a dumped `xemacs'. Normally you wouldn't want
858 to do that; but the Makefiles do this when you rebuild XEmacs using
859 `make all-elc', which builds XEmacs and simultaneously compiles any
860 out-of-date Lisp files. (You need `xemacs' in order to compile Lisp
861 files. However, you also need the compiled Lisp files in order to dump
862 out `xemacs'. If both of these are missing or corrupted, you are out
863 of luck unless you're able to bootstrap `xemacs' from `temacs'. Note
864 that `make all-elc' actually loads the alternative loadup file
865 `loadup-el.el', which works like `loadup.el' but disables the
866 pure-copying process and forces XEmacs to ignore any compiled Lisp
867 files even if they exist.)
869 You can specify additional files to preload by writing a library
870 named `site-load.el' that loads them. You may need to increase the
871 value of `PURESIZE', in `src/puresize.h', to make room for the
872 additional files. You should _not_ modify this file directly, however;
873 instead, use the `--puresize' configuration option. (If you run out of
874 pure space while dumping `xemacs', you will be told how much pure space
875 you actually will need.) However, the advantage of preloading
876 additional files decreases as machines get faster. On modern machines,
877 it is often not advisable, especially if the Lisp code is on a file
878 system local to the machine running XEmacs.
880 You can specify other Lisp expressions to execute just before dumping
881 by putting them in a library named `site-init.el'. However, if they
882 might alter the behavior that users expect from an ordinary unmodified
883 XEmacs, it is better to put them in `default.el', so that users can
884 override them if they wish. *Note Start-up Summary::.
886 Before `loadup.el' dumps the new executable, it finds the
887 documentation strings for primitive and preloaded functions (and
888 variables) in the file where they are stored, by calling
889 `Snarf-documentation' (*note Accessing Documentation::). These strings
890 were moved out of the `xemacs' executable to make it smaller. *Note
891 Documentation Basics::.
893 - Function: dump-emacs to-file from-file
894 This function dumps the current state of XEmacs into an executable
895 file TO-FILE. It takes symbols from FROM-FILE (this is normally
896 the executable file `temacs').
898 If you use this function in an XEmacs that was already dumped, you
899 must set `command-line-processed' to `nil' first for good results.
900 *Note Command Line Arguments::.
902 - Function: run-emacs-from-temacs &rest args
903 This is the function that implements the `run-temacs' command-line
904 argument. It is called from `loadup.el' as appropriate. You
905 should most emphatically _not_ call this yourself; it will
906 reinitialize your XEmacs process and you'll be sorry.
908 - Command: emacs-version
909 This function returns a string describing the version of XEmacs
910 that is running. It is useful to include this string in bug
914 => "XEmacs 20.1 [Lucid] (i586-unknown-linux2.0.29)
915 of Mon Apr 7 1997 on altair.xemacs.org"
917 Called interactively, the function prints the same information in
920 - Variable: emacs-build-time
921 The value of this variable is the time at which XEmacs was built
924 emacs-build-time "Mon Apr 7 20:28:52 1997"
927 - Variable: emacs-version
928 The value of this variable is the version of Emacs being run. It
929 is a string, e.g. `"20.1 XEmacs Lucid"'.
931 The following two variables did not exist before FSF GNU Emacs
932 version 19.23 and XEmacs version 19.10, which reduces their usefulness
933 at present, but we hope they will be convenient in the future.
935 - Variable: emacs-major-version
936 The major version number of Emacs, as an integer. For XEmacs
937 version 20.1, the value is 20.
939 - Variable: emacs-minor-version
940 The minor version number of Emacs, as an integer. For XEmacs
941 version 20.1, the value is 1.
944 File: lispref.info, Node: Pure Storage, Next: Garbage Collection, Prev: Building XEmacs, Up: Building XEmacs and Object Allocation
949 XEmacs Lisp uses two kinds of storage for user-created Lisp objects:
950 "normal storage" and "pure storage". Normal storage is where all the
951 new data created during an XEmacs session is kept; see the following
952 section for information on normal storage. Pure storage is used for
953 certain data in the preloaded standard Lisp files--data that should
954 never change during actual use of XEmacs.
956 Pure storage is allocated only while `temacs' is loading the
957 standard preloaded Lisp libraries. In the file `xemacs', it is marked
958 as read-only (on operating systems that permit this), so that the
959 memory space can be shared by all the XEmacs jobs running on the machine
960 at once. Pure storage is not expandable; a fixed amount is allocated
961 when XEmacs is compiled, and if that is not sufficient for the preloaded
962 libraries, `temacs' aborts with an error message. If that happens, you
963 must increase the compilation parameter `PURESIZE' using the
964 `--puresize' option to `configure'. This normally won't happen unless
965 you try to preload additional libraries or add features to the standard
968 - Function: purecopy object
969 This function makes a copy of OBJECT in pure storage and returns
970 it. It copies strings by simply making a new string with the same
971 characters in pure storage. It recursively copies the contents of
972 vectors and cons cells. It does not make copies of other objects
973 such as symbols, but just returns them unchanged. It signals an
974 error if asked to copy markers.
976 This function is a no-op except while XEmacs is being built and
977 dumped; it is usually called only in the file
978 `xemacs/lisp/prim/loaddefs.el', but a few packages call it just in
979 case you decide to preload them.
981 - Variable: pure-bytes-used
982 The value of this variable is the number of bytes of pure storage
983 allocated so far. Typically, in a dumped XEmacs, this number is
984 very close to the total amount of pure storage available--if it
985 were not, we would preallocate less.
987 - Variable: purify-flag
988 This variable determines whether `defun' should make a copy of the
989 function definition in pure storage. If it is non-`nil', then the
990 function definition is copied into pure storage.
992 This flag is `t' while loading all of the basic functions for
993 building XEmacs initially (allowing those functions to be sharable
994 and non-collectible). Dumping XEmacs as an executable always
995 writes `nil' in this variable, regardless of the value it actually
996 has before and after dumping.
998 You should not change this flag in a running XEmacs.
projects / chise / xemacs-chise.git / blob