Re: [gentoo-dev] [PATCH 0/1] [RFC] greadme.eclass

[Florian Schmaus <flow@gentoo.org>]

[-- Attachment #1.1.1: Type: text/plain, Size: 3803 bytes --]

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, and "fixing" readme.gentoo-r1 
would consist of copying most of greadme into readme.gentoo-r1, while 
still having the "legacy" readme.gentoo-r1 functionality in it.

Starting over strikes me as sensible in this case.


>> 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 gets even worse if you consider binpkgs, as you have surely read the 
comment while looking at the code of the greadme.eclass.


 > 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".

The primary motivation for posting this RFC was to find a solution and 
avoid the "docompress -x" approach. However, I don't think there is one 
that does not require adjusting PMS to provide the guarantee that the 
eclass can decompress the compressed doc file.

Adjusting PMS seems overkill just for avoiding to exclude a single small 
file from compression.

I also tried to make the greadme eclass handle unpacking errors 
gracefully. This turned out to be harder than I hoped because most 
(all?) functions of unpacker.eclass are not nonfatal compatible. The 
same is true for unpack() from PMS, which is used by unpacker.eclass.

I'll send out v2 of greadme.eclass soon.

Looking at the conditional _GREADME_COMPRESS code, you will find that 
adding support for compressing the doc file introduces a lot of 
complexity to the eclass. That would still make me consider it, but I 
can not see any reliable approach to unpacking that does not involve 
adjusting PMS.

Surely you would be able to correct me if I am wrong.


>> 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.

How is this mechanism helpful here?

- Flow


[-- Attachment #1.1.2: OpenPGP public key --]
[-- Type: application/pgp-keys, Size: 17273 bytes --]

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 618 bytes --]