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

[Kevin Rodgers]

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?

--
Kevin Rodgers