Handbook Talk:AMD64

From Gentoo Wiki
Jump to:navigation Jump to:search

Adjust second person pronoun to third person

Talk status
This discussion is done as of 2017-01-26.

I would have just fixed this myself, but new account. On this page there's a blurb tat we could adjust to be more gender neutral.

" A Portage introduction

   This chapter explains the "simple" steps a user definitely needs to know to maintain the software on his system. "

I think we should go ahead and change "his" to "their",or some similar phrasing. — The preceding unsigned comment was added by Steakwipe (talkcontribs) 26 January 2017‎

Consider it done. --Maffblaster (talk) 20:17, 26 January 2017 (UTC)

Improve install experience?

Talk status
This discussion is done as of 2023-03-10.

Hello, I was thinking perhaps in some places this guide could do with some updating and restructuring? As far as I can tell, each package's page on the wiki is designed to give more information (including things like common changes users may want to make, fixes to current issues, et cetera. These are useful, but are not really geared towards a new user) most notably, the handbook makes it sound as if you are intended to follow a separate guide that is in systemd. Obviously this is not the case, there is no guide within systemd's article that can carry an installation to the end, and all the relevant information that is available there is written in such a way that you would need base knowledge a new user to gentoo wouldn't have.

For this reason I feel that it may make more sense to make it so the guide branches off when the user needs to choose between systemd or openRC. After all, the openRC user doesn't need the instructions for systemd, and the systemd user does not need instructions for openRC.In gentoo's current state, choosing one or the other creates a very different set of requirements for the user's next steps in their installation. Outside of this, in its current state the guide essentially leaves the user with nothing more than a CLI only install? Surely the guide should help the user reach something a bit closer to what they expect (especially considering their experience may be limited).

I perfectly understand that it may take a while for proper guides on all desktop environments/common applications to exist, however I can't see the harm in starting with at least guiding the user on how to install the two environments the user had the option to pick when they chose a system profile. I have a KDE plasma/systemd install that runs quite happily, so I don't mind contributing largely to those two parts.

If this idea will only be accepted if multiple desktop environment guides are added "from the get-go" I do not mind doing my best to write guides for a few others as well. As I write the new sections/edit old ones, I'll make sure to test run the handbook as well, to ensure that the user will be left with a stable, running system.

I love gentoo, however despite the fact many sections are well written,there were plenty of points where the handbook as a whole left me on the verge of quitting and reinstalling Kubuntu (my previous distro at the time) and even now I dread the day I may break my installation and need to go through the handbook again; for this reason I would love to help ensure the handbook is an easy, smooth, pleasurable experience rather than the difficult, (negatively) documentation heavy, expert only experience that even some of my veteran Linux user friends would rather not touch, or dabble with. Not only will I have a far more reduced fear if my install were to break, but my friends may be more inclined to try out gentoo for themselves, and see why they may too want to use gentoo.

A few more issues that I neglected to mention were as follows: outdated commands, not enough use of common slang/acronyms (these will help ensure the user reads the whole guide, as they will have to backtrack to see what the abbreviation were short for if they skipped ahead. Armed with this knowledge they should be able to more comfortably converse with the Linux community as well), considering this could be the user's first time encountering some of them, there did not seem to be enough explanation of common package choices or why they would want them, at some points the guide instructs the user to emerge in such a way that would select a package, despite the fact some packages would actually pull it in anyway with the correct USE flags (hence it could make sense to explain what the -1 switch is for and where relevant include examples of how they could use it). I hope this is suitably received by the relevant people and look forward to what may be said in future, to those who read this now and in the future thank you for your time, I hope you are not left feeling like reading this robbed you of it. --Lyciathelycanroc (talk) 13:53, 5 June 2018 (UTC)

