emacs-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: Drew Adams
Subject: RE: jargon translation up-front in doc (was: Menu suggestion)
Date: Thu, 29 Apr 2004 10:37:44 -0700

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: address@hidden
[mailto:address@hidden Behalf Of
Kevin Rodgers
Sent: Thursday, April 29, 2004 8:44 AM
To: address@hidden
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?





reply via email to

[Prev in Thread] Current Thread [Next in Thread]