bug#1381: 23.0.60; capitalization of car and cdr in the doc

bug#1381: 23.0.60; capitalization of car and cdr in the doc

[Drew Adams]

See for example these nodes of the Elisp manual: Cons Cell Type,
Search-based Fontification (which should be called Search-Based
Fontification, BTW).
 
I'd suggest not making CAR and CDR uppercase. There is no need to do
that; they are normal words of our vocabulary: speaking about "the
cdr" is no different from speaking about "the cons" ("the cons
cell"). 
 
The first time these terms are introduced (defined), then whatever
convention (quotation marks, uppercase, italic - whatever it is) we
normally use to introduce new terms should be followed, of course.
But thereafter we should just write about conses, cars, and cdrs,
using no special typography. Not CONSes, CARs, and CDRs, and not
CONSES, CARS, and CDRS.
 
Especially in a context, such as node Search-Based Fontification,
where uppercase means something different, treating "car" and "cdr" as
"CAR" and "CDR" is confusing:
 
  `(MATCHER . SUBEXP)'
     In this kind of element, MATCHER is either a regular expression or
     a function, as described above.  The CDR, SUBEXP, specifies which
     subexpression of MATCHER should be highlighted (instead of the
     entire text that MATCHER matched).
 
We wouldn't write "the CDR of the CONS".  "the CDR of the cons" is no
more appropriate. It's clearest to write "the car of the cons".
 
Also, if we don't already do so (I didn't find it), then we should
mention (e.g. in node Cons Cell Type) that "cons" is sometimes used as
short for "cons cell": a cons is a cons cell.  That will improve
readability.  The alternative of mentioning this is to make sure that
we use "cons cell" each time.
 
Naturally, whatever convention we use generally for Emacs vocabulary
should be used for "car" and "cdr" too.  I'm not sure what it is, but
I know we don't use uppercase systematically for Emacs terminology:
"The BUFFER displayed in the top WINDOW of the selected FRAME...".
Similarly: "This cons, whose cdr is 42, has the symbol `foo' as its
car", not "This CONS, whose CDR is 42, has the SYMBOL `foo' as its
CAR".
 
Car 54, where are you?
 
Caveat: I'm looking at the doc in Info (in Emacs). I have no idea how
these terms appear in print. 
 
 
 
In GNU Emacs 23.0.60.1 (i386-mingw-nt5.1.2600)
 of 2008-11-08 on LENNART-69DE564
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --no-opt --cflags -Ic:/g/include
-fno-crossjumping'
 

bug#1381: 23.0.60; capitalization of car and cdr in the doc

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Wed, 19 Nov 2008 10:22:25 -0800
> Cc: 
> 
> See for example these nodes of the Elisp manual: Cons Cell Type,
> Search-based Fontification (which should be called Search-Based
> Fontification, BTW).
>  
> I'd suggest not making CAR and CDR uppercase.

They are not in uppercase, they are in "small caps" typeface (@sc in
Texinfo markup).  You are reading the Info manual, where @sc is
rendered as uppercase, but in the printed manual it looks differently.

bug#1381: 23.0.60; capitalization of car and cdr in the doc

[Drew Adams]

> > See for example these nodes of the Elisp manual: Cons Cell Type,
> > Search-based Fontification (which should be called Search-Based
> > Fontification, BTW).
> >  
> > I'd suggest not making CAR and CDR uppercase.
> 
> They are not in uppercase, they are in "small caps" typeface (@sc in
> Texinfo markup).  You are reading the Info manual, where @sc is
> rendered as uppercase, but in the printed manual it looks differently.

I see. But is that normal for Emacs terminology? See what I wrote about cons,
buffer, window, frame, symbol, etc.

If this is intentional, feel free to close the bug. It seems odd to me, though -
to me, these are normal Emacs terms.

bug#1381: 23.0.60; capitalization of car and cdr in the doc

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <emacs-pretest-bug@gnu.org>, <bug-gnu-emacs@gnu.org>
> Date: Wed, 19 Nov 2008 11:46:59 -0800
> 
> > > I'd suggest not making CAR and CDR uppercase.
> > 
> > They are not in uppercase, they are in "small caps" typeface (@sc in
> > Texinfo markup).  You are reading the Info manual, where @sc is
> > rendered as uppercase, but in the printed manual it looks differently.
> 
> I see. But is that normal for Emacs terminology? See what I wrote about cons,
> buffer, window, frame, symbol, etc.
> 
> If this is intentional, feel free to close the bug. It seems odd to me, though -
> to me, these are normal Emacs terms.

These were in the manual since a long time ago, so I'll let Richard
answer this.

bug#1381: 23.0.60; capitalization of car and cdr in the doc

[Richard M. Stallman]

    They are not in uppercase, they are in "small caps" typeface (@sc in
    Texinfo markup).  You are reading the Info manual, where @sc is
    rendered as uppercase, but in the printed manual it looks differently.

It may be a mistake to render @sc as upper case in Info
because these words might get confused with variable names.
(I don't know if that is a real problem.)

bug#1381: 23.0.60; capitalization of car and cdr in the doc

[Drew Adams]

>     They are not in uppercase, they are in "small caps" 
>     typeface (@sc in
>     Texinfo markup).  You are reading the Info manual, where @sc is
>     rendered as uppercase, but in the printed manual it looks 
>     differently.
> 
> It may be a mistake to render @sc as upper case in Info
> because these words might get confused with variable names.
> (I don't know if that is a real problem.)

OK, that's one thing. But my question was whether these shouldn't simply be
treated as normal Emacs terms - just like cons, buffer, symbol, and frame, after
they have been introduced (defined).

bug#1381: 23.0.60; capitalization of car and cdr in the doc

[Richard M. Stallman]

    OK, that's one thing. But my question was whether these shouldn't simply be
    treated as normal Emacs terms - just like cons, buffer, symbol, and frame, after
    they have been introduced (defined).

The reason for using @sc on car and cdr is that they are acronyms.
Those other terms are not acronyms.

bug#1381: 23.0.60; capitalization of car and cdr in the doc

[Drew Adams]

>     OK, that's one thing. But my question was whether these 
>     shouldn't simply be treated as normal Emacs terms - just
>     like cons, buffer, symbol, and frame, after
>     they have been introduced (defined).
> 
> The reason for using @sc on car and cdr is that they are acronyms.
> Those other terms are not acronyms.

I see. That makes sense, I guess, though I'm not sure it's important. (If we
always stuck to that convention, then we might always write "EMACS" or "EMacS",
not "Emacs". ;-))

FWIW, this is what Wikipedia says about the orthography of acronyms:

 The most common capitalization scheme seen with acronyms
 and initialisms is all-uppercase (all-caps), except for
 those few that have linguistically taken on an identity
 as regular words, with the acronymous etymology of the
 words fading into the background of common knowledge, such
 as has occurred with the words scuba, laser, and radar.

That's the argument I'd make here: "car" and "cdr" have linguistically taken on
an identity as regular words. The machine registers that were at the orgins of
these terms are incidental to the current meanings, and knowledge of that
historical relation is anecdotal.

I see "cdr" (for Lispians) the same way I see "radar". We should encourage
thinking of these as common terms, rather than as acronyms about machine
registers. Rather than facilitating understanding, I think it gets in the way of
understanding (and readability) to write "RADAR" and "CDR".

bug#1381: 23.0.60; capitalization of car and cdr in the doc

[Eli Zaretskii]

> From: "Richard M. Stallman" <rms@gnu.org>
> CC: drew.adams@oracle.com, 1381@emacsbugs.donarmstrong.com,
> 	bug-submit-list@donarmstrong.com, emacs-pretest-bug@gnu.org,
> 	bug-gnu-emacs@gnu.org, bug-gnu-emacs@gnu.org
> Date: Thu, 20 Nov 2008 09:26:10 -0500
> 
> It may be a mistake to render @sc as upper case in Info
> because these words might get confused with variable names.

Maybe so, but the alternative (leave them in lower-case) is even
worse.

bug#1381: 23.0.60; capitalization of car and cdr in the doc

[Drew Adams]

> > It may be a mistake to render @sc as upper case in Info
> > because these words might get confused with variable names.
> 
> Maybe so, but the alternative (leave them in lower-case) is even worse.

You spoke in terms of the rendering of @sc, about which I have no opinion.

But just to clarify, did you also mean that "car" and "cons" should not be
lowercase?

Yes, I know you did not say that. But that is what my bug report was about, and
I just want to be sure of what you're saying.

Let's try to separate the issue of how @sc should be rendered from how car and
cdr should be represented. Thx.
 

bug#1381: 23.0.60; capitalization of car and cdr in the doc

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <1381@emacsbugs.donarmstrong.com>, <emacs-pretest-bug@gnu.org>,
>         <bug-gnu-emacs@gnu.org>
> Date: Thu, 20 Nov 2008 12:28:22 -0800
> 
> But just to clarify, did you also mean that "car" and "cons" should not be
> lowercase?

I don't know.  I guess I'm not enough of a Lisper to have an opinion
on that.  I hoped that Richard will respond to that.

> Let's try to separate the issue of how @sc should be rendered from how car and
> cdr should be represented. Thx.

One problem with saying just "car" is that it could be confused to
mean an automobile.  (I'm serious.)

bug#1381: 23.0.60; capitalization of car and cdr in the doc

[Drew Adams]

> > But just to clarify, did you also mean that "car" and 
> > "cons" should not be lowercase?
> 
> I don't know.  I guess I'm not enough of a Lisper to have an opinion
> on that.  I hoped that Richard will respond to that.
> 
> > Let's try to separate the issue of how @sc should be 
> rendered from how car and
> > cdr should be represented. Thx.
> 
> One problem with saying just "car" is that it could be confused to
> mean an automobile.  (I'm serious.)

OK, let's hope to hear from Richard.

I don't think car as automobile is much of a problem, personally.

This is not a big issue, in any case, especially if something is done to
distinguish @sc so that there is no confusion with, say, parameter names. 

If that potential confusion is removed, then the remaining issue is mainly
aesthetic: CDR is just ugly and unnecessary. But I'm OK with whatever is
decided.

bug#1381: 23.0.60; capitalization of car and cdr in the doc

[Yavor Doganov]

Eli Zaretskii wrote:
> 
> One problem with saying just "car" is that it could be confused to
> mean an automobile.  (I'm serious.)

Absolutely.  We had a few reports from readers of
http://gnu.org/gnu/rms-lisp.html who complained that there's a typo.
We changed it to <tt>car</tt>.

bug#1381: 23.0.60; capitalization of car and cdr in the doc

[Drew Adams]

> > One problem with saying just "car" is that it could be confused to
> > mean an automobile.  (I'm serious.)
> 
> Absolutely.  We had a few reports from readers of
> http://gnu.org/gnu/rms-lisp.html who complained that there's a typo.
> We changed it to <tt>car</tt>.

I won't belabor the point, and, again, I'm OK with whatever is decided, but just
for the record, that reference really argues exactly the _opposite_:


1. Unlike the Elisp manual, that speech does not define terms such as `car' that
it uses. It is not intended to be a rigorous or complete description of the Lisp
language and its terminology.

