bug#24890: 25.1; Several documentation problems

bug#24890: 25.1; Several documentation problems

[Jorge Morais Neto]

I am sorry for having taken this long to report these problems as I
said I would.

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.  For example, outline-hide-sublevels
   reveals the top N levels of headlines and the top headless body, and all else
   is hidden.  So if N is 2 and some level 1 tree was folded, its children will
   be actively revealed.

   Also, please document that, for outline-hide-sublevels, N defaults to the
   level of the current headline.

   Finally, perhaps the manual should mention that hide-sublevels, hide-other
   and some other commands are actually deprecated aliases.
2) [[info:emacs#Outline Visibility]] informs that hide-body does not
hide the top
   headless body.  This information should also be in the docstring.  Also,
   maybe the manual should inform that "hide-body" is a deprecated alias for
   "outline-hide-body".
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.
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".
5) [[info:emacs#Mode Line]] omits the "@" of emacsclient frames.
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.
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.
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.
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").
10) [[info:emacs#Misc Help]]: In the paragraph for describe-mode, please mention
    that it shows the key bindings, which is very useful.
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/.
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>".
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/.
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".
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

    Also, the docstring of "dabbrev-expand" should mention these two 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.

In GNU Emacs 25.1.1 (x86_64-unknown-linux-gnu, GTK+ Version 3.18.9)
 of 2016-09-18 built on jorge-HP-G42
Windowing system distributor 'The X.Org Foundation', version 11.0.11804000
System Description: Ubuntu 16.04.1 LTS

Configured using:
 'configure --prefix=/usr/local/emacs/ --with-modules'

Configured features:
XPM JPEG TIFF GIF PNG RSVG IMAGEMAGICK SOUND GPM DBUS GCONF GSETTINGS
NOTIFY ACL LIBSELINUX GNUTLS LIBXML2 FREETYPE M17N_FLT LIBOTF XFT ZLIB
TOOLKIT_SCROLL_BARS GTK3 X11 MODULES

Important settings:
  value of $LC_CTYPE: pt_BR.UTF-8
  value of $LC_MONETARY: pt_BR.UTF-8
  value of $LC_NUMERIC: pt_BR.UTF-8
  value of $LC_TIME: en_DK.UTF-8
  value of $LANG: en_US.UTF-8
  value of $XMODIFIERS: @im=ibus
  locale-coding-system: utf-8-unix

Major mode: Org

Minor modes in effect:
  diff-auto-refine-mode: t
  recentf-mode: t
  org-bullets-mode: t
  flyspell-mode: t
  column-enforce-mode: t
  helm-descbinds-mode: t
  helm-mode: t
  shell-dirtrack-mode: t
  async-bytecomp-package-mode: t
  window-numbering-mode: t
  global-edit-server-edit-mode: t
  show-paren-mode: t
  global-whitespace-mode: t
  tooltip-mode: t
  global-eldoc-mode: t
  electric-quote-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  size-indication-mode: t
  column-number-mode: t
  line-number-mode: t
  auto-fill-function: org-auto-fill-function
  transient-mark-mode: t

Recent messages:

Reverting buffer ‘agenda’.
Saving file /home/jorge/org/agenda/genérico.org...
Wrote /home/jorge/org/agenda/genérico.org
Reverting buffer ‘agenda’.
Saved text until "-buffers is non-nil (it defaults to t).
"
Save your position in the tutorial? (y or n) n
Tutorial position not saved
q is undefined

Load-path shadows:
/home/jorge/.emacs.d/elpa/org-bullets-20140918.1137/org-bullets hides
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-bullets
~/.emacs.d/lisp/dired-aux hides /usr/local/emacs/share/emacs/25.1/lisp/dired-aux
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-fortran hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-fortran
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-mhe hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-mhe
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-docview hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-docview
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-eshell hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-eshell
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-tangle hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-tangle
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-plot hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-plot
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-calc hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-calc
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-crypt hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-crypt
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-js hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-js
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-irc hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-irc
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ox-publish hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ox-publish
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-latex hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-latex
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-scala hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-scala
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ox-icalendar hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ox-icalendar
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-gnuplot hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-gnuplot
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ox-beamer hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ox-beamer
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ox hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ox
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-C hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-C
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-bibtex hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-bibtex
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-entities hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-entities
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-core hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-core
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-colview hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-colview
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-ocaml hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-ocaml
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-id hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-id
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-install hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-install
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-loaddefs hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-loaddefs
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-pcomplete
hides /usr/local/emacs/share/emacs/25.1/lisp/org/org-pcomplete
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ox-odt hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ox-odt
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-sass hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-sass
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ox-org hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ox-org
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-table hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-table
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-eval hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-eval
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-compat hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-compat
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-octave hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-octave
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ox-ascii hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ox-ascii
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-org hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-org
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-ledger hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-ledger
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-capture hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-capture
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-io hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-io
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-R hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-R
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ox-texinfo hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ox-texinfo
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-gnus hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-gnus
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-emacs-lisp
hides /usr/local/emacs/share/emacs/25.1/lisp/org/ob-emacs-lisp
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-sql hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-sql
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-bbdb hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-bbdb
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-exp hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-exp
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-clojure hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-clojure
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-plantuml hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-plantuml
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-table hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-table
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ox-man hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ox-man
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-feed hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-feed
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-awk hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-awk
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-keys hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-keys
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-ruby hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-ruby
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-info hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-info
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-dot hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-dot
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-ditaa hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-ditaa
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-ref hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-ref
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-habit hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-habit
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-maxima hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-maxima
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-inlinetask
hides /usr/local/emacs/share/emacs/25.1/lisp/org/org-inlinetask
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-macs hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-macs
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-timer hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-timer
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-clock hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-clock
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ox-md hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ox-md
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-lisp hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-lisp
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-lob hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-lob
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ox-html hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ox-html
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-rmail hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-rmail
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-sqlite hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-sqlite
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-archive hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-archive
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-agenda hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-agenda
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-version hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-version
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-css hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-css
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-screen hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-screen
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-footnote hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-footnote
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-faces hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-faces
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-asymptote hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-asymptote
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-python hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-python
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-scheme hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-scheme
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-comint hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-comint
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-ctags hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-ctags
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-makefile hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-makefile
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-list hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-list
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-java hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-java
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-src hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-src
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-w3m hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-w3m
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-indent hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-indent
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-mscgen hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-mscgen
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-element hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-element
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-picolisp hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-picolisp
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-attach hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-attach
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-haskell hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-haskell
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-macro hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-macro
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ox-latex hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ox-latex
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-shen hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-shen
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-mobile hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-mobile
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-perl hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-perl
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-mouse hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-mouse
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-matlab hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-matlab
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-datetree hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-datetree
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/org-protocol hides
/usr/local/emacs/share/emacs/25.1/lisp/org/org-protocol
/home/jorge/.emacs.d/elpa/org-plus-contrib-20161102/ob-lilypond hides
/usr/local/emacs/share/emacs/25.1/lisp/org/ob-lilypond

Features:
(shadow sort mail-extr emacsbug helm-ring two-column chistory term/xterm
xterm tutorial sendmail gnus-msg gnus-art mm-uu mml2015 mm-view
mml-smime smime dig gnus-sum gnus-group gnus-undo gnus-start gnus-cloud
nnimap nnmail mail-source utf7 netrc nnoo gnus-spec gnus-int gnus-range
gnus-win gnus gnus-ems nnheader org-timer org-colview org-attach vc-git
reporter tabify eieio-opt speedbar sb-image ezimage dframe face-remap
helm-font dabbrev org-capture timezone diff-mode diff wdired
helm-dabbrev term ehelp org-lint ox-odt rng-loc rng-uri rng-parse
rng-match rng-dt rng-util rng-pttrn nxml-parse nxml-ns nxml-enc xmltok
nxml-util ox-latex ox-icalendar ox-html table ox-ascii ox-publish ox
org-archive autorevert help-at-pt cal-move parse-time org-clock
char-fold misearch multi-isearch iso-transl tramp-cache tramp-sh recentf
tree-widget ido cal-iso solar cal-dst cal-julian appt org-eldoc
org-bullets flyspell org-depend org-w3m org-rmail org-mhe org-irc
org-info org-id org-gnus org-docview doc-view subr-x jka-compr
image-mode org-bibtex bibtex org-bbdb org-element avl-tree J-org
diary-lib diary-loaddefs orgtbl-show-header org-table org-protocol
org-mobile org-agenda org-expiry filenotify org org-macro org-footnote
org-pcomplete org-list org-faces org-entities noutline outline
org-version ob-emacs-lisp ob ob-tangle org-src ob-ref ob-lob ob-table
ob-keys ob-exp ob-comint ob-core ob-eval org-compat org-macs
org-loaddefs find-func mm-archive message rfc822 mml mml-sec mailabbrev
gmm-utils mailheader mm-decode mm-bodies mm-encode url-handlers
mail-utils network-stream nsm starttls url-http tls gnutls mail-parse
rfc2231 rfc2047 rfc2045 ietf-drums url-gw url-cache url-auth epg winner
helm-command helm-elisp helm-eval edebug rainbow-delimiters
column-enforce-mode cl ispell edit-server-htmlize html2text cus-edit
wid-edit helm-descbinds helm-mode helm-files rx tramp tramp-compat
tramp-loaddefs trampver ucs-normalize shell pcomplete ffap thingatpt
helm-buffers helm-elscreen helm-tags helm-bookmark helm-adaptive
helm-info bookmark pp helm-locate helm-grep helm-regexp helm-external
helm-net browse-url xml url url-proxy url-privacy url-expand url-methods
url-history url-cookie url-domsuf url-util url-parse auth-source
gnus-util mm-util help-fns mail-prsvr password-cache url-vars mailcap
helm-utils compile comint ansi-color ring helm-help helm-types helm
derived helm-source eieio-compat eieio eieio-core helm-multi-match
helm-lib cl-seq helm-config helm-easymenu edmacro kmacro cl-macs
async-bytecomp async J-bc window-numbering edit-server
solarized-light-theme solarized color dash easy-mmode advice dired+
image-dired format-spec image-file dired-aux dired-x dired finder-inf
info package epg-config seq byte-opt gv bytecomp byte-compile cl-extra
help-mode cconv cl-loaddefs pcase cl-lib disp-table paren whitespace
cus-start cus-load holidays hol-loaddefs cal-menu easymenu calendar
cal-loaddefs J-local server time-date mule-util tooltip eldoc electric
uniquify ediff-hook vc-hooks lisp-float-type mwheel x-win
term/common-win x-dnd tool-bar dnd fontset image regexp-opt fringe
tabulated-list newcomment elisp-mode lisp-mode prog-mode register page
menu-bar rfn-eshadow timer select scroll-bar mouse jit-lock font-lock
syntax facemenu font-core frame cl-generic cham georgian utf-8-lang
misc-lang vietnamese tibetan thai tai-viet lao korean japanese eucjp-ms
cp51932 hebrew greek romanian slovak czech european ethiopic indian
cyrillic chinese charscript case-table epa-hook jka-cmpr-hook help
simple abbrev minibuffer cl-preloaded nadvice loaddefs button faces
cus-face macroexp files text-properties overlay sha1 md5 base64 format
env code-pages mule custom widget hashtable-print-readable backquote
dbusbind inotify dynamic-setting system-font-setting font-render-setting
move-toolbar gtk x-toolkit x multi-tty make-network-process emacs)

Memory information:
((conses 16 2655637 322584)
 (symbols 48 67629 10)
 (miscs 40 15820 16990)
 (strings 32 286913 56350)
 (string-bytes 1 9933897)
 (vectors 16 87909)
 (vector-slots 8 2268496 189885)
 (floats 8 1374 1152)
 (intervals 56 378977 14831)
 (buffers 976 124)
 (heap 1024 185650 16507))

-- 
• 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/

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.

bug#24890: 25.1; Several documentation problems

[Drew Adams]

Thanks, to both of you, for working on this!

bug#24890: 25.1; Several documentation problems

[Jorge Morais Neto]

Sorry I took this long to reply.

On 7 November 2016 at 15:56, Eli Zaretskii <eliz@gnu.org> wrote:
>> From: Jorge Morais Neto <jorge13515@gmail.com>
> 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/

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.

bug#24890: 25.1; Several documentation problems

[Jorge Morais Neto]

On 10 November 2016 at 14:26, Eli Zaretskii <eliz@gnu.org> wrote:
>> From: Jorge Morais Neto <jorge13515@gmail.com>
>> Date: Thu, 10 Nov 2016 12:36:58 -0200
>> Cc: 24890@debbugs.gnu.org
>> 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.
>> [...]
>
> 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?

I parse that excerpt as "Hide (everything but the top LEVELS levels of
headers)", with parenthesis used for grouping as in Mathematics.  But
in an outline buffer, "everything but the top LEVELS levels of
headers" means "headers of level > LEVELS and all bodies".  Therefore
I interpret the excerpt as "hide (headers of level > LEVELS and all
bodies)", with no action for headers of level ≤ LEVELS. Thus if a
header of level ≤ LEVELS started hidden, in principle it would stay
hidden.  Perhaps I am just misunderstanding English.  My native and
primary language is Portuguese.  If you think the current wording is
clear then we can leave it as is.

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

-- 
• 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/

bug#24890: 25.1; Several documentation problems

[Eli Zaretskii]

> From: Jorge Morais Neto <jorge13515@gmail.com>
> Date: Thu, 10 Nov 2016 16:10:19 -0200
> Cc: 24890-done@debbugs.gnu.org
> 
> On 10 November 2016 at 14:26, Eli Zaretskii <eliz@gnu.org> wrote:
> >> From: Jorge Morais Neto <jorge13515@gmail.com>
> >> Date: Thu, 10 Nov 2016 12:36:58 -0200
> >> Cc: 24890@debbugs.gnu.org
> >> 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.
> >> [...]
> >
> > 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?
> 
> I parse that excerpt as "Hide (everything but the top LEVELS levels of
> headers)", with parenthesis used for grouping as in Mathematics.  But
> in an outline buffer, "everything but the top LEVELS levels of
> headers" means "headers of level > LEVELS and all bodies".  Therefore
> I interpret the excerpt as "hide (headers of level > LEVELS and all
> bodies)", with no action for headers of level ≤ LEVELS. Thus if a
> header of level ≤ LEVELS started hidden, in principle it would stay
> hidden.  Perhaps I am just misunderstanding English.  My native and
> primary language is Portuguese.  If you think the current wording is
> clear then we can leave it as is.

Yes, I think it's clear.

bug#24890: 25.1; Several documentation problems

[Jorge Morais Neto]

On 7 November 2016 at 15:56, Eli Zaretskii <eliz@gnu.org> wrote:
>> From: Jorge Morais Neto <jorge13515@gmail.com>
>>    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.
Thank you.  Could you also update [[info:emacs#Foldout]]?  It still mentions
obsolete aliases.

-- 
• 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/

bug#24890: 25.1; Several documentation problems

[Eli Zaretskii]

> From: Jorge Morais Neto <jorge13515@gmail.com>
> Date: Sat, 12 Nov 2016 17:02:40 -0200
> Cc: 24890@debbugs.gnu.org
> 
> On 7 November 2016 at 15:56, Eli Zaretskii <eliz@gnu.org> wrote:
> >> From: Jorge Morais Neto <jorge13515@gmail.com>
> >>    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.
> Thank you.  Could you also update [[info:emacs#Foldout]]?  It still mentions
> obsolete aliases.

Done.