Various documentation pages and wiki pages seem to describe how to use PYTHON_TARGETS, and the official documentation at http://www.gentoo.org/proj/en/Python/python-r1/user-guide.xml has samples for make.conf, but
does not include any information about PYTHON_TARGETS.
Steps to Reproduce:
Hit "/" to search for "python" , "PYTHON", etc. Nothing found.
I wrote a patch for this but was told that it is not appropriate to document it in the man page as you suggest.
I ran into this issue because I updated python, and started seeing messages about PYTHON_TARGETS (presumably from the python ebuild classes?) for python-based packages.
But I had a hard time figuring out what I was supposed to with those messages, because my first few attempts to find documentation fizzled.
Given that Python is required by Gentoo, I think it is easy to argue that PYTHON_TARGETS should be documented far better than it is. Much less important than getting docs for other flags such as APACHE2_MODULES as readily visible, because with those variables, someone generally has to choose to install something that then triggers the presence of the variables. Likely they'll go read about installing Ruby/Apache/LibreOffice/ etc. as part of that processes. That will expose said users to the info about the variables.
PYTHON_TARGETS is effectively always there, and not introduced in the installation docs.
I'll gladly accept suggestions here. For me, the python stuff is not as transparent as I hope it to be (USE_PYTHON, PYTHON_TARGETS, PYTHON_SINGLE_TARGET).
If we were to document something, I think we should document all proper USE_EXPAND variables in one place. That is, ABI_*, PYTHON_*, RUBY_*, PHP_* etc.
Excluding the obvious overuses of USE_EXPAND that are used by single package only like APACHE2_MODULES, NGINX_*...
Sven, Mike, Brian, Arfrever, Sebastian, let's agree on what to do. I'll do whatever needs done from Portage's side. I agree with Mike that it should be documented in the eclass. But I am sympathetic to the users who pointed out that documenting it in an eclass by itself is user-unfriendly -- so we should link to this notice in the handbook or in make.conf comments, or somewhere, anywhere. Does that sound OK to you guys? Do you have a preference re: handbook v. make.conf?
Michał, please deal with those in separate bugs.
I'm not opposed to a generic brief description of the various PYTHON_TARGETS, RUBY_TARGETS,APACHE2_MODULES, XFCE_PLUGINS, VIDEO_CARDS,...
See what I mean, it just keeps growing...
Ideally, there should be a central wiki page for all the approved "USE_EXPAND" variables. And we add a link to that. From that page it lists all the variables that exist and link to the specific project/USE_EXPAND page for details.
USE_EXPAND variables are not subject to the portage codebase's control (other than PM support for them), so we should not have to make a release with an updated man page every time one is added, removed or changed.
I could accept adding mention of a few of the main ones like PYTHON_TARGETS, VIDEO_CARDS, LINGUAS which are central to most users in the brief description of USE_EXPAND variables. But ultimately, the description should be general about how they work or are used, not specifics of individual variables.
I think that a wiki (linked to from the handbook) page is the best place to put this. So I'm reassigning this. However, if there is someone who *really* feels like this needs to go into Portage, do feel free to ping us again.
by all means, if anyone comes up with some USE_EXPAND docs, please let us know on the appropriate handbook discussion pages (so long as they don't distract from the primary purpose of getting a basic system up and running), and we can link 'em in. but no one's written anything, yet; nothing we can do.