From owner-freebsd-doc@FreeBSD.ORG Thu Feb 23 02:58:53 2012 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id F343C1065675 for ; Thu, 23 Feb 2012 02:58:53 +0000 (UTC) (envelope-from gjb@FreeBSD.org) Received: from glenbarber.us (onyx.glenbarber.us [199.48.134.227]) by mx1.freebsd.org (Postfix) with SMTP id A48298FC1D for ; Thu, 23 Feb 2012 02:58:53 +0000 (UTC) Received: (qmail 98533 invoked by uid 0); 22 Feb 2012 21:58:52 -0500 Received: from unknown (HELO glenbarber.us) (76.124.49.145) by 0 with SMTP; 22 Feb 2012 21:58:52 -0500 Date: Wed, 22 Feb 2012 21:58:47 -0500 From: Glen Barber To: Robert Simmons Message-ID: <20120223025846.GC1874@glenbarber.us> References: MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: X-Operating-System: FreeBSD 10.0-CURRENT amd64 User-Agent: Mutt/1.5.21 (2010-09-15) Cc: freebsd-doc@freebsd.org Subject: Re: BUGS section of man pages X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 23 Feb 2012 02:58:54 -0000 Hi, On Mon, Feb 20, 2012 at 03:30:20PM -0500, Robert Simmons wrote: > Can someone clarify the usage for the "BUGS" section of man pages? > > My assumption is that it is for listing known bugs, as in defects that > are correctable but not yet corrected. The section exists as a list > of the existence of these defects until the defect is fixed. Similar > to a section of known problems or known bugs in the release notes of a > piece of software. > In my opinion, the BUGS section should be used for known issues of said software under circumstances that may not necessarily be considered "normal", or would require change to other parts of the system (kernel, for example). > However, I have noticed that some man pages use the section as a list > of warnings or gotchas that the user should know about, but are not > really defects or bugs in the software. > Some other manual page use the NOTES section for this. > For example, the cat(1) man page's bugs section lists "Because of the > shell language mechanism used to perform output redirection, the > command ``cat file1 file2 > file1'' will cause the original data in > file1 to be destroyed!" This does not seem like a bug to me. > I think it depends on the user's expectation in a very specific circumstance. In this case, I would consider the entry in BUGS to be correct, as a fix, if any, would depend on a change in how the shell interprets the command. Glen