Date: Wed, 8 Dec 1999 16:39:04 -0600 From: Mike Pritchard <mpp@mppsystems.com> To: Chris Costello <chris@calldei.com> Cc: doc@FreeBSD.ORG Subject: Re: mdoc(7) vs. example.? vs. real man pages Message-ID: <19991208163904.C16225@mppsystems.com> In-Reply-To: <19991208001020.D976@holly.calldei.com> References: <19991208001020.D976@holly.calldei.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Wed, Dec 08, 1999 at 12:10:20AM -0600, Chris Costello wrote: > As you may just have seen from a recent problem report, David > O'Brien brought up the issue of inconsistant documentation. > > So here's the deal. There are several different disagreeing > ideas here: > > - Real manual pages. Take a look at chmod(1). It's got the > BUGS listing above SEE ALSO. Compare with mdoc(7) and > example.1 in /usr/share/examples/mdoc > - /usr/share/examples/mdoc/example.?. These conflict with > mdoc(7) in the way of ordering sections. BUGS here are at > the very bottom. > > How are we going to deal with this? I propose (due to > preference) that mdoc(7) be updated to reflect the type of layout > that's in the example manual pages. > > Can anybody give feedback so we can reach a conclusion and > make everything consistent? I originally wrote the example man pages, based on the mdoc template in mdoc.samples(7) and share/misc/mdoc.template. I just commited changes that make the examples and the mdoc man pages all consistent with each other. Even the examples weren't consistent with each other before :-(. This should be the preferred ordering of section headers for new man pages, and for additions to existing man pages. However, if someone really feels that a section should be moved higher up in the man page, we shouldn't absolutely forbid it. A good example might be the BUGS section. If there is some really nasty bug that might bite you, moving it up in the man page would probably be OK, since it makes it more likely that the reader will make it that far and see the warning. Along the same lines, we should probably leave the existing man pages alone. We can probably find better projects to spend our time on. But if you are working on a man page, and re-ordering the section is just another minor change to go along with it, go for it. -Mike -- Mike Pritchard mpp@FreeBSD.org or mpp@mppsystems.com To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19991208163904.C16225>