>Number:         16827
>Category:       bin
>Synopsis:       addition of EXAMPLES section to basesrc/bin/cat.1
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    bin-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Wed May 15 00:54:01 PDT 2002
>Closed-Date:
>Last-Modified:
>Originator:     Giorgos Keramidas
>Release:        
>Organization:
>Environment:
>Description:
The FreeBSD manual page of cat(1) has a few nice examples of how the
command can be used.  Here's a patch that adds the same information to
basesrc/bin/cat/cat.1 of NetBSD.

Note that I don't have the NetBSD version of groff macros, since my
repo copy is still fetching itself, and I have tested this with the
FreeBSD version of /usr/share/tmac - you might have to make minor
changes to this to make it fit the existing style of the rest of the
NetBSD manpages - sorry 'bout that.

Soon I'll hopefully have a powerpc installed with NetBSD and will be
able to test these in a real NetBSD installation :)


>How-To-Repeat:

>Fix:
Index: cat.1
===================================================================
RCS file: /home/netbsd/basesrc/bin/cat/cat.1,v
retrieving revision 1.24
diff -u -r1.24 cat.1
--- cat.1	8 Feb 2002 01:21:55 -0000	1.24
+++ cat.1	15 May 2002 07:38:16 -0000
@@ -109,6 +109,56 @@
 The
 .Nm
 utility exits 0 on success, and \*[Gt]0 if an error occurs.
+.Sh EXAMPLES
+The command:
+.Bd -literal -offset indent
+.Ic cat file1
+.Ed
+.Pp
+will print the contents of
+.Ar file1
+to the standard output.
+.Pp
+The command:
+.Bd -literal -offset indent
+.Ic cat file1 file2 > file3
+.Ed
+.Pp
+will sequentially print the contents of
+.Ar file1
+and
+.Ar file2
+to the file
+.Ar file3 ,
+truncating
+.Ar file3
+if it already exists.
+See the manual page for your shell (i.e.,
+.Xr sh 1 )
+for more information on redirection.
+.Pp
+The command:
+.Bd -literal -offset indent
+.Ic cat file1 - file2 - file3
+.Ed
+.Pp
+will print the contents of
+.Ar file1 ,
+print data it receives from the standard input until it receives an
+.Dv EOF
+.Pq Sq ^D
+character, print the contents of
+.Ar file2 ,
+read and output contents of the standard input again, then finally output
+the contents of
+.Ar file3 .
+Note that if the standard input referred to a file, the second dash
+on the command-line would have no effect, since the entire contents of the file
+would have already been read and printed by
+.Nm
+when it encountered the first
+.Ql \&-
+operand.
 .Sh SEE ALSO
 .Xr head 1 ,
 .Xr hexdump 1 ,

>Release-Note:
>Audit-Trail:
>Unformatted: