(Printed Representation): Clarify read syntax vs print.

(Floating Point Type): Explain meaning better.
(Symbol Type): Explain uniqueness better.
(Cons Cell Type): Explain empty list sooner.  CAR and CDR later.
List examples sooner.
(Box Diagrams): New subnode broken out.
Some examples moved from old Lists as Boxes node.
(Dotted Pair Notation): Clarify intro.
(Array Type): Clarify.
(Type Predicates): Add hash-table-p.

1 files changed, 122 insertions, 69 deletions

diff --git a/lispref/objects.texi b/lispref/objects.texi
index 43ecb02f09e..f0bef593f29 100644
--- a/lispref/objects.texi
+++ b/lispref/objects.texi
@@ -68,36 +68,37 @@ to use these types can be found in later chapters.
 
   The @dfn{printed representation} of an object is the format of the
 output generated by the Lisp printer (the function @code{prin1}) for
-that object.  The @dfn{read syntax} of an object is the format of the
-input accepted by the Lisp reader (the function @code{read}) for that
-object.  @xref{Read and Print}.
-
-  Most objects have more than one possible read syntax.  Some types of
-object have no read syntax, since it may not make sense to enter objects
-of these types directly in a Lisp program.  Except for these cases, the
-printed representation of an object is also a read syntax for it.
-
-  In other languages, an expression is text; it has no other form.  In
-Lisp, an expression is primarily a Lisp object and only secondarily the
-text that is the object's read syntax.  Often there is no need to
-emphasize this distinction, but you must keep it in the back of your
-mind, or you will occasionally be very confused.
+that object.  Every data type has a unique printed representation.
+The @dfn{read syntax} of an object is the format of the input accepted
+by the Lisp reader (the function @code{read}) for that object.  This
+is not necessarily unique; many kinds of object have more than one
+syntax.  @xref{Read and Print}.
 
 @cindex hash notation
