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.

Checking 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:

Checking out the gentoo module

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:

/etc/xml/catalog addendum

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

Minimal /etc/xml/catalog

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:

Extra /etc/xml/catalog addendum

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

Using xmllint to validate GuideXML

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

Converting 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:

Recoding a file

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.

Forgetting the all-arch-aspect of the Gentoo Handbook
The files in that do not end with a "- .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. should become , not. 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  should become  ,   should become   , and so on.