[gentoo-dev] Proposal for compression handling (was: Re: prepalldocs is now banned)

[Ulrich Mueller]

>>>>> On Wed, 18 Feb 2009, Alexis Ballier wrote:

>> If you really, genuinely think you have a case for compression of
>> docs, backed up with statistics showing that it's a relevant
>> change, then you should write a proposal for future EAPIs for
>> handling it,

> I don't understand why something that has been there for ages has to
> die. For what I've seen, the major (and only) problem with
> prepalldocs is its definition and I'm sure we can find one that
> everybody will agree with.

>> and you should do it in such a way that it works automatically for
>> all ebuilds, without any developer intervention (but providing some
>> way for ebuilds to disable it where necessary).

> This is probably a good start:
> http://archives.gentoo.org/gentoo-dev/msg_eb1f7952eb2f0fe725bde331a4d9ae30.xml

Let's fill this with some life. What do you think about the following
proposal:

Package managers supporting compression would internally maintain two
lists of paths, both having a default value, plus the possibility to
modify them from ebuilds/eclasses:

   - an inclusion list, initially containing:
     /usr/share/doc /usr/share/info /usr/share/man
   - an exclusion list, initially containing:
     /usr/share/doc/${PF}/html

Then we need a new command, let's call it "docompress" for now (name
to be discussed), to manipulate the lists:

   - "docompress" (without option or with option "-a"): add paths
      (directories or files) to the inclusion list
   - "docompress -d": delete paths from the inclusion list
   - "docompress -x": add paths to the exclusion list
   - "docompress -x -d": remove paths from the exclusion list
     (maybe this is not needed?)

(For package managers not supporting compression, "docompress" would
be a no-op.)

Between the src_install and pkg_postinst phases, the package manager
would then go through the inclusion list and optionally (depending on
the user's setting, i.e. PORTAGE_COMPRESS in the Portage case)
compress anything found there, excluding the stuff from the exclusion
list.

The two most common usage cases:

   1. dodoc <file1> <file2> ...

and

   2. emake ... docdir="/usr/share/doc/${PF}" install

would just work as expected, without any need for calling docompress.

A package that needs uncompressed documentation would simply call
"docompress -d /usr/share/doc" or
"docompress -x /usr/share/doc/${PF}/<some subdir>".

In addition, I think that Tiziano's suggestion to have "dodoc" operate
on directories (or to add a "-r" option as "doins" has) is also a good
idea.

Ulrich