Welcome to POI

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 @@

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 @@ + + + + + + + + + + + + + + + + + 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 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 @@ + + + + +

+ 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 @@ + + + + +

+ Welcome to POI + + + +

+ + +

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 @@ + + + + +

+ POI Documentation Translations + + + +

+ + +

+ 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. +

+ 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. +

+ + + + + + + + +

xx	Language	Status	On/Offsite	Link
de	German	Just beginning (help!)	On	link
es	Spanish	Index page, some auxiliary pages translated	On	link
jp	Japanese	Complete XML translation, a few releases old	Off	link

+ + + -- 2.39.5