Re: [Patch] Adding examples to the man pages

[Paul Eggert]

"Dr. David Alan Gilbert" <address@hidden> writes:

> OK, here is a handful of stuff against the CVS checkout.
> Is this OK?

A few comments:

We need to have ChangeLog entries.

The programs should use program_name to generate their own names.
(This requires a tweak to man/Makefile.am as shown below.)

I'd scale back on the examples a bit.  I don't think users ordinarily
want to know what "basename functions.lisp p", "cat -s", or "chgrp
--reference" do.  And the comments can be made shorter without losing
utility.  Admittedly these are all judgment calls, but there is a
danger in having too many examples in what is supposed to be a fairly
terse reference.

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.

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 do you want some more changes to the format,
or do you want all the examples in one big patch?

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.

Index: doc/coreutils.texi
===================================================================
RCS file: /fetish/cu/doc/coreutils.texi,v
retrieving revision 1.246
diff -p -u -r1.246 coreutils.texi
--- doc/coreutils.texi  26 Mar 2005 18:43:30 -0000      1.246
+++ doc/coreutils.texi  4 Apr 2005 05:25:49 -0000
@@ -1309,6 +1309,16 @@ characters at the end of each line are a
 
 @end table
 
+Examples:
+
address@hidden
+# Output f's contents, then standard input, then g's contents.
+cat f - g
+
+# Copy standard input to standard output.
+cat
address@hidden smallexample
+
 @exitstatus
 
 
@@ -7703,9 +7713,14 @@ Print the name of each file before linki
 Examples:
 
 @smallexample
-ln -s /some/name  # creates link ./name pointing to /some/name
-ln -s /some/name myname  # creates link ./myname pointing to /some/name
-ln -s a b ..      # creates links ../a and ../b pointing to ./a and ./b
+# Create link ./name pointing to /some/name.
+ln -s /some/name
+
+# Create link ./myname pointing to /some/name.
+ln -s /some/name myname
+
+# Create links ../a and ../b pointing to ./a and ./b.
+ln -s a b ..
 @end smallexample
 
 @exitstatus
@@ -8264,6 +8279,19 @@ Recursively change ownership of director
 
 @end table
 
+Examples:
+
address@hidden
+# Change the owner of /u to "root".
+chown root /u
+
+# Likewise, but also change its group to "staff".
+chown root:staff /u
+
+# Change the owner of /u and subfiles to "root".
+chown -hR root /u
address@hidden smallexample
+
 @exitstatus
 
 
@@ -8372,6 +8400,16 @@ Recursively change the group ownership o
 
 @end table
 
+Examples:
+
address@hidden
+# Change the group of /u to "staff".
+chgrp staff /u
+
+# Change the group of /u and subfiles to "staff".
+chgrp -hR staff /u
address@hidden smallexample
+
 @exitstatus
 
 
@@ -10186,6 +10224,16 @@ result on standard output.
 The only options are @option{--help} and @option{--version}.  @xref{Common
 options}.  Options must precede operands.
 
+Examples:
+
address@hidden
+# Output "sort".
+basename /usr/bin/sort
+
+# Output "stdio".
+basename include/stdio.h .h
address@hidden smallexample
+
 @exitstatus
 
 
@@ -10210,6 +10258,16 @@ If @var{name} is a single component, @co
 The only options are @option{--help} and @option{--version}.  @xref{Common
 options}.
 
+Examples:
+
address@hidden
+# Output "/usr/bin".
+dirname /usr/bin/sort
+
+# Output ".".
+dirname stdio.h
address@hidden smallexample
+
 @exitstatus
 
 
