[gentoo-dev] New Install Instructions

[gentoo-dev] New Install Instructions

[Michael Lang]

Here are the new install instructions.  Not knowing the "proper" way to put 
this out for review, I have put it up at the following URL (my pardons if 
this breaks any protocols):

http://www.gibberishcode.net/gentoo-web/xsl/build.html

What to expect:

The first half has been completely overhauled to allow more than one method 
of documentation to be written.   I tried to take scattered notes about the 
system requirements and misc notes and collect them into an overview so 
that we weren't losing valuable info in cluttered notes and "oh, by the 
way" sort of remarks.

I felt that it was starting to get confusing talking about both fast-binary 
and from scratch installation methods in one sweep and it would've gotten 
really confusing with interlacing the third method, which I have written 
here for installing from existing distro.

This reorganization leads to _some_ duplication of material which you will 
see at the modprobe area, but I figured this was better than mingling the 
different install processes (and thus overly confusing the reader).

I didn't incorporate the altinstall doc which has installation over network 
instructions, but this can probably be easily incorporated if desired.

Most of the changes take place before the Setting up Partitions 
chapter.  Notes were inserted as appropriate after this point.

A section for Lilo was added as I figured this is a common occurrence for 
those converting over from existing distro.  In any event, I have no 
experience with Grub, so I can't comment on how to convert a Lilo system to 
grub.

Please keep in mind that I am a Linux newbie, so if I said something that 
made absolutely no sense or is completely wrong, then please definitely let 
me know without totally trashing me.  I made a lot of assumptions and 
"interpretation" of what Linux is doing on the system level based on my 
experience with Windoze.

There is a completely commented out section (search for BAH).  If you can 
offer some insights here, that would be great.

Regards,

Michael Lang

President
www.cybrains.net

"All things should be as simple as possible, but no simpler" -- Albert Einstein

Re: [gentoo-dev] New Install Instructions

[George Shapovalov]

Quick comment.

section 8: unpack and chroot. 
User is requested to mount -o bind /proc /whereewer/proc. 
This is fine if user boots from CD, however with "from existing distro" 
method it is not impossible, that user has 2.2.x kernel (I added recently new 
HDD to one server and used this as a good excuse to upgrade system. Total 
downtime in this way can be as small as just a  reboot!). The above command 
apparently is not going to work, so you might want to consider adding a 
comment at this point. 
While on the other hand user going this same route should probably know how 
to mount proc again...
Anyway, just a thought.

George


On Thursday 14 March 2002 22:34, you wrote:
> Here are the new install instructions.  Not knowing the "proper" way to put
> this out for review, I have put it up at the following URL (my pardons if
> this breaks any protocols):
[skipped]

Re: [gentoo-dev] New Install Instructions

[Dan Armak]

In the section abut installing piggyback from an existing distro, you should 
add that a separate partition is not absolutely required. A user can build 
Gentoo in a subdirectory, and then boot from a bootdisc, delete the old 
system and move the files in the chroot dir to root.

This requires a bootdisc (and thus a burner), but eliminates the effectual 
downtime of a day or so while the system is bootstrapping from a cd.

-- 
Dan Armak
Gentoo Linux Developer, Desktop Team (KDE)
Matan, Israel

Re: [gentoo-dev] New Install Instructions

[Michael Lang]

What exactly is the mount -o bind /proc...cmd doing?  Perhaps it can be 
skipped altogether when installing from another distro?  If not, then I 
should probably put an important note in the overview saying that 2.4 
kernel is required to use this method of installation...

Michael
At 11:39 PM 3/14/2002 -0800, you wrote:
>Quick comment.
>
>section 8: unpack and chroot.
>User is requested to mount -o bind /proc /whereewer/proc.
>This is fine if user boots from CD, however with "from existing distro"
>method it is not impossible, that user has 2.2.x kernel (I added recently new
>HDD to one server and used this as a good excuse to upgrade system. Total
>downtime in this way can be as small as just a  reboot!). The above command
>apparently is not going to work, so you might want to consider adding a
>comment at this point.
>While on the other hand user going this same route should probably know how
>to mount proc again...
>Anyway, just a thought.
>
>George
>
>
>On Thursday 14 March 2002 22:34, you wrote:
> > Here are the new install instructions.  Not knowing the "proper" way to put
> > this out for review, I have put it up at the following URL (my pardons if
> > this breaks any protocols):
>[skipped]
>_______________________________________________
>gentoo-dev mailing list
>gentoo-dev@gentoo.org
>http://lists.gentoo.org/mailman/listinfo/gentoo-dev