-  Every type has a printed representation.  Some types have no read
-syntax---for example, the buffer type has none.  Objects of these types
-are printed in @dfn{hash notation}: the characters @samp{#<} followed by
-a descriptive string (typically the type name followed by the name of
-the object), and closed with a matching @samp{>}.  Hash notation cannot
-be read at all, so the Lisp reader signals the error
-@code{invalid-read-syntax} whenever it encounters @samp{#<}.
-@kindex invalid-read-syntax
+  In most cases, an object's printed representation is also a read
+syntax for the object.  However, some types have no read syntax, since
+it does not make sense to enter objects of these types as constants in
+a Lisp program.  These objects are printed in @dfn{hash notation}: the
+characters @samp{#<} followed by a descriptive string (typically the
+type name followed by the name of the object), and closed with a
+matching @samp{>}.  For example:
 
 @example
 (current-buffer)
      @result{} #<buffer objects.texi>
 @end example
 
+@noindent
+Hash notation cannot be read at all, so the Lisp reader signals the
+error @code{invalid-read-syntax} whenever it encounters @samp{#<}.
+@kindex invalid-read-syntax
+
+  In other languages, an expression is text; it has no other form.  In
+Lisp, an expression is primarily a Lisp object and only secondarily the
+text that is the object's read syntax.  Often there is no need to
+emphasize this distinction, but you must keep it in the back of your
+mind, or you will occasionally be very confused.
+
   When you evaluate an expression interactively, the Lisp interpreter
 first reads the textual representation of it, producing a Lisp object,
 and then evaluates that object (@pxref{Evaluation}).  However,
@@ -204,9 +205,11 @@ leading @samp{+} or a final @samp{.}.
 @subsection Floating Point Type
 
   Floating point numbers are the computer equivalent of scientific
-notation.  The precise number of significant figures and the range of
-possible exponents is machine-specific; Emacs always uses the C data
-type @code{double} to store the value.
+notation; you can think of a floating point number as a fraction
+together with a power of ten.  The precise number of significant
+figures and the range of possible exponents is machine-specific; Emacs
+uses the C data type @code{double} to store the value, and internally
+this records a power of 2 rather than a power of 10.
 
   The printed representation for floating point numbers requires either
 a decimal point (with at least one digit following), an exponent, or
@@ -474,9 +477,10 @@ following text.)
 @node Symbol Type
 @subsection Symbol Type
 
-  A @dfn{symbol} in GNU Emacs Lisp is an object with a name.  The symbol
-name serves as the printed representation of the symbol.  In ordinary
-use, the name is unique---no two symbols have the same name.
+  A @dfn{symbol} in GNU Emacs Lisp is an object with a name.  The
+symbol name serves as the printed representation of the symbol.  In
+ordinary Lisp use, with one single obarray (@pxref{Creating Symbols},
+a symbol's name is unique---no two symbols have the same name.
 
   A symbol can serve as a variable, as a function name, or to hold a
 property list.  Or it may serve only to be distinct from all other Lisp
@@ -606,18 +610,10 @@ Lisp are implicit.
 
   A @dfn{list} is a series of cons cells, linked together so that the
 @sc{cdr} slot of each cons cell holds either the next cons cell or the
-empty list.  @xref{Lists}, for functions that work on lists.  Because
-most cons cells are used as part of lists, the phrase @dfn{list
-structure} has come to refer to any structure made out of cons cells.
-
-  The names @sc{car} and @sc{cdr} derive from the history of Lisp.  The
-original Lisp implementation ran on an @w{IBM 704} computer which
-divided words into two parts, called the ``address'' part and the
-``decrement''; @sc{car} was an instruction to extract the contents of
-the address part of a register, and @sc{cdr} an instruction to extract
-the contents of the decrement.  By contrast, ``cons cells'' are named
-for the function @code{cons} that creates them, which in turn was named
-for its purpose, the construction of cells.
+empty list.  The empty list is actually the symbol @code{nil}.
+@xref{Lists}, for functions that work on lists.  Because most cons
+cells are used as part of lists, the phrase @dfn{list structure} has
+come to refer to any structure made out of cons cells.
 
 @cindex atom
   Because cons cells are so central to Lisp, we also have a word for
@@ -627,7 +623,18 @@ for its purpose, the construction of cells.
 @cindex parenthesis
   The read syntax and printed representation for lists are identical, and
 consist of a left parenthesis, an arbitrary number of elements, and a
-right parenthesis.
+right parenthesis.  Here are examples of lists:
+
+@example
+(A 2 "A")            ; @r{A list of three elements.}
+()                   ; @r{A list of no elements (the empty list).}
+nil                  ; @r{A list of no elements (the empty list).}
+("A ()")             ; @r{A list of one element: the string @code{"A ()"}.}
+(A ())               ; @r{A list of two elements: @code{A} and the empty list.}
+(A nil)              ; @r{Equivalent to the previous.}
+((A B C))            ; @r{A list of one element}
+                     ;   @r{(which is a list of three elements).}
+@end example
 
    Upon reading, each object inside the parentheses becomes an element
 of the list.  That is, a cons cell is made for each element.  The
@@ -636,8 +643,26 @@ slot refers to the next cons cell of the list, which holds the next
 element in the list.  The @sc{cdr} slot of the last cons cell is set to
 hold @code{nil}.
 
+  The names @sc{car} and @sc{cdr} derive from the history of Lisp.  The
+original Lisp implementation ran on an @w{IBM 704} computer which
+divided words into two parts, called the ``address'' part and the
+``decrement''; @sc{car} was an instruction to extract the contents of
+the address part of a register, and @sc{cdr} an instruction to extract
+the contents of the decrement.  By contrast, ``cons cells'' are named
+for the function @code{cons} that creates them, which in turn was named
+for its purpose, the construction of cells.
+
+@menu
+* Box Diagrams::                Drawing pictures of lists.
+* Dotted Pair Notation::        A general syntax for cons cells.
+* Association List Type::       A specially constructed list.
+@end menu
+
+@node Box Diagrams
+@subsubsection Drawing Lists as Box Diagrams
 @cindex box diagrams, for lists
 @cindex diagrams, boxed, for lists
+
   A list can be illustrated by a diagram in which the cons cells are
 shown as pairs of boxes, like dominoes.  (The Lisp reader cannot read
 such an illustration; unlike the textual notation, which can be
@@ -688,19 +713,6 @@ buttercup)}, sketched in a different manner:
 to the symbol @code{nil}.  In other words, @code{nil} is both a symbol
 and a list.
 
-  Here are examples of lists written in Lisp syntax:
-
-@example
-(A 2 "A")            ; @r{A list of three elements.}
-()                   ; @r{A list of no elements (the empty list).}
-nil                  ; @r{A list of no elements (the empty list).}
-("A ()")             ; @r{A list of one element: the string @code{"A ()"}.}
-(A ())               ; @r{A list of two elements: @code{A} and the empty list.}
-(A nil)              ; @r{Equivalent to the previous.}
-((A B C))            ; @r{A list of one element}
-                     ;   @r{(which is a list of three elements).}
-@end example
-
   Here is the list @code{(A ())}, or equivalently @code{(A nil)},
 depicted with boxes and arrows:
 
@@ -715,27 +727,64 @@ depicted with boxes and arrows:
 @end group
 @end example
 
-@menu
-* Dotted Pair Notation::        An alternative syntax for lists.
-* Association List Type::       A specially constructed list.
-@end menu
+  Here is a more complex illustration, showing the three-element list,
+@code{((pine needles) oak maple)}, the first element of which is a
+two-element list:
+
+@example
+@group
+    --- ---      --- ---      --- ---
+   |   |   |--> |   |   |--> |   |   |--> nil
+    --- ---      --- ---      --- ---
+     |            |            |
+     |            |            |
+     |             --> oak      --> maple
+     |
+     |     --- ---      --- ---
+      --> |   |   |--> |   |   |--> nil
+           --- ---      --- ---
+            |            |
+            |            |
+             --> pine     --> needles
+@end group
+@end example
+
+  The same list represented in the first box notation looks like this:
+
+@example
+@group
+ --------------       --------------       --------------
+| car   | cdr  |     | car   | cdr  |     | car   | cdr  |
+|   o   |   o------->| oak   |   o------->| maple |  nil |
+|   |   |      |     |       |      |     |       |      |
+ -- | ---------       --------------       --------------
+    |
+    |
+    |        --------------       ----------------
+    |       | car   | cdr  |     | car     | cdr  |
+     ------>| pine  |   o------->| needles |  nil |
+            |       |      |     |         |      |
+             --------------       ----------------
+@end group
+@end example
 
 @node Dotted Pair Notation
-@comment  node-name,  next,  previous,  up
 @subsubsection Dotted Pair Notation
 @cindex dotted pair notation
 @cindex @samp{.} in lists
 
-  @dfn{Dotted pair notation} is an alternative syntax for cons cells
-that represents the @sc{car} and @sc{cdr} explicitly.  In this syntax,
+  @dfn{Dotted pair notation} is a general syntax for cons cells that
+represents the @sc{car} and @sc{cdr} explicitly.  In this syntax,
 @code{(@var{a} .@: @var{b})} stands for a cons cell whose @sc{car} is
 the object @var{a}, and whose @sc{cdr} is the object @var{b}.  Dotted
-pair notation is therefore more general than list syntax.  In the dotted
-pair notation, the list @samp{(1 2 3)} is written as @samp{(1 . (2 . (3
-. nil)))}.  For @code{nil}-terminated lists, you can use either
-notation, but list notation is usually clearer and more convenient.
-When printing a list, the dotted pair notation is only used if the
-@sc{cdr} of a cons cell is not a list.
+pair notation is more general than list syntax because the @sc{cdr}
+does not have to be a list.  However, it is more cumbersome in cases
+where list syntax would work.  In dotted pair notation, the list
+@samp{(1 2 3)} is written as @samp{(1 .  (2 . (3 . nil)))}.  For
+@code{nil}-terminated lists, you can use either notation, but list
+notation is usually clearer and more convenient.  When printing a
+list, the dotted pair notation is only used if the @sc{cdr} of a cons
+cell is not a list.
 
   Here's an example using boxes to illustrate dotted pair notation.
 This example shows the pair @code{(rose . violet)}:
@@ -860,8 +909,9 @@ Once an array is created, its length is fixed.
 
   All Emacs Lisp arrays are one-dimensional.  (Most other programming
 languages support multidimensional arrays, but they are not essential;
-you can get the same effect with an array of arrays.)  Each type of
-array has its own read syntax; see the following sections for details.
+you can get the same effect with nested one-dimensional arrays.)  Each
+type of array has its own read syntax; see the following sections for
+details.
 
   The array type is contained in the sequence type and
 contains the string type, the vector type, the bool-vector type, and the
@@ -1661,6 +1711,9 @@ with references to further information.
 @item functionp
 @xref{Functions, functionp}.
 
+@item hash-table-p
+@xref{Other Hash, hash-table-p}.
+
 @item integer-or-marker-p
 @xref{Predicates on Markers, integer-or-marker-p}.