Gentoo Websites Logo
Go to: Gentoo Home Documentation Forums Lists Bugs Planet Store Wiki Get Gentoo!
Bug 493180 - PYTHON_TARGETS needs more visibility (was: man pages for make.conf and portage do not include any description of PYTHON_TARGETS)
Summary: PYTHON_TARGETS needs more visibility (was: man pages for make.conf and portag...
Status: RESOLVED CANTFIX
Alias: None
Product: [OLD] Docs on www.gentoo.org
Classification: Unclassified
Component: Installation Handbook (show other bugs)
Hardware: All Linux
: Normal normal (vote)
Assignee: Docs Team
URL: http://thread.gmane.org/gmane.linux.g...
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2013-12-02 23:23 UTC by Eric Johnson
Modified: 2016-02-06 07:04 UTC (History)
1 user (show)

See Also:
Package list:
Runtime testing required: ---


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Eric Johnson 2013-12-02 23:23:58 UTC
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

>man make.conf

does not include any information about PYTHON_TARGETS.

Reproducible: Always

Steps to Reproduce:
>man make.conf

Hit "/" to search for "python" , "PYTHON", etc. Nothing found.
Comment 1 Alexander Berntsen (RETIRED) gentoo-dev 2013-12-04 14:05:19 UTC
I wrote a patch for this but was told that it is not appropriate to document it in the man page as you suggest.
Comment 2 Eric Johnson 2013-12-19 18:02:28 UTC
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.
Comment 3 Sven Vermeulen (RETIRED) gentoo-dev 2013-12-19 18:42:08 UTC
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).
Comment 4 Michał Górny archtester Gentoo Infrastructure gentoo-dev Security 2013-12-19 19:06:36 UTC
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_*...
Comment 5 Alexander Berntsen (RETIRED) gentoo-dev 2016-02-02 15:20:49 UTC
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.
Comment 6 Brian Dolbec gentoo-dev 2016-02-02 19:49:40 UTC
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.
Comment 7 Alexander Berntsen (RETIRED) gentoo-dev 2016-02-02 21:24:33 UTC
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.
Comment 8 nm (RETIRED) gentoo-dev 2016-02-06 07:04:34 UTC
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.