Handbook Talk:Main Page/Archive 1

This page is an archive. Do not edit the contents of this page. Please direct any additional comments to the current talk page.

Merging tables
I find having two separate tables for describing and then selecting the appropriate architecture to be somewhat awkward. Could we perhaps merge these tables, like this?

Note that I have modified the column headers to try to clarify the differences between the two styles of presentation of the handbook, and I've used shorter text in the last 4 columns, since they all say the same thing, anyway. Since the ARM architecture is not (yet?) listed in the 2nd table, I have not included it in the above merged version. - dcljr (talk) 23:34, 25 January 2015 (UTC)
 * Since normal users apparently can't edit Handbook: pages, can someone who can please make this change? Just today I went to look up a page and clicked on the wrong link by mistake (I wanted one of the short pages but accidentally chose a long page instead). BTW, I've gone through what-links-here and didn't find any links to sections within this page, so the Architectures and Viewing the handbook sections can safely be merged under any section heading without breaking any internal wikilinks.) - dcljr (talk) 23:39, 3 March 2015 (UTC)


 * Sure thing, fixed. --SwifT (talk) 11:37, 4 March 2015 (UTC)
 * Thanks! Couple things, though... We probably don't need two links to the same "WhatLinksHere" results in the "I disagree with ..." section (link text "track open issues" and "keep track"). And shouldn't we encourage all "external" style links to be protocol-relative (without the leading "http:" or "https:")? Although all pages here are apparently served as HTTPS anyway, this would keep the wikicode "cleaner" and would work right if it was ever decided to also allow HTTP browsing. - dcljr (talk) 20:53, 4 March 2015 (UTC)

Intel Core2
"Intel Core2" should be added to the list of example CPUs for AMD64, just before the "Intel Core i3, i5, i7". Many people viewing the table may wrongly assume that, because Core2 is not present, but Core is (under x86), that their Core2 CPU is only x86, which is not the case. - aaronmdjones (talk) 20:22, 21 February 2015 (UTC)


 * Added. --SwifT (talk) 11:37, 4 March 2015 (UTC)

Improving tables to display better as text

 * Apologies in advance for the super-large comment.

The way we're doing the "large" tables here at Handbook:Main Page and in the handbook itself (all versions) at Handbook:AMD64/Full/Installation, in the "Hardware options" table, makes them difficult to read in a text-only browser (e.g., on a standard console, as suggested in the handbook).

A small but significant improvement can be achieved by simply top-aligning the rows of the tables.

Here's what the beginning of the "Viewing the handbook" table looks like in on an 80-column text console (bold text indicates a link) with the current alignment and then with "top" alignment. Try to find the beginning and ending of the description for "amd64". Current alignment One page per chapter (many     One page per part (longer pages)   shorter pages) Handbook for Description of    Installing   Working Working Network architecture architecture      Gentoo Linux with    with    configuration Gentoo Portage The Alpha architecture is a                64-bit architecture developed by                Digital Equipment Corporation (DEC). It is  alpha         still in use by   Installation Working Portage Networking some mid-range and high-end servers, but the architecture is                slowly being faded out. (ES40, AlphaPC,                UP1000, Noname) A 64-bit architecture that is compatible with the x86 architecture (and                thus also known                 as x86_64). It                was first used by                 AMD (under the                 AMD64 name) and Intel (under the                EM64T name) and is now the most prominent architecture for amd64        medium and        Installation Working Portage Networking high-end desktop PCs. It is also commonly found in                the server segment. (AMD Athlon 64,                AMD Opteron, AMD                 Sempron                 processors, AMD                 Phenom, Intel                 Pentium 4, Intel                 Core2, Intel Core                 i3, i5, i7, some                 Intel Atom                 variants) This 32-bit architecture is a                very popular architecture for embedded and small systems. Sub-architectures range from ARMv1 to ARMv7 (Cortex) arm          and are often found in smart phones, tablets, hand-held consoles, end-user GPS navigation systems, etc.                (StrongARM,                 Cortex-M)

Top alignment One page per chapter (many     One page per part (longer pages)   shorter pages) Handbook for Description of    Installing   Working Working Network architecture architecture      Gentoo Linux with    with    configuration Gentoo Portage alpha        The Alpha         Installation Working Portage Networking architecture is a                64-bit architecture developed by                Digital Equipment Corporation (DEC). It is                still in use by                 some mid-range and high-end servers, but the architecture is                slowly being faded out. (ES40, AlphaPC,                UP1000, Noname) amd64        A 64-bit          Installation Working Portage Networking architecture that is compatible with the x86 architecture (and                thus also known                 as x86_64). It                was first used by                 AMD (under the                 AMD64 name) and Intel (under the                EM64T name) and is now the most prominent architecture for medium and high-end desktop PCs. It is also commonly found in                the server segment. (AMD Athlon 64,                AMD Opteron, AMD                 Sempron                 processors, AMD                 Phenom, Intel                 Pentium 4, Intel                 Core2, Intel Core                 i3, i5, i7, some                 Intel Atom                 variants) arm          This 32-bit architecture is a                very popular architecture for embedded and small systems. Sub-architectures range from ARMv1 to ARMv7 (Cortex) and are often found in smart phones, tablets, hand-held consoles, end-user GPS navigation systems, etc.                (StrongARM,                 Cortex-M)

