Re: [gentoo-dev] Standard parsable format for profiles/package.mask file

[Ulrich Mueller <ulm@gentoo.org>]

[-- Attachment #1: Type: text/plain, Size: 2401 bytes --]

>>>>> On Thu, 21 Sep 2023, Arthur Zamarin wrote:

> ===== "Formal" format =====

> Each entry is composed of 2 parts: "#"-prefixed explanation block and
> list of "${CATEGORY}/${PN}" packages. Entries are separated when a new
> explanation block starts (meaning first "#"-prefixed line after packages
> list). You may add newlines between packages in packages list.

"Must" rather than "may" here? You certainly cannot list several
packages in the same line.

> The first line of the "#"-prefixed explanation block must be of the
> format "${AUTHOR_NAME} <${EMAIL}> (${SINGLE_DATE})" when the date is of
> format YYYY-MM-DD, in UTC timezone.

> If this is a last-rite message, the last line must list the last-rite
> last date (removal date) and the last-rite bug number. You can also list
> other bugs relevant to the last-rite. So I think a format of: "Removal
> on ${REMOVAL_DATE}.  Bug #NNNNNN, #NNNNNN." Where the bug list is comma
> and space separated, we have at least one space (" +" regex) between the
> removal date and bug list, and the date is of YYYY-MM-DD format.
> I prefer this line is separate (and not continuous of prefix message text).

> The explanation block itself can reference bugs, by matching the regex
> "[Bb]ugs? #\d+(, +#\d+)*" (For example: "bug #713106, #753134"). I think
> this is quite a simple one, but powerful enough for most.

> Lines with single newline between them (so no blank line between them)
> are considered as single paragraph continuum. If you want to start new
> paragraph, leave a blank line (still prefixed with #) - think similar to
> markdown. A line matching the last-rite line is always it's own paragraph.

Is this rule about paragraphs needed? It is at odds with the rule that
the removal date and bug must be on their own line (i.e. that line is
_not_ part of a "paragraph continuum").

What about the introductory comment block in the file? Should there be a
defined syntax for a separator between it and the rest of the file? For
example, everything above the first line matching "^#[ \t]*---" could be
ignored by automatic tools, and they would insert new entries below that
separator.

> Should it be a GLEP, I don't think so? But I'm unsure about it. We do
> need to document it (for example header of that exact file).

It shouldn't be too difficult to wrap this up as a GLEP. OTOH, we don't
have a GLEP for eclassdoc either.

Ulrich

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 507 bytes --]