`k' in Dired with inserted subdirectories.

`k' in Dired with inserted subdirectories.

[Luc Teirlinck]

As I pointed out in a prior message in this thread (quite a while
ago),  the documentation of `dired-do-kill-lines' in the docstring and
the Emacs manual contradict each other and _both_ are wrong.
Moreover, `dired-do-kill-lines' contains code that never gets
executed.  Of course, it is strictly speaking not necessary to remove
that code.  Since it never gets executed it never does any harm.  But
it is confusing to anybody reading the source code.

The patches below to dired-aux and man/dired.texi correct both problems.

The reason I replaced:

! \(A negative argument kills lines before the current line.)

with:

! \(A negative argument kills backward.)

in `dired-do-kill-lines's docstring is that to me, the original
sentence does not make clear whether the line itself is included (it is).

I can install if it looks OK.

===File ~/dired-aux-diff====================================
*** dired-aux.el	14 Jun 2004 22:05:32 -0500	1.124
--- dired-aux.el	13 Jul 2004 14:22:28 -0500	
***************
*** 627,635 ****
  (defun dired-do-kill-lines (&optional arg fmt)
    "Kill all marked lines (not the files).
  With a prefix argument, kill that many lines starting with the current line.
! \(A negative argument kills lines before the current line.)
! To kill an entire subdirectory, go to its directory header line
! and use this command with a prefix argument (the value does not matter)."
    ;; Returns count of killed lines.  FMT="" suppresses message.
    (interactive "P")
    (if arg
--- 627,640 ----
  (defun dired-do-kill-lines (&optional arg fmt)
    "Kill all marked lines (not the files).
  With a prefix argument, kill that many lines starting with the current line.
! \(A negative argument kills backward.)
! If a prefix argument is given and you kill the line for a file
! that is a directory, which is inserted in the Dired buffer as
! a subdirectory, then that subdirectory is deleted 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)."
    ;; Returns count of killed lines.  FMT="" suppresses message.
    (interactive "P")
    (if arg
***************
*** 638,660 ****
  	(dired-kill-line arg))
      (save-excursion
        (goto-char (point-min))
!       (let (buffer-read-only (count 0))
! 	(if (not arg)			; kill marked lines
! 	    (let ((regexp (dired-marker-regexp)))
! 	      (while (and (not (eobp))
! 			  (re-search-forward regexp nil t))
! 		(setq count (1+ count))
! 		(delete-region (progn (beginning-of-line) (point))
! 			       (progn (forward-line 1) (point)))))
! 	  ;; else kill unmarked lines
! 	  (while (not (eobp))
! 	    (if (or (dired-between-files)
! 		    (not (looking-at "^  ")))
! 		(forward-line 1)
! 	      (setq count (1+ count))
! 	      (delete-region (point) (save-excursion
! 				       (forward-line 1)
! 				       (point))))))
  	(or (equal "" fmt)
  	    (message (or fmt "Killed %d line%s.") count (dired-plural-s count)))
  	count))))
--- 643,656 ----
  	(dired-kill-line arg))
      (save-excursion
        (goto-char (point-min))
!       (let (buffer-read-only
! 	    (count 0)
! 	    (regexp (dired-marker-regexp)))
! 	(while (and (not (eobp))
! 		    (re-search-forward regexp nil t))
! 	  (setq count (1+ count))
! 	  (delete-region (progn (beginning-of-line) (point))
! 			 (progn (forward-line 1) (point))))
  	(or (equal "" fmt)
  	    (message (or fmt "Killed %d line%s.") count (dired-plural-s count)))
  	count))))
============================================================

===File ~/dired.texi-diff===================================
*** dired.texi	14 Jun 2004 14:51:51 -0500	1.29
--- dired.texi	13 Jul 2004 12:46:51 -0500	
***************
*** 1030,1039 ****
  files, or on the marked files if any; but it does not operate on the
  current file as a last resort.
  
!   If you kill the line for a file that is a directory, the directory's
! contents are also deleted from the buffer.  Typing @kbd{C-u k} on the
! header line for a subdirectory is another way to delete a subdirectory
! from the Dired buffer.
  
    The @kbd{g} command brings back any individual lines that you have
  killed in this way, but not subdirectories---you must use @kbd{i} to
--- 1030,1040 ----
  files, or on the marked files if any; but it does not operate on the
  current file as a last resort.
  
!   If a numeric prefix argument is given and you kill the line for a
! file that is a directory, the directory's contents are also deleted
! from the buffer.  Typing @kbd{C-u k} on the header line for a
! subdirectory is another way to delete a subdirectory from the Dired
! buffer.
  
    The @kbd{g} command brings back any individual lines that you have
  killed in this way, but not subdirectories---you must use @kbd{i} to
============================================================

Re: `k' in Dired with inserted subdirectories.

