Re: Documentation for Outline mode's hide-leaves is unclear

[Richard M. Stallman]

The message below points out a conflict between the code of
hide-leaves and most of its documentaion.  We need to change one or
the other.

It is easy to change hide-leaves to do what the manual says.
But it's clear that the code was intentionally written
to do what it does, and the command's doc string accords
with the code.  Since I don't use Outline mode, I don't
have a basis to judge which change is better.

Do others here who really use Outline mode have a preference,
or an argument, for what is right here?

From: "Otto Maddox" <address@hidden>
To: address@hidden
Date: Tue, 22 Nov 2005 21:41:13 +0000
Subject: Documentation for Outline mode's hide-leaves is unclear

In GNU Emacs 22.0.50.1 (powerpc-apple-darwin8.3.0)
 of 2005-11-22

Say the following text is in a buffer in Outline mode (copied from the
Emacs manual):

* Food
This is the body,
which says something about the topic of food.

** Delicious Food
This is the body of the second-level header.

** Distasteful Food
This could have
a body too, with
several lines.

*** Dormitory Food

* Shelter
Another first-level topic with its header line.

Then, interactively, put point on the "* Food" header and type
`C-c C-l'.

Only the bodies of the subheadings are made invisible.  The body of
the top heading stays visible.  But in (emacs) Outline Visibility,
this is written:

`C-c C-l'
     Make the body of the current heading line, and of all its
     subheadings, invisible (`hide-leaves').

which implies that the "* Food" body should be made invisible.  So the
documentation and the behaviour clash.

Furthermore, with respect to the command name (`hide-leaves'), it is a
bit unclear what exactly a leaf is.  But the most consistent
interpretation seems to be that a leaf is a body.  In which case, the
command name also seems to imply the same thing the documentation
does.

-- 
http://www.fastmail.fm - Accessible with your email software
                          or over the web