1. Checking out the web site files
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 :pserver:anonymous@anoncvs.gentoo.org/var/cvsroot 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.gentoo.org:/var/cvsroot $ cvs co gentoo/xml |
To update our copy of the repository, run cvs update -dP in the gentoo/xml directory.
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
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 on gorg's home page to configure it. 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 www.gentoo.org.
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" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<rewriteURI uriStartString="/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/>
</catalog>
|
Besides, some files may specify the on-line DTD with an uri like http://www.gentoo.org/dtd/guide.dtd. 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="http://www.gentoo.org/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/>
|
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 on gorg's home page 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 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.
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.
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, docs-team@gentoo.org 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 gentoo-doc@gentoo.org 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 (SwifT 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 as if it were a decimal number. It's not. 3.9 should become 3.10, not 4.0, nor 3.91.
The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.