[Luc Teirlinck]

I believe that the following patch to man/dired.texi is better than the
original:

===File ~/dired.texi-diff-2=================================
*** dired.texi	14 Jun 2004 14:51:51 -0500	1.29
--- dired.texi	13 Jul 2004 15:01:18 -0500	
***************
*** 1030,1039 ****
  files, or on the marked files if any; but it does not operate on the
  current file as a last resort.
  
!   If you kill the line for a file that is a directory, the directory's
! contents are also deleted from the buffer.  Typing @kbd{C-u k} on the
! header line for a subdirectory is another way to delete a subdirectory
! from the Dired buffer.
  
    The @kbd{g} command brings back any individual lines that you have
  killed in this way, but not subdirectories---you must use @kbd{i} to
--- 1030,1040 ----
  files, or on the marked files if any; but it does not operate on the
  current file as a last resort.
  
!   If you kill the line for a file that is a directory using @kbd{k}
! with a numeric prefix argument, the directory's contents are also
! deleted from the buffer.  Typing @kbd{C-u k} on the header line for a
! subdirectory is another way to delete a subdirectory from the Dired
! buffer.
  
    The @kbd{g} command brings back any individual lines that you have
  killed in this way, but not subdirectories---you must use @kbd{i} to
============================================================

Re: `k' in Dired with inserted subdirectories.

[Luc Teirlinck]

>From my previous patch to the `dired-do-kill-lines' docstring:

! If a prefix argument is given and you kill the line for a file
! that is a directory, which is inserted in the Dired buffer as
! a subdirectory, then that subdirectory is deleted from the buffer
! as well.

Maybe here:

   If you use a prefix argument and kill the line for a file that is
   a directory, which is inserted in the Dired buffer as a subdirectory,
   then this function deletes that subdirectory from the buffer as well.

is better.

Sincerely,

Luc.

Re: `k' in Dired with inserted subdirectories.

[Richard Stallman]

    ! If a prefix argument is given and you kill the line for a file
    ! that is a directory, which is inserted in the Dired buffer as
    ! a subdirectory, then that subdirectory is deleted from the buffer
    ! as well.

This uses the passive voice three times, which makes it hard to read.
Let's always try to avoid the passive voice in documentation.
Here's how I'd rewrite it.  Using the active voice makes it shorter
as well as easier to read.

      If you use this command with a prefix argument to kill the line for a
      subdirectory, and you've dispayed the subdirectory contents in the buffer
      with \\[dired-insert-subdir], it kills the subdirectory's lines too.

"with \\[dired-insert-subdir]" is a more precise and clear way to identify
the case in question than any description could be.

    !   If a numeric prefix argument is given and you kill the line for a
    ! file that is a directory, the directory's contents are also deleted
    ! from the buffer.  Typing @kbd{C-u k} on the header line for a
    ! subdirectory is another way to delete a subdirectory from the Dired
    ! buffer.

The first sentence there is passive too.

    !   If you kill the line for a file that is a directory using @kbd{k}
    ! with a numeric prefix argument, the directory's contents are also
    ! deleted from the buffer.  Typing @kbd{C-u k} on the header line for a
    ! subdirectory is another way to delete a subdirectory from the Dired
    ! buffer.

That's an improvement, but the end of the first sentence is still
passive.

       If you use a prefix argument and kill the line for a file that is
       a directory, which is inserted in the Dired buffer as a subdirectory,
       then this function deletes that subdirectory from the buffer as well.

This avoids the passive.  If we combine the tail end of this
with the rest from the previous example, we get a good text:

    !   If you kill the line for a file that is a directory using
    ! @kbd{k} with a numeric prefix argument, this function deletes
    ! that subdirectory from the buffer as well.  Typing @kbd{C-u k}
    ! on the header line for a subdirectory is another way to delete a
    ! subdirectory from the Dired buffer.

Re: `k' in Dired with inserted subdirectories.

[Luc Teirlinck]

Richard Stallman wrote:

	 If you use this command with a prefix argument to kill the
	 line for a subdirectory, and you've dispayed the subdirectory
	 contents in the buffer with \\[dired-insert-subdir], it kills
	 the subdirectory's lines too.

   "with \\[dired-insert-subdir]" is a more precise and clear way to identify
   the case in question than any description could be.