See how much easier it is with "top" alignment?

But to really improve it, the table needs to be completely refactored. Here's my first attempt:

Which looks like this on the console (this was the primary motivation for the format I chose):

Handbooks for supported architectures Architecture Description alpha       The Alpha architecture is a 64-bit architecture developed by                Digital Equipment Corporation (DEC). It is still in use by               some mid-range and high-end servers, but the architecture is                slowly being faded out. (ES40, AlphaPC, UP1000, Noname) * View the Alpha Handbook (several smaller pages) * Or choose a specific part of the handbook: (one large                   page for each) Installation - Working - Portage - Networking amd64       A 64-bit architecture that...

Another possibility is to use a "definition list" to achieve the same effect: ("view source" of this comment for the wiki markup)

Handbooks for supported architectures (ES40, AlphaPC, UP1000, Noname)
 * Handbook:Alpha
 * The Alpha architecture is a 64-bit architecture developed by Digital Equipment Corporation (DEC). It is still in use by some mid-range and high-end servers, but the architecture is slowly being faded out.
 * View the Alpha Handbook (several smaller pages)
 * Or choose a specific part of the handbook: (one large page for each)
 * Installation – Working – Portage – Networking


 * Handbook:AMD64
 * A 64-bit architecture that…

On the console:

Handbooks for supported architectures alpha The Alpha architecture is a 64-bit architecture developed by          Digital Equipment Corporation (DEC). It is still in use by some mid-range and high-end servers, but the architecture is slowly being faded out. (ES40, AlphaPC, UP1000, Noname) * View the Alpha Handbook (several smaller pages) * Or choose a specific part of the handbook: (one large page               for each) Installation - Working - Portage - Networking amd64 A 64-bit architecture that...

Now, as for the "Hardware options" table, here's what it looks like on the console, current version and top-aligned: Current alignment

Hardware options This loads support for ACPI and also causes the acpid daemon acpi=on    to be started by the CD on boot. This is only needed if the system requires ACPI to function properly. This is not required for Hyperthreading support. Completely disables ACPI. This is useful on some older systems acpi=off   and is also a requirement for using APM. This will disable any Hyperthreading support of your processor. This sets up serial console access for the CD. The first console=X  option is the device, usually ttyS0 on x86, followed by any connection options, which are comma separated. The default options are 9600,8,n,1.

Top alignment

Hardware options acpi=on    This loads support for ACPI and also causes the acpid daemon to be started by the CD on boot. This is only needed if the system requires ACPI to function properly. This is not required for Hyperthreading support. acpi=off   Completely disables ACPI. This is useful on some older systems and is also a requirement for using APM. This will disable any Hyperthreading support of your processor. console=X  This sets up serial console access for the CD. The first option is the device, usually ttyS0 on x86, followed by any connection options, which are comma separated. The default options are 9600,8,n,1.

This really should be a definition list, since that is literally what it is:


 * acpi=on
 * This loads support for ACPI and also causes the acpid daemon to be started by the CD on boot. This is only needed if the system requires ACPI to function properly. This is not required for Hyperthreading support.


 * acpi=off
 * Completely disables ACPI. This is useful on some older systems and is also a requirement for using APM. This will disable any Hyperthreading support of your processor.


 * console=X
 * This sets up serial console access for the CD. The first option is the device, usually ttyS0 on x86, followed by any connection options, which are comma separated. The default options are 9600,8,n,1.

On the console:

Hardware options acpi=on This loads support for ACPI and also causes the acpid daemon to be     started by the CD on boot. This is only needed if the system requires ACPI to function properly. This is not required for Hyperthreading support. acpi=off Completely disables ACPI. This is useful on some older systems and is     also a requirement for using APM. This will disable any Hyperthreading support of your processor. console=X This sets up serial console access for the CD. The first option is the device, usually ttyS0 on x86, followed by any connection options, which are comma separated. The default options are 9600,8,n,1.

