Bug 770109 – metadata/install-qa-check.d/08gentoo-paths: allow more than /usr/share/doc/${PF} for docs

• Status: CONFIRMED
• Product: Gentoo Linux

[Description Sergei Trofimovich (RETIRED) 2021-02-11 18:03:09 UTC]

Use case: packages in different categories (and the same version) moth install docs cause collisions.

Haskell (or toolchain) example is dev-lang/ghc and cross-${CTARGET}/ghc. I think it's not unreasonable to have some wiggle room to disambiguate paths here.

Before we allowed only
    /usr/share/doc/${PF}
as a docs location.

The proposal suggests having
    /usr/share/doc/${PF}
    /usr/share/doc/${CATEGORY}-${PF}

That should provide unique key.

Place to plug it if agreed:

https://gitweb.gentoo.org/repo/gentoo.git/tree/metadata/install-qa-check.d/08gentoo-paths#n59

	# 3. check for unexpected /usr/share/doc subdirectories
	local doc_dirs=( "${ED%/}"/usr/share/doc/* )
	for x in "${doc_dirs[@]##*/}"; do
		if [[ ${x} != ${PF} ]]; then
			bad_paths+=( "/usr/share/doc/${x}" )
		fi
	done

[Comment 1 Sergei Trofimovich (RETIRED) 2021-02-11 18:07:52 UTC]

On #gentoo-dev-help Alessandro-B reports another example:

"""
18:05:13 < Alessandro-B> slyfox I'm on the node-overlay. The two packaged are dev-node/retry-0.12.0 and node-types/retry-0.12.0
18:06:00 < Alessandro-B> https://www.npmjs.com/package/retry
18:06:32 < Alessandro-B> https://www.npmjs.com/package/@types/retry
"""

[Comment 2 Michał Górny 2021-02-11 18:12:01 UTC]

Back at some point, I've pretty verbosely complained that abusing categories to disambiguate packages is a pretty bad idea.  I still think it'd better to start using unique PNs rather than adding more hacks to support the bad idea.

[Comment 3 Ulrich Müller 2021-02-11 19:58:51 UTC]

(In reply to Sergei Trofimovich from comment #0)
> The proposal suggests having
>     /usr/share/doc/${PF}
>     /usr/share/doc/${CATEGORY}-${PF}

I believe that's not a good idea, from a user's point of view. Users expect documentation to be installed in ${PF}, not ${CATEGORY}-${PF}. If anything, the category shouldn't be a prefix but a suffix, so that at least it can be discovered with autocompletion.

[Comment 4 Sergei Trofimovich (RETIRED) 2021-02-11 20:11:45 UTC]

(In reply to Ulrich Müller from comment #3)
> (In reply to Sergei Trofimovich from comment #0)
> > The proposal suggests having
> >     /usr/share/doc/${PF}
> >     /usr/share/doc/${CATEGORY}-${PF}
> 
> I believe that's not a good idea, from a user's point of view. Users expect
> documentation to be installed in ${PF}, not ${CATEGORY}-${PF}. If anything,
> the category shouldn't be a prefix but a suffix, so that at least it can be
> discovered with autocompletion.

The
    /usr/share/doc/${PF}
    /usr/share/doc/${PF}-${CATEGORY}
should be fine as well.

[Comment 5 Arfrever Frehtes Taifersar Arahesis 2021-02-11 22:42:11 UTC]

Maybe:
  /usr/share/doc/${PN}-*-${PVR}
?