On 22/09/2023 00.22, Ulrich Mueller wrote:
>>>>>> 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.
Agreed, poor choice of words.
>> 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").
Hmm, yeah, rereading my text shows I've over-complicated it. What I
wanted is that last paragraph (yes, if there are many bugs it might wrap
into new line) can be not separated with blank line from "main
explanation block".
> 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.
Good point, and I should address it as you recommended. I will mention
the ignore-until-this-line, and that new entries should be added as
first entry after that ignore-until-this-line.
>> 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.
Yeah, after all the input, yes, I will work on a formal GLEP. It will
take time, but I hope to prepare a first draft in the coming 2 weeks.
> Ulrich
--
Arthur Zamarin
arthur...@gentoo.org
Gentoo Linux developer (Python, pkgcore stack, Arch Teams, GURU)
OpenPGP_signature.asc
Description: OpenPGP digital signature
