------------------------------------------------------------------------------
H Y D R O G E N Drum machine
------------------------------------------------------------------------------
HYDROGEN DOCUMENTATION
======================
Contents:
1. Overview
2. Tools, Supported Platforms, and Releases
3. Translators
4. Documentors
5. Developers
6. XML and Validation
7. Additional DocBook Authoring Restrictions
8. README.DOCUMENTATION.txt Changelog
1. Overview
-----------
Hydrogen documentation is maintained in DocBook 4.0 (XML) and
translated to HTML before release. Different translations are managed
through GNU gettext PO files. When the documentation is generated,
the PO files and the master documentation are merged to create the doc
for that specific language.
This document is split up into the three types of people who may want
to contribute to Hydrogen documentation: Translators, Documentors,
and Developers. A section is devoted to each one, individually.
This document assumes that you don't know much, and tries to give you
pointers to the stuff you need to know.
2. Tools, Supported Platforms, and Releases
-------------------------------------------
The following tools are used to maintain and process the
documentation. Depending on what you're working on, you may not need
all (or any) of these.
xml2po - Creates and updates the translation templates (*.pot) and
translation files (*.po) based on the original DocBook source.[1]
po2xml - Merges the master DocBook source with a translation file
(*.po) to create a translated DocBook file.[1]
xmlto - Converts DocBook files to HTML. (Note that xmlto can
convert DocBook to much more than just HTML.)[2]
xmllint - Used to validate the DocBook files against the DocBook
DTD.[3]
make - GNU's make utility.
As it happens, these tools are all very easy to install on Linux,
being a part of the core toolchains for KDE, Gnome, Debian, etc.
However, these tools are not as easy to set up on non-Linux platforms.
Furthermore, it is undesireable to add these to the list of build
dependencies for Hydrogen.
Therefore, these files will be processed before making a release of
Hydrogen, and the generated HTML output will become a part of the
distribution.
[1] xml2po and po2xml are part of poxml, which is in the KDE SDK.
http://www.kde.org/. The Makefile is set up for the KDE3 version.
[2] xmlto is a convenient front-end to an XSLT processor.
http://cyberelk.net/tim/software/xmlto/
[3] xmllint is part of libxml http://xmlsoft.org/
3. Translators
--------------
To translate documentation for Hydrogen you will need:
* To understand XML, and enough DocBook to be dangerous.
* A PO-file editor. (Note that a text editor works fine, but a
translation assistant like KBabel is better.)
* To be able to read and understand English.
If you don't have all the tools listed in Section 2, that's OK. Ask
the Hydrogen Developer list and someone there can process files for
you.
To make a new translation of the Hydrogen manual or tutorial, simply
copy the template and get started:
$ cp manual.pot manual_ja.po
Note that the _ZZ is added, and ZZ is the IANA abbreviation code for
that language. (E.g. 'ja' is for 'Japanese.') The registry for the
codes is located here:
http://www.iana.org/assignments/language-subtag-registry
If a translation already exists, but needs to be updated, you can
update the .po file like this:
$ touch manual.docbook
$ make manual_es.po
You can either see the changes using 'diff' or your translation
editor.
When you want to check your translation (and view it in HTML), this
can be done like this:
$ make manual_ja.html
NOTICE: Before creating the HTML file, the document will be
validated. If the document does not validate, you will have to alter
your translation file so that the output is a valid DocBook document.
For more information on Validation, see Section 6.
RULES AND GUIDELINES FOR TRANSLATING:
* No new content. New content must be first added to the master
(English) manual, and then translated to all the other manuals.
* Maintain the DocBook XML structure as closely as possible. Do
not add sections, divide paragraphs, or alter the markup
significantly.
* The English translation uses a little humor to try to keep the
reading interesting. When this happens, the language and idioms
being used are very cultural. Please do *NOT* translate the
words literally. Instead, please translate the ideas to your
culture as you see fit. We've asked the Documentors to mark
when this is happening so that you don't miss the joke. This
should show up in the PO file.
* If your culture doesn't like American-style informal writing,
please feel free to make a humor-less translation.
* Submit translations to the Hydrogen Developers list
(hydrogen-devel@lists.sourceforge.net)
4. Documentors
--------------
The master Hydrogen Manual and Tutorial are in English. All new
content and major revisions shall be done there first. In order to
work on the documentation, you will need:
* To know and understand XML and DocBook well.
* To know and understand Hydrogen well enough to *ask*
*questions*.
* An XML editor (note: any text editor will do).
* An XML validator (e.g. xmllint, xsltproc, Xalan)
* A way to create PNG images. (e.g. GIMP, PhotoShop)
What you write is pretty much your own style. Please *do* keep the
text interesting to read by using wit and a more familiar
conversational style. If you are using an English pun or expression
that is intended to convey humor, please mark it so that the
translator gets the joke:
(Ahem, don't ask me how I came up with that one.....)
Before submitting (or committing) your changes, please make sure that
your documents validate (see Section 6 below). Some guidelines:
* Use double-quotes for all attributes.
Good: , and then start a new one by putting
another . The closing tag "Knock, knock." "Who's there?" I am the very model of a modern
major general.
and
. (In HTML they didn't have the
forward slash.)
If a document follows all the rules of XML, it is called
"Well-Formed." For example, the following is a well-formed XML
document:
) inside of a. Instead, do it like this: Install hydrogen like this: However, if you *really* need to, go ahead and try it. Just be sure to test that it will match the strings for translation. * If you change indention... in tags... be careful how that affects the .po files. For example, if you had: $ apt-get hydrogen But change it to: bat zap You will need to add spaces in the .po files like this: Before: " bat zap " After: " bat zap " 8. README.DOCUMENTATION.txt Changelog ------------------------------------- 2009-09-02 Gabriel M. Beddingfield bat zap * Add section 7 Additional DocBook Authoring Restrictions. * Fixed a typo in TOC for Changelog. 2009-04-09 Gabriel M. Beddingfield * Create README.DOCUMENTATION.txt