From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#24890: 25.1; Several documentation problems Date: Mon, 07 Nov 2016 19:56:54 +0200 Message-ID: <834m3ji36h.fsf@gnu.org> References: Reply-To: Eli Zaretskii NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Trace: blaine.gmane.org 1478541451 4579 195.159.176.226 (7 Nov 2016 17:57:31 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 7 Nov 2016 17:57:31 +0000 (UTC) Cc: 24890@debbugs.gnu.org To: Jorge Morais Neto Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Nov 07 18:57:26 2016 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1c3oAP-00070s-NK for geb-bug-gnu-emacs@m.gmane.org; Mon, 07 Nov 2016 18:57:09 +0100 Original-Received: from localhost ([::1]:55671 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1c3oAS-0003mE-Iz for geb-bug-gnu-emacs@m.gmane.org; Mon, 07 Nov 2016 12:57:12 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:54922) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1c3oAL-0003m8-A5 for bug-gnu-emacs@gnu.org; Mon, 07 Nov 2016 12:57:06 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1c3oAI-0000ZD-6c for bug-gnu-emacs@gnu.org; Mon, 07 Nov 2016 12:57:05 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:33237) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1c3oAI-0000Z7-2G for bug-gnu-emacs@gnu.org; Mon, 07 Nov 2016 12:57:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1c3oAH-0002RJ-Ny for bug-gnu-emacs@gnu.org; Mon, 07 Nov 2016 12:57:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 07 Nov 2016 17:57:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 24890 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 24890-submit@debbugs.gnu.org id=B24890.14785413959343 (code B ref 24890); Mon, 07 Nov 2016 17:57:01 +0000 Original-Received: (at 24890) by debbugs.gnu.org; 7 Nov 2016 17:56:35 +0000 Original-Received: from localhost ([127.0.0.1]:48636 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1c3o9q-0002Qd-TZ for submit@debbugs.gnu.org; Mon, 07 Nov 2016 12:56:35 -0500 Original-Received: from eggs.gnu.org ([208.118.235.92]:35570) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1c3o9o-0002QP-Kr for 24890@debbugs.gnu.org; Mon, 07 Nov 2016 12:56:33 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1c3o9g-0000Qt-Bk for 24890@debbugs.gnu.org; Mon, 07 Nov 2016 12:56:27 -0500 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:39963) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1c3o9g-0000Qp-7Y; Mon, 07 Nov 2016 12:56:24 -0500 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:2167 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1c3o9f-0002Fo-GP; Mon, 07 Nov 2016 12:56:23 -0500 In-reply-to: (message from Jorge Morais Neto on Sun, 6 Nov 2016 19:14:52 -0200) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:125428 Archived-At: > From: Jorge Morais Neto > Date: Sun, 6 Nov 2016 19:14:52 -0200 > > I am sorry for having taken this long to report these problems as I > said I would. Thank you for your report. In the future, please consider dividing such long reports into chunks that pertain to related issues. It is hard to discuss and manage a report about so many unrelated subjects. > 1) outline-hide-sublevels and outline-hide-other\\ > The docstrings and the manual should say that each of these commands reveals > everything it does not actively hide. AFAIU, "everything" here boils down to the top body without a heading, if any. Because the fact that all the levels N and above are revealed is mentioned in the doc string already, right? I added a sentence about the heading-less body being unhidden. > Also, please document that, for outline-hide-sublevels, N defaults to the > level of the current headline. Done. I also documented the effect of the prefix argument. > Finally, perhaps the manual should mention that hide-sublevels, hide-other > and some other commands are actually deprecated aliases. I simply replaced the obsolete names with the current ones. > 2) [[info:emacs#Outline Visibility]] informs that hide-body does not > hide the top headless body. This information should also be in the > docstring. Added. > Also, maybe the manual should inform that "hide-body" is a > deprecated alias for "outline-hide-body". See above: I replaced the obsolete name. > 3) Tutorial > 1. In section "* AUTO SAVE", the tutorial mentions "recover-file" where > "recover-this-file" would be better and perhaps recover-session would be > best. > 2. Why does section "* MULTIPLE FRAMES" use "M-x make-frame" and > "M-x delete-frame" instead of "C-x 5 2" and "C-x 5 0" respectively? > 3. In section "* GETTING MORE HELP": > 1) > #+BEGIN_QUOTE > Multi-character commands such as C-x C-s and (if you have no META or > EDIT or ALT key) v are also allowed after C-h c. > #+END_QUOTE > The way that is written, some user might think that "C-h c v" only > works if the terminal lacks a META or EDIT or Alt key. I suggest > replacing the parenthesized text by "(alternative to M-v)", positioned > just after "v". > 2) > #+BEGIN_QUOTE > C-h a Command Apropos. Type in a keyword and Emacs will list all the > commands whose names contain that keyword. These commands can all be > invoked with META-x. For some commands, Command Apropos will also list > a one or two character sequence which runs the same command. > #+END_QUOTE > In the last sentence please replace "one or two" → "short", as some > commands (like find-file-other-frame) have character sequences of 3-4 > chars. > 3) > #+BEGIN_QUOTE > C-h i Read included Manuals (a.k.a. Info). This command puts you into a > special buffer called `*info*' where you can read manuals for the > packages installed on your system. Type m emacs to read the > Emacs manual. If you have never before used Info, type ? and Emacs > will take you on a guided tour of Info mode facilities. > #+END_QUOTE > The guided tour is provided by "h". "?" is also useful, but provides > Info-summary, not the tutorial. Complete beginners need "h" first, > then "?" for a quick reminder each time they forget a keybinding. All fixed. > 4) [[info:emacs#Exiting]] says C-z is bound to suspend-emacs. It is > actually bound to suspend-frame. Only several paragraphs below does > the manual report the correct information. Please correct the > first mention of "C-z". Fixed. > 5) [[info:emacs#Mode Line]] omits the "@" of emacsclient frames. Added. > 6) [[info:emacs#Completion Styles]] on partial-completion > Says that > #+BEGIN_QUOTE > Furthermore, a ‘*’ in the minibuffer text is treated as a “wildcard”—it > matches any character at the corresponding position in the completion > alternative. > #+END_QUOTE > Actually it matches any /string/ at the corresponding position. Fixed. > 7) "list-command-history" docstring is confusing. It says "List history of > commands typed to minibuffer." This does not clearly explain that the > command lists the history of commands that /used/ the minibuffer, including > those that were invoked by keys. Fixed. > 8) [[info:emacs#Yes or No Prompts]] > 1. Swaps "M-v" with "C-v". > 2. In the last paragraph it says: > #+BEGIN_QUOTE > use the history commands ‘M-p’ and ‘M-f’, etc. > #+END_QUOTE > It probably meant M-n instead of M-f. Both fixed. > 9) [[info:emacs#Help Mode]] says: > #+BEGIN_QUOTE > While retracing your steps, you can go forward by using ‘C-c C-b’ > (‘help-go-forward’). > #+END_QUOTE > "help-go-forward" is not "C-c C-b". > > Also, the section omits the handy single-letter aliases: "l" ("C-c C-b"), "r" > ("C-c C-f"). Fixed. > 10) [[info:emacs#Misc Help]]: In the paragraph for describe-mode, please mention > that it shows the key bindings, which is very useful. Done. > 11) "set-mark-command" docstring omits the behavior of activating the mark. > Also it says: > #+BEGIN_QUOTE > Also push the old mark on global mark ring, if the previous mark was set > in another buffer. > #+END_QUOTE > Actually, AFAICT it pushes to the global mark ring /the mark just set/. Fixed. > 12) "C-[" for "" and "C-i" for ""\\ > The manual and probably also the tutorial should mention at the beginning > that C-[ is an alias for . It is very useful because C-[ is faster to > type. Sometimes the difference is big, such as in "C-x ESC ESC" → "C-x C-[ > C-[". In fact it is sometimes faster to type C-[ * than M-*. > > C-i as an alias for TAB is also very useful. For example, to bring an Org > buffer to startup visibility, "C-u C-u C-i" is faster to type than > "C-u C-u ". I understand your point, but I don't see how telling this in a (very large) manual will make these conveniences visible enough to justify the changes. We don't even have a section in the manual that describes special keys, to begin with. > 13) [[info:elisp#Coding Conventions]] > #+BEGIN_QUOTE > • If loading the file adds functions to hooks, define a function > ‘FEATURE-unload-hook’, where FEATURE is the name of the feature the package > provides, and make it undo any such changes. Using ‘unload-feature’ to > unload the file will run this function. > #+END_QUOTE > info:elisp#Unloading, however, mentions /FEATURE-unload-function/ instead of > /FEATURE-unload-hook/. They can both be used, but the -hook variant is obsolete, so I replaced it with -function. > 14) [[info:emacs#Other Repeating Search]]: In my test, "M-s o" does not "Run ‘occur’ > using the search string of the last incremental string search." Instead it > calls "occur" and asks for the pattern. The pattern can then be yanked with > "M-n". I cannot reproduce this. The feature works for me as documented. Did you invoke "M-s o" during the incremental search, i.e. after typing "C-s SOME-TEXT"? > 15) [[info:emacs#Dynamic Abbrevs]] imprecision – it says: > #+BEGIN_QUOTE > After scanning the current buffer, ‘M-/’ normally searches other buffers, > unless you have set ‘dabbrev-check-all-buffers’ to ‘nil’. > #+END_QUOTE > > Actually, according to the docstrings of "dabbrev-check-all-buffers" and > "dabbrev-check-other-buffers", the "unless…" part is imprecise. I suggest > rewriting to > #+BEGIN_QUOTE > After scanning the current buffer, ‘M-/’ normally searches other buffers. > This can be customized via the options "dabbrev-check-other-buffers" and > "dabbrev-check-all-buffers". > #+END_QUOTE Done. > Also, the docstring of "dabbrev-expand" should mention these two options. Added. Also added a couple of other relevant options. > And it should fully describe the behavior when both options are left at > their defaults. Currently it does not say what happens by default if no > suitable preceding word is found in the buffers accepted by the function > pointed out by dabbrev-friend-buffer-function. Not sure what you mean by the last sentence: did you mean the error that is signaled? All the changes were done on the emacs-25 branch, except the tutorial, whose fixes were pushed to master (because tutorial translations need to catch up). Thanks.