Project:Handbook/Handbook Development

From Gentoo Wiki
Jump to:navigation Jump to:search

This page provides instructions to Gentoo handbook authors and editors who wish to understand the architectural design and implementation details for creating new handbooks, or extending the existing ones.

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.

Changelog

Although MediaWiki software records detailed change records for each page, due to the technical implementation of the handbooks, it is difficult to track changes across the handbooks as a whole (Handbook:Parts and the all the sub-arches). Due to this hassle, it has been determined that an official 'at a glance' changelog would be a positive addition for the Gentoo community to obtain better visibility to Handbook revisions.

This effort is loosely based on and inspired by Common Changelog, but has some distinctions since MediaWiki uses Wikitext for syntax as opposed to Markdown. Releases should follow the following format, as described upstream[1]. The Handbook Project will attempt to maintain a basic semantic versioning for most revisioning, however it will not be as strict as documentation managed with a version control system since revisions must be manually added by editing the changelog page.

Types of changes are to be grouped together. Groups include: Add, Refactor, Bump, Document, Fix, and Deprecate. Changes are to be prefixed with the scope for the change, which can be either "All" for all handbooks (transcluded from Handbook:Parts) or specific computer architectures (Handbook:Alpha, Handbook:AMD64, Handbook:HPPA, etc.). {{Anchor}} templates should be added to each of the grouped change type subsections for appropriate linking. This is demoed in the following example:

CODE Example of some recorded change revisions
== Changelog ==

=== 1.0.0 - 2023-09-03 ===

==== {{Anchor|1.0.0_-_2023-09-03_Added}} Added ====

* '''All:''' Added a semantically versioned changelog loosely based on and inspired by [https://common-changelog.org/ Common Changelog]. Page is available under {{Link|Handbook:Main Page/Changelog}}.

Architectural consolidation

In order to support the architectural consolidation of the handbook sections, we use the transclusion feature of MediaWiki. All resources that are common to all architectures are available as subpages of the Handbook:Parts pages. 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 properties. Like was the case in the historical previous driven Handbooks, each main Handbook page (such as Handbook:AMD64) set properties that can be referenced within the Handbook.

The current set of properties are:

Parameter Property type Example value(s) Description
architecture Text amd64 The computer architecture supported by the handbook. Can be one of alpha, amd64, arm, arm64, hppa, ia64, mips, ppc, ppc64, sparc, or x86.
apple-partition-map Boolean Yes, True, No, False 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.
apple-partition-map-partition Text /dev/sda1 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.
apple-newworld-bootblock-partition Text /dev/sda2 A device file necessary for bootstrapping a New World type Power PC system. This is exclusive to the ppc and ppc64 architectures.
apple-swap-partition Text /dev/sda3 A device file used as the swap partition for the Apple PowerMac G5 system. This is exclusive to the ppc and ppc64 architectures.
apple-root-partition Text /dev/sda4 A device file used as the root partition (/) for the Apple PowerMac G5 system. This is exclusive to the ppc and ppc64 architectures.
efi-system-partition Text /dev/sda1 A device file used as the EFI System Partition (typically /efi).
efi-system-partition-uuid Text c12a7328-f81f-11d2-ba4b-00a0c93ec93b The Discoverable Partition Specification used as the EFI System Partition identifier (typically /efi).
boot-partition Text /dev/sda2 A device file used as the boot partition (/boot/) for the architecture.
boot-partition-mount-point Text /boot /boot is as the recommended mount point used for most computer architectures.
boot-partition-format Text xfs The file system format used on the MBR DOS / legacy BIOS boot partition.
esp-mount-point Text /efi Recommended mount point for the EFI System Partition. See UAPI Group Specification's Mount Points section of the Boot Loader Specification.
esp-mount-options Text umask=0077 Recommended default mount options for a more secure ESP mount point.
esp-format Text vfat Required filesystem for the EFI System Partition.
root-partition Text /dev/sda4 A device file used as the root partition (/) for the architecture.
root-partition-mount-point Text / The mount point of the root partition, as visible from the chrooted environment.
root-partition-live-env-mount-point Text /mnt/gentoo The mount point of the root partition, as visible from the live environment.
root-partition-format Text xfs The file system format used on the root partition.
root-partition-uuid Text 1aacdb3b-5444-4138-bd9e-e5c2239b2346 A Discoverable Partition Specification used as a root partition identifier (/) for an architecture; in this example HPPA.
root-partition-uuid-32-bit Text 44479540-f297-41b2-9af7-d131d5f0458a A Discoverable Partition Specification used as a root partition identifier (/) for a 32-bit x86 architecture.
root-partition-uuid-32-bit-little-endian Text 37c58c8a-d913-4156-a25f-48b1b64e07f0 A Discoverable Partition Specification used as a root partition identifier (/) for the 32-bit MIPS LittleEndian (mipsel).
root-partition-uuid-64-bit Text 4f68bce3-e8cd-4db1-96e7-fbcaf984b709 A Discoverable Partition Specification used as a root partition identifier (/) for a the 64-bit AMD64 architecture.
root-partition-uuid-64-bit-big-endian Text 912ade1d-a839-4913-8964-a10eee08fbd2 A Discoverable Partition Specification used as a root partition identifier (/) for the 64-bit PowerPC BigEndian architecture.
root-partition-uuid-64-bit-little-endian Text c31c45e6-3f39-412e-80fb-4809c4980599 A Discoverable Partition Specification used as a root partition identifier (/) for the 64-bit PowerPC LittleEndian architecture.
swap-partition Text /dev/sda2 A device file used as the swap partition for the architecture.
swap-partition-uuid Text 0657fd6d-a4ab-43c4-84e5-0933c84b4f4f The Discoverable Partition Specification used as the swap space partition identifier.
swap-partition-format Text swap Linux swap may not ever change, but a property has been defined for it none-the-less.
stage3-tarball-file Text stage3-*.tar.xz Filename of the stage3 tarball file.
cflags Text -march=native -O2 -pipe Proper CFLAGS for the architecture.
kernel-version Text 6.1.38-gentoo A currently stable Linux kernel version that includes the source suffix for the target architecture.
linux-kernel-short-version Text 6.1.38 A currently stable, shorter version number of the Linux kernel that excludes the source suffix for the target architecture.
kernel-sources Text gentoo-sources The kernel sources package (without category) that is recommended for the target architecture.
supports-systemd Boolean Yes, True, No, False true if the architecture supports systemd (support for OpenRC is presumed to be always true for Gentoo).
grub-platforms Text efi-64 See sys-boot/grub's USE_EXPAND values for a list of possible values.
grub-efi-file Text grubx64.efi Possible options include: grubx64.efi.
grub-install-target Text x86_64-efi Possible options include: x86_64-efi, ...
efibootmgr-efi-file Text bootx64.efi Possible options include: bootx64.efi.
default-efi-file Text bootx64.efi Possible options include: bootx64.efi.
deprecated-main-ebuild-repository-location Text /usr/portage The directory location Portage previously used to hold the Gentoo ebuild repository.
main-ebuild-repository-location Text /var/db/repos/gentoo The directory location Portage currently uses to hold the Gentoo ebuild repository.
portage-deprecated-distdir-location Text /usr/portage/distfiles The directory location Portage previously used to hold downloaded distfiles.
portage-distdir-location Text /var/cache/distfiles The directory location Portage currently uses to hold downloaded distfiles.
portage-deprecated-binpkg-location Text /usr/portage/packages The directory location Portage previously used to hold binary packages.
portage-binpkg-location Text /usr/portage/packages The directory location Portage currently uses to hold binary packages.
portage-deprecated-profile Text 13.0 A deprecated Portage profile version number.
portage-deprecated-profile Text 17.1 The currently stable Portage profile version number.
portage-deprecated-profile Text 17.1 The currently unstable Portage profile version number.

The properties should be defined something like the following in the main (base) page of each 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 via the {{Handbook Variable}} template 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 not render properly on the page.

Adding new properties

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, but could be a boolean value, URL, etc.

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

Editing

Formatting guidelines

As much as possible, handbook edits and enhancements follow the wiki project's agreed upon formatting Guidelines. Extensions to these guidelines are called out in the following subsections.

Links

Targeting the Handbook namespace

All links which point to targets inside the Handbook: namespace should use the {{HandbookLink}} template. This is so that transcluded and translated pages can be linked properly.

Targeting any other namespace

Links that point outside the Handbook space, e.g to the Project: or Main: namespaces, can be safely converted to the {{Link}} template per wiki Guidelines.

Adding new topics

Handbook authors and editors should exhibit caution and discuss with other members of the team before adding new topics or features into the handbook. Ideally, all open handbook discussions will be closed out and current formatting standards met before attempting to add new features.

Principals to consider

As stated at the beginning of the handbook: "an effort to centralize essential documentation for initial Gentoo installation and basic system administration."

The Handbook has to track project work and Gentoo features from many areas of the Gentoo ecosystem before adding new topics and/or features. Many times changes in the Handbook are reactive or are make in conjunction with development efforts from other Gentoo projects.

Areas to watch include, but not limited to:

  1. Project:Base team: Profile and other system-wide changes which impact every Gentoo installation.
  2. Project:RelEng team: Changes to live images, stage files, crypo signatures.
  3. Project:Infrastructure team: Downloads, mirrors, retrieval methods, etc.
  4. Project:Portage team: New Portage features which would benefit new installations. Eg Cryptographically signed ebuilds, binhost/binpkg support.
  5. Project:Wiki team: Changes to templates, formatting guidelines, etc.
  6. Project:Website Websites team: Changes to www.g.o download links, news items, and other misc. items.

For example, some wish list items from the Gentoo community include handbook installation and configuration paths for

  • Full disk encryption - One of the more popular requests, but would require yet another install path and additional caveats through the already complex Preparing the disks section.
  • Full desktop environments - Aligning with official Gentoo project support of each (Project:GNOME, Project:KDE, etc.). Would add significant overhead to a very limited number of hands increase the number of projects (see areas to watch above) to formally monitor. Great support exists elsewhere on the wiki
  • Accelerated graphics - Helpful for systems, but can be configured post-install and is a topic unnecessary for basic Gentoo system administration.
  • Support for even MOAR bootloaders - Architecture specific, therefore must be put into blocks sections... is more than one bootloader really needed?
  • Power management - Helpful for systems, but can be configured post-install and is a topic unnecessary for basic Gentoo system administration.
  • Switching C implementations - No. Just no.
  • Ricing beyond belief - Also no.
Disk formatting and filesystems
Disk formats and filesystems should be included in within the mainline Linux kernel. ZFS has intentionally left off, since it's not (yet) included within mainline.

Other handbooks

Several other handbooks efforts exist, and should be considered before adding new topics to the main handbook.

  • Complete Handbook — extends and expands the wiki's coverage of several subjects related to Linux in general and the Gentoo Linux operating system in particular.
  • Embedded Handbook — a collection of community maintained documents providing a consolidation of embedded and SoC knowledge for Gentoo.
  • Security Handbook — valuable guidance on Gentoo Linux security and cybersecurity in general.

When possible, these handbooks should act like 'extensions' to the main handbook for certain topics.

Discussions

Requests made within discussions may be rejected, discussed further, or implemented. It is common to have requests which fall outside the goal of the handbook's state purpose, which can massively increase the scope of covered content. Generally speaking, these requests should be politely declined.

Important
Always consider the handbook's thesis statement when deliberating the appropriate actions to take on a discussion: an effort to centralize essential documentation for initial Gentoo installation and basic system administration.

Talk pages with open discussions can be tracked using Semantic MediaWiki queries: view handbook pages with open discussions.

Closing discussions

When closing discussions use diff links to show the changes which were implemented as a result of the discussion. Be sure to set the {{Talk}} template's anonymous parameter to closed and pass the date parameter today's date in ISO 8601 format, per the wiki Guidelines.

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

Important
Note that Talk: pages may associated with every page of the handbook listed in the table below. Talk pages should be cleaned up and old discussions archived. For example stale discussions from Handbook Talk:AMD64/Installation/Stage have been moved to Handbook Talk:AMD64/Installation/Stage/Archive‎‎.

The following is an overview of the structure of a handbook (and could act as a simple ordered listing for translators to focus on).


Todo: Handbook development table

  • Use {{subpages}} to find possible missing pages to add to the table.
  • Create a policy or at least some guidance for length of time Handbook discussions should be discussed before closing or becoming stale.


Handbook pages

Handbook page matrix
Chapter Parts page(s) 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
OpenRC 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 HWReqs (BLOCK), Booting (BLOCK), Media HWReqs (BLOCK), Booting (BLOCK), Media HWReqs (BLOCK), Booting (BLOCK), Media HWReqs (BLOCK), Booting (BLOCK), Media HWReqs (BLOCK), Booting (BLOCK), Media HWReqs (BLOCK), Booting (BLOCK), Media HWReqs (BLOCK), Booting (BLOCK), Media HWReqs (BLOCK), Booting (BLOCK), Media HWReqs (BLOCK), Booting (BLOCK), Media HWReqs (BLOCK), Booting (BLOCK), Media
Configuring the network Networking Networking Networking Networking Networking Networking Networking Networking Networking Networking
Preparing the disks Disks (BLOCK), 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
The stage file Stage Stage Stage Stage Stage Stage Stage Stage Stage Stage
Installing base system ProfileChoice (BLOCK), systemd (BLOCK), Base ProfileChoice (BLOCK), Base ProfileChoice (BLOCK), Base ProfileChoice (BLOCK), Base ProfileChoice (BLOCK), Base ProfileChoice (BLOCK), Base ProfileChoice (BLOCK), Base ProfileChoice (BLOCK), Base ProfileChoice (BLOCK), Base ProfileChoice (BLOCK), Base
Configuring the kernel Kernel (BLOCK), Kernel, Dist-Kernel Transcluded into Kernel for amd64, arm64, ppc64, x86 ISAs. 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 Fstab (BLOCK), System Fstab (BLOCK), System Fstab (BLOCK), System Fstab (BLOCK), System Fstab (BLOCK), System Fstab (BLOCK), System Fstab (BLOCK), System Fstab (BLOCK), System Fstab (BLOCK), System Fstab (BLOCK), System
Installing tools Tools Tools Tools Tools Tools Tools Tools Tools Tools Tools
Configuring the 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 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 package repository CustomTree CustomTree CustomTree CustomTree CustomTree CustomTree CustomTree CustomTree CustomTree CustomTree
Advanced features Advanced Advanced Advanced Advanced Advanced Advanced Advanced Advanced Advanced Advanced
OpenRC 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

See also

References