Copyedits for Internals and OS chapters of Lisp manual.

* doc/lispref/internals.texi (Building Emacs, Garbage Collection): Copyedits.
(Writing Emacs Primitives): Re-organize discussion of functions
with variable Lisp arguments are handled.  Delete an obsolete
remark, previously tagged as FIXME.

* doc/lispref/os.texi (Idle Timers): Minor clarification.
(Idle Timers): Link to Time of Day for description of time list.

3 files changed, 104 insertions, 136 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 6c512a33978..af0cb306245 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,13 @@
+2012-03-18  Chong Yidong  <cyd@gnu.org>
+
+        * internals.texi (Building Emacs, Garbage Collection): Copyedits.
+        (Writing Emacs Primitives): Re-organize discussion of functions
+        with variable Lisp arguments are handled.  Delete an obsolete
+        remark, previously tagged as FIXME.
+
+        * os.texi (Idle Timers): Minor clarification.
+        (Idle Timers): Link to Time of Day for description of time list.
+
 2012-03-18  Glenn Morris  <rgm@gnu.org>
 
         * os.texi (System Interface): Flow control was removed.
diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index 55b18edf2ec..edf892e751a 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -28,42 +28,39 @@ internal aspects of GNU Emacs that may be of interest to C programmers.
   This section explains the steps involved in building the Emacs
 executable.  You don't have to know this material to build and install
 Emacs, since the makefiles do all these things automatically.  This
-information is pertinent to Emacs maintenance.
+information is pertinent to Emacs developers.
 
    Compilation of the C source files in the @file{src} directory
 produces an executable file called @file{temacs}, also called a
-@dfn{bare impure Emacs}.  It contains the Emacs Lisp interpreter and I/O
-routines, but not the editing commands.
+@dfn{bare impure Emacs}.  It contains the Emacs Lisp interpreter and
+I/O routines, but not the editing commands.
 
 @cindex @file{loadup.el}
-  The command @w{@samp{temacs -l loadup}} uses @file{temacs} to create
-the real runnable Emacs executable.  These arguments direct
-@file{temacs} to evaluate the Lisp files specified in the file
-@file{loadup.el}.  These files set up the normal Emacs editing
-environment, resulting in an Emacs that is still impure but no longer
-bare.
+  The command @w{@command{temacs -l loadup}} would run @file{temacs}
+and direct it to load @file{loadup.el}.  The @code{loadup} library
+loads additional Lisp libraries, which set up the normal Emacs editing
+environment.  After this step, the Emacs executable is no longer
+@dfn{bare}.
 
 @cindex dumping Emacs
-  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
-load the files.  This is the Emacs executable that is normally
-installed.
-
+  Because it takes some time to load the standard Lisp files, the
+@file{temacs} executable usually isn't run directly by users.
+Instead, as one of the last steps of building Emacs, the command
+@samp{temacs -batch -l loadup dump} is run.  The special @samp{dump}
+argument causes @command{temacs} to dump out an executable program,
+called @file{emacs}, which has all the standard Lisp files preloaded.
+(The @samp{-batch} argument prevents @file{temacs} from trying to
+initialize any of its data on the terminal, so that the tables of
+terminal information are empty in the dumped Emacs.)
+
+@cindex preloaded Lisp files
 @vindex preloaded-file-list
