The docs are not clear. Whenever docs talk about LiveCD, they should hyperlink this word to one of those three files(x86-1.4-20030911-cd1.iso, x86-1.4-20030911-cd2.iso, x86-basic-1.4-20030911.iso). I've realized x86-basic-1.4-20030911.iso is not LiveCD, as it's missing either the distfiles/ or packages/ subdirectory. The docs should be clear on which CD are the sources. They aren't on any!!! Why? Why is user forced to install binaries from CD2? At least in one place the installation manual talk about CD1 but the directory was on CD2. CD2 is not bootable, if I remember right, so the document should say that LiveCD's are bootable. http://www.gentoo.org/doc/en/handbook/handbook.xml?part=1&chap=2 It would be nice if a user could download from somewhere the contents of packages/ and distfiles/ and possibly some other directories, so that one could install from sources without network at all! For example one cannot copy /usr/portage as a whole, as it seems to me that the directory contains the information what is already installed(so one shouldn't extract the whole tree on a new box). Make the paragraphs numbered. Look at this text at http://www.gentoo.org/doc/en/handbook/handbook.xml?part=1&chap=2 : "Now take a look at the available installation media: * Gentoo LiveCDs o Gentoo basic LiveCDs o Gentoo 2-CD LiveCD Set o Gentoo KDE/Gnome LiveCD * Knoppix * Existing Distribution * Net Booting " When you look at the paragraphs like "Gentoo KDE/Gnome LiveCD" and "Knoppix". They have same font type, same colour and one has no clue that Knoppix is an alternative approach. This problem is everywhere in th edocument and makes is very difficult to follow the trajectory(as one has to skip time to time so paragraphs). http://www.gentoo.org/doc/en/handbook/handbook.xml?part=1&chap=3 Section 3.a is unclear. - Mention why the basic LiveCD isn't listed. - Make more clear the following text so that one knows what's on CD1 and what's on CD2: "If you are in this situation you will need to use the 2CD-sets. These sets include the sourcecode, a snapshot of the portage-tree and the tools to install a Gentoo base-system and beyond. This method comes at a price: You won't have the very latest software, although differences will be minimal." - I used Gentoo 1.4 CD's and haven't managed to to install from sources as not even those "system" have been on the CD1. - Explain the "emerge -k" usage in the install document. Often emerge(1) tried to connect over the network instead of picking up the binary package from the local disk. - Why does one have to have to copy the packages out of teh installation CD-ROM to a disk? That sucks is definitely isn't clear from the installation document unless one hits the point during install. - I had to use second CD-ROM drive to mount the CD2 because the CD1 media was mounted during the stage3 install I've performed. That's unexpected while reading the install doc. In chapter "4.k. Mounting" it should be better expalined the /proc mounting versus binding. Don't say "If you are not installing Gentoo from a Gentoo LiveCD ..." but rather say when that applies. I guess when Knoppix CD was used to boot, what are the other cases? :) In chapter "5.c. Alternative: Using a Stage from the LiveCD", make sure the steps are doable. To copy the files in case of GRP install, one needs second CD-ROM drive! The text doesn't say in thi place that one actually needs CD2, although is clear to experienced install-user from the previous text. I suspect the Gentoo 1.4 x86 CD's don't match the expectation of this install document. :( - The "cp -R" command made for me subdirectory /usr/portage/distfiles/distfiles, which I expect was wrong. I used rather: cd distfiles && tar cvf - . | (cd /usr/portage/distfiles; tar xfp -) In chapter "6.a. Chrooting" contains unclear statement: "and people that install Gentoo from an installation medium that does not use DevFS". Does that apply to LiveCD1 user or not? "Code listing 17: Creating extra initscripts" in http://www.gentoo.org/doc/en/handbook/handbook.xml?part=1&chap=8 doesn't say about depscan.sh. In chapter 10, http://www.gentoo.org/doc/en/handbook/handbook.xml?part=1&chap=10 I failed to install system logger while off the network using stage3. emerge tried to connect to the network instead. Possibly, it would be a good place to talk about "PKGDIR=/mnt/cdrom/packages" chance to mount CD2 if another CD-ROM drive is available. Hope this helps and gives you some courage to rewamp the document a bit(I know it's not easy). ;) All the best and thanks for nice distro! Reproducible: Always Steps to Reproduce: 1. 2. 3.
We can't hyperlink the "LiveCD" words to any specific LiveCD because there are several dozens of them (every architecture - except MIPS) has at least a LiveCD (and most of them have several LiveCDs). x86-basic is a LiveCD, it just doesn't contain sourcecode nor prebuilt packages. The user is informed about this in the second chapter of the installation instructions, section "Gentoo basic LiveCDs". The description of the 2-CD LiveCD set also informs you that the first CD is bootable and contains sourcecode and precompiled packages and that the second one only contains prebuilt packages. The next Gentoo release will have all files online so that you can download it beforehand (although you are advised to download the 2-CD LiveCD set instead) or during the installation. In other words, we will support stage3+GRP with networking. I also disagree with the numbering of those sections. I believe that numbering them makes it less readable and less enjoyable to read. "Gentoo KDE/Gnome LiveCD" and "Knoppix" are indeed similar. This is done on purpose: both are separate methods. The reason that the three Gentoo LiveCD sections are placed as if they were children of the "Gentoo LiveCDs" is to make it obvious for users that the section on "Gentoo LiveCDs" is an introduction, while any of the three sections are more specific. Mentioning why the basic LiveCD isn't listed provides duplicate information in the handbook. You are informed at the beginning of the installation process that the basic LiveCD is not made for network-less installations. It would also be impossible to list the installation methods that can not use a networkless install because *all* other installation methods require it. Not only booting from other CDs, but also PXE booting, other distributions, tomsrtbt, UML, ... You should be able to install Gentoo 1.4 from the 2-CD LiveCD set without networking. If this is not the case, then this is a LiveCD error, not documentation error. The use of the "--usepkg" option is mentioned in the document (chapter 7, which is where the first usage of "emerge --usepkg" is listed). You need to copy over the sources and packages so Portage can use them. I don't see how this can be put more elaborate? We can't target just the CD because after a while, you need the second CD which contains packages that will probably depend on packages of the first CD (which will then be removed). I don't see why you still had CD-1 in your system when you needed CD-2. CD-2 is only used after rebooting the system (and we tell the user to remove CD-1 so he doesn't just restart the installation). You don't need to mount CD-2 before then . About bind-mounting vs normal mounting: the reason for this is quite technical. I can provide information on why, but 99.9% of the users don't want to know this yet. They just want to be able to install Gentoo by following the instructions. That is also how the instructions are structured: being too elaborate clutters the document. Other cases are installations from an existing distribution or from a PXE netboot. The "cp -a" and "cp -R" commands have always been a PITA for me. The problem is that, if you don't type exactly what we provide (i.e. no trailing "/" if there is no trailing "/", or a trailing "/" if we tell a trailing "/") things indeed do go wrong. I'll rewrite that little part to be more precise and less error prone. (*TODO*) You're also right about the DevFS stuff - it is indeed not that clear who should bind-mount and who shouldn't. I'll update that too. (*TODO*) We don't talk about depscan.sh because you don't need to know about depscan.sh. When you do "rc-update add net.eth1" rc-update will run depscan.sh for you. depscan.sh is not a tool that users should run. Perhaps they should know about its existance (which is done in the second part of the Handbook, in the chapter on "Init Scripts") but not on running it. Failing to install a network logger that is listed as installable is an error in the LiveCD: all tools listed in the handbook should be on the first CD (CD-1). This is also why we don't tell users how to install pptpclient or anything related: we don't provide it yet. Pfew, this is quite a bugreport :) I'll fix the things I marked as (*TODO*) but I believe the other things are invalid. Wkr, Sven Vermeulen
Created attachment 22950 [details, diff] Patch to hb-install-stage.xml Make GRP copying a tad less errorprone
Created attachment 22951 [details, diff] Patch to hb-install-finalise.xml
Okay, I hope these patches are (1) not erroneous and (2) better-looking :) If someone can verify that these commands are indeed working (It's GRP, I don't have great experiences with that)?
Created attachment 22952 [details, diff] Patch 2 to hb-install-stage.xml
Created attachment 22953 [details, diff] Patch 2 to hb-install-finalise.xml These patches don't use the "-a" or "-R" anymore as it isn't needed and only confuses people (tx to roger55).
I performed a quick GRP install, the commands are working.
I tested the commands too and the commands worked. And certainly these commands are less "confusing". :)
Thanks for the feedback. The changes are now committed.
