Hi, A discussion at the local Manchester LUG pointed out that many man pages don't include examples and there is a general view that it would be nice if this situation was improved.
I've included a handful of examples that I've started to put together for coreutils (against 5.3.0) and would like your view on incorporating them into the distribution. I've had a quick check over this patch but there is obviously quite a bit more to do in covering the rest of the set of utilities that I am happy to complete. Suggestions and comments welcome. Dave -----Open up your eyes, open up your mind, open up your code ------- / Dr. David Alan Gilbert | Running GNU/Linux on Alpha,68K| Happy \ \ gro.gilbert @ treblig.org | MIPS,x86,ARM,SPARC,PPC & HPPA | In Hex / \ _________________________|_____ http://www.treblig.org |_______/
diff -urN orig/coreutils-5.3.0/man/basename.x coreutils-5.3.0/man/basename.x --- orig/coreutils-5.3.0/man/basename.x 1999-11-02 14:07:36.000000000 +0000 +++ coreutils-5.3.0/man/basename.x 2005-03-13 15:20:30.000000000 +0000 @@ -2,3 +2,14 @@ basename \- strip directory and suffix from filenames [DESCRIPTION] .\" Add any additional description here +[EXAMPLES] +.TP +.B basename \fI/an/example/path/finalname\fR +.br +Strip off the path leaving just \fIfinalname\fR. +.TP +.B basename \fIthe/path/finalname.foo\fR \fI.foo\fR +.br +Stip off the path and the trailing \fI.foo\fR leaving \fIfinalname\fR. Note +that if the name did not end in \fI.foo\fR the full basename would be passed +through. diff -urN orig/coreutils-5.3.0/man/cat.x coreutils-5.3.0/man/cat.x --- orig/coreutils-5.3.0/man/cat.x 1999-11-02 13:58:56.000000000 +0000 +++ coreutils-5.3.0/man/cat.x 2005-03-13 15:41:14.000000000 +0000 @@ -1,4 +1,20 @@ [NAME] cat \- concatenate files and print on the standard output +[EXAMPLES] +.TP +.B cat \fIfirst\fR \fImiddle\fR \fIlast\fR +.br +Concatenate the three files \fIfirst\fR \fImiddle\fR \fIlast\fR onto the standard output. +.TP +.B cat \fIheader\fR \fB-\fR \fIfooter\fR +.br +Concatenate the two files \fIheader\fR and \fIfooter\fR putting the contents of standard +input in between; the result is placed onto the standard output. +.TP +.B cat -s +.br +Squeeze multiple blank lines from standard input down to a single blank; the result is +placed onto the standard output. Standard output is only read if no filenames are given +or if \fB-\fR is used. [DESCRIPTION] .\" Add any additional description here diff -urN orig/coreutils-5.3.0/man/chgrp.x coreutils-5.3.0/man/chgrp.x --- orig/coreutils-5.3.0/man/chgrp.x 2000-02-01 10:34:35.000000000 +0000 +++ coreutils-5.3.0/man/chgrp.x 2005-03-13 16:07:26.000000000 +0000 @@ -2,3 +2,13 @@ chgrp \- change group ownership [DESCRIPTION] .\" Add any additional description here +[EXAMPLES] +.TP +.B chgrp \fImygroup\fR \fIfile1\fR \fIfile2\fR +.br +Change the group ownership of \fIfile1\fR and \fIfile2\fR to \fImygroup\fR. +.TP +.B chgrp -R --reference=\fImyreffile\fR \fI/usr/myexampledir\fR +.br +Change the group ownership of the directory \fI/usr/myexampledir\fR and +all files under it to be the same as that of \fImyreffile\fR. diff -urN orig/coreutils-5.3.0/man/chown.x coreutils-5.3.0/man/chown.x --- orig/coreutils-5.3.0/man/chown.x 2001-10-13 17:50:59.000000000 +0100 +++ coreutils-5.3.0/man/chown.x 2005-03-13 17:19:21.000000000 +0000 @@ -20,3 +20,19 @@ performs the same function as .BR chgrp . .SH OPTIONS +[EXAMPLES] +.TP +.B chown \fIauser\fR \fIfile1\fR \fIfile2\fR +.br +Change the user ownership of \fIfile1\fR and \fIfile2\fR to \fIauser\fR which +may be either a name or numerical user ID. The group ID of the files is left +unchanged. +.TP +.B chown -R \fIauser:agroup\fR \fIadirectory\fR +.br +Change the user and group ownership of \fIadirectory\fR and all the files +and directories under it to \fIauser\fR and \fIagroup\fR respectively. +.TP +.B chown --reference \fIonefile\fR \fIanotherfile\fR +.br +Change the user and group of \fIanotherfile\fR to match that of \fIonefile\fR. diff -urN orig/coreutils-5.3.0/man/chroot.x coreutils-5.3.0/man/chroot.x --- orig/coreutils-5.3.0/man/chroot.x 1999-11-02 14:07:36.000000000 +0000 +++ coreutils-5.3.0/man/chroot.x 2005-03-13 17:25:56.000000000 +0000 @@ -2,3 +2,14 @@ chroot \- run command or interactive shell with special root directory [DESCRIPTION] .\" Add any additional description here +[EXAMPLES] +.TP +.B chroot \fIdirectory\fR +.br +Substitute \fIdirectory\fR as / and execute the /bin/sh under that root in the +new environment. +.TP +.B chroot \fI/my/new/install\fR \fI/bin/bash\fR +.br +Execute \fI/my/new/install/bin/bash\fR in an environment with \fI/my/new/install\fR +as /. diff -urN orig/coreutils-5.3.0/man/cksum.x coreutils-5.3.0/man/cksum.x --- orig/coreutils-5.3.0/man/cksum.x 1999-11-02 13:58:56.000000000 +0000 +++ coreutils-5.3.0/man/cksum.x 2005-03-13 18:10:18.000000000 +0000 @@ -2,3 +2,9 @@ cksum \- checksum and count the bytes in a file [DESCRIPTION] .\" Add any additional description here +[EXAMPLE] +.TP +.B cksum \fIfile1\fR \fIfile2\fR +.br +Produce checksum and byte count values for each of \fIfile1\fR and \fIfile2\fR. + diff -urN orig/coreutils-5.3.0/man/comm.x coreutils-5.3.0/man/comm.x --- orig/coreutils-5.3.0/man/comm.x 1999-11-02 13:58:56.000000000 +0000 +++ coreutils-5.3.0/man/comm.x 2005-03-13 18:21:34.000000000 +0000 @@ -2,3 +2,20 @@ comm \- compare two sorted files line by line [DESCRIPTION] .\" Add any additional description here +[EXAMPLES] +.TP +.B comm \fIa1\fR \fIa2\fR +.br +Output three columns showing (respectively) the lines that are +only in \fIa1\fR, only in \fIa2\fR and finally in both. +Both files must be presorted. +.TP +.B comm -1 -2 \fIa1\fR \fIa2\fR +.br +Output a list of the lines that are common to both input files. +(i.e. surpress the lines unique to the first and second files). +.TP +.B comm -3 \fIa1\fR \fIa2\fR +.br +Output a list of the lines that are added in either file +(i.e. surpress the lines common to both files). diff -urN orig/coreutils-5.3.0/man/cp.x coreutils-5.3.0/man/cp.x --- orig/coreutils-5.3.0/man/cp.x 1999-11-02 13:51:42.000000000 +0000 +++ coreutils-5.3.0/man/cp.x 2005-03-13 18:55:48.000000000 +0000 @@ -1,4 +1,33 @@ [NAME] cp \- copy files and directories +[EXAMPLES] +.TP +.B cp \fIfile1\fR \fIname\fR +.br +Copy the contents of \fIfile1\fR to \fIname\fR. If \fIname\fR is an existing +directory then the file will be copied to \fIname/file1\fR. +.TP +.B cp \fIfile1\fR \fIfile2\fR \fIdir\fR +.br +Copy the contents of \fIfile1\fR and \fIfile2\fR to \fIdir\fR that must be +the name of an existing directory. +.TP +.B cp -a \fIdir\fR \fIname\fR +.br +Copy the directory \fIdir\fR and all its children to a new directory of the +name \fIname\fR preserving as much as possible about the original as possible, +including permisisons, symbolic links and modification times. Symbolic links +are copied but not followed. +.TP +.B cp -x -r \fIdir\fR \fIname\fR +.br +Copy the directory \fIdir\fR and its children but ommitting +the contents of any directory on another filesystem. +.TP +.B cp --sparse=always \fIabigfile\fR \fIasparsefile\fR +.br +Given a file containing large sections of zeros use the sparse file +facility provided on most filesystems to create a new file that does +not actually bother storing the zeros on disk. [DESCRIPTION] .\" Add any additional description here
_______________________________________________ Bug-coreutils mailing list [email protected] http://lists.gnu.org/mailman/listinfo/bug-coreutils
