changeset 60044:d1e94109daa4

(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.

--- a/lispref/objects.texi	Mon Feb 14 10:19:36 2005 +0000
+++ b/lispref/objects.texi	Mon Feb 14 10:22:36 2005 +0000
@@ -68,14 +68,30 @@
 
   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}.
+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}.
 
-  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.
+@cindex hash notation
+  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
@@ -83,21 +99,6 @@
 emphasize this distinction, but you must keep it in the back of your
 mind, or you will occasionally be very confused.
 
-@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
-
-@example
-(current-buffer)
-     @result{} #<buffer objects.texi>
-@end example
-
   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 @@
 @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 @@
 @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,9 +610,38 @@
 
   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.
+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
+``an object which is not a cons cell''.  These objects are called
+@dfn{atoms}.
+
+@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.  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
+@sc{car} slot of the cons cell holds the element, and its @sc{cdr}
+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
@@ -619,25 +652,17 @@
 for the function @code{cons} that creates them, which in turn was named
 for its purpose, the construction of cells.
 
-@cindex atom
-  Because cons cells are so central to Lisp, we also have a word for
-``an object which is not a cons cell''.  These objects are called
-@dfn{atoms}.
+@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
 
-@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.
-
-   Upon reading, each object inside the parentheses becomes an element
-of the list.  That is, a cons cell is made for each element.  The
-@sc{car} slot of the cons cell holds the element, and its @sc{cdr}
-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}.
-
+@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 @@
 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 @@
 @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 @@
 
   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 @@
 @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}.