(This concerns the `dired-do-kill-lines' docstring.)

I have two problems with the above:

"the line for a subdirectory" could be misunderstood as the
subdirectory header line and "\\[dired-insert-subdir]" is going to
come out as `M-x dired-insert-subdir', unless C-h f was issued from a
Dired buffer.  This might look cryptic to non-Elisp users, thinking of
this as `i'.  \\<dired-mode-map>\\[dired-insert-subdir] is going to
come out worse if dired is not yet loaded.

What about:

If you use this command with a prefix argument to kill the line for
a file that is a directory, which the Dired buffer also displays as
a subdirectory, then it deletes that subdirectory from the buffer
as well.

Re: `k' in Dired with inserted subdirectories.

[Richard Stallman]

    If you use this command with a prefix argument to kill the line for
    a file that is a directory, which the Dired buffer also displays as
    a subdirectory, then it deletes that subdirectory from the buffer
    as well.

That is ok except that the middle clause is clumsy.  How about this?

    If you use this command with a prefix argument to kill the line
    for a file that is a subdirectory, and you've displayed the
    subdirectory's contents in the Dired buffer with
    \\<dired-mode-map>\\[dired-insert-subdir], it deletes that
    subdirectory from the buffer as well.

I was thinking only about using this in Dired mode, but now that you
mention the issue, I am not sure whether it is better to use
\\<dired-mode-map>.  When you're not in Dired mode, i won't do this.
Maybe it is clearer to say M-x dired-insert-subdir in that case.  I am
not sure.


Thanks for working on this.

Re: `k' in Dired with inserted subdirectories.

[Luc Teirlinck]

Richard Stallman wrote:

       If you use this command with a prefix argument to kill the line
       for a file that is a subdirectory, and you've displayed the
       subdirectory's contents in the Dired buffer with
       \\<dired-mode-map>\\[dired-insert-subdir], it deletes that
       subdirectory from the buffer as well.

Apart from the problems I already mentioned before, this makes it
sound like it makes a difference whether you inserted them with `i'
or with the "R" switch, whereas it does not make any difference how
you inserted them.  The name "subdirectory" is used in several
docstrings in Dired as implicitly meaning "inserted subdirectory".
What about:

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.

Re: `k' in Dired with inserted subdirectories.

[Richard Stallman]

    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.

That is good.  Thanks.

Re: `k' in Dired with inserted subdirectories.

[Luc Teirlinck]

Richard Stallman wrote:

   This avoids the passive.  If we combine the tail end of this
   with the rest from the previous example, we get a good text:

       !   If you kill the line for a file that is a directory using
       ! @kbd{k} with a numeric prefix argument, this function deletes
       ! that subdirectory from the buffer as well.  Typing @kbd{C-u k}
       ! on the header line for a subdirectory is another way to delete a
       ! subdirectory from the Dired buffer.

"that subdirectory" sounds somewhat confusing, because most
directories are not inserted in the Dired buffer as subdirectories.

What about:

  If you use @kbd{k} with a numeric prefix argument to kill the line
for a file that is a directory, which the Dired buffer also displays
as a subdirectory, then this deletes that subdirectory from the buffer
as well.  Typing @kbd{C-u k} on the header line for a subdirectory is
another way to delete a subdirectory from the Dired buffer.

`k' in Dired with inserted subdirectories.

[Luc Teirlinck]

There are inconsistencies regarding the behavior of `k' for subdirectories.
Also, `dired-do-kill-lines' contains several lines of code that can
_never_ be executed.

First problem:

Doc string:

  To kill an entire subdirectory, go to its directory header line and
  use this command with a prefix argument (the value does not matter).

No other way to kill a subdirectory is mentioned.

Emacs manual:

     If you kill the line for a file that is a directory, the directory's
  contents are also deleted from the buffer.  Typing `C-u k' on the
  header line for a subdirectory is another way to delete a subdirectory
  from the Dired buffer.

The fact that C-u k on a subdirectory header line kills that
subdirectory is uncontested.  But what for `k' on a line for a file
that is a directory (but _not_ a directory header line)?

Actual behavior:

If a numeric prefix argument is used and if the directory is inserted in
the buffer, it _is_ removed.  But if marks are used, it is _not_ removed.
What _should_ the behavior be?  Or is the current behavior for some
reason OK, but just not correctly documented?

Second problem with `dired-do-kill-lines':

There is some code in `dired-do-kill-lines' that attempts to delete
all lines that are _not_ marked if a numeric prefix argument is given.
This conflicts with the standard meaning of a numeric prefix argument
in Dired, which `dired-do-kill-lines' _also_ implements.  As a result the
`delete-if-not-marked' with numeric prefix argument code will _never_ be
executed.  So why is it there?  It will never cause bugs, but it is
confusing:

  (if arg
      (if (dired-get-subdir)
        (dired-kill-subdir)
	(dired-kill-line arg))
    ;; Pesonal remark: arg is nil now.
    (save-excursion
      (goto-char (point-min))
      (let (buffer-read-only (count 0))
      ;; Personal remark:  This is equivalent with:
      ;; (if t                          ; kill marked lies
      (if (not arg)			; kill marked lines
 

   ;; else kill unmarked lines
   ;; Personal remark: who cares, `else' _never_ happens.
     (while (not (eobp))         

Sincerely,

Luc.