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

[Jim Meyering]

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?

> $ cp m n
> $ mv -b n m