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

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

That might be good (though excessive hyperlinking can be obfuscating, so
occurrences should *not* all become hyperlinks automatically). If we
provided such hyperlinking, programmers should have a way to explicitly,
selectively apply it (just as they can selectively expand command names in
doc strings to provide key bindings: \\[foobar]).

However, that does *not* address the main issue I raised. (Eli also missed
it, so I must not be making myself clear.)

Explaining our jargon is one thing. Come across "yank" somewhere, don't know
what it means, click it, get the definition - great.

What's missing is the set of common terms as user **entry points**. We
should *mention* those terms, and then provide a bridge to our similar
terms. Just defining our own terms doesn't provide this learning bridge.

A user should be able to do `M-x command-apropos paste' and come up with the
*few, common* commands that involve pasting. A user should be able to see
"paste" prominently in the user interface. Today, "Paste" is available in
the Edit menu - that's great. Let's also make it available in the first line
of (a few) appropriate doc strings. (I just tried `M-x command-apropos
paste' and came up with only dv-paste-to-temp: Load clipboard in buffer
`TEMP' - gnuserv.)

  - 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
Kevin Rodgers
Sent: Thursday, April 29, 2004 8:44 AM
To: emacs-devel@gnu.org
Subject: Re: jargon translation up-front in doc (was: Menu suggestion)


Drew Adams wrote:
 > 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".)

How about automatically highlighting and hyperlinking glossary terms in
doc strings to the corresponding entry in the Glossary info node?