(displaying-byte-compile-warnings): Show

[bpt/emacs.git] / lispref / internals.texi

diff --git a/lispref/internals.texi b/lispref/internals.texi
index c1b17f6..58bd402 100644 (file)
--- a/lispref/internals.texi
+++ b/lispref/internals.texi
@@ -64,36 +64,58 @@ extra time is not too severe a problem.
 
 @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 increase the
-value of @code{PURESIZE}, in @file{src/puresize.h}, to make room for the
-additional files.  (Try adding increments of 20000 until it is big
+@file{site-load.el} that loads them.  You may need to increase the value
+of @code{PURESIZE}, in @file{src/puresize.h}, to make room for the
+additional data.  (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.
 
+  After @file{loadup.el} reads @file{site-load.el}, it finds the
+documentation strings for primitive and preloaded functions (and
+variables) in the file @file{etc/DOC} where they are stored, by calling
+@code{Snarf-documentation} (@pxref{Accessing Documentation}).
+
 @cindex @file{site-init.el}
   You can specify other Lisp expressions to execute just before dumping
-by putting them in a library named @file{site-init.el}.  However, if
-they might alter the behavior that users expect from an ordinary
-unmodified Emacs, it is better to put them in @file{default.el}, so that
-users can override them if they wish.  @xref{Start-up Summary}.
-
-  Before @file{loadup.el} dumps the new executable, it finds the
-documentation strings for primitive and preloaded functions (and
-variables) in the file where they are stored, by calling
-@code{Snarf-documentation} (@pxref{Accessing Documentation}).  These
-strings were moved out of the @file{emacs} executable to make it
-smaller.  @xref{Documentation Basics}.
+by putting them in a library named @file{site-init.el}.  This file is
+executed after the documentation strings are found.
+
+  If you want to preload function or variable definitions, there are
+three ways you can do this and make their documentation strings
+accessible when you subsequently run Emacs:
+
+@itemize @bullet
+@item
+Arrange to scan these files when producing the @file{etc/DOC} file,
+and load them with @file{site-load.el}.
+
+@item
+Load the files with @file{site-init.el}, then copy the files into the
+installation directory for Lisp files when you install Emacs.
+
+@item
+Specify a non-@code{nil} value for
+@code{byte-compile-dynamic-docstrings} as a local variable in each these
+files, and load them with either @file{site-load.el} or
+@file{site-init.el}.  (This method has the drawback that the
+documentation strings take up space in Emacs all the time.)
+@end itemize
+
+  It is not advisable to put anything in @file{site-load.el} or
+@file{site-init.el} that would alter any of the features that users
+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{Start-up Summary}.
 
 @defun dump-emacs to-file from-file
 @cindex unexec
-  This function dumps the current state of Emacs into an executable file
+This function dumps the current state of Emacs into an executable file
 @var{to-file}.  It takes symbols from @var{from-file} (this is normally
 the executable file @file{temacs}).
 
-If you use this function in an Emacs that was already dumped, you must
-set @code{command-line-processed} to @code{nil} first for good results.
-@xref{Command Line Arguments}.
+If you want to use this function in an Emacs that was already dumped,
+you must run Emacs with @samp{-batch}.
 @end defun
 
 @deffn Command emacs-version
@@ -322,6 +344,12 @@ operating system, but that are not currently being used.
 @end table
 @end deffn
 
+@defopt garbage-collection-messages
+If this variable is non-@code{nil}, Emacs displays a message at the
+beginning and end of garbage collection.  The default value is
+@code{nil}, meaning there are no such messages.
+@end defopt
+
 @defopt gc-cons-threshold
 The value of this variable is the number of bytes of storage that must
 be allocated for Lisp objects after one garbage collection in order to
@@ -371,7 +399,7 @@ appearance.)
 @smallexample
 @group
 DEFUN ("or", For, Sor, 0, UNEVALLED, 0,
-  "Eval args until one of them yields non-nil, then return that value.\n\
+  "Eval args until one of them yields non-nil; return that value.\n\
 The remaining args are not evalled at all.\n\
 @end group
 @group