Re: [gentoo-dev] Some suggestions

[Troy Dack]

On Sun, 2003-09-07 at 15:59, Jan Krueger wrote:
> On Sunday 07 September 2003 03:08, Martin Schlemmer wrote:
> > Come on guys, think what is best for the *distro* (meaning,
> > what will work best for the other 90% of users,

I'd say 95% of user, but that's just me :P

> From my point of view the best for the 90% of users in this case (make.conf)
> would be:
> 1. a very precise documentation with examples about the user settable things
> for make.conf thats accessable via a standard command, like man make.conf or
> info make.conf

How imprecise and unaccessible is:

	nano -w /etc/make.conf

All settings are commented, and commented well, and it's available using
standard commands (you could even use ed or a combination of cat, less,
head & tail if you really wanted to)

> 2. a clean, easy to read configuration file without mess and things the user
> doesnt care about so it is easy for the user (even easier for tools) to
> change exactly the setting the user wants to change because it is easier to
> identify the place where the change must happen and easier to identify the
> values that already are there.

OK, I've installed Gentoo on my boxes that many times I know the process
pretty much off the top of my head, however I can't remember all of the
FEATURES that are available, having them listed in make.conf is
beneficial.

> You may try this yourself:
> nano -w make.conf as it gets installed
>
> and
> nano -w make.conf with just the settings you actually use, everything else
> thrown out.

grep -v "#" /etc/make.conf|wc -l && wc -l < /etc/make.conf
     31
    290

Fair enough, I've got 259 lines of comments, I can live with that, the
file isn't confusing and the options are grouped sensibly.

It seems to me to be fairly standard Linux practice to provide a well
commented config file that can be modified slightly as suited, eg:

grep -v "#" /etc/squid/squid.conf | wc -l && wc -l <
/etc/squid/squid.conf
    258
   3231

So, I've got nearly 3000 lines of comments in my squid.conf, I bet you
won't see anyone suggesting that squid gets installed with an empty
config file and you have to roll one by hand.

> Which one is easier to modify?
> Especially try to change a FEATURE setting. Or even better, let a new gentoo
> user try to change a FEATURE setting.
>
> If the user is not sure about the variables/values to put there the user may
> at anytime suspend nano or open another terminal or use another virtual
> console and execute man make.conf

So it is easier to explain to a newbie that they need to switch to a
new virtual console, start up the documentation viewer (man, less,
lynx), read through the docs, switch back to the other virtual console,
make a few changes in the file, lather, rinse, repeat.

I'll differ with your opinion here, I think it is much easier to have a
well commented file (same as reading code, if the comments are in the
code, it's easier than referring to a description of it and trying to
read the code).

> most users probably use just 4 or 5 settings:
> use flags
> c(xx) flags
> sync
> mirrors
> features

True, those are probably the only ones people set, but they are some of
the most important ones in the system.

Having a config file that lists only the variables to be changed will
lead to people swapping conf files ("Here, use this one it is all set
and works well for me") which could in turn lead to more problems
because people have settings enabled/disabled and they don't know why,
or what those things do.

> the rest is for the majority of users just useless in make.conf. So my
> expirience (and assumption).
>
>
> So i strongly support:
> On Saturday 06 September 2003 23:48, Steven Elling wrote:
> > Requiring portage updates to make.conf at all has always bugged me.  The
> > file is meant to contain custom settings for portage and to append to or
> > override variables in make.globals and the defaults.  It should not hold
> > all the documentation for make.conf.  It should not hold all the
> > defaults... that's what make.globals and the defaults are for.
> >
> > Why is all the documentation on make.conf in make.conf anyway?  Shouldn't
> > it be in make.globals or better yet the man page?
> >
> > make.conf is used for system customization and, as such, portage should
> > leave it alone.  When portage is installed on the drive for the first time
> > it should not create make.conf.  Portage should leave it up to the
> > admin/user of the box to create the file.
> Thats sound like a clean solution to me. Thats the way it should be.

Given that a very, very, very large portion of the questions that get
fielded on #gentoo are the result of a significant lack of RTF'ing M I
don't think having an empty file is the way to go, #gentoo would just
degenerate into "RTFM" responses (of which I am pleased to say that
generally there are not *that* many).

[see above re: swapping of config files as well]

> I refuse to update my customised and over the time grown settings in
> /etc/make.conf with /etc/make.conf with comments for things i never intend to
> use. That doesnt make any sense to me to put such useless comments with
> documentation that has to be in the man page anyway in a file thats so
> important for my system.
> I refuse to let anything automaticly update this file.
> I refuse to touch this file until there is a strong need to edit it because i
> want a feature/useflag or whatever. So then, and only then, i edit this file
> or let a tool edit it (eg: euse).

etc-update, merge files, half a dozen l's, a couple of r's, the odd eb
and it's all done, new FEATURES merged in, old settings left intact.

Not hard, plus I am now aware of what new things are available.

> If a change, because of a new advanced portage version, to my existing
> settings is needed, this change should be delayed as other software does it:
> mark the old thing as deprecated and warn the user for some time|versions to
> give the user time to get informed and do the change manually or by using a
> dedicated tool.
>

"Gentoo moves pretty fast; if you don't stop and look around once and
awhile, you could miss out."
-- 
Troy Dack        "Yes, yes, I know that, Sydney ... Everybody knows that!
tad@g.o    ... But look: Four wrongs squared, minus two wrongs to 
                  the fourth power, divided by this formula, do make a
                  right." -- Gary Larson

Public Key: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x4D90BE3C
Key fingerprint = 1F3D 6C15 16AA 09D5 0C96  92E5 FD89 16F9 4D90 BE3C