[gentoo-dev] Installation Instructions improvements

[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...

Re: [gentoo-dev] Installation Instructions improvements

[Pierre-Henri Jondot]

On Sun, 20 Oct 2002 02:36:00 +0200
Andreas Karafyllis <ak_personal@onlinehome.de> wrote:

> 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.
> 

Agreed. The small iso for gentoo 1.1a took care of this... This has been
forgotten in 1.4_rc1 isos... Hope new isos (and especially with better
hardware support) will come soon.

> 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
> 
Done... 

> 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.

You're right... The build document could be made clearer there... 

> 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

Hmm... Well, if it can serve as a lesson, learning new users to think, and
read the docs, before messing things up, it is not such a bad thing...

> 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)
> 
Not sure about the second (synctty) because it is listed as (unused) on my
system, but quite confident pppoe is not needed at all... But a note has
been added to the build instruction to that effect...

(N.B. : PPP support for async ports is needed for the async mode of
rp-pppoe, which is the default, PPP support for sync tty ports is needed for
the sync mode of rp-pppoe (to be enabled by editing /etc/ppp/pppoe.conf) as
well as another one. As for pppoe, it could only be used when rp-pppoe is
built with kernel mode pppoe support, which is not currently done by the
rp-pppoe ebuild.)

(I was perhaps wrong though about the compression algorithms in the build
documentation... Sometimes they are needed it seems, sometimes they aren't.)

-- 
Pierre-Henri Jondot <Pierre-Henri.Jondot@wanadoo.fr>
Page perso : http://perso.wanadoo.fr/phj