bug#24890: 25.1; Several documentation problems

[Eli Zaretskii]

> From: Jorge Morais Neto <jorge13515@gmail.com>
> Date: Thu, 10 Nov 2016 12:36:58 -0200
> Cc: 24890@debbugs.gnu.org
> 
> >> 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?
> In git (branch emacs-25), the docstring of outline-hide-sublevels is only:
> "Hide everything but the top LEVELS levels of headers, in whole buffer.
> This also unhides the top heading-less body, if any.
> 
> Interactively, the prefix argument supplies the value of LEVELS.
> When invoked without a prefix argument, LEVELS defaults to the level
> of the current heading, or to 1 if the current line is not a heading."
> 
> In my understanding, this still does not fully document the behavior
> of actively revealing all headers up to level LEVELS.

Maybe I'm missing something, but what does "Hide everything but the
top LEVELS levels of headers" mean, if not that all the headers of
those levels are revealed?

> The docstring of outline-hide-other is also incomplete in this sense
> because it does not fully document that it actively reveals the body
> of the current entry (it then becomes visible even if it was
> previously hidden).

Once again, I'm at a loss.  The doc string says

  Hide everything except current body and parent and top-level headings.

IOW, it hides everything, leaving the current body revealed.  How else
can this phrase be interpreted?

> >> 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"?
> The manual says:
>     Run ‘occur’ using the search string of the last incremental string
>     search.  You can also run ‘M-s o’ when an incremental search is
>     active; this uses the current search string.
> 
> If I understand English correctly (I am Brazilian) the first sentence
> cited above says that if you run an incremental search, exit it (e.g.
> by pressing RET), and later type M-s o, it will automatically run
> ‘occur’ using the search string of the last incremental string search.

To have occur use the last search string, you need to type "M-n" at
the prompt.  I've now clarified this in the manual.

> >>     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?
> I mean the fact that, in that case, "dabbrev searches all the other
> buffers, except those named in ‘dabbrev-ignored-buffer-names’, or
> matched by ‘dabbrev-ignored-regexps’." (according to
> dabbrev-check-all-buffers docstring).

That is already in the doc string.

Thanks.