From tonymaher@optushome.com.au  Sat Aug 16 21:53:38 2003
Return-Path: <tonymaher@optushome.com.au>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 006E437B401
	for <FreeBSD-gnats-submit@freebsd.org>; Sat, 16 Aug 2003 21:53:38 -0700 (PDT)
Received: from c210-49-151-50.thorn1.nsw.optusnet.com.au (c210-49-151-50.thorn1.nsw.optusnet.com.au [210.49.151.50])
	by mx1.FreeBSD.org (Postfix) with ESMTP id D0A2B43F85
	for <FreeBSD-gnats-submit@freebsd.org>; Sat, 16 Aug 2003 21:53:36 -0700 (PDT)
	(envelope-from tonymaher@optushome.com.au)
Received: from dt.home (localhost [127.0.0.1])
	by c210-49-151-50.thorn1.nsw.optusnet.com.au (8.12.9/8.12.9) with ESMTP id h7H4rZkI053144
	for <FreeBSD-gnats-submit@freebsd.org>; Sun, 17 Aug 2003 14:53:35 +1000 (EST)
	(envelope-from tonym@dt.home)
Received: (from tonym@localhost)
	by dt.home (8.12.9/8.12.9/Submit) id h7H4rUCi053082;
	Sun, 17 Aug 2003 14:53:30 +1000 (EST)
	(envelope-from tonym)
Message-Id: <200308170453.h7H4rUCi053082@dt.home>
Date: Sun, 17 Aug 2003 14:53:30 +1000 (EST)
From: Tony Maher <tonymaher@optushome.com.au>
Reply-To: Tony Maher <tonymaher@optushome.com.au>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: chflags.1 - note that not all tools chflags aware.
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         55653
>Category:       docs
>Synopsis:       chflags.1 - note that not all tools chflags aware.
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    trhodes
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sat Aug 16 22:00:31 PDT 2003
>Closed-Date:    Sat Feb 26 04:50:53 GMT 2005
>Last-Modified:  Sat Feb 26 04:50:53 GMT 2005
>Originator:     Tony Maher
>Release:        FreeBSD 4.8-STABLE i386
>Organization:
>Environment:
System: FreeBSD dt.home 4.8-STABLE FreeBSD 4.8-STABLE #3: Sun Aug 10 11:11:38 EST 2003 root@dt.home:/usr/obj/usr/src/sys/DT i386


>Description:
	It was pointed out to me last week that not all tools are aware of
	BSD extension file flags (chflags).
	Attached is patch which just notes this in the chflags.1 man page.

>How-To-Repeat:

>Fix:


--- chflags.1.orig	Sun Aug 17 14:31:38 2003
+++ chflags.1	Sun Aug 17 14:43:57 2003
@@ -149,6 +149,23 @@
 .Xr stat 2 ,
 .Xr fts 3 ,
 .Xr symlink 7
+.Sh BUGS
+Only a limited number of tools know about about chflags.
+Some of the tools which are
+.Nm
+aware include:
+.Xr ls 1 ,
+.Xr cp 1 ,
+.Xr find 1 ,
+.Xr dump 8 ,
+and
+.Xr restore 8 .
+In particular the following tools are not
+.Nm
+aware:
+.Xr tar 1
+and
+.Xr pax 1 .
 .Sh HISTORY
 The
 .Nm

>Release-Note:
>Audit-Trail:

From: underway@comcast.net (Gary W. Swearingen)
To: Tony Maher <tonymaher@optushome.com.au>
Cc: FreeBSD-gnats-submit@FreeBSD.org
Subject: Re: docs/55653: chflags.1 - note that not all tools chflags aware.
Date: Sun, 17 Aug 2003 07:36:37 -0700

 Tony Maher <tonymaher@optushome.com.au> writes:
 
 > 	Attached is patch which just notes this in the chflags.1 man page.
 
 Good idea.
 
 > +.Sh BUGS
 
 The warning note would be better placed in a custom WARNING (or NOTES)
 section, or in a standard COMPATIBILITY section or even in the
 DESCRIPTION.  It's not about a chflags(1) bug.  The fact that other
 manpages abuse their BUGS section is no reason for this one to do it.
 
 > +Only a limited number of tools know about about chflags.
 
   --  Only a limited number of tools know about chflags.
   --  Only a limited number of tools know about file flags.
   --  Only a limited number of programs know about file flags.
   --  A limited number of programs know about file flags.
   --  Some programs do not know about file flags.
   --  Some programs do not handle file flags.
   --  Some programs which should handle file flags do not.
 
 > +Some of the tools which are
 
 It's debatable whether any of these tools/utilities/programs should be
 listed in the manpage, mainly because it adds a continual source of
 manpage bugs as file flags and their support changes from time to
 time.  Also, the info would, to be consistent, need to be added to
 chflags(2) and other manpages that deal with file flags.
 
 I tend to like helpful manpages, but in this case I think it's better
 to limit that help to the generic warning note and put these lists of
 programs in a Handbook "File Flags" section, if anywhere.
 
 
 Also: The tar(1) and pax(1) manpages should say in their BUGS sections
 that they don't support file flags, if that's the case.

From: Tony Maher <tonymaher@optushome.com.au>
To: tonymaher@optushome.com.au, underway@comcast.net
Cc: FreeBSD-gnats-submit@freebsd.org
Subject: Re: docs/55653: chflags.1 - note that not all tools chflags aware.
Date: Mon, 18 Aug 2003 19:00:45 +1000 (EST)

 Hello,
 
 thanks for feedback.
 
 >> +.Sh BUGS
 >
 > The warning note would be better placed in a custom WARNING (or NOTES)
 > section, or in a standard COMPATIBILITY section or even in the
 > DESCRIPTION.  It's not about a chflags(1) bug.  The fact that other
 > manpages abuse their BUGS section is no reason for this one to do it.
 
 I agree but the example man pages I looked at used bugs.
 But I dont care how its done, I'll leave it up to a docs person.
 
 > It's debatable whether any of these tools/utilities/programs should be
 > listed in the manpage, mainly because it adds a continual source of
 > manpage bugs as file flags and their support changes from time to
 > time.  Also, the info would, to be consistent, need to be added to
 > chflags(2) and other manpages that deal with file flags.
 >
 > I tend to like helpful manpages, but in this case I think it's better
 > to limit that help to the generic warning note and put these lists of
 > programs in a Handbook "File Flags" section, if anywhere.
 
 I prefer man pages since they are more accessible. I liked the info
 all in the once place so that someone reading about chflags would
 immediately be aware that there could be problems using copy mecahnisms like
 tar and pax.
 
 That said I am happy for whatever the docs people decide 
 matches best with FreeBSD docs practice.
 
 > Also: The tar(1) and pax(1) manpages should say in their BUGS sections
 > that they don't support file flags, if that's the case.
 
 That would be useful.
 
 cheers
 --
 tonym
State-Changed-From-To: open->patched 
State-Changed-By: trhodes 
State-Changed-When: Wed Feb 23 23:08:27 GMT 2005 
State-Changed-Why:  
Slightly modified version committed to CURRENT, MFC pending. 


Responsible-Changed-From-To: freebsd-doc->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Wed Feb 23 23:08:27 GMT 2005 
Responsible-Changed-Why:  
Over to me for the pending MFC. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=55653 
State-Changed-From-To: patched->closed 
State-Changed-By: trhodes 
State-Changed-When: Sat Feb 26 04:50:33 GMT 2005 
State-Changed-Why:  
MFC complete, close this PR. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=55653 
>Unformatted:
