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?
| One page per chapter (many shorter pages) | One page per part (longer pages) | ||||
|---|---|---|---|---|---|
| Handbook for architecture | Description of architecture | Installing Gentoo Linux | Working with Gentoo | Working with Portage | Network configuration |
| 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) |
Installation | Working | Portage | Networking |
| AMD64 | 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 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 Core i3, i5, i7) |
Installation | Working | Portage | Networking |
| HPPA | Referred to as HPPA, the PA-RISC architecture is an instruction set developed by Hewlett-Packard and was used in their mid- and high-end server series until about 2008 (after which HP started using Intel Itanium). (HP 9000, PA-8600) |
Installation | Working | Portage | Networking |
| IA64 | A 64-bit architecture designed by Intel and used in their Intel Itanium processor series. This architecture is not compatible with x86 or x86_64 (aka amd64) and is mostly found in medium and high-end server series. (Intel Itanium) |
Installation | Working | Portage | Networking |
| MIPS | Developed by MIPS Technologies, the MIPS architecture entails multiple subfamilies (called revisions) such as MIPS I, MIPS III, MIPS32, MIPS64 and more. MIPS is most common in embedded systems. (MIPS32 1074K, R16000) |
Installation | Working | Portage | Networking |
| PPC | A 32-bit architecture used by many Apple, IBM and Motorola processors. They are most commonly found in embedded systems. (Apple OldWorld, Apple NewWorld, generi Pegasos, Efika, older IBM iSeries and pSeries) |
Installation | Working | Portage | Networking |
| PPC64 | The 64-bit variant of the PPC architecture, popular in both embedded as well as high-end performance servers. (IBM RS/6000s, IBM pSeries, IBM iSeries) |
Installation | Working | Portage | Networking |
| SPARC | The SPARC architecture is best known by its most common producers, Sun (now Oracle) and Fujitsu. It is used in server systems although a few workstations exist as well. In Gentoo, only SPARC64 compatible CPUs are supported. (E3000, Blade 1000, Ultra 2) |
Installation | Working | Portage | Networking |
| X86 | A 32-bit architecture used by CPUs that are often said to be "Intel compatible". It was, until recently, the most popular architecture for desktop PCs. Gentoo offers builds for i486 (supports all families) and i686 (supports Pentium and higher or compatible). (i486, i686, Intel Core, AMD Athlon, Intel Atom) |
Installation | Working | Portage | Networking |
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)
- Sure thing, fixed. --SwifT (talk) 11:37, 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)
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#Viewing the handbook and in the handbook itself (all versions) at Handbook:AMD64/Full/Installation#Booting the CD, in the "Hardware options" table, makes them difficult to read in a text-only browser (e.g., links 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 links 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:
| 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.
|
| amd64 | A 64-bit architecture that… |
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
- 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…
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 links and lynx 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 {{tl|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=<pre>
{{InfoBox stack
|{{InfoBox talk open|date=Jul 2 2015}}
by:
{{CodeBox|title=Example open discussion|1=<pre>
{{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)
- Fixed. --Maffblaster (talk) 00:44, 15 January 2017 (UTC)
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 Page|<span style="color: white;">Handbook (Main)</span>]]
- But I'd really rather see links to the individual "Full" pages, as shown at Handbook Talk:Parts/TOC#Linking to "Full" parts (not putting it here because of the large amount of code involved). - dcljr (talk) 05:29, 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:
- 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#How to I improve the Handbook?, 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:
Kind regards, --Larry (talk) 05:38, 5 January 2017 (UTC)</nowiki>}}
To this:
Kind regards, --~~~~</nowiki>}}
Then the next paragraph should be changed to something like:
The code <code><nowiki>--~~~~</nowiki></code>, which inserts a dated signature when the page is saved or previewed, can either be typed in manually or generated by using the ''Signature and timestamp'' button in the edit toolbar.
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)
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)