Problems of Emacs's Manual; Examples

By Xah Lee. Date:

This page gives some examples of outdated text in Emacs Manual.

I ran into a Chinese blog article on emacs today. GNU Emacs on Windows , by 葉難 (Yeh Nan). At yehnan.blogspot.com.

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

Emacs Manual Seems Odd?

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

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

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

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

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

④ 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 and kill” here is like “cut and 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”.

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

Emacs Manual Seems Odd? (original Chinese)

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.

Emacs Modernization

  1. Simple Changes Emacs Should Adopt
  2. Why Emacs Keys are Painful
  3. Problems of the Scratch Buffer
  4. M-key Notation vs Alt+key Notation
  5. Menu Problem
  6. Mode Line Problem
  7. cua-mode Problems
  8. kill-buffer Induces Buffer Accumulation
  9. Emacs Form Feed ^L
  10. Inconsistency of Search Features
  11. Single Key to Delete Whole Line
  12. Emacs HTML Mode Sucks
  13. Emacs Does Not Support Viewing Images Files In Windows
  14. Emacs Spell Checker Problems
  15. Adopt HTML as Texinfo Replacement
  16. Support HTML Mail
  17. Problems of “man” Command
  18. Emacs Lisp Mode Syntax Coloring Problem
  19. Emacs Ahk Mode Problems
  20. Problems of Emacs's Manual
  21. Problems of Emacs's Manual; Examples
  22. Emacs: Have You Read Emacs Manual?
  23. Elisp: Ban Syntax Table
  24. Emacs: Make elisp-index-search use Current Symbol
  25. Emacs: Usability Problems of Mode Documentation
  26. Problems of Emacswiki
  27. Emacs GNU Texinfo Problems; Invalid HTML
  28. A Record of Frustration in IT Industry; Disappearing FSF URLs, 2006
  29. Emacs Manual Node Persistency Issues
  30. Emacs: dired-do-query-replace-regex Replace ALL (fixed)
  31. Problems of Emacs Supporting Obsolete Systems
  32. Elisp: Function to Copy/Delete a Dir Recursively (fixed)
  33. Thoughts on Common Lisp Scheme Lisp Based Emacs
  34. Text Editors Popularity and Market Research
  35. Text Editor's Cursor Movement Behavior (emacs, vi, Notepad++)
  36. GNU Emacs Development Inefficiency
  37. Emacs Dev Inefficiency and Emacs Web 2.0?
  38. Letter-Case Commands Usability Problems
  39. Emacs: Select Line, between Quotes, Extend Selection
  40. Emacs: isearch Current Word
  41. Suggestions on Line Wrap Commands
  42. Emacs: Single Key to Delete Whole Line
  43. Emacs Cult Problem: Emacs vs Windows Notepad
  44. Emacs Undo and Emacs Cult Problem

If you have a question, put $5 at patreon and message me.
Or Buy Xah Emacs Tutorial
Or buy a nice keyboard: Best Keyboards for Emacs

Emacs

Emacs Lisp

Misc