RE: jargon translation up-front in doc (was: Menu suggestion)

["Drew Adams" <drew.adams@oracle.com>]

Two suggestions in the same spirit that was behind naming the Edit menu
items "Cut", "Copy", and "Paste" (rather than something like "Kill", "Copy
As Kill", and "Yank").


Suggestion #1: a doc table translating five Emacs-speak terms (restated)

My point was not to *replace* anything in the tutorial or anything in the
manual. I too assume that all Emacs terms are defined there before they are
used.

My point was this:

1) In the world outside Emacs (yes, Virginia...) many people are already
familiar with similar (though not identical) concepts under very different
names.

2) So, it can help them to learn Emacs - and to understand its doc - if we
give them a simple, if inexact, translation table for these few terms (five
terms, unless you see others) - *up front*, before any systematic
explanation or tutorial of anything.

Common Term          Emacs Term
-----------          ----------
selection            region
cut                  kill
paste                yank
window               frame
shortcut             key sequence

If they are familiar with these common terms, then this table can help a
lot; if not, they can ignore it.

That's all.

The usefulness of such a simple table is *not* achieved by any up-front
reference to "go read the glossary". And it is not replaced by making sure
that each new term is defined in the doc before it is used.

And yes, there is no guarantee that a user will see such an up-front table.
But it cannot hurt to add it, and it can help.


Suggestion #2: Mention such common terms in doc strings, parenthetically,
for a touchstone.

Since some new users are likely to see `C-h k' help for commonly used keys
before they read the doc or run through the tutorial, it wouldn't hurt to
add the associated "common" term(s) somewhere in the doc strings of a
**few** important, common commands - in parentheses or as added explanation.
Example commands: `kill-region', `clipboard-kill-region', `yank',
`clipboard-yank', `kill-ring-save', `clipboard-kill-ring-save'.

This would also help with finding relevant commands using `command-apropos'.
And it would help them learn the associated Emacs terminology that they will
need in order to understand other concepts.

Again, ignore this suggestion if the Emacs 21 doc strings for these commands
already refer to "cut", "paste", and "copy" - I have only Emacs 20. The
menubar command names "Cut", "Paste", and "Copy" are helpful to newbies, but
the doc strings are not correspondingly clear (in Emacs 20, at least). It
wouldn't take much to add a simple explanation that provides a bridge to
familiar concepts (added text: <<>>):

`kill-region' - "Kill between point and mark.
<<Cuts the selected text to the clipboard for subsequent pasting.>>" (The
complete doc string in Emacs 20 is 14 lines long, without once using the
word "cut", the word "paste", or the word "selected".)

`clipboard-kill-ring-save' - "Copy region to kill ring, and save in the X
clipboard.
<<Copies the selected text to the clipboard for subsequent pasting.>>"

`yank' - "Reinsert the last stretch of killed text.
<<Pastes the clipboard text at the cursor (point). This is the text last
copied or cut.>>" (BTW, the doc string currently says nothing about *where*
the text is inserted.)

`kill-ring-save' is already an example of applying suggestion #2: Among six
lines of arcane stuff about transient mark mode and mark deactivation, we do
mention "cut" and "paste" - that's the kind of additional help I'm
suggesting Emacs should offer.

Yes, I realize that the Emacs functions do not map 1-1 to the common
operations, and it can be misleading to suggest otherwise. Nonetheless, as
long as the "real" explanation is present and precise, it can help if we add
some perhaps imprecise but very familiar terminology in a few key places.

I would further suggest that the *first* doc-string line be the
perhaps-imprecise explanation using familiar terms (that is, reverse the
order shown above). The rest of the doc-string can be as arcane as is needed
to explain the concepts precisely.

 - Drew



-----Original Message-----
From: emacs-devel-bounces+drew.adams=oracle.com@gnu.org
[mailto:emacs-devel-bounces+drew.adams=oracle.com@gnu.org]On Behalf Of
Eli Zaretskii
Sent: Monday, April 26, 2004 11:44 PM
To: Drew Adams
Cc: emacs-devel@gnu.org
Subject: Re: jargon translation up-front in doc (was: Menu suggestion)


> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Mon, 26 Apr 2004 09:36:55 -0700
>
> Proposal - Add a *brief* jargon translation near the beginning of the
> tutorial and the Emacs manual, such as that at
> http://www.emacswiki.org/cgi-bin/wiki/EmacsNewbie, "Fundamental Concepts"
>
> "Emacs-Speak (Jargon)".

I think the tutorial should explain each term before it uses it for
the first time, rather than have a translation table.  If this is not
so, please point out the places that need to ve fixed.

For the manual, we already have all the terms, including the 5 you
mentioned, explained in the Glossary node.  Perhaps all we need to do
is add a reference to that node near the manual's beginning.  I'm not
sure how much it will help, since I don't think many people read the
manual from its beginning, but it surely cannot hurt, I think.