President
www.cybrains.net

"All things should be as simple as possible, but no simpler" -- Albert Einstein

Re: [gentoo-dev] New Install Instructions

[George Shapovalov]

Some programs might need to have access to /proc during bootstrap/emerge 
system after you chroot. 
mount -o bind /proc /mnt/gentoo/proc
does just that - "mirrors" /proc contents under /mnt/gentoo/proc (which will 
become new /proc after chrooting).
With kernel 2.2 (and correspondingly older mount) you cannot use -o bind 
option, but you can mount proc for the second time with:
mount -t proc none /mnt/gentoo/proc
that will take care of it, and this is what I did in such situation (and BTW 
this should work for 2.4 as well, just not that elegant, as in my case upon 
umounting proc mtab was not updated properly. Really minor issue, especially 
considering that the next step is a reboot :-) (and I was not using a full 
path when mounting, that might have been a problem). 

George


On Friday 15 March 2002 08:10, you wrote:
> What exactly is the mount -o bind /proc...cmd doing?  Perhaps it can be
> skipped altogether when installing from another distro?  If not, then I
> should probably put an important note in the overview saying that 2.4
> kernel is required to use this method of installation...
>
> Michael
>
> At 11:39 PM 3/14/2002 -0800, you wrote:
> >Quick comment.
> >
> >section 8: unpack and chroot.
> >User is requested to mount -o bind /proc /whereewer/proc.
> >This is fine if user boots from CD, however with "from existing distro"
> >method it is not impossible, that user has 2.2.x kernel (I added recently
> > new HDD to one server and used this as a good excuse to upgrade system.
> > Total downtime in this way can be as small as just a  reboot!). The above
> > command apparently is not going to work, so you might want to consider
> > adding a comment at this point.
> >While on the other hand user going this same route should probably know
> > how to mount proc again...
> >Anyway, just a thought.
> >
> >George
> >
> >On Thursday 14 March 2002 22:34, you wrote:
> > > Here are the new install instructions.  Not knowing the "proper" way to
> > > put this out for review, I have put it up at the following URL (my
> > > pardons if this breaks any protocols):
> >
> >[skipped]
> >_______________________________________________
> >gentoo-dev mailing list
> >gentoo-dev@gentoo.org
> >http://lists.gentoo.org/mailman/listinfo/gentoo-dev
>
> President
> www.cybrains.net
>
> "All things should be as simple as possible, but no simpler" -- Albert
> Einstein
>
> _______________________________________________
> gentoo-dev mailing list
> gentoo-dev@gentoo.org
> http://lists.gentoo.org/mailman/listinfo/gentoo-dev

Re: [gentoo-dev] New Install Instructions

[Daniel Robbins]

On Thu, 2002-03-14 at 23:34, Michael Lang wrote:
> Here are the new install instructions.  Not knowing the "proper" way to put 
> this out for review, I have put it up at the following URL (my pardons if 
> this breaks any protocols):
> 
> http://www.gibberishcode.net/gentoo-web/xsl/build.html

I like your new instructions.  Please continue to refine them based on
comments in here, and then when you feel they're ready, submit them on
bugzilla and we'll do one last edit and then make them our official
docs.  I think they're better than what we have.

Best Regards,

-- 
Daniel Robbins                                  <drobbins@gentoo.org>
Chief Architect/President                       http://www.gentoo.org 
Gentoo Technologies, Inc.

Re: [gentoo-dev] New Install Instructions

[Nathan Nutter]

I am not sure if regular users are allowed to post here, but I have some suggestions about install instructions.

