From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by finch.gentoo.org (Postfix) with ESMTPS id 7C82B158089 for ; Thu, 5 Oct 2023 03:12:40 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id F39612BC0EA; Thu, 5 Oct 2023 03:12:36 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [IPv6:2001:470:ea4a:1:5054:ff:fec7:86e4]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id BE7642BC025 for ; Thu, 5 Oct 2023 03:12:36 +0000 (UTC) Message-ID: Subject: Re: [gentoo-dev] [DRAFT] GLEP 84: Standard format for package.mask files From: =?UTF-8?Q?Micha=C5=82_G=C3=B3rny?= To: gentoo-dev@lists.gentoo.org, glep@gentoo.org Date: Thu, 05 Oct 2023 05:12:32 +0200 In-Reply-To: References: Organization: Gentoo Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable User-Agent: Evolution 3.50.0 Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-dev@lists.gentoo.org Reply-to: gentoo-dev@lists.gentoo.org X-Auto-Response-Suppress: DR, RN, NRN, OOF, AutoReply MIME-Version: 1.0 X-Archives-Salt: d070d971-2b7f-4fbc-9342-2b9bec16a2a3 X-Archives-Hash: 60364cfbde5a0ebee71439b980b17ee9 On Wed, 2023-10-04 at 21:43 +0300, Arthur Zamarin wrote: > Specification > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D >=20 > Header > ------ >=20 > As an opt-in GLEP for files, files which want to use this GLEP format sho= uld > define a special header line which tools should use to know the format of= the > file. This line should appear as the first non empty line after the copyr= ight > header. The line should be: >=20 > # Uses GLEP 84 format >=20 > This header should come instead of the current very long header [#CURR-MA= SK]_, > as mentioning the GLEP is enough. >=20 > Files can decide to add some extra file documentation, in which case, the > entries start after the line: >=20 > #--- END OF EXAMPLES --- >=20 > Entries Grouping > ---------------- >=20 > Each mask entry consists of 2 parts: `comments block`_ and `packages list= `_, > which aren't separated by a blank line between the 2 parts. Between entri= es, a > mandatory blank line must appear. >=20 > New entries added to the file must be inserted at the beginning, after th= e file > header. >=20 > Packages List > ------------- >=20 > Must conform to PMS sections 4.4 [#PMS-4.4]_ and 5.2.8 [#PMS-5.2.8]_. Thi= s GLEP > further limits the syntax to one item per line, without any leading or > proceeding whitespaces, no comments inside the packages list, and no blan= k > lines between items in the list. That kinda sucks. For very long masks, it is useful to be able to split the entry into subgroups. I suppose it's technically still doable via splitting the entry but that sounds a bit backwards. > Comments Block > -------------- >=20 > The comments block consists of 2 mandatory parts (`author line`_ and > `explanation`_) and one optional part (`last-rite epilogue`_). A blank li= ne to > separate the parts is optional. Trailing whitespaces should be dropped. "Trailing whitespace". >=20 > The comments block is prefixed with a "#" symbol. The comments should be "The lines in the comment block are ..." > separated with single space from the "#", unless this is trailing whitesp= ace, > in which case it should be removed (meaning blank lines in comments block= are > just "#\n"). >=20 > The lines of the comments block should use column wrapping of 80 characte= rs > (including the "#" prefix). The author line is excluded from this maximum > width. >=20 > For simplifying the explanation, we wouldn't mention the "#" prefix. "To simplify the specification, the following sections will skip mentioning the "#" prefix." (still imperfect) > Explanation > ''''''''''' >=20 > In this block the reasons for the block should be listed, with extra "Block" in two meanings, confusing. > explanation where needed. If referencing bugs, use the `bugs list`_ forma= t > (mask rendering tools should render mentioned bugs also in this part). >=20 > In this part, a paragraph separator is a blank line, similar to ReStructu= redText > format. Using multiple blank lines between paragraphs is prohibited. >=20 > Last-Rite Epilogue > '''''''''''''''''' >=20 > If the last paragraph starts with "Removal after", then this mask entry i= s > considered as last-rite mask, and the last paragraph must conform to the > last-rite epilogue format. This is inconsistent with the current usage, and confusing. "After" makes it unclear whether the list is inclusive (i.e. "remove on that day or later") or exclusive ("remove the next day or later"), and in the latter case it's quite backwards. --=20 Best regards, Micha=C5=82 G=C3=B3rny