Hi Filipus, Filipus Klutiero wrote: > Right. It could be > > cp [-R|-a|-r] [OPTION]... FILE... DIRECTORY > cp [OPTION]... REGULAR-FILE... DIRECTORY > > But then, there are more file types than regular files and > directories, so that probably wouldn't be perfect.
I think keeping it generic with simply SOURCE or FILE is better.
(Noting that directories are files too.)
The behavior of cp on whatever source file is going to be whatever is
allowed on the original file. Whether that is a "regular" file, a
pipe, a character device, a block device or whatever. Directories are
the most special because you can't open(2) them. (And the same for
unix domain sockets.)
If cp can open the file then it will read the contents then it will
write the contents out. Trying to individually document what happens
with various input files types means that if the kernel adds a new
type of file that the cp documentation is immediately out of date.
Better to avoid that and simply say it copies from the source file to
the destination.
Whatever the source file type I expect that if the kernel allows me to
open the file and read it then I expect cp to do so and to read the
source file and to copy it to the destination file. Whether this is
successful completely depends upon the file type and the kernel and
not cp.
> I didn't mean to blame the synopsis, it was just part of the
> relevant part of the manpage. The problematic parts are the NAME
> section ("copy files*and directories*") and the description "Copy
> SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY."
Hmm... Interesting. So if it didn't say "and directories" it would
be better? I note that BSD and SunOS don't say that. But HP-UX
does. And the old V7 just said "copy" and nothing more. I think the
addition are trying to make things better but perhaps they do say too
much.
> >The challenge for the 'cp --help' online documentation is to keep them
> >short and concise yet accurately display the required information.
> >This is then turned into the man page.
>
> I understand the resources challenge. Sometimes vagueness is the
> only solution.
Yep!
> In the end, we know that most people will use the manpage. cp's
> manpage may be incomplete or vague, but it can't afford to mislead
> readers on a behavior as fundamental as the treatment of
> directories.
But if "and directories" doesn't appear in the synopsis then it won't
appear in an apropos ('man -k') keyword search. And 'cp' will copy
directories with the right options. However the "kitchen sink" of
file copying tools is 'rsync'. 'rsync' never met an option that it
couldn't incorporate! The rsync synopsis doesn't mention directories
so that must be okay. Maybe the "and directories" should simply be
dropped.
> >Note here is the POSIX online documentation on the cp command.
> >
> > http://pubs.opengroup.org/onlinepubs/009695399/utilities/cp.html
>
> Thanks, this is very interesting. First, the NAME just says "copy
> files" rather than "copy files and directories". Some may equate
> "copy files" with "copy all files", but I do not consider the POSIX
> NAME misleading.
V7 just says "copy". BSD says "copy files". HP-UX says "copy file
and directory subtrees".
> Then, the synopsis treats -R as a different form, as you
> discussed. This has the advantage of allowing a separate description
> for the 2 forms.
There can always be description even with one synopsis.
> I have no strong opinion on which approach is preferable. Either 2
> forms and 2 descriptions or keeping 1 form with a different
> description. As long as 1 - we don't say that cp copies SOURCE to
> DEST, when SOURCE can't be a directory without options, or 2 - we
> add right after a big warning about directories like the info
> documentation's.
I think it would be defendable to request upstream to change to:
-Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY.\n\
+Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY,\n\
+or optionally recursively directory SOURCES(s) to DIRECTORY.\n\
Bob
signature.asc
Description: Digital signature
