* [PATCH] objects.texi style
@ 2005-09-09 18:26 Joshua Varner
2005-09-09 20:05 ` Alan Mackenzie
0 siblings, 1 reply; 2+ messages in thread
From: Joshua Varner @ 2005-09-09 18:26 UTC (permalink / raw)
[-- Attachment #1: Type: text/plain, Size: 7759 bytes --]
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.
[-- Attachment #2: objects.texi.style.patch --]
[-- Type: application/octet-stream, Size: 6686 bytes --]
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)
***************
*** 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
***************
*** 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
--- 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
***************
*** 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
***************
*** 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 ----
***************
*** 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.
***************
*** 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)
***************
*** 1607,1613 ****
@node Type Predicates
@section Type Predicates
- @cindex predicates
@cindex type checking
@kindex wrong-type-argument
--- 1575,1580 ----
***************
*** 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
***************
*** 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
[-- Attachment #3: Type: text/plain, Size: 142 bytes --]
_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel
^ permalink raw reply [flat|nested] 2+ messages in thread
* Re: [PATCH] objects.texi style
2005-09-09 18:26 [PATCH] objects.texi style Joshua Varner
@ 2005-09-09 20:05 ` Alan Mackenzie
0 siblings, 0 replies; 2+ messages in thread
From: Alan Mackenzie @ 2005-09-09 20:05 UTC (permalink / raw)
Hi, Emacs!
On Fri, 9 Sep 2005, Joshua Varner wrote:
>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.
Some of your changes aren't style changes; they change the meaning of
the text, albeit subtly.
[original:]
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:
The colon here is not opening a list of (grammatical) objects which get
printed; it is introducing a parenthetical remark which explains what
"hash notation" is. The colon means "which is".
In the changed version, the words after the colon have become a list, but
they are left hanging in the air without a verb. The only available verb
is "printed". The sentence then comes to mean "The following objects get
printed in hash notation: the #<, the descriptive string and the #>.".
This is entirely different from the original, where "these objects" means
lisp objects.
[patched:]
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:
#########################################################################
[original:]
> 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
Here, "... first reads ....., producing a Lisp object" means that the
process of reading the text produces the Lisp object. Compare with "I
turned on the sprinkler, deluging the hackers".
The changed version says "the interpreter first reads the text, then it
produces a Lisp object, and finally it evaluates that object". This is
something different from the original.
[patched:]
> 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
#########################################################################
[ .... ]
>*** 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
Perhaps, but maybe not the one you changed! The question is "what does
`(A . B)' stand for?". By removing that comma, you have changed the
answer from "a cons cell whose car is A, and whose cdr is B" to the bare
"a cons cell" to which secondary information about the components is
appended. I think it would be better to remove the "Oxford comma" before
"and whose cdr is ..". However, these two alternative semantic setups
don't noticeably affect the meaning.
#########################################################################
[ .... ]
>*** 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.
I don't think "subset" is right, here. A type isn't a set. "contained"
isn't too brilliant, either. How about "the array type is a sequence
type, and the string type, .... char-table type are all array types"?
[ .... ]
--
Alan Mackenzie (Munich, Germany)
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2005-09-09 20:05 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2005-09-09 18:26 [PATCH] objects.texi style Joshua Varner
2005-09-09 20:05 ` Alan Mackenzie
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.