It has come to my attention, after four years of using Linux as my primary OS, that there are not just a few but many packages which secretly look for files which do not exist on my system, and are not documented in the manpages. There is almost never any manpage for any configuration file and the manpages for programs which do look for phantom files almost never mention the existence of much less the format of such phantom files. The documentation for Xterm only implies the existence of a phantom file in a 1-sentence comment at the end of a 20 page document. Phantom files are not hinted at by the programs themselves in normal operation. This creates an unacceptable situation where it is possible for a user to create an arbitrarily named file expecting nothing to happen and instead see arbitrary and undesirable changes to system behavior. Furthermore cases where important changes to system behavior are desirable but only possible through extensive knowledge that is not available from the system itself or even through google by reason of unknown keywords. I, myself, have only learned of such files from either helpful comments regarding important problems I was trying to deal with. I was not able to implement the suggested changes because I don't have any documentation explaining what problems the changes I was told to make might cause. At times I have even been insulted for my ignorance of things for which only ESP could conceivably have brought me knowledge of. Once again, this is unacceptable. Gentoo should get on upstream's ass about this problem and demand that **ALL** configurations be made available through modern interractive GUIs (text mode or X-based, I don't care). Failing that, every package that is determined to use phantom files -- no mean feat! should come with examples of the correct usage of those files and all appropriate documentation. I am calling this a major bug because one such phantom configuration file prevents me from using voice in Second Life, which in turn is a major problem because second life is increasingly expecting all participants to be voice enabled. Reproducible: Always Expected Results: DOS. As in all things the user actually cared about, DOS did this the right way. Even if phantom files existed in DOS, they were almost never outside the program's own directory and never posed a risk to the stability of the system.
If you have issues with upstream documentation, then go and complain *upstream* about sucky documentation. We don't write docs, we ship upstream tarballs. This absolutely can't be assigned to anyone or fixed in any way by us, marking UPSTREAM. Please don't misuse Gentoo bugzilla for generic rants about upstream issues.