Opinions? - dcljr (talk) 08:15, 10 August 2016 (UTC)


 * I think your definition list change looks very nice and would make our tables look a lot better. Seems trivial enough for a better looking page... --Maffblaster (talk) 16:47, 10 August 2016 (UTC)


 * BTW, for consistency, the "short overview of the available kernels" table immediately above the "Hardware options" one should also be changed to a definition list at the same time. The other 3 main divisions of the Handbook ("Working with Gentoo", etc.) also contain tables that are really just definition lists, but I'll leave it to someone else to consider whether and how those should be refactored. - dcljr (talk) 22:23, 10 August 2016 (UTC)

Quick reminder that none of this has been implemented yet (AFAICT). Can someone actually make the necessary changes? - dcljr (talk) 03:26, 5 January 2017 (UTC)


 * Hi dcljr, thanks for the persistence and your due diligence in all that wiki text formatting for the examples. I was waiting for someone else to weigh in and had forgotten about this open discussion. Since no one else has weighted in by now I will make the changes to the tables and the Hardware options section. Thanks for helping make the wiki a better place AND providing the code/text to do so. That is truly rare. --Maffblaster (talk) 05:38, 5 January 2017 (UTC)


 * I 'valigned' the text for the arches on the front page for now and implemented the definition list. Time permitting I may refactor the tables later. Does this work for you? --Maffblaster (talk) 06:19, 5 January 2017 (UTC)

Maffblaster: In my userspace you will find complete versions of the "Viewing the Handbooks" table as a refactored table and as a definition list. Either of these should be suitable for copying-and-pasting over what we're using now (they're based on the current wording but with some additional copyediting and wikification). I recommend the definition-list version because it looks better in both and  on the console while still looking acceptable in a graphical browser. - dcljr (talk) 03:39, 19 February 2017 (UTC)


 * Thanks. Finally implemented the list format. I may go through in the future an change the formatting a bit, but it should be helpful for people who are using in text-mode. Closing this discussion. Kind regards, --Maffblaster (talk) 02:40, 5 March 2017 (UTC)


 * Hmm… The way you've implemented this does not make clear that the "Installation – Working – Portage – Networking" links are not simply a way to "jump to" different parts of the Handbook, they are completely different ways of getting the Handbook information (i.e., one huge page per section, as opposed to several small pages). - dcljr (talk) 09:08, 7 March 2017 (UTC)


 * Revised. Re-closing. --Maffblaster (talk) 18:23, 8 March 2017 (UTC)

Directing users away from Handbook:Parts
Please see my comment at Handbook Talk:Parts. - dcljr (talk) 08:47, 15 August 2016 (UTC)


 * Will do. Please add talk InfoBoxes to your open discussions so that we can better track them.


 * Done. It now points directly to the Handbook table. --Maffblaster (talk) 06:37, 5 January 2017 (UTC)

Simplify open-discussion template
In the "I disagree with ..." section, I think the following two changes will improve understanding of, and participation in, the drive to mark open talk page discussions:

First, in the "T:26" translation block, please replace: we ask you to add the following marker to each discussion you open: by: we ask you to add the Talk template to each discussion you open, as seen in this example:

Secondly, in the "T:27" translation block, please replace: {{CodeBox|title=Example open discussion|1=&lt;pre> {{InfoBox stack by: {{CodeBox|title=Example open discussion|1=&lt;pre> {{Talk|open|date=Jul 2 2015}}
 * {{InfoBox talk open|date=Jul 2 2015}}

Thanks. - dcljr (talk) 08:08, 14 January 2017 (UTC)


 * Looks good. I implemented it. Should save some newcomers headaches having a simplified template. --Maffblaster (talk) 23:42, 14 January 2017 (UTC)


 * Just noticed that the same link (to Special:WhatLinksHere for Template:InfoBox_talk_open) is provided on the words "track open issues" before the Code box and "keep track of" after it. Only one of these is necessary. - dcljr (talk) 00:41, 15 January 2017 (UTC)


 * Fixed. --Maffblaster (talk) 00:44, 15 January 2017 (UTC)

Navigating to Handbook Main Page and Full versions
We should probably provide prominent links at the top of pages like Handbook:AMD64 back to Handbook:Main Page. The simplest way of doing this would be to link the words "Gentoo Handbook" (in the lead section) at Handbook:Parts, but I would also suggest we add a "Gentoo Handbook" entry (that links to the Handbook:Main Page) at the top of the Handbook:Parts/TOC navbox.

I'd also like to see links to the four "Full" pages for each architecture (Handbook:AMD64/Full/Installation, etc.) on the handbook index pages (Handbook:AMD64, etc.) — which presumably only requires editing Handbook:Parts — since currently the only way to get to these "full" versions is via Handbook:Main Page. - dcljr (talk) 06:07, 23 January 2017 (UTC)


 * I added a link back to the main page. Better now? --Maffblaster (talk) 00:19, 24 February 2017 (UTC)


 * The link text is difficult to read because of the dark purple background color. You'd have to put the "color: white" setting inside the link, like this:
 * ! style="text-align: center; background-color:#463c65;" | Handbook (Main)
 * But I'd really rather see links to the individual "Full" pages, as shown at Handbook Talk:Parts/TOC (not putting it here because of the large amount of code involved). - dcljr (talk) 05:29, 24 February 2017 (UTC)


 * Changes accepted. I think it looks good and navigation is more featured. Closing discussion. --Maffblaster (talk) 17:55, 24 February 2017 (UTC)

Continual Handbook improvement
Um… Continual Handbook improvement is not a "question". [wink] How 'bout something like, "I want to change this"? (Not a question either, but you know…) - dcljr (talk) 01:49, 27 January 2017 (UTC)


 * It's a question now. Closing. --Maffblaster (talk) 23:35, 23 February 2017 (UTC)

from ooold handbook
search for "please read the first section of the Gentoo Handbook's second chapter (Choosing the Right Installation Medium)". "section" and "chapter" this is old style naming and should be deleted --Cronolio (talk) 17:10, 22 February 2017 (UTC)


 * I have reworded the entire section (what was being said didn't make much sense to me), so it should read a lot better now. Hit me up on IRC if you still don't like it. Closing discussion. --Maffblaster (talk) 03:02, 5 March 2017 (UTC)

Link target missing
The link target "handbook-table", which is linked to from pages like Handbook:Parts, disappeared in this edit. It should probably be restored (even though we're not using a table anymore) for the benefit of incoming links and possible user bookmarks. - dcljr (talk) 03:02, 9 March 2017 (UTC)


 * I have changed the link so that it connects to the section header. I added the "handbook-table" ID relatively recently only for the use on the Handbook:Parts/Warning sub-article. No one else linked to it. Now that the Handbooks are listed in list format (and I cleaned up some of the duplicate text) people can just link to the section header. --Maffblaster (talk) 23:47, 9 March 2017 (UTC)

Example comment should not show a completed signature
Under Handbook:Main Page, the example comment includes a user signature with timestamp, but of course this should not actually be typed out by the user leaving the comment. Instead, the usual "four tilde" wikicode should be used. Then below the code box it suggests signing the discussion by using the "Signature and timestamp button", but doing that would only insert the aforementioned wikicode and not a completed signature (so this could be a little confusing to newbies).

I suggest, therefore, that the last line of the code box be changed from this:

To this:

Then the next paragraph should be changed to something like:

Or words to that effect. - dcljr (talk) 07:20, 28 March 2017 (UTC)


 * Implemented! --Maffblaster (talk) 17:31, 28 March 2017 (UTC)

Fix sentence
Small fix: "The list below gives a high-level overview of the architectures supported by various Gentoo Linux projects." Fturco (talk) 09:45, 17 April 2017 (UTC)


 * Fixed! Thank you! --Maffblaster (talk) 16:46, 17 April 2017 (UTC)

Pegasos
"They are most commonly found in embedded systems. Variants include: Apple OldWorld, Apple NewWorld, generi Pegasos, Efika, older IBM iSeries and pSeries."

I'm not sure: should it be fixed with generic Pegasos or with Genesi Pegasos? I'm not familiar with the PPC architecture.

Fturco (talk) 09:53, 17 April 2017 (UTC)


 * Looks like "Genesi Pegasos" is correct. https://genesi.company/products/pegasos --Maffblaster (talk) 16:48, 17 April 2017 (UTC)


 * Can you than change this form 'generi Pegasos' to 'Genesi Pegasos'? --Phamming (talk) 14:07, 20 April 2019 (UTC)

Update AMD64 processor list
The latest AMD processor in the current example list of AMD64 processors is AMD Phenom. The Phenom brand was discontinued in 2011. It would be good to update the list at least with AMD FX and AMD Ryzen. --Yuri69 (talk) 22:35, 22 April 2017 (UTC)


 * I have added the newer CPU models to the list. Thanks! --Maffblaster (talk) 13:05, 24 April 2017 (UTC)

Add AArch64 mention
It seems the ARM64 section lacks any mention of AArch64. Many distros use this architecture name extensively, so this info might be useful for new users. --Yuri69 (talk) 22:45, 22 April 2017 (UTC)


 * I have added a reference for AArch64 and have updated the ARM section to reflect the present. Unfortunately the ARM project has still not provided an ARM64 Handbook. You should get on them to do so! Thanks! --Maffblaster (talk) 13:05, 24 April 2017 (UTC)