Commit 520f2425 authored by Glenn Morris's avatar Glenn Morris
Browse files

Some lispref/internals.texi updates

* doc/lispref/internals.texi: Change @appendix section commands to @section
(both forms are equivalent; just being consistent with the rest of lispref).
(Building Emacs): Say less about CANNOT_DUMP platforms.
Replace deleted eval-at-startup with custom-initialize-delay.
* etc/NEWS: Mention eval-at-startup.
parent b3134b95
2012-03-03 Glenn Morris <rgm@gnu.org> 2012-03-03 Glenn Morris <rgm@gnu.org>
* internals.texi: Change @appendix section commands to @section.
(Building Emacs): Say less about CANNOT_DUMP platforms.
Replace deleted eval-at-startup with custom-initialize-delay.
* tips.texi: Copyedits. * tips.texi: Copyedits.
(Coding Conventions): Mention autoloads. (Coding Conventions): Mention autoloads.
Combine partially duplicated macro items. Fix xref. Combine partially duplicated macro items. Fix xref.
......
...@@ -21,7 +21,7 @@ internal aspects of GNU Emacs that may be of interest to C programmers. ...@@ -21,7 +21,7 @@ internal aspects of GNU Emacs that may be of interest to C programmers.
@end menu @end menu
@node Building Emacs @node Building Emacs
@appendixsec Building Emacs @section Building Emacs
@cindex building Emacs @cindex building Emacs
@pindex temacs @pindex temacs
...@@ -44,7 +44,7 @@ environment, resulting in an Emacs that is still impure but no longer ...@@ -44,7 +44,7 @@ environment, resulting in an Emacs that is still impure but no longer
bare. bare.
@cindex dumping Emacs @cindex dumping Emacs
It takes a substantial time to load the standard Lisp files. Luckily, It takes some time to load the standard Lisp files. Luckily,
you don't have to do this each time you run Emacs; @file{temacs} can you don't have to do this each time you run Emacs; @file{temacs} can
dump out an executable program called @file{emacs} that has these files dump out an executable program called @file{emacs} that has these files
preloaded. @file{emacs} starts more quickly because it does not need to preloaded. @file{emacs} starts more quickly because it does not need to
...@@ -61,23 +61,22 @@ The argument @samp{dump} tells @file{loadup.el} to dump a new executable ...@@ -61,23 +61,22 @@ The argument @samp{dump} tells @file{loadup.el} to dump a new executable
named @file{emacs}. The variable @code{preloaded-file-list} stores a named @file{emacs}. The variable @code{preloaded-file-list} stores a
list of the Lisp files that were dumped with the @file{emacs} executable. list of the Lisp files that were dumped with the @file{emacs} executable.
Some operating systems don't support dumping. On those systems, you If you port Emacs to a new operating system, and are not able to
must start Emacs with the @samp{temacs -l loadup} command each time you implement dumping, then Emacs must load @file{loadup.el} each time it
use it. This takes a substantial time, but since you need to start starts.
Emacs once a day at most---or once a week if you never log out---the
extra time is not too severe a problem.
@cindex @file{site-load.el} @cindex @file{site-load.el}
You can specify additional files to preload by writing a library named You can specify additional files to preload by writing a library named
@file{site-load.el} that loads them. You may need to add a definition @file{site-load.el} that loads them. You may need to rebuild Emacs
with an added definition
@example @example
#define SITELOAD_PURESIZE_EXTRA @var{n} #define SITELOAD_PURESIZE_EXTRA @var{n}
@end example @end example
@noindent @noindent
to make @var{n} added bytes of pure space to hold the additional files. to make @var{n} added bytes of pure space to hold the additional files;
see @file{src/puresize.h}.
(Try adding increments of 20000 until it is big enough.) However, the (Try adding increments of 20000 until it is big enough.) However, the
advantage of preloading additional files decreases as machines get advantage of preloading additional files decreases as machines get
faster. On modern machines, it is usually not advisable. faster. On modern machines, it is usually not advisable.
...@@ -107,6 +106,7 @@ and load them with @file{site-load.el}. ...@@ -107,6 +106,7 @@ and load them with @file{site-load.el}.
Load the files with @file{site-init.el}, then copy the files into the Load the files with @file{site-init.el}, then copy the files into the
installation directory for Lisp files when you install Emacs. installation directory for Lisp files when you install Emacs.
@c FIXME the default is non-nil; I don't think this makes sense.
@item @item
Specify a non-@code{nil} value for Specify a non-@code{nil} value for
@code{byte-compile-dynamic-docstrings} as a local variable in each of these @code{byte-compile-dynamic-docstrings} as a local variable in each of these
...@@ -121,17 +121,27 @@ expect in an ordinary unmodified Emacs. If you feel you must override ...@@ -121,17 +121,27 @@ expect in an ordinary unmodified Emacs. If you feel you must override
normal features for your site, do it with @file{default.el}, so that normal features for your site, do it with @file{default.el}, so that
users can override your changes if they wish. @xref{Startup Summary}. users can override your changes if they wish. @xref{Startup Summary}.
In a package that can be preloaded, it is sometimes useful to In a package that can be preloaded, it is sometimes necessary (or
specify a computation to be done when Emacs subsequently starts up. useful) to delay certain evaluations until Emacs subsequently starts
For this, use @code{eval-at-startup}: up. The vast majority of such cases relate to the values of
customizable variables. For example, @code{tutorial-directory} is a
variable defined in @file{startup.el}, which is preloaded. The default
value is set based on @code{data-directory}. The variable needs to
access the value of @code{data-directory} when Emacs starts, not when
it is dumped, because the Emacs executable has probably been installed
in a different location since it was dumped.
@defun custom-initialize-delay symbol value
This function delays the initialization of @var{symbol} to the next
Emacs start. You normally use this function by specifying it as the
@code{:initialize} property of a customizable variable. (The argument
@var{value} is unused, and is provided only for compatiblity with the
form Custom expects.)
@end defun
@defmac eval-at-startup body@dots{} In the unlikely event that you need a more general functionality than
This evaluates the @var{body} forms, either immediately if running in @code{custom-initialize-delay} provides, you can use
an Emacs that has already started up, or later when Emacs does start @code{before-init-hook} (@pxref{Startup Summary}).
up. Since the value of the @var{body} forms is not necessarily
available when the @code{eval-at-startup} form is run, that form
always returns @code{nil}.
@end defmac
@defun dump-emacs to-file from-file @defun dump-emacs to-file from-file
@cindex unexec @cindex unexec
...@@ -144,7 +154,7 @@ you must run Emacs with @samp{-batch}. ...@@ -144,7 +154,7 @@ you must run Emacs with @samp{-batch}.
@end defun @end defun
@node Pure Storage @node Pure Storage
@appendixsec Pure Storage @section Pure Storage
@cindex pure storage @cindex pure storage
Emacs Lisp uses two kinds of storage for user-created Lisp objects: Emacs Lisp uses two kinds of storage for user-created Lisp objects:
...@@ -205,7 +215,7 @@ You should not change this flag in a running Emacs. ...@@ -205,7 +215,7 @@ You should not change this flag in a running Emacs.
@end defvar @end defvar
@node Garbage Collection @node Garbage Collection
@appendixsec Garbage Collection @section Garbage Collection
@cindex garbage collection @cindex garbage collection
@cindex memory allocation @cindex memory allocation
...@@ -494,7 +504,7 @@ Emacs session. ...@@ -494,7 +504,7 @@ Emacs session.
@end defvar @end defvar
@node Writing Emacs Primitives @node Writing Emacs Primitives
@appendixsec Writing Emacs Primitives @section Writing Emacs Primitives
@cindex primitive function internals @cindex primitive function internals
@cindex writing Emacs primitives @cindex writing Emacs primitives
...@@ -512,7 +522,7 @@ appearance.) ...@@ -512,7 +522,7 @@ appearance.)
@group @group
DEFUN ("or", For, Sor, 0, UNEVALLED, 0, DEFUN ("or", For, Sor, 0, UNEVALLED, 0,
doc: /* Eval args until one of them yields non-nil, then return that doc: /* Eval args until one of them yields non-nil, then return that
value. The remaining args are not evalled at all. value. The remaining args are not evalled at all.
If all args return nil, return nil. If all args return nil, return nil.
@end group @end group
@group @group
...@@ -811,7 +821,7 @@ in @file{byte-opt.el} which binds @code{side-effect-free-fns} and ...@@ -811,7 +821,7 @@ in @file{byte-opt.el} which binds @code{side-effect-free-fns} and
knows about it. knows about it.
@node Object Internals @node Object Internals
@appendixsec Object Internals @section Object Internals
@cindex object internals @cindex object internals
GNU Emacs Lisp manipulates many different types of data. The actual GNU Emacs Lisp manipulates many different types of data. The actual
...@@ -838,7 +848,7 @@ explicitly using a suitable predicate (@pxref{Type Predicates}). ...@@ -838,7 +848,7 @@ explicitly using a suitable predicate (@pxref{Type Predicates}).
@end menu @end menu
@node Buffer Internals @node Buffer Internals
@appendixsubsec Buffer Internals @subsection Buffer Internals
@cindex internals, of buffer @cindex internals, of buffer
@cindex buffer internals @cindex buffer internals
...@@ -1101,7 +1111,7 @@ if that window no longer displays this buffer. ...@@ -1101,7 +1111,7 @@ if that window no longer displays this buffer.
@end table @end table
@node Window Internals @node Window Internals
@appendixsubsec Window Internals @subsection Window Internals
@cindex internals, of window @cindex internals, of window
@cindex window internals @cindex window internals
...@@ -1134,8 +1144,8 @@ vertically. ...@@ -1134,8 +1144,8 @@ vertically.
@item next @item next
@itemx prev @itemx prev
The next sibling and previous sibling of this window. @code{next} is The next sibling and previous sibling of this window. @code{next} is
@code{nil} if the window is the rightmost or bottommost in its group; @code{nil} if the window is the right-most or bottom-most in its group;
@code{prev} is @code{nil} if it is the leftmost or topmost in its @code{prev} is @code{nil} if it is the left-most or top-most in its
group. group.
@item left_col @item left_col
...@@ -1296,7 +1306,7 @@ A glyph matrix describing the desired display of this window. ...@@ -1296,7 +1306,7 @@ A glyph matrix describing the desired display of this window.
@end table @end table
@node Process Internals @node Process Internals
@appendixsubsec Process Internals @subsection Process Internals
@cindex internals, of process @cindex internals, of process
@cindex process internals @cindex process internals
......
...@@ -1057,6 +1057,11 @@ you have nothing to do in this regard. Code not following the ...@@ -1057,6 +1057,11 @@ you have nothing to do in this regard. Code not following the
appropriate conventions may fail to compile. The most common cause of appropriate conventions may fail to compile. The most common cause of
trouble seems to be an old-style backquote followed by a newline. trouble seems to be an old-style backquote followed by a newline.
+++
** The macro `eval-at-startup' was removed in Emacs 23.2, but this
was not advertised at the time. The function `custom-initialize-delay'
replaced all known uses.
--- ---
** view-buffer now treats special mode-class in the same way that ** view-buffer now treats special mode-class in the same way that
view-file has since Emacs 22 (ie, it won't enable View mode if the view-file has since Emacs 22 (ie, it won't enable View mode if the
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment