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).
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
01-03-2012, 08:18 PM
Petteri Räty
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
01-03-2012, 08:57 PM
Roy Bamford
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
01-03-2012, 09:21 PM
Sven Vermeulen
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
01-03-2012, 09:40 PM
Markos Chandras
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
Documentating advanced portage feaetures in Gentoo Handbook
