I really like the functionality of readme.gentoo-r1.eclass, as it
allows to communicate Gentoo-specific information about a package to
the user. Especially as it improves the signal-to-noise ratio of
messages arriving to our users.

However, readme.gentoo-r1.eclass will only show this information on
new installs, but not if the information changed. This is a major
drawback. Furthermore, readme.gentoo-r1.eclass does not provide an API
to assemble the information via heredoc.

The following patch includes a new eclass named "greadme", that
addresses those shortcomings of readme.gentoo-r1.eclass and hopefully
can be seen as a general overhaul.

This is a first draft of the eclass and therefore I'd like to ask for
feedback.

The greadme.eclass contains some TODO items at the end of its
@DESCRIPTION.

The main item is doc compression. Right now, greadme.eclass defaults
to add the readme doc to the compression exclusion list via
"docompress -x". A mode where the readme doc is compressed, just as readme.gentoo-r1.eclass does, can be activated by setting
_GREADME_COMPRESS. However, I believe this mode is fragile as it can
not be guaranteed that a binary for the used compression algorithms is installed on the host [1].

I believe it is reasonable to simply install the readme doc
uncompressed, since they are typically only a few lines long. However,
if anyone can point out a way to achieve the desired functionality with
a compressed readme doc, then please let me know.

Thanks for reviewing the eclass.

Florian Schmaus (1):
greadme.eclass: new eclass

eclass/greadme.eclass | 281 ++++++++++++++++++++++++++++++++++++++++++
1 file changed, 281 insertions(+)
create mode 100644 eclass/greadme.eclass

--
2.41.0

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

This new eclass is similar to readme.gentoo-r1.eclass. The main
differences are as follows. Firstly, it also displays the doc file
contents if they have changed. Secondly, it provides a convenient API to install the doc file via stdin.

Signed-off-by: Florian Schmaus <flow@gentoo.org>
---
eclass/greadme.eclass | 281 ++++++++++++++++++++++++++++++++++++++++++
1 file changed, 281 insertions(+)
create mode 100644 eclass/greadme.eclass

diff --git a/eclass/greadme.eclass b/eclass/greadme.eclass
new file mode 100644
index 000000000000..ac83c36983ef
--- /dev/null
+++ b/eclass/greadme.eclass
@@ -0,0 +1,281 @@
+# Copyright 1999-2024 Gentoo Authors
+# Distributed under the terms of the GNU General Public License v2
+
+# @ECLASS: greadme.eclass
+# @MAINTAINER:
+# Florian Schmaus <flow@gentoo.org>
+# @AUTHOR:
+# Author: Florian Schmaus <flow@gentoo.org>
+# @SUPPORTED_EAPIS: 6 7 8
+# @BLURB: install a doc file, that will be conditionally shown via elog messages
+# @DESCRIPTION:
+# An eclass for installing a README.gentoo doc file recording tips
+# shown via elog messages. With this eclass, those elog messages will only be +# shown at first package installation or if the contents of the file have changed.
+# Furthermore, a file for later reviewing will be installed under
+

On Sat, 2024-01-06 at 18:01 +0100, Florian Schmaus wrote:

I really like the functionality of readme.gentoo-r1.eclass, as it
allows to communicate Gentoo-specific information about a package to
the user. Especially as it improves the signal-to-noise ratio of
messages arriving to our users.

However, readme.gentoo-r1.eclass will only show this information on
new installs, but not if the information changed. This is a major
drawback. Furthermore, readme.gentoo-r1.eclass does not provide an API
to assemble the information via heredoc.

Are you implying that readme.gentoo-r1 is unfixable and you need to
start over, and have a third generation of eclasses to install a readme
file?

The main item is doc compression. Right now, greadme.eclass defaults
to add the readme doc to the compression exclusion list via
"docompress -x". A mode where the readme doc is compressed, just as readme.gentoo-r1.eclass does, can be activated by setting
_GREADME_COMPRESS. However, I believe this mode is fragile as it can
not be guaranteed that a binary for the used compression algorithms is installed on the host [1].

Dangling reference here. In any case, documentation compression is
a standard feature of the package manager. If it doesn't work for
whatever reason, I'd rather see you focus on find a good solution rather
than working it around via abusing `docompress -x`. It's basically
a case of "standard feature X doesn't work for me sometimes, so I now
randomly disable X via my eclass, and hope nobody notices".

