My kneejerk reaction is that I like the idea of adding examples, but
I'd rather see them added to the output of "--help". That way, they'd
be put into the man pages automatically. We should also add them to
doc/coreutils.texi. That's maintaining two copies, but we already
have to do that.
As far as the examples themselves (independent of mechanics), my reaction to
<http://lists.gnu.org/archive/html/bug-coreutils/2005-03/txt8jnsvtOTux.txt>
is that they're a bit wordy and generic, and should be more concise and
specific. For example, for basename I'd prefer something like this:
EXAMPLES
"basename /usr/bin/sort" outputs "sort".
"basename /usr/include/stdio.h .h" outputs "stdio".
and for cat I'd prefer the following (as we shouldn't be encouraging
the use of any of cat's options):
EXAMPLE
"cat a.h - b.c" outputs the contents of a.h, then standard input, then b.c.