The POI documentation translation project has begun. The first ones
to start are the Spanish
- (espaniol) and Japanese
+ (espaniol) and Japanese, and
+ German
translations. Others are welcome. Please feel
free to participate!
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 @@
+
+
+
+
+
+ Welcome to POI
+
+
+
+
+
+
+
+
+
+
+ The POI documentation translation project has begun. The first ones
+ to start are the Spanish
+ (espaniol) and Japanese
+ translations. Others are welcome. Please feel
+ free to participate!
+
+
+
+
+ Voting for the POI logo contest is now complete. Thank you for your votes.
+
+
+
+
+
+
+
+
+ The POI project consists of APIs for manipulating various file formats
+ based upon Microsoft's OLE 2 Compound Document format using pure Java.
+
+
+ OLE 2 Compound Document Format based files include most Microsoft Office
+ files such as XLS and DOC.
+
+
+ As a general policy we try to collaborate as much as possible with other projects to
+ provide this functionality. Examples include: Cocoon for
+ which you'll soon find generators and serializers for our projects;
+ Open Office.org with whom we collaborate in documenting the
+ XLS format; and Lucene for which we'll soon have file
+ format interpretors. When practical, we donate components directly to those projects for POI-enabling them.
+
+
+
+ We'll tackle this on a component level. POI refers to the whole project.
+
+
+ So why should you use POIFS or HSSF?
+
+
+ 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!
+
+
+ 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.
+
+
+
+
+
+ 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.
+
+
+ Poi is also a Hawaiian delicacy that Merriam Webster's dictionary 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.
+
+
+ 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.
+
+
+
+
+
+
+
+
+ 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.
+
+
+ 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 the POIFS project page for more information.
+
+
+ HSSF is our port of the Microsoft Excel 97(-2002) file format (BIFF8) to pure Java. It supports read and write
+ capability. Please see the HSSF project page for more information.
+
+
+ HDF is our port of the Microsoft Word 97 file format to pure Java. It supports read and write capability.
+ Please see the HDF project page for more information. This component is
+ in the early stages of design. Jump in!
+
+
+ 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 the HPSF project page for more
+ information.
+
+
+
+
+
+ The HSSF Serializer, which was part of our 1.0 release and last builds on
+ Sourceforge, has been donated to the
+ Cocoon project, and is available starting from version
+ 2.0.2.
+
+
+
+
+ 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!
+
+ 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!
+
+
+
+
+
+
+
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 @@
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+ 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.
+
+
+ To generate all of teh documentation such as it would appear on the
+ POI Website you can execute the "site" target (optionally
+ preceeded by the "clean" target.
+
+
+ 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.
+
+
+ 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.
+
+
+ We prefer you donate translations directly to the Jakarta POI
+ 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 appropriate software
+ 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)
+
+
+ Submitting translations is simple, you follow the same
+ instructions 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
+ Bugzilla
+ and create attachments per the above linked instructions.
+
+
+
+
+ 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
+ Who We Are 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.
+
+
+
+
+ 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).
+
+
+ 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 Table of encodings 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.)
+
+
+
+
+ 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.
+
+
+
+
+ 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.
+
+
+
+
+
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 @@
+
+
+
+