Skip site navigation (1)Skip section navigation (2)
Date:      Mon, 20 Feb 2012 15:30:20 -0500
From:      Robert Simmons <rsimmons0@gmail.com>
To:        freebsd-doc@freebsd.org
Subject:   BUGS section of man pages
Message-ID:  <CA%2BQLa9DQzRT-HPcivC9mxVyrANR3Zr4dcr0%2Bsyhvd6UR-1CbEA@mail.gmail.com>

next in thread | raw e-mail | index | archive | help
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?



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CA%2BQLa9DQzRT-HPcivC9mxVyrANR3Zr4dcr0%2Bsyhvd6UR-1CbEA>