[gentoo-portage-dev] [PATCH] make.conf.5: Document PYTHON_TARGETS, bug #493180

[gentoo-portage-dev] [PATCH] make.conf.5: Document PYTHON_TARGETS, bug #493180

[Alexander Berntsen]

Using git send-email since vapier told me to. I haven't used this before, so
sorry if I have done something wrong. Please let me know.
---
 man/make.conf.5 | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/man/make.conf.5 b/man/make.conf.5
index c271d17..db198f9 100644
--- a/man/make.conf.5
+++ b/man/make.conf.5
@@ -1,4 +1,4 @@
-.TH "MAKE.CONF" "5" "Aug 2013" "Portage VERSION" "Portage"
+.TH "MAKE.CONF" "5" "Dec 2013" "Portage VERSION" "Portage"
 .SH "NAME"
 make.conf \- custom settings for Portage
 .SH "SYNOPSIS"
@@ -949,6 +949,19 @@ directories.
 .br
 Defaults to no value.
 .TP
+\fBPYTHON_SINGLE_TARGET = \fI[target]\fR
+Set this to the Python interpreter you want to use when only a single Python
+implementation can be enabled. This takes precedence over
+\fBPYTHON_TARGETS\fR. Python 2.7 is enabled by default, and is overriden if
+this variable is set manually. Targets look like pythonX_Y, e.g. python2_7
+and python3_2.
+.TP
+\fBPYTHON_TARGETS = \fI[space delimited list of targets]\fR
+Set this to the Python interpreters you want to choose from when more than one
+Python implementation can be enabled at the same time. Python 2.7 and 3.2 are
+enabled by default, and are overriden if this variable is set manually.
+Targets look like pythonX_Y, e.g. python2_7 and python3_2.
+.TP
 \fBQA_STRICT_EXECSTACK = \fI"set"\fR
 Set this to cause portage to ignore any \fIQA_EXECSTACK\fR override
 settings from ebuilds.  See also \fBebuild\fR(5).
-- 
1.8.3.2

Re: [gentoo-portage-dev] [PATCH] make.conf.5: Document PYTHON_TARGETS, bug #493180

[Alexander Berntsen]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Apparently I forgot to turn off the option that CCs the author, and
consequently managed to do what I have been telling you to not do.
Don't take this as an invitation to CC me after all. ;-)

- -- 
Alexander
alexander@plaimi.net
http://plaimi.net/~alexander
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iF4EAREIAAYFAlKdopgACgkQRtClrXBQc7UUKQD7B+4JhBxJ2gNIU3zw4NmKOUAF
bOHnLOCqDrqGJFd7pZ0BAIpfPgdZGzKWFSseguvtvw83OYq14v230LtqhvFlTqef
=UTcm
-----END PGP SIGNATURE-----

Re: [gentoo-portage-dev] [PATCH] make.conf.5: Document PYTHON_TARGETS, bug #493180

[Sebastian Luther]

Should we really document specific USE_EXPAND variables? What about all
the others?

USE_EXPAND="ABI_MIPS ABI_X86 ALSA_CARDS APACHE2_MODULES APACHE2_MPMS
CALLIGRA_FEATURES CAMERAS COLLECTD_PLUGINS CROSSCOMPILE_OPTS CURL_SSL
DRACUT_MODULES DVB_CARDS ELIBC ENLIGHTENMENT_MODULES FCDSL_CARDS FFTOOLS
FOO2ZJS_DEVICES FRITZCAPI_CARDS GPSD_PROTOCOLS GRUB_PLATFORMS
INPUT_DEVICES KERNEL LCD_DEVICES LIBREOFFICE_EXTENSIONS LINGUAS
LIRC_DEVICES MONKEYD_PLUGINS NETBEANS_MODULES NGINX_MODULES_HTTP
NGINX_MODULES_MAIL OFED_DRIVERS OFFICE_IMPLEMENTATION OPENMPI_FABRICS
OPENMPI_OFED_FEATURES OPENMPI_RM PHP_TARGETS PYTHON_SINGLE_TARGET
PYTHON_TARGETS QEMU_SOFTMMU_TARGETS QEMU_USER_TARGETS RUBY_TARGETS
SANE_BACKENDS USERLAND VIDEO_CARDS VOICEMAIL_STORAGE XFCE_PLUGINS
XTABLES_ADDONS

