Re: Typos in the manual

[Mark Harig]

> > 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.
>
> This should be “to hold other data---i.e., pairs”, i.e., this should
> be an em dash with no surrounding spaces.


Agreed, except that both instances of the Latin abbreviations in your
sentence should be replaced by the words "that is", and both instances
should be preceded by an em dash:

  This should be “to hold other data---that is, pairs”---that is,
  this should be an em dash with no surrounding spaces.

Unfortunately, this opens another can of worms because the internet is
chock full of people using Latin abbreviations in English sentences
outside of parenthetical expressions.


Here are the relevant rules that I learned years ago.  They are
followed by some examples from the Emacs manual (which also contains
many examples that do not follow these rules).

1) Primarily, English sentences should contain English words.  Numbers
should be spelled out when they are in the low digits.  When foreign
words or phrases are included, they should be printed in italics
(unless they have already been accepted into English).  This applies
to general writing.  Mathematics and other academic fields have their
own specialized rules.

2) Because of the previous rule, Latin abbreviations should NOT be
used in English sentences, although there is an exception: when they
are used inside and begin parenthesized expressions, (e.g., inside
this expression).  This applies to "i.e.", "e.g.", and "etc.".  The
abbreviations "i.e." and "e.g." should always be followed by a comma.

3) Clauses that are set off with "that is," or "for example," should
begin with an em dash, and if the clause is in the interior of the
sentence it should be followed with an em dash.  If the following
clause is an independent clause then the em dash is not required.


Examples for rule 2)

- "Send mail through an external mail host (e.g., your Internet
  service provider's SMTP server)."

- "You can force these commands to move according to 'logical lines'
  (i.e., according to the text lines in the buffer) by setting the
  variable `line-move-visual' to `nil'; if a logical line occupies
  multiple screen lines, the cursor then skips over the additional
  screen lines."

- "Finally, you can set the mark by holding down the shift key while
  typing certain cursor motion commands (such as `S-<right>',
  `S-C-f', `S-C-n', etc.)"


Examples for rule 3)

- "Note that in order to insert rows after the last row at the bottom
  of a table, you must place point below the table--that is, outside
  the table--prior to invoking this command."

- "When you edit a file that changes automatically and frequently--for
  example, a log of output from a process that continues to run--it
  may be useful for Emacs to revert the file without querying you."

- "Letters represent various nontrivial 'coding systems'--for example,
  `1' represents ISO Latin-1."

- "This feature is useful for certain character-only terminals built
  to support specific languages or character sets--for example,
  European terminals that support one of the ISO Latin character
  sets."

- `\{N\}' is a postfix operator that specifies repetition N
  times--that is, the preceding regular expression must match exactly
  N times in a row.

- "You will probably want to use a fixed-width default font--that is,
  a font in which all characters have the same width."

- "The command `C-c C-b' (`message-goto-body') moves point to just
  after the header separator line--that is, to the beginning of the
  body."


The next examples, which do NOT use em dashes, are INCORRECT.  The
semicolon should be replaced with an em dash.  The em dash is required
when the subordinate clause is not an independent clause.

- "A date may be "generic"; that is, partially unspecified."

- "By convention, a command name consists of one or more words,
 separated by hyphens; for example, `auto-fill-mode' or
 `manual-entry'."

- "This variable, like all the variables that control Font Lock mode,
  take effect whenever fontification is done; that is, potentially at
  any time."


The next examples, which do NOT use em dashes, are CORRECT.  The
clauses are independent clauses that can stand on their own (they have
their own subject and predicate).

- "The numbers of days shown is inclusive; that is, it includes the
  days specified by mark and point."

- "`C-x C-s' used on a buffer that is not visiting a file has the same
  effect as `C-x C-w'; that is, it reads a file name, marks the
  buffer as visiting that file, and saves it there."

- "However, if a word starts with single-quotes, these are treated as
  a prefix for purposes such as capitalization.  That is, `M-c' will
  convert `'hello'' into `'Hello'', as expected."

- "Some Emacs commands are invoked by just one input event; for
  example, `C-f' moves forward one character in the buffer."

- "Many Emacs commands move point to different places in the buffer;
  for example, you can place point by clicking mouse button 1
  (normally the left button) at the desired location."


--