Strictly speaking, someone is able to load a document alone with the ODF Package API. The base class of ODF XML document is part of the package layer. I also have improved the ODF 1.2 part3 spec during my work in the TC that it is clear that even a package has documents. In technical terms a document is adequate to a directory with a MIME type.
I interpreted his request to merge Simple API and ODFDOM by the request to merge Simple API and ODFDOM DOC API. Svante On 01.03.2012 10:43, Devin Han wrote: > Answer your question “Who is claiming that those API are in general not > required?” > > see comments from Jeremias Maerki： > > Hi Devin, > > just my 0.05CHF: > > .... Some may not even need Simple at all. ..... > > I drafted this proposal, just hope ODFDOM users still have an easy way to > load ODF Document. > Keep class OdfDocument is a way, but that will lead to code duplicated. As > you know, Simple API also has class Document, which is very similar with > OdfDocument. > So, ODFDOM uses Simple API to load document is the best way. That means > ODFDOM depends on Simple API, while Simple API depends on ODFDOM. Why not > put them together? > > 2012/2/29 Svante Schubert <[email protected]> > >> We all agreed on deprecating the DOC API and continuing the Simple API >> as both APIs are redundant to each other. >> Before we remove the DOC API, we should be certain that we are not >> removing a feature super set that is already being in use of developers. >> Ashok announced yesterday to migrate, let us get feed-back from him >> before deletion. In addition no DOC functionality (as the DOC tests) >> should not be thrown away, but be moved to the Simple API. >> >> More comments inline... >> >> On 29.02.2012 07:20, Devin Han wrote: >>> Hi all, >>> >>> I keep silence because I am waiting for the comments from somebody who >> have >>> dived into the ODFDOM and Simple API source code. Unfortunately, >> nobody... >>> Before read the following mail, please open this link: >>> http://incubator.apache.org/odftoolkit/odfdom/Layers.html >>> It describes the layers of ODFDOM. ODF Document API is what we want to >>> remove and replaced by Simple API. >> Not exactly nobody, 'cause I wrote the above documentation. (Changed is >> only the background-color of the code examples, but be careful. The new >> color might be an accessibility issue - see >> http://www.accesskeys.org/tools/color-contrast.html) >> <http://www.accesskeys.org/tools/color-contrast.html> >>> What does the ODF Document API include? The right answer is that all of >> the >>> classes in package "org.odftoolkit.odfdom.doc" and >>> "org.odftoolkit.odfdom.incubator". >>> What does it mean? That means not only Table API will be moved, but also >>> OdfDocument, OdfTextDocument, OdfSpreadsheetDocument and etc. Does >> people, >>> who said you didn't use ODFDOM Doc API or Simple API, can tell me how can >>> you load an ODF document after the movement? You even can't use any dom >>> element or attribute, because there is only an API support to load >> document >>> as OdfPackageDocument. OdfPackageDocument knows nothing about dom element >>> and attribute! >>> >>> You may say, I can realize a loadDocument method in OdfSchemaDocument. >> Yes, >>> that can resolve the problem that how to use dom element and attribute. >> But >>> you still don't know whether this document is a text document or a >>> spreadsheet document. >>> >>> What I want to explain are 4 points: >>> (1) All of us enjoy the convenience of ODFDOM Doc API or Simple API, but >>> somebody say you don't need it! >> Could you rephrase your point here, I do not fully understand. Who is >> claiming that those API are in general not required? >>> (2) The best way to resolve the problem after ODFDOM Doc API removed is >>> Simple API. >>> (3) Please think thing from the user view. Most of users don't care >> whether >>> ODFDOM is designed as the three parts of ODF specification. They just >> want >>> to manipulate ODF document easily! A so simple requirement, why we have >> to >>> let them import so many jars? odfdom.jar is not enough, odfpackage.jar is >>> also needed... In your opinion, it's resonable that JDK has to be >> separated >>> in to lost of small jars, io.jar, util.jar, xml.jar... Could you tell me >>> how many people use odfpackage.jar only? Please cost some time read the >>> user mail list, most of questions are about Simple API, not >> odfpackage.jar. >>> The report from Google Analytics also show Simple API is the most popular >>> component of ODF Toolkit. Most people know ODFDOM, just because, Simple >> API >>> needs it! But they have to download it separately and find the right >>> version. >> Not all users do care much about software design/modularization. For the >> same reason the ODF specification part 3 had been split of from the main >> spec, our library should be modularized. >> In general the benefits are to split the complexity, decouple >> unnecessary dependencies and to allow the user only to use (load/pay) >> what is really needed. Avoiding memory overhead and boilerplate, >> enabling a much more flexible design. >> Even if 100% of the users on the list are using ODF XML it still makes >> sense, as ODF 1.2 was designed to allow the independent usage of the >> package, e.g. for audio books. >> It is indeed a sad story, that the ePub standard (becoming an ISO >> standard) is not reusing the ODF package, already. Those ePub ppl will >> not write on the list, we have to work towards them to be adoptable. >> Common users are no software developers. If someone only reacts to user >> demands - without any adaption/refactoring of design/implementation - >> the time to add features will grow, as the code becomes more difficult >> to maintain, becoming unstable . Some ppl claim this happens with flash.. >> >>> (4) About the combine javadoc. I just want to say, no people have rights >> to >>> stop a child to explore the Unknown! >> With the above argumentation, you may as well try to persuade us to jump >> from a bridge. IMHO a little too much polemic, too little reasoning. >>> We supply getOdfElement in most of >>> Simple API classes. It possible that user want to know more about >>> OdfElement and its subclasses and OdfAttribute. The combine javadoc >> supplys >>> this way. >>> >>> Anyway, I have started the ODFDOM Doc API removement work. You will see >> the >>> result later in the SVN. Any improvement suggestions are welcomed. Don't >>> worry, I will not combine the two components before we get the consistent >>> answer ;) >> Perhaps it becomes a little more obvious, when I draft a vision: >> IMHO the Simple API shall become the operations API that I plan to use >> for ODF 1.3 change-tracking, see >> >> http://www.oasis-open.org/committees/document.php?document_id=45161&wg_abbrev=office-collab >> >> For an advance scenario see: >> http://lists.oasis-open.org/archives/office-collab/201202/msg00030.html >> >> Most likely the API will have to be adapted a little on new demands, >> still it is worth the effort. >> I got scenarios in mind, that here are currently not being questioned, >> but I am aware are very much in need at very large companies (for the >> ODF ecosystem in general), see >> http://lists.oasis-open.org/archives/office-collab/201202/msg00037.html >> >> BTW the above examples not only work for collaboration, but should >> become the lingua franca for ODF applications doing collaboration. >> In addition the approach will not only allow automated merge on the >> server (e.g. using ODF Toolkit), but history functions for ODF >> applications. >> >> If you got comments on ODF 1.3, please state them directly to the ODF TC >> as comment >> <http://www.oasis-open.org/committees/comments/index.php?wg_abbrev=office> >> due to IPR. >> >> The above should make it more obvious, why it makes sense to divide the >> Simple API (to be standardized) from the ODF XML API (redundant >> functionality on a much fine granular implementation level). >> To assist the user, I suggest instead to use JavaDoc Tags to provide a >> reference from the Simple API JavaDoc to the ODFDOM API JavaDoc. >>> BTW: change package name to org.apache.odftoolkit is in our todo list of >>> the second release, so take it easy. >> We all feel like Sunday morning. >> >> - Svante >>> 2012/2/24 Svante Schubert <[email protected]> >>> >>>> On 23.02.2012 09:30, Devin Han wrote: >>>>> Hi all, >>>>> >>>>> As you know we will remove the deprecated ODFDOM DOC layer and replace >> it >>>>> with Simple API in the 2nd release. After that, ODFDOM will focus on >> low >>>>> level dom/package layer, while Simple API focus on the high level >>>>> convenient API. That would be a good news for users. >>>>> >>>>> Now, I have a new idea that why not combine ODFDOM and Simple API >>>> together? >>>>> If we do that, the advantages are: >>>>> (1) The user only needs to download a single jar. Include to classpath >>>>> easily and no need to care about the version dependency between ODFDOM >>>> and >>>>> Simple API. >>>> I would rather got the opposite way and split ODFDOM into a odfdom.jar >>>> and a odfpackage.jar to have a better modularization. >>>> The ODF specification comes along with a three parts. ODF XML, ODF >>>> formula and package for a reason. We should adapt the given modularity. >>>> >>>> Still we might and should ODFDOM and Simple API join to provide a single >>>> ZIP, as they belong semantically closer together as the other projects. >>>> >>>> I do not see the download of multiple Jars as a problem. >>>> Users tend to use build tools as Maven automated the download the jar or >>>> download a jar only once. As mentioned we might even bundle jars to a >>>> zip for manual download, as for instance Apache Xerces does. >>>>> (2) ODFDOM and Simple API javadoc are together, user can find class, >>>> method >>>>> easily. >>>> Quite the opposite. Simple API is called simple as you do only have such >>>> a little powerful API calls, which bundle several DOM API calls. >>>> If combine them, you will have again a jungle of an API. >>>> >>>> In addition Simple and ODFDOM are different views on the model, we >>>> should keep them separated. >>>> Currently I am trying to evolve ODF operations to be serialized for ODF >>>> change-tracking at OASIS. >>>> In the end it is very close to the Simple API and should be later be >>>> implemented as such, see >>>> >>>> >> http://www.oasis-open.org/committees/document.php?document_id=45161&wg_abbrev=office-collab >>>>> (3) People, who only use ODFDOM before, has a chance to use Simple API >> to >>>>> improve the efficiency. The jar of Simple API 0.7 is only 444.8 KB, >> would >>>>> not take too much space. >>>> I would indeed adapt our documentation / markering and put odfdom and >>>> simple documentation closer together. Allow the jars and API being >>>> downloaded as one, as they belong together. >>>>> The questions are: >>>>> (1) We need a new name for ODFDOM&Simple API. >>>>> (2) What's the new package name of Simple API? Inherit ODFDOM DOC >> Layer >>>>> name or change nothing? >>>> Therefore a mixed answer: >>>> +1 for moving ODFDOM and Simple API closer together via wiki/website >>>> documentation, Maven subproject and download bundle (ZIP) >>>> -1 for moving ODFDOM and Simple API JavaDoc and JAR level together >>>> >>>> - Svante >>>> >>>> >> >> >