Re: [gentoo-portage-dev] [PATCH] make.conf.5: Document PYTHON_TARGETS, bug #493180

[Alexander Berntsen]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On 03/12/13 10:46, Sebastian Luther wrote:
> Should we really document specific USE_EXPAND variables? What
> about all the others?
I think so, yes.

> USE_EXPAND="ABI_MIPS ABI_X86 ALSA_CARDS APACHE2_MODULES
> APACHE2_MPMS CALLIGRA_FEATURES CAMERAS COLLECTD_PLUGINS
> CROSSCOMPILE_OPTS CURL_SSL DRACUT_MODULES DVB_CARDS ELIBC
> ENLIGHTENMENT_MODULES FCDSL_CARDS FFTOOLS FOO2ZJS_DEVICES
> FRITZCAPI_CARDS GPSD_PROTOCOLS GRUB_PLATFORMS INPUT_DEVICES KERNEL
> LCD_DEVICES LIBREOFFICE_EXTENSIONS LINGUAS LIRC_DEVICES
> MONKEYD_PLUGINS NETBEANS_MODULES NGINX_MODULES_HTTP
> NGINX_MODULES_MAIL OFED_DRIVERS OFFICE_IMPLEMENTATION
> OPENMPI_FABRICS OPENMPI_OFED_FEATURES OPENMPI_RM PHP_TARGETS
> PYTHON_SINGLE_TARGET PYTHON_TARGETS QEMU_SOFTMMU_TARGETS
> QEMU_USER_TARGETS RUBY_TARGETS SANE_BACKENDS USERLAND VIDEO_CARDS
> VOICEMAIL_STORAGE XFCE_PLUGINS XTABLES_ADDONS
I can do this over the weekend.

- -- 
Alexander
alexander@plaimi.net
http://plaimi.net/~alexander
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iF4EAREIAAYFAlKdrbYACgkQRtClrXBQc7WCXgD/dlNapTePpmRy2GzW+SunYxVG
Z18ELRpZwISNqvBSI6IA/A4hL2eHlaDSz9spFkwua8tv38P76Z8xDnzzEWEOZhzA
=ivF7
-----END PGP SIGNATURE-----

Re: [gentoo-portage-dev] [PATCH] make.conf.5: Document PYTHON_TARGETS, bug #493180

[Sebastian Luther]

Am 03.12.2013 11:08, schrieb Alexander Berntsen:
> On 03/12/13 10:46, Sebastian Luther wrote:
>> Should we really document specific USE_EXPAND variables? What 
>> about all the others?
> I think so, yes.
> 
[...]
> I can do this over the weekend.
> 

The problem with all these variables is that we don't maintain them.
If they disappear, change meaning or new ones are added we constantly
have to fix our documentation.