1. In either the "/etc/localtime" or the "/etc/rc.conf" section add a note about setting "localtime" or "UTC", I thought that most people use localtime, so maybe it should be default in /etc/rc.conf(which is unrelated to this of course).
2. In the "Final Configuration" section you didn't mention lilo in summary since you added it; also, in the "lilo" section it almost seems like that is the next step, maybe show that you can do lilo or grub, user following down the list might not realise or may do both.
3. Link or more info on USE flags would be awesome.
4. In the "Setting up partitions" section, note about ext2/3 being resizeable, xfs growth but not shrink, etc. would be helpful.  I realize you have a link to in-depth discusion about filesystems, but I don't think this was discussed in those articles either.  Also a not about parted and/or fips and other tools to modify partitions.
5. Booting section, maybe make link to 3 separate pages, rather than all in one, same with lilo and grub install section.
BTW, I think the install instructions are excellent, they are to the point, and easy to follow, color coding is nice.  Good Work.
Panax

---
On 15 Mar 2002 10:11:33 -070  
 Daniel Robbins wrote:
>On Thu, 2002-03-14 at 23:34, Michael Lang wrote:
>> Here are the new install instructions.  Not knowing the "proper" way to put 
>> this out for review, I have put it up at the following URL (my pardons if 
>> this breaks any protocols):
>> 
>> http://www.gibberishcode.net/gentoo-web/xsl/build.html
>
>I like your new instructions.  Please continue to refine them based on
>comments in here, and then when you feel they're ready, submit them on
>bugzilla and we'll do one last edit and then make them our official
>docs.  I think they're better than what we have.
>
>Best Regards,
>
>-- 
>Daniel Robbins                                  <drobbins@gentoo.org>
>Chief Architect/President                       http://www.gentoo.org 
>Gentoo Technologies, Inc.
>
>_______________________________________________
>gentoo-dev mailing list
>gentoo-dev@gentoo.org
>http://lists.gentoo.org/mailman/listinfo/gentoo-dev
>


2,000,000,000 Web Pages--you only need 1. Save time with My Lycos.
http://my.lycos.com

Re: [gentoo-dev] New Install Instructions

[Michael Lang]

No Problem.  I will give it my attention for the next couple days and then 
submit to bugzilla.

One thing I would like to comment on...the intra-doc links are a bit 
difficult to work with, esp. if you add/delete chapters and sections or 
just move them around.  As soon as you do this a like like <uri 
link="#doc_chap15_sect2" easily becomes invalid during the editing process.

BTW, #doc_chap_15_sect2 doesn't work at all even though both do 
exist...looking at the generated HTML, it looks like the sections aren't 
getting "defined" at the top of the document as the chapters are.

Anyway, not to get off track from the first problem...I think this would 
work much better if we can explicitly name the chapters and sections in the 
documents...i.e. instead of:  <chapter><title>Installing a 
Bootloader</title>.... we do this:
<chapter name=bootloader><title>Installing a Bootloader</title> Then no 
matter where that final chapter ends up, when we say <uri 
link="#bootloader">Installing a Bootloader</uri>, we are assured that the 
link works as long as we don't delete the chapter or arbitrarily rename 
it.  Ditto for sections.

Another thought:  If we do shorthand <uri>#bootloader</uri> Then the 
transformer should automatically plug in the title of the chapter...if for 
some reason a chapter title doesn't exist, then plug in "Chapter 1", 
etc..  The nice thing about this is that the author no longer cares what 
the chapter title is and doesn't have to carefully proofread the final work 
to ensure all references to that chapter match the chapter title exactly.


At 10:11 AM 3/15/2002 -0700, you wrote:
>On Thu, 2002-03-14 at 23:34, Michael Lang wrote:
> > Here are the new install instructions.  Not knowing the "proper" way to 
> put
> > this out for review, I have put it up at the following URL (my pardons if
> > this breaks any protocols):
> >
> > http://www.gibberishcode.net/gentoo-web/xsl/build.html
>
>I like your new instructions.  Please continue to refine them based on
>comments in here, and then when you feel they're ready, submit them on
>bugzilla and we'll do one last edit and then make them our official
>docs.  I think they're better than what we have.
>
>Best Regards,
>
>--
>Daniel Robbins                                  <drobbins@gentoo.org>
>Chief Architect/President                       http://www.gentoo.org
>Gentoo Technologies, Inc.
>
>_______________________________________________
>gentoo-dev mailing list
>gentoo-dev@gentoo.org
>http://lists.gentoo.org/mailman/listinfo/gentoo-dev

