[gentoo-dev] Installation Instructions improvements

[Andreas Karafyllis]

Hello everyone!

I installed before 2 days the 1.4-rc1 version (from the UT2003 CD) using an 
ADSL connection and I would like to suggest some improvements and corrections 
to the installation instructions. Before that, I would like to say THANK YOU 
for this great distribution. Keep the good job. After testing the last years 
a lot of different dists, I think that this time I found what I was looking 
for.

I describe my suggestions under the title of the corresponding sections.

2.Booting
----------
I use a german keyboard (I am a Greek living in Germany :-)) and I was not 
prompted to choose a keyboard layout after I logged in as described in this 
section. This can be a VERY difficult situation for some people and certainly 
a very bad first impression.

5. Configure installation networking
----------------------------------------
The instructions about the ADSL subscribers are a little bit confusing. There 
is only a note which refers to another document. I think that this reference 
make thinks complicated and should be removed. At this point you have to do 
only "adsl-setup" and then "adsl-start" (net-setup eth0 was not needed in my 
case). Therefore I suggest to remove this note and add a subsection for the 
ADSL configuration using the following listing:
# adsl-setup
# adsl-start

14. Final steps: kernel and system logger
----------------------------------------------
Many things here.
a) I decided initially to use the gentoo-sources. But when I was configuring 
the kernel using "make menuconfig" I could not locate the XFS module (I 
choosed the XFS filesystem for my root partition in the previous steps). You 
should have a big warning here in which sources is available the XFS. Finally 
I used the XFS sources of course.
b) The notes and warnings must be BEFORE the code listings. Many people (like 
me ;-)) are not so patient and execute the listsings before reading all the 
paragraph.
c) I realized later (after booting)  that my adsl connection was not working. 
I suspected that probably I forgot something when I was compiling the kernel. 
I booted with CD again, brought up the ADSL connection and made an lsmod to 
see which modules are loaded. I realized that the problem was that when 
compiling the kernel I did not included the "PPP support for async ports" 
(ppp_async) and "PPP support for sync tty ports" (ppp_synctty). Both are 
needed (and the pppoe of course)

Some final notes about the "emerge" now.
1. It is not very clear in the current man page of the emerge (and the portage 
howto) how do you rebuild already installed packages after, for example, you 
changes the USE options in the make.conf. After asking for help in the 
#gentoo channel, they told me to use the -e or --emptytree option. I think 
that --emptytree is not the most appropriate name for this thing (That's the 
reason I missed it in the first place). You should provide an --rebuild alias 
too.
2. What is the best way to uninstall packages ensuring that you do not break 
depedencies? Please describe it in a clean way in the man page and the 
portage howto. I am not sure about the answer yet :-(

I hope you will find useful my suggestions

Have a nice time!!

Andreas Karafyllis

PS: I found a bug also in the licq package but I will use the bugzilla for 
this...