Re: [gentoo-dev] [DRAFT] GLEP 84: Standard format for package.mask files

["Michał Górny" <mgorny@gentoo.org>]

On Wed, 2023-10-04 at 21:43 +0300, Arthur Zamarin wrote:
> Specification
> =============
> 
> Header
> ------
> 
> As an opt-in GLEP for files, files which want to use this GLEP format should
> 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 copyright
> header. The line should be:
> 
>     # Uses GLEP 84 format
> 
> This header should come instead of the current very long header [#CURR-MASK]_,
> as mentioning the GLEP is enough.
> 
> Files can decide to add some extra file documentation, in which case, the
> entries start after the line:
> 
>     #--- END OF EXAMPLES ---
> 
> Entries Grouping
> ----------------
> 
> 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 entries, a
> mandatory blank line must appear.
> 
> New entries added to the file must be inserted at the beginning, after the file
> header.
> 
> Packages List
> -------------
> 
> Must conform to PMS sections 4.4 [#PMS-4.4]_ and 5.2.8 [#PMS-5.2.8]_. This GLEP
> further limits the syntax to one item per line, without any leading or
> proceeding whitespaces, no comments inside the packages list, and no blank
> 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
> --------------
> 
> The comments block consists of 2 mandatory parts (`author line`_ and
> `explanation`_) and one optional part (`last-rite epilogue`_). A blank line to
> separate the parts is optional. Trailing whitespaces should be dropped.

"Trailing whitespace".

> 
> 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 whitespace,
> in which case it should be removed (meaning blank lines in comments block are
> just "#\n").
> 
> The lines of the comments block should use column wrapping of 80 characters
> (including the "#" prefix). The author line is excluded from this maximum
> width.
> 
> 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
> '''''''''''
> 
> 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`_ format
> (mask rendering tools should render mentioned bugs also in this part).
> 
> In this part, a paragraph separator is a blank line, similar to ReStructuredText
> format. Using multiple blank lines between paragraphs is prohibited.
> 
> Last-Rite Epilogue
> ''''''''''''''''''
> 
> If the last paragraph starts with "Removal after", then this mask entry is
> 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.



-- 
Best regards,
Michał Górny