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

-----BEGIN PGP SIGNATURE-----

iQFDBAEBCAAtFiEEtDnZ1O9xIP68rzDbUYgzUIhBXi4FAmUMtBMPHHVsbUBnZW50 b28ub3JnAAoJEFGIM1CIQV4uCsMIAMDpEHdBaNPHjHiwjr5EXGMdGxZsCl4AU7e3 TKk8lDAM3ZqyqfB5o9TpQXfUn+mOfzF0xEbmPn6fIUd1BYuQVf1FBGoBwWK7/XbA 4WGyVHu4gAyv8DSm3ZHrf3Xd3HMGrcFaKsyU65xmw9eR8ryAZI1JX1ezXAVG4Fsz svUyT3VIA6cs+1yJq0gnqQ/kOvGP26IWzgYQvOkrT/eDkwgBlFbKQjKbI9Z4Foxe JKDHGBnNiHACUNt15nRRa1cT/+g4gCX9ph7SSjE0DZhqfMJ4qwiNsstvjib2HYul wFrbZyzJzxbNbnNT+7804Fw+DF7YeLGUKPNZAJ3PSxxeUgXRnqs=
=rL8j
-----END PGP SIGNATURE-----

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)

Tim Harder <radhermit@gentoo.org> writes:

On 2023-09-21 Thu 15:22, Ulrich Mueller wrote:

On Thu, 21 Sep 2023, Arthur Zamarin wrote:

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.

To me standardizing a format in Gentoo (outside of PMS-related
functionality) requires a GLEP or at the very least some semi-formal documentation outside the file in question in a place like the
devmanual. Consider it due diligence of the process that allows people writing code to target the format without having to chase details down
into code bases or mailing list threads.

+1

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)

On 2023-09-21 Thu 15:22, Ulrich Mueller wrote:

On Thu, 21 Sep 2023, Arthur Zamarin wrote:

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.

To me standardizing a format in Gentoo (outside of PMS-related
functionality) requires a GLEP or at the very least some semi-formal documentation outside the file in question in a place like the
devmanual. Consider it due diligence of the process that allows people
writing code to target the format without having to chase details down
into code bases or mailing list threads.

OTOH, we don't have a GLEP for eclassdoc either.

This is a poor example since it's partly the reason why an awk script
with issues relating to extensibility and maintainability is still used
to generate eclass manpages.

I mainly let it slide when writing pkgcore/pkgcheck parsing
functionality because the devmanual [0] was a passable resource at the
time.

Tim

[0]: https://devmanual.gentoo.org/eclass-writing/#documenting-eclasses

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)

On Thu, Sep 21, 2023 at 22:40:05 +0300, 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.

What about mandatory blank line(s) between entries? That way it ensures
they are visually separated when skimming through the file. Plus, you
can easily jump from entry to entry in editors that support
paragraph-wise movement.

- Oskari

-----BEGIN PGP SIGNATURE-----

iHUEABYIAB0WIQQfOU+JeXjo4uxN6vCp8he9GGIfEQUCZQ0RIAAKCRCp8he9GGIf EX8kAQDuMOxiJGHkdNoYkb1qQ722QNnY3lYZbZlwnvVrquuUywD/Y/7EX2EjG7IR XYIHEKqcumCZJgF2BHQQkVQK91gI1w0=
=ceJu
-----END PGP SIGNATURE-----

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)

On Thu, Sep 21, 2023 at 23:22:27 +0200, 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.

I read it to mean something like this would be allowed:

# Blurb about package1, package2, and package3
category/package1
category/package2

category/package3

Whether it makes sense to allow that is a different question.

- Oskari

-----BEGIN PGP SIGNATURE-----

iHUEABYIAB0WIQQfOU+JeXjo4uxN6vCp8he9GGIfEQUCZQ0QDAAKCRCp8he9GGIf EYi6AQC76DO/Ip/xEx3KJHoaNfevheb++Iohtn9jyj50OscEogEA/7sfh3kUy2o9 um6pgLnAP6w6tp3Jwi8XAxomTNBDqgQ=
=s3fI
-----END PGP SIGNATURE-----

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)

On Fri, 22 Sep 2023, Oskari Pirhonen wrote:

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.

What about mandatory blank line(s) between entries? That way it ensures
they are visually separated when skimming through the file. Plus, you
can easily jump from entry to entry in editors that support
paragraph-wise movement.

Yes, please. Mandatory blank lines between entries, and no blank lines
(or lines containing only whitespace) within entries. Especially, no
blank lines in the list of packages.

-----BEGIN PGP SIGNATURE-----

iQFDBAEBCAAtFiEEtDnZ1O9xIP68rzDbUYgzUIhBXi4FAmUNXKUPHHVsbUBnZW50 b28ub3JnAAoJEFGIM1CIQV4urFYIALSVVw09Rc0t+1mEix2DhDPEEG/lhaMqbAL3 K9xxoFYUv8rYimippUpbqWumfMo36XBElidPuQ0yRAmF4hKn3A/frle2xS+iLpAs 7Ta5lbggea89faqJ73nTg/jVOzzIwQw5i7dcrVynXsuYDnjqKBnx4HnprzAH2wIl 38oWpZNV7XE4TtTNXoaS8eDSyovC2V7XK4UqX+ROQWmRh8SdcrZJ8lJj2R68Tva0 d6bm1mo9W5Jlvzl/6xaKk8ZyUoI3udqHNxsZfUMvGtUPcV1tcBjDAsNH7eny21rt PEO27hKJBv2qAoeAV6g28PPTWxvFJSvBPoZC0PqwSW+EHTHRc7o=
=Cu7C
-----END PGP SIGNATURE-----

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)

This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --------------pst3CxFj2i20FEfnVm8MimU0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

On 22/09/2023 12.21, Ulrich Mueller wrote:

On Fri, 22 Sep 2023, Oskari Pirhonen wrote:

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.

What about mandatory blank line(s) between entries? That way it ensures
they are visually separated when skimming through the file. Plus, you
can easily jump from entry to entry in editors that support
paragraph-wise movement.

Yes, please. Mandatory blank lines between entries, and no blank lines
(or lines containing only whitespace) within entries. Especially, no
blank lines in the list of packages.

Yeah I agree. Originally I wanted to allow blank lines between packages
in same entry (to enable you to group them), but as further
considerations and your input, this is a bad idea (if you want to divide
the group, create separate entries).

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


--------------pst3CxFj2i20FEfnVm8MimU0--

-----BEGIN PGP SIGNATURE-----

iQEzBAEBCgAdFiEE/axFlFuH2ptjtO5EAqCvUD0SBQQFAmUNY/0ACgkQAqCvUD0S BQR+nwgAlI/XsnhIGTj2+3Od/z9QSP5qGcV8PRRSowU7A1pHfrdt6ZS5dQrDp+Mv CxhBg7yoMZNOjS4LzMw3ValP+9aCmvJMtrnsxiQTTQkp9jHVHG39nNYvW5k/4MtU GIBl+y/KWuZKGqgC4Zy6bHzDydDqRu/jwQ5c64JOlLysbwuDnTlJNIJJ5uLM/I4u vJ2SeIhwU2iUdLyTjI0fsKEyCkbSZ4dFhtmeQn5FwZKelbvVCrlQEVDfBsLsBgGI JAZV4tKPmSwl11BRqlcw53QBaRiIgyLs8GpRHX0OfWRDiDaFi819/SAT0lMO58AV iBQ1y62GCkydFbbahp0ybOsHYCSq1Q==
=Zzr2
-----END PGP SIGNATURE-----

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)

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)