I believe it is reasonable to simply install the readme doc
uncompressed, since they are typically only a few lines long. However,
if anyone can point out a way to achieve the desired functionality with
a compressed readme doc, then please let me know.

The compression mechanism automatically detects when the file is too
small to be worth compressing. See PORTAGE_DOCOMPRESS_SIZE_LIMIT.


--
Best regards,
Michał Górny


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

iQFGBAABCgAwFiEEx2qEUJQJjSjMiybFY5ra4jKeJA4FAmWZjCMSHG1nb3JueUBn ZW50b28ub3JnAAoJEGOa2uIyniQOTPEIAIWZcwy1SLlra1ugLDRLhxihB2kp4JoF JEHGh7j3HbJs1FpthxwQ0EwtRPeLDvi9uJIKijLBoLJfcQ4Jh/L936yzSomWF2fo RmDEMFanccasWgdCOYgdibs0/l1wijfzWk4p6EXY8r6tLuTeyPd8zcoUrrhXpY1Z iUqmEbMLthTFH6jBJo1Awgt2QOGZWydSB0/q4tgKLLFn1karGZY1mIFAvubppbPz 6aR1CFw7PSsDriX9WvfBZ4oF8mcn9KghCkr0qqLrVIAPwhTT/BeNL132pzkZ/GSB cnmtvphXOOXWyjt1CoHsyPj4Ycr9eaT/wgyuCA3T3Th1UHXpjLyhncg=
=GG69
-----END PGP SIGNATURE-----

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

On Tue, 2024-01-09 at 09:30 +0100, Florian Schmaus wrote:

On 06/01/2024 18.21, Michał Górny wrote:

On Sat, 2024-01-06 at 18:01 +0100, Florian Schmaus wrote:

I really like the functionality of readme.gentoo-r1.eclass, as it
allows to communicate Gentoo-specific information about a package to
the user. Especially as it improves the signal-to-noise ratio of
messages arriving to our users.

However, readme.gentoo-r1.eclass will only show this information on
new installs, but not if the information changed. This is a major drawback. Furthermore, readme.gentoo-r1.eclass does not provide an API
to assemble the information via heredoc.

Are you implying that readme.gentoo-r1 is unfixable and you need to
start over, and have a third generation of eclasses to install a readme file?

Not at all. See the second item of the TODO list in the eclass' description.

That said, both eclasses are rather small,

Since when, 300 lines to install a README file is "small"?

The main item is doc compression. Right now, greadme.eclass defaults
to add the readme doc to the compression exclusion list via
"docompress -x". A mode where the readme doc is compressed, just as readme.gentoo-r1.eclass does, can be activated by setting _GREADME_COMPRESS. However, I believe this mode is fragile as it can
not be guaranteed that a binary for the used compression algorithms is installed on the host [1].

Dangling reference here. In any case, documentation compression is
a standard feature of the package manager. If it doesn't work for
whatever reason, I'd rather see you focus on find a good solution rather than working it around via abusing `docompress -x`.

The problem is the lack of a guarantee that the utilities required to decompress the file are available at installation time.

It's user's responsibility to ensure that the tools set in their
make.conf are available.

It gets even worse if you consider binpkgs, as you have surely read the comment while looking at the code of the greadme.eclass.

See FEATURES=-binpkg-docompress. That's the correct way to distribute
binary packages.


--
Best regards,
Michał Górny


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

iQFGBAABCgAwFiEEx2qEUJQJjSjMiybFY5ra4jKeJA4FAmWdGP4SHG1nb3JueUBn ZW50b28ub3JnAAoJEGOa2uIyniQOHgcH/AscEm4B27arzHihuMCGiHSaAqG3yo/I yZtuXuVfAyaqYZfXIUUcOQOj7zn9uDCqLgwYm2WA4P+rCSX1OH2izRlla05grkh/ ir+9x3Mh5J5NT+zrI85IYKf/L29mETSH7dm2SfXrTifrR1MmJ4Qf9XSB7RUGZNv0 JzgSSCl0qCKjFimLXu6HD4qILHNYJ+YCjqAKT1lmJDlqbI+j4/cvyui+z6/pImTR Qo6nKxhpjIc7HLxwAWfLuMe6PXFpj3qYucw08odGtNVXqulosvrKg7YvXMxeNOrv yrg7ZBnWkiOr/9uvv8/jtIP03oDNwXMgBohOoJipAhzfHoxDuWCUaSY=
=iMKu
-----END PGP SIGNATURE-----

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