Index: man/Makefile.am
===================================================================
RCS file: /fetish/cu/man/Makefile.am,v
retrieving revision 1.37
diff -p -u -r1.37 Makefile.am
--- man/Makefile.am     24 Jan 2005 08:21:39 -0000      1.37
+++ man/Makefile.am     4 Apr 2005 05:25:49 -0000
@@ -131,7 +131,7 @@ mapped_name = `echo $*|sed 's/install/gi
        (cd $t && $(LN_S) ../../src/$(mapped_name) $*); \
        $(PERL) -- $(srcdir)/help2man           \
            --include=$(srcdir)/$*.x            \
-           --output=$@ $t/$*
+           $t/$* | sed 's|$*\.td/||g' > $@
        @chmod a-w $@
        @rm -rf $t
 
Index: src/basename.c
===================================================================
RCS file: /fetish/cu/src/basename.c,v
retrieving revision 1.59
diff -p -u -r1.59 basename.c
--- src/basename.c      17 Nov 2004 00:56:25 -0000      1.59
+++ src/basename.c      4 Apr 2005 05:25:49 -0000
@@ -1,5 +1,5 @@
 /* basename -- strip directory and suffix from filenames
-   Copyright (C) 1990-1997, 1999-2004 Free Software Foundation, Inc.
+   Copyright (C) 1990-1997, 1999-2005 Free Software Foundation, Inc.
 
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
@@ -64,6 +64,13 @@ If specified, also remove a trailing SUF
 "), stdout);
       fputs (HELP_OPTION_DESCRIPTION, stdout);
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
+      printf (_("\
+\n\
+Examples:\n\
+  %s /usr/bin/sort       Output \"sort\".\n\
+  %s include/stdio.h .h  Output \"stdio\".\n\
+"),
+             program_name, program_name);
       printf (_("\nReport bugs to <%s>.\n"), PACKAGE_BUGREPORT);
     }
   exit (status);
Index: src/cat.c
===================================================================
RCS file: /fetish/cu/src/cat.c,v
retrieving revision 1.97
diff -p -u -r1.97 cat.c
--- src/cat.c   21 Sep 2004 22:26:42 -0000      1.97
+++ src/cat.c   4 Apr 2005 05:25:49 -0000
@@ -1,5 +1,5 @@
 /* cat -- concatenate files and print on the standard output.
-   Copyright (C) 88, 90, 91, 1995-2004 Free Software Foundation, Inc.
+   Copyright (C) 88, 90, 91, 1995-2005 Free Software Foundation, Inc.
 
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
@@ -118,6 +118,13 @@ With no FILE, or when FILE is -, read st
   -B, --binary             use binary writes to the console device.\n\n\
 "), stdout);
 #endif
+      printf (_("\
+\n\
+Examples:\n\
+  %s f - g  Output f's contents, then standard input, then g's contents.\n\
+  %s        Copy standard input to standard output.\n\
+"),
+             program_name, program_name);
       printf (_("\nReport bugs to <%s>.\n"), PACKAGE_BUGREPORT);
     }
   exit (status);
Index: src/chgrp.c
===================================================================
RCS file: /fetish/cu/src/chgrp.c,v
retrieving revision 1.116
diff -p -u -r1.116 chgrp.c
--- src/chgrp.c 28 Mar 2005 17:47:48 -0000      1.116
+++ src/chgrp.c 4 Apr 2005 05:25:49 -0000
@@ -153,6 +153,13 @@ one takes effect.\n\
 "), stdout);
       fputs (HELP_OPTION_DESCRIPTION, stdout);
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
+      printf (_("\
+\n\
+Examples:\n\
+  %s staff /u      Change the group of /u to \"staff\".\n\
+  %s -hR staff /u  Change the group of /u and subfiles to \"staff\".\n\
+"),
+             program_name, program_name);
       printf (_("\nReport bugs to <%s>.\n"), PACKAGE_BUGREPORT);
     }
   exit (status);
Index: src/chown.c
===================================================================
RCS file: /fetish/cu/src/chown.c,v
retrieving revision 1.121
diff -p -u -r1.121 chown.c
--- src/chown.c 28 Mar 2005 17:47:06 -0000      1.121
+++ src/chown.c 4 Apr 2005 05:25:50 -0000
@@ -148,6 +148,14 @@ Owner is unchanged if missing.  Group is
 to login group if implied by a `:' following a symbolic OWNER.\n\
 OWNER and GROUP may be numeric as well as symbolic.\n\
 "), stdout);
+      printf (_("\
+\n\
+Examples:\n\
+  %s root /u        Change the owner of /u to \"root\".\n\
+  %s root:staff /u  Likewise, but also change its group to \"staff\".\n\
+  %s -hR root /u    Change the owner of /u and subfiles to \"root\".\n\
+"),
+             program_name, program_name, program_name);
       printf (_("\nReport bugs to <%s>.\n"), PACKAGE_BUGREPORT);
     }
   exit (status);
Index: src/dirname.c
===================================================================
RCS file: /fetish/cu/src/dirname.c,v
retrieving revision 1.65
diff -p -u -r1.65 dirname.c
--- src/dirname.c       17 Nov 2004 00:56:25 -0000      1.65
+++ src/dirname.c       4 Apr 2005 05:25:50 -0000
@@ -1,5 +1,7 @@
 /* dirname -- strip filename suffix from pathname
-   Copyright (C) 1990-1997, 1999-2002, 2004 Free Software Foundation, Inc.
+
+   Copyright (C) 1990-1997, 1999-2002, 2004, 2005 Free Software
+   Foundation, Inc.
 
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
@@ -56,6 +58,13 @@ output `.' (meaning the current director
 "), stdout);
       fputs (HELP_OPTION_DESCRIPTION, stdout);
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
+      printf (_("\
+\n\
+Examples:\n\
+  %s /usr/bin/sort  Output \"/usr/bin\".\n\
+  %s stdio.h        Output \".\".\n\
+"),
+             program_name, program_name);
       printf (_("\nReport bugs to <%s>.\n"), PACKAGE_BUGREPORT);
     }
   exit (status);