Re: [Patch] Adding examples to the man pages

[Jim Meyering]

Paul Eggert <address@hidden> wrote:
> "Dr. David Alan Gilbert" <address@hidden> writes:
>
>> OK, here is a handful of stuff against the CVS checkout.
>> Is this OK?
...
> The examples need to be written up in doc/coreutils.texi as well.
> Jim, do you think they should be before or after the exit-status
> documentation?  The patch below puts it before (since "ln invocation"
> already does this), but after might make sense too.

I could go either way when the single sentence of exit-status
documentation is all that follows the option descriptions.
But when there's more than that one sentence, I have a slight
preference for putting the examples at the end.

Of course, if there are many examples, it might
make sense to put them in their own section.

> Here is a proposed patch illustrating the sort of format I was
> thinking of.  Jim, is this worth installing as-is as an "example of
> how to do examples", or...

Yes.  Please do.
Thanks for working on this.

> 2005-04-03  Paul Eggert  <address@hidden>
>
>       * doc/coreutils.texi (cat invocation, chown invocation)
>       (chgrp invocation, basename invocation, dirname invocation):
>       Add examples.
>       (ln invocation): Use same format as other examples above,
>       for consistency.
>       * man/Makefile.am (.x.1): Remove "COMMAND.td/" from examples.
>       * src/basename.c (usage): Add examples.
>       * src/cat.c (usage): Likewise.
>       * src/chgrp.c (usage): Likewise.
>       * src/chown.c (usage): Likewise.
>       * src/dirname.c (usage): Likewise.