From dkelly@nospam.hiwaay.net Mon Jun 28 17:46:33 1999
Return-Path: <dkelly@nospam.hiwaay.net>
Received: from mail.HiWAAY.net (fly.HiWAAY.net [208.147.154.56])
	by hub.freebsd.org (Postfix) with ESMTP id 4198714D94
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 28 Jun 1999 17:46:31 -0700 (PDT)
	(envelope-from dkelly@nospam.hiwaay.net)
Received: from nospam.hiwaay.net (tnt8-216-180-15-77.dialup.HiWAAY.net [216.180.15.77])
	by mail.HiWAAY.net (8.9.1a/8.9.0) with ESMTP id TAA20841
	for <FreeBSD-gnats-submit@freebsd.org>; Mon, 28 Jun 1999 19:46:22 -0500 (CDT)
Received: (from dkelly@localhost)
	by nospam.hiwaay.net (8.9.3/8.9.3) id TAA82782;
	Mon, 28 Jun 1999 19:32:10 -0500 (CDT)
	(envelope-from dkelly)
Message-Id: <199906290032.TAA82782@nospam.hiwaay.net>
Date: Mon, 28 Jun 1999 19:32:10 -0500 (CDT)
From: dkelly@hiwaay.net
Sender: dkelly@nospam.hiwaay.net
Reply-To: dkelly@hiwaay.net
To: FreeBSD-gnats-submit@freebsd.org
Subject: I keep forgetting "diff -ruN"
X-Send-Pr-Version: 3.2

>Number:         12440
>Category:       docs
>Synopsis:       added an example to diff(1) man page
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    sheldonh
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Mon Jun 28 17:50:03 PDT 1999
>Closed-Date:    Thu Jul 29 11:59:44 PDT 1999
>Last-Modified:  Thu Jul 29 12:00:57 PDT 1999
>Originator:     David Kelly
>Release:        FreeBSD 3.2-STABLE i386
>Organization:
n/a
>Environment:

	

>Description:

For some reason every time I fix something I'd like others to consider
for FreeBSD, I can't remember/find the proper syntax for diff. That is,
to do diff the way the team likes it.

When I go looking for this information, I know its in the handbook.
Somewhere in the handbook. It used to be on the post-it note on
my monitor. But I keep wishing to find it in diff(1).

So I've added it to diff.

Maybe I've done it right this time?

Am not totally pleased with my grammar. Would be happy if somebody
re-wrote it in man-ese. Just wish the "diff -ruN x.orig x" part
would remain.

Don't know enough man macros to know how to properly format the
literal example line to represent "typed text". What I've done
looks right in monospaced ASCII but probably not correct when
printed to a postscript printer.

>How-To-Repeat:

--- gnu/usr.bin/diff/diff.1.orig        Sun May 26 17:27:52 1996
+++ gnu/usr.bin/diff/diff.1     Mon Jun 28 19:17:24 1999
@@ -463,6 +463,14 @@
 .TP
 .B \-y
 Use the side by side output format.
+.SH EXAMPLE
+This is the prefered way to output the differences in something you
+wish to share with others, such as via send-pr(1) for consideration
+to be included in FreeBSD. Notice 'something.orig' and 'something'
+may be directories.
+.sp
+diff -ruN something.orig something
+.sp
 .SH SEE ALSO
 cmp(1), comm(1), diff3(1), ed(1), patch(1), pr(1), sdiff(1).
 .SH DIAGNOSTICS


>Fix:
>Release-Note:
>Audit-Trail:

From: Sheldon Hearn <sheldonh@uunet.co.za>
To: freebsd-gnats-submit@freebsd.org
Cc: mpp@freebsd.org
Subject: Re: docs/12440: added an example to diff(1) man page
Date: Tue, 29 Jun 1999 15:13:08 +0200

 The handbook says that the context diff is preferred, but your example
 uses the unified diff. Funnily enough, though, I note that both you and
 I obviously prefer unified diffs. :-)
 
 You should call the section "EXAMPLES" instead of "EXAMPLE" to keep
 the manpage consistent with other manpages and with the guidelines in
 the mdoc.samples(7) manpage.
 
 Also, you really are putting your information in the wrong place. You
 might be able to get away with that by changing the wording. Are you
 happy with the diff below?
 
 Ciao,
 Sheldon.
 
 Index: diff.1
 ===================================================================
 RCS file: /home/ncvs/src/gnu/usr.bin/diff/diff.1,v
 retrieving revision 1.3
 diff -u -d -r1.3 diff.1
 --- diff.1	1996/05/26 22:27:52	1.3
 +++ diff.1	1999/06/29 13:09:26
 @@ -463,6 +463,20 @@
  .TP
  .B \-y
  Use the side by side output format.
 +.SH EXAMPLES
 +To save to a file some changes that you have made to your local source
 +tree (possibly including new files), which you would like to show to others
 +(perhaps using the
 +.B send-pr(1)
 +program), you could type
 +.sp
 +diff -crN foo.orig foo >foo.diff
 +.sp
 +where
 +.I foo.orig
 +and
 +.I foo
 +might be directory hierarchies or single files.
  .SH SEE ALSO
  cmp(1), comm(1), diff3(1), ed(1), patch(1), pr(1), sdiff(1).
  .SH DIAGNOSTICS
 
State-Changed-From-To: open->feedback 
State-Changed-By: sheldonh 
State-Changed-When: Mon Jul 19 03:04:50 PDT 1999 
State-Changed-Why:  
Waitinf for comments from David. 


Responsible-Changed-From-To: freebsd-doc->sheldonh 
Responsible-Changed-By: sheldonh 
Responsible-Changed-When: Mon Jul 19 03:04:50 PDT 1999 
Responsible-Changed-Why:  
If David's happy with my variation on his theme, I'll do it. :-) 
State-Changed-From-To: feedback->closed 
State-Changed-By: sheldonh 
State-Changed-When: Thu Jul 29 11:59:44 PDT 1999 
State-Changed-Why:  
Example added in the absence of feedback from originator. Thanks! :-) 
>Unformatted:
