I suggest that additional command was added into emerge. Suggested name is emerge doc, emerge hint, or emerge readme. This command would allow the user to know where to start reading official Gentoo-supported documentation of the package to be sure he is using the program correctly and to have a clue how to use it at all in first line. With source distribution, this function is fulfilled by README in toplevel directory of source tarball and this system works well. By gentoo-supported documentation I mean that the user doesn't do a STFW and then comes across outdated ancient document that misleads him into hell, and also that this documentation will be chosen in a way that bugreports against it will be accepted either by gentoo team or upstream development team of the package to ensure recyclation of time spent on possible problems with the documentation. Reproducible: Always Steps to Reproduce: 1. 2. 3.
The standards for new commands are "man emerge", "emerge --help", "emerge -h". The first is particularly important, but all three of those work already and give you up to date information.
I meant for a particular package, not for emerge itself. I have changed it in the summary.
You should be able to find these files in /usr/share/doc/<package name>/ Docs team, is this standard documented anywhere for users to see?
the docs that docs team deals with are only on www.g.o/doc/lang/whatever. for information about readmes or something like that, you would have to look at the package documentation, which is inside the tarball. we do _not_ have anywhere close to enough docs to cover every package, and many docs don't really deal with a package at all if the package maintainer believes a doc that docs-team or a project maintains would be useful, (s)he is free to put it in EINFO at the end of the emerge imho, this is not a docs-team bug...
Of course you don't. The docs are already located in /usr/share/doc/<pkg>. The question is whether or not users are ever pointed to look there. If not, notifying users of that standard in the docs somewhere will solve this bug.
ah, i see what you are saying now, jstubbs. to my knowledge, its not documented in any official documentation. perhaps a side note in the FAQ or "working with portage" in the handbook?
Sorry about the ping-pong with dev-portage. We can insert this info in the handbook.
Added some info about installed package documentation. It will show at http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=2&chap=1#doc_chap3_sect3 within an hour.