Bug 113064

Summary:	Handbook for amd64 contains x86-only instructions for installing a stage3 tarball
Product:	[OLD] Docs-user	Reporter:	Wiktor Wandachowicz <wiktorw>
Component:	Handbook	Assignee:	Docs Team <docs-team>
Status:	RESOLVED WORKSFORME
Severity:	minor
Priority:	High
Version:	unspecified
Hardware:	AMD64
OS:	Linux
URL:	http://www.gentoo.org/doc/en/handbook/handbook-amd64.xml?part=1&chap=5#doc_chap2
Whiteboard:
Package list:		Runtime testing required:	---

Description Wiktor Wandachowicz 2005-11-20 02:01:29 UTC

In "Code Listing 6: Example checking integrity of a stage tarball" there is
an md5sum invocation with "stage3-x86-2005.1.tar.bz2.md5" file as an argument.
AMD64 users would never use such a file, so this is misleading.

Later, in "Code Listing 11: Extracting the stage tarball" the instructions
contain the "stage3-<subarch>-2005.1.tar.bz2" meta-name. This is correct and
IMHO the same should be applied to the "Code Listing 6". Preferably with the
explanation what this "<arch>" part means.

Alternatively a concise clarification is needed in this chapter.

BTW. The "stage3-x86-2005.1.tar.bz2.md5" file name is not too good on its own.
How many users would need/use a generic "stage3-x86" tarball, instead of
"stage3-athlon-xp" or "stage3-pentium4" (and similar) tarballs?

The whole issue is mostly cosmetic, but misleading for the beginners who
attempt to install amd64 flavor of Gentoo. If one attempts to follow the
handbook in that part to the letter, this will lead to a confusion.


Reproducible: Always
Steps to Reproduce:
1. Navigate to the URL that demonstrates the problem

Actual Results:  
# md5sum -c stage3-x86-2005.1.tar.bz2.md5
stage3-x86-2005.1.tar.bz2: OK


Expected Results:  
# md5sum -c stage3-<arch>-2005.1.tar.bz2.md5
stage3-<arch>-2005.1.tar.bz2: OK

Be sure to substitute the tarball filename with your stage.

Comment 1 Wiktor Wandachowicz 2005-11-20 02:09:43 UTC

Alternatively all <arch> references could be changed to "amd64", because no
other name would be ever used in this situation. This applies to the whole 5th
chapter!

(iif the amd64 handbook source is separated from, say, x86 handbook source,
then the above is completely valid my contr-proposal)

Comment 2 SpanKY gentoo-dev

2005-11-20 02:31:02 UTC

that page is shared among all architectures and in the paragraphs they say that
x86 is used as an example but that you should replace with your system info

Comment 3 Wiktor Wandachowicz 2005-11-20 08:02:06 UTC

Well, you're right.

The text before the example states indeed:
"For instance, to check the validity of the x86 stage tarball:"

Somehow I missed that on first reading. :oops: