Project:Handbook/Handbook Development

Handbook on the wiki
The Gentoo handbook has been moved to the Gentoo Wiki. This move allows for
 * 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 is used in the chapter on installation media and shows the hardware requirements for that platform
 * Blocks/Booting is 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 is used in the chapter on partitioning and informs the user how to partition the disks
 * Blocks/ProfileChoice is used in the chapter on installing the base system and informs the user about the available Gentoo profiles
 * Blocks/Kernel is used in the chapter on configuring the kernel, informing the user about how to configure the kernel for the given platform
 * Blocks/Bootloader is 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:

These parameters are defined as follows in the main page:

Declaration of a parameter

Inside the pages themselves, the parameter can be referred to as follows:

Requesting the value of a parameter

This support is powered by the Semantic MediaWiki extension.

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:  and   which are the links to the previous and next chapter.

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:

Transclusion of the About page

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:

Transclusion of the About page referring to the translated version

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.

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

Progress
The move of the handbooks is still work in progress.


 * (done) Main pages (architecture-agnostic) pushed to the wiki
 * Architecture specifics
 * (done) amd64
 * (done) x86
 * (done) alpha
 * (done) hppa
 * (done) ia64
 * (done) mips
 * (done) ppc
 * (done) ppc64
 * (done) sparc
 * (done) Verify partitioning example usage consistency
 * Update handbook GuideXML links to point to Wiki
 * Update main site links to point to new handbooks
 * Update various links in wiki to the new handbooks