poi-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Murphy, Mark" <murphym...@metalexmfg.com>
Subject RE: Restarting styled numbered/lettered lists
Date Fri, 04 Nov 2016 11:07:33 GMT
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.klo@sri.com]
Sent: Thursday, November 03, 2016 12:45 PM
To: Nick Burch <apache@gagravarr.org>
Cc: user@poi.apache.org
Subject: Re: Restarting styled numbered/lettered lists

On Nov 3, 2016, at 4:24 AM, Nick Burch <apache@gagravarr.org<mailto:apache@gagravarr.org>>

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


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