bug#29315: info cp: documentation feedback

[kalle]

I already sent this mail on 19.05.2018, but since I got no response and
my bug-report then had be closed and I just unarchived and reopened it,
here again my message.

> Am 10.12.2017 um 01:23 schrieb Pádraig Brady:
>> On 16/11/17 03:36, kalle wrote:

>> here some mistakes/improvement proposals to `info cp' from me:

>> -sentence "If the `--target": take away "failing that"?
> 
> It's better as is, to document that these are separate modes

I simply don't understand the sentence. what is meant by
"If the ‘--target-directory’ (‘-t’) option is given, or failing that
if the last file is a directory and the ‘--no-target-directory’
(‘-T’) option is not given " ?

-the sentence "just as they are read" sounds ambiguous using the words
"just as", since it is not clear if it refers to a time point or to an
operating mode..
That it is not about a time point becomes clear from the reference to
the 'sparse'-option, but it shouldn't be necessary to read information
about the sparse-option first to understand this sentence.


-option "sparse": I don't really understand the explanation - do the
'holes' neither contain any physical device blocks nor any space at all?
Then - how is this possible How can a series of zero bytes not occupy
any physical disk  blocks?



>> -sentence "descending into source directories": shouldn't it be rather
>> "descending into SOURCE's directories"?
> 
> That could be interpreted as only descending one level
I don't understand why only the first level of subdirectories could be
meant, but that point is not so important to me.

> 
>> And since `-r' and `-R' is the
>> same: write "-r/-R" instead.
> 
> That would be less standard/searchable
what I meant was, to write "-r/-R" in the sentence "to copy recursively
by descending".

> 
>> -option `-f': why is it written about _opening_ a file, e.g. "opened for
>> writing" and not simply "writeable"?
> 
> There can be differing restrictions on various operations,
> so we're being explicit about the truncation permission.
maybe one could add a specific, more common example of such a
restriction situation  or refer to further explanation such that the
terminology (writing a file) seems not too alienating, as it was to me.

kalle