Re: [Patch] Adding examples to the man pages

[Dave Gilbert (Home)]

Paul Eggert wrote:
> James Youngman <address@hidden> writes:

> 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.

Hmm - if you can suggest a good way to do this then I'd be happy to
write the examples in any reasonable way as long as they end up in 'man'
(as well as anywhere you want them).


> 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.

OK, although I'd like on some things to include the really useful GNU 
options; for example --sparse=always has saved my hide a few times 
recently on cp, and knowing that '-a' is probably the way you want
if you just want to make a safe copy of a directory.

Dave