XWPF is a work in process, and the API is not really stable. 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. I am working through a basic architecture right now so that what we have doesn’t feel so disjointed. Then I will start adding in convenience methods for missing parts. Your comments will be helpful in deciding what to work on. Documentation is also very important, but I want to have an underlying architecture in place before I publish how to use it.
From: Jim Klo [mailto:jim....@sri.com] Sent: Thursday, November 03, 2016 12:45 PM To: Nick Burch <apa...@gagravarr.org> Cc: user@poi.apache.org Subject: Re: Restarting styled numbered/lettered lists On Nov 3, 2016, at 4:24 AM, Nick Burch <apa...@gagravarr.org<mailto:apa...@gagravarr.org>> 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
