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

[Jim Meyering]

Jim Meyering wrote:
> address@hidden wrote:
>> (info "(coreutils) Backup options") should add some examples, for
>> "So how do we make a backup file of m?"
>> $ ls
>> m
>> $ cp -b m m #no go
>
> Thanks for the suggestion.
> I use this zsh/bash shell function:
>
> backup ()
> {
>   local i
>   for i in "$@"; do
>     command cp -bf "$i" "$i"
>   done
> }
>
> but as I inserted the above, I realize it's buggy.
> It doesn't propagate failure like you'd expect,
> so here's a better one:
>
> backup()
> {
>   local i fail=0
>   for i in "$@"; do
>     command cp -bf -- "$i" "$i" || fail=1
>   done
>   return $fail
> }
>
> That's already almost what info coreutils says:
>
>   Make a backup of each file that would otherwise be overwritten or removed.
>   As a special case, @command{cp} makes a backup of @var{source} when the 
> force
>   and backup options are given and @var{source} and @var{dest} are the same
>   name for an existing, regular file.  One useful application of this
>   combination of options is this tiny Bourne shell script:
>
>   @example
>   #!/bin/sh
>   # Usage: backup FILE...
>   # Create a @sc{gnu}-style backup of each listed FILE.
>   for i; do
>     cp --backup --force -- "$i" "$i"
>   done
>   @end example
>
> I'll adjust that to reflect the above improvement:
> Do you think that's enough?

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.

>From 3a1bc89c3e3ca277be49d4fceb60abb57e3fc9d2 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.
---
 doc/coreutils.texi | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

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
--
1.7.11.1.59.gbc9e7dd