Contributing to this document

Contributions for this document are very welcome. Whether you've found a typo or have written an entire new section, the best way to get in touch is via Bugzilla. Please look at the bug list and file a new bug.

The editors reserve the right to modify submissions as they see fit. Any substantial changes will of course be discussed with the submitter first — unless explicitly requested, minor typo corrections and formatting fixes will not be discussed.

This document is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. If this is a problem, don't submit anything.

This document is produced using the DevBook XML build system. You can download a snapshot of the system as well as the relevant XML files from Git, see the following section. If you'd rather just work with plain text, that's fine too — the formatting can be easily done by someone else (meaning, us).

Where to find the sources

Currently, sources are hosted on git.gentoo.org. For current Gentoo developers, access is at git+ssh://[email protected]/proj/devmanual.git. Non-developers can clone the repository by typing git clone git://anongit.gentoo.org/proj/devmanual.git. The sources are also hosted on GitHub for those who prefer to submit patches using pull requests.

To build the devmanual, simply run make in the top directory of the repository. You need xsltproc (from dev-libs/libxslt) for the XML to HTML conversion, xmllint (from dev-libs/libxml2) for validation, and rsvg-convert (from gnome-base/librsvg) for the SVG to PNG conversion used in some of the figures throughout the document.

To check if the document's XML is valid, run make validate in the top-level directory, which will validate all XML files using xmllint.

Quick introduction to DevBook XML

DevBook XML is heavily based on GuideXML and many tags are similar, if not the same. The main differences occur in layout which are designed to make a large-scale publication easier to produce and manage using a hierarchical tree system. Before starting off you really should first examine the DevBook XML guide in a reasonable amount of depth.

Differences from GuideXML

Indentation
Indent when needed — you should not indent any section flow elements such as <subsection> but do indent tables, lists and definition lists. Do not indent text in ordinary paragraph blocks.
Code samples
You can use the normal GuideXML tag <pre> when you need no syntax highlighting. When you need syntax highlighting use the <codesample> tag along with a lang attribute — usually you want this to be set to ebuild to syntax highlight ebuild code snippets.
Hierarchy
The whole document is organized as a tree. Each directory can contain one document. Each document can inherit multiple sub-documents using the <include> flag. You must ensure that the self tag in each document correctly points to the relative path of the document from the root node so that the tree-walking algorithms work correctly.

Style guidelines

  • This document is in British English. Submissions in other kinds of English are welcome, but they may have their spelling corrected.
  • Third person form should be used rather than first.
  • This is not a formal document. The writing style is intended to be professional but readable.