From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from kerhand.co.uk (_smtpd@82-69-137-214.dsl.in-addr.zen.co.uk [82.69.137.214]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id o6REFetF014655 for ; Tue, 27 Jul 2010 10:15:41 -0400 (EDT) Received: from localhost (1000@localhost [IPv6:::1]) by kerhand.co.uk (OpenSMTPD) with ESMTP id LqPmxvgl; Tue, 27 Jul 2010 15:15:14 +0100 (BST) Date: Tue, 27 Jul 2010 15:15:14 +0100 From: Jason McIntyre To: discuss@mdocml.bsd.lv Cc: "ru@freebsd.org" Subject: Re: mdoc EXIT STATUS (Was: pending open issues) Message-ID: <20100727141538.GA8226@bramka.kerhand.co.uk> References: <20100727071224.GB7946@bramka.kerhand.co.uk> <4C4E996B.5080908@bsd.lv> <20100727092007.GA21455@bramka.kerhand.co.uk> <4C4EA7A0.1040104@bsd.lv> <20100727094102.GC21455@bramka.kerhand.co.uk> <4C4EAEE9.9000106@bsd.lv> <20100727101815.GD21455@bramka.kerhand.co.uk> <4C4EC13B.1000906@bsd.lv> <20100727131709.GA16499@edoofus.dev.vega.ru> <4C4EE52F.9020601@bsd.lv> X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <4C4EE52F.9020601@bsd.lv> User-Agent: Mutt/1.4.2.3i On Tue, Jul 27, 2010 at 03:54:55PM +0200, Kristaps Dzonsons wrote: > > > > Traditionally BSD used DIAGNOSTICS for both exit statuses and diagnostic > > messages. Then POSIX took BSD manpages to form their document base. > > They invented EXIT STATUS. In 2000, I participated in mdoc(7) macro > > package rewrite in Groff, including massive updates of FreeBSD manpages. > > As part of this work, FreeBSD received permission from Austin Group to > > use POSIX texts in their manpages. I've then "introduced" EXIT STATUS > > to FreeBSD manpages, in 2005, splitting the existing DIAGNOSTICS section > > into two: EXIT STATUS for documenting program's exit statuses, and > > DIAGNOSTICS for program/driver diagnostic messages. The current > > manpage skeletons are there: > > > > http://svn.freebsd.org/viewvc/base/head/share/misc/mdoc.template > > http://svn.freebsd.org/viewvc/base/head/share/examples/mdoc/ > > so, would you like to comment on how well this works in your pages in practice? i dislike the idea of two sections because i fear most pages will have, in essence: .Sh EXIT STATUS .Ex -std app .Sh DIAGNOSTICS Another tiny sentence. what exactly is the purpose of having two sections? how do you separate application diagnostics from their return codes? i'm struggling to find a page (sections 1, 6, or 8) where DIAGNOSTICS makes sense. i cannot even find any posix pages with it. or are you just using DIAGNOSTICS for section 4? jmc -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv