Gentoo Logo

Documentation Development Tips & Tricks


1.  Checking out the web site files

Using anonymous CVS

Contributors should use our anonymous CVS server. It contains the same files as the official CVS that Gentoo developers use. The anonymous CVS repository is updated every hour.

Create a dedicated directory for the sole purpose of developing documentation, then check out the web site files.

Code Listing 1.1: Checking out the web site files

$ cvs -d co gentoo/xml

To update your copy of the repository, run cvs update -dP in the gentoo/xml directory.

Live repository for Gentoo developers

If you haven't checked out the gentoo module yet, do it:

Code Listing 1.2: Checking out the gentoo module

$ export CVSROOT=<your nick>
$ cvs co gentoo/xml

To update our copy of the repository, run cvs update -dP in the gentoo/xml directory.

Online CVS Repository

You can request our Online CVS Repository to provide the differences between individual versions. The main English repository is fully available. The online CVS repository is updated every hour.

2.  Setting up your local environment

Installing gorg

Our GuideXML documentation is transformed into HTML by the www-servers/gorg package. You need to install it.

Note: You need at least gorg-0.6.3. You may need to keyword it for your architecture.

Follow the directions to configure gorg. You need to define the web root directory where you checked out our CVS repository (.../gentoo/xml/htdocs). The other parameters are only useful if you want to serve a local copy of

Setting up your XML Environment

Your system needs to know where to find the DTDs that our documentation uses. Edit /etc/xml/catalog as root and add the following line:

Code Listing 2.1: /etc/xml/catalog addendum

<rewriteURI uriStartString="/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/>

Note: You can also rewrite to the path where the DTDs have been checked out of CVS.

If your /etc/xml/catalog is empty or does not contain any entry, you need to insert the <rewriteURI> element inside the <catalog> element:

Code Listing 2.2: Minimal /etc/xml/catalog

<?xml version="1.0"?>
<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <rewriteURI uriStartString="/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/>

Besides, some files may specify the on-line DTD with an uri like You can also rewrite those references and avoid slow accesses to the net at validation time:

Code Listing 2.3: Extra /etc/xml/catalog addendum

<rewriteURI uriStartString="" rewritePrefix="/usr/portage/metadata/dtd/"/>

Testing a Gentoo Guide

To test a Gentoo Guide, first use xmllint (from dev-libs/libxml2) to check if it uses valid XML:

Code Listing 2.4: Using xmllint to validate GuideXML

$ xmllint --valid --noout alsa-guide.xml

If xmllint returns without showing anything, then the file structure is valid. Next you need to convert it to HTML:

Code Listing 2.5: Converting to HTML

$ gorg < alsa-guide.xml > alsa-guide.html

If no errors are displayed, you should be able to point your browser to alsa-guide.html to view the resulting document. If not, fix your guide until it works.

Note: In handbook chapters, links to other chapters will not be generated because on-line versions access handbook chapters via the master file, and the chap and part parameters.

Browsing your local copy of Gentoo's web site

Since you checked out a copy of Gentoo's web site out of our CVS, you can also use gorg to browse your local copy. Make sure you download the news index as explained in the guide if you want to see the same front page.

3.  Frequently Asked Questions

How do I convert a file to UTF-8?

There are quite a few tools that help you. A popular one is app-text/recode. Another one is iconv, part of sys-libs/glibc.

Recode's use is pretty straightforward. You tell it what character encoding is currently used by the document and to what encoding you want to convert the document.

For instance, to convert a document from ISO-8859-15 (also known as Latin-9) to UTF-8, you can use:

Code Listing 3.1: Recoding a file

(l9 = ISO-8859-15, u8 = UTF-8)
$ recode l9..u8 file.xml

4.  Documentation Submission Tips

Check for correct <guide> tags

Make sure that the <guide link> attribute points to the correct location for the guide. This is generally /doc/${LANG}/filename.xml. If you have a translated document, always specify the absolute path to the document (e.g. /doc/${LANG}/). If you are writing a guide that uses the guide or book DTD, you may use either /doc/${LANG}/filename.xml or filename.xml. Generally, the GDP recommends the former specification.

Check links

You must verify that all hyperlinks in your document work. If it is a translated document, make sure that any links to other translated documents point to the existing files.

Check for tabs

Tabs are absolutely forbidden in GuideXML documents except when required (e.g. if the document instructs the user to use tabs). To check a document for tabs, run grep "CTRL+V<TAB>" file.xml. Fix any lines that grep prints out.


Once you have finished your document, submit it to the Documentation Team using Bugzilla. You don't have to mention information like platform, emerge info output, arch, steps to reproduce, etc. If you have a translated document, be sure to select the Doc Translations component for your bug. Also, include a helpful summary for your translation using the preferred format: "[fr] New translation: /doc/fr/gnupg-user.xml". Replace [fr] with the two-letter code for your language.

By default, is the assignee of your bug; there's no need to change the assignee field.

Attach files and patches to the bug using the "plain text (text/plain)" selection. Do not select "XML source (application/xml)", even if you are submitting a .xml file. Patches should have the "Patch" option checked. Do not submit tarballs full of documents; attach each document and patch individually.

5.  Commonly or Dangerous Made Mistakes

Forgetting the all-arch-aspect of the Gentoo Handbook

The files in [gentoo]/xml/htdocs/doc/en/handbook that do not end with a "-<arch>.xml" suffix are read by all handbooks, which means that whatever is listed inside must be cross-architectural.

If you need to make modifications regarding your own architecture and you're afraid you need to place this in such a file, you might want to ask on first how to solve this. Sometimes there is a way without making it more difficult for other architectural users.

Not bumping version/date or doing it the wrong way

Conforming to the policy, you must bump a version/date when you make certain changes (most actually). Although the version is less important (the GDP lead will still kill you if you forget it) the date tells our users when the document was last modified.

If you are making a content change to a document (such as instructions, code examples, etc.), then you must increment the version. For non-content changes (e.g. typo or GuideXML fixes), version bumping is usually unnecessary.

When updating the handbook, only bump the date and version of the files you changed. Don't bump the handbook-ARCH.xml unless you actually changed its content.

Another common mistake is to update the version number using decimals. You shouldn't do this. The version is a simple whole number. Each update should increment it by one. 9 should become 10, not 9.1. For old documents not yet using the simpler whole number versioning, please increment it to the nearest whole number the next time you make a commit to it. So 4.67 should become 5, 1.2 should become 2, and so on.

Important: The exception to this rule is /doc/en/metadoc.xml. Metadoc should still use the existing point version scheme. So 1.119 becomes 1.120, not 2.


Page updated December 6, 2010

Summary: Some tips & tricks that make the life for a Gentoo Documentation Developer easier

Xavier Neys

Sven Vermeulen

Joshua Saddler

Donate to support our development efforts.

Copyright 2001-2015 Gentoo Foundation, Inc. Questions, Comments? Contact us.