doc string of dired-do-kill-lines, "killing" lines in Dired

doc string of dired-do-kill-lines, "killing" lines in Dired

[Drew Adams]

1. The last two sentences seem redundant, to me:
 
 If you use this command with a prefix argument to kill the line
 for a file that is a directory, which you have inserted in the
 Dired buffer as a subdirectory, then it deletes that subdirectory
 from the buffer as well.
 To kill an entire subdirectory (without killing its line in the
 parent directory), go to its directory header line and use this
 command with a prefix argument (the value does not matter).
 
These sentences both seem to be saying only that `C-u k' on a subdir
header line deletes the subdir listing (all files). Just say that
(once).
 

2. Also, the text in that doc string and elsewhere regarding "killing"
lines in Dired should not speak of "killing" (even though this command
is misnamed this way). The kill-ring is not affected in any way,
AFAIK. For example: Emacs manual nodes Subdir Switches and Dired
Updating.
 

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: doc string of dired-do-kill-lines, "killing" lines in Dired

[Andreas Schwab]

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

> 1. The last two sentences seem redundant, to me:
>  
>  If you use this command with a prefix argument to kill the line
>  for a file that is a directory, which you have inserted in the
>  Dired buffer as a subdirectory, then it deletes that subdirectory
>  from the buffer as well.
>  To kill an entire subdirectory (without killing its line in the
                                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>  parent directory), go to its directory header line and use this
   ^^^^^^^^^^^^^^^^^
>  command with a prefix argument (the value does not matter).
>  
> These sentences both seem to be saying only that `C-u k' on a subdir
> header line deletes the subdir listing (all files). Just say that
> (once).

They are two different operations, the latter deleting one line less.

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: doc string of dired-do-kill-lines, "killing" lines in Dired

[Drew Adams]

> > 1. The last two sentences seem redundant, to me:
> >  
> >  If you use this command with a prefix argument to kill the line
> >  for a file that is a directory, which you have inserted in the
> >  Dired buffer as a subdirectory, then it deletes that subdirectory
> >  from the buffer as well.
> >  To kill an entire subdirectory (without killing its line in the
>                                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> >  parent directory), go to its directory header line and use this
>    ^^^^^^^^^^^^^^^^^
> >  command with a prefix argument (the value does not matter).
> >  
> > These sentences both seem to be saying only that `C-u k' on a subdir
> > header line deletes the subdir listing (all files). Just say that
> > (once).
> 
> They are two different operations, the latter deleting one line less.

This is unclear: "the line for a file that is a directory, which you have
inserted in the Dired buffer as a subdirectory". I thought that was trying
to refer to a subdir header line. Please rephrase the text to make the
difference clear.

Suggestion: start by using simple, short sentences.

Re: doc string of dired-do-kill-lines, "killing" lines in Dired

[Andreas Schwab]

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

>> > 1. The last two sentences seem redundant, to me:
>> >  
>> >  If you use this command with a prefix argument to kill the line
>> >  for a file that is a directory, which you have inserted in the
>> >  Dired buffer as a subdirectory, then it deletes that subdirectory
>> >  from the buffer as well.
>> >  To kill an entire subdirectory (without killing its line in the
>>                                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>> >  parent directory), go to its directory header line and use this
>>    ^^^^^^^^^^^^^^^^^
>> >  command with a prefix argument (the value does not matter).
>> >  
>> > These sentences both seem to be saying only that `C-u k' on a subdir
>> > header line deletes the subdir listing (all files). Just say that
>> > (once).
>> 
>> They are two different operations, the latter deleting one line less.
>
> This is unclear: "the line for a file that is a directory, which you have
> inserted in the Dired buffer as a subdirectory". I thought that was trying
> to refer to a subdir header line.

Where does it say "subdir header line"?

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: doc string of dired-do-kill-lines, "killing" lines in Dired

[Drew Adams]

> > This is unclear: "the line for a file that is a directory, 
> > which you have inserted in the Dired buffer as a subdirectory".
> > I thought that was trying to refer to a subdir header line.
> 
> Where does it say "subdir header line"?

Where does it say you just don't get it? If something can be misunderstood,
it will be. That's the burden of all technical communication. The text in
question is unnecessarily complex and unclear. It reads like an automatic
translation from some other language. Try starting with simple sentences -
that alone will help clear up ambiguous references.

I'm trying to help; you are being defensive. Did you write the text in
question, or what? Try reading it all again, with the fresh viewpoint of a
reader who is unfamiliar with the behavior. Or stay closed and (un)sure of
yourself - your choice.

Re: doc string of dired-do-kill-lines, "killing" lines in Dired

[Andreas Schwab]

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

