From: Eli Zaretskii <eliz@gnu.org>
To: Jorge Morais Neto <jorge13515@gmail.com>
Cc: 24890@debbugs.gnu.org
Subject: bug#24890: 25.1; Several documentation problems
Date: Mon, 07 Nov 2016 19:56:54 +0200 [thread overview]
Message-ID: <834m3ji36h.fsf@gnu.org> (raw)
In-Reply-To: <CAJR3QndJij=dJEWvH1gVxfGeGU+CHuBLGcQKHbSYwMAt6SJpjA@mail.gmail.com> (message from Jorge Morais Neto on Sun, 6 Nov 2016 19:14:52 -0200)
> From: Jorge Morais Neto <jorge13515@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.
next prev parent reply other threads:[~2016-11-07 17:56 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-11-06 21:14 bug#24890: 25.1; Several documentation problems Jorge Morais Neto
2016-11-07 17:56 ` Eli Zaretskii [this message]
2016-11-07 18:06 ` Drew Adams
2016-11-10 14:36 ` Jorge Morais Neto
2016-11-10 16:26 ` Eli Zaretskii
2016-11-10 18:10 ` Jorge Morais Neto
2016-11-10 18:53 ` Eli Zaretskii
2016-11-12 19:02 ` Jorge Morais Neto
2016-11-12 19:41 ` Eli Zaretskii
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=834m3ji36h.fsf@gnu.org \
--to=eliz@gnu.org \
--cc=24890@debbugs.gnu.org \
--cc=jorge13515@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.