From owner-freebsd-doc@FreeBSD.ORG Mon Feb 20 20:58:19 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 96F661065674 for ; Mon, 20 Feb 2012 20:58:18 +0000 (UTC) (envelope-from rsimmons0@gmail.com) Received: from mail-gx0-f182.google.com (mail-gx0-f182.google.com [209.85.161.182]) by mx1.freebsd.org (Postfix) with ESMTP id 501228FC0C for ; Mon, 20 Feb 2012 20:58:18 +0000 (UTC) Received: by ggnk5 with SMTP id k5so3102264ggn.13 for ; Mon, 20 Feb 2012 12:58:17 -0800 (PST) Received-SPF: pass (google.com: domain of rsimmons0@gmail.com designates 10.101.126.18 as permitted sender) client-ip=10.101.126.18; Authentication-Results: mr.google.com; spf=pass (google.com: domain of rsimmons0@gmail.com designates 10.101.126.18 as permitted sender) smtp.mail=rsimmons0@gmail.com; dkim=pass header.i=rsimmons0@gmail.com Received: from mr.google.com ([10.101.126.18]) by 10.101.126.18 with SMTP id d18mr9587087ann.43.1329771497804 (num_hops = 1); Mon, 20 Feb 2012 12:58:17 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=mime-version:date:message-id:subject:from:to:content-type; bh=Xj5fCMqZIXslay0d0qhippEHEHi5BLxreC7qu5rfDYI=; b=d7jATSmXK1tHdwUbpvRc44WoV+TBUgIomLoOtge/HoNBMi7A2piWmKN18Wmr6OEg6B +gZBtKmTFkUA4oMV3f7KTQExp8Fx8QZC5X1c87W3E9hQyKrUyD18HRno5A5WK2UeGg/P ATU7Jc6JIdQEmBJwBHCrAdr2aNzBVqVl/02KA= MIME-Version: 1.0 Received: by 10.101.126.18 with SMTP id d18mr7387229ann.43.1329769820862; Mon, 20 Feb 2012 12:30:20 -0800 (PST) Received: by 10.101.102.11 with HTTP; Mon, 20 Feb 2012 12:30:20 -0800 (PST) Date: Mon, 20 Feb 2012 15:30:20 -0500 Message-ID: From: Robert Simmons To: freebsd-doc@freebsd.org Content-Type: text/plain; charset=ISO-8859-1 Subject: 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: Mon, 20 Feb 2012 20:58:19 -0000 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. 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. 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. Perhaps a "WARNINGS" section should be used for this type of information?