[Top][All Lists]
[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?
- Re: Menu suggestion, (continued)
- Re: Menu suggestion, Robert J. Chassell, 2004/04/28
- Re: Menu suggestion, Miles Bader, 2004/04/28
- Re: Menu suggestion, Robert J. Chassell, 2004/04/28
- Re: Menu suggestion, Richard Stallman, 2004/04/29
- Re: Menu suggestion, Juri Linkov, 2004/04/29
- Re: Menu suggestion, Eli Zaretskii, 2004/04/26
- jargon translation up-front in doc (was: Menu suggestion), Drew Adams, 2004/04/26
- Re: jargon translation up-front in doc (was: Menu suggestion), Eli Zaretskii, 2004/04/27
- RE: jargon translation up-front in doc (was: Menu suggestion), Drew Adams, 2004/04/28
- Re: jargon translation up-front in doc (was: Menu suggestion), Kevin Rodgers, 2004/04/29
- RE: jargon translation up-front in doc (was: Menu suggestion),
Drew Adams <=
- Re: jargon translation up-front in doc (was: Menu suggestion), Kim F. Storm, 2004/04/29
- RE: jargon translation up-front in doc (was: Menu suggestion), Drew Adams, 2004/04/29
- Re: jargon translation up-front in doc (was: Menu suggestion), Richard Stallman, 2004/04/30
- Default Emacs keybindings (was: Re: Menu suggestion), Per Abrahamsen, 2004/04/26
- Re: Default Emacs keybindings (was: Re: Menu suggestion), Luc Teirlinck, 2004/04/26
- Re: Default Emacs keybindings, Per Abrahamsen, 2004/04/26
- Re: Default Emacs keybindings (was: Re: Menu suggestion), Alan Mackenzie, 2004/04/26
- Re: Default Emacs keybindings (was: Re: Menu suggestion), David Kastrup, 2004/04/26
- Re: Default Emacs keybindings (was: Re: Menu suggestion), Kim F. Storm, 2004/04/26
- Re: Default Emacs keybindings (was: Re: Menu suggestion), David Kastrup, 2004/04/26