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.

3 files changed, 49 insertions, 30 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index bfd49e82d83..1cf91340b9e 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,5 +1,9 @@
 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.
         (Coding Conventions): Mention autoloads.
         Combine partially duplicated macro items.  Fix xref.
diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index 66357516c41..696b2d998c0 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -21,7 +21,7 @@ internal aspects of GNU Emacs that may be of interest to C programmers.
 @end menu
 
 @node Building Emacs
-@appendixsec Building Emacs
+@section Building Emacs
 @cindex building Emacs
 @pindex temacs
 
@@ -44,7 +44,7 @@ environment, resulting in an Emacs that is still impure but no longer
 bare.
 
 @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
 dump out an executable program called @file{emacs} that has these files
 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
 named @file{emacs}.  The variable @code{preloaded-file-list} stores a
 list of the Lisp files that were dumped with the @file{emacs} executable.
 
-  Some operating systems don't support dumping.  On those systems, you
-must start Emacs with the @samp{temacs -l loadup} command each time you
-use it.  This takes a substantial time, but since you need to start
-Emacs once a day at most---or once a week if you never log out---the
-extra time is not too severe a problem.
+  If you port Emacs to a new operating system, and are not able to
+implement dumping, then Emacs must load @file{loadup.el} each time it
+starts.
 
 @cindex @file{site-load.el}
-
   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
 #define SITELOAD_PURESIZE_EXTRA @var{n}
 @end example
 
 @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
 advantage of preloading additional files decreases as machines get
 faster.  On modern machines, it is usually not advisable.
@@ -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
 installation directory for Lisp files when you install Emacs.
 
+@c FIXME the default is non-nil; I don't think this makes sense.
 @item
 Specify a non-@code{nil} value for
 @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
 normal features for your site, do it with @file{default.el}, so that
 users can override your changes if they wish.  @xref{Startup Summary}.
 
-  In a package that can be preloaded, it is sometimes useful to
-specify a computation to be done when Emacs subsequently starts up.
-For this, use @code{eval-at-startup}:
+  In a package that can be preloaded, it is sometimes necessary (or
+useful) to delay certain evaluations until Emacs subsequently starts
+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{}
-This evaluates the @var{body} forms, either immediately if running in
-an Emacs that has already started up, or later when Emacs does start
-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
+In the unlikely event that you need a more general functionality than
+@code{custom-initialize-delay} provides, you can use
+@code{before-init-hook} (@pxref{Startup Summary}).
 
 @defun dump-emacs to-file from-file
 @cindex unexec
@@ -144,7 +154,7 @@ you must run Emacs with @samp{-batch}.
 @end defun
 
 @node Pure Storage
-@appendixsec Pure Storage
+@section Pure Storage
 @cindex pure storage
 
   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.
 @end defvar
 
 @node Garbage Collection
-@appendixsec Garbage Collection
+@section Garbage Collection
 @cindex garbage collection
 
 @cindex memory allocation
@@ -494,7 +504,7 @@ Emacs session.
 @end defvar
 
 @node Writing Emacs Primitives
-@appendixsec Writing Emacs Primitives
+@section Writing Emacs Primitives
 @cindex primitive function internals
 @cindex writing Emacs primitives
 
@@ -512,7 +522,7 @@ appearance.)
 @group
 DEFUN ("or", For, Sor, 0, UNEVALLED, 0,
   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.
 @end group
 @group
@@ -811,7 +821,7 @@ in @file{byte-opt.el} which binds @code{side-effect-free-fns} and
 knows about it.
 
 @node Object Internals
-@appendixsec Object Internals
+@section Object Internals
 @cindex object internals
 
   GNU Emacs Lisp manipulates many different types of data.  The actual
@@ -838,7 +848,7 @@ explicitly using a suitable predicate (@pxref{Type Predicates}).
 @end menu
 
 @node Buffer Internals
-@appendixsubsec Buffer Internals
+@subsection Buffer Internals
 @cindex internals, of buffer
 @cindex buffer internals
 
@@ -1101,7 +1111,7 @@ if that window no longer displays this buffer.
 @end table
 
 @node Window Internals
-@appendixsubsec Window Internals
+@subsection Window Internals
 @cindex internals, of window
 @cindex window internals
 
@@ -1134,8 +1144,8 @@ vertically.
 @item next
 @itemx prev
 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{prev} is @code{nil} if it is the leftmost or topmost in its
+@code{nil} if the window is the right-most or bottom-most in its group;
+@code{prev} is @code{nil} if it is the left-most or top-most in its
 group.
 
 @item left_col
@@ -1296,7 +1306,7 @@ A glyph matrix describing the desired display of this window.
 @end table
 
 @node Process Internals
-@appendixsubsec Process Internals
+@subsection Process Internals
 @cindex internals, of process
 @cindex process internals
 
diff --git a/etc/NEWS b/etc/NEWS
index 0180ff55dba..1c733ae5de7 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -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
 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-file has since Emacs 22 (ie, it won't enable View mode if the