Bug 228427 – Deficiencies in Overlays docs makes install difficult

• Product: [OLD] Docs on www.gentoo.org
• Status: RESOLVED FIXED

[Description bungernut 2008-06-19 22:27:58 UTC]

I had to find out via forums that to use layman at least how I thought it was intended you needed to emerge "/dev-util/git" and "subversion". These were not mentioned in the document and makes the following steps of getting the available packages impossible. Either these should be dependencies of layman or the doc needs to mention that you need them.

In order to emerge the package you need it probably should be mentioned that you will most likely (always?) need to edit /etc/portage/package.keywords to accept ~ on the packages you need.Otherwise you will be emerging the regular portage apps if they exist already.

I also found the code "emerge -av <category>/<package>" in the doc confusing. An example would have been good or some explanation of what category means. I was trying "emerge -av science/octave" since <package> could be interpreted as the layman package you installed earlier. 

In my opinion you might as well remove the line "echo "source /usr/portage/local/layman/make.conf" >> /etc/make.conf" under code listing 2.1. For the first time user this is not what you need to do, I was lucky that I read ahead before I did it. But in fixing the problems of installing the science overlay which took quite a while I had forgot that I had to skip that step until I had one installed. It would fit better in my opinion between code 2.4 and 2.5 as a final step before trying to emerge a package in the overlay. 

Reproducible: Always

Steps to Reproduce:
1.Use the documentation to try to install a package in an overlay
2.
3.

Actual Results:  
Did not install necessary dependencies for layman with a simple "emerge layman" so couldn't install science overlay.Figured that out after an hour.
Tried to emerge the regular portage Octave for a few min, got on IRC #gentoo-science and figured out from the nice people that I was supposed to be putting the packages in package.keywords to see the overlay ebuilds. 
Forgot to go back to the beginning of the document to add the source to make.conf until I was reminded on IRC.Finally figure it all out with much frustration and resource hunting.

Expected Results:  
Dident expect to have to require the use of much forum browsing and theuse of IRC to figure out how to install something that was in the end so simple.

[Comment 1 Ben de Groot (RETIRED) 2008-06-19 22:32:07 UTC]

Since version 1.2.0 layman now has git and subversion useflags.

[Comment 2 bungernut 2008-06-19 22:35:21 UTC]

even still, how would one know that you needed to use the flags? I had no idea what they were for, i didn't even look at the useflags necessary because they were never mentioned. 

[Comment 3 Rafael 2008-11-24 00:50:13 UTC]

(In reply to comment #1)
> Since version 1.2.0 layman now has git and subversion useflags.
> 

Can't it be fixed in the stable version too?

Also there's another error in the  docs, in the line:

 echo "source /usr/local/portage/layman/make.conf" >> /etc/make.conf

In my system, the correct is:

 echo "source /usr/portage/local/layman/make.conf" >> /etc/make.conf

[Comment 4 James Broadhead 2011-07-24 14:44:35 UTC]

These problems have been fixed -- I suggest closing.

[Comment 5 Sebastian Pipping 2011-07-25 01:20:22 UTC]

I have added mention of

  USE="git subversion"

to mentioned page now.  keep in mind that sync takes some time until

  http://www.gentoo.org/proj/en/overlays/userguide.xml

reflects my changes.  If there is need for more, please re-open this bug or make a new one as you see fits.  Thanks.