Re: [Patch] Adding examples to the man pages

[Jim Meyering]

Paul Eggert <address@hidden> wrote:
> 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.

I'd be happy to see more examples, but would be even happier
if they could be added in a way that would minimize the associated
maintenance burden.  That means I agree with Paul: it's better to
avoid putting examples in the man/*.x files.

It's probably too much to ask, but supposing these new examples
all end up both in --help output and in coreutils.texi, it'd sure
be nice if there were a way to keep the two sets in sync.
Ideally, we'd generate one from the other or both from some third
source.  Please keep this in mind.