Documentating advanced portage feaetures in Gentoo Handbook
 

Hi guys,

There's a small discussion going on on gentoo-doc [1] about documenting (or
not documenting) advanced portage features in the Gentoo handbook. The
suggestion currently is to have it as an added chapter in "Working with
Portage" of which you can find a preview on [2] (don't mind the numbering).

[1] http://archives.gentoo.org/gentoo-doc/msg_f3c1439def8cd1df8b0f57fdbb7e6462.xml
[2] http://dev.gentoo.org/~swift/docs/previews/hb-portage-advanced.xml

The discussion however is if it is okay to document these things there or
not. Some of the features are considered to be too "fragile" to be broadly
documented (at least in a beginners resource like the Gentoo Handbook) and
might cause eventual bugs to be closed as RESO:WONTFIX because the user used
such a feature.

Since you're the community at large for supporting stuff, we'd like to know
if it is okay to document these things in the Gentoo Handbook (and if we
need to put in specific warnings to ensure people don't abuse the
functionality) or if you would rather not see it in.

I personally don't think we cannot "not document" it. Eventually, the Gentoo
WiKi will have it documented anyhow, and I already notice that many of the
features are already used in #gentoo or gentoo-user@g.o. But there's still a
difference between "not documenting" and putting it in the Gentoo Handbook.

Thoughts? Suggestions?

Wkr,
Sven Vermeulen

Documentating advanced portage feaetures in Gentoo Handbook
 

On 3.1.2012 19.51, Sven Vermeulen wrote:
>
> [2] http://dev.gentoo.org/~swift/docs/previews/hb-portage-advanced.xml
>
> The discussion however is if it is okay to document these things there or
> not. Some of the features are considered to be too "fragile" to be broadly
> documented (at least in a beginners resource like the Gentoo Handbook) and
> might cause eventual bugs to be closed as RESO:WONTFIX because the user used
> such a feature.
>

A quick read didn't seem like there would be something overly dangerous
or support nightmare producing there.

Regards,
Petteri

Documentating advanced portage feaetures in Gentoo Handbook
 

On 2012.01.03 17:51, Sven Vermeulen wrote:
> Hi guys,
>
> There's a small discussion going on on gentoo-doc [1] about
> documenting (or
> not documenting) advanced portage features in the Gentoo handbook.
> The
> suggestion currently is to have it as an added chapter in "Working
> with
> Portage" of which you can find a preview on [2] (don't mind the
> numbering).
>
> [1] http://archives.gentoo.org/gentoo-doc/
> msg_f3c1439def8cd1df8b0f57fdbb7e6462.xml
> [2] http://dev.gentoo.org/~swift/docs/previews/hb-portage-
> advanced.xml
>
> The discussion however is if it is okay to document these things
> there
> or
> not.
[snip]
> Thoughts? Suggestions?
>
> Wkr,
> Sven Vermeulen
>
>

Team,

The Gentoo Handbook is about getting the base system installed.
As such features such as per package CFLAGS have no place there. They
are not within the scope of installing the base system.

We already have separate guides for Xorg, Gnome, KDE, ALSA, binary blob
video drivers and so on.

I agree these portage features should be documented but probably in a
'bleeding edge' guide.

Our users will tinker and break things just because they can anyway. At
least don't give them the means to make them difficult to help in the
introductory Gentoo text.

--
Regards,

Roy Bamford
(Neddyseagoon) a member of
elections
gentoo-ops
forum-mods
trustees

Documentating advanced portage feaetures in Gentoo Handbook
 

On Tue, Jan 03, 2012 at 09:57:04PM +0000, Roy Bamford wrote:
> Team,
>
> The Gentoo Handbook is about getting the base system installed.
> As such features such as per package CFLAGS have no place there. They
> are not within the scope of installing the base system.

I disagree. The first part is about getting a base system. The rest of the
handbook is to describe the Gentoo-specific administrative stuff.

Wkr,
Sven Vermeulen

Documentating advanced portage feaetures in Gentoo Handbook
 

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

On 01/03/2012 10:21 PM, Sven Vermeulen wrote:
> On Tue, Jan 03, 2012 at 09:57:04PM +0000, Roy Bamford wrote:
>> Team,
>>
>> The Gentoo Handbook is about getting the base system installed.
>> As such features such as per package CFLAGS have no place there.
>> They are not within the scope of installing the base system.
>
> I disagree. The first part is about getting a base system. The rest
> of the handbook is to describe the Gentoo-specific administrative
> stuff.
>
> Wkr, Sven Vermeulen
>
I agree. Advanced portage features can be in Gentoo Handbook provided
it is clear that they should be not used without proper and complete
understanding

- --
Regards,
Markos Chandras / Gentoo Linux Developer / Key ID: B4AFF2C2
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.18 (GNU/Linux)

iQIcBAEBCgAGBQJPA4PLAAoJEPqDWhW0r/LC5pgQAIPKKkn4dYaEz/R+BCdobPlP
1DBEdmB4IGFwPJfmDup6ubVcNuCwarJ9OXIx+kTuBtar48G7bb HljmhD53qWhFy/
7PeYmrNuwy05SDH0n3xm69Bf0ycCVgX/SiF5diV5S9K+v+HCrvP6YVSvsmBYOvbt
mlxvqnU8pMg/OnOfSUck+rOzvkbGTWOf8zkWL3YQ8r7hKeAkG/fZj0iTjDzAXlqf
Ng5SEHiNsHzE96psVH1IuCH1gEz1La+WUpeXKg2FBj1IVOhl1D UCCYqWd5zd8HHX
/K8vh8OVsgv0Vv6X78Ugus9wXdUoYzODdrbne1dlwOP/3DK0mYG87p04sJCKzO8j
RC1TU85eM54gMSRdP58MG/wqwi3yFmiURrmlhhS9yz4c2vlJ1J9iLehxUjPTzt7G
ZgR6Xbbkk/ksiq6x/62vptvx/8zXN8/iRG32G9ESAJBrTmcwm8b3jrZYewKRkw/G
I82tu+ubWsdA+bOqD+Qcd810ybElMhGNb7SB/YMtoCGtGSha4DX/Tli/q8kw81zQ
tnb2vCKRe22p4s0D6F5hP5EKOHvEGx2TQtTvmUf+4hrO5033yP p/KZXM1IL7qfj6
2Ic7KMK2dmQavPJGsEG5O94Fjoh8F3djnPq2DaRR8pH37Rxh2U I83ZGfjrsJqWPM
nmaPjNOxBMKTBc3BqjTY
=5eW+
-----END PGP SIGNATURE-----