There are already multiple versions of the Handbook for different architectures. Splitting off systemd separately would multiply these by two. Given that wiki admins must approve (and implement) all changes to the Handbook, I don't see that ever happening. As for stopping at a CLI system, going any farther from that point in the Handbook itself would be introducing material better handled elsewhere — namely the existing guides under Category:Software and Category:Desktop (for example). I agree (with your implication) that the installation part of the Handbook ends rather abruptly, but it does point to the "Working with Gentoo" part (e.g., Handbook:AMD64/Working/Portage) where users are intended to learn how to use emerge, et al., to continue building their system — and to the "Documentation topics" list on the Main Page, whence users can find documentation about specific software, including desktop environments. That all being said, you are free to look through our documentation outside of the "Handbook:" namespace (which, like I said, only admins can edit), and add anything you feel is lacking. I agree that the Handbook(s) could be improved in many places, but unfortunately I've found that getting changes accepted and properly implemented there can be a rather frustrating experience; when it does work, it's usually when very specific suggestions have been offered (as in: here's some text to add to this place, or to replace this particular text). --dcljr (talk) 21:54, 11 July 2018 (UTC)
In my opinion, the manual pages about Portage are more useful than the Handbook. I am convinced that Gentoo does not know their user profiles. In short, I think that Gentoo makes organizational mistakes especially in relation to the community. I would not be surprised that these potential errors have implications on the quality assurance: outdated documentation, unintelligible features, decrease of contributors.... By the way, I share your point of view and I disagree with Dcljr or as some people would say "Gentoo lets you choose but Gentoo is not for everyone" (what?). --Feng (talk) 13:19, 15 December 2018 (UTC)

