Re: some examples of emacs manual problem

[Michael Powe]

>>>>> "Stefan" == Stefan Monnier <monnier@iro.umontreal.ca> writes:

    >> (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”?

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

I agree.  IMO, the usage of the term `window' and `frame' here correctly
reflects how the editor is used.  When designing a GUI, `frame' has a
different meaning; that is in a different context.  In general
conversation, `window' refers to the entire GUI interface of an
application. This is how it is in daily use in M$ Windows.  We're not
there. As the quoted manual text clearly states, `our window' is that
portion of the frame inside which we interact with the buffer.

    >> (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.

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

In fact, he is missing the point of `self-documenting.'  `C-h k' and
press a keyboard combination and get a message telling you what that
combination is bound to.  `C-h f' and type a function name (e.g.,
`auto-fill-mode') and get a help window with its documentation,
including current status and key binding, if any.  And if you don't know
for sure the name of the function, type a portion, hit TAB, and get a
completion list from which to choose.  AFAIK, no other editor does that.

As far as `advanced' goes ... no other editor (even vi) makes it so
trivially easy to alter the editor's behavior directly by writing
functions and setting keybindings in a config file.  

Many features of modern programming IDEs started in emacs (like jumping
from a compiler error message to the line of source code where the error
was generated).  Just because everybody else knew a good idea when they
saw it and copied it, doesn't make us less `advanced.'

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

One wonders how, exactly, a feature can be "too powerful."

    >> 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”.

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

Most people use a kill-ring without thinking about it -- it's called
`multiple undo' in other editors.  The power in emacs is that you can
select directly from the collection of cut text to put just the piece
you want in exactly the place you want it.

Also, if you're using the GUI version of emacs, you can see the contents
of the kill-ring through the `edit' menu.

(If he thinks the kill-ring is confusing, what's going to happen when he
stumbles across registers?)

If I had a gripe about emacs documentation, it would be the cumbersome
navigation in *info*.  

Thanks.

mp

-- 
Michael Powe            michael@trollope.org            Naugatuck CT USA
I have found little that is good about human beings.  In my experience
most of them are trash.
                -- Sigmund Freud