Merge from trunk.

3 files changed, 65 insertions, 13 deletions

diff --git a/src/ChangeLog b/src/ChangeLog
index f61c2ccdb00..c81009928de 100644
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,7 @@
+2012-10-20  Chong Yidong  <cyd@gnu.org>
+
+        * lread.c (Fload): Doc fix (Bug#12592).
+
 2012-10-19  Kazuhiro Ito  <kzhr@d1.dion.ne.jp>  (tiny change)
 
         * font.c (Ffont_at): Fix previous change.
diff --git a/src/lisp.h b/src/lisp.h
index b9e78385313..7b9654e89e8 100644
--- a/src/lisp.h
+++ b/src/lisp.h
@@ -222,7 +222,9 @@ enum enum_USE_LSB_TAG { USE_LSB_TAG = 0 };
 
 /* Define the fundamental Lisp data structures.  */
 
-/* This is the set of Lisp data types.  */
+/* This is the set of Lisp data types.  If you want to define a new
+   data type, read the comments after Lisp_Fwd_Type definition
+   below.  */
 
 /* Lisp integers use 2 tags, to give them one extra bit, thus
    extending their range from, e.g., -2^28..2^28-1 to -2^29..2^29-1.  */
@@ -298,6 +300,53 @@ enum Lisp_Fwd_Type
     Lisp_Fwd_Kboard_Obj,        /* Fwd to a Lisp_Object field of kboards.  */
   };
 
+/* If you want to define a new Lisp data type, here are some
+   instructions.  See the thread at
+   http://lists.gnu.org/archive/html/emacs-devel/2012-10/msg00561.html
+   for more info.
+
+   First, there are already a couple of Lisp types that can be used if
+   your new type does not need to be exposed to Lisp programs nor
+   displayed to users.  These are Lisp_Save_Value, a Lisp_Misc
+   subtype, and PVEC_OTHER, a kind of vectorlike object.  The former
+   is suitable for temporarily stashing away pointers and integers in
+   a Lisp object (see the existing uses of make_save_value and
+   XSAVE_VALUE).  The latter is useful for vector-like Lisp objects
+   that need to be used as part of other objects, but which are never
+   shown to users or Lisp code (search for PVEC_OTHER in xterm.c for
+   an example).
+
+   These two types don't look pretty when printed, so they are
+   unsuitable for Lisp objects that can be exposed to users.
+
+   To define a new data type, add one more Lisp_Misc subtype or one
+   more pseudovector subtype.  Pseudovectors are more suitable for
+   objects with several slots that need to support fast random access,
+   whil Lisp_Misc types are foreverything else.  A pseudovector object
+   provides one or more slots for Lisp objects, followed by struct
+   members that are accessible only from C.  A Lisp_Misc object is a
+   wrapper for a C struct that can contain anything you like.
+
+   To add a new pseudovector type, extend the pvec_type enumeration;
+   to add a new Lisp_Misc, extend the Lisp_Misc_Type enumeration.
+
+   For a Lisp_Misc, you will also need to add your entry to union
+   Lisp_Misc (but make sure the first word has the same structure as
+   the others, starting with a 16-bit member of the Lisp_Misc_Type
+   enumeration and a 1-bit GC markbit) and make sure the overall size
+   of the union is not increased by your addition.
+
+   Then you will need to add switch branches in print.c (in
+   print_object, to print your object, and possibly also in
+   print_preprocess) and to alloc.c, to mark your object (in
+   mark_object) and to free it (in gc_sweep).  The latter is also the
+   right place to call any code specific to your data type that needs
+   to run when the object is recycled -- e.g., free any additional
+   resources allocated for it that are not Lisp objects.  You can even
+   make a pointer to the function that frees the resources a slot in
+   your object -- this way, the same object could be used to represent
+   several disparate C structures.  */
+
 #ifdef CHECK_LISP_OBJECT_TYPE
 
 typedef struct { EMACS_INT i; } Lisp_Object;
diff --git a/src/lread.c b/src/lread.c
index 6d4c0d990af..94744620279 100644
--- a/src/lread.c
+++ b/src/lread.c
@@ -996,18 +996,17 @@ If optional fifth arg MUST-SUFFIX is non-nil, insist on
 the suffix `.elc' or `.el'; don't accept just FILE unless
 it ends in one of those suffixes or includes a directory name.
 
-If this function fails to find a file, it may look for different
-representations of that file before trying another file.
-It does so by adding the non-empty suffixes in `load-file-rep-suffixes'
-to the file name.  Emacs uses this feature mainly to find compressed
-versions of files when Auto Compression mode is enabled.
-
-The exact suffixes that this function tries out, in the exact order,
-are given by the value of the variable `load-file-rep-suffixes' if
-NOSUFFIX is non-nil and by the return value of the function
-`get-load-suffixes' if MUST-SUFFIX is non-nil.  If both NOSUFFIX and
-MUST-SUFFIX are nil, this function first tries out the latter suffixes
-and then the former.
+If NOSUFFIX is nil, then if a file could not be found, try looking for
+a different representation of the file by adding non-empty suffixes to
+its name, before trying another file.  Emacs uses this feature to find
+compressed versions of files when Auto Compression mode is enabled.
+If NOSUFFIX is non-nil, disable this feature.
+
+The suffixes that this function tries out, when NOSUFFIX is nil, are
+given by the return value of `get-load-suffixes' and the values listed
+in `load-file-rep-suffixes'.  If MUST-SUFFIX is non-nil, only the
+return value of `get-load-suffixes' is used, i.e. the file name is
+required to have a non-empty suffix.
 
 Loading a file records its definitions, and its `provide' and
 `require' calls, in an element of `load-history' whose