Subject: bug#24890: 25.1; Several documentation problems

From: Jorge Morais Neto <[email-masked]>
Date: Thu, 10 Nov 2016 12:36:58 -0200

Sorry I took this long to reply.

On 7 November 2016 at 15:56, Eli Zaretskii <[email-masked]> wrote:
>> From: Jorge Morais Neto <[email-masked]>
> 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.
OK.

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

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

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

Thank you very much for improving Emacs!
@Drew: you are welcome.

Regards
-- 
• I am Brazilian.  I hope my English is correct and I welcome corrections.
• Please adopt free formats like PDF, ODF, Org, LaTeX, Opus, WebM and 7z.
• Free (as in free speech) software for Android: https://f-droid.org/