On 05/10/2023 21.40, Ulrich Mueller wrote:
>>>>>> On Wed, 04 Oct 2023, Arthur Zamarin wrote:
> 
>> Files can decide to add some extra file documentation, in which case, the
>> entries start after the line:
> 
>>     #--- END OF EXAMPLES ---
> 
> This agrees with current package.mask, but seems rather specific.
> Instead of reinventing the wheel, maybe a "scissors line" could be used,
> i.e. a line consisting mainly of "-", ">8" and "8<", similar to the line
> used by git-mailinfo?
> 
> I'm also wondering if we shouldn't have a similar marker for the end of
> the mask entries, i.e. everything after it would be ignored. This isn't
> currently needed for package.mask, but other files in profiles have an
> Emacs local variables block or a Vim modeline at the end.
> 
> Ulrich

After fast discussion on #gentoo-dev IRC between me and ulm, we agreed
that the "scissors line" from git-mailinfo would be very overkill and
also very complicated to implement.

So we agreed on something simpler and good enough. Comment line
containing at least 5 "-" on beginning and end. As regex:

# -{5,}.*-{5,}

All lines before first occurrence of such line (except the GLEP header
to opt in) are ignored as generic comments not part of mask, and all
lines after second occurrence (if exists) are also ignored.

Those lines are optional, which does mean that implementation should
firstly filter out the ignored part (before first time if found, and
after second time if found), and only that part parse. This means
implementing it as a straight stream is much-much harder, but since the
file are never very big, I think it won't impact performance to perform
multiple text runs.

-- 
Arthur Zamarin
arthurzam@gentoo.org
Gentoo Linux developer (Python, pkgcore stack, Arch Teams, GURU)