[PATCH] objects.texi style

[Joshua Varner]

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.

objects.texi.style.patch
Description: Binary data