Re: [PATCH] objects.texi style

[Alan Mackenzie]

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)