From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-02.scc.kit.edu (scc-mailout-kit-02.scc.kit.edu [129.13.231.82]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 0dde501e for ; Mon, 29 May 2017 20:15:41 -0500 (EST) Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-02.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1dFVl5-0002Zv-6p; Tue, 30 May 2017 03:15:40 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1dFVl3-0001Di-95; Tue, 30 May 2017 03:15:37 +0200 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1dFVl1-0007V6-Te; Tue, 30 May 2017 03:15:36 +0200 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id 1338c2fa; Tue, 30 May 2017 03:15:35 +0200 (CEST) Date: Tue, 30 May 2017 03:15:35 +0200 From: Ingo Schwarze To: Yuri Pankov Cc: discuss@mdocml.bsd.lv Subject: Re: move roff sections to a separate file Message-ID: <20170530011535.GC54102@athene.usta.de> References: <20170529234717.GA54102@athene.usta.de> <5b13e76b-8d21-92c8-dcb3-6dddb6d9480b@gmx.com> 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: <5b13e76b-8d21-92c8-dcb3-6dddb6d9480b@gmx.com> User-Agent: Mutt/1.6.2 (2016-07-01) Hi Yuri, Yuri Pankov wrote on Tue, May 30, 2017 at 03:09:06AM +0300: > On Tue, 30 May 2017 01:47:17 +0200, Ingo Schwarze wrote: >> 3. Technically, i don't like the concept of *.in files at all. >> They make reading the code harder, as they are neither fish nor >> fowl, neither proper, readable C code, nor proper, readable *.h >> headers. I want to slowly get rid of them. I have deleted a >> few already and hope to continue in that direction, even if not >> with terribly high priority. But i certainly don't want to add >> any more of them. > That's unfortunate as .in files allow us to keep the man sections > (msec.in) and library (lib.in) descriptions separate of the code Oh. Yeah. Don't panic about those two. Regarding msec.in, that's the one of these files where i don't see any realistical chance to get rid of it in any forseeable future. That indeed varies so wildly among systems for historical reasons that there is little hope of convergence. Regarding lib.in, i had half forgetten about it already because it was deleted from OpenBSD long ago. We don't use the .Lb macro at all. But lib.in was expressly kept in the portable distribution because illumos isn't the only system out there that likes grooming a bewildering zoo of libraries. Free, Net, and DragonFly rely on that too, so it's not going away either. But as soon as i have to touch st.c for some reason, st.in is likely to die, and one day, predefs.in might get swallowed up by roff.c, or by a similar file in the neighbourhood. [...] > We have CONTEXT section after RETURN VALUES. Hmmm. You have a point here. We added that section recently in OpenBSD, and maybe it was premature to make it public in this way. I'm currently working on a -Wstyle message level. That is likely to need some system dependencies anyway. I haven't worked out the required concepts of system dependency yet, but hope to keep them as simple as possible. Maybe that will yield a natural solution. For the next update of your tree (probably to 1.14.1), i suggest that you simply maintain a local 4-line patch for CONTEXT; it shouldn't be too burdensome, the enum doesn't change that frequently upstream. I'll try that you can get rid of it again. In case i forget, it might be useful to remind me in the context of the *next* update after that. > The sections I listed below are standard for us, so there's a need > to order them properly. [...] > We have the following sections in our man pages that aren't present > currently in validation, and I don't think it'd make sense to add > them as generic ones: > > INTERFACE LEVEL (after SYNOPSIS and before DESCRIPTION) > CODE SET INDEPENDENCE > INTERFACE STABILITY > MT-LEVEL I see. NetBSD has a similar need, they use COMPATIBILITY, CODE REFERENCES, and SECURITY CONSIDERATIONS in some pages and want those in a specific order. While migrating functionality from mdoclint(1) to mandoc(1) -Wall, i have to find a solution for that anyway, so that will very likely solve the task for you, too. The peculiar ordering of CONTEXT in OpenBSD is of the same kind, i think. While issues like SEE ALSO before DESCRIPTION are WARNINGS (such an order would be wrong on any system), the system-specific checks will probably end up in the lower STYLE message level, but that shouldn't be a problem for you. So i think i know now what i need to know when doing the (low-intensity) work on the message system during the next few months. Yours, Ingo -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv