Handbook Talk:Main Page/Archive 2
This page is a historical record of unanswered questions from an older plugin. No new discussions here, please put them Handbook_Talk:Main_Page.
Warning about size of rootfs
The Handbook gives very minimal information about how large the root partition should be if one is not using the "rest of the disk" for it, as shown in the default partitioning scheme. It mentions that /usr/portage will be "around 650 MiB" (mine is currently 711MiB, not counting distfiles), but gives no indication whatsoever of how large the entire rootfs will end up being. (When I first tried installing Gentoo many years ago, I made the mistake of using a root partition too small to even unpack the stage3 tarball!)
I just checked, and the latest amd64 multilib stage3 tarball (a 183 MiB file, as downloaded) when unpacked rolls out to a generous 1046 MiB. Since I'm not actually installing a new Gentoo system at the moment, I have not checked how big everything is after completing the entire installation process. (Obviously this is highly dependent on the architecture and system configuration choices the user has made, but just having that info for one particular system would be helpful, I think, to give readers some idea of what to expect.)
If I were to complete the install based on that stage3, I estimate the final filesystem (upon completion of the Handbook) would run to at least 2.7 GiB (stuff mentioned above plus a gentoo-sources kernel tree).
Of course, after adding a desktop (which most users want) and various other software, a truly "complete" system can be several GiB larger than that. Personally, my current root filesystem — with OpenRC, X, MATE, Firefox, Thunderbird, 2 versions of GCC, 2 gentoo-sources kernels, and misc other sotware (of course), plus the distfiles from my last emerge --emptytree world (followed by an eclean-dist --deep) — stands at 8.8 GiB used (not counting /home).
Users should therefore be warned in the "Designing a partition scheme" section that just unpacking the stage3 tarball can take more than 1 GiB, the portage tree — er… Gentoo repository — (at /usr/portage) is over 700 MiB (and likely to grow), each kernel tree (under /usr/src/linux/) can take up to 1 GiB (or possibly more), the X graphical system takes… some amount of space, and a full-blown desktop environment can run to… however big.
We should also warn users at this point in the Handbook that certain large software packages (e.g., Thunderbird) can take 4 GiB or even 8 GiB of free space to build (the latter if pgo is used), which by default happens at /var/tmp/portage — and that /usr/portage/distfiles can get very large (2.5 GiB or more), even if you purge all old distfiles not associated with an installed package.
Some of this may be touched on in other parts of the Handbook (I can't remember), but it needs to be said at the point where users are partitioning their drives. --Dcljr (talk) 05:16, 12 July 2018
- This is a very good point. Given the handbook's wide target audience, there should definitely be a note hinting rough rootfs sizes. For instance, a desktop usually can be fit within 40GiB. Thus making the rootfs 100+GiB is really not needed. --Yuri69 (talk) 03:37, 13 July 2018
- It has been a while since Dcljr made his point, but it remains a point well made. We do not currently outline space requirements for different architectures in our installation, and having at least a baseline on typical installation sizes for the most popular profiles on the AMD64 architecture would be a fitting edition. I can do some testing to determine how much rootfs disk space a few different common profiles will be... for this testing I will presume the Gentoo ebuild repository and Portage's associated working directories (DISTDIR and PKGDIR) will be located inside the same rootfs partition even though the handbook does suggest the reader consider partitioning different mount points.
I'll cover 17.1 (basic install), 17.1/desktop/gnome (OpenRC Gnome), desktop/gnome/systemd (systemd Gnome), desktop/plasma (OpenRC Plasma), desktop/plasma/systemd (systemd Plasma). Perhaps some of the Gentoo devs have some scripts available to quickly spin out some tests on sizes, so I'll ask in #gentoo-dev (webchat) first.--Maffblaster (talk) 18:15, 20 April 2021 (UTC)
- After some additional consideration, defining minimum sizes for certain partitions is dependent on many factors (see the following diff link), and is therefore complex/non-trivial. There can be tiny embedded systems with rootfs read-only, squashed, and compressed, large fully-featured graphical desktop installations with lots of added programs, servers with terabytes of storage on different partitions on different disks, etc., etc. I've made the following recommendation for rootfs to hopefully provide more guidance and rationale during the installation process: Special:Diff/1281456/1281476
- Perhaps at some future state we'll add something like minimum recommended size for the rootfs, but for now I think using the remainder of the disk will have to suffice. --Maffblaster (talk) 11:45, 14 February 2024 (UTC)
Linking back to Handbook:Main Page
The index page for each Handbook (i.e., Handbook:Parts) should probably include a prominent link near the top to the list of Handbooks for all architectures at Handbook:Main Page#Viewing the Handbook, since users may land on Handbook pages from many different sources, like search results or links from other websites, and they may not always land in the correct Handbook for their architecture.
Note that users looking at Handbook:Parts directly will see a link back to the list of Handbooks in the red Warning box at the top, but those viewing the equivalent page for a specific architecture (e.g., Handbook:AMD64) do not see such a link anywhere in the text of the page. (Although there is one "hidden" inside the "Documentation" drop-down menu at the very top.)
Additionally, an "Other Architectures" link (or some such) could be added to Handbook:Parts/TOC, so every single Handbook subpage would provide a way of getting to the list of Handbooks for other architectures. --Dcljr (talk) 01:45, 12 July 2018
- Each of the pages under Handbook:Parts do now contain links back to Handbook:Main Page#Viewing the Handbook; that part of this suggestion has been implemented for a long time. I'm not sure how to cleanly implement a "other arches" link into the current TOC. Please re-open this discussion if you have a suggestion on the code to present it cleanly within the Parts/TOC. I really do not think there are many use cases for readers to switch another to different handbooks. They all essentially present the same information in chapters 2-4. Chapter 1 (Installation) should be followed end-to-end since it's more architecture specific. Maybe for editing purposes, but in my opinion one can use a bookmark in a browser for that purpose. Thank you. --Maffblaster (talk) 07:56, 14 February 2024 (UTC)
Clearly marking the "shorter pages" links
The "Viewing the Handbook" section of the "Handbook:Main Page" was refactored from a table format to a list format in March 2017 in response to my request. Now that I have returned one year later to check the Handbook for various things, I have found myself repeatedly confused as to how to select the "many shorter pages" version of the Handbook! (And if I can't figure it out, as someone who saw the change happen…)
Back when the information was presented as a table, there was an explicit indication as to which set of links led to the "many shorter pages" version of the Handbook and which led to the "longer pages" version. In my redesign I had suggested two bullet points per architecture, one noting parenthetically "(several smaller pages)" and the other "(one large page for each)". When the refactoring was actually done, only one "Full sections" bullet point per item was included. The "shorter pages" version was (and is, currently) linked only from the architecture handbook name itself (e.g., "AMD64 Handbook").
I suggest we include a second bullet point per item that somehow indicates it's for the "several smaller pages" / "many shorter pages" version of the Handbook. (Not sure what wording is best.) We probably should also explain the distinction a bit in the text above the list of handbooks, at the top of the "Viewing the Handbook" section. --Dcljr (talk) 18:35, 10 July 2018
- I have visually presented the 'single page per-chapter' view as a sub-bullet like you had in the your linked sandbox example. That said, since the default link to each handbook has always been shorter, bite sized 'many sections per-chapter', I do not see a strong need to discretely describe the default view in each list or provide a second link, but I did add some extra text to the lead-in paragraphs above which should help. As you mentioned, this link is already provided from the architecture handbook name itself (e.g., "AMD64 Handbook"), so no need to double-link in each Handbook's list. See Special:Diff/1281438/1281454. As always, thank you for the thoughts and suggestions! --Maffblaster (talk) 08:35, 14 February 2024 (UTC)