-@cindex dumped Lisp files
-  To create @file{emacs}, use the command @samp{temacs -batch -l loadup
-dump}.  The purpose of @samp{-batch} here is to prevent @file{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.
-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.
-
-  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.
+  The dumped @file{emacs} executable (also called a @dfn{pure} Emacs)
+is the one which is installed.  The variable
+@code{preloaded-file-list} stores a list of the Lisp files preloaded
+into the dumped Emacs.  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
@@ -163,7 +160,7 @@ all the new data created during an Emacs session are kept
 in the preloaded standard Lisp files---data that should never change
 during actual use of Emacs.
 
-  Pure storage is allocated only while @file{temacs} is loading the
+  Pure storage is allocated only while @command{temacs} is loading the
 standard preloaded Lisp libraries.  In the file @file{emacs}, it is
 marked as read-only (on operating systems that permit this), so that
 the memory space can be shared by all the Emacs jobs running on the
@@ -214,31 +211,27 @@ You should not change this flag in a running Emacs.
 
 @node Garbage Collection
 @section Garbage Collection
-@cindex garbage collection
 
 @cindex memory allocation
-  When a program creates a list or the user defines a new function (such
-as by loading a library), that data is placed in normal storage.  If
-normal storage runs low, then Emacs asks the operating system to
-allocate more memory in blocks of 1k bytes.  Each block is used for one
-type of Lisp object, so symbols, cons cells, markers, etc., are
-segregated in distinct blocks in memory.  (Vectors, long strings,
-buffers and certain other editing types, which are fairly large, are
-allocated in individual blocks, one per object, while small strings are
-packed into blocks of 8k bytes.)
-
-  It is quite common to use some storage for a while, then release it by
-(for example) killing a buffer or deleting the last pointer to an
-object.  Emacs provides a @dfn{garbage collector} to reclaim this
-abandoned storage.  (This name is traditional, but ``garbage recycler''
-might be a more intuitive metaphor for this facility.)
+  When a program creates a list or the user defines a new function
+(such as by loading a library), that data is placed in normal storage.
+If normal storage runs low, then Emacs asks the operating system to
+allocate more memory.  Different types of Lisp objects, such as
+symbols, cons cells, markers, etc., are segregated in distinct blocks
+in memory.  (Vectors, long strings, buffers and certain other editing
+types, which are fairly large, are allocated in individual blocks, one
+per object, while small strings are packed into blocks of 8k bytes.)
 
-  The garbage collector operates by finding and marking all Lisp objects
-that are still accessible to Lisp programs.  To begin with, it assumes
-all the symbols, their values and associated function definitions, and
-any data presently on the stack, are accessible.  Any objects that can
-be reached indirectly through other accessible objects are also
-accessible.
+@cindex garbage collection
+  It is quite common to use some storage for a while, then release it
+by (for example) killing a buffer or deleting the last pointer to an
+object.  Emacs provides a @dfn{garbage collector} to reclaim this
+abandoned storage.  The garbage collector operates by finding and
+marking all Lisp objects that are still accessible to Lisp programs.
+To begin with, it assumes all the symbols, their values and associated
+function definitions, and any data presently on the stack, are
+accessible.  Any objects that can be reached indirectly through other
+accessible objects are also accessible.
 
   When marking is finished, all objects still unmarked are garbage.  No
 matter what the Lisp program or the user does, it is impossible to refer
@@ -336,11 +329,9 @@ The total size of all strings, in characters.
 The total number of elements of existing vectors.
 
 @item used-floats
-@c Emacs 19 feature
 The number of floats in use.
 
 @item free-floats
-@c Emacs 19 feature
 The number of floats for which space has been obtained from the
 operating system, but that are not currently being used.
 
@@ -417,7 +408,6 @@ memory used by Lisp data, broken down by data type.  By contrast, the
 function @code{memory-limit} provides information on the total amount of
 memory Emacs is currently using.
 
-@c Emacs 19 feature
 @defun memory-limit
 This function returns the address of the last byte Emacs has allocated,
 divided by 1024.  We divide the value by 1024 to make sure it fits in a
@@ -428,7 +418,7 @@ memory usage.
 @end defun
 
 @defvar memory-full
-This variable is @code{t} if Emacs is close to out of memory for Lisp
+This variable is @code{t} if Emacs is nearly out of memory for Lisp
 objects, and @code{nil} otherwise.
 @end defvar
 
@@ -519,8 +509,9 @@ appearance.)
 @smallexample
 @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.
