This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --------------5YHmV7ngiv4PsKyNciP69FRX
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
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
arthurzam@gentoo.org
Gentoo Linux developer (Python, pkgcore stack, Arch Teams, GURU)
--------------5YHmV7ngiv4PsKyNciP69FRX--
-----BEGIN PGP SIGNATURE-----
iQEzBAEBCgAdFiEE/axFlFuH2ptjtO5EAqCvUD0SBQQFAmUNhLEACgkQAqCvUD0S BQQBQgf6AmlC7bEWgExuZGfcst21aKglwn5gkbiJYfJzGtb2FsBFPdIjnWx6UvY+ lDWh4+rnzWkUEJggnpclcIC1WpPjvL9BBO/IhJpYBn+923/TJ4eYQEF5waCmnECL LPRldAs3E7pZs4fie0QCOJsfX5VMHQLEq1UWaNAJcTdPXJpKuHov/Dnt6N76IIdS Ki4ETTaVFOK8jffpHjdM+kmHHnB1D1qTizkx2qPTYg7Ge66HFPVav3Z/V6FCX5uX vJIhYbDo0mh3omRugA008VbSGQeybpKJwfBw9DgJmrqFKh1dZx8wMxNM0UV3/Mp5 YPkQHhUfmoS+wXzTYEsXOziR/7duog==
=v5Wp
-----END PGP SIGNATURE-----
--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)