President
www.cybrains.net

"All things should be as simple as possible, but no simpler" -- Albert Einstein

Re: [gentoo-dev] New Install Instructions

[Daniel Robbins]

On Fri, 2002-03-15 at 13:35, Michael Lang wrote:

> Another thought:  If we do shorthand <uri>#bootloader</uri> Then the 
> transformer should automatically plug in the title of the chapter...if for 
> some reason a chapter title doesn't exist, then plug in "Chapter 1", 
> etc..  The nice thing about this is that the author no longer cares what 
> the chapter title is and doesn't have to carefully proofread the final work 
> to ensure all references to that chapter match the chapter title exactly.

Good plan.  Please submit this as a bug to me and I'll add it to the XSL
later this month.  It shouldn't be too difficult.

Best Regards,

-- 
Daniel Robbins                                  <drobbins@gentoo.org>
Chief Architect/President                       http://www.gentoo.org 
Gentoo Technologies, Inc.

Re: [gentoo-dev] New Install Instructions

[Avi Schwartz]

On Tue, 2002-04-16 at 12:51, Michael Lang wrote:
> At 01:19 PM 3/15/2002 -0600, you wrote:
> 
> >1. In either the "/etc/localtime" or the "/etc/rc.conf" section add a note 
> >about setting "localtime" or "UTC", I thought that most people use 
> >localtime, so maybe it should be default in /etc/rc.conf(which is 
> >unrelated to this of course).
> 
> What's the verdict on this one?  I think I put localtime, thinking UTC 
> might mess up my dual booting back to Windoze, but not sure.

For dual boot systems the recommendation should be to use local time. 
On single boot system it should be UTC as it takes care automatically of
daylight saving switches.

-- 
Avi Schwartz
avi@CFFtechnologies.com

Re: [gentoo-dev] New Install Instructions

[Daniel Robbins]

On Sat, 2002-03-16 at 11:04, Avi Schwartz wrote:
> For dual boot systems the recommendation should be to use local time. 
> On single boot system it should be UTC as it takes care automatically of
> daylight saving switches.

Agreed.  Setting the clock to UTC should be recommended in the install
docs, unless someone has a dual-boot where the other OS is configured
for local time.

-- 
Daniel Robbins                                  <drobbins@gentoo.org>
Chief Architect/President                       http://www.gentoo.org 
Gentoo Technologies, Inc.

Re: [gentoo-dev] New Install Instructions

[Steve Ackerman]

How about adding a small section for installation of a software RAID 
system. It would be nice to show a brief overview of how to get this 
working...

Michael Lang wrote:

