Documentation Development Tips & Tricks1. 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.
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:
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.
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 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:
If your /etc/xml/catalog is empty or does not contain any entry, you need to insert the <rewriteURI> element inside the <catalog> element:
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:
To test a Gentoo Guide, first use xmllint (from dev-libs/libxml2) to check if it uses valid XML:
If xmllint 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 alsa-guide.html 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 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:
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 (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.
The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply. |
|