node Subdirectories in Dired in Emacs manual

node Subdirectories in Dired in Emacs manual

[Drew Adams]

This text in the node is misleading or unintelligible:
 
  If the subdirectory's contents are already present in the
  buffer, the `i' command just moves to it.
 
I tried `i' everywhere in the buffer, and it did nothing of the
kind...except if the cursor is over the subdir line of the parent
directory. That needs to be said.
 

In GNU Emacs 22.1.1 (i386-mingw-nt5.1.2600)
 of 2007-06-02 on RELEASE
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --cflags -Ic:/gnuwin32/include'
 

Re: node Subdirectories in Dired in Emacs manual

[Andreas Schwab]

"Drew Adams" <drew.adams@oracle.com> writes:

> This text in the node is misleading or unintelligible:
>  
>   If the subdirectory's contents are already present in the
>   buffer, the `i' command just moves to it.
>  
> I tried `i' everywhere in the buffer, and it did nothing of the
> kind...except if the cursor is over the subdir line of the parent
> directory. That needs to be said.

That's exactly what the preceding paragraph says.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
PGP key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

RE: node Subdirectories in Dired in Emacs manual

[Drew Adams]

> > This text in the node is misleading or unintelligible:
> >  
> >   If the subdirectory's contents are already present in the
> >   buffer, the `i' command just moves to it.
> >  
> > I tried `i' everywhere in the buffer, and it did nothing of the
> > kind...except if the cursor is over the subdir line of the parent
> > directory. That needs to be said.
> 
> That's exactly what the preceding paragraph says.

Not at all. Hitting `i' *WHERE* just moves to *WHERE*? It says nothing about
where the cursor is when you hit `i', in order to have this effect. And even
the effect is unclear: "moves to it" is ambiguous - what is "it"? For that
matter, the "and moves there" of the previous paragraph is also unclear -
moves where? Inserts the directory "and moves *THERE*"? 

This is all poorly phrased. Perhaps you are handicapped by knowing the
behavior. Try reading it from the standpoint of someone who doesn't already
know what the behavior is. You'll see that the description given doesn't
help.

Re: node Subdirectories in Dired in Emacs manual

[Andreas Schwab]

"Drew Adams" <drew.adams@oracle.com> writes:

>> > This text in the node is misleading or unintelligible:
>> >  
>> >   If the subdirectory's contents are already present in the
>> >   buffer, the `i' command just moves to it.
>> >  
>> > I tried `i' everywhere in the buffer, and it did nothing of the
>> > kind...except if the cursor is over the subdir line of the parent
>> > directory. That needs to be said.
>> 
>> That's exactly what the preceding paragraph says.
>
> Not at all. Hitting `i' *WHERE*

"on a line that describes a file which is a directory"

> just moves to *WHERE*?

"the subdirectory's contents"

Just as the paragraph says.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
PGP key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

RE: node Subdirectories in Dired in Emacs manual

[Drew Adams]

> >> > This text in the node is misleading or unintelligible:
> >> >  
> >> >   If the subdirectory's contents are already present in the
> >> >   buffer, the `i' command just moves to it.
> >> >  
> >> > I tried `i' everywhere in the buffer, and it did nothing of the
> >> > kind...except if the cursor is over the subdir line of the parent
> >> > directory. That needs to be said.
> >> 
> >> That's exactly what the preceding paragraph says.
> >
> > Not at all. Hitting `i' *WHERE*
> 
> "on a line that describes a file which is a directory"

Which could also be interpreted to mean a subdir header line.

And the sentence "If the subdirectory's..." should not be in a separate
paragraph, especially if you expect someone to assume the same context (e.g.
location) for hitting `i'.

> > just moves to *WHERE*?
> 
> "the subdirectory's contents"

That's not a place. The English and the logic are bad.

> Just as the paragraph says.

You seem interested in justifying, rather than learning. 

Take it from a user: the text is not as clear as it should be. Or take it
from someone who has been writing, editing, and managing technical
documentation professionally for a couple decades. Or not - remain stubborn
and don't try to learn or improve. Your choice.