`car' is used in that speech only in passing, with no explanation of what it is.
This is a speech to a Lisp community, after all. The readers might not all be
Lispians, of course, which is why it helps to use a special typeface when it is
first encountered in reading. But Richard's use of `car' in no way explains what
it is - he just uses it normally as if speaking to Lispians. That is quite
different from the use of `car' in the Elisp manual, where it is defined
clearly.


2. Even in that speech (its printed representation, which is all that can count
for this topic), `car' is written as <tt>car</tt>  _only the first time it is
used_. Thereafter, it is written normally - no uppercase, no special typeface -
just normal text, treating it as a normal word.

So even when printing the speech for an audience that you know might be confused
by the term (because of typo reports), you chose to use a special typeface for
only the _first occurrence_.


#2 is exactly what I proposed: Use whatever convention we normally employ to
introduce (define) a term - <tt> or caps or whatever, and thereafter treat it as
a normal word.

bug#1381: acknowledged by developer (close 1382)

[Drew Adams]

What's this about - is it a mistake?

#1381 has nothing to do with #1382.

See below for my last mail (2008) about #1381.



> -----Original Message-----
> From: GNU bug Tracking System [mailto:help-debbugs@gnu.org] 
> Sent: Thursday, June 24, 2010 11:24 AM
> To: Drew Adams
> Subject: bug#1381 acknowledged by developer (close 1382)
> 
> This is an automatic notification regarding your bug report
> #1381: 23.0.60; capitalization of car and cdr in the doc,
> which was filed against the emacs package.
> 
> It has been marked as closed by one of the developers, namely
> Chong Yidong <cyd@stupidchicken.com>.
> 
> You should be hearing from them with a substantive response shortly,
> in case you haven't already. If not, please contact them directly.
> 
> debbugs.gnu.org maintainers
> (administrator, GNU bugs database)

