In section 15 of the x86 installation guide, the fstab file contains "/dev/BOOT", "/dev/ROOT", and "/dev/SWAP". This is inconsistent with the style of the rest of the document. The rest of the document assumes that the user used the default partition settings. As such, to be consistent, the fstab example should list "/dev/hda1", "/dev/hda3", and "/dev/hda2" respectively. I encountered an error where I just blindly typed in "/dev/BOOT" expecting it to work, and I saw a couple people struggling with the same thing in the forums. The rest of the install guide lets the user "just copy the line and Gentoo will work." Then the user hits the fstab section and does not realize they need to change mentalities and stop copying. Reproducible: Always Steps to Reproduce: 1. 2. 3.
Created attachment 16977 [details, diff] created patch to add notification added notification about /dev/BOOT replacement
Um, >I encountered an error where I just blindly typed in "/dev/BOOT" expecting >it to work, Replacing uppercase BOOT, ROOT, etc. with hda1, hda2... will make more people do just what you described, which is *absolutely bad*. People *should think* about what they are doing, especially about this step. I believe this example was done the way it is to get user's attention, sure things are not always completely apparent :). As such I think it would be bad to use "something looking right" in this case (in other examples things just won't work for the most part, while here user won't be able to boot). Byt the added note, just as is done in the patch should be fine. Oh, and it may be made to be <warn> instead of <note> - little bit more eye catching :). George
Created attachment 16987 [details, diff] replaced note with warn replaced note with warn for eye catching purpose.. please review the patch
In my initial description, I think I sidestepped my main issue with the document. My main concern is that I thought of the sections in purple as code blocks. That is, they are examples of what could actually be entered at the command line or what output you might actually see. There are two sections in the install document where this principle is violated. One is in the fstab code block. /dev/BOOT is not an example, it is a variable that should be replaced with the correct partition. The second violating section is in the grub section where the -KV must be replaced with the correct kernel version. Other than aesthetics, it's probably fine to use exceptional code examples that require substitutions. However, please make these instances clear to prevent confusion. Currently, the two explanations that substitution is required blend into the surrounding text in the preceding examples. Benny's idea to use "warn" blocks to flag these substitution code examples seems prudent.
Created attachment 16990 [details, diff] Added Warning tags for Grub, Lilo KV subsitutition Please review patch
Created attachment 16996 [details, diff] The warning for BOOT,ROOT doubles removed the added warning, replaced <p> to <warn> to: 1: eye catching purpose 2: remove repetition
The last patch looks good.
Patch include replaced <p> to <warn> in /etc/fstab, grub, lilo thank you for your suggestion Daniel :)
