Re: Typos in the manual

[Mark Harig <idirectscm@aim.com>]

>
> > Both "i.e." and "e.g." should always be followed by a comma.
>
> Well.  Let me tell you.  I've written those kinds of patches before,
> adding a comma unconditionally and all.  After a few maintainers of
> some packages rejected them, I've become less enthused.
>

Something that's long been a mystery to me is why it is that computer
programmers, who spend their days learning and following the rules and
idioms of various programming languages, do not want to learn and
follow the rules and idioms of natural languages.

Reference manuals should strive to follow grammar and usage rules as
much as possible in a jargon-filled context.  There is enough room
already for confusion and lack of precision.

> Also, while the Chicago Manual of Style recommends it, some other 
online
> grammar sites mention that it is American English style, but British
> English would not add a comma afterwards.  Yet others do not require 
it
> even in American style.
>

Let's follow the guides that do require it.

To propose that the comma sometimes be included and sometimes be
omitted after "i.e." and "e.g." should be considered the same as
proposing that the comma following the words "that is" and "for
example" are optional.  The comma should not be optional because it
changes the meaning of the sentence, often making it ungrammatical.

Examples from the Guile reference manual:

Example 1:

By "simple" we mean data types that are not primarily used as
containers to hold other data -- i.e. pairs, lists, vectors and so on.

Substituting the words "that is" for "i.e." in two alternatives, which
is correct?

A)
By "simple" we mean data types that are not primarily used as
containers to hold other data -- that is pairs, lists, vectors and
so on.

B)
By "simple," we mean data types that are not primarily used as
containers to hold other data, that is, pairs, lists, vectors,
and so on.

Without the comma between "that is" and "pairs," the reader has a
noun-verb phrase that he needs to disambiguate to figure out the true
meaning.  ("that is pairs?"  "that is pairs" *what*?  What is "pairs"
doing?  Oh, you mean, "that is, pairs, lists, ...")

(Note the added comma before 'and so on' in keeping with the rule that
"etc." should always be preceded by a comma, and "etc." is an (Latin)
abbreviation for "and so on.")

Example 2:

An external representation (i.e. one which can written with `write'
and read with `read') of a random state object can be obtained via
`random-state->datum'.

Which is correct?

A)
An external representation (that is one which can written with
`write' and read with `read') of a random state object can be obtained
via `random-state->datum'.

B)
An external representation (that is, one which can written with
`write' and read with `read') of a random state object can be obtained
via `random-state->datum'.

Again, without the comma after "that is," the parenthetical phrase has
a different meaning than it does with the comma.  With the comma,
the phrase is a supplemental description of what is meant by the term
"external representation."  Without the comma, the phrase is selecting
from the supposedly many types of "external representations."

> Cheers,
> Ralf (whose first style book is shipping this way right now ... :-)

GNU Guile is lucky to have someone as knowledgeable as yourself
reviewing its manual.

--