Project:Documentation/Tips and tricks

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

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.

To update your copy of the repository, run  in the  directory.

Live repository for Gentoo developers
If you haven't checked out the  module yet, do it:

To update our copy of the repository, run  in the  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.

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

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

Setting up your XML Environment
Your system needs to know where to find the DTDs that our documentation uses. Edit as root and add the following line:

If your is empty or does not contain any entry, you need to insert the   element inside the   element:

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:

Testing a Gentoo Guide
To test a Gentoo Guide, first use  (from   ) to check if it uses valid XML:

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

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

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.

How do I convert a file to UTF-8?
There are quite a few tools that help you. A popular one is. Another one is , part of.

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:

Check for correct tags
Make sure that the attribute points to the correct location for the guide. This is generally. If you have a translated document, always specify the absolute path to the document (e.g. ). If you are writing a guide that uses the   or   DTD, you may use either  or. 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. Fix any lines that  prints out.

Bugzilla
Once you have finished your document, submit it to the Documentation Team using Bugzilla. You don't have to mention information like platform,  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 file. Patches should have the "Patch" option checked. Do not submit tarballs full of documents; attach each document and patch individually.