Project:Handbook/Handbook Development

From Gentoo Wiki
Jump to: navigation, search

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 parameters. Like was the case in the GuideXML-driven Handbooks, each main Handbook page (such as Handbook:AMD64) defines a couple of parameters that can be used in the Handbook.

The current set of parameters are:

Parameter Description Example
architecture A lowercase representation of the architecture name as used by Gentoo. amd64
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 that architecture. /dev/sda2
root-partition A device file used as the root partition (/) for that architecture. /dev/sda4
swap-partition A device file used as the swap partition for that architecture. /dev/sda3
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 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 page of the architecture's Handbook:

CODE Declaration of a parameter
{{#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:

CODE Requesting the value of a parameter using the Handbook Variable template
This is the {{Handbook Variable|architecture}} architecture
Important
This 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.

TOC and navigator

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:

CODE Setting page title
{{#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 the moment the new architecture can be structured and installed as the current handbooks are. This means that the architecture:

  • Must support installation through the minimal installation CDs.
  • Use the autobuilds location on the mirrors.
  • Support manual and genkernel configuration of the kernel.

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:

CODE Transclusion of the About page
{{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:

CODE Transclusion of the About page referring to the translated version
{{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.

Important
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:

CODE Setting a translated title
{{#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:

CODE Setting DISPLAYTITLE with noerror
{{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).


Chapter Parts page alpha amd64 hppa ia64 mips ppc ppc64 sparc x86
Introduction page Main page
TOC
Contents Index Index Index Index Index Index Index Index Index Index
Full pages
Name Parts page alpha amd64 hppa ia64 mips ppc ppc64 sparc x86
Intro to full Full Full Full Full Full Full Full Full Full Full
Installing Gentoo Linux Installation Installation Installation Installation Installation Installation Installation Installation Installation Installation
Working with Gentoo Working Working Working Working Working Working Working Working Working Working
Working with portage Portage Portage Portage Portage Portage Portage Portage Portage Portage Portage
Network configuration Networking Networking Networking Networking Networking Networking Networking Networking Networking Networking
Installation
Chapter Parts page alpha amd64 hppa ia64 mips ppc ppc64 sparc x86
About the installation About About About About About About About About About About
Choosing the media Media HWReqs, Booting, Media HWReqs, Booting, Media HWReqs, Booting, Media HWReqs, Booting, Media HWReqs, Booting, Media HWReqs, Booting, Media HWReqs, Booting, Media HWReqs, Booting, Media HWReqs, Booting, Media
Configuring the network Networking Networking Networking Networking Networking Networking Networking Networking Networking Networking
Preparing the disks DesigningPartitionScheme, Disks Disks (block), Disks Disks (block), Disks Disks (block), Disks Disks (block), Disks Disks (block), Disks Disks (block), Disks Disks (block), Disks Disks (block), Disks Disks (block), Disks
Installing stage3 Stage Stage Stage Stage Stage Stage Stage Stage Stage Stage
Installing base system Systemd, Base ProfileChoice, Base ProfileChoice, Base ProfileChoice, Base ProfileChoice, Base ProfileChoice, Base ProfileChoice, Base ProfileChoice, Base ProfileChoice, Base ProfileChoice, Base
Configuring the kernel Kernel Kernel (block), Kernel Kernel (block), Kernel Kernel (block), Kernel Kernel (block), Kernel Kernel (block), Kernel Kernel (block), Kernel Kernel (block), Kernel Kernel (block), Kernel Kernel (block), Kernel
Configuring the system System System System System System System System System System System
Installing tools Tools Tools Tools Tools Tools Tools Tools Tools Tools Tools
Configuring the boot loader Bootloader Bootloader (block), Bootloader Bootloader (block), Bootloader Bootloader (block), Bootloader Bootloader (block), Bootloader Bootloader (block), Bootloader Bootloader (block), Bootloader Bootloader (block), Bootloader Bootloader (block), Bootloader Bootloader (block), Bootloader
Finalizing Finalizing Finalizing Finalizing Finalizing Finalizing Finalizing Finalizing Finalizing Finalizing Finalizing
Working with Gentoo
Chapter Parts page alpha amd64 hppa ia64 mips ppc ppc64 sparc x86
Portage introduction Portage Portage Portage Portage Portage Portage Portage Portage Portage Portage
USE flags USE USE USE USE USE USE USE USE USE USE
Portage features Features Features Features Features Features Features Features Features Features Features
Initscript system Initscripts Initscripts Initscripts Initscripts Initscripts Initscripts Initscripts Initscripts Initscripts Initscripts
Environment variables EnvVar EnvVar EnvVar EnvVar EnvVar EnvVar EnvVar EnvVar EnvVar EnvVar
Working with portage
Chapter Parts page alpha amd64 hppa ia64 mips ppc ppc64 sparc x86
Files and directories Files Files Files Files Files Files Files Files Files Files
Variables Variables Variables Variables Variables Variables Variables Variables Variables Variables Variables
Mixing software branches Branches Branches Branches Branches Branches Branches Branches Branches Branches Branches
Additional tools Tools Tools Tools Tools Tools Tools Tools Tools Tools Tools
Custom portage tree CustomTree CustomTree CustomTree CustomTree CustomTree CustomTree CustomTree CustomTree CustomTree CustomTree
Advanced features Advanced Advanced Advanced Advanced Advanced Advanced Advanced Advanced Advanced Advanced
Network configuration
Chapter Parts page alpha amd64 hppa ia64 mips ppc ppc64 sparc x86
Getting started Introduction Introduction Introduction Introduction Introduction Introduction Introduction Introduction Introduction Introduction
Advanced configuration Advanced Advanced Advanced Advanced Advanced Advanced Advanced Advanced Advanced Advanced
Modular networking Modular Modular Modular Modular Modular Modular Modular Modular Modular Modular
Wireless Wireless Wireless Wireless Wireless Wireless Wireless Wireless Wireless Wireless Wireless
Adding functionality Extending Extending Extending Extending Extending Extending Extending Extending Extending Extending
Dynamic management Dynamic Dynamic Dynamic Dynamic Dynamic Dynamic Dynamic Dynamic Dynamic Dynamic