From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from acme.spoerlein.net (acme.spoerlein.net [188.72.220.29]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id o4BB8vH4024022 for ; Tue, 11 May 2010 05:08:58 -0600 (MDT) Received: from acme.spoerlein.net (localhost.spoerlein.net [IPv6:::1]) by acme.spoerlein.net (8.14.4/8.14.4) with ESMTP id o4BEvCCf087456 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Tue, 11 May 2010 16:57:12 +0200 (CEST) (envelope-from uqs@spoerlein.net) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=spoerlein.net; s=dkim200908; t=1273589832; bh=FBZQIBSbTCz156jMqOEVYhPfHwP1NG85N0dGpJ9TC8E=; h=Date:From:To:Subject:Message-ID:References:MIME-Version: Content-Type:In-Reply-To; b=Ufnzsx7QD++3ItKbOevvJzFmn2nuJAnHxocVoS81Ww+/NFNAH+QAo+u5eIai5+W10 g5xhNiiihUSHtFzM4uxsj74AryYkXPM8/AvAVNzq1jDmK+QoZiwCFBDSqZ3qYre4wl tI+r4++yQZ/W7H6qRb4LWH5iRVyvm4v3t+3LtVwc= Received: (from uqs@localhost) by acme.spoerlein.net (8.14.4/8.14.4/Submit) id o4BEvB1r087455 for discuss@mdocml.bsd.lv; Tue, 11 May 2010 16:57:11 +0200 (CEST) (envelope-from uqs@spoerlein.net) Date: Tue, 11 May 2010 16:57:11 +0200 From: Ulrich =?utf-8?B?U3DDtnJsZWlu?= To: discuss@mdocml.bsd.lv Subject: Re: mdoc section ordering Message-ID: <20100511145711.GW88504@acme.spoerlein.net> References: <20100511115233.GV88504@acme.spoerlein.net> <20100511134542.GA24992@bramka.kerhand.co.uk> 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: <20100511134542.GA24992@bramka.kerhand.co.uk> User-Agent: Mutt/1.5.20 (2009-06-14) On Tue, 11.05.2010 at 14:45:18 +0100, Jason McIntyre wrote: > On Tue, May 11, 2010 at 01:52:33PM +0200, Ulrich Sp??rlein wrote: > > Hi, > > > > right now the lint option of mandoc will complain mildly, if the section > > order of manpages is not in a certain order. This is good. > > > > However, while working on the FreeBSD mdoc corpus, I found that FreeBSD > > and mdocml diverge on where they think the EXIT STATUS section should be > > placed. > > > > FreeBSD: mdocml: > > > > .Dd Month day, year .Dd $Mdocdate$ > > .Os [OPERATING_SYSTEM] .Dt mdoc 7 > > .Dt DOCUMENT_TITLE .Os > > > > .Sh NAME .Sh NAME > > .Nm name .Nm foo > > .Nd one line description of name .Nd a description goes here > > .Sh LIBRARY .Sh LIBRARY > > .Sh SYNOPSIS .Sh SYNOPSIS > > .Sh DESCRIPTION .Sh DESCRIPTION > > .Sh IMPLEMENTATION NOTES .Sh IMPLEMENTATION NOTES > > > > .Sh RETURN VALUES .Sh EXIT STATUS > > .Sh ENVIRONMENT .Sh RETURN VALUES > > .Sh FILES .Sh ENVIRONMENT > > .Sh EXIT STATUS .Sh FILES > > .Sh EXAMPLES .Sh EXAMPLES > > > > .Sh DIAGNOSTICS .Sh DIAGNOSTICS > > .Sh COMPATIBILITY > > .Sh ERRORS .Sh ERRORS > > .Sh SEE ALSO .Sh SEE ALSO > > .Sh STANDARDS .Sh STANDARDS > > .Sh HISTORY .Sh HISTORY > > .Sh AUTHORS .Sh AUTHORS > > .Sh CAVEATS > > .Sh BUGS .Sh BUGS > > .Sh SECURITY CONSIDERATIONS > > > > It is desirable that we not diverge in this regard and Ruslan's initial > > motive for putting EXIT STATUS after FILES in FreeBSD has to do with how > > POSIX is structuring their manpages. > > > > So I'd like to get some consensus on where we should put EXIT STATUS and > > I'd also like a vote on if COMPATIBILITY should be included as a > > standard section enforced by mdocml. > > > > Please discuss! > > Uli > > -- > > not voting, but i can tell you what is standard for openbsd pages - we > have neither exit status nor compat sections. we did away with exit > status i think because it was too silly to have a section just saying > "the app exits blah"; we did away with COMPATIBILITY because the > potential overlap with STANDARDS was making the structurer of the pages > poorer (we just rolled it all in to STANDARDS). > > so i personally wouldn;t want mandoc complaining that these sections > were missing. To clarify, none of these sections shall become mandatory. It's just the ordering that mandoc -Tlint would complain about iff such a section exist. I did a quick grep over the OpenBSD tree and it seems that EXIT STATUS isn't really used at all, and where it is used the ordering is not impacted as there are no RETURN VALUES, ENVIRONMENT or FILES sections nearby. NetBSD however has a couple of pages where FILES or ENVIRONMENT come after EXIT STATUS and that means one of NetBSD or FreeBSD would need to change a couple of pages. Regards, Uli -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv