Re: Restarting styled numbered/lettered lists

[Jim Klo <ji...@gmail.com>]

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 <mu...@metalexmfg.com> 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:jim.klo@sri.com]
> Sent: Thursday, November 03, 2016 12:45 PM
> To: Nick Burch <ap...@gagravarr.org>
> Cc: user@poi.apache.org
> Subject: Re: Restarting styled numbered/lettered lists
> 
> 
> On Nov 3, 2016, at 4:24 AM, Nick Burch <ap...@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
> 
> 



---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@poi.apache.org
For additional commands, e-mail: dev-help@poi.apache.org

Re: Restarting styled numbered/lettered lists

[Mark Murphy <jm...@gmail.com>]

> Jim Klo <ji...@gmail.com> via
<https://support.google.com/mail/answer/1311182?hl=en> poi.apache.org wrote:

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

No offense, I just took this over, still working on getting it under
control. BTW, I have been doing this professionally for a living for over
25 years (most of that not in Java). I understand your comments.

>> On Nov 4, 2016, at 4:07 AM, Murphy, Mark <mu...@metalexmfg.com>
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.

Just my own built out of frustration from trying to use this API. I have an
overall picture of what I want it to look like, but have not yet put that
down on paper. There is some discussion here about making the code better
by reducing duplicated code, but if I have someone who wants to have input
into the re-architecting of XWMP, I can put my musings in a document for
comment. We could use my github fork here:
https://github.com/JMarkMurphy/poi. Nothing there yet except some ideas on
how to generalize some of the functions, but let me work on that this
weekend.

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

Which is the current situation. Multiple independent developers adding bits
and pieces here and there to solve (likely in a 'quick-n-dirty' manner) a
specific problem with no discussion on the best way to go about it. If we
can get more than one person's opinion on what use cases we have, then we
can make a more cohesive interface. And preferably one that will be
intuitive to those using the XSSF interface as well.

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

So let me get some of the stuff that has been running around in my head
down in my fork. I will set up a wiki page because things are in such flux
right now that I really don't want anything out there for general
consumption yet. Then you can add you two cents. and maybe with both of us
thinking about it we will be able to start down a path that will make XWPF
look more like a mainline module of POI.

On Fri, Nov 4, 2016 at 2:00 PM, Jim Klo <ji...@gmail.com> wrote:

> 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 <mu...@metalexmfg.com>
> 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:jim.klo@sri.com]
> > Sent: Thursday, November 03, 2016 12:45 PM
> > To: Nick Burch <ap...@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:a
> pache@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
> >
> >
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@poi.apache.org
> For additional commands, e-mail: dev-help@poi.apache.org
>
>