Moving this discussion from user onto the dev list, as that seems a more appropriate place to discuss.
And please don’t take any of what I take below personally - it is offered as a genuine critique and strategy - from someone who does this professionally for a living. > On Nov 4, 2016, at 4:07 AM, Murphy, Mark <[email protected]> wrote: > > XWPF is a work in process, and the API is not really stable. Understood. > The goal is that it not be simply a surrogate for the CT classes, but rather > an intuitive interface to create word documents from Java. That’s seems like a good goal. However some what I see so far seems more like shortcut methods that are ultimately surrogates to the CT classes. There appears to be a lack of design in what the X* classes should do differently from the CT. > I am working through a basic architecture right now so that what we have > doesn’t feel so disjointed. So my question then is have you developed use cases? To steal a quote form Frank Lloyd Wright… “form follows function.” This rings just as true in architecture of software as it does in building structures. Designing a software architecture without use cases is very much designing a solution without a problem. As this is an ASF project, it wouldn’t be out of the ordinary to have a public place to define and discuss these use cases. If you had a something like a Google doc for open comment and contribution, I’d be happy to provide input and feedback as time permits. I believe that only after you’ve done the due diligence of flushing out the use can you really define a architecture that will fit the problem adequately. > Then I will start adding in convenience methods for missing parts. Your > comments will be helpful in deciding what to work on. I’m hoping that my comments are more about defining the cases rather than just identifying holes in your architecture. That approach leads to patchwork and fragmented solutions. > Documentation is also very important, but I want to have an underlying > architecture in place before I publish how to use it. > Yes, however I find that writing some pre-documentation that illustrates how you want to use the framework before software is written results in a more usable solution. Without this you end up building functionality that requires some dependency that is hard to get at. i.e. the More often than not - it’s very easy to develop an architecture that’s unusable, because the “how" doesn’t jive with the “what”. Just my 2 cents worth of advice. I think this is a great project so far, and has a lot of potential, and I’m happy to help and contribute as my time permits. - JK > From: Jim Klo [mailto:[email protected]] > Sent: Thursday, November 03, 2016 12:45 PM > To: Nick Burch <[email protected]> > Cc: [email protected] > Subject: Re: Restarting styled numbered/lettered lists > > > On Nov 3, 2016, at 4:24 AM, Nick Burch > <[email protected]<mailto:[email protected]>> wrote: > > On Thu, 3 Nov 2016, Jim Klo wrote: > > As I toiled away trying to figure out how to restart styled > bulleted/numbered/lettered lists without messing with the applied numbering > style - as there seems to be a lack of reasonable examples (in both the unit > tests, and existing documentation and tutorials) > > Where would you have expected to find a method to do this in XWPF, and what > would you have expected it to look like? > > Given the XWPF classes are more of a DAO to the underlying Office Open XML, I > don’t know that I would expect a specific convenience method that does this. > However, I would hope that the sequence of how to do common tasks such as > restarting numbered lists to exist in some sort of FAQ/tutorial that explains > how styles, lists and numbering work. > > FWIW, there’s very little on the XWPF side of things that document these > sorts of things… maybe the intent is that the ECMA-376 standard is to > supplant that? However there isn’t really a pointer to which specific > version of ECMA-376 that the POI project supports, nor a very good > explanation of how the POI API maps to the spec. Only now have I located the > ECMA Office Open XML Part 1 [1], section 17.9 Numbering (page 682) which > covers how numbering works: > The basis for all numbering in WordprocessingML is specified via two > structures: > • abstract numbering definitions > • numbering definition instances > > Abstract numbering definitions define the appearance and behavior of a > specific set of numbered paragraphs in a document. Because this construct is > abstract, they are not be directly referenced by document content, but rather > they shall be inherited by a numbering definition instance, which itself is > referenced by document content. > > There are a lot of additional details it goes into but I think most would get > the gist. > > In some respects I would also think there would be at least an exemplar unit > test that maps and validates according to the spec. > > Note this isn’t a rant - you asked what I would expect - that’s kind of what > I would expect to find. > > I think most challenges that I’ve found with POI so far would have been > solved sooner if references to the ECMA standard were present in the Quick > Start and overview. IMO, part 1 of the ECMA standard is very readable and > understandable, and parts of it should be a prerequisite to working with POI > effectively. > > > > I finally found a solution - and I kind of understand it… So I published a > full working sample here: > https://github.com/jimklo/apache-poi-sample/blob/master/src/main/java/com/sri/jklo/StyledDocument.java > > Based on the investigations you've done shown in that code, we might be able > to add a friendly method, especially if you can suggest what that method > should look like... :) > > Again, I’m not sure a “friendly” method is necessarily needed given the XWPF > classes are really just an API to the OpenDocXML DOM. > > A “friendly” method would be a separate project that encapsulates POI as a > wrapper with shortcut methods for authoring docs / editing docs… I’m just not > aware of any open source/non-commercial projects that do this. > > But if I were to ask to add anything, it would be property getters on > protected fields; i.e. XWPFNumbering.getAbstractNums() and > XWPFNumbering.getNums(). Overall, I’m not sure why all these fields have > protected visibility and have no property getters. Protected visibility in > Java is just one of those things that was sort of done “wrong” IMO, as it can > cause some package pollution - such as in this instance. > > I’ve updated my sample [2] which leverages the use of those protected fields > by defining a utility class in the same package as XWPFNumbering. > > While I understand that this is probably the acceptable ‘Java’ way of doing > this, it feels like a “dirty” way of doing this as in practice, an update of > the POI libraries could cause a conflict with my newly defined NumberingUtil > class, if the project were to add the same named class in the future. > > [1] http://www.ecma-international.org/publications/standards/Ecma-376.htm > > [2] > https://github.com/jimklo/apache-poi-sample/commit/a2833583e801eb9fbdb708fabdeeb88f18b05a25 > > > - JK > > > Nick > > --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