> At 01:19 PM 3/15/2002 -0600, you wrote:
>
>> 1. In either the "/etc/localtime" or the "/etc/rc.conf" section add a 
>> note about setting "localtime" or "UTC", I thought that most people 
>> use localtime, so maybe it should be default in /etc/rc.conf(which is 
>> unrelated to this of course).
>
>
> What's the verdict on this one?  I think I put localtime, thinking UTC 
> might mess up my dual booting back to Windoze, but not sure.
>
>> 2. In the "Final Configuration" section you didn't mention lilo in 
>> summary since you added it; also, in the "lilo" section it almost 
>> seems like that is the next step, maybe show that you can do lilo or 
>> grub, user following down the list might not realise or may do both.
>
>
> Good points here.  Turned this into a Bootloader chapter with overview.
>
>> 3. Link or more info on USE flags would be awesome.
>
>
> I'm not really qualified to write about the USE flags.  Anybody want 
> to provide me with a paragraph or two?  Or if there's a url somewhere 
> covering this, please point me there.
>
>> 4. In the "Setting up partitions" section, note about ext2/3 being 
>> resizeable, xfs growth but not shrink, etc. would be helpful.  I 
>> realize you have a link to in-depth discusion about filesystems, but 
>> I don't think this was discussed in those articles either.  Also a 
>> not about parted and/or fips and other tools to modify partitions.
>
>
> Again, I'm not really qualified to write this up.  If there's any 
> volunteers or someone can point me to some good docs, I'll be glad to 
> add info to docs...however, I'm not sure we want to put *every* sort 
> of detail into the install docs as this tends to clutter it a good bit.
>
> I tried to clean up a lot of this clutter..while I have definitely 
> trimmed a lot of fluff out, I don't think I've deleted any actual 
> information, yet.  A lot of things got pushed to the top into the 
> Overview chapter and then where ever I spotted the info being 
> rehashed, I zapped it.
>
> One thing I'm curious about is the Important Note about being at 
> FOSDEM...is this a note affecting the vast majority of installers 
> (i.e. something that should definitely be left in), or is this a 
> highly targeted notes to Gentoo developers or from earlier Gentoo days?
>
>> 5. Booting section, maybe make link to 3 separate pages, rather than 
>> all in one, same with lilo and grub install section.
>
>
> I thought about doing this as well, but figured people might want to 
> be printing the guide out because they are potentially going to be 
> offline for a while while bringing new system on-line.  Any others 
> with feedback?
>
> I have been re-drafting as ideas come in.  Please check out latest 
> revisions at:
>
> http://www.gibberishcode.net/gentoo-web/xsl/build.html
>
> Michael
>
> President
> www.cybrains.net
>
> "All things should be as simple as possible, but no simpler" -- Albert 
> Einstein
>
> _______________________________________________
> gentoo-dev mailing list
> gentoo-dev@gentoo.org
> http://lists.gentoo.org/mailman/listinfo/gentoo-dev
>

-- 

Steve Ackerman

Re: [gentoo-dev] New Install Instructions

[George Shapovalov]

Ok, this is it :-).
I have been following the discussion of these new install instructions and my 
feeling is that it is about the right place now.  Adding many small 
specialized topics will make it large and hard for 1st read and step-trough 
installation.
However there definitely are people interested in that or another special 
topic, and it would be unfare to just draw the line and not accept anything 
new. 
So what about having one "basic" install guide and provide a link to a 
"special topic collection"? For which experts on certain topics willing to 
see the topic covered will write up a short paraghraph or two and send it to 
maintainer so it gets included? This is of course if maintainer accept new 
responsibility. He is doing a great job (and demanding one) already!
Just my 2 cents on this :-)

George

On Wednesday 20 March 2002 09:23, you wrote:
> How about adding a small section for installation of a software RAID
> system. It would be nice to show a brief overview of how to get this
> working...
>
> Michael Lang wrote:
> > At 01:19 PM 3/15/2002 -0600, you wrote:
> >> 1. In either the "/etc/localtime" or the "/etc/rc.conf" section add a
> >> note about setting "localtime" or "UTC", I thought that most people
> >> use localtime, so maybe it should be default in /etc/rc.conf(which is
> >> unrelated to this of course).
> >
> > What's the verdict on this one?  I think I put localtime, thinking UTC
> > might mess up my dual booting back to Windoze, but not sure.
> >
> >> 2. In the "Final Configuration" section you didn't mention lilo in
> >> summary since you added it; also, in the "lilo" section it almost
> >> seems like that is the next step, maybe show that you can do lilo or
> >> grub, user following down the list might not realise or may do both.
> >
> > Good points here.  Turned this into a Bootloader chapter with overview.
> >
> >> 3. Link or more info on USE flags would be awesome.
> >
> > I'm not really qualified to write about the USE flags.  Anybody want
> > to provide me with a paragraph or two?  Or if there's a url somewhere
> > covering this, please point me there.
> >
> >> 4. In the "Setting up partitions" section, note about ext2/3 being
> >> resizeable, xfs growth but not shrink, etc. would be helpful.  I
> >> realize you have a link to in-depth discusion about filesystems, but
> >> I don't think this was discussed in those articles either.  Also a
> >> not about parted and/or fips and other tools to modify partitions.
> >
> > Again, I'm not really qualified to write this up.  If there's any
> > volunteers or someone can point me to some good docs, I'll be glad to
> > add info to docs...however, I'm not sure we want to put *every* sort
> > of detail into the install docs as this tends to clutter it a good bit.
> >
> > I tried to clean up a lot of this clutter..while I have definitely
> > trimmed a lot of fluff out, I don't think I've deleted any actual
> > information, yet.  A lot of things got pushed to the top into the
> > Overview chapter and then where ever I spotted the info being
> > rehashed, I zapped it.
> >
> > One thing I'm curious about is the Important Note about being at
> > FOSDEM...is this a note affecting the vast majority of installers
> > (i.e. something that should definitely be left in), or is this a
> > highly targeted notes to Gentoo developers or from earlier Gentoo days?
> >
> >> 5. Booting section, maybe make link to 3 separate pages, rather than
> >> all in one, same with lilo and grub install section.
> >
> > I thought about doing this as well, but figured people might want to
> > be printing the guide out because they are potentially going to be
> > offline for a while while bringing new system on-line.  Any others
> > with feedback?
> >
> > I have been re-drafting as ideas come in.  Please check out latest
> > revisions at:
> >
> > http://www.gibberishcode.net/gentoo-web/xsl/build.html
> >
> > Michael
> >
> > President
> > www.cybrains.net
> >
> > "All things should be as simple as possible, but no simpler" -- Albert
> > Einstein
> >
> > _______________________________________________
> > gentoo-dev mailing list
> > gentoo-dev@gentoo.org
> > http://lists.gentoo.org/mailman/listinfo/gentoo-dev

Re: [gentoo-dev] New Install Instructions

[Michael Lang]

At 01:19 PM 3/15/2002 -0600, you wrote:

>1. In either the "/etc/localtime" or the "/etc/rc.conf" section add a note 
>about setting "localtime" or "UTC", I thought that most people use 
>localtime, so maybe it should be default in /etc/rc.conf(which is 
>unrelated to this of course).

What's the verdict on this one?  I think I put localtime, thinking UTC 
might mess up my dual booting back to Windoze, but not sure.

>2. In the "Final Configuration" section you didn't mention lilo in summary 
>since you added it; also, in the "lilo" section it almost seems like that 
>is the next step, maybe show that you can do lilo or grub, user following 
>down the list might not realise or may do both.

Good points here.  Turned this into a Bootloader chapter with overview.

>3. Link or more info on USE flags would be awesome.

I'm not really qualified to write about the USE flags.  Anybody want to 
provide me with a paragraph or two?  Or if there's a url somewhere covering 
this, please point me there.

>4. In the "Setting up partitions" section, note about ext2/3 being 
>resizeable, xfs growth but not shrink, etc. would be helpful.  I realize 
>you have a link to in-depth discusion about filesystems, but I don't think 
>this was discussed in those articles either.  Also a not about parted 
>and/or fips and other tools to modify partitions.

Again, I'm not really qualified to write this up.  If there's any 
volunteers or someone can point me to some good docs, I'll be glad to add 
info to docs...however, I'm not sure we want to put *every* sort of detail 
into the install docs as this tends to clutter it a good bit.

I tried to clean up a lot of this clutter..while I have definitely trimmed 
a lot of fluff out, I don't think I've deleted any actual information, 
yet.  A lot of things got pushed to the top into the Overview chapter and 
then where ever I spotted the info being rehashed, I zapped it.

One thing I'm curious about is the Important Note about being at 
FOSDEM...is this a note affecting the vast majority of installers (i.e. 
something that should definitely be left in), or is this a highly targeted 
notes to Gentoo developers or from earlier Gentoo days?

>5. Booting section, maybe make link to 3 separate pages, rather than all 
>in one, same with lilo and grub install section.

I thought about doing this as well, but figured people might want to be 
printing the guide out because they are potentially going to be offline for 
a while while bringing new system on-line.  Any others with feedback?

I have been re-drafting as ideas come in.  Please check out latest 
revisions at:

http://www.gibberishcode.net/gentoo-web/xsl/build.html

Michael

President
www.cybrains.net

"All things should be as simple as possible, but no simpler" -- Albert Einstein