[Emacs-diffs] /srv/bzr/emacs/trunk r107487: Some lispref/internals.texi updates

[Glenn Morris]

------------------------------------------------------------
revno: 107487
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Fri 2012-03-02 21:45:21 -0500
message:
  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.
modified:
  doc/lispref/ChangeLog
  doc/lispref/internals.texi
  etc/NEWS

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-03-03 01:29:55 +0000
+++ b/doc/lispref/ChangeLog     2012-03-03 02:45:21 +0000
@@ -1,5 +1,9 @@
 2012-03-03  Glenn Morris  <address@hidden>
 
+       * 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.

=== modified file 'doc/lispref/internals.texi'
--- a/doc/lispref/internals.texi        2012-02-28 04:17:02 +0000
+++ b/doc/lispref/internals.texi        2012-03-03 02:45:21 +0000
@@ -21,7 +21,7 @@
 @end menu
 
 @node Building Emacs
address@hidden Building Emacs
address@hidden Building Emacs
 @cindex building Emacs
 @pindex temacs
 
@@ -44,7 +44,7 @@
 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 @@
 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
address@hidden that loads them.  You may need to add a definition
address@hidden 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 @@
 Load the files with @file{site-init.el}, then copy the files into the
 installation directory for Lisp files when you install Emacs.
 
address@hidden FIXME the default is non-nil; I don't think this makes sense.
 @item
 Specify a address@hidden value for
 @code{byte-compile-dynamic-docstrings} as a local variable in each of these
@@ -121,17 +121,27 @@
 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}:
-
address@hidden eval-at-startup address@hidden
-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}.
address@hidden defmac
+  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.
+
address@hidden 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
address@hidden:initialize} property of a customizable variable.  (The argument
address@hidden is unused, and is provided only for compatiblity with the
+form Custom expects.)
address@hidden defun
+
+In the unlikely event that you need a more general functionality than
address@hidden provides, you can use
address@hidden (@pxref{Startup Summary}).
 
 @defun dump-emacs to-file from-file
 @cindex unexec
@@ -144,7 +154,7 @@
 @end defun
 
 @node Pure Storage
address@hidden Pure Storage
address@hidden Pure Storage
 @cindex pure storage
 
   Emacs Lisp uses two kinds of storage for user-created Lisp objects:
@@ -205,7 +215,7 @@
 @end defvar
 
 @node Garbage Collection
address@hidden Garbage Collection
address@hidden Garbage Collection
 @cindex garbage collection
 
 @cindex memory allocation
@@ -494,7 +504,7 @@
 @end defvar
 
 @node Writing Emacs Primitives
address@hidden Writing Emacs Primitives
address@hidden Writing Emacs Primitives
 @cindex primitive function internals
 @cindex writing Emacs primitives
 
@@ -512,7 +522,7 @@
 @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 @@
 knows about it.
 
 @node Object Internals
address@hidden Object Internals
address@hidden Object Internals
 @cindex object internals
 
   GNU Emacs Lisp manipulates many different types of data.  The actual
@@ -838,7 +848,7 @@
 @end menu
 
 @node Buffer Internals
address@hidden Buffer Internals
address@hidden Buffer Internals
 @cindex internals, of buffer
 @cindex buffer internals
 
@@ -1101,7 +1111,7 @@
 @end table
 
 @node Window Internals
address@hidden Window Internals
address@hidden Window Internals
 @cindex internals, of window
 @cindex window internals
 
@@ -1134,8 +1144,8 @@
 @item next
 @itemx prev
 The next sibling and previous sibling of this window.  @code{next} is
address@hidden if the window is the rightmost or bottommost in its group;
address@hidden is @code{nil} if it is the leftmost or topmost in its
address@hidden if the window is the right-most or bottom-most in its group;
address@hidden is @code{nil} if it is the left-most or top-most in its
 group.
 
 @item left_col
@@ -1296,7 +1306,7 @@
 @end table
 
 @node Process Internals
address@hidden Process Internals
address@hidden Process Internals
 @cindex internals, of process
 @cindex process internals
 

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2012-02-29 04:31:55 +0000
+++ b/etc/NEWS  2012-03-03 02:45:21 +0000
@@ -1057,6 +1057,11 @@
 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