Here are some initial style recommendations for objects.texi. A couple of them are related to indexing. Are there any guidelines when it comes to what should be indexed? For example, none of the types have index entries. Patch attached. Josh Index: objects.texi =================================================================== RCS file: /cvsroot/emacs/emacs/lispref/objects.texi,v retrieving revision 1.48 diff -c -r1.48 objects.texi *** objects.texi 10 Aug 2005 14:29:00 -0000 1.48 --- objects.texi 9 Sep 2005 18:16:23 -0000 *************** *** 79,87 **** 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) --- 79,87 ---- 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{#<}, a descriptive string (typically the type name ! followed by the name of the object), and a closing @samp{>}. For ! example: @example (current-buffer) > Makes the list use consistent parts of speech *************** *** 100,106 **** 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, evaluation and reading are separate activities. Reading returns the Lisp object represented by the text that is read; the object may or may --- 100,106 ---- mind, or you will occasionally be very confused. When you evaluate an expression interactively, the Lisp interpreter ! first reads the textual representation of it, produces a Lisp object, and then evaluates that object (@pxref{Evaluation}). However, evaluation and reading are separate activities. Reading returns the Lisp object represented by the text that is read; the object may or may > Makes the list use consistent parts of speech *************** *** 706,712 **** @end group @end smallexample - @cindex @samp{(@dots{})} in lists @cindex @code{nil} in lists @cindex empty list A list with no elements in it is the @dfn{empty list}; it is identical > Not addressed in this section --- 706,711 ---- *************** *** 749,755 **** @end group @end example ! The same list represented in the first box notation looks like this: @example @group --- 748,754 ---- @end group @end example ! The same list represented in the second box notation looks like this: @example @group > It's the second notation style *************** *** 775,782 **** @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 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 --- 774,781 ---- @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 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 > misplaced comma *************** *** 823,859 **** @code{buttercup} in the @sc{cdr} of a cons cell whose @sc{cdr} is already used for @code{violet}. - The list @code{(rose violet)} is equivalent to @code{(rose . (violet))}, - and looks like this: - - @example - @group - --- --- --- --- - | | |--> | | |--> nil - --- --- --- --- - | | - | | - --> rose --> violet - @end group - @end example - - Similarly, the three-element list @code{(rose violet buttercup)} - is equivalent to @code{(rose . (violet . (buttercup)))}. - @ifnottex - It looks like this: - - @example - @group - --- --- --- --- --- --- - | | |--> | | |--> | | |--> nil - --- --- --- --- --- --- - | | | - | | | - --> rose --> violet --> buttercup - @end group - @end example - @end ifnottex - @node Association List Type @comment node-name, next, previous, up @subsubsection Association List Type --- 822,827 ---- > redundant examples, similar ones already provided *************** *** 913,919 **** 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 char-table type. --- 881,887 ---- type of array has its own read syntax; see the following sections for details. ! The array type is a subset of the sequence type and contains the string type, the vector type, the bool-vector type, and the char-table type. > To me this is clearer, but http://blue.bikeshed.com *************** *** 1166,1173 **** A hash table is a very fast kind of lookup table, somewhat like an alist in that it maps keys to corresponding values, but much faster. ! Hash tables have no read syntax, and ! print using hash notation. @xref{Hash Tables}. @example (make-hash-table) --- 1134,1141 ---- A hash table is a very fast kind of lookup table, somewhat like an alist in that it maps keys to corresponding values, but much faster. ! Hash tables have no read syntax, and print using hash notation. ! @xref{Hash Tables} for functions that work on Hash Tables. @example (make-hash-table) > Makes this reference consistent with other similar references in > similar sections *************** *** 1607,1613 **** @node Type Predicates @section Type Predicates - @cindex predicates @cindex type checking @kindex wrong-type-argument --- 1575,1580 ---- > @cindex type predicates, on next paragraph so this one is > redundant and less explicit *************** *** 1812,1817 **** --- 1779,1785 ---- @node Equality Predicates @section Equality Predicates @cindex equality + @cindex equality predicates Here we describe two functions that test for equality between any two objects. Other functions test equality between objects of specific > Missing index entry *************** *** 1942,1947 **** --- 1910,1916 ---- @end group @end example + @cindex equality of unibyte and multibyte strings Comparison of strings is case-sensitive, but does not take account of text properties---it compares only the characters in the strings. For technical reasons, a unibyte string and a multibyte string are > This may be discussed elsewhere, but I think this warrants an > entry in the index.