Re: [Patch] Adding examples to the man pages

[Paul Eggert]

James Youngman <address@hidden> writes:

> Jim, Paul, it might be useful at this point to give Dave some
> feedback, to let him know if he should continue to work on examples or
> whether he's been wasting his time.

Jim has the final say, of course; we should let him weigh in.

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.