Package: emacs;
Reported by: Jorge Morais Neto <jorge13515 <at> gmail.com>
Date: Sun, 6 Nov 2016 21:16:01 UTC
Severity: minor
Found in version 25.1
Done: Eli Zaretskii <eliz <at> gnu.org>
Bug is archived. No further changes may be made.
View this message in rfc822 format
From: Eli Zaretskii <eliz <at> gnu.org> To: Jorge Morais Neto <jorge13515 <at> gmail.com> Cc: 24890 <at> debbugs.gnu.org Subject: bug#24890: 25.1; Several documentation problems Date: Mon, 07 Nov 2016 19:56:54 +0200
> From: Jorge Morais Neto <jorge13515 <at> gmail.com>
> 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) <ESC>v are also allowed after C-h c.
> #+END_QUOTE
> The way that is written, some user might think that "C-h c <ESC>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 "<ESC>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 <Return> 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 "<ESC>" and "C-i" for "<tab>"\\
> The manual and probably also the tutorial should mention at the beginning
> that C-[ is an alias for <ESC>. 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 <tab>".
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.
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.