Re: [gentoo-dev] Some suggestions

[Alexander Gretencord]

On Sunday 07 September 2003 10:19, Troy Dack wrote:
> > 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)

You are right, make.conf is quite well commented in the file itself. But Jan 
is also right :) man is _the_ standard way of looking something up. I am all 
for documentation in the config file itself, that's especially useful if you 
have a big file with many options _but_ gentoo has a general problem with 
documentation. Nothing responds to a 'man xyz' in gentoo or if it does, the 
information is outdated. I think that's one serious disadvantage.

Nobody likes to write documentation, I know, but it is necessary. As Phil 
Richards pointed out somewhere else in this thread: "I don't like running 
commands as root that neither have a man page nor respond to "-h" or 
"--help"."

> "Gentoo moves pretty fast; if you don't stop and look around once and
> awhile, you could miss out."

Oh, too true. Somewhere in time fixpackages was added. I was told to run it. 
Ok but what's it good for? Either portage should run it on its own, if it is 
necessary and I can't do anything about it and _not_ tell me anything _or_ if 
it tells me about it and even tells *me* to run it, then have some 
documentation. It has no man page, not even one telling to use info, nor does 
it respond to -h or --help. No documentation at all and that sucks elephants 
through key holes. I had to search through the forum to find out what it 
does. Documentation is one of the big problems of gentoo.


Alex

--
gentoo-dev@g.o mailing list