scratch/no-purespace 813b4414b02 12/13: Pure storage removal: Remove documentation

[Pip Cet]

branch: scratch/no-purespace
commit 813b4414b023c0b0c068bef0fc636a2045794430
Author: Pip Cet <pipcet@protonmail.com>
Commit: Pip Cet <pipcet@protonmail.com>

    Pure storage removal: Remove documentation
    
    As pure storage is now gone, it no longer needs to be documented.
    
    * doc/lispref/elisp.texi (Top):
    * doc/lispref/internals.texi (GNU Emacs Internals): Remove "Pure
    Storage" section.
    (Building Emacs):
    (Garbage Collection):
    (Writing Emacs Primitives):
    * doc/lispref/symbols.texi (Standard Properties): Remove references to
    pure storage.
    * src/alloc.c (Fgarbage_collect): Remove docstring text referring to
    pure storage.
---
 doc/lispref/elisp.texi     |  1 -
 doc/lispref/internals.texi | 73 ----------------------------------------------
 doc/lispref/symbols.texi   |  3 +-
 src/alloc.c                |  4 ---
 4 files changed, 1 insertion(+), 80 deletions(-)

diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index f464bcfe94f..b0bf7f96cf3 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -1651,7 +1651,6 @@ Tips and Conventions
 GNU Emacs Internals
 
 * Building Emacs::          How the dumped Emacs is made.
-* Pure Storage::            Kludge to make preloaded Lisp functions shareable.
 * Garbage Collection::      Reclaiming space for Lisp objects no longer used.
 * Stack-allocated Objects:: Temporary conses and strings on C stack.
 * Memory Usage::            Info about total size of Lisp objects made so far.
diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index a5480a9bf8a..00a3704fcac 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -12,7 +12,6 @@ internal aspects of GNU Emacs that may be of interest to C 
programmers.
 
 @menu
 * Building Emacs::      How the dumped Emacs is made.
-* Pure Storage::        Kludge to make preloaded Lisp functions shareable.
 * Garbage Collection::  Reclaiming space for Lisp objects no longer used.
 * Stack-allocated Objects::    Temporary conses and strings on C stack.
 * Memory Usage::        Info about total size of Lisp objects made so far.
@@ -251,71 +250,6 @@ If the current session was not restored from a dump file, 
the
 value is @code{nil}.
 @end defun
 
-@node Pure Storage
-@section Pure Storage
-@cindex pure storage
-
-  Emacs Lisp uses two kinds of storage for user-created Lisp objects:
-@dfn{normal storage} and @dfn{pure storage}.  Normal storage is where
-all the new data created during an Emacs session are kept
-(@pxref{Garbage Collection}).  Pure storage is used for certain data
-in the preloaded standard Lisp files---data that should never change
-during actual use of Emacs.
-
-  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
-machine at once.  Pure storage is not expandable; a fixed amount is
-allocated when Emacs is compiled, and if that is not sufficient for
-the preloaded libraries, @file{temacs} allocates dynamic memory for
-the part that didn't fit.  If Emacs will be dumped using the
-@code{pdump} method (@pxref{Building Emacs}), the pure-space overflow
-is of no special importance (it just means some of the preloaded stuff
-cannot be shared with other Emacs jobs).  However, if Emacs will be
-dumped using the now obsolete @code{unexec} method, the resulting
-image will work, but garbage collection (@pxref{Garbage Collection})
-is disabled in this situation, causing a memory leak.  Such an
-overflow normally won't happen unless you try to preload additional
-libraries or add features to the standard ones.  Emacs will display a
-warning about the overflow when it starts, if it was dumped using
-@code{unexec}.  If this happens, you should increase the compilation
-parameter @code{SYSTEM_PURESIZE_EXTRA} in the file
-@file{src/puresize.h} and rebuild Emacs.
-
-@defun purecopy object
-This function makes a copy in pure storage of @var{object}, and returns
-it.  It copies a string by simply making a new string with the same
-characters, but without text properties, in pure storage.  It
-recursively copies the contents of vectors and cons cells.  It does
-not make copies of other objects such as symbols, but just returns
-them unchanged.  It signals an error if asked to copy markers.
-
-This function is a no-op except while Emacs is being built and dumped;
-it is usually called only in preloaded Lisp files.
-@end defun
-
-@defvar pure-bytes-used
-The value of this variable is the number of bytes of pure storage
-allocated so far.  Typically, in a dumped Emacs, this number is very
-close to the total amount of pure storage available---if it were not,
-we would preallocate less.
-@end defvar
-
-@defvar purify-flag
-This variable determines whether @code{defun} should make a copy of the
-function definition in pure storage.  If it is non-@code{nil}, then the
-function definition is copied into pure storage.
-
-This flag is @code{t} while loading all of the basic functions for
-building Emacs initially (allowing those functions to be shareable and
-non-collectible).  Dumping Emacs as an executable always writes
-@code{nil} in this variable, regardless of the value it actually has
-before and after dumping.
-
-You should not change this flag in a running Emacs.
-@end defvar
-
 @node Garbage Collection
 @section Garbage Collection
 
@@ -526,12 +460,6 @@ Total heap size, in @var{unit-size} units.
 @item free-size
 Heap space which is not currently used, in @var{unit-size} units.
 @end table
-
-If there was overflow in pure space (@pxref{Pure Storage}), and Emacs
-was dumped using the (now obsolete) @code{unexec} method
-(@pxref{Building Emacs}), then @code{garbage-collect} returns
-@code{nil}, because a real garbage collection cannot be done in that
-case.
 @end deffn
 
 @defopt garbage-collection-messages
@@ -967,7 +895,6 @@ improves user experience.
 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}.
 
 @cindex @code{defsubr}, Lisp symbol for a primitive
   Defining the C function is not enough to make a Lisp primitive
diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi
index c76bf3d3820..211d9b58e06 100644
--- a/doc/lispref/symbols.texi
+++ b/doc/lispref/symbols.texi
@@ -593,8 +593,7 @@ modes.  @xref{Setting Hooks}.
 If the value is non-@code{nil}, the named function is considered to be
 pure (@pxref{What Is a Function}).  Calls with constant arguments can
 be evaluated at compile time.  This may shift run time errors to
-compile time.  Not to be confused with pure storage (@pxref{Pure
-Storage}).
+compile time.
 
 @item risky-local-variable
 If the value is non-@code{nil}, the named variable is considered risky
diff --git a/src/alloc.c b/src/alloc.c
index f7b403f8c0a..ffe68392c03 100644
--- a/src/alloc.c
+++ b/src/alloc.c
@@ -6288,10 +6288,6 @@ where each entry has the form (NAME SIZE USED FREE), 
where:
   keeps around for future allocations (maybe because it does not know how
   to return them to the OS).
 
-However, if there was overflow in pure space, and Emacs was dumped
-using the \"unexec\" method, `garbage-collect' returns nil, because
-real GC can't be done.
-
 Note that calling this function does not guarantee that absolutely all
 unreachable objects will be garbage-collected.  Emacs uses a
 mark-and-sweep garbage collector, but is conservative when it comes to