I read the preceding comments with some interest. I have just begun my third attempt at installing Gentoo on my Dell XPS8930 box. The second try went fairly well, but I noticed that Gentoo was gobbling up disk space at an alarming rate, so I built a bigger root partition and started over. (I realize I can probably remove some source code from the database, but I'm leaving some of that sort of housekeeping for later.) I already have seven different versions of Linux installed on my hard disk (openSUSE Tumbleweed, Neon, Ubuntu (18.04), Fedora 32, Linux Mint, MX Linux, and Debian 10.4 (Buster). So I'm not exactly a novice. I've even got some experience with the "make" command, because I have an old HP printer, and the "hplip" package in many distros doesn't work well enough. So I've installed that package from SourceForge more than once. And I'm involved with the KDE-PIM team (documentation, for now), so I've poked around Github quite a bit.

The main problems I encountered in dealing with the "Handbook" were two-fold. First, some of the discussions that involved several possible paths were very hard to understand. The Networking page springs to mind. Second, some of the error messages that came back from "Portage" were sort of obscure. A link to the error messages, and what to do about them, would have been very helpful. As it was, I had to boot up a different version of Linux and visit the Gentoo forums a few times before I was able to actually boot my Gentoo system from the hard disk for the first time.

I aim to work my way through the handbook pages (the "Installing Gentoo" section, at least) and make suggestions for improvement. Let me know if it's helpful, or not. Thanks! --Davidbryant (talk) 15:46, 29 June 2020 (UTC)

This discussion is large, but is long over due for a reply of the Gentoo Handbook project. Maintaining the Handbook on the wiki is sub-optimal due to the complexity of creating a comprehensive guide document that covers the essential steps necessary to get hardware running a source-based operating system. Certainly improvements can be made - no doubt here - and we will continue to make improvements as times goes on. We may even move away from the Handbook to a better documentation generator... but we'll lose certain aspects (like the approachability of a wiki).
At least one of the above issues would be solved by Gentoo distributing bootable media that includes a web browser (Chromium/Firefox) and better automagic network configuration (our media already runs a DHCP client). The issue with including more software is that it increases release engineer build times for live media. It currently takes my latest generation system 3h36m to build Chromium and about 34m to build Firefox (not including dependencies)... More to come... --Maffblaster (talk) 20:35, 15 February 2022 (UTC)
I return here after having made several major improvements to the Handbook since my previous comment in 2022. One such improvement is suggesting the distribution kernels as the go-forward default path for Kernel management in the Handbooks, while enhancing both the Genkernel and manual kernel management parts for modern symbol / driver support. Improvements have been made to the network sections as well - although I do not believe those were ever really that bad (with the exception of wireless networks which still needs some tender love and care). The main issue with network is that NetworkManager is not included in the live media, which is the tool most other distributions use to configure networks. The handbook suggests using OpenRC's netifrc scripts for OpenRC0-based profiles by default. It always has done this. When you find other things to constructively suggest (which will occur, because the work is never finished), please continue to open discussions on the relevant Handbook pages. I will mark this discussion as complete since there has not been movement outside my own comments for several years. Kind regards, --Maffblaster (talk) 22:52, 10 March 2023 (UTC)

Suggested Handbook Changes

Talk status
This discussion is done as of 17 July, 2020.

The main handbook page ("Handbook:Main Page") says "Suggestions, comments, or ideas on how to make the Handbook better can be reported ... via the Discussion page of the respective article[sic]. Documentation is made for the community, so community feedback is well appreciated."

The following suggestions for improvement are offered in a spirit of cooperation. Quoted material is from the main "Handbook:AMD64" page. I take it as axiomatic that wiki articles should use good grammar and idiomatic English phraseology. I'm not going to pick nits about split infinitives or dangling participles. But I will insist on basic rules like subject / verb agreement, using the objective case where necessary, etc.


"To be able to install Gentoo, the necessary partitions need to be created. This chapter describes how to partition a disk for future usage."

Very clumsy. I suggest "Before Gentoo can be installed, the necessary partitions must be created. This chapter describes how to partition a disk."


"Installing the Gentoo installation files

"Gentoo installs work through a stage3 archive. In this chapter we describe how to extract the stage3 archive and configure Portage."

Clumsy. You break your own rules by speaking in the first person. And the word "installs" is a verb (used here as a noun -- unless Gentoo is really installing work -- only God knows what that means). This would be better:

Downloading the Gentoo installation files

The basic Gentoo system is downloaded as a stage3 archive. This chapter explains how to download and extract the archive, and also how to configure Portage, Gentoo's package management program.

"After installing and configuring a stage3, ..."

A stage3 what? (This is not idiomatic English.) It would be better to say "After installing and configuring stage3, ..." or else "After installing and configuring a stage3 tarball, ..."


"Some important configuration files need to be edited. In this chapter an overview of these files is provided and an explanation on how to proceed."

Clumsy and ungrammatical. The passive voice doesn't work as well as the active voice in almost every case. I suggest "Some important configuration files must be created. This chapter provides an overview of these files and explains how to tailor the configuration."


"... amongst other features, ..."

"Amongst" is pretentious. Say "among".


"With Gentoo environment variables can be easily managed."

What on Earth is a "Gentoo environment variable"? Which of those three nouns is the subject of this sentence? Either insert a comma (With Gentoo, environment ...) or better still, invert the word order: Environment variables can be easily managed with Gentoo. (Yes, I understand that the attributive noun is making great inroads in the contemporary vernacular. But when it's this ugly, it ought to be fixed.)


"Portage is completely configurable through various variables that can be set in the configuration file or as environment variable."

This is not idiomatic English. Either insert the indefinite article (... as [an] environment variable) or use the plural (... as environment variables). The sentence is also horribly repetitive. Better would be

Portage is completely configurable, with several options that can be set in a configuration file, or as environment variables.


"This chapter gives some tips and tricks on how to use a custom package repository, how to synchronize only the categories necessary, inject packages, and more."

Ellipsis doesn't work here, and adjectives/participles come before the nouns they modify, in English. I suggest

This chapter gives some tips and tricks on how to use a custom package repository, how to synchronize only the required categories, how to inject packages, and more.


"As times goes by, Portage evolves and matures further and further. Additional features are continuously being put in - many of these are only of use by more advanced users. This chapter will go into more detail of these specific features."

Horribly clumsy and replete with grammatical errors. Did a foreigner translate some Russian or French original to come up with this sentence? This would be better:

As time passes, Portage evolves and matures. New features are continually being added. Many of these are useful only to the more experienced user. This chapter explains some of Portage's newer features.


Well, that's it for today. I'll tackle another chapter in the "Handbook" tomorrow. --Davidbryant (talk) 20:03, 16 July 2020 (UTC)

I took most of these suggestions. Thanks for the help. --Grknight (talk) 16:56, 17 July 2020 (UTC)

Marking the boot partition as bootable is missing

Talk status
This discussion is done as of 2024-01-03.

With BIOS and Master boot record systems, it is necessary to mark the boot partition as bootable, else the BIOS will not load the bootloader. In fdisk the boot flag can be toggled with the "a" command.

The handbooks for x86 and AMD64 do not mention this. Please add such a section. --Laci (talk) 18:56, 16 November 2023 (UTC)

**Gasp!!** You're right! I'm fairly certain this step was previously included but regressed at this point during a revision. Fixed: Special:Diff/1266963/1272220 Thanks! --Maffblaster (talk) 08:05, 3 January 2024 (UTC)

Minor textual addition

Talk status
This discussion is done as of 2024-02-13.

Just a minor textual addition to the Handbook:AMD64 wiki article.

Handbook:AMD64#Installing_Gentoo (missing something like need to be): under the topic Preparing the disks, I believe it should read something like "Before Gentoo can be installed, a root file system layout and - optionally - other partitions need to be created."

Thank you for the consideration. Gabe (talk) 07:17, 14 February 2024 (UTC)

Done. See Special:Diff/1272281/1281448. Thanks. --Maffblaster (talk) 07:38, 14 February 2024 (UTC)