bug#24890: 25.1; Several documentation problems

[Eli Zaretskii]

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