From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mout.gmx.net (mout.gmx.net [212.227.17.22]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 0ad0ad47 for ; Mon, 29 May 2017 19:09:13 -0500 (EST) Received: from [192.168.1.2] ([188.162.166.40]) by mail.gmx.com (mrgmx103 [212.227.17.174]) with ESMTPSA (Nemesis) id 0MZU7V-1dU8OR0l2L-00LFp3 for ; Tue, 30 May 2017 02:09:10 +0200 Subject: Re: move roff sections to a separate file To: discuss@mdocml.bsd.lv References: <20170529234717.GA54102@athene.usta.de> From: Yuri Pankov Message-ID: <5b13e76b-8d21-92c8-dcb3-6dddb6d9480b@gmx.com> Date: Tue, 30 May 2017 03:09:06 +0300 User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:52.0) Gecko/20100101 Thunderbird/52.1.1 X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv MIME-Version: 1.0 In-Reply-To: <20170529234717.GA54102@athene.usta.de> Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 7bit X-Provags-ID: V03:K0:YN8R/xGXAdk0Jo4nWPEKT9VJKusp0nWkaL3Nlrsk3ptZGdRJjt9 tBqHHfazlUDE5qk1IRYv2t8NCfwhRuZV/btvaGXNv5q38O7YRnkkuNawUl4pY3dxww4Qhnh YG+t+BTbR5/kG1co736u15RhWHetWNQaGLSTfGhyA1/LOxzDL2lhUhqYqhfh5Vv9azkLGNW hWza5vuApFqiyHGAVCrow== X-UI-Out-Filterresults: notjunk:1;V01:K0:+w4RNIDafE8=:OBZBKMkW2RrQ8lLNagrg/U AEIEXIYvlkTCBMMTrBjsYueOrNDbw7JPr7Elzd/G6vwxgqs6ndtNl+SmaAvpuVBV1Cl7BdfKu GA9fuO7Th5yazcYm+GOkz02iTV4p2aW8OaU6BAc2T3eaX6cQmSBmPjnwTl4l3mWSBmbwok90C 76dAFmosfC4Fa3l8KpV2Pyliw4+0lZopHU2lxDm+MwmmWjcLe9wkrJD7MJELHMn07dAiBChs/ jlcdBubs21ihRGSRdTnNm3vLoYGvV0iWRjpkPIw4WZBEevImJ1AVxTZcHgus5V20jVQ4gZr1B Mbn/w/s8TLBBkF/VwrmmzjUwyVjpsNZrabVTd8PwvwrYF3rhSt4jO5Gh1x23SgxWkoVYzLLS1 fU71ndWzveKfnZPcKEPcx+Zom4+gtgzAn07s6LSXbouMmhCfXDMEuHGbJbgiCge/Qr1y+Fgbm vX1LpKR8DpNmDCkElWXma3hXMQd2Z2ikOna9jq5fwjcH9OGyyAskezAZ1pBpSoogQOsAa6D86 rPGDpnUODgyxtiMB7bpkaq2W55MG+XtkyTkM/1Om0ytIWrEc1QlXGpTCMU/DLmD+8XzVuTk76 YfYCJsjP9dZjVL2cZE0ZWFmRn9FpgsroYfWooFLPb6wq0bAey4ghn9RBBhIJnYZ0q2nv6TnQ4 3CABKh41KX96/GKnIlN+eRB4v5Gh5UUelKgMXtQeojMi1o8hDxiBZKkAwizPW/m0FUBxNQMOA bQIuSyM8KIPS8NvT6teLkre23o+MfMWvCkTQBlaeHNPHwy//Fb/i7rJgUYvypKRhaWVoLEdAB M3Z+ce3GhrBfFzgCQp87eNprO2aiA== On Tue, 30 May 2017 01:47:17 +0200, Ingo Schwarze wrote: > Hi Yuri, > > Yuri Pankov wrote on Tue, May 30, 2017 at 01:14:35AM +0300: > >> I'd like a propose a small change which would simplify maintaining a >> downstream version for us (as we need it modified and with a bit changed >> order) - move list of sections (roff_sec) and their descriptions (secnames) >> to separate file which we keep without a need to sync with upstream, >> roffsec.in. Patch is pretty straightforward and simply moves both there. > > I see why such small differences can be a bother in maintenance, > but i don't like the direction this is going. > > 1. I'd like to encourage more consistency in manual page organization > across different systems, not facilitate divergence. Section > naming and ordering is an area where existing differences are > relatively mild, and making this aggressively configurable > really seems like pushing into the wrong direction to me. > > 2. Besides harming users by promoting gratuitious differences among > platforms, such configurability also impedes flexibility of > development because - even keeping the user-visibile functionality > constant - the implementation cannot be modified when *.in-style > interfaces are promised to downstream systems. > > 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 updates, see: https://github.com/illumos/illumos-gate/blob/master/usr/src/cmd/mandoc/lib.in https://github.com/illumos/illumos-gate/blob/master/usr/src/cmd/mandoc/msec.in That's where we historically differ from BSD section layout, and it's (sadly) not going to change soon. > 4. Your specific patch is incorrect. > "static const char * const secnames[SEC__MAX]" > is not a declaration, but a definition. > So if it goes into an *.in file, that *.in file cannot be > included in any *.h file, but only in one *.c file, because > otherwise every *.o file using the *.h file gets its own copy > of the array. > But enum roff_sec *is* needed in roff.h, so you are stuck. It works as it's *static*, but I do agree that it's ugly, it was more an idea than actual patch. > I don't think you should try to fix the technicality (4) because > that will only make the patch yet uglier, aggravate (3), and not > solve the more fundamental issues (1) and (2) in the least. > > > To help finding a solution, i should like to understand the scope > of the issue better. > > Which sections specificially do you want to order in which > non-standard way? > > Is there any other, specific issue except ordering that you would > like to change? If so, which one? We have CONTEXT section after RETURN VALUES. > Note that, if you simply use some additional, non-standard sections > in some pages, i'm not convinced they need to be listed at all. > They should work just fine as SEC_CUSTOM. The sections I listed below are standard for us, so there's a need to order them properly. > Then again, if a section name is sufficiently widespread, we > usually carry it even if it is not used in every system (e.g. LIBRARY). > If you think there is such a case of a section name used by many, but > not by all systems, that ought to be added, which one is it? 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 Having separate .in file would allow us having our own ordering rules while making updates easier - we do NOT modify any of the mdocml source except for customized .in files. To sum it all up, the differences are for historic reasons, and not something that can be changed easily, hence the request. -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv