bug#11809: document "So how do we just simply make a backup file?"

[Jim Meyering]

Jim Meyering wrote:
> Bernhard Voelker wrote:
>> On 06/29/2012 10:48 AM, Jim Meyering wrote:
>>> Here's the doc patch I suggested, but I'll hold off for now.
>>> I'd like to hear if anyone thinks it's worth adding a new option,
>>> which would obviate such a script.
>>
>> I think it's okay, that special backup case is described in the info
>> page of cp twice anyway.
>>
>>> diff --git a/doc/coreutils.texi b/doc/coreutils.texi
>>> index 08ef2d8..5207c44 100644
>>> --- a/doc/coreutils.texi
>>> +++ b/doc/coreutils.texi
>>> @@ -7675,9 +7675,11 @@ cp invocation
>>>  #!/bin/sh
>>>  # Usage: backup FILE...
>>>  # Create a @sc{gnu}-style backup of each listed FILE.
>>> +fail=0
>>>  for i; do
>>> -  cp --backup --force -- "$i" "$i"
>>> +  cp --backup --force -- "$i" "$i" || fail=1
>>>  done
>>> +exit $fail
>>>  @end example
>>>
>>>  @item --copy-contents
>>
>> When we speak of "backup", then maybe "--preserve=all" would be nice.
>>
>> BTW: that special backup case accepts -a which includes both -d and -R
>> which both are maybe not ideal if you speak about a backup of a regular
>> file. The former treats symlinks specially, and the latter is designed
>> to recurse into directories - both may be misleading (although -d may
>> make some sense in certain situation when creating a backup of a
>> symlink). WDYT?
>
> Adding --preserve=all sounds like a good idea.
> Thanks.
>
> Allowing this little script to work also for non-regular files
> seems like it'd be useful, too.  But it's beginning to look as if
> this combination of options is both useful and involved enough that
> the functionality should be provided by a new --only-backup option.

I went ahead and pushed this:

>From 5f6c22fceedd0d350e1a8246d4d73840de666c7e Mon Sep 17 00:00:00 2001
From: Jim Meyering <address@hidden>
Date: Fri, 29 Jun 2012 10:45:31 +0200
Subject: [PATCH] doc: improve sample backup script

* doc/coreutils.texi (cp invocation): Make the backup script exit
with an accurate reflection of any failure.
Also, add --preserve=all.

Improved-by: Bernhard Voelker
---
 doc/coreutils.texi | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 08ef2d8..954a1f8 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -7675,9 +7675,11 @@ cp invocation
 #!/bin/sh
 # Usage: backup FILE...
 # Create a @sc{gnu}-style backup of each listed FILE.
+fail=0
 for i; do
-  cp --backup --force -- "$i" "$i"
+  cp --backup --force --preserve=all -- "$i" "$i" || fail=1
 done
+exit $fail
 @end example

 @item --copy-contents
--
1.7.11.1.104.ge7b44f1