swift 05/07/05 10:31:45
Added: www-redesign/htdocs/proj/en/gdp/doc doc-policy.xml
doc-quiz.xml doc-tipsntricks.xml metadoc-guide.xml
translators-howto.xml
Log:
Adding GDP docs
Revision Changes Path
1.1
gentoo-projects/www-redesign/htdocs/proj/en/gdp/doc/doc-policy.xml
file :
http://www.gentoo.org/cgi-bin/viewcvs.cgi/gentoo-projects/www-redesign/htdocs/proj/en/gdp/doc/doc-policy.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain:
http://www.gentoo.org/cgi-bin/viewcvs.cgi/gentoo-projects/www-redesign/htdocs/proj/en/gdp/doc/doc-policy.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo
Index: doc-policy.xml
===================================================================
<?xml version='1.0' encoding="UTF-8"?>
<!-- $Header:
/var/cvsroot/gentoo-projects/www-redesign/htdocs/proj/en/gdp/doc/doc-policy.xml,v
1.1 2005/07/05 10:31:45 swift Exp $ -->
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<guide link="doc-policy.xml">
<title>Gentoo Linux Documentation Policy</title>
<author title="Author">
<mail link="[EMAIL PROTECTED]">John P. Davis</mail>
</author>
<author title="Author">
<mail link="[EMAIL PROTECTED]">Sven Vermeulen</mail>
</author>
<author title="Editor">
<mail link="[EMAIL PROTECTED]">Donnie Berkholz</mail>
</author>
<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.0 -->
<abstract>
This document contains the Gentoo Documentation Policy, which is the
base document which all Gentoo Documentation developers and
Contributors should know and exercise.
</abstract>
<license/>
<version>3.13</version>
<date>2005-06-02</date>
<chapter>
<title>Introduction</title>
<section>
<title>Introduction</title>
<body>
<p>
The Gentoo Linux Documentation team aspires to create exceptionally
professional documentation that is immediately clear and concise to the
end user. In order to fulfill this goal, we have very specific rules and
guidelines that <e>all</e> documentation must go through prior to
dissemination on our website, or elsewhere.
</p>
</body>
</section>
<section>
<title>Covered Topics</title>
<body>
<p>
This policy will cover the following topics:
</p>
<ul>
<li>Documentation Project Team Organization</li>
<li>Documentation Guidelines</li>
<li>Documentation Team Recruitment</li>
</ul>
</body>
</section>
</chapter>
<chapter>
<title>Documentation Project Team Organization</title>
<section>
<title>Organization</title>
<body>
<p>
The Gentoo Documentation Project Team is split into several smaller teams
that work in tandem with each other. Each smaller team represents an active
development team of a Gentoo Documentation Subproject.
</p>
<p>
The Gentoo Documentation Project is strategically led by a top-level Manager
as required by the <uri link="/doc/en/management-structure.xml">Gentoo
Management Structure</uri>. This document also describes the responsibilities
of the Strategic Manager with respect to Gentoo Linux.
</p>
<p>
For day-to-day managerial tasks, the Gentoo Documentation Project has an
Operational Manager. This person keeps track of all short-term tasks
related to documentation. The Operational Manager and Strategic Manager can be
one and the same if the Strategic Manager wishes so.
</p>
<p>
Currently these positions are taken by the following people:
</p>
<table>
<tr>
<th>Position</th>
<th>Developer Name</th>
<th>Developer Nick</th>
</tr>
<tr>
<ti>Strategic Manager</ti>
<ti>Sven Vermeulen</ti>
<ti><mail link="[EMAIL PROTECTED]">swift</mail></ti>
</tr>
<tr>
<ti>Operational Manager</ti>
<ti>Xavier Neys</ti>
<ti><mail link="[EMAIL PROTECTED]">neysx</mail></ti>
</tr>
</table>
<p>
Every subproject has a Strategic Manager of its own, and may have an
Operational Manager if deemed appropriate. His responsibilities to the Gentoo
Documentation Project (GDP) are listed in the <e>Manager responsibilities</e>
section of the <uri
link="/doc/en/management-structure.xml#doc_chap1_sect5">Gentoo Management
Structure</uri> document.
</p>
<p>
Every subproject of the Gentoo Documentation Team is listed on the
<uri link="/proj/en/gdp/">GDP Webpage</uri>, along with their respective
Strategic Managers.
</p>
<p>
The decision on adding a subproject is in the hands of the Strategic Manager.
</p>
</body>
</section>
<section>
<title>Documentation Project Team Members</title>
<body>
<p>
Every member of the Gentoo Documentation Project must be subscribed to
the <mail link="[EMAIL PROTECTED]">[email protected]</mail>
mailing list. This mailing list will be used to discuss all
documentation-related issues. This mailing list is open to all interested
parties, developer or not.
</p>
<p>
Every member of the Gentoo Documentation Project must be part of the
<mail link="[EMAIL PROTECTED]">[EMAIL PROTECTED]</mail> alias. This
alias is <e>only</e> used by <uri
link="http://bugs.gentoo.org";>bugs.gentoo.org</uri> to inform the documentation
team about bugs regarding the Gentoo Documentation. You can add yourself by
editing <path>/var/mail/alias/misc/docs-team</path> on dev.gentoo.org.
</p>
<p>
Members of the Gentoo Documentation Team should be available at
<c>#gentoo-doc</c> on <uri link="http://www.freenode.net";>irc.freenode.net</uri>
whenever they are online.
</p>
<p>
Depending on the assignment or responsibilities, a member may have limited CVS
access to <c>cvs.gentoo.org</c>. Full CVS access is restricted to Gentoo
Developers. Read-only CVS access may be granted to recruits.
</p>
</body>
</section>
<section>
<title>Documentation Translation Teams</title>
<body>
<p>
Every language should be backed up by an official Translation Team. This
team is led by a <e>Lead Translator</e> and perhaps a <e>Follow-On Lead
Translator</e>, who both have CVS commit access. If for any reason the
<e>Lead Translator</e> cannot perform his duties, the <e>Follow-On Lead
Translator</e> is in charge. If the <e>Follow-On</e> is unavailable, the
mentor(s) is/are in charge of the language.
</p>
<p>
If a translated document for an unsupported language is contributed, the Gentoo
Documentation Team will not publish it officially. Such documents shall not be
linked to the website until an official Translation Team of that language is
formed.
</p>
<p>
When a language is officially supported, but the team does not have any
members willing to take on the responsibilities of the <e>Lead
Translator</e>, all links to the documents will be removed from the site.
However, the documents will stay available in case the language becomes
officially supported again.
</p>
<p>
1.1
gentoo-projects/www-redesign/htdocs/proj/en/gdp/doc/doc-quiz.xml
file :
http://www.gentoo.org/cgi-bin/viewcvs.cgi/gentoo-projects/www-redesign/htdocs/proj/en/gdp/doc/doc-quiz.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain:
http://www.gentoo.org/cgi-bin/viewcvs.cgi/gentoo-projects/www-redesign/htdocs/proj/en/gdp/doc/doc-quiz.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo
Index: doc-quiz.xml
===================================================================
<?xml version='1.0' encoding="UTF-8"?>
<!-- $Header:
/var/cvsroot/gentoo-projects/www-redesign/htdocs/proj/en/gdp/doc/doc-quiz.xml,v
1.1 2005/07/05 10:31:45 swift Exp $ -->
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<guide link="/proj/en/gdp/doc/doc-quiz.xml">
<title>Gentoo Linux Documentation Quiz</title>
<author title="Author">
<mail link="[EMAIL PROTECTED]">Sven Vermeulen</mail>
</author>
<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.0 -->
<abstract>
This document contains the Documentation Project Quiz, a collection of questions
pertaining to documentation development which need to be answered correctly
before a developer can be given CVS access to the Gentoo Documentation
Repository.
</abstract>
<license/>
<version>1.2</version>
<date>2005-05-17</date>
<chapter>
<title>Gentoo Documentation Project Quiz</title>
<section>
<title>GuideXML Format</title>
<body>
<p>
What is the <c><version></c> element used for?
</p>
<p>
What license does a Gentoo Document use when the <c><license></c>
element is set?
</p>
<p>
Where is the content of the <c><abstract></c> element placed on the
Gentoo website for a particular guide? And for the Gentoo Handbook?
</p>
<p>
Give the recommended format that you would use for "February 17th, 2005" inside
<c><date></c>. What is the benefit for this format?
</p>
<p>
What are the differences between an English document and a translated document
XML-wise (not taking into account <path>metadoc.xml</path>)?
</p>
<p>
Suppose you have a document on the differences between distributions. The
document has the following chapters and sections. How would you create a link
to the section <e>Availability</e>?
</p>
<pre caption="Document layout">
Chapter: What is a Distribution?
Chapter: What are the Differences?
Section: Optimization
Section: Availability
Section: Software Choices
Section: Internationalisation
Section: Software Maintenance
Section: Branding
Section: Installation
Section: System Configuration
Chapter: What is Gentoo?
Chapter: Gentoo's Advantages
</pre>
<p>
What is wrong with the following code snippet of a Gentoo Handbook main file
which covers "Gentoo Security" in German? Why do you make the changes you made?
</p>
<pre caption="Excerpt of a handbook main page">
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<book lang="de">
<title>Gentoo Sicherheit</title>
</pre>
<p>
What is the result of using the <c>lang</c> attribute?
</p>
<p>
What is a valid GuideXML file and how do you check for validity?
</p>
</body>
</section>
<section>
<title>Coding Style</title>
<body>
<p>
Please download the following <uri link="fix-me.xml.txt?passthru=1">GuideXML
document</uri> that does not validate GuideXML correctly and also isn't written
using the Coding Style. Reformat the code so it adheres to the Gentoo
Documentation Coding Style and GuideXML format.
</p>
</body>
</section>
<section>
<title>Commit Policy</title>
<body>
<p>
A new document is submitted through bugzilla. You have succesfully reviewed the
document but have not found any issues. What is the procedure for adding it to
CVS (give commands and the actions you perform)?
</p>
<p>
A patch for "KaBooZa Guide" has been submitted to bugzilla and you have decided
to take care of it even though you know nothing about KaBooZa. How do you
proceed?
</p>
<p>
Someone notices a grammar issue on one of Gentoo's pages and reports it on IRC.
What do you do if the page is one that you can correct (you have access and you
understand the language)? What if you can't correct it?
</p>
</body>
</section>
</chapter>
</guide>
1.1
gentoo-projects/www-redesign/htdocs/proj/en/gdp/doc/doc-tipsntricks.xml
file :
http://www.gentoo.org/cgi-bin/viewcvs.cgi/gentoo-projects/www-redesign/htdocs/proj/en/gdp/doc/doc-tipsntricks.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain:
http://www.gentoo.org/cgi-bin/viewcvs.cgi/gentoo-projects/www-redesign/htdocs/proj/en/gdp/doc/doc-tipsntricks.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo
Index: doc-tipsntricks.xml
===================================================================
<?xml version='1.0' encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header:
/var/cvsroot/gentoo-projects/www-redesign/htdocs/proj/en/gdp/doc/doc-tipsntricks.xml,v
1.1 2005/07/05 10:31:45 swift Exp $ -->
<guide link="doc-tipsntricks.xml">
<title>Documentation Development Tips & Tricks</title>
<author title="Author">
<mail link="[EMAIL PROTECTED]">Sven Vermeulen</mail>
</author>
<author title="Editor">
<mail link="[EMAIL PROTECTED]">Xavier Neys</mail>
</author>
<abstract>
Some tips & tricks that make the life for a Gentoo Documentation Developer
easier (or more miserable :)
</abstract>
<license/>
<version>0.15</version>
<date>2005-04-08</date>
<chapter>
<title>Setting up your local environment</title>
<section>
<title>Local environment for contributors</title>
<body>
<p>
Create a dedicated directory for the sole purpose of developing documentation.
As an example we take <path>~/work/gentoo/doc</path>. Inside this directory,
create a subdirectory in which you will keep the (up to date) English
documentation (for instance, <path>en/</path>).
</p>
<p>
Download the tarball with the most recent English documentation:
</p>
<pre caption="Downloading the English documentation">
# <i>wget http://www.gentoo.org/dyn/doc-snapshots/docs-latest-en.tar.bz2</i>
</pre>
<p>
Unpack the documentation in the <path>en/</path> directory. You now have an
up to date snapshot of the English documentation. Every time you want to update
your snapshot, you can download the tarball again, but you can also surf to the
document and add <path>?passthru=1</path> to the URL. For instance:
</p>
<pre caption="Updating an English document">
# <i>wget http://www.gentoo.org/doc/en/alsa-guide.xml?passthru=1 -O
alsa-guide.xml</i>
</pre>
<p>
In case you want to help translating documents, create a directory for your
language in which you keep the at that time current translations:
</p>
<pre caption="Downloading the snapshot for your language">
# <i>mkdir </i><comment>${LANG}</comment>
# <i>cd </i><comment>${LANG}</comment>
# <i>wget
http://www.gentoo.org/dyn/doc-snapshots/docs-latest-</i><comment>${LANG}</comment><i>.tar.bz2</i>
# <i>tar xvjf docs-latest-*.tar.bz2</i>
</pre>
<p>
When you update a document, always copy your document from
<path>${LANG}/</path> to the root dir (<path>~/work/gentoo/doc</path>) first,
then adjust the copied version. You need to keep the original one to create a
patch:
</p>
<pre caption="Creating a patch for an update">
# <i>diff -uNt </i><comment>${LANG}</comment><i>/alsa-guide.xml
alsa-guide.xml</i> > alsa-guide.diff
</pre>
</body>
</section>
<section>
<title>Online CVS Repository</title>
<body>
<p>
You can request our <uri link="/cgi-bin/viewcvs.cgi">Online CVS
Repository</uri> to provide the differences between individual versions. The
main English repository is <uri
link="/cgi-bin/viewcvs.cgi/en/?root=doc&sortby=date">fully
available</uri>. Also, the online CVS repository is updated every hour.
</p>
</body>
</section>
<section>
<title>Local repository for developers</title>
<body>
<p>
Create a working directory dedicated to Gentoo; for instance
<path>~/work/gentoo/doc</path>. Then create a subdir called <path>cvs/</path>
in which you will place the CVS snapshot:
</p>
<pre caption="Getting the CVS snapshot">
# <i>mkdir cvs; cd cvs/</i>
# <i>export CVSROOT=</i><comment><your
nick></comment><i>@cvs.gentoo.org:/var/cvsroot</i>
# <i>cvs co doc</i>
</pre>
<p>
To update the CVS snapshot, run <c>cvs update -dP</c> in the
<path>cvs/doc</path> directory.
</p>
</body>
</section>
</chapter>
<chapter>
<title>Testing GuideXML</title>
<section>
<title>Testing Environment</title>
<body>
<p>
First create a <path>test/</path> directory in which you place the
<path>guide.xsl</path>, <path>main.css</path> and some images:
</p>
<pre caption="Creating the test environment">
# <i>mkdir test</i>
# <i>cd test</i>
# <i>mkdir css images</i>
# <i>wget -P css/ http://www.gentoo.org/css/main.css</i>
# <i>wget -P images/ http://www.gentoo.org/images/gbot-s.gif \
http://www.gentoo.org/images/gridtest.gif \
http://www.gentoo.org/images/gtop-s.jpg \
http://www.gentoo.org/images/line.gif \
http://www.gentoo.org/images/netraverse-gentoo.gif</i>
</pre>
<p>
Now download a special version of <path>guide.xsl</path> available on <uri
link="http://dev.gentoo.org/~swift/gentoo/downloads/guide.xsl";>SwifT's
webspace</uri>. This version is adapted to transform GuideXML to HTML on
local systems.
</p>
<pre caption="Downloading guide.xsl">
# <i>wget http://dev.gentoo.org/~swift/gentoo/downloads/guide.xsl</i>
</pre>
<p>
Finally, edit <path>/etc/xml/catalog</path> and add the following line:
</p>
<pre caption="/etc/xml/catalog addendum">
<rewriteURI uriStartString="/dtd"
rewritePrefix="<i>/usr/portage/metadata/dtd/</i>"/>
</pre>
</body>
</section>
<section>
<title>Test a Gentoo Guide</title>
<body>
<p>
To test a Gentoo Guide, first check if it uses correct XML:
</p>
<pre caption="Using xmllint to verify guides">
# <i>xmllint --valid --noout alsa-guide.xml</i>
</pre>
<p>
If <c>xmllint</c> returns without showing anything, then the file is
error-free (or at least concerning XML-tags). Next you need to convert it to
HTML. <c>xsltproc</c> is the tool needed for that:
</p>
<pre caption="Converting to HTML">
# <i>xsltproc --novalid test/guide.xsl alsa-guide.xml >
test/alsa-guide.html</i>
</pre>
<p>
If no errors are displayed, you should be able to point your browser to
<uri>file:///home/user/work/gentoo/doc/test/alsa-guide.html</uri> to view the
resulting document. If not, fix your guide until it works.
</p>
</body>
</section>
<section>
<title>Test the Gentoo Handbook</title>
<body>
<p>
The Gentoo Handbook is divided in chapters. To process a certain chapter, you
1.1
gentoo-projects/www-redesign/htdocs/proj/en/gdp/doc/metadoc-guide.xml
file :
http://www.gentoo.org/cgi-bin/viewcvs.cgi/gentoo-projects/www-redesign/htdocs/proj/en/gdp/doc/metadoc-guide.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain:
http://www.gentoo.org/cgi-bin/viewcvs.cgi/gentoo-projects/www-redesign/htdocs/proj/en/gdp/doc/metadoc-guide.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo
Index: metadoc-guide.xml
===================================================================
<?xml version='1.0' encoding='UTF-8'?>
<!-- $Header:
/var/cvsroot/gentoo-projects/www-redesign/htdocs/proj/en/gdp/doc/metadoc-guide.xml,v
1.1 2005/07/05 10:31:45 swift Exp $ -->
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<guide link="metadoc-guide.xml">
<title>Gentoo Metadoc XML Guide</title>
<author title="Author">
<mail link="[EMAIL PROTECTED]">Sven Vermeulen</mail>
</author>
<author title="Editor">
<mail link="[EMAIL PROTECTED]">Xavier Neys</mail>
</author>
<abstract>
This guide informs developers how to use the Metadoc XML format that allows the
Gentoo Documentation Project to keep its documentation in a hierarchical manner
and allow more information to be stored about each document.
</abstract>
<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.0 -->
<license/>
<version>1.2</version>
<date>2005-04-04</date>
<chapter>
<title>Introduction</title>
<section>
<title>Why is MetadocXML Needed?</title>
<body>
<p>
MetadocXML is not needed, it's an additional resource for the Gentoo
Documentation Project to keep track of documents, even if they are located
outside of the normal <path>[gentoo]/xml/htdocs/doc</path> scope.
</p>
<p>
Thanks to MetadocXML, we can now
</p>
<ul>
<li>
track documents that are located inside project webspace
(<path>/proj</path>) instead of the usual documentation repository
(<path>/doc</path>)
</li>
<li>
categorize documentation into various categories (or subcategories) with the
additional benefit that we can now automatically generate the documentation
index (and more)
</li>
<li>
track non-official documentation team members (such as translators)
</li>
<li>
use parts of big documents (Handbooks) as individual guides on certain
topics
</li>
<li>
assign bugs to particular documents for quick reference and with the
possibility of masking out a document in case of a major showstopping bug
</li>
<li>
primitively check if a translated file is in sync with it's English
counterpart or not
</li>
</ul>
<p>
Note that the last advantage is primitive and will probably not be extended.
There are more powerful tools (such as Xavier's <uri
link="http://dev.gentoo.org/~neysx/trads/trads-doc.html";>trads-doc</uri> script)
that has many more features than this.
</p>
<p>
Translation teams that do not use MetadocXML yet don't need to worry - they will
not lose any current functionality as it only builds upon the existing
infrastructure - there are no changes to the GuideXML format that need
MetadocXML.
</p>
</body>
</section>
<section>
<title>How does MetadocXML Work?</title>
<body>
<p>
There is one central file in which all meta information on the documentation is
maintained. We call this file <path>metadoc.xml</path>. This file should be
located inside your main repository (<path>/doc/${LANGUAGE}</path>) although
this is not hard-coded.
</p>
<p>
Inside this file, all meta information is stored:
</p>
<ul>
<li>Members of the team</li>
<li>Categories in which documents participate</li>
<li>Files that are covered</li>
<li>Documents that are covered</li>
<li>Bugs that are part of a document</li>
</ul>
<p>
Next to <path>metadoc.xml</path>, one also can have a dynamically generated
index
file (usually called <path>index.xml</path>), an overview listing of all
documentation (usually called <path>list.xml</path>) and an overview listing of
all members, files and bugs (usually called <path>overview.xml</path>).
</p>
</body>
</section>
</chapter>
<chapter>
<title>The metadoc.xml File</title>
<section>
<title>XML Structure</title>
<body>
<p>
The <path>metadoc.xml</path> file is started with the usual XML initialisation
code and Gentoo CVS header information:
</p>
<pre caption="XML Initialisation">
<?xml version='1.0' encoding="UTF-8"?>
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/metadoc.xml,v 1.25
2004/12/23 09:51:30 swift Exp $ -->
<!DOCTYPE metadoc SYSTEM "/dtd/metadoc.dtd">
</pre>
<p>
Then, one starts with the MetadocXML declaration.
</p>
<pre caption="English MetadocXML declaration">
<metadoc lang="<comment>en</comment>">
</pre>
<p>
Translators should reference the main <path>/doc/en/metadoc.xml</path> in the
<c>parent</c> attribute. This lets metadoc identify untranslated files and find
out whether versions of translated versions and originals still match.
</p>
<pre caption="Translated MetadocXML declaration">
<metadoc lang="<comment>language code</comment>"
parent="/doc/en/metadoc.xml">
</pre>
<p>
Beneath the <c>metadoc</c> entity, the following entities should be declared (in
the given order):
</p>
<ul>
<li>
<c>version</c> to help keep track of changes
</li>
<li>
<c>members</c> which declares all members of the given language team
</li>
<li>
<c>categories</c> which declares the possible categories used
</li>
<li>
<c>files</c> which contains all files covered by the Metadoc file
</li>
<li>
<c>docs</c> which contains all documents covered by the Metadoc file
</li>
</ul>
</body>
</section>
<section>
<title>The Version Entity</title>
<body>
<p>
The version number should be increased when a document or a file is added or
removed, when a path is changed or on any update that might have an impact on
translated versions.
</p>
</body>
</section>
<section>
<title>The Members Entity</title>
<body>
1.1
gentoo-projects/www-redesign/htdocs/proj/en/gdp/doc/translators-howto.xml
file :
http://www.gentoo.org/cgi-bin/viewcvs.cgi/gentoo-projects/www-redesign/htdocs/proj/en/gdp/doc/translators-howto.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain:
http://www.gentoo.org/cgi-bin/viewcvs.cgi/gentoo-projects/www-redesign/htdocs/proj/en/gdp/doc/translators-howto.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo
Index: translators-howto.xml
===================================================================
<?xml version='1.0' encoding="UTF-8"?>
<!-- $Header:
/var/cvsroot/gentoo-projects/www-redesign/htdocs/proj/en/gdp/doc/translators-howto.xml,v
1.1 2005/07/05 10:31:45 swift Exp $ -->
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<guide link="translators-howto.xml">
<title>Translators Howto for Gentoo Documentation</title>
<author title="Author">
<mail link="[EMAIL PROTECTED]">Sven Vermeulen</mail>
</author>
<abstract>
A frequently asked question is how to become a translator and what actions
should be performed both to become one and to act as one. This document tries to
explain all this.
</abstract>
<license/>
<version>0.16</version>
<date>2005-06-01</date>
<chapter>
<title>Introduction</title>
<section>
<title>What does this document explain?</title>
<body>
<p>
Frequently, people are interested in joining the Gentoo translation teams and
contributing to the translation efforts. However, few of them know what a
translator does, needs to know and how translations are handled. This howto
should answer most questions, and if you still have some questions left, contact
<mail link="[EMAIL PROTECTED]">Xavier Neys</mail> or <mail
link="[EMAIL PROTECTED]">Sven Vermeulen</mail>.
</p>
</body>
</section>
</chapter>
<chapter>
<title>Situation</title>
<section>
<title>Structure</title>
<body>
<p>
The <uri link="/proj/en/gdp/">Gentoo Documentation Project</uri> has a separate
<uri link="/proj/en/gdp/international.xml">Internationalisation Project</uri>
which involves all translation efforts. This subproject is lead by <mail
link="[EMAIL PROTECTED]">Xavier Neys</mail> and embraces all translation
teams.
</p>
<p>
Every translation team is lead by a <e>Lead Translator</e>. This person is
responsible for all the translations created by the translation team. You can
find the <e>Lead Translator</e> for your language on the <uri
link="/proj/en/gdp/international.xml">Internationalisation Project Page</uri>.
</p>
<p>
In case the <e>Lead Translator</e> is off (vacation, exams, network connectivity
issues, ...) the <e>Translator Follow-Up</e> takes over his job. Both the
<e>Lead Translator</e> and <e>Follow-Up Lead Translator</e> are Gentoo
Developers and should act like one.
</p>
</body>
</section>
<section id="trans_situation">
<title>Lead Translator and Translator Follow-Up</title>
<body>
<p>
The <e>Lead Translator</e> acts as the translation lead, his successor is the
<e>Translator Follow-Up</e>. Both developers must be acquainted
with the following important documents:
</p>
<ul>
<li>
<uri link="/proj/en/devrel/handbook/handbook.xml?part=3&chap=1">Gentoo
Ebuild Policy</uri>:
Although this document is most important for Ebuild-writers, the <e>Lead
Translator</e> and <e>Translator Follow-Up</e> must understand this
document. As Gentoo Developers they are supposed to be able to answer the
common questions about Gentoo that are discussed in this document (such as
QA and masked packages).
</li>
<li>
<uri link="/proj/en/gdp/doc/doc-policy.xml">Gentoo Documentation
Policy</uri>: Every Gentoo Documentation Developer, including the <e>Lead
Translator</e> and <e>Translator Follow-Up</e> must read and learn this
policy by heart. It lists all guidelines regarding documentation
development. Not adhering to this policy may lead to sanctions.
</li>
<li>
<uri link="/doc/en/xml-guide.xml">Gentoo Linux XML Guide</uri>: All Gentoo
Documentation is written in GuideXML, an easy-to-learn and easy-to-write
format that allows us to easily convert the documentation to any format
using XSLT. This document explains how GuideXML is structured <e>and</e>
discloses the Coding Style used in the Gentoo Documentation Project.
</li>
</ul>
<p>
The <e>Lead Translator</e> has CVS commit access to the documentation tree in
Gentoo's CVS repository. The <e>Lead Translator</e> and his <e>Follow-Up</e>
are allowed to add and update translations on the website. He is responsible
for the translations on the website and for their accuracy. Failing to
correctly review the translations (resulting in wrong instructions in our
translated guides that don't exist in the English versions) is a serious error.
</p>
</body>
</section>
<section>
<title>Translation Teams</title>
<body>
<p>
Every translation team is free to organise their translation efforts as they see
fit. If a team requires a common mailinglist, they can contact <mail
link="[EMAIL PROTECTED]">Sven Vermeulen</mail> to setup a translation-specific
mailinglist for their language ([EMAIL PROTECTED]).
</p>
<p>
Unlike the <e>Lead Translator</e> and <e>Translator Follow-Up</e>, the members
of the translation team have no CVS access nor Gentoo Developer status. They do
not have to adhere to the restrictions of the Gentoo Developer as listed above.
It is up to the <e>Lead Translator</e> to provide the translation team members
with the necessary information. However, <uri
link="/proj/en/gdp/doc/doc-tipsntricks.xml">tips and tricks</uri> are available
that can be of help for the translation efforts.
</p>
<p>
Translators will probably want to subscribe to our <mail
link="[email protected]">CVS mailing list</mail>. Whenever a Gentoo
developer commits a new English version of a document, a message is mailed to
this list. The mail contains the list of committed files and a diff of modified
files. Check our <uri link="/main/en/lists.xml">mailing lists page</uri> to
learn how to subscribe to our lists.
</p>
<p>
Translation teams can opt to use the <uri
link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file for their
language. This file also allows translation team members to be listed on the
website when the overview page functionality is used.
</p>
</body>
</section>
</chapter>
<chapter>
<title>Requirements</title>
<section id="trans_req">
<title>Translation Accuracy</title>
<body>
<p>
Translations available on the Gentoo website must be as accurate as possible.
The installation instructions (<uri
link="/doc/en/handbook/handbook-x86.xml?part=1">Part I</uri> of the <uri
link="/doc/en/handbook/index.xml">Gentoo Handbook</uri>) are the most important
instructions and have absolute priority over all other documents. They may not
lag <e>more than three days</e> behind on the English document in case of
<b>important</b> updates (which will be announced on <mail
link="[email protected]">[email protected]</mail> by the <e>Operational
Manager</e> with "Important" in the subject. Less important updates are not
announced; in this case the documentation must be <e>accurate to two weeks</e>.
</p>
<p>
Operational documents (listed below) have the second highest priority. Their
translations may not lag <e>more than two weeks</e> behind on the English
document in case of <b>important</b> updates (which will be announced on <mail
link="[email protected]">[email protected]</mail> by the <e>Operational
Manager</e> with "Important" in the subject. Less important updates are not
announced; in this case the documentation must be <e>accurate to three
weeks</e>.
</p>
<p>
Operational documents are:
</p>
<ul>
<li>
<uri link="/doc/en/altinstall.xml">Alternative Installation Guide</uri>
</li>
<li>
<uri link="/doc/en/handbook/handbook-x86.xml?part=2">Part II</uri> of the
<uri link="/doc/en/handbook/index.xml">Gentoo Handbook</uri>
</li>
<li>
--
[email protected] mailing list
