diff options
Diffstat (limited to 'src/documentation/content/xdocs/trans/guidelines.xml')
| -rw-r--r-- | src/documentation/content/xdocs/trans/guidelines.xml | 127 |
1 files changed, 127 insertions, 0 deletions
diff --git a/src/documentation/content/xdocs/trans/guidelines.xml b/src/documentation/content/xdocs/trans/guidelines.xml new file mode 100644 index 0000000000..7af132b9a3 --- /dev/null +++ b/src/documentation/content/xdocs/trans/guidelines.xml @@ -0,0 +1,127 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "./dtd/document-v11.dtd"> + +<document> + <header> + <title>Welcome to POI</title> + <authors> + <person id="AO" name="Andrew C. Oliver" email="acoliver@apache.org"/> + </authors> + </header> + + <body> + <section><title>Purpose</title> + <p>This document hopes to serve as a general introduction and helpful set of + guidelines for translating POI documentation into other languages. We hope + to capture both general information here (such as "how do I test my changes") + as well as language specific guidelines and translation conventions.</p> + </section> + <section><title>Introduction</title> + <p> + POI's XML based documentation is built along side the sources. To build poi's documentation + you run "./build.sh docs" (UNIX/cygwin) or "build docs" (Windows) from the jakarta-poi + directory. This will put the documentation under the build/docs directory, you can navigate + there using your browser generally by typing in the path name or File -> Open new web location + (or some similar wording) + and browsing to the "index.html" file. You may also want to run "./build.sh clean docs" or + "build clean docs" so that all documentation previously built is erased before running the build. + The words "clean" and "docs" are called "targets", from here on out we will refer to them as + "targets" in which case you may assume you type "./build.sh" or "build" before them in order to + execute them. + </p> + <p> + To generate all of teh documentation such as it would appear on the + <link href="http://jakarta.apache.org/poi">POI Website</link> you can execute the "site" target (optionally + preceeded by the "clean" target. + </p> + <p> + The source for POI's XML documentation is in src/documentation/xdocs. To edit one of these files you can use + a standard text editor. Translated documentation is under src/documentation/xdocs/trans/xx, where xx is a + two to three letter country code, in general this should match the internet domain suffix of the country where + that language generally evolved or just be generally recognizable and unique. The directory structure under + src/documentation/trans/xx should match the structure of src/documentation (the English edition) minus the + trans directory. + </p> + <p> + The translated documentation should match the content and meaning of the "master" or English documentation. + All documentation should originate in English (this is for simplicity). While documentation written in other + languages is certainly welcome, it must first be translated (perhaps by posting it to the mail list and + requesting it be translated) into English and applied to the master before being applied to a translation. + </p> + <p> + We prefer you donate translations directly to the <link href="http://jakarta.apache.org/poi">Jakarta POI</link> + project rather than hosting them offsite. We will make every effort to accomidate you as we greatly appreciate your + efforts. However, we understand that sites located within a country are the fastest and most searchable. Therefore, + we recommend and welcome folks mirroring the POI site and making the translated page the home page. You can do this + either via an HTML copy with some <link href="http://httpd.apache.org/info/how-to-mirror.html">appropriate software</link> + or the preferred method of executing the POI build directly. You can contact us via the mail list for both push and + pull options. The same scripts which regenerate the POI website every 2 hours, should work for others. These are not + yet in CVS as they are nasty dirty shell scripts ;-). If you mirror us, tell us so we can link you. (This will help google + associate you strongly with the project) + </p> + <p> + Submitting translations is simple, you follow the same + <link href="http://jakarta.apache.org/poi/getinvolved/index.html">instructions</link> as you would for submitting a code patch. + Remeber to always generate patchs in diff -u format preserving the context relative to the jakarta-poi directory. Also remember + to submit any new files in a directory preserving archive format. Never post these to the list, always use + <link href="http://nagoya.apache.org/bugzilla/buglist.cgi?product=POI&short_desc=%5BPATCH%5D&short_desc_type=allwordssubstr">Bugzilla</link> + and create attachments per the above linked instructions. + </p> + </section> + <section><title>Credits</title> + <p> + Some people feel uncomfortable putting themselves in the <authors> tags at the top of the documentation as they feel that + translation does not give them the right to claim authorship. Please don't feel this way, please add yourself to the authors + tags. It can be assumed that authors on the master documentation are all content creators and any additional authors listed + on the translation that are not on the master document are translators of the documentation. You authored the xx language + version of the document and should freely add yourself there. Additionally, please supply a patch to the + <link href="../who.html">Who We Are</link> page noting you as a developer once you've submitted a few translation patches. You deserve + credit and it helps the project to give you credit. Remember documentation is on par with code contribution. + </p> + </section> + <section><title>Starting a new translation</title> + <p> + To start a translation for a language not already in existance you must create a directory under src/documentation/xdocs/trans with a + two or three letter designation of the country where the language originated. (For example es = Spanish, de = German) + Copy the book.xml and index.xml file from src/documentation/xdocs directory into the src/documentation/xdocs/trans/xx directory. + Change all paths in the book.xml and index.xml to match the relative location of the English version. For example if there is a + link in index.html that references ./poifs/index.html, you'd change that to ../../poifs/index.html (up 2 directories from trans/xx). + Create a link from the book.xml file in the src/documentation/trans directory (this is necessary or the build will ignore your + documentation) similar to the other languages. + Run the clean target followed by the docs target. If the build is successful, congradulations! If it fails, you probably got one of + the relative paths incorrect! Go fix it (the first error message generally contains the most useful information). If you need help + post to the poi-dev list and ask for it (send the output from the build). + </p> + <p> + So now you have a directory with a copy of the index from the master documentation...so what? Well now translate book.xml and index.xml. + Try to build again. It probably won't work. Why? The encoding. At the top of every file there is an encoding="UTF-8" (in general). + This encoding will work for many Western European languages, but not for others, or will require some nasty escape sequencing. This is + where trial and error + guess work come in. This <link + href="http://www.ibiblio.org/xml/books/xmljava/chapters/ch03s03.html#encoding_table">Table of encodings</link> may help. There is a + catch. Your encoding should work on a Linux system under Java 1.3.1 and of course with the build in general. If in doubt, ask. + (This is a practical consideration as thats the setup of the machine currently running the nightly/site builds.) + </p> + </section> + <section><title>Need help?</title> + <p> + Andy Oliver is the cofounder of the POI project and one of its most active documentation contributers. Well, Andy used to think he + spoke very clearly until he traveled abroad and discovered his speech was composed almost entirely of coloquialisms. This can make some + of the POI documentation difficult to translate, if in doubt...ask. Its also appropriate to eliminate these from the master documentation + where it makes it clearer. + </p> + </section> + <section><title>Translation Conventions</title> + <p> + In addition to the above practical guidelines we hope to come up with a set of translation guidelines here (or linked from here) for + general use as well as language specific translation guidelines and conventions. We assume that the POI translators will document + them here as they develop. + </p> + </section> + </body> + <footer> + <legal> + Copyright (c) @year@ The Apache Software Foundation All rights reserved. + $Revision$ $Date$ + </legal> + </footer> +</document> |