Confusing/unclear documentation of Sed back references

[Peter Kehl]

Dear GNU sed maintainers,

I believe that either Sed documentation is unclear, or its implementation
has a defect, regarding back references in -r mode.
https://www.gnu.org/software/sed/manual/sed.html#index-Backreferences_002c-in-regular-expressions-103
reads that the match has to be between \( and its matching \). However,
that only works if you don't use -r mode:

echo HELLO | sed  "s/\(HELLO\)/She said:\1/"
She said:HELLO

If you use -r, then
echo HELLO | sed *-r* "s/*\(*HELLO*\)*/She said:\1"
sed: -e expression #1, char 23: unterminated `s' command

The correct way with -r is to have the match between ( and ), not between
\( and \):
echo HELLO | sed *-r* "s/*(*HELLO*)*/She said:\1/"
She said:HELLO

That may be documented somewhere in your manual, but it's not documented at
the section above. This is highly confusing and counter-productive. Please
update the manual or fix the implementation.

*sed --version*
sed (GNU sed) 4.2.2
Copyright (C) 2012 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html
>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Written by Jay Fenlason, Tom Lord, Ken Pizzini,
and Paolo Bonzini.
GNU sed home page: <http://www.gnu.org/software/sed/>.
General help using GNU software: <http://www.gnu.org/gethelp/>.
E-mail bug reports to: <address@hidden>.
Be sure to include the word ``sed'' somewhere in the ``Subject:'' field.

*bash --version*
GNU bash, version 4.2.53(1)-release (x86_64-redhat-linux-gnu)
Copyright (C) 2011 Free Software Foundation, Inc.

*Fedora 20x64:*
uname -a
Linux localhost.localdomain 3.15.10-200.fc20.x86_64 #1 SMP Thu Aug 14
15:39:24 UTC 2014 x86_64 x86_64 x86_64 GNU/Linux

Best regards,

-Peter Kehl