incubator-odf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Devin Han <devin...@apache.org>
Subject Re: [PROPOSAL] Combine ODFDOM and Simple API
Date Thu, 01 Mar 2012 09:43:44 GMT
 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 <svante.schubert@gmail.com>

> 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 <svante.schubert@gmail.com>
> >
> >> 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
> >>
> >>
>
>
>


-- 
-Devin

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message