From owner-freebsd-doc@FreeBSD.ORG Mon Aug 18 02:10:09 2003 Return-Path: Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 7E0CB37B401 for ; Mon, 18 Aug 2003 02:10:09 -0700 (PDT) Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id 1CCA643F3F for ; Mon, 18 Aug 2003 02:10:09 -0700 (PDT) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.12.9/8.12.9) with ESMTP id h7I9A8Up076050 for ; Mon, 18 Aug 2003 02:10:08 -0700 (PDT) (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.12.9/8.12.9/Submit) id h7I9A8IO076049; Mon, 18 Aug 2003 02:10:08 -0700 (PDT) Date: Mon, 18 Aug 2003 02:10:08 -0700 (PDT) Message-Id: <200308180910.h7I9A8IO076049@freefall.freebsd.org> To: freebsd-doc@FreeBSD.org From: Tony Maher Subject: Re: docs/55653: chflags.1 - note that not all tools chflags aware. X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list Reply-To: Tony Maher List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 18 Aug 2003 09:10:09 -0000 The following reply was made to PR docs/55653; it has been noted by GNATS. From: Tony Maher 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