[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH] objects.texi style
From: |
Joshua Varner |
Subject: |
[PATCH] objects.texi style |
Date: |
Fri, 9 Sep 2005 13:26:37 -0500 |
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
- [PATCH] objects.texi style,
Joshua Varner <=