From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from pigeon.gentoo.org ([208.92.234.80] helo=lists.gentoo.org) by finch.gentoo.org with esmtp (Exim 4.60) (envelope-from ) id 1RcOoS-0004P3-MV for garchives@archives.gentoo.org; Sun, 18 Dec 2011 22:02:32 +0000 Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 1744221C396; Sun, 18 Dec 2011 22:02:09 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183]) by pigeon.gentoo.org (Postfix) with ESMTP id B66A921C1F9; Sun, 18 Dec 2011 22:01:19 +0000 (UTC) Received: from pomiocik.lan (77-253-147-68.adsl.inetia.pl [77.253.147.68]) (using TLSv1 with cipher DHE-RSA-AES128-SHA (128/128 bits)) (No client certificate requested) (Authenticated sender: mgorny) by smtp.gentoo.org (Postfix) with ESMTPSA id E296E1B4033; Sun, 18 Dec 2011 22:01:17 +0000 (UTC) Date: Sun, 18 Dec 2011 23:02:05 +0100 From: =?UTF-8?B?TWljaGHFgiBHw7Nybnk=?= To: gentoo-dev@lists.gentoo.org Cc: tetromino@gentoo.org, Gentoo PMS Subject: Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF Message-ID: <20111218230205.4df86707@pomiocik.lan> In-Reply-To: References: Organization: Gentoo X-Mailer: Claws Mail 3.7.10 (GTK+ 2.24.8; x86_64-pc-linux-gnu) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-dev@lists.gentoo.org Reply-to: gentoo-dev@lists.gentoo.org Mime-Version: 1.0 Content-Type: multipart/signed; micalg=PGP-SHA256; boundary="Sig_/LWRBd/ujOtXYRHmr4jSbn7T"; protocol="application/pgp-signature" X-Archives-Salt: de752405-4a1e-43ff-8522-e8dbbda5c83e X-Archives-Hash: 5b687ce35857e5868251a5fe1a513fae --Sig_/LWRBd/ujOtXYRHmr4jSbn7T Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable I basically agree, it's quite a great idea. Just a few comments though. On Sun, 18 Dec 2011 16:49:38 -0500 Alexandre Rostovtsev wrote: > * The package's documentation may be designed primarily for tools and > viewers which expect to load documentation files from a different > location. That's why I, for instance, use gtk-doc in my libraries. It's just that it has its standard install procedures and locations. > 1. If a package's documentation is designed to be accessed by a > specific documentation viewer tool, then the package should install > the documentation in a location where that tool will look for it (e.g. > devhelp expects to find GNOME API documentation in > /usr/share/gtk-doc/html, and khelpcenter expects to find KDE handbooks > in /usr/share/doc/HTML). This already happens in practice, but some > devs had expressed opposition to this (e.g. bug #312363) because it > had not been formalized as policy. Agree. But that's outside of the GLEP/PMS scope; just an internal policy should fine, I think. > 2. In EAPI-5 and higher, other documentation should be installed under > /usr/share/doc: > a. if SLOT =3D "0": in /usr/share/doc/$CATEGORY/$PN by default, xor > (at the package maintainer's discretion) in > /usr/share/doc/$CATEGORY/$PN-0. I'd rather not see that -0 there. > b. if SLOT !=3D "0": in /usr/share/doc/$CATEGORY/$PN-$SLOT. [...] > Q3: Why $PN-$SLOT instead of $PN:$SLOT? > A3: So that the directory names are compatible with bash's > tab-completion. What if 'foo' has slot named 'bar', and there is unslotted 'foo-bar' package? :P > Q5: Then why allow package maintainers to alternatively use > $CATEGORY/$PN-0? A5: Why not? It will not hurt anything, will not > cause file collisions, and some maintainers of a multislotted > package, one of which is 0, might prefer to install that slot's docs > in $CATEGORY/$PN-0 to prevent a potential impression that docs in > $CATEGORY/$PN apply to all of that package's slots. This will make the policy less clear, and documentation locations more enigmatic for users. While at this, I think we should somehow move the docs for all EAPIs to avoid this, and probably move installed ones as well. > Q6: Why can't the dodoc/dohtml path be changed before EAPI-5? > A6: Because the path where dodoc and dohtml install files is part of > the PMS. Portage can't just change it on its own. A possible > workaround for current EAPIs is adding new-style dodoc/dohtml > analogues to an eclass. I think some of devs agree we should be allowed to fix past mistakes without waiting another 20 years till the tree is migrated to a new EAPI... --=20 Best regards, Micha=C5=82 G=C3=B3rny --Sig_/LWRBd/ujOtXYRHmr4jSbn7T Content-Type: application/pgp-signature; name=signature.asc Content-Disposition: attachment; filename=signature.asc -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.18 (GNU/Linux) iJwEAQEIAAYFAk7uYt0ACgkQfXuS5UK5QB1p7gQAjmxVl1mHiQe1BNfDAZPmchzz PZ1HXnolIbMWbMkdEHYLzQtqeUlOdMJphCEAIzf8RJCtMJ98WwFkUTyGn4DCzlwL yfHkTooclGbOIgREmGy/kz7X/v1RWbRPQ5KYAeFwXWZKAy3KvXAYKcbPu4HjuVoT loJN6CiRGIFCKTNuZns= =I5mi -----END PGP SIGNATURE----- --Sig_/LWRBd/ujOtXYRHmr4jSbn7T--