Handbook Talk:Main Page

From Gentoo Wiki
Jump to: navigation, search

Merging tables

Talk status
This discussion is done.

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)

Intel Core2

Talk status
This discussion is done.

"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

Talk status
This discussion is done as of March 8, 2017.
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:

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)

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)
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

Talk status
This discussion is done.

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

Talk status
This discussion is done as of Jan 14, 2017.

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)
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

Talk status
This discussion is done.

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)
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

Talk status
This discussion is done.

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

Talk status
This discussion is done.

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

Talk status
This discussion is done.

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

Talk status
This discussion is still ongoing.

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)