I would like to see a bit more descriptive information included with ebuilds, something that could be viewed with a new emerge flag. The information currently available with "emerge --search <pkgspec>" is quite cryptic and sometimes insufficient. Such proper self-doc might follow more closely the style of documentation for linux kernel build options, which provide anywhere from 2 or 3 lines to a couple of screens of info for each option. Debian also generally provides better documentation for packages than does Gentoo. Helpful information such as warnings, honored USE flags and available environmental vars which will affect the merge would also be very useful. I realize that this would substantially increase the size of the portage tree, which is already one of the drawbacks of Gentoo. I think the tradeoff would be worth it. For system which need to keep the size of the portage tree to a minimum, a separate tree (e.g. /usr/portage/doc) might be used to hold this information and whether or not this were populated by a sync would be controlled by a setting in make.conf. So... emerge --document <pkgspec> would provide all one might need to know about installation and configuration of an ebuild. A lot of important information is already presented by ebuilds as they're executed, but it would be very useful to have this and other relevant information available at any time, including before a package is emerged.
This is a terribly unspecific request. Don't really see what documentation you mean. You can see the use flags in emerge -pv output, metadata w/ emerge -s and that's about all what's there to document. Or use eix/esearch/equery or whatever other tool. If something really needs documenting, there should be a comment in the ebuild.
You can always read code in an ebuild and find out what it does, but having the information available from the CLI would be much more convenient and would be very helpful. A few examples, since you want something more specific: amanda honors a substantial set of environment variables at compile time which can be set in /etc/env.d/amanda. These can be found a couple of screens down in the ebuild, assuming one knows how to read the code. It would be nice to be able to review these without cd'ing 4 levels down into the portage tree and digging into the ebuild code. Some packages, such as mysql, require emerge --config after a build, some don't. This info is generally emitted by the ebuild when it gets run, but this information can get lost or buried. I could go on, but these are a couple that come to mind right away. This relates directly to http://bugs.gentoo.org/show_bug.cgi?id=11359. This bug discussion wouldn't have become so large if some of the information people wanted were available pre or post merge. Jacob, please re-open this and bring it to the attention of appropriate gentoo devs. Don't just close it because you feel it isn't specific enough. I'll be glad to go into more detail if you wish. Gentoo pacakge docs are _very_ short, compared to the package docs available for other distributions. The situation can be improved on!
(In reply to comment #2) > This relates directly to http://bugs.gentoo.org/show_bug.cgi?id=11359. This > bug discussion wouldn't have become so large if some of the information people > wanted were available pre or post merge. > > Jacob, please re-open this and bring it to the attention of appropriate gentoo > devs. What appropriate devs? Look, if you feel that a particular ebuild needs more documenting or whatever, file a bug about _that_ particular ebuild, and we can stick some info to pkg_setup() or whatever else. > Don't just close it because you feel it isn't specific enough. I'll be > glad to go into more detail if you wish. Gentoo pacakge docs are _very_ short, > compared to the package docs available for other distributions. The situation > can be improved on! Filing a generic bug requesting "oh, ebuild internals should be documented" without even specifying what exactly and how/where is should be documented won't go anywhere and can't ever be fixed. Also, bloating the ebuilds/tree in general w/ lots of redundant comments etc. isn't really an option. See GLEP42 if it's what you want (http://www.gentoo.org/proj/en/glep/glep-0042.html). Closing this, bugzilla is not a proper place for broad discussions. If you have some ideas, ask in gentoo-dev mailing list. Thanks.
Jacob, this was filed as a _feature request_ and "appropriate devs" means exactly who and what it's intended to mean when anyone posts to bugs.gentoo.org with a feature request. You have obviously given very little thought to what I'm saying. I'm not going to pursue this, but your attitude doesn't do credit to you or Gentoo.
After some discussion, I'm reopening this. It may be somewhat vague, but it deserves better than to be summarily closed and ignored.
(In reply to comment #5) > After some discussion, I'm reopening this. It may be somewhat vague, but it > deserves better than to be summarily closed and ignored. Sigh. I've already asked you twice to go discuss things to mailing lists. Mailing lists are for discussions, bugzilla is for bugs. Pretty simple. Thanks!
Then remove "enhancement" as a severity category. I'm filing a request for an enhancement. Please either modify the Severity list to remove this category or else let this stand. Reopening ....
It looks as if the database structure for this enhancement is already in place in the <longdescription> tag in the per-package metadata.xml and is supported by the DTD, but it doesn't look as if this information is well used, or that it can be queried either by emerge or equery. I should probably modify this request to be more specific and ask that an option be added to either emerge or equery that can search or query this data. It would additionally be nice if ebuild maintainers would make good use of this tag. Jacub, please leave this as REOPENED and assign it.
I don't have anyone to assigned this bug to. Go discuss such suggestion to gentoo-dev mailing list and open a bug once you've got at least some implementation concept ready.
Closing. Don't reopen this bug, please. This is not a discussion forum.
JACUB, PLEASE ASSIGN THIS BUG TO THE PORTAGE DEV GROUP. IT IS A LEGITIMATE ENHANCEMENT REQUEST. IF YOU DON'T UNDERSTAND IT, THEN GET OUT OF THE WAY AND LET SOMEONE ELSE DEAL WITH IT.
Don't shout. Thanks. Do what I suggested and don't bugspam us. Thanks for understanding.
This bug is closed. Like - really closed.
Then please do as I suggested, get out of the way, and assign this bug to the portage dev team.
Please, take such general discussions to gentoo-devel (or gentoo-portage-dev if you think that portage is really a place do to such stuff) mailing list. http://www.gentoo.org/main/en/lists.xml This suggestion is more like some material for GLEP, definitely not for filing bugs in bugzilla at this stage. I've politely asked you to use appropriate place to discuss this enough times already. So - if you don't stop abusing our bugzilla system, I'll have to ask our bugzilla stuff to temporarily suspend your account. Thanks.
CLOSED.
Jacub, This is a legitimate request for an enhancement to a Gentoo facility. I don't need to provide implementation details here, or anywehere else, although I'll be happy to look into the matter. This is a totally appropriate format to make such a request. I have done so in the past and will continue to do so, as have many other people. If you want to refer this to bugzilla staff please do so. I would be happy to discus the matter with someone with more understanding of the matter (and more personal courtesy) than you seem to have.
Reassigned to dev-portage per request, but being reassigned does not change anything. Bring this up on a mailing list and get community support for it as Jakub has said so many times already.
