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.