On Tue, 2024-01-09 at 11:39 +0100, Florian Schmaus wrote:

Even if we say it is the user's fault, then the problem of handling a decompressor failure would still exist. The eclass does not gracefully continue when decompressing the doc file, but instead it runs into a
die(). To address this we would need to make unpacker.eclass and
unpack() aware of nonfatal. The latter would require a PMS change.

Or, I could duplicate unpack logic --- which is probably a lot to
account for the various compression options --- in the eclass. But I
suspect be both do not want that.

Perhaps this is the moment when you realize that there is no guarantee
that unpacker.eclass and/or unpack will support the compression format
set for docompress. The two were never intended to interact.

--
Best regards,
Michał Górny


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

iQFGBAABCgAwFiEEx2qEUJQJjSjMiybFY5ra4jKeJA4FAmWdI00SHG1nb3JueUBn ZW50b28ub3JnAAoJEGOa2uIyniQOn8QH/isYDxIqCPNtjhrlYvYuExGmEIzZTVnU mBwKbRvwyf7S/6yjn/vEth0Y09ifKIRCqmCiTALjnUE2tiLG6/ox1dDxxDVjxuHD etaZGmRnEkaIoDyr1w7SqRSxS+ncgPxs5YnaJ39uJWNdhDp5No1gLxv3Ff/uG7vq pBRXhR49b5sgvxpdN3c3jpjb/mC8KQe6pxtgcd06WmXbfu91iicg/Tx8Su/P9Y9v V14TA+sTGtvfQomxoH0Srf9tcEbmZgCgrmCZMCP74eYyMmiJpjd/T4xuw2sZHSpg 1qq3rb0bjXzCMZ2Iu0Q2tekQZFIX5gNeFSCKtCkPYU2ioLAO/iBqU+g=
=y3C4
-----END PGP SIGNATURE-----

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

Florian Schmaus <flow@gentoo.org> writes:

I really like the functionality of readme.gentoo-r1.eclass, as it
allows to communicate Gentoo-specific information about a package to
the user. Especially as it improves the signal-to-noise ratio of
messages arriving to our users.

However, readme.gentoo-r1.eclass will only show this information on
new installs, but not if the information changed. This is a major
drawback. Furthermore, readme.gentoo-r1.eclass does not provide an API
to assemble the information via heredoc.

The following patch includes a new eclass named "greadme", that
addresses those shortcomings of readme.gentoo-r1.eclass and hopefully
can be seen as a general overhaul.

I have a few concerns at the moment, but of varying severity:
1) The name seems odd (why not readme.gentoo-r2)?
2) Why can't the existing eclass be improved?
3) Is the reason for 2) strong enough to introduce a new eclass?
4) The compression deal seems not worth bothering with.

I don't really want to see a bifurcation in our README eclasses
if we can help it. Porting to something new takes ages and it's
a lot of churn.

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

On Wed, 10 Jan 2024, Florian Schmaus wrote:

On 10/01/2024 12.04, Sam James wrote:

1) The name seems odd (why not readme.gentoo-r2)?
2) Why can't the existing eclass be improved?

Both points, the name of the eclass and the question if this should be
added to the existing eclass or as a new eclass, are absolutely *no*
hill I want to die on.

What I *really* care about is having the functionality that there is a
readme eclass that *also* shows the elog message if the README's
content changed (and not just on the first installation of the
package).

Looks like readme.gentoo-r1 already gives you control over this:

# If you want to show them always, please set FORCE_PRINT_ELOG to a non empty
# value in your ebuild before this function is called.
# This can be useful when, for example, DOC_CONTENTS is modified, then, you can # rely on specific REPLACING_VERSIONS handling in your ebuild to print messages # when people update from versions still providing old message.

4) The compression deal seems not worth bothering with.

Just to clarify: you are agreeing that excluding the readme doc from
being compressed is fine?

Please respect the user's compression settings there. IMHO overriding
them with docompress -x is a big no-no.

