This is Info file ../../info/lispref.info, produced by Makeinfo version 1.68 from the input file lispref.texi. Edition History: GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp Reference Manual (for 19.15 and 20.1, 20.2) v3.2, April, May 1997 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc. Copyright (C) 1995, 1996 Ben Wing. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the Free Software Foundation instead of in the original English.  File: lispref.info, Node: Composite Characters, Next: ISO 2022, Prev: MULE Characters, Up: MULE Composite Characters ==================== Composite characters are not yet completely implemented. - Function: make-composite-char STRING This function converts a string into a single composite character. The character is the result of overstriking all the characters in the string. - Function: composite-char-string CH This function returns a string of the characters comprising a composite character. - Function: compose-region START END &optional BUFFER This function composes the characters in the region from START to END in BUFFER into one composite character. The composite character replaces the composed characters. BUFFER defaults to the current buffer if omitted. - Function: decompose-region START END &optional BUFFER This function decomposes any composite characters in the region from START to END in BUFFER. This converts each composite character into one or more characters, the individual characters out of which the composite character was formed. Non-composite characters are left as-is. BUFFER defaults to the current buffer if omitted.  File: lispref.info, Node: ISO 2022, Next: Coding Systems, Prev: Composite Characters, Up: MULE ISO 2022 ======== This section briefly describes the ISO 2022 encoding standard. For more thorough understanding, please refer to the original document of ISO 2022. Character sets ("charsets") are classified into the following four categories, according to the number of characters of charset: 94-charset, 96-charset, 94x94-charset, and 96x96-charset. 94-charset ASCII(B), left(J) and right(I) half of JISX0201, ... 96-charset Latin-1(A), Latin-2(B), Latin-3(C), ... 94x94-charset GB2312(A), JISX0208(B), KSC5601(C), ... 96x96-charset none for the moment The character in parentheses after the name of each charset is the "final character" F, which can be regarded as the identifier of the charset. ECMA allocates F to each charset. F is in the range of 0x30..0x7F, but 0x30..0x3F are only for private use. Note: "ECMA" = European Computer Manufacturers Association There are four "registers of charsets", called G0 thru G3. You can designate (or assign) any charset to one of these registers. The code space contained within one octet (of size 256) is divided into 4 areas: C0, GL, C1, and GR. GL and GR are the areas into which a register of charset can be invoked into. C0: 0x00 - 0x1F GL: 0x20 - 0x7F C1: 0x80 - 0x9F GR: 0xA0 - 0xFF Usually, in the initial state, G0 is invoked into GL, and G1 is invoked into GR. ISO 2022 distinguishes 7-bit environments and 8-bit environments. In 7-bit environments, only C0 and GL are used. Charset designation is done by escape sequences of the form: ESC [I] I F where I is an intermediate character in the range 0x20 - 0x2F, and F is the final character identifying this charset. The meaning of intermediate characters are: $ [0x24]: indicate charset of dimension 2 (94x94 or 96x96). ( [0x28]: designate to G0 a 94-charset whose final byte is F. ) [0x29]: designate to G1 a 94-charset whose final byte is F. * [0x2A]: designate to G2 a 94-charset whose final byte is F. + [0x2B]: designate to G3 a 94-charset whose final byte is F. - [0x2D]: designate to G1 a 96-charset whose final byte is F. . [0x2E]: designate to G2 a 96-charset whose final byte is F. / [0x2F]: designate to G3 a 96-charset whose final byte is F. The following rule is not allowed in ISO 2022 but can be used in Mule. , [0x2C]: designate to G0 a 96-charset whose final byte is F. Here are examples of designations: ESC ( B : designate to G0 ASCII ESC - A : designate to G1 Latin-1 ESC $ ( A or ESC $ A : designate to G0 GB2312 ESC $ ( B or ESC $ B : designate to G0 JISX0208 ESC $ ) C : designate to G1 KSC5601 To use a charset designated to G2 or G3, and to use a charset designated to G1 in a 7-bit environment, you must explicitly invoke G1, G2, or G3 into GL. There are two types of invocation, Locking Shift (forever) and Single Shift (one character only). Locking Shift is done as follows: LS0 or SI (0x0F): invoke G0 into GL LS1 or SO (0x0E): invoke G1 into GL LS2: invoke G2 into GL LS3: invoke G3 into GL LS1R: invoke G1 into GR LS2R: invoke G2 into GR LS3R: invoke G3 into GR Single Shift is done as follows: SS2 or ESC N: invoke G2 into GL SS3 or ESC O: invoke G3 into GL (#### Ben says: I think the above is slightly incorrect. It appears that SS2 invokes G2 into GR and SS3 invokes G3 into GR, whereas ESC N and ESC O behave as indicated. The above definitions will not parse EUC-encoded text correctly, and it looks like the code in mule-coding.c has similar problems.) You may realize that there are a lot of ISO-2022-compliant ways of encoding multilingual text. Now, in the world, there exist many coding systems such as X11's Compound Text, Japanese JUNET code, and so-called EUC (Extended UNIX Code); all of these are variants of ISO 2022. In Mule, we characterize ISO 2022 by the following attributes: 1. Initial designation to G0 thru G3. 2. Allow designation of short form for Japanese and Chinese. 3. Should we designate ASCII to G0 before control characters? 4. Should we designate ASCII to G0 at the end of line? 5. 7-bit environment or 8-bit environment. 6. Use Locking Shift or not. 7. Use ASCII or JIS0201-1976-Roman. 8. Use JISX0208-1983 or JISX0208-1976. (The last two are only for Japanese.) By specifying these attributes, you can create any variant of ISO 2022. Here are several examples: junet -- Coding system used in JUNET. 1. G0 <- ASCII, G1..3 <- never used 2. Yes. 3. Yes. 4. Yes. 5. 7-bit environment 6. No. 7. Use ASCII 8. Use JISX0208-1983 ctext -- Compound Text 1. G0 <- ASCII, G1 <- Latin-1, G2,3 <- never used 2. No. 3. No. 4. Yes. 5. 8-bit environment 6. No. 7. Use ASCII 8. Use JISX0208-1983 euc-china -- Chinese EUC. Although many people call this as "GB encoding", the name may cause misunderstanding. 1. G0 <- ASCII, G1 <- GB2312, G2,3 <- never used 2. No. 3. Yes. 4. Yes. 5. 8-bit environment 6. No. 7. Use ASCII 8. Use JISX0208-1983 korean-mail -- Coding system used in Korean network. 1. G0 <- ASCII, G1 <- KSC5601, G2,3 <- never used 2. No. 3. Yes. 4. Yes. 5. 7-bit environment 6. Yes. 7. No. 8. No. Mule creates all these coding systems by default.  File: lispref.info, Node: Coding Systems, Next: CCL, Prev: ISO 2022, Up: MULE Coding Systems ============== A coding system is an object that defines how text containing multiple character sets is encoded into a stream of (typically 8-bit) bytes. The coding system is used to decode the stream into a series of characters (which may be from multiple charsets) when the text is read from a file or process, and is used to encode the text back into the same format when it is written out to a file or process. For example, many ISO-2022-compliant coding systems (such as Compound Text, which is used for inter-client data under the X Window System) use escape sequences to switch between different charsets - Japanese Kanji, for example, is invoked with `ESC $ ( B'; ASCII is invoked with `ESC ( B'; and Cyrillic is invoked with `ESC - L'. See `make-coding-system' for more information. Coding systems are normally identified using a symbol, and the symbol is accepted in place of the actual coding system object whenever a coding system is called for. (This is similar to how faces and charsets work.) - Function: coding-system-p OBJECT This function returns non-`nil' if OBJECT is a coding system. * Menu: * Coding System Types:: Classifying coding systems. * EOL Conversion:: Dealing with different ways of denoting the end of a line. * Coding System Properties:: Properties of a coding system. * Basic Coding System Functions:: Working with coding systems. * Coding System Property Functions:: Retrieving a coding system's properties. * Encoding and Decoding Text:: Encoding and decoding text. * Detection of Textual Encoding:: Determining how text is encoded. * Big5 and Shift-JIS Functions:: Special functions for these non-standard encodings.  File: lispref.info, Node: Coding System Types, Next: EOL Conversion, Up: Coding Systems Coding System Types ------------------- `nil' `autodetect' Automatic conversion. XEmacs attempts to detect the coding system used in the file. `no-conversion' No conversion. Use this for binary files and such. On output, graphic characters that are not in ASCII or Latin-1 will be replaced by a `?'. (For a no-conversion-encoded buffer, these characters will only be present if you explicitly insert them.) `shift-jis' Shift-JIS (a Japanese encoding commonly used in PC operating systems). `iso2022' Any ISO-2022-compliant encoding. Among other things, this includes JIS (the Japanese encoding commonly used for e-mail), national variants of EUC (the standard Unix encoding for Japanese and other languages), and Compound Text (an encoding used in X11). You can specify more specific information about the conversion with the FLAGS argument. `big5' Big5 (the encoding commonly used for Taiwanese). `ccl' The conversion is performed using a user-written pseudo-code program. CCL (Code Conversion Language) is the name of this pseudo-code. `internal' Write out or read in the raw contents of the memory representing the buffer's text. This is primarily useful for debugging purposes, and is only enabled when XEmacs has been compiled with `DEBUG_XEMACS' set (the `--debug' configure option). *Warning*: Reading in a file using `internal' conversion can result in an internal inconsistency in the memory representing a buffer's text, which will produce unpredictable results and may cause XEmacs to crash. Under normal circumstances you should never use `internal' conversion.  File: lispref.info, Node: EOL Conversion, Next: Coding System Properties, Prev: Coding System Types, Up: Coding Systems EOL Conversion -------------- `nil' Automatically detect the end-of-line type (LF, CRLF, or CR). Also generate subsidiary coding systems named `NAME-unix', `NAME-dos', and `NAME-mac', that are identical to this coding system but have an EOL-TYPE value of `lf', `crlf', and `cr', respectively. `lf' The end of a line is marked externally using ASCII LF. Since this is also the way that XEmacs represents an end-of-line internally, specifying this option results in no end-of-line conversion. This is the standard format for Unix text files. `crlf' The end of a line is marked externally using ASCII CRLF. This is the standard format for MS-DOS text files. `cr' The end of a line is marked externally using ASCII CR. This is the standard format for Macintosh text files. `t' Automatically detect the end-of-line type but do not generate subsidiary coding systems. (This value is converted to `nil' when stored internally, and `coding-system-property' will return `nil'.)  File: lispref.info, Node: Coding System Properties, Next: Basic Coding System Functions, Prev: EOL Conversion, Up: Coding Systems Coding System Properties ------------------------ `mnemonic' String to be displayed in the modeline when this coding system is active. `eol-type' End-of-line conversion to be used. It should be one of the types listed in *Note EOL Conversion::. `post-read-conversion' Function called after a file has been read in, to perform the decoding. Called with two arguments, BEG and END, denoting a region of the current buffer to be decoded. `pre-write-conversion' Function called before a file is written out, to perform the encoding. Called with two arguments, BEG and END, denoting a region of the current buffer to be encoded. The following additional properties are recognized if TYPE is `iso2022': `charset-g0' `charset-g1' `charset-g2' `charset-g3' The character set initially designated to the G0 - G3 registers. The value should be one of * A charset object (designate that character set) * `nil' (do not ever use this register) * `t' (no character set is initially designated to the register, but may be later on; this automatically sets the corresponding `force-g*-on-output' property) `force-g0-on-output' `force-g1-on-output' `force-g2-on-output' `force-g3-on-output' If non-`nil', send an explicit designation sequence on output before using the specified register. `short' If non-`nil', use the short forms `ESC $ @', `ESC $ A', and `ESC $ B' on output in place of the full designation sequences `ESC $ ( @', `ESC $ ( A', and `ESC $ ( B'. `no-ascii-eol' If non-`nil', don't designate ASCII to G0 at each end of line on output. Setting this to non-`nil' also suppresses other state-resetting that normally happens at the end of a line. `no-ascii-cntl' If non-`nil', don't designate ASCII to G0 before control chars on output. `seven' If non-`nil', use 7-bit environment on output. Otherwise, use 8-bit environment. `lock-shift' If non-`nil', use locking-shift (SO/SI) instead of single-shift or designation by escape sequence. `no-iso6429' If non-`nil', don't use ISO6429's direction specification. `escape-quoted' If non-nil, literal control characters that are the same as the beginning of a recognized ISO 2022 or ISO 6429 escape sequence (in particular, ESC (0x1B), SO (0x0E), SI (0x0F), SS2 (0x8E), SS3 (0x8F), and CSI (0x9B)) are "quoted" with an escape character so that they can be properly distinguished from an escape sequence. (Note that doing this results in a non-portable encoding.) This encoding flag is used for byte-compiled files. Note that ESC is a good choice for a quoting character because there are no escape sequences whose second byte is a character from the Control-0 or Control-1 character sets; this is explicitly disallowed by the ISO 2022 standard. `input-charset-conversion' A list of conversion specifications, specifying conversion of characters in one charset to another when decoding is performed. Each specification is a list of two elements: the source charset, and the destination charset. `output-charset-conversion' A list of conversion specifications, specifying conversion of characters in one charset to another when encoding is performed. The form of each specification is the same as for `input-charset-conversion'. The following additional properties are recognized (and required) if TYPE is `ccl': `decode' CCL program used for decoding (converting to internal format). `encode' CCL program used for encoding (converting to external format).  File: lispref.info, Node: Basic Coding System Functions, Next: Coding System Property Functions, Prev: Coding System Properties, Up: Coding Systems Basic Coding System Functions ----------------------------- - Function: find-coding-system CODING-SYSTEM-OR-NAME This function retrieves the coding system of the given name. If CODING-SYSTEM-OR-NAME is a coding-system object, it is simply returned. Otherwise, CODING-SYSTEM-OR-NAME should be a symbol. If there is no such coding system, `nil' is returned. Otherwise the associated coding system object is returned. - Function: get-coding-system NAME This function retrieves the coding system of the given name. Same as `find-coding-system' except an error is signalled if there is no such coding system instead of returning `nil'. - Function: coding-system-list This function returns a list of the names of all defined coding systems. - Function: coding-system-name CODING-SYSTEM This function returns the name of the given coding system. - Function: make-coding-system NAME TYPE &optional DOC-STRING PROPS This function registers symbol NAME as a coding system. TYPE describes the conversion method used and should be one of the types listed in *Note Coding System Types::. DOC-STRING is a string describing the coding system. PROPS is a property list, describing the specific nature of the character set. Recognized properties are as in *Note Coding System Properties::. - Function: copy-coding-system OLD-CODING-SYSTEM NEW-NAME This function copies OLD-CODING-SYSTEM to NEW-NAME. If NEW-NAME does not name an existing coding system, a new one will be created. - Function: subsidiary-coding-system CODING-SYSTEM EOL-TYPE This function returns the subsidiary coding system of CODING-SYSTEM with eol type EOL-TYPE.  File: lispref.info, Node: Coding System Property Functions, Next: Encoding and Decoding Text, Prev: Basic Coding System Functions, Up: Coding Systems Coding System Property Functions -------------------------------- - Function: coding-system-doc-string CODING-SYSTEM This function returns the doc string for CODING-SYSTEM. - Function: coding-system-type CODING-SYSTEM This function returns the type of CODING-SYSTEM. - Function: coding-system-property CODING-SYSTEM PROP This function returns the PROP property of CODING-SYSTEM.  File: lispref.info, Node: Encoding and Decoding Text, Next: Detection of Textual Encoding, Prev: Coding System Property Functions, Up: Coding Systems Encoding and Decoding Text -------------------------- - Function: decode-coding-region START END CODING-SYSTEM &optional BUFFER This function decodes the text between START and END which is encoded in CODING-SYSTEM. This is useful if you've read in encoded text from a file without decoding it (e.g. you read in a JIS-formatted file but used the `binary' or `no-conversion' coding system, so that it shows up as `^[$B!', `:' 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: 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: 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.  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: (emacs)Comments.