Re: some examples of emacs manual problem

[Stefan Monnier <monnier@iro.umontreal.ca>]

> (1) The writer presumes all users are beginners, with no experience in
> using a editor, even no experience in using a computer. Look at this
> sentence:

>     Files are named units of text which are stored by the operating
> system for you to retrieve later by name.

> O please, do i need to be told what's a file?

We could/should probably remove that part, indeed.

> (2) The author seems to have stopped in the 1980s, lots of tech terms
> have gone obsolete. Look at this:

>     We use the term frame to mean the entire terminal screen or
> graphical window used by Emacs.

>     The main area of the frame, below the tool bar (if one exists) and
> above the echo area, is called the window.

> Wow, your “frame” is my “window”, then what the heck is your “window”?

In what way is that a problem in the manual?  These are the terms used
throughout Emacs's source code and for reasons of Emacs's design source
code names are very visible to the user, so if the manual doesn't
explain what we mean by "frame" and "window", that will be a lot more
confusing.

> (3) Author is nostalgic of the past era; some advanced features of the
> past are no longer advanced. Example:

>     You are reading about GNU Emacs, the GNU incarnation of the
> advanced, self-documenting, customizable, extensible editor Emacs.

> Huh? “self-documenting”? What editor doesn't have documentation?
> “extensible, customizable”? Nowadays many editors all can be extended
> or customized to various degrees.

Very few programs have so much documentation available online.
Even many internal functions have online documentation.
And very few programs are nearly as deeply customizable.
Yes, it's a question of degree, but I think we're still ahead in
those areas.  As for "advanced", well it's just a marketing term.

> (4) Some features are too powerful, so explanation would be
> cumbersome:

>     You can yank text from the kill ring into any position in a
> buffer, including a position in a different buffer; the kill ring is
> shared by all buffers.

> The “yank & kill” here is like “cut & paste”, then what's “kill ring”?
> Perhaps that means when you cut many times, it won't leave just the
> last cut text, previous cuts are all still in “kill ring”.

If you look up kill-ring in the index (e.g. by typing "i kill-ring RET"
in Info), you'll find the section "13.3 Yanking Earlier Kills" which
I hope explains it well enough.

> (5) Because Emacs uses keyboard as its primary input, although these
> days we have mouse, but the core design philosophy still requires all
> functionalities be operable with a keyboard. For example, “selecting a
> text” can be easily done with a mouse, but the manual must use lots
> words to explain how this is done with keyboard. Example:

If you consider it useless to use the keyboard when you can use the
mouse, that's your problem.  For people who find it handy to use the
keyboard, this section is useful.


        Stefan