Project:Handbook/Handbook Development
Handbook on the wiki
The Gentoo handbook has been moved to the Gentoo Wiki. This move allows:
- Developers to easily update the important parts of the Gentoo handbook (instead of relying on the documentation project developers)
- The further run-down of the GuideXML format used by Gentoo (and thus optimization of infrastructure resources)
- Consolidation of all documentation on a single platform (the Gentoo Wiki) which also ensures a common interface and writing style
- Simpler links to the handbook
The handbook is within its own namespace (namely Handbook:). Currently, only developers and trusted contributors have edit rights on this namespace.
Architectural consolidation
In order to support the architectural consolidation of the handbook sections, we use the transclusion support of MediaWiki. All resources that are common to all architectures are available as subpages of the Handbook:Parts page. The architecture-specific handbooks include these subpages in their own location. For instance, Handbook:AMD64/Installation/About pulls in Handbook:Parts/Installation/About without any additional modifications.
When architecture-specific information is needed, it is first read in through the architecture-agnostic page. For instance, the Handbook:Parts/Installation/Media, which is included in the AMD64 handbook through Handbook:AMD64/Installation/Media, pulls in the hardware requirements block (Handbook:AMD64/Blocks/HWReqs). The following blocks need to be created for each and every architecture handbook:
- Blocks/HWReqs
- Used in the chapter on installation media and shows the hardware requirements for that platform
- Blocks/Booting
- Used in the chapter on installation media and shows the boot options as well as boot procedure of the installation media for that platform
- Blocks/Disks
- Used in the chapter on partitioning and informs the user how to partition the disks
- Blocks/ProfileChoice
- Used in the chapter on installing the base system and informs the user about the available Gentoo profiles
- Blocks/Kernel
- Used in the chapter on configuring the kernel, informing the user about how to configure the kernel for the given platform
- Blocks/Bootloader
- Used in the chapter on configuring the boot loader and informs the user about how to install and configure the boot loader for the given platform
Beyond these blocks, no architecture-specific information is (at the time of writing) necessary. This can be modified as more architecture-specific instructions and handbooks are being moved to the wiki though, so consider this a work-in-progress.
Architectural parameters
The general, architecture-agnostic pages can refer to some architecture-specific Semantic MediaWiki parameters. Like was the case in the historical previous driven Handbooks, each main Handbook page (such as Handbook:AMD64) defines a some of parameters that can be used in the Handbook.
The current set of parameters are:
| Parameter | Description | Example value |
|---|---|---|
| apple-partition-map | A boolean value that defines if a Handbook supports an Apple Partition Map during the disk partitioning section. This is exclusive to the ppc and ppc64 architectures. | Yes / True |
| apple-partition-map-partition | A device file automatically created by setting the Apple Partition Map as the partition table type for the architecture. This is exclusive to the ppc and ppc64 architectures. | /dev/sda1 |
| apple-newworld-bootblock-partition | A device file necessary for bootstrapping a New World type Power PC system. This is exclusive to the ppc and ppc64 architectures. | /dev/sda2 |
| apple-swap-partition | A device file used as the swap partition for the Apple PowerMac G5 system. This is exclusive to the ppc and ppc64 architectures. | /dev/sda3 |
| apple-root-partition | A device file used as the root partition (/) for the Apple PowerMac G5 system. This is exclusive to the ppc and ppc64 architectures. | /dev/sda4 |
| efi-system-partition | A device file used as the ESF partition (typically /boot/efi). | /dev/sda1 |
| boot-partition | A device file used as the boot partition (/boot/) for the architecture. | /dev/sda2 |
| root-partition | A device file used as the root partition (/) for the architecture. | /dev/sda4 |
| swap-partition | A device file used as the swap partition for the architecture. | /dev/sda3 |
| stage3-tarball-file | Filename of the stage3 tarball file. | stage3-*.tar.xz |
| cflags | Proper cflags for the architecture. | -march=native -O2 -pipe |
| kernel-version | A kernel version that is currently stable for that architecture. | 3.16.5-gentoo |
| kernel-sources | The kernel sources package (without category) that is recommended for that architecture. | gentoo-sources |
| supports-systemd | true if the architecture supports systemd (support for OpenRC is presumed to be always true for Gentoo). | true |
| grub-platforms | Possible options include: efi-64, ...
|
efi-64 |
| grub-efi-file | Possible options include: grubx64.efi, ...
|
grubx64.efi |
| grub-install-target | Possible options include: x86_64-efi, ...
|
x86_64-efi |
These parameters should be defined something like the following in the main (base) page of each architecture's handbook:
{{#set: architecture=amd64
|efi-system-partition=/dev/sda1
|boot-partition=/dev/sda2
|swap-partition=/dev/sda3
|root-partition=/dev/sda4
|cflags=-march{{=}}native -O2 -pipe
|kernel-version=3.16.5-gentoo
|kernel-sources=gentoo-sources
|supports-systemd=true
|grub-platforms=efi-64
|grub-efi-file=grubx64.efi
|grub-install-target=x86_64-efi
}}Inside the pages themselves, the the following template can be used to ask Semantic MediaWiki generate the contextually appropriate variable values:
This is the {{Handbook Variable|architecture}} architectureThis support is powered by the Semantic MediaWiki extension, however this extension must now be used through a template (in this case the {{Handbook Variable}} template). Direct SMW calls are not advised as they can eventually not render properly.
Adding new parameters
New parameters can be added by creating a new Property for the appropriate type of data. In most cases this will likely be a text property.
Each chapter in the handbook will refer to the table of contents (Handbook:Parts/TOC) which acts as a structure for readers to easily see where in the handbook they are currently positioned.
At the end of each chapter, a navigator (Handbook:Parts/Navigator) is added which takes two options: Prev= and Next= which are the links to the previous and next chapter. Before the navigator is sourced, the page title is set:
{{#set:Has Title=This Is The Page Title}}
{{Handbook:Parts/Navigator
|Next=Handbook:{{ROOTPAGENAME}}/Installation/Disks
|Prev=Handbook:{{ROOTPAGENAME}}/Installation/About
}}Translation teams can copy the Handbook:Parts/Navigator/de content and include that content in the page itself, making sure that the Home= parameter to set the translated value of "Home".
New architecture requirements
New handbooks should only be made available when the newly supported architecture can be structured and installed in a fashion similar to the current handbooks. This means that the architecture:
- Must support installation through Gentoo official installation media (currently ISO files either burned to CD/DVDs or USB bootable disks).
- Use the autobuilds/ location on the distfile mirrors.
- Support manual and genkernel configuration of the kernel, and/or a distribution binary kernel such as sys-kernel/gentoo-kernel-bin.
- If only a customized binary kernel (such as a kernel with device tree support (CONFIG_OF) - which is necessary to support certain devices connected to ARM64-based Raspberry Pi boards - for example) is supported, then it must be explicitly noted.
Translating
The Gentoo handbook is marked ready for translations. However, through the use of transclusion and Semantic MediaWiki a few guidelines are in place.
Transclusion
When encountering a request for a transclusion, first make sure that the target page is already translated.
For instance, in Handbook:AMD64/Installation/About only a transclusion of Handbook:Parts/Installation/About is shown:
{{Handbook:Parts/Installation/About}}In this case, first translate the transcluded page. This should result in a language-specific page (such as Handbook:Parts/Installation/About/en for the (trivial) English translation).
In the architecture-specific page, the transclusion then refers to the translated page:
{{Handbook:Parts/Installation/About/en}}Noinclude tags
During translations, sometimes a dangling noinclude tag might show up. If that is the case, then this tag may not be part of the translation. Instead, make this an empty translation block.
This is a result of the combination of translations and transclusions.
The use of
<noinclude> was due to a misunderstanding though, and can be removed in future. Instead of transcluding the (translatable) pages, the English (master) language should be included as that one does not contain any translation related information.Titles
To support setting the title for a translated page, the {{Handbook:Templates/SetTitle}} code is added to all master pages. This code includes all necessary logic to set the title of a page.
All it needs is the title inside a Has short Title and Has Title definition. These can be added right before the navigator tag, like so:
{{#set:Has short Title=Über die Installation|Has Title=Über die Gentoo Linux-Installation}}
{{Handbook:Parts/Navigator/de|Prev=Handbook:{{ROOTPAGENAME}}/de|Next=Handbook:{{ROOTPAGENAME}}/Installation/Media/de}}There is no need to include the DISPLAYTITLE directive inside the translation tags. If a warning is displayed about multiple DISPLAYTITLE entries, add the noerror option to the DISPLAYTITLE directive like so:
{{DISPLAYTITLE:This is the pagename|noerror}}Overview
The following is an overview of the structure of a handbook (and could act as a simple ordered listing for translators to focus on).