+  doc: /* Eval args until one of them yields non-nil, then return
+that value.
+The remaining args are not evalled at all.
 If all args return nil, return nil.
 @end group
 @group
@@ -566,14 +557,11 @@ This is the name of the Lisp symbol to define as the function name; in
 the example above, it is @code{or}.
 
 @item fname
-This is the C function name for this function.  This is
-the name that is used in C code for calling the function.  The name is,
-by convention, @samp{F} prepended to the Lisp name, with all dashes
-(@samp{-}) in the Lisp name changed to underscores.  Thus, to call this
-function from C code, call @code{For}.  Remember that the arguments must
-be of type @code{Lisp_Object}; various macros and functions for creating
-values of type @code{Lisp_Object} are declared in the file
-@file{lisp.h}.
+This is the C function name for this function.  This is the name that
+is used in C code for calling the function.  The name is, by
+convention, @samp{F} prepended to the Lisp name, with all dashes
+(@samp{-}) in the Lisp name changed to underscores.  Thus, to call
+this function from C code, call @code{For}.
 
 @item sname
 This is a C variable name to use for a structure that holds the data for
@@ -627,38 +615,35 @@ too.
 @end table
 
   After the call to the @code{DEFUN} macro, you must write the
-argument list that every C function must have, including the types for
-the arguments.  For a function with a fixed maximum number of
-arguments, declare a C argument for each Lisp argument, and give them
-all type @code{Lisp_Object}.  When a Lisp function has no upper limit
-on the number of arguments, its implementation in C actually receives
-exactly two arguments: the first is the number of Lisp arguments, and
-the second is the address of a block containing their values.  They
-have types @code{int} and @w{@code{Lisp_Object *}}.
+argument list for the C function, including the types for the
+arguments.  If the primitive accepts a fixed maximum number of Lisp
+arguments, there must be one C argument for each Lisp argument, and
+each argument must be of type @code{Lisp_Object}.  (Various macros and
+functions for creating values of type @code{Lisp_Object} are declared
+in the file @file{lisp.h}.)  If the primitive has no upper limit on
+the number of Lisp arguments, it must have exactly two C arguments:
+the first is the number of Lisp arguments, and the second is the
+address of a block containing their values.  These have types
+@code{int} and @w{@code{Lisp_Object *}} respectively.
 
 @cindex @code{GCPRO} and @code{UNGCPRO}
 @cindex protect C variables from garbage collection
   Within the function @code{For} itself, note the use of the macros
-@code{GCPRO1} and @code{UNGCPRO}.  @code{GCPRO1} is used to
-``protect'' a variable from garbage collection---to inform the garbage
-collector that it must look in that variable and regard its contents
-as an accessible object.  GC protection is necessary whenever you call
-@code{eval_sub} (or @code{Feval}) either directly or indirectly.
-At such a time, any Lisp object that this function may refer to again
-must be protected somehow.
+@code{GCPRO1} and @code{UNGCPRO}.  These macros are defined for the
+sake of the few platforms which do not use Emacs' default
+stack-marking garbage collector.  The @code{GCPRO1} macro ``protects''
+a variable from garbage collection, explicitly informing the garbage
+collector that that variable and all its contents must be as
+accessible.  GC protection is necessary in any function which can
+perform Lisp evaluation by calling @code{eval_sub} or @code{Feval} as
+a subroutine, either directly or indirectly.
 
   It suffices to ensure that at least one pointer to each object is
-GC-protected; that way, the object cannot be recycled, so all pointers
-to it remain valid.  Thus, a particular local variable can do without
+GC-protected.  Thus, a particular local variable can do without
 protection if it is certain that the object it points to will be
 preserved by some other pointer (such as another local variable that
-has a @code{GCPRO}).
-@ignore
-@footnote{Formerly, strings were a special exception; in older Emacs
-versions, every local variable that might point to a string needed a
-@code{GCPRO}.}.
-@end ignore
-Otherwise, the local variable needs a @code{GCPRO}.
+has a @code{GCPRO}).  Otherwise, the local variable needs a
+@code{GCPRO}.
 
   The macro @code{GCPRO1} protects just one local variable.  If you
 want to protect two variables, use @code{GCPRO2} instead; repeating
@@ -667,34 +652,17 @@ want to protect two variables, use @code{GCPRO2} instead; repeating
 implicitly use local variables such as @code{gcpro1}; you must declare
 these explicitly, with type @code{struct gcpro}.  Thus, if you use
 @code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}.
-Alas, we can't explain all the tricky details here.
 
   @code{UNGCPRO} cancels the protection of the variables that are
 protected in the current function.  It is necessary to do this
 explicitly.
 
-  Built-in functions that take a variable number of arguments actually
-accept two arguments at the C level: the number of Lisp arguments, and
-a @code{Lisp_Object *} pointer to a C vector containing those Lisp
-arguments.  This C vector may be part of a Lisp vector, but it need
-not be.  The responsibility for using @code{GCPRO} to protect the Lisp
-arguments from GC if necessary rests with the caller in this case,
-since the caller allocated or found the storage for them.
-
   You must not use C initializers for static or global variables unless
 the variables are never written once Emacs is dumped.  These variables
 with initializers are allocated in an area of memory that becomes
 read-only (on certain operating systems) as a result of dumping Emacs.
 @xref{Pure Storage}.
 
-@c FIXME is this still true?  I don't think so...
-  Do not use static variables within functions---place all static
-variables at top level in the file.  This is necessary because Emacs on
-some operating systems defines the keyword @code{static} as a null
-macro.  (This definition is used because those systems put all variables
-declared static in a place that becomes read-only after dumping, whether
-they have initializers or not.)
-
 @cindex @code{defsubr}, Lisp symbol for a primitive
   Defining the C function is not enough to make a Lisp primitive
 available; you must also create the Lisp symbol for the primitive and
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index ee1aa88a2dd..1021787a0f4 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1760,9 +1760,9 @@ certain length of time.  Aside from how to set them up, idle timers
 work just like ordinary timers.
 
 @deffn Command run-with-idle-timer secs repeat function &rest args
-Set up a timer which runs when Emacs has been idle for @var{secs}
-seconds.  The value of @var{secs} may be an integer or a floating point
-number; a value of the type returned by @code{current-idle-time}
+Set up a timer which runs the next time Emacs is idle for @var{secs}
+seconds.  The value of @var{secs} may be an integer or a floating
+point number; a value of the type returned by @code{current-idle-time}
 is also allowed.
 
 If @var{repeat} is @code{nil}, the timer runs just once, the first time
@@ -1775,13 +1775,13 @@ can use in calling @code{cancel-timer} (@pxref{Timers}).
 @end deffn
 
 @cindex idleness
-  Emacs becomes ``idle'' when it starts waiting for user input, and it
-remains idle until the user provides some input.  If a timer is set for
-five seconds of idleness, it runs approximately five seconds after Emacs
-first becomes idle.  Even if @var{repeat} is non-@code{nil}, this timer
-will not run again as long as Emacs remains idle, because the duration
-of idleness will continue to increase and will not go down to five
-seconds again.
+  Emacs becomes @dfn{idle} when it starts waiting for user input, and
+it remains idle until the user provides some input.  If a timer is set
+for five seconds of idleness, it runs approximately five seconds after
+Emacs first becomes idle.  Even if @var{repeat} is non-@code{nil},
+this timer will not run again as long as Emacs remains idle, because
+the duration of idleness will continue to increase and will not go
+down to five seconds again.
 
   Emacs can do various things while idle: garbage collect, autosave or
 handle data from a subprocess.  But these interludes during idleness do
@@ -1795,22 +1795,12 @@ minutes, and even if there have been garbage collections and autosaves.
 input.  Then it becomes idle again, and all the idle timers that are
 set up to repeat will subsequently run another time, one by one.
 
-@c Emacs 19 feature
 @defun current-idle-time
 If Emacs is idle, this function returns the length of time Emacs has
-been idle, as a list of three integers: @code{(@var{high} @var{low}
-@var{microsec})}.  The integers @var{high} and @var{low} combine to
-give the number of seconds of idleness, which is
-@ifnottex
-@var{high} * 2**16 + @var{low}.
-@end ifnottex
-@tex
-$high*2^{16}+low$.
-@end tex
-
-The third element, @var{microsec}, gives the microseconds since the
-start of the current second (or 0 for systems that return time with
-the resolution of only one second).
+been idle, as a list of three integers: @code{(@var{sec-high}
+@var{sec-low} @var{microsec})}, where @var{high} and @var{low} are the
+high and low bits for the number of seconds and @var{microsec} is the
+additional number of microseconds (@pxref{Time of Day}).
 
 When Emacs is not idle, @code{current-idle-time} returns @code{nil}.
 This is a convenient way to test whether Emacs is idle.
@@ -1843,9 +1833,9 @@ Here's an example:
 @end smallexample
 @end defun
 
-  Some idle timer functions in user Lisp packages have a loop that
-does a certain amount of processing each time around, and exits when
-@code{(input-pending-p)} is non-@code{nil}.  That approach seems very
+  Do not write an idle timer function containing a loop which does a
+certain amount of processing each time around, and exits when
+@code{(input-pending-p)} is non-@code{nil}.  This approach seems very
 natural but has two problems:
 
 @itemize
@@ -1858,9 +1848,9 @@ It blocks out any idle timers that ought to run during that time.
 @end itemize
 
 @noindent
-To avoid these problems, don't use that technique.  Instead, write
-such idle timers to reschedule themselves after a brief pause, using
-the method in the @code{timer-function} example above.
+The correct approach is for the idle timer to reschedule itself after
+a brief pause, using the method in the @code{timer-function} example
+above.
 
 @node Terminal Input
 @section Terminal Input