---------------------------------------------------------------------

> -----Original Message-----
> From: Drew Adams Sent: Friday, November 21, 2008 8:18 AM
> To: rms@gnu.org Cc: 1381@emacsbugs.donarmstrong.com; 
> bug-submit-list@donarmstrong.com; bug-gnu-emacs@gnu.org;
emacs-pretest-bug@gnu.org
> Subject: bug#1381: 23.0.60; capitalization of car and cdr in the doc
> 
> >     OK, that's one thing. But my question was whether these 
> >     shouldn't simply be treated as normal Emacs terms - just
> >     like cons, buffer, symbol, and frame, after
> >     they have been introduced (defined).
> > 
> > The reason for using @sc on car and cdr is that they are acronyms.
> > Those other terms are not acronyms.
> 
> I see. That makes sense, I guess, though I'm not sure it's 
> important. (If we
> always stuck to that convention, then we might always write 
> "EMACS" or "EMacS",
> not "Emacs". ;-))
> 
> FWIW, this is what Wikipedia says about the orthography of acronyms:
> 
>  The most common capitalization scheme seen with acronyms
>  and initialisms is all-uppercase (all-caps), except for
>  those few that have linguistically taken on an identity
>  as regular words, with the acronymous etymology of the
>  words fading into the background of common knowledge, such
>  as has occurred with the words scuba, laser, and radar.
> 
> That's the argument I'd make here: "car" and "cdr" have 
> linguistically taken on
> an identity as regular words. The machine registers that were 
> at the orgins of
> these terms are incidental to the current meanings, and 
> knowledge of that
> historical relation is anecdotal.
> 
> I see "cdr" (for Lispians) the same way I see "radar". We 
> should encourage
> thinking of these as common terms, rather than as acronyms 
> about machine
> registers. Rather than facilitating understanding, I think it 
> gets in the way of
> understanding (and readability) to write "RADAR" and "CDR".