new translations stuff

PR:
Obtained from:
Submitted by:
Reviewed by:


git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@352876 13f79535-47bb-0310-9956-ffa450edef68

7 files changed, 407 insertions, 1 deletions

diff --git a/src/documentation/xdocs/book.xml b/src/documentation/xdocs/book.xml
index da5b268629..789d1b1901 100644
--- a/src/documentation/xdocs/book.xml
+++ b/src/documentation/xdocs/book.xml
@@ -37,6 +37,14 @@
     <menu-item label="References" href="references/index.html"/>  
   </menu>
   
+  <menu label="Tranlsations">
+    <menu-item label="Index" href="trans/index.html"/>
+    <menu-item label="Guidelines" href="trans/guidelines.html"/>
+    <menu-item label="German" href="trans/de/index.html"/>
+    <menu-item label="Spanish" href="trans/es/index.html"/>
+    <menu-item label="Japanese" href="http://www.terra-intl.com/jakarta/poi/"/>
+  </menu>
+  
   <menu label="Code">
     <menu-item label="Source Code" href="http://jakarta.apache.org/poi/javadocs/javasrc/"/>       
     <menu-item label="CVS" href="http://jakarta.apache.org/site/cvsindex.html"/>  
diff --git a/src/documentation/xdocs/index.xml b/src/documentation/xdocs/index.xml
index 83e27a869f..65f682e10c 100644
--- a/src/documentation/xdocs/index.xml
+++ b/src/documentation/xdocs/index.xml
@@ -16,7 +16,8 @@
         <p> 
             The POI documentation translation project has begun.  The first ones 
             to start are the <link href="trans/es/index.html">Spanish 
-            (espaniol)</link> and <link href="http://www.terra-intl.com/jakarta/poi/">Japanese</link>
+            (espaniol)</link> and <link href="http://www.terra-intl.com/jakarta/poi/">Japanese</link>, and 
+            <link href="trans/de/index.html">German</link>
             translations.  Others are welcome.  Please feel 
             free to participate!
         </p>
