   This version is newer than the second printed edition of the GNU
Emacs Lisp Reference Manual.  It corresponds to Emacs Version 19.19.

   Published by the Free Software Foundation 675 Massachusetts Avenue
Cambridge, MA 02139 USA

   Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.

   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.

Example of Sending Messages
---------------------------

   Here's a simple example that sends a query to another application
and then displays its reply.  Both the query and the reply are stored
in the first argument of the message.

     (defun tooltalk-random-query-handler (msg)
       (let ((state (get-tooltalk-message-attribute msg 'state)))
         (cond
           ((eq state 'TT_HANDLED)
            (message (get-tooltalk-message-attribute msg arg_val 0)))
           ((memq state '(TT_FAILED TT_REJECTED))
            (message "Random query turns up nothing")))))

     (defvar random-query-message
       '(   class TT_REQUEST
            scope TT_SESSION
          address TT_PROCEDURE
               op "random-query"
             args '((TT_INOUT "?" "string"))
         callback tooltalk-random-query-handler))

     (let ((m (make-tooltalk-message random-query-message)))
       (send-tooltalk-message m))

Elisp Interface for Sending Messages
------------------------------------

 - Function: make-tooltalk-message ATTRIBUTES
     Create a ToolTalk message and initialize its attributes.  The
     value of ATTRIBUTES must be a list of alternating keyword/values,
     where keywords are symbols that name valid message attributes.
     For example:

            (make-tooltalk-message
              '(class TT_NOTICE
                scope TT_SESSION
                address TT_PROCEDURE
                op "do-something"
                args ("arg1" 12345 (TT_INOUT "arg3" "string"))))

     Values must always be strings, integers, or symbols that represent
     ToolTalk constants.  Attribute names are the same as those
     supported by `set-tooltalk-message-attribute', plus `args'.

     The value of `args' should be a list of message arguments where
     each message argument has the following form:

             `(mode [value [type]])' or just `value'

     Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is
     a string.  If TYPE isn't specified then `int' is used if VALUE is
     a number; otherwise `string' is used.  If TYPE is `string' then
     VALUE is converted to a string (if it isn't a string already) with
     `prin1-to-string'.  If only a value is specified then MODE
     defaults to `TT_IN'.  If MODE is `TT_OUT' then VALUE and TYPE
     don't need to be specified.  You can find out more about the
     semantics and uses of ToolTalk message arguments in chapter 4 of
     the `ToolTalk Programmer's Guide'.

 - Function: send-tooltalk-message MSG
     Send the message on its way.  Once the message has been sent it's
     almost always a good idea to get rid of it with
     `destroy-tooltalk-message'.

 - Function: return-tooltalk-message MSG &optional MODE
     Send a reply to this message.  The second argument can be `reply',
     `reject' or `fail'; the default is `reply'.  Before sending a
     reply, all message arguments whose mode is `TT_INOUT' or `TT_OUT'
     should have been filled in - see `set-tooltalk-message-attribute'.

 - Function: get-tooltalk-message-attribute MSG ATTRIBUTE &optional ARGN
     Returns the indicated ToolTalk message attribute.  Attributes are
     identified by symbols with the same name (underscores and all) as
     the suffix of the ToolTalk `tt_message_<attribute>' function that
     extracts the value.  String attribute values are copied and
     enumerated type values (except disposition) are converted to
     symbols; e.g. `TT_HANDLER' is `'TT_HANDLER', `uid' and `gid' are
     represented by fixnums (small integers), `opnum' is converted to a
     string, and `disposition' is converted to a fixnum.  We convert
     `opnum' (a C int) to a string (e.g. `123' => `"123"') because
     there's no guarantee that opnums will fit within the range of
     Emacs Lisp integers.

     [TBD] Use the `plist' attribute instead of C API `user' attribute
     for user-defined message data.  To retrieve the value of a message
     property, specify the indicator for ARGN.  For example, to get the
     value of a property called `rflag', use

             (get-tooltalk-message-attribute msg 'plist 'rflag)

     To get the value of a message argument use one of the `arg_val'
     (strings), `arg_ival' (integers), or `arg_bval' (strings with
     embedded nulls), attributes.  For example, to get the integer
     value of the third argument:

             (get-tooltalk-message-attribute msg 'arg_ival 2)

     As you can see, argument numbers are zero-based.  The type of each
     arguments can be retrieved with the `arg_type' attribute; however
     ToolTalk doesn't define any semantics for the string value of
     `arg_type'.  Conventionally `string' is used for strings and `int'
     for 32 bit integers.  Note that Emacs Lisp stores the lengths of
     strings explicitly (unlike C) so treating the value returned by
     `arg_bval' like a string is fine.

 - Function: set-tooltalk-message-attribute VALUE MSG ATTRIBUTE
          &optional ARGN
     Initialize one ToolTalk message attribute.

     Attribute names and values are the same as for
     `get-tooltalk-message-attribute'.  A property list is provided for
     user data (instead of the `user' message attribute); see
     `get-tooltalk-message-attribute'.

     Callbacks are handled slightly differently than in the C ToolTalk
     API.  The value of CALLBACK should be the name of a function of one
     argument.  It will be called each time the state of the message
     changes.  This is usually used to notice when the message's state
     has changed to `TT_HANDLED' (or `TT_FAILED'), so that reply
     argument values can be used.

     If one of the argument attributes is specified as `arg_val',
     `arg_ival', or `arg_bval', then ARGN must be the number of an
     already created argument.  Arguments can be added to a message
     with `add-tooltalk-message-arg'.

 - Function: add-tooltalk-message-arg MSG MODE TYPE &optional VALUE
     Append one new argument to the message.  MODE must be one of
     `TT_IN', `TT_INOUT', or `TT_OUT', TYPE must be a string, and VALUE
     can be a string or an integer.  ToolTalk doesn't define any
     semantics for TYPE, so only the participants in the protocol
     you're using need to agree what types mean (if anything).
     Conventionally `string' is used for strings and `int' for 32 bit
     integers.  Arguments can initialized by providing a value or with
     `set-tooltalk-message-attribute'; the latter is neccessary if you
     want to initialize the argument with a string that can contain
     embedded nulls (use `arg_bval').

 - Function: create-tooltalk-message
     Create a new ToolTalk message.  The message's session attribute is
     initialized to the default session.  Other attributes can be
     intialized with `set-tooltalk-message-attribute'.
     `make-tooltalk-message' is the preferred way to create and
     initialize a message.

 - Function: destroy-tooltalk-message MSG
     Apply `tt_message_destroy' to the message.  It's not necessary to
     destroy messages after they've been processed by a message or
     pattern callback, the Lisp/ToolTalk callback machinery does this
     for you.

Receiving Messages
==================

Example of Receiving Messages
-----------------------------

   Here's a simple example of a handler for a message that tells emacs
to display a string in the mini-buffer area.  The message operation is
called `emacs-display-string'.  Its first (0th) argument is the string
to display.

     (defun tooltalk-display-string-handler (msg)
       (message (get-tooltalk-message-attribute msg 'arg_val 0)))

     (defvar display-string-pattern
       '(category TT_HANDLE
            scope TT_SESSION
               op "emacs-display-string"
         callback tooltalk-display-string-handler))

     (let ((p (make-tooltalk-pattern display-string-pattern)))
       (register-tooltalk-pattern p))

Elisp Interface for Receiving Messages
--------------------------------------

 - Function: make-tooltalk-pattern ATTRIBUTES
     Create a ToolTalk pattern and initialize its attributes.  The
     value of attributes must be a list of alternating keyword/values,
     where keywords are symbols that name valid pattern attributes or
     lists of valid attributes.  For example:

            (make-tooltalk-pattern
              '(category TT_OBSERVE
                   scope TT_SESSION
                      op ("operation1" "operation2")
                    args ("arg1" 12345 (TT_INOUT "arg3" "string"))))

     Attribute names are the same as those supported by
     `add-tooltalk-pattern-attribute', plus `'args'.

     Values must always be strings, integers, or symbols that represent
     ToolTalk constants or lists of same.  When a list of values is
     provided all of the list elements are added to the attribute.  In
     the example above, messages whose `op' attribute is `"operation1"'
     or `"operation2"' would match the pattern.

     The value of ARGS should be a list of pattern arguments where each
     pattern argument has the following form:

             `(mode [value [type]])' or just `value'

     Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is
     a string.  If TYPE isn't specified then `int' is used if VALUE is
     a number; otherwise `string' is used.  If TYPE is `string' then
     VALUE is converted to a string (if it isn't a string already) with
     `prin1-to-string'.  If only a value is specified then MODE
     defaults to `TT_IN'.  If MODE is `TT_OUT' then VALUE and TYPE
     don't need to be specified.  You can find out more about the
     semantics and uses of ToolTalk pattern arguments in chapter 3 of
     the `ToolTalk Programmer's Guide'.

 - Function: register-tooltalk-pattern PAT
     Emacs will begin receiving messages that match this pattern.

 - Function: unregister-tooltalk-pattern PAT
     Emacs will stop receiving messages that match this pattern.

 - Function: add-tooltalk-pattern-attribute VALUE PAT INDICATOR
     Add one value to the indicated pattern attribute. The names of
     attributes are the same as the ToolTalk accessors used to set them
     less the `tooltalk_pattern_' prefix and the `_add' suffix.  For
     example, the name of the attribute for the
     `tt_pattern_disposition_add' attribute is `disposition'.  The
     `category' attribute is handled specially, since a pattern can only
     be a member of one category (`TT_OBSERVE' or `TT_HANDLE').

     Callbacks are handled slightly differently than in the C ToolTalk
     API.  The value of CALLBACK should be the name of a function of one
     argument.  It will be called each time the pattern matches an
     incoming message.

 - Function: add-tooltalk-pattern-arg PAT MODE TYPE VALUE
     Add one fully-specified argument to a ToolTalk pattern.  MODE must
     be one of `TT_IN', `TT_INOUT', or `TT_OUT'.  TYPE must be a
     string.  VALUE can be an integer, string or `nil'.  If VALUE is an
     integer then an integer argument (`tt_pattern_iarg_add') is added;
     otherwise a string argument is added.  At present there's no way
     to add a binary data argument.

 - Function: create-tooltalk-pattern
     Create a new ToolTalk pattern and initialize its session attribute
     to be the default session.

 - Function: destroy-tooltalk-pattern PAT
     Apply `tt_pattern_destroy' to the pattern.  This effectively
     unregisters the pattern.

 - Function: describe-tooltalk-message MSG &optional STREAM
     Print the message's attributes and arguments to STREAM.  This is
     often useful for debugging.

Internationalization
********************

I18N Levels 1 and 2
===================

   Emacs is now compliant with I18N levels 1 and 2.  Specifically, this
means that it is 8-bit clean and correctly handles time and date
functions.  Emacs will correctly display the entire ISO-Latin 1
character set.

   The compose key may now be used to create any character in the
ISO-Latin 1 character set not directly available via the keyboard..  In
order for the compose key to work it is necessary to load the file
`x-compose.el'.  At any time while composing a character, `C-h' will
display all valid completions and the character which would be produced.

I18N Level 3
============

Level 3 Basics
--------------

   Emacs now provides alpha-level functionality for I18N Level 3.  This
means that everything necessary for full messaging is available, but
not every file has been converted.

   The two message files which have been created are `src/emacs.po' and
`lisp/packages/mh-e.po'.  Both files need to be converted using
`msgfmt', and the resulting `.mo' files placed in some locale's
`LC_MESSAGES' directory.  The test "translations" in these files are
the original messages prefixed by `TRNSLT_'.

   The domain for a variable is stored on the variable's property list
under the property name VARIABLE-DOMAIN.  The function
`documentation-property' uses this information when translating a
variable's documentation.

Level 3 Primitives
------------------

 - Function: gettext STRING
     This function looks up STRING in the default message domain and
     returns its translation.  If `I18N3' was not enabled when Emacs was
     compiled, it just returns STRING.

 - Function: dgettext DOMAIN STRING
     This function looks up STRING in the specified message domain and
     returns its translation.  If `I18N3' was not enabled when Emacs was
     compiled, it just returns STRING.

 - Function: bind-text-domain DOMAIN PATHNAME
     This function associates a pathname with a message domain.  Here's
     how the path to message file is constructed under SunOS 5.x:

          `{pathname}/{LANG}/LC_MESSAGES/{domain}.mo'

     If `I18N3' was not enabled when Emacs was compiled, this function
     does nothing.

 - Special Form: domain STRING
     This function specifies the text domain used for translating
     documentation strings and interactive prompts of a function.  For
     example, write:

          (defun foo (arg) "Doc string" (domain "emacs-foo") ...)

     to specify `emacs-foo' as the text domain of the function `foo'.
     The "call" to `domain' is actually a declaration rather than a
     function; when actually called, `domain' just returns `nil'

 - Function: domain-of FUNCTION
     This function returns the text domain of FUNCTION; it returns
     `nil' if it is the default domain.  If `I18N3' was not enabled
     when Emacs was compiled, it always returns `nil'.

Dynamic Messaging
-----------------

   The `format' function has been extended to permit you to change the
order of parameter insertion.  For example, the conversion format
`%1$s' inserts parameter one as a string, while `%2$s' inserts
parameter two.  This is useful when creating translations which require
you to change the word order.

Domain Specification
--------------------

   The default message domain of Emacs is `emacs'.  For add-on
packages, it is best to use a different domain.  For example, let us
say we want to convert the "gorilla" package to use the domain
`emacs-gorilla'.  To translate the message "What gorilla?", use
`dgettext' as follows:

     (dgettext "emacs-gorilla" "What gorilla?")

   A function (or macro) which has a documentation string or an
interactive prompt needs to be associated with the domain in order for
the documentation or prompt to be translated.  This is done with the
`domain' special form as follows:

     (defun scratch (location)
       "Scratch the specified location."
       (domain "emacs-gorilla")
       (interactive "sScratch: ")
       ... )

   It is most efficient to specify the domain in the first line of of
the function body, before the `interactive' form.

   For variables and constants which have documentation strings,
specify the domain after the documentation.

 - Special Form: defvar SYMBOL [VALUE [DOC-STRING [DOMAIN]]]
     Example:
          (defvar weight 250 "Weight of gorilla, in pounds." "emacs-gorilla")

 - Special Form: defconst SYMBOL [VALUE [DOC-STRING [DOMAIN]]]
     Example:
          (defconst limbs 4 "Number of limbs" "emacs-gorilla")

   Autoloaded functions which are specified in `loaddefs.el' do not need
to have a domain specification, because their documentation strings are
extracted into the main message base.  However, for autoloaded functions
which are specified in a separate package, use following syntax:

 - Function: autoload SYMBOL FILENAME &optional DOCSTRING INTERACTIVE
          MACRO DOMAIN
     Example:
          (autoload 'explore "jungle" "Explore the jungle." nil nil "emacs-gorilla")

Documentation String Extraction
-------------------------------

   The utility `etc/make-po' scans the file `DOC' to extract
documentation strings and creates a message file `doc.po'.  This file
may then be inserted within `emacs.po'.

   Currently, `make-po' is hard-coded to read from `DOC' and write to
`doc.po'.  In order to extract documentation strings from an add-on
package, first run `make-docfile' on the package to produce the `DOC'
file.  Then run `make-po -p' with the `-p' argument to indicate that we
are extracting documentation for an add-on package.

   (The `-p' argument is a kludge to make up for a subtle difference
between pre-loaded documentation and add-on documentation:  For add-on
packages, the final carriage returns in the strings produced by
`make-docfile' must be ignored.)

I18N Level 4
============

   Not yet documented.

Tips and Standards
******************

   This chapter describes no additional features of Emacs Lisp.
Instead it gives advice on making effective use of the features
described in the previous chapters.

Writing Clean Lisp Programs
===========================

   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 Emacs 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 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 Emacs 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 one file FOO uses a macro defined in another file BAR, FOO
     should contain `(require 'BAR)' before the first use of the macro.
     (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.  See Compiling Macros.

   * If you define a major mode, make sure to run a hook variable using
     `run-hooks', just as the existing major modes do.  See Hooks.

   * 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.

     Changing all the major modes in Emacs 18 so they would follow this
     convention was a lot of work.  Abandoning this convention would
     waste that work and inconvenience the users.

   * 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 Emacs, 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.

   * If a file requires certain standard library programs to be loaded
     beforehand, then the comments at the beginning of the file should
     say so.

   * Please keep the names of your Emacs 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.  See Text Lines.

   * Don't use functions that set the mark in your Lisp code (unless
     you are writing a command to set the mark).  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.  See 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.

   * The recommended way to print a message in the echo area is with
     the `message' function, not `princ'.  See The Echo Area.

   * When you encounter an error condition, call the function `error'
     (or `signal').  The function `error' does not return.  See
     Signaling Errors.

     Do not use `message', `throw', `sleep-for', or `beep' to report
     errors.

   * Avoid using recursive edits.  Instead, do what the Rmail `w'
     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.  See 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 library.  (In fact,
     in Emacs names of this form are conventionally used 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 Emacs 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.

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 Emacs Lisp even when a compiled function is
     calling another compiled function.

   * Using the primitive list-searching functions `memq', `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 by the byte
     compiler 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 (see Array Functions.) while `elt' is not
     (see 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
     for users to care about the speed.  See Inline Functions.

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 subroutine of a Lisp program need not have a
     documentation string, and you can save space by using a comment
     instead.

   * The first line of the documentation string should consist of one
     or two complete sentences which stand on their own as a summary.
     In particular, start the line with a capital letter and end with a
     period.

     The documentation string can have additional lines which 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.

   * 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 want to set interactively often.
     If the value is a long list, or a function, or if the variable
     would only be set in init files, then don't start the
     documentation string with `*'.  See 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 both that the variable only has two meaningfully distinct
     values and which value means "yes".

   * 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'.

     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 be variable.

   * 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.

   * 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
     the documentation string is printed, Emacs will substitute
     whatever key is currently bound to `forward-char'.  This will
     usually be `C-f', but if the user has moved key bindings, it will
     be the correct key for that user.  See 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.

   * Don't use the term "Elisp", since that is or was a trademark.  Use
     the term "Emacs Lisp".

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
     inserted.

     (The 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 are used
     to describe the purpose of the following lines or the state of the
     program at that point.  For example:

          (prog1 (setq auto-fill-function
                       ...
                       ...
            ;; update mode-line
            (force-mode-line-update)))

     These comments are also written before a function definition to
     explain what the function does and how to call it properly.

`;;;'
     Comments that start with three semicolons, `;;;', should start at
     the left margin.  Such comments are not used within function
     definitions, but are used to make more general comments.  For
     example:

          ;;; This Lisp code is run in Emacs
          ;;; when it is to operate as a server
          ;;; for other processes.

`;;;;'
     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 Emacs, such as `M-;'
(`indent-for-comment') and TAB (`lisp-indent-line') automatically
indent comments according to these conventions, depending on the the
number of semicolons.  See Manipulating Comments (emacs).

   If you wish to "comment out" a number of lines of code, use triple
semicolons at the beginnings of the lines.

   Any character may be included in a comment, but it is advisable to
precede a character with syntactic significance in Lisp (such as `\' or
unpaired `(' or `)') with a `\', to prevent it from confusing the Emacs
commands for editing Lisp.

Conventional Headers for Emacs Libraries
========================================

   Emacs 19 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 <esr@snark.thyrsus.com>
     ;; Maintainer: Eric S. Raymond <esr@snark.thyrsus.com>
     ;; Created: 14 Jul 1992
     ;; Version: 1.2
     ;; Keywords: docs

     ;; This file is part of GNU Emacs.
     COPYING CONDITIONS...

   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 `;;<TAB>', like this:

          ;; Author: Ashwin Ram <Ram-Ashwin@cs.yale.edu>
          ;;	Dave Sill <de5@ornl.gov>
          ;;	Dave Brennan <brennan@hal.com>
          ;;	Eric Raymond <esr@snark.thyrsus.com>

`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.

   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 Emacs, 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.

GNU Emacs Internals
*******************

   This chapter describes how the runnable Emacs executable is dumped
with the preloaded Lisp libraries in it, how storage is allocated, and
some internal aspects of GNU Emacs that may be of interest to C
programmers.

Building Emacs
==============

   The first step in building Emacs is to compile the C sources.  This
produces a program called `temacs', also called a "bare impure Emacs".
It contains the Emacs Lisp interpreter and I/O routines, but not the
editing commands.

   Then, to create a working Emacs editor, issue the `temacs -l loadup'
command.  This directs `temacs' to evaluate the Lisp files specified in
the file `loadup.el'.  These files set up the normal Emacs editing
environment, resulting in an Emacs which is still impure but no longer
bare.

   It takes a long time to load the standard Lisp files.  Luckily, you
don't have to do this each time you run Emacs; `temacs' can dump out an
executable program called `emacs' which has these files preloaded.
`emacs' starts more quickly because it does not need to load the files.
This is the program that is normally installed.

   To create `emacs', use the command `temacs -batch -l loadup dump'.
The purpose of `-batch' here is to prevent `temacs' from trying to
initialize any of its data on the terminal; this ensures that the
tables of terminal information are empty in the dumped Emacs.

   When the `emacs' executable is started, it automatically loads the
user's `.emacs' file, or the default initialization file `default.el'
if the user has none.  (see Starting Up.)  With the `.emacs' file,
you can produce a version of Emacs that suits you and is not the same
as the version other people use.  With `default.el', you can customize
Emacs for all the users at your site who don't choose to customize it
for themselves.  (For further reflection: why is this different from
the case of the barber who shaves every man who doesn't shave himself?)

   On some systems, dumping does not work.  Then, you must start Emacs
with the `temacs -l loadup' command each time you use it.  This takes a
long time, but since you need to start Emacs once a day at most--and
once a week or less frequently if you never log out--the extra time is
not too severe a problem.

   Before `emacs' is dumped, the documentation strings for primitive
and preloaded functions (and variables) need to be found in the file
where they are stored.  This is done by calling `Snarf-documentation'
(see Accessing Documentation.).  These strings were moved out of
`emacs' to make it smaller.  See Documentation Basics.

 - Function: dump-emacs TO-FILE FROM-FILE
     This function dumps the current state of Emacs 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 Emacs that was already dumped, you
     must set `command-line-processed' to `nil' first for good results.
     See Command Line Arguments.

 - Command: emacs-version
     This function returns a string describing the version of Emacs
     that is running.  It is useful to include this string in bug
     reports.

          (emacs-version)
            => "GNU Emacs 19.10 Lucid of Mon Mar  7 1994 on wellworld
               (usg-unix-v)"

     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 Emacs was built at
     the local site.

          emacs-build-time
               => "Mon Mar  7 18:39:05 1994"

 - Variable: emacs-version
     The value of this variable is the version of Emacs being run.  It
     is a string, e.g. `"19.10 Lucid"'.

Pure Storage
============

   There are two types of storage in GNU Emacs Lisp for user-created
Lisp objects: "normal storage" and "pure storage".  Normal storage is
where all the new data which is created during an Emacs 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 Emacs.

   Pure storage is allocated only while `temacs' is loading the
standard preloaded Lisp libraries.  In the file `emacs', it is marked
as read-only (on operating systems which permit this), so that the
memory space can be shared by all the Emacs jobs running on the machine
at once.  Pure storage is not expandable; a fixed amount is allocated
when Emacs is compiled, and if that is not sufficient for the preloaded
libraries, `temacs' crashes.  If that happens, you will have to
increase the compilation parameter `PURESIZE' in the file `puresize.h'.
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 symbols, or any
     other objects, but just returns them unchanged.  It signals an
     error if asked to copy markers.

     This function is used only while Emacs is being built and dumped;
     it is called only in the file `emacs/lisp/loaddefs.el'.

 - Variable: pure-bytes-used
     The value of this variable is the number of bytes of pure storage
     allocated so far.  Typically, in a dumped Emacs, 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 Emacs initially (allowing those functions to be sharable
     and non-collectible).  It is set to `nil' when Emacs is saved out
     as `emacs'.  The flag is set and reset in the C sources.

     You should not change this flag in a running Emacs.