some examples of emacs manual problem

some examples of emacs manual problem

[Xah Lee]

in the past there's some discussion about emacs manual problems.

recently i found in a blog that contains some concrete example of
emacs's manual problem.

here's relevant excerpt.
--------------------------------------------------

I ran into a Chinese blog article on emacs today. 〈GNU Emacs on
Windows〉 (2010-06-25), by 葉難 (Yeh Nan). At: yehnan.blogspot.com.

It's written in a “Question & Answer” format in a humorous way. Very
well done. There's a interesting section about emacs documentation.
Here's my translation.

Q: These docs [emacs's manual] seem odd?

A: I think Emacs's official docs are all odd and wordy, because:

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

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

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

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

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

    Setting the mark at a position in the text also activates it. When
the mark is active, Emacs indicates the extent of the region by
highlighting the text within it, using the region face. After certain
non-motion commands, including any command that changes the text in
the buffer, Emacs automatically deactivates the mark; this turns off
the highlighting.

What the hell? A Click and a drag, and it's done.

Here's the original.

    問：這些文件怎麼看起來怪怪的？

    答：我覺得Emacs官方寫的文件都很奇怪很囉嗦，因為：

    第一，寫的人把用的人都當做初學者，沒有使用編輯器的經驗、甚至沒有使用電腦的經驗。看看這段話： "Files are named
units of text which are stored by the operating system for you to
retrieve later by name."，拜託，我還需要你教我“檔案”是什麼東西嗎？

    第二，寫文件的人似乎停留在1980年代，裡面很多術語都很老舊了，看看這個： " 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."，哇哩咧，你的frame是我的
window，你的window又是什麼鬼？

    第三，寫文件的人還在緬懷以前的時光，有些在以前算特殊的功能，已經不再特殊了，例如： "You are reading about
GNU Emacs, the GNU incarnation of the advanced, self- documenting,
customizable, extensible editor Emacs."，啥？self-documenting？哪個編輯器沒有說明文件
啊？extensible, customizable？現在很多編輯器多多少少都可以客製化了。

    第四，有些功能太過強大，所以解釋起來很麻煩： "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."，yank&kill在這裡等於cut&paste，而kill
ring呢？大概是指你cut好幾次後，不會只剩下最後一次cut的東西，之前的都還在kill ring裡面。

    第五，因為Emacs以鍵盤為主，雖然現在有滑鼠可以用了，可是其中心思想還是要求所有的功能動作都要能用鍵盤達到，以至於像“把一段文字圈
選”這種以滑鼠可以輕易達到的功能，手冊要用好多篇幅講解鍵盤的指令。譬如說： "Setting the mark at a position
in the text also activates it. When the mark is active, Emacs
indicates the extent of the region by highlighting the text within it,
using the region face. After certain non-motion commands, including
any command that changes the text in the buffer, Emacs automatically
deactivates the mark; this turns off the highlighting. "，什麼鬼啊，滑鼠點一點拉一拉就
好了啦。

For a overall discussion of Emacs Manual problems, see: Problems of
Emacs's Manual.

--------------------------------------------------

html version with formats and links at:
http://xahlee.blogspot.com/2010/08/problems-of-emacss-manual-examples.html

 Xah ∑ xahlee.org ☄

Re: some examples of emacs manual problem

[Stefan Monnier]

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

Re: some examples of emacs manual problem

[Xah Lee]

Hi stefan,

i think the general situation is not about logical flaw or deficiency
of emacs manual. Rather, it's generation gap.

(side note: one example i've been thinking is to compare the classic
english literature Gulliver's Travels. It is well acknowledged by all
scholars to be a impecable piece of english work in grammar, style,
story quality, satire execution, but if you read it today, you find
it's exceedingly difficult to understand... requiring a background
understanding all the politics, history, of europe at the time, as
well as the writing style and vocabulary that's few hundred years old)

back to emacs manual... to my mind, emacs manual problems can be
solved rather without much difficulty, yet still remain accurate, true
to emacs spirit, and i think agreeable to FSF's philosophy as well as
any marketing spirit thrown in.

 Xah ∑ xahlee.org ☄

On Sep 13, 3:30 am, Stefan Monnier <monn...@iro.umontreal.ca> wrote:
> > (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

Re: some examples of emacs manual problem

[B. T. Raven]

Xah Lee wrote:
> Hi stefan,
> 
> i think the general situation is not about logical flaw or deficiency
> of emacs manual. Rather, it's generation gap.
> 
> (side note: one example i've been thinking is to compare the classic
> english literature Gulliver's Travels. It is well acknowledged by all
> scholars to be a impecable piece of english work in grammar, style,
> story quality, satire execution, but if you read it today, you find
> it's exceedingly difficult to understand... requiring a background
> understanding all the politics, history, of europe at the time, as
> well as the writing style and vocabulary that's few hundred years old)

This work is "exceedingly difficult" only to the illiterate and possibly
to many whose native language is not English. Tidbit (beginning of tale
proper):


"
My father had a small estate in Nottinghamshire: I was the third of five
sons.
He sent me to Emanuel College in Cambridge at fourteen years old, where I
resided three years, and applied myself close to my studies; but the
charge of
maintaining me, although I had a very scanty allowance, being too great
for a
narrow fortune, I was bound apprentice to Mr. James Bates, an eminent
surgeon
in London, with whom I continued four years. My father now and then
sending me
small sums of money, I laid them out in learning navigation, and other
parts of
the mathematics, useful to those who intend to travel, as I always
believed it
would be, some time or other, my fortune to do.
"

after a few sentences the author states that he "went down." This is the
first substantive difficulty that I see and, without verifying the fact
of the matter, I assume that Nottinghamshire is lower in elevation than
Cambridge. This is a simple example of a general characteristic of all
natural language: perfect understanding is always dependent on the
minutia of interpretation and context.

Compare this with _Hamlet_, written only 126 years earlier. That play
really is "exceedingly difficult" even for many native speakers of English.

Btw, 99% of the vocabulary of _Gulliver's Travels_ is still in daily
use, 99.99% of it in contemporary writing (even excluding reference works).

Ed


> 
> back to emacs manual... to my mind, emacs manual problems can be
> solved rather without much difficulty, yet still remain accurate, true
> to emacs spirit, and i think agreeable to FSF's philosophy as well as
> any marketing spirit thrown in.
> 
>  Xah ∑ xahlee.org ☄
> 
> On Sep 13, 3:30 am, Stefan Monnier <monn...@iro.umontreal.ca> wrote:
>>> (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

Re: some examples of emacs manual problem

[Stefan Monnier]

> back to emacs manual... to my mind, emacs manual problems can be
> solved rather without much difficulty, yet still remain accurate, true
> to emacs spirit, and i think agreeable to FSF's philosophy as well as
> any marketing spirit thrown in.

I'm glad to hear that, but I personally don't know how you intend to do
that, so please send us some sample patches,


        Stefan