Re: PR: dired-do-create-files now checks for trailing slashes in the target

[Eli Zaretskii]

> From: Rudi C <rudiwillalwaysloveyou@gmail.com>
> Date: Tue, 9 Nov 2021 16:22:59 +0330
> Cc: larsi@gnus.org, tsdh@gnu.org, stefankangas@gmail.com, emacs-devel@gnu.org
> 
> Okay, I have attached a new patch (no need for the previous patches).

Thanks.

> PS: I inserted newlines into the docstring to make the lines shorter, but 
> this makes the docstring ugly to view
> (as it is essentially hardwrapping based on an arbitrary column size that the 
> user's screen will not share). 

No, that's not TRT.  The first line of a doc string should be a
complete sentence, and it should be a summary of what the variable or
the function does.  That's because some Help commands display only
that first line to the user.  See below.

> +(defcustom dired-create-dirs-trailing-separator nil
> +  "If t, when selecting a single destination in Dired,
> +paths that end in a path separator will be treated as a non-existent 
> directory,
> +and acted on according to `dired-create-destination-dirs'.

Here, I'd rephrase:

    "If non-nil, create missing directories when copying or moving in Dired.
  If this variable is non-nil, and the destination of a move or a copy
  operation in Dired is a directory name, i.e. it ends in a slash, Dired
  will create the destination if it doesn't already exist, provided that
  `dired-create-destination-dirs' says so."

Additional comments:

  . we don't use "path" for anything except PATH-style directory
    lists; the GNU Coding Standards frown on using that to mean "file
    name" or "directory name"
  . instead of "path separator" (which could be confused with the
    colon which separates directories in PATH), use "slash" or
    "directory separator"

> +For example, when renaming a directory named `old_name' to `new_name/'
> +(note the trailing path separator), `new_name' might be created depending on

"path separator" again

> +`dired-create-destination-dirs' and `old_name' will be moved into it
> +if it is created; Otherwise `old_name' will be directly renamed to 
> `new_name'."

The "Otherwise" part should not be capitalized here.

> +  :type '(choice
> +          (const :tag
> +                 "Do not treat paths with a trailing path separator 
> specially" nil)
> +          (const :tag "Treat paths with a trailing path separator specially" 
> t))

Once again, "paths" used for file names.  Also, "treat specially" is a
riddle: it doesn't explain the effect of the setting.  I suggest the
following descriptions instead:

  "Create missing destination directories on copy/move."
  "Do not create missing destination directories."

OK?