[...]

It exports phase functions, which readme.gentoo-r1 does not.

Looking at the history, readme.gentoo[-r0] used to export phase
functions: https://gitweb.gentoo.org/repo/gentoo.git/tree/eclass/readme.gentoo.eclass?id=1e7b2242de29ec60105df1ef31939aed85a8b0eb#n32
It turned out to be a bad design choice, so -r1 no longer does that.

The readme.gentoo-r1 eclass always shoves the full content of the
readme into an environment variable.

Why is this a problem?

Ulrich

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

iQFDBAEBCAAtFiEEtDnZ1O9xIP68rzDbUYgzUIhBXi4FAmWeop0PHHVsbUBnZW50 b28ub3JnAAoJEFGIM1CIQV4u94gH/iDSL87eiV9yKFDoQPfCXgmrmWboQ/llhJdd +1hWz2APO+/LKZ2XcrJTigpWenaLdJpnjRTyBhxvkGasuVwXgELlgqDmKFYcDecW L8f+ekJuErq/slpFu/3vNXIKivAnXF2B2LPzGyOZi2vvuk+6y8yPQxXZKlyg+mKh bYZS5lcfeqFYmdtdBJUDGqFkG4LnTeFVjSZBieeM4dsWTlquQSDWQJghGqErxwdv WlRG3Hcdg+YGSQMRgm4ee3xDGGhr9flz5jZSZiwJX+iDcBULvLEhEoy6G3j7VJ7H joqQKPwa/NtZNV8ScxbYg1N/AEX9JZkhTWU5xm8M1vxsYdNgFy4=
=e7W1
-----END PGP SIGNATURE-----

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

On Wed, 10 Jan 2024, Florian Schmaus wrote:

On 10/01/2024 14.58, Ulrich Mueller wrote:

Looks like readme.gentoo-r1 already gives you control over this:
# If you want to show them always, please set FORCE_PRINT_ELOG to a non empty
# value in your ebuild before this function is called.
# This can be useful when, for example, DOC_CONTENTS is modified, then, you can
# rely on specific REPLACING_VERSIONS handling in your ebuild to print messages
# when people update from versions still providing old message.

It is easy to forget setting FORCE_PRINT_ELOG, just as it is easy to
forget to unset it again.

An automatism is always preferable over a manual solution.

Maybe I want manual control? For example, when I fix a typo in the
README file then I don't want to show it to users again.

Just to clarify: you are agreeing that excluding the readme doc from
being compressed is fine?

Please respect the user's compression settings there. IMHO
overriding
them with docompress -x is a big no-no.

Then why does "docompress -x" exist at all?

Short answer, because some upstream programs access these directories
and cannot cope with compressed files there.

Long answer, see the previous discussion on this list [1] and in
bug 250077 [2].

There seems to be a big win-win if we override the compression
settingin this case.

I tend to disagree. We shouldn't override users' choices unless
absolutely necessary.

Ulrich

[1] https://archives.gentoo.org/gentoo-dev/message/2fd5f58132881ef69219c126a525bce3
[2] https://bugs.gentoo.org/250077

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

iQFDBAEBCAAtFiEEtDnZ1O9xIP68rzDbUYgzUIhBXi4FAmWes2gPHHVsbUBnZW50 b28ub3JnAAoJEFGIM1CIQV4urDUIAJ4vLi2Hs3CGRRoo3zVZaMZXWW0YVsMmPxk3 XLjoVFwk/ODdEydy6+sxV5Nnv8ayug53IHUjTjbAAG4OjNfbgxWv3GrHwOTp0X7D cdn0b7UFOLN69H18eRw2wQq4Av/XWwSQ15SWWSTQ/OebH3b84k1VgxJBUCRoyE33 yRWciMGgovsTj55xwbzN6QNg2BDLgl9dsthB0QnBHkrAOmHbZJqeLgoyewmW4sGD sM1EX+Du5rLDo4C9WFD4v/SuUxuMHU1DDV8ZeUgzDAHZXXvngBPhcOr6qLaFnRoN wi6ZCEjsszvzqQG0ao6s0VX0DTXvTHhGC29a/v/D3bFxZAz5ZmI=
=YJTY
-----END PGP SIGNATURE-----

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