>> > This is unclear: "the line for a file that is a directory, 
>> > which you have inserted in the Dired buffer as a subdirectory".
>> > I thought that was trying to refer to a subdir header line.
>> 
>> Where does it say "subdir header line"?
>
> Where does it say you just don't get it? If something can be misunderstood,
> it will be.

There are two ways to read documentation: trying to find the worst
possible interpretation and trying to find the best possible
interpretation.

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: doc string of dired-do-kill-lines, "killing" lines in Dired

[Drew Adams]

> > If something can be misunderstood, it will be.
> 
> There are two ways to read documentation: trying to find the worst
> possible interpretation and trying to find the best possible
> interpretation.

Yes, and the writer should always read it trying to find the worst possible
interpretation. That is the burden you need to assume, if you want to
communicate.

Why? Because that is how you improve communication. Progress comes through
contradiction.

If you as a writer read only what you intended to say, and not what you
actually wrote, with all of its reasonable possible interpretations, then
you are not putting yourself in the place of the reader. And you write _for
the reader_.

This is no different from writing code. The reader is your compiler or
interpreter: it is s?he who lets you know if what you wrote makes sense.

Re: doc string of dired-do-kill-lines, "killing" lines in Dired

[Richard Stallman]

    Where does it say you just don't get it? If something can be misunderstood,
    it will be. That's the burden of all technical communication. The text in
    question is unnecessarily complex and unclear. It reads like an automatic
    translation from some other language. Try starting with simple sentences -
    that alone will help clear up ambiguous references.

Making documentation clear is very important -- just being correct
is not enough.

Would you like to try rewriting that section to be clearer?

RE: doc string of dired-do-kill-lines, "killing" lines in Dired

[Drew Adams]

>     If something can be misunderstood, it will be.
>     That's the burden of all technical communication.
>     The text in question is unnecessarily
>     complex and unclear... Try starting with 
>     simple sentences - that alone will help clear up
>     ambiguous references.
> 
> Making documentation clear is very important -- just being correct
> is not enough.
> 
> Would you like to try rewriting that section to be clearer?

No. I explained what is unclear and how to make it clear. This time, I
prefer to teach how to fish than to dish out the fish & chips. (I don't mean
that I'm teaching you, Richard.)

Re: doc string of dired-do-kill-lines, "killing" lines in Dired

[Richard Stallman]

    No. I explained what is unclear and how to make it clear. This time, I
    prefer to teach how to fish than to dish out the fish & chips.

Are you claiming that it is in general more helpful just to report a
problem than to report it and fix it?

RE: doc string of dired-do-kill-lines, "killing" lines in Dired

[Drew Adams]

>     No. I explained what is unclear and how to make it clear. 
>     This time, I prefer to teach how to fish than to dish out
>     the fish & chips.
> 
> Are you claiming that it is in general more helpful just to report a
> problem than to report it and fix it?

Are you jumping wildly to presumptuous conclusions?

I claimed nothing in general. Or in particular, for that matter - I claimed
nothing at all. I said _this time_ (not in general) and I said _I prefer_. I
said nothing about being more helpful. I said nothing about why I prefer
that action this time.

However, wrt helpfulness and reporting problems: (1) Reporting a problem
(usually) _is_ helping. QA is an important part of production (of anything);
it shouldn't be undervalued. (2) In this case, I didn't just report the
problem. And I didn't just say "use this text instead" with no explanation.
I indicated what is wrong, why, and how to fix it.

And yes, if you're looking for a generality here, sometimes pointing out why
something is wrong and how to fix it is more help in the long run than just
fixing it. If only because the world is larger and lasts longer than any
individual contributor, all of whom are, alas, mortal. And, yes, there is
still a "sometimes" in that generality.

Explaining what is wrong and how to fix it can serve as an example that
helps to avoid and fix similar future problems. That is as true of
documentation as of coding or anything else.

Re: doc string of dired-do-kill-lines, "killing" lines in Dired

[Richard Stallman]

    And yes, if you're looking for a generality here, sometimes pointing out why
    something is wrong and how to fix it is more help in the long run than just
    fixing it.

The question is whether anyone actually wants to rewrite this
rather than just teach others how ;-).

RE: doc string of dired-do-kill-lines, "killing" lines in Dired

[Drew Adams]

>     And yes, if you're looking for a generality here, 
>     sometimes pointing out why something is wrong and how to
>     fix it is more help in the long run than just fixing it.
> 
> The question is whether anyone actually wants to rewrite this
> rather than just teach others how ;-).

The bigger question is whether a little learning can come about from the
discussion, to help doc quality generally. If so, good; if not, a little
time wasted all around perhaps.

It's not about one particular doc page. If nothing is done to improve that
page it is no worse off than before.