Packages, especially services, which require special post-ebuild configuration need a logical online space for special instructions, such as config files that need to be modified, rc-update runlevel selections (does it go in 'boot' or 'default') and other similar stuff. This might be no more than a database field containing a URL pointing into the documentation, where much of this info can already be found. Many times an ebuild will display a summary of post-ebuild instructions, but these are transient and sometimes not even seen if one is doing several ebuilds from a single emerge command. The general level of Gentoo documentation is excellent, and I frequently will do a google search with 'site:gentoo.org' to find this stuff, but it would be really nice to be able to drill down to a package description online and find a reference to full gentoo-specific install and config docs.
How many packages really require gentoo-specific documentation? Most of the requirements are "rc-update add <package> default" to add it to the default runlevel, and then read up on the documentation of that package.
Sven, I don't know a number here, but some packages _do_ want to be one runlevel as opposed to another, and the rc-update issue is only part of the problem, and sometimes only a small part at that. Yesterday, for instance, after about 12 hours of work, I finally managed to debug a problem with a Gentoo amanda install which involved samba and xinetd (all three are pretty complex packages), plus permission, ownership and security issues. Some helpful hints went by in the closing notes on the amanda ebuild which helped, but such notes are very transient and get lost completely in a multi-package emerge. If they're mission-critical to getting the package working then they need to be in some more easily accessed location. It would be nice to be able to go to packages.gentoo.org, bring up a package and see a reference to the location of the docs, espeially those that are critical to getting the the package working properly with Gentoo. Some packages such as openldap and cups have good install and setup docs at gentoo.org. Some have notes at the end of the ebuilds which can save a lot of setup time if you get a chance to read them. Some have good instructions included from upstream such as man pages, READMEs or HTML documentation. Yet others, such as mrtg and tidy, have little in the way of included docs but provide good online documentation. Here's a thought. The PHP website (www.php.net) has excellent online docs, plus a way for users to annotate the docs. The annotations are not always spot on, but many of them are very helpful. Maybe a way for people to add annotations to the per package info in package database would be a good move in this direction. This may not be technically feasable, but from an outside perspective it seems like and idea worth considering.
perhaps Bug 11359 is enough to address this ?
This bug is more of a feature-request to extend the services (packages.gentoo.org) to include this information online. Perhaps I should take this up with whoever is working on packages.gentoo.org because it might indeed be interesting. Otoh, the einfo/ewarning messages aren't structured so there is no way to really know what information would be feasible to place on packages.gentoo.org and what isn't. Currently we don't have PHP (nor any database backend) available for infrastructure so providing user-commented documentation is difficult. I also believe that, if we would provide it, it would grow enormously -- just take a look at the forums. It's almost impossible to keep up with them :/ That's of course a personal annotation.
Interesting reference SpanKY. Looks like other people are thinking along the same lines <grin>. What I'm suggesting goes a bit further, and I prolly should shut up before the idea gets completely out of hand ;-) Yeah, this is a feature request. Linux documentation, in general, is a real riot in the rookery, even with LDP! Docs are good, but essential info is scattered about in different formats and venues. I've observed that Gentoo has made some really solid progress w. the online handbook, install docs, etc. and I thought I'd toss the idea in the hat. I still think the idea of user annotations in the package db would be a real winner. It sure worked in the PHP docs.
Sven, one would think that the annotations in the PHP docs would get out of hand, too, and certainly some of the functions have some sizeable annotation collections. But it really is pretty managable, and sometimes quite helpful from a user's perspective. The annotations aren't a help forum, and by and large people who post annotations realize this and are doing the Right Thing - posting supplemental information that will help others, and the overall result has been positive. The PHP doc maintainers may edit the annotations some, I don't know.
The PHP annotations are still targeted to a small amount of people, namely PHP developers (coders if you wish). Gentoo is targeted to a much broader spectrum of people: computerusers.
Would a knowledge base like system be interesting for this? It is a database-driven website that contains answers to common questions. The knowledge base software makes sure that specific queries are mapped to the correct answers. By having the users be able to provide Q&A and have the documentation team (or any other team) check the answers for accuracy, we would provide fast answers to common questions without losing the QA we currently have for the documentation. It would allow people to add Q&A about certain services (for instance a question on Virtual Hosts in Apache with Gentoo)...
A searchable Gentoo Knowledge Base would help, for sure, but would be a major task. A search function on the existing documentation would help, too, although one can get this straight from google ("site:gentoo.org") since most of the gentoo pages appear to be indexed. I really don't know whether or not package annotations would get out of hand and turn into something else. You're right that the target audience for the PHP function database is different in nature from from the target audience for a Gentoo annotated package system. I have observed, however, that the community of people using Gentoo in general seem to be much more in tune with concepts of open source responsibility than with most other distributions, and are by and large pretty savvy. Gentoo is not for the faint of heart! If an annotated package database could work with _any_ distribution, it would be Gentoo.
a little knit picky but better to get out now than later ... lets not call it 'Gentoo Knowledge Base' ;)
<LOL>! The temptation to co-opt the term altogether is pretty strong :-) I think a knowledge base on Gentoo would be a really good idea. Prolly the only difference between that and annotated packages is a matter of reference. It might be feasable, and technically easier than annotated package descriptions, to have a search button on each package listing that would automatically do a search on the knowledge base for articles related to that particular package.
*** Bug 37970 has been marked as a duplicate of this bug. ***
I'm going to mark this one as "WONTFIX". The knowledge base (or whatever we'll call it) idea is still active, but providing a database as requested in this bug won't be implemented in the nearby future (if ever).
As you wish, however this is at the core of one of the only serious drawbacks to Gentoo, IMHO. At very least, some way needs to be found to capture and present vital information on ebuilds which is sent to standard output during a build. Debian pauses and presents questions and important information in an ncurses environment and waits for the "OK" button (and I can capture this info and save it off as it shows up). I find that with Gentoo I have to stand by and be ready to press Ctl-S to stop a build so I can back up the scroll buffer and swipe critical info on the previous ebuild before it scrolls into oblivion. Gentoo developers put this stuff into the ebuilds for the benefit of people using the packages, but without some way of capturing this, they might as well not bother if the build is part of a series of builds done with, say, 'emerge -u world'.
Indeed, but what you say now is discussed in a separate bugreport (#11359).
