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.
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.
The comments block is prefixed with a "#" symbol. The comments should be
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.
Explanation
'''''''''''
In this block the reasons for the block should be listed, with extra
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.
"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.
On Wed, 2023-10-04 at 21:43 +0300, Arthur Zamarin wrote:
Specification
=============
...
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.
On Thu, 05 Oct 2023, Arthur Zamarin wrote:
On 05/10/2023 06.12, Michał Górny wrote:
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.
Hmm, I don't really care what word we use here, but I do want us to
agree on one word (cause I'll need to update `pkgdev mask`). Some of the considerations against "on" (currently used) is the fact: does it mean
it isn't fine to remove after it?
Does English has a nice word for ">= time"?
On Thu, 05 Oct 2023, Michał Górny wrote:
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.
| Sysop: | Keyop |
|---|---|
| Location: | Huddersfield, West Yorkshire, UK |
| Users: | 475 |
| Nodes: | 16 (2 / 14) |
| Uptime: | 17:52:32 |
| Calls: | 9,487 |
| Calls today: | 6 |
| Files: | 13,617 |
| Messages: | 6,121,090 |