diff --git a/src/documentation/xdocs/trans/book.xml b/src/documentation/xdocs/trans/book.xml
new file mode 100644
index 0000000000..9eb97892b5
--- /dev/null
+++ b/src/documentation/xdocs/trans/book.xml
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "./dtd/book-cocoon-v10.dtd">
+
+<book software="Poi" 
+      title="POI Documentation Translations" 
+      copyright="@year@ Poi Project"
+      xmlns:xlink="http://www.w3.org/1999/xlink">
+
+  <menu label="Translations">
+    <menu-item label="Main Index" href="../index.html"/>    
+    <menu-item label="Guidelines" href="guidelines.html"/>    
+  </menu>
+
+  <menu label="Languages">
+    <menu-item label="Spanish" href="es/index.html"/>    
+    <menu-item label="German" href="de/index.html"/>    
+    <menu-item label="Japanese" href="http://www.terra-intl.com/jakarta/poi/"/>    
+  </menu>
+
+</book>
diff --git a/src/documentation/xdocs/trans/de/book.xml b/src/documentation/xdocs/trans/de/book.xml
new file mode 100644
index 0000000000..6ad528d049
--- /dev/null
+++ b/src/documentation/xdocs/trans/de/book.xml
@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "./dtd/book-cocoon-v10.dtd">
+
+<book software="Poi" 
+      title="Poi Project Documentation" 
+      copyright="@year@ Poi Project"
+      xmlns:xlink="http://www.w3.org/1999/xlink">
+
+  <menu label="Community">
+    <menu-item label="News" href="../../news.html"/>    
+    <menu-item label="Changes" href="../../changes.html"/> 
+    <menu-item label="To do" href="../../todo.html"/> 
+    <menu-item label="Get Involved" href="../../getinvolved/index.html"/>
+    <menu-item label="Vision" href="../../plan/POI20Vision.html"/>
+    <menu-item label="History and Future" href="../../historyandfuture.html"/>
+    <menu-item label="Who we are" href="../../who.html"/> 
+    <menu-item label="Resolutions" href="../../resolutions/index.html"/>    
+  </menu>
+  
+  <menu label="Marketing">
+    <menu-item label="Case Studies" href="../../casestudies.html"/>
+  </menu>
+
+  <menu label="Project">
+    <menu-item label="Overview" href="../../overview.html"/>
+    <menu-item label="POIFS" href="../../poifs/index.html"/>
+    <menu-item label="HSSF" href="../../hssf/index.html"/>
+    <menu-item label="HDF" href="../../hdf/index.html"/>
+    <menu-item label="HPSF" href="../../hpsf/index.html"/>
+    <menu-item label="POI-Utils" href="../../utils/index.html"/>  
+    <menu-item label="Download" href="http://jakarta.apache.org/builds/jakarta-poi/"/> 
+  </menu>
+  
+  <menu label="Docs">
+    <menu-item label="Javadocs" href="http://jakarta.apache.org/poi/javadocs/"/>  
+    <menu-item label="FAQ" href="../../faq.html"/>
+    <menu-item label="References" href="../../references/index.html"/>  
+  </menu>
+  
+  <menu label="Code">
+    <menu-item label="Source Code" href="http://jakarta.apache.org/poi/javadocs/javasrc/"/>       
+    <menu-item label="CVS" href="http://jakarta.apache.org/site/cvsindex.html"/>  
+    <menu-item label="Top Voted Bugs" href="http://nagoya.apache.org/bugzilla/buglist.cgi?votes=1&amp;product=POI&amp;order=bugs.votes"/>  
+    <menu-item label="Bug Database" href="http://nagoya.apache.org/bugzilla/buglist.cgi?product=POI"/>  
+    <menu-item label="Patches" href="http://nagoya.apache.org/bugzilla/buglist.cgi?product=POI&amp;short_desc=%5BPATCH%5D&amp;short_desc_type=allwordssubstr"/>  
+
+    <menu-item label="Junit Test Results" href="http://jakarta.apache.org/poi/tests/junit/"/>  
+    <menu-item label="Dependency Metrics" href="http://jakarta.apache.org/poi/metrics/jdepend/"/> 
+    <menu-item label="Checkstyle Metrics" href="http://jakarta.apache.org/poi/metrics/checkstyle/"/> 
+  </menu>
+
+</book>
diff --git a/src/documentation/xdocs/trans/de/index.xml b/src/documentation/xdocs/trans/de/index.xml
new file mode 100644
index 0000000000..1130e9beef
--- /dev/null
+++ b/src/documentation/xdocs/trans/de/index.xml
@@ -0,0 +1,152 @@
+<?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"/>
+      <person id="GJS" name="Glen Stampoultzis" email="glens@apache.org"/>
+    </authors>
+  </header>
+
+  <body>
+   <section title="News">
+    <section title="Translations">
+        <p> 
+            The POI documentation translation project has begun.  The first ones 
+            to start are the <link href="../es/index.html">Spanish 
+            (espaniol)</link> and <link href="http://www.terra-intl.com/jakarta/poi/">Japanese</link>
+            translations.  Others are welcome.  Please feel 
+            free to participate!
+        </p>
+    </section>
+    <section title="Logo Contest">
+        <p>
+            Voting for the POI logo contest is now complete.  Thank you for your votes.
+        </p>
+<!--        <p>-->
+<!--            <link href="http://vote.sparklit.com/poll.spark/640946">Click here</link> to see the current results.-->
+<!--        </p>-->
+     </section>
+    </section>
+    <section title="Purpose">
+      <p>
+      The POI project consists of APIs for manipulating various file formats
+      based upon Microsoft's OLE 2 Compound Document format using pure Java.
+      </p>
+      <p>
+      OLE 2 Compound Document Format based files include most Microsoft Office
+      files such as XLS and DOC.
+      </p>
+      <p>
+         As a general policy we try to collaborate as much as possible with other projects to
+         provide this functionality.  Examples include: <link href="http://xml.apache.org/cocoon">Cocoon</link> for
+         which you'll soon find generators and serializers for our projects;
+         <link href="http://www.openoffice.org">Open Office.org</link> with whom we collaborate in documenting the
+         XLS format; and <link href="http://jakarta.apache.org/lucene">Lucene</link> for which we'll soon have file
+         format interpretors.  When practical, we donate components directly to those projects for POI-enabling them.
+      </p>
+      <section title="Why/when would I use POI?">
+        <p>
+ 		We'll tackle this on a component level. POI refers to the whole project.
+        </p>
+        <p>
+		So why should you use POIFS or HSSF?
+        </p>
+        <p>
+		You'd use POIFS if you had a document written in OLE 2 Compound Document Format, probably written using
+		MFC, that you needed to read in Java. Alternatively, you'd use POI to write OLE 2 Compound Document Format
+		if you needed to inter-operate with software running on the Windows platform. We are not just bragging when
+		we say that POIFS is the most complete and correct port of this file format to date!
+        </p>
+        <p>
+		You'd use HSSF if you needed to read or write an XLS (Excel) file using Java. You can also read and modify
+		spreadsheets using this API, although right now writing is more mature.
+        </p>
+      </section>
+
+      <section title="What does POI stand for?">
+        <p>
+		POI stands for Poor Obfuscation Implementation. Why would we name our project such a derogatory name? Well,
+		Microsoft's OLE 2 Compound Document Format is a poorly conceived thing. It is essentially an archive structured
+		much like the old DOS FAT filesystem. Redmond chose, instead of using tar, gzip, zip or arc, to invent their own
+		archive format that does not provide any standard encryption or compression, is not very appendable and is prone
+		to fragmentation.
+        </p>
+      <p>
+		Poi is also a Hawaiian delicacy that <link href="http://www.m-w.com">Merriam Webster's dictionary</link> defines as:
+		"A Hawaiian food of taro root cooked, pounded, and kneaded to a paste and often allowed to ferment." This seemed
+		strangely descriptive of the file format.
+        </p>
+      <p>
+		So if you like acronyms, then POI is an acronym.  If you hate them, then we just used the name of the food for our
+		project.  If you wish to signify your love or hate for acronyms, use POI or Poi to refer to the project respectively.
+      </p>
+      </section>
+
+    </section>
+
+
+    <section title="Components To Date">
+        <section title="Overview">
+	     <p>A common misconception is that POI writes Excel files.  POI is the name of the project.  POI contains several
+             components, one of which, HSSF, writes Excel files.  The following are components of the entire POI project
+             and a brief summary of their purpose.</p>
+        </section>
+        <section title="POIFS (POI Filesystem)">
+             <p>POIFS is the oldest and most stable part of the project.  It is our port of the OLE 2 Compound Document Format to
+             pure Java.  It supports both read and write functionality.  All of our components ultimately rely on it by
+             definition.  Please see <link href="../../poifs/index.html">the POIFS project page</link> for more information.</p>
+        </section>
+        <section title="HSSF (Horrible Spreadsheet Format)">
+             <p>HSSF is our port of the Microsoft Excel 97(-2002) file format (BIFF8) to pure Java.  It supports read and write
+             capability.  Please see <link href="../../hssf/index.html">the HSSF project page</link> for more information.</p>
+        </section>
+        <section title="HDF (Horrible Document Format)">
+             <p>HDF is our port of the Microsoft Word 97 file format to pure Java.  It supports read and write capability.
+             Please see <link href="../../hdf/index.html">the HDF project page for more information</link>.  This component is
+             in the early stages of design.  Jump in!</p>
+        </section>
+        <section title="HPSF (Horrible Property Set Format)">
+	<p>HPSF is our port of the OLE 2 property set format to pure
+	  Java. Property sets are mostly use to store a document's properties
+	  (title, author, date of last modification etc.), but they can be used
+	  for application-specific purposes as well. Currently HPSF supports
+	  read functionality only. Please see <link
+	    href="../../hpsf/index.html">the HPSF project page</link> for more
+	  information.</p>
+        </section>
+
+     </section>
+
+    <section title="What happened to the HSSF Serializer?">
+	<p>The HSSF Serializer, which was part of our 1.0 release and last builds on
+        <link href="http://www.sourceforge.net/projects/poi">Sourceforge</link>, has been donated to the
+        <link href="http://xml.apache.org/cocoon/">Cocoon</link> project, and is available starting from version
+        2.0.2.</p>
+    </section>
+
+    <section title="Contributing ">
+        <p>
+		So you'd like to contribute to the project? Great! We need enthusiastic, hard-working, talented folks to help
+		us on the project in several areas. The first is bug reports and feature requests! The second is documentation -
+		we'll be at your every beck and call if you've got a critique or you'd like to contribute or otherwise improve
+		the documentation. We could especially use some help documenting the HSSF file format! Last, but not least, we
+		could use some binary crunching Java coders to chew through the convolution that characterizes Microsoft's file
+		formats and help us port new ones to a superior Java platform!
+        </p>
+        <p>So if you're motivated, ready, and have the time, join the mail lists and we'll be happy to help you get started on the
+           project!
+        </p>
+
+
+    </section>
+  </body>
+  <footer>
+    <legal>
+      Copyright (c) @year@ The Apache Software Foundation All rights reserved.
+      $Revision$ $Date$
+    </legal>
+  </footer>
+</document>
diff --git a/src/documentation/xdocs/trans/guidelines.xml b/src/documentation/xdocs/trans/guidelines.xml
new file mode 100644
index 0000000000..61ab1cf1fd
--- /dev/null
+++ b/src/documentation/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">
+      <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">
+     <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 -&gt; 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&amp;short_desc=%5BPATCH%5D&amp;short_desc_type=allwordssubstr">Bugzilla</link>
+       and create attachments per the above linked instructions.
+     </p>
+   </section>
+   <section title="Credits">
+     <p>
+       Some people feel uncomfortable putting themselves in the &lt;authors&gt; 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">
+      <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?">
+      <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">
+      <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>
diff --git a/src/documentation/xdocs/trans/index.xml b/src/documentation/xdocs/trans/index.xml
new file mode 100644
index 0000000000..200067493b
--- /dev/null
+++ b/src/documentation/xdocs/trans/index.xml
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "./dtd/document-v11.dtd">
+
+<document>
+  <header>
+    <title>POI Documentation Translations</title>
+    <authors>
+      <person id="AO" name="Andrew C. Oliver" email="acoliver@apache.org"/>
+    </authors>
+  </header>
+
+  <body>
+   <section title="Introduction">
+      <p>
+        The POI project has always had a very international following.  In fact even today POI is 
+        more popular in Europe than in the US where the original founders reside.  Today POI is 
+        developed by people from all over the world including India, Austrailia, Japan, and Russia. 
+        We recognize and welcome our geographically and culturally diverse users and contributors and
+        wish to accomidate you as best as we can.  
+      </p>
+      <p>
+        Documentation has always been a cornerstone to POI's success.  No matter how fluent one is in 
+        a second language, it is always easier to comprehend concepts explained in one's native language,
+        therefore, we encourage volunteers to come and help us translate the documentation into other 
+        languages.  Below is a list of the translations that are currently in progress and their status.
+      </p>
+   </section>
+   <section title="Languages">
+      <table>
+        <tr><td>xx</td><td>Language</td><td>Status</td><td>On/Offsite</td><td>Link</td></tr>
+        <tr><td>de</td><td>German</td><td>Just beginning (help!)</td><td>On</td>
+            <td><link href="de/index.html">link</link></td></tr>
+        <tr><td>es</td><td>Spanish</td><td>Index page, some auxiliary pages translated</td><td>On</td>
+            <td><link href="es/index.html">link</link></td></tr>
+        <tr><td>jp</td><td>Japanese</td><td>Complete XML translation, a few releases old</td><td>Off</td>
+            <td><link href="http://www.terra-intl.com/jakarta/poi/">link</link></td></tr>
+      </table>
+   </section>
+  </body>
+  <footer>
+    <legal>
+      Copyright (c) @year@ The Apache Software Foundation All rights reserved.
+      $Revision$ $Date$
+    </legal>
+  </footer>
+</document>