The python team's documentation [1] is just fine imo. Maybe this one
needs to be more user visible? Maybe by linking it into the handbook
(if it isn't already)?


[1] http://www.gentoo.org/proj/en/Python/python-r1/user-guide.xml

Re: [gentoo-portage-dev] [PATCH] make.conf.5: Document PYTHON_TARGETS, bug #493180

[Alexander Berntsen]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On 03/12/13 11:21, Sebastian Luther wrote:
> The problem with all these variables is that we don't maintain
> them. If they disappear, change meaning or new ones are added we
> constantly have to fix our documentation.
I don't think this is a problem. I could fix any documentation bugs
related to this.

> The python team's documentation [1] is just fine imo. Maybe this
> one needs to be more user visible? Maybe by linking it into the
> handbook (if it isn't already)?
It could be linked in the man page of make.conf as well.


Ultimately my stance is that it should be in the man page. I can add
them myself. However, I will leave it out if more people agree with
Sebastian than me.
- -- 
Alexander
alexander@plaimi.net
http://plaimi.net/~alexander
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iF4EAREIAAYFAlKdtd4ACgkQRtClrXBQc7WwpgD+IYfhSD43rRpU4NTUaBRpWzyB
vZcUJveJttZEd5MlUF8A+gLKqf9T9EtzjQzqTWl2twuUu/oDSwhPe9fePM4ZrEg2
=bbW5
-----END PGP SIGNATURE-----

[gentoo-portage-dev] Re: [PATCH] make.conf.5: Document PYTHON_TARGETS, bug #493180

[Duncan]

Alexander Berntsen posted on Tue, 03 Dec 2013 11:43:42 +0100 as excerpted:

> On 03/12/13 11:21, Sebastian Luther wrote:
>> The problem with all these variables is that we don't maintain them. If
>> they disappear, change meaning or new ones are added we constantly have
>> to fix our documentation.
> I don't think this is a problem. I could fix any documentation bugs
> related to this.
> 
>> The python team's documentation [1] is just fine imo. Maybe this one
>> needs to be more user visible? Maybe by linking it into the handbook
>> (if it isn't already)?
> It could be linked in the man page of make.conf as well.
> 
> 
> Ultimately my stance is that it should be in the man page. I can add
> them myself. However, I will leave it out if more people agree with
> Sebastian than me.

User contribution, FWIW:  I'll stay neutral on having it in the manpage, 
but I definitely agree PYTHON_TARGETS and PYTHON_SINGLE_TARGET need more 
visibility, and I like the proposed explanation in the patch very much, 
as it finally cleared up the relationship between the two of them for me.

And given my level of gentoo knowledge and experience, if I was a bit 
confused by the two separate python-targets settings and unaware of the 
precise relationship between them as well as their defaults, I think it's 
a pretty safe bet that well above 90% of the user base is at least as 
confused as I was if not more so.  So manpage or some other location I'm 
not sure, but I definitely agree it's not documented well enough now, and 
the proposed patch would at least give it /some/ visibility.

Regardless of whether it gets in the manpage, tho, can I suggest 
mentioning that definition in the next GMN, gentoo monthly newsletter, 
now that it has been resurrected?  The handbook and/or manpage are good, 
but that won't necessarily reach the existing users GMN should, even if 
it doesn't reach them all.  From there the explanation will hopefully 
spread via the users themselves.  =:^)

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman

Re: [gentoo-portage-dev] [PATCH] make.conf.5: Document PYTHON_TARGETS, bug #493180

[Arfrever Frehtes Taifersar Arahesis]

[-- Attachment #1: Type: Text/Plain, Size: 130 bytes --]

Portage's documentation is inappropriate place for this.
Please do not commit this patch.

--
Arfrever Frehtes Taifersar Arahesis

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [gentoo-portage-dev] [PATCH] make.conf.5: Document PYTHON_TARGETS, bug #493180

[Brian Dolbec]

[-- Attachment #1: Type: text/plain, Size: 1227 bytes --]

On Tue, 2013-12-03 at 11:43 +0100, Alexander Berntsen wrote:
> On 03/12/13 11:21, Sebastian Luther wrote:
> > The problem with all these variables is that we don't maintain
> > them. If they disappear, change meaning or new ones are added we
> > constantly have to fix our documentation.
> I don't think this is a problem. I could fix any documentation bugs
> related to this.
> 
> > The python team's documentation [1] is just fine imo. Maybe this
> > one needs to be more user visible? Maybe by linking it into the
> > handbook (if it isn't already)?
> It could be linked in the man page of make.conf as well.
> 
> 
> Ultimately my stance is that it should be in the man page. I can add
> them myself. However, I will leave it out if more people agree with
> Sebastian than me.

I think a good compromise is to use python_targets as an example under a
general use expand heading, explaining how use expand works.  Add the
link to the python doc, yes

Then simply mention to look for the relevant docs for details of any of
the other use expand variables.  And a pointer to the gentoo docs index.

I think python_targets is too central to a gentoo system to be
completely ignored in the man pages. 

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 620 bytes --]

Re: [gentoo-portage-dev] [PATCH] make.conf.5: Document PYTHON_TARGETS, bug #493180

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 824 bytes --]

On Tuesday 03 December 2013 04:19:27 Alexander Berntsen wrote:
> Using git send-email since vapier told me to. I haven't used this before,
> so sorry if I have done something wrong. Please let me know.

looks ok from `git send-email` pov, but random comments not meant for the 
commit message should be below the --- line ;)

as for the patch, i'm of the opinion that make.conf is not for documenting 
random USE_EXPAND-ed variables.

this sort of thing should go into the relevant eclass, python-r1.eclass in 
this case.  then people would read about it via `man python-r1.eclass`.

there is the matter of visibility ... we could add a generic pointer to the 
make.conf man page discussing that there are many more variables that might 
impact the build and to look at the man page for the eclasses.
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [gentoo-portage-dev] [PATCH] make.conf.5: Document PYTHON_TARGETS, bug #493180

[Robin H. Johnson]

On Tue, Dec 03, 2013 at 11:05:51AM -0500, Mike Frysinger wrote:
> as for the patch, i'm of the opinion that make.conf is not for documenting 
> random USE_EXPAND-ed variables.
...
> there is the matter of visibility ... we could add a generic pointer to the 
> make.conf man page discussing that there are many more variables that might 
> impact the build and to look at the man page for the eclasses.
Can I make a possible additional suggestion?

We do already have profiles/${VAR}.desc, describing what the settings
themselves do. Can we augment those files to describe the variable
itself?

Then put a generic note in make.conf about reading those (or something
to build docs from them like the eclass docs).

-- 
Robin Hugh Johnson
Gentoo Linux: Developer, Infrastructure Lead
E-Mail     : robbat2@gentoo.org
GnuPG FP   : 11ACBA4F 4778E3F6 E4EDF38E B27B944E 34884E85

Re: [gentoo-portage-dev] [PATCH] make.conf.5: Document PYTHON_TARGETS, bug #493180

[René Neumann]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Am 03.12.2013 17:05, schrieb Mike Frysinger:
> as for the patch, i'm of the opinion that make.conf is not for
> documenting random USE_EXPAND-ed variables.
> 
> this sort of thing should go into the relevant eclass,
> python-r1.eclass in this case.  then people would read about it via
> `man python-r1.eclass`.

I object. As a user you should (most of the time) not need to read
eclass-documentation. And even if you'd count this as a necessity: How
should a user know _which_ eclass documentation to read? I think such
a thing is way too much 'implementation detail'.

If you all think, that make.conf.5 is not the right place (which I
understand), then there should be another central place where the most
important USE_EXPAND-ed vars are explained and/or pointers provided.
Perhaps one could make (active) contribution to this place a
prerequisite to obtaining a new USE_EXPAND-var.

And in make.conf.5 there then can be a pointer to this central
documentation.

- - René
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQEcBAEBAgAGBQJSnhcNAAoJEC/VbLI/MjXALUEH/iloA1/Pxee/0K3dv3s3P0NO
buDmWKLQQ/rtUwlaM3VZj4b71MqHK7zIjumD+9IIq9to4l/ot5Bsx8hUbdcyJtsa
wrSPZBKGeYw9m3qYmP9GIr9uKb+/BfUPrfGefSp3rtWPnaAb1clZJbC40Hw+J2Mp
rzKWzvmweqVbrzXSg/Dm38+JqBozQFk1cbHshe2d15S/Cem4yCn+NQaPSl7l1hQE
eljJ/b5lGbIeF8QxtPJPwSVEv/ohC6nXLK7eKvGDXvV0ZpuDl9KvmeYpc8/40d9n
LSzTBB7ENEC34hpTwhoTekufitmFj/IRvN63ekHf6+asjrfhCejFCO6HKZFa3I4=
=Rky6
-----END PGP SIGNATURE-----

Re: [gentoo-portage-dev] [PATCH] make.conf.5: Document PYTHON_TARGETS, bug #493180

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 1204 bytes --]

On Tuesday 03 December 2013 11:52:47 Robin H. Johnson wrote:
> On Tue, Dec 03, 2013 at 11:05:51AM -0500, Mike Frysinger wrote:
> > as for the patch, i'm of the opinion that make.conf is not for
> > documenting random USE_EXPAND-ed variables.
> 
> ...
> 
> > there is the matter of visibility ... we could add a generic pointer to
> > the make.conf man page discussing that there are many more variables
> > that might impact the build and to look at the man page for the
> > eclasses.
> 
> Can I make a possible additional suggestion?
> 
> We do already have profiles/${VAR}.desc, describing what the settings
> themselves do. Can we augment those files to describe the variable
> itself?
> 
> Then put a generic note in make.conf about reading those (or something
> to build docs from them like the eclass docs).

we have profiles/desc/python_targets.desc too.  how about we update the eclass-
manpages to parse those files and produce man pages ?  it'd use the existing 
doc format that has been adopted for eclasses.

then the make.conf man page would point you to a main landing page (like 
use.desc), and that would bounce you to all the other generated man pages.
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [gentoo-portage-dev] [PATCH] make.conf.5: Document PYTHON_TARGETS, bug #493180

[Brian Dolbec]

[-- Attachment #1: Type: text/plain, Size: 1432 bytes --]

On Tue, 2013-12-03 at 18:38 +0100, René Neumann wrote:
> Am 03.12.2013 17:05, schrieb Mike Frysinger:
> > as for the patch, i'm of the opinion that make.conf is not for
> > documenting random USE_EXPAND-ed variables.
> > 
> > this sort of thing should go into the relevant eclass,
> > python-r1.eclass in this case.  then people would read about it via
> > `man python-r1.eclass`.
> 
> I object. As a user you should (most of the time) not need to read
> eclass-documentation. And even if you'd count this as a necessity: How
> should a user know _which_ eclass documentation to read? I think such
> a thing is way too much 'implementation detail'.
> 
> If you all think, that make.conf.5 is not the right place (which I
> understand), then there should be another central place where the most
> important USE_EXPAND-ed vars are explained and/or pointers provided.
> Perhaps one could make (active) contribution to this place a
> prerequisite to obtaining a new USE_EXPAND-var.
> 
> And in make.conf.5 there then can be a pointer to this central
> documentation.
> 
> - René

+1

It follows similarly with what I proposed about having a generic USE
EXPAND heading and description in make.conf.  It just doesn't show the
python_targets as an example.  but it could still, just not with the
extra documentation that Alexander did. Instead point to this landing
page for all the use expand variables.

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 620 bytes --]

[gentoo-portage-dev] Re: [PATCH] make.conf.5: Document PYTHON_TARGETS, bug #493180

[Ryan Hill]

[-- Attachment #1: Type: text/plain, Size: 558 bytes --]

On Tue, 3 Dec 2013 13:43:49 +0000 (UTC)
Duncan <1i5t5.duncan@cox.net> wrote:

> User contribution, FWIW:  I'll stay neutral on having it in the manpage, 
> but I definitely agree PYTHON_TARGETS and PYTHON_SINGLE_TARGET need more 
> visibility, and I like the proposed explanation in the patch very much, 
> as it finally cleared up the relationship between the two of them for me.

+1


-- 
Ryan Hill                        psn: dirtyepic_sk
   gcc-porting/toolchain/wxwidgets @ gentoo.org

47C3 6D62 4864 0E49 8E9E  7F92 ED38 BD49 957A 8463

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 490 bytes --]