[gentoo-dev] Staging 'einstalldocs' for EAPI 6

[Michał Górny]

Hello,

Due to the widespread breakage in the tree noted in bug #480892 [1],
and mis-design of multilib-minimal.eclass, we'd like to put some more
work into getting einstalldocs() ready for EAPI 6.

When it's mostly defined, we'd like to backport it to eutils.eclass so
that we could use it to fix the existing breakages. But for that, we'd
really prefer if we had a final spec for it so that the EAPI switch
could be as simple as disabling the function in eutils.

Therefore, I'd like to open a final discussion for the features set
that is intended to be included in it, and it's name.

[1]:https://bugs.gentoo.org/show_bug.cgi?id=480892


Future EAPI bug: https://bugs.gentoo.org/show_bug.cgi?id=459692


1. Name

- einstalldocs

  -- probably the least confusing one, consistent with emake

- edocs

  -- but what does it do to the docs?

- dodocs

  -- do* prefix suggests it accepts list of files like doins,

  -- single-letter difference from 'dodoc' is confusing

- dodoc (without arguments)

  -- two different behaviors of a single function -- confusing

  -- wouldn't be feasible for backporting


2. Support for HTML_DOCS

   https://bugs.gentoo.org/show_bug.cgi?id=468310

It's used consistently in a few eclasses. if we put it into
the default, we can replace the eclass implementations with this one.


3. Support DOCS=() / DOCS='' to disable dodoc

   https://bugs.gentoo.org/show_bug.cgi?id=463736

Well, this one is mostly what the bug is about. I think we should just
do it. Implementation could be discussed a bit though.

For example, hasufell has suggested checking ${DOCS// /} to support
DOCS='   ' as well. IMO we shouldn't be supporting such a weird
mistakes.


4. Globbing support in DOCS array

   https://bugs.gentoo.org/show_bug.cgi?id=394211

radhermit suggested this to have equivalent set of features in DOCS
as scalar and DOCS as array. IMO it's PITA to implement and not worth
the effort.


5. Appending to DOCS

   https://bugs.gentoo.org/show_bug.cgi?id=449806

That is, ability to install default docs + listed files. I doubt that
it's worth the effort, especially for einstalldocs.


What are your thoughts?

-- 
Best regards,
Michał Górny