OASIS Open Document Format for Office Applications (OpenDocument) TC

Dear TC members,

reviewing our OpenDocument specification draft 6 I recognized, that
OpenOffice.org has a more detailed view of the frame formatting property
style:flow-with-text than our OpenDocument specification has.

I've implemented that feature for OpenOffice.org 2.0 according to the
attached OpenOffice.org specification "Follow text flow vs. leaving
layout environment for Writer fly frames", which can be found at
http://specs.openoffice.org/writer/index.html. Later on in the
development of OpenOffice.org 2.0, this feature is adopted for drawing
shapes, too.

Due to this implementation in OpenOffice.org 2.0 this frame formatting
property style:flow-with-text has been proposed by Sun and accepted by
the ODF TC. Unfortunately, the proposal and the corresponding
OpenDocument specification text has been simplified - it covers only one
use case.

In OpenOffice.org the value of frame formatting property
style:flow-with-text in general decides, if an anchored object (frame,
graphic, embedded object, drawing shape) flows with the text of its
layout environment and thus, is captured inside its layout environment
or not. The layout environment of an anchored object is given by the
surrounding environment of its anchor. The following layout environments
exists:
- page's text area, if its anchor is inside body text.
- table cell area, if its anchor is inside a table cell.
- page header/footer area, if its anchor is inside the page header/footer.
- footnote/endnode area, if its anchor is inside a footnote/endnode.
- frame area, if its anchor is inside a frame.
The most inner surrounding enironment of its anchor defines the layout
environment of the anchored object.
E.g., The layout environment of an object, which is anchored at a
paragraph, which is inside a table, which is inside a page header, is
the table cell.

OpenOffice.org's interpretation of style:flow-with-text is the following:
- style:flow-with-text = true means, that the object flows with the text
respectively follows the text flow of its layout environment. It stays
inside its layout environment and if needed due to its position it flows
into the next corresponding layout environment - e.g. for layout
environment page's text area. If no next corresponding layout
environment exists, typical for page header/footer area, the object is
captured inside its layout environment.
There are same exceptions and special behaviors, which can be found in
the attached OpenOffice.org specification.

- style:flow-with-text = false means, that the object doesn't flow with
the text of its layout environment and thus, can leave its layout
environment. It can be positioned somewhere on the page its anchor is on.

Currently, the OpenDocument specification speaks only about the use
case, that the anchor of an object is inside the body text - layout
environment of an object is the page's text area. The other use cases
aren't mentioned.
Thus, from my point of view it would be advantageous to clarify also the
missing use cases.
I want to ask the OASIS ODF TC to consider this clarification for ODF
1.2. If the TC in general agrees I would provide the detailed
clarification, covering also the above mentioned exceptions and special
behaviors.


Regards, Oliver.

On Monday 17 September 2007 12:32:20 Oliver-Rainer Wittmann - Software 
Engineer - Sun Microsystems wrote:
> OpenOffice.org's interpretation of style:flow-with-text is the following:
> - style:flow-with-text = true means, that the object flows with the text
> respectively follows the text flow of its layout environment. It stays
> inside its layout environment and if needed due to its position it flows
> into the next corresponding layout environment - e.g. for layout
> environment page's text area. If no next corresponding layout
> environment exists, typical for page header/footer area, the object is
> captured inside its layout environment.
> There are same exceptions and special behaviors, which can be found in
> the attached OpenOffice.org specification.

I'm not convinced that we need a different (auto defined) behavior of 
capturing (or clipping is what we call it in KOffice) the embedded object for 
the different containers.

For example;
If I have a table of items and I add a bright yellow graphic with the 
text "TIP" as an anchored frame to the text in row 4 then I can totally see 
that the user would want to make the graphic be left-aligned to the page 
margin, and thus be positioned outside the table itself.

In other words; if you want to have some way to 'capture' the embedded item 
inside its layout environment, I suggest you make a proposal that adds a 
property to specify the capturing behavior of that anchor. I'd also like to 
call it "clipping" as thats the technical term used in graphics for this 
behavior.

Something like adding this to the embedded object; "clip-to-parent="  With 
values like "None", "Table Cell", "Text Area", "Page"


Cheers
-- 
Thomas Zander

Hi Thomas,

Thomas Zander wrote:
> On Monday 17 September 2007 12:32:20 Oliver-Rainer Wittmann - Software 
> Engineer - Sun Microsystems wrote:
>> OpenOffice.org's interpretation of style:flow-with-text is the following:
>> - style:flow-with-text = true means, that the object flows with the text
>> respectively follows the text flow of its layout environment. It stays
>> inside its layout environment and if needed due to its position it flows
>> into the next corresponding layout environment - e.g. for layout
>> environment page's text area. If no next corresponding layout
>> environment exists, typical for page header/footer area, the object is
>> captured inside its layout environment.
>> There are same exceptions and special behaviors, which can be found in
>> the attached OpenOffice.org specification.
> 
> I'm not convinced that we need a different (auto defined) behavior of 
> capturing (or clipping is what we call it in KOffice) the embedded object for 
> the different containers.
> 
> For example;
> If I have a table of items and I add a bright yellow graphic with the 
> text "TIP" as an anchored frame to the text in row 4 then I can totally see 
> that the user would want to make the graphic be left-aligned to the page 
> margin, and thus be positioned outside the table itself.
> 
> In other words; if you want to have some way to 'capture' the embedded item 
> inside its layout environment, I suggest you make a proposal that adds a 
> property to specify the capturing behavior of that anchor. I'd also like to 
> call it "clipping" as thats the technical term used in graphics for this 
> behavior.
> 
> Something like adding this to the embedded object; "clip-to-parent="  With 
> values like "None", "Table Cell", "Text Area", "Page"
> 
> 
> Cheers


There seems to be a misunderstanding.
I'm not proposing any new feature. The feature, namely frame formatting 
property style:flow-with-text, already exists. I only want to state that 
the current specification text doesn't define all use cases and I'm 
asking to add the missing definitions to the specification text.

BTW, the frame formatting property style:flow-with-text has originally 
been proposed by the former Sun TC member Daniel Vogelheim for 
OpenOffice.org. The property's purpose is to reflect the OpenOffice.org 
feature, which has been described in the specification, I've mentioned 
and attached in my previous eMail.

Regards, Oliver.

On Tuesday 25 September 2007 08:52:40 Oliver-Rainer Wittmann - Software 
Engineer - Sun Microsystems wrote:
> There seems to be a misunderstanding.
> I'm not proposing any new feature. The feature, namely frame formatting
> property style:flow-with-text, already exists. I only want to state that
> the current specification text doesn't define all use cases and I'm
> asking to add the missing definitions to the specification text.

Seems I understood you, then :)
You propose to add implied behavioral rules to an existing feature so it works 
without configuration for your couple of usecases.

I disagree that this is a good way to extend ODF, as I showed with a 
conflicting usecase in my previous mail already.  In other words; adding 
implied behavior is not acceptable to me.
If you want to specify the behaviors you should create a new attribute, like I 
described in my previous mail.

-- 
Thomas Zander

Hi,

Thomas Zander wrote:
> On Tuesday 25 September 2007 08:52:40 Oliver-Rainer Wittmann - Software 
> Engineer - Sun Microsystems wrote:
>> There seems to be a misunderstanding.
>> I'm not proposing any new feature. The feature, namely frame formatting
>> property style:flow-with-text, already exists. I only want to state that
>> the current specification text doesn't define all use cases and I'm
>> asking to add the missing definitions to the specification text.
> 
> Seems I understood you, then :)
> You propose to add implied behavioral rules to an existing feature so it works 
> without configuration for your couple of usecases.

No, I want to clarify the missing use cases in the ODF specification for 
this frame formatting property.

> 
> I disagree that this is a good way to extend ODF, as I showed with a 
> conflicting usecase in my previous mail already.  In other words; adding 
> implied behavior is not acceptable to me.
> If you want to specify the behaviors you should create a new attribute, like I 
> described in my previous mail.

Again, I don't want to extend ODF - I only want to clarify things.

I don't know, if I get the conflicting use case in your previous mail. 
Is it, that the user anchored an object inside a table cell and stated 
that the object should be positioned left-aligned at the page margin and 
thus, in your opinion, this conflicts with clipping/capturing the object 
inside the table cell?

There is no need for a new attribute. The existing attribute 
style:flow-with-text expresses everything that is needed. The only thing 
that was missing is, that the ODF specification text doesn't contain all 
the use cases. As I already stated in my first mail, for what ever 
reason our initial proposal, which introduced this frame formatting 
property, was simplified too much.

I don't understand your objections.
Currently, the specification doesn't define the meaning of the frame 
formatting property style:flow-with-text, if the object is anchored 
inside a table cell, the page header, the page footer, a 
footnote/endnote or inside another object.
I only want to clarify these use cases. I think I can do this, because I 
am somehow the original author of this frame formatting property, but 
somehow in the communication process to the OASIS ODF TC some stuff is 
lost. Nowadays, we've improved our processes to assure that nothing is 
lost on the way from the team, which is responsible for the development 
of a new feature in OpenOffice.org, to the OASIS ODF TC.

Regards, Oliver.

Morning Oliver.
On Wednesday 26 September 2007 09:11:25 Oliver-Rainer Wittmann wrote:
> > I disagree that this is a good way to extend ODF, as I showed with a
> > conflicting usecase in my previous mail already.  In other words; adding
> > implied behavior is not acceptable to me.
> > If you want to specify the behaviors you should create a new attribute,
> > like I described in my previous mail.
>
> Again, I don't want to extend ODF - I only want to clarify things.
>
> I don't know, if I get the conflicting use case in your previous mail.
> Is it, that the user anchored an object inside a table cell and stated
> that the object should be positioned left-aligned at the page margin and
> thus, in your opinion, this conflicts with clipping/capturing the object
> inside the table cell?

Let me try to explain what I think your proposal says, maybe I'm 
misunderstanding.

You state that the behavior of the embedded object is slightly different based 
on where it is embedded. Embedding it in a text in the main page will draw it 
as normal while embedding it in a table cell will make sure that the embedded 
object can not be drawn outside that table cell.
Your 'usecases' are thus embedded positions with slightly different behavior.

Is that right?

> I don't understand your objections.

I don't want different behavior based on position since that is implied 
behavior and if you want different behavior you should not make it implied by 
some slightly-relevant thing like where the text is positioned.
So I disagree with your 'usecases'[1] actually requiring a different outcome.

> Currently, the specification doesn't define the meaning of the frame
> formatting property style:flow-with-text, if the object is anchored
> inside a table cell, the page header, the page footer, a
> footnote/endnote or inside another object.

Yes it does, it defines the behavior exactly.  By not making exceptions the 
behavior written in the spec is for all of those circumstances and thus the 
behavior is defined to be the same for all of them.
The fact that you want to let OOo as well as KOffice and all the others behave 
differently based on where the embedding is done basically doesn't work for 
me.  So I object.

> I only want to clarify these use cases. I think I can do this, because I
> am somehow the original author of this frame formatting property, but
> somehow in the communication process to the OASIS ODF TC some stuff is
> lost. 

Luckely I spotted this in time then, or else KOffice would not be able to 
express its fuller feature set of embedding in ODF :)

Bottom line; your different 'usecases' here should not be expressed add-ons to 
the style:flow-with-text property as that will only work for the model that 
OOo made up. Its not very flexible and it certainly will not work for 
KOffice.
I do agree that clipping would be great to have, but that for sure is a 
different feature which we should get into ODF.

I suggested "clip-to-parent" as a new property, would that work for you?

> Nowadays, we've improved our processes to assure that nothing is 
> lost on the way from the team, which is responsible for the development
> of a new feature in OpenOffice.org, to the OASIS ODF TC.

Which is great. It would be even better if you can take into account some 
discussions with us (KDE) to make sure your proposals are not too much aimed 
at just one implementation.


1) your usage of the term 'usecase' is confusing as it doesn't relate to the 
definition of the word (see wikipedia for example).  Specifically its not 
about different behavior that the user wants.  Its about different technical 
circumstances.
-- 
Thomas Zander

Hi Thomas,

Thomas Zander wrote:
> Morning Oliver.
> On Wednesday 26 September 2007 09:11:25 Oliver-Rainer Wittmann wrote:
>>> I disagree that this is a good way to extend ODF, as I showed with a
>>> conflicting usecase in my previous mail already.  In other words; adding
>>> implied behavior is not acceptable to me.
>>> If you want to specify the behaviors you should create a new attribute,
>>> like I described in my previous mail.
>> Again, I don't want to extend ODF - I only want to clarify things.
>>
>> I don't know, if I get the conflicting use case in your previous mail.
>> Is it, that the user anchored an object inside a table cell and stated
>> that the object should be positioned left-aligned at the page margin and
>> thus, in your opinion, this conflicts with clipping/capturing the object
>> inside the table cell?
> 
> Let me try to explain what I think your proposal says, maybe I'm 
> misunderstanding.
> 
> You state that the behavior of the embedded object is slightly different based 
> on where it is embedded. Embedding it in a text in the main page will draw it 
> as normal while embedding it in a table cell will make sure that the embedded 
> object can not be drawn outside that table cell.
> Your 'usecases' are thus embedded positions with slightly different behavior.
> 
> Is that right?
> 

That's partly right.
I have to add that an object anchored inside the body text will not
leave the body text area, if style:flow-with-text="true" - it can't be
positioned over the page header or the page footer as it is said in the
current specification text. If style:flow-with-text="false" for an
object, which is anchored inside the body text, it can leave the body
text area.


>> I don't understand your objections.
> 
> I don't want different behavior based on position since that is implied 
> behavior and if you want different behavior you should not make it implied by 
> some slightly-relevant thing like where the text is positioned.
> So I disagree with your 'usecases'[1] actually requiring a different outcome.
> 
>> Currently, the specification doesn't define the meaning of the frame
>> formatting property style:flow-with-text, if the object is anchored
>> inside a table cell, the page header, the page footer, a
>> footnote/endnote or inside another object.
> 
> Yes it does, it defines the behavior exactly.  By not making exceptions the 
> behavior written in the spec is for all of those circumstances and thus the 
> behavior is defined to be the same for all of them.
> The fact that you want to let OOo as well as KOffice and all the others behave 
> differently based on where the embedding is done basically doesn't work for 
> me.  So I object.
> 
I didn't agree to this interpretation.
The current specification text isn't very clear in my eyes. From my
point of view it only make sense to the situation that an object is
anchored inside the body text, probably also for an object that is
anchored inside a table cell, which is inside the body text.
It doesn't make sense for objects anchored inside a footnote/endnote,
page header, page footer or inside a text frame.

But finally, I can only repeat, that the original proposal for this
frame formatting property went into the specification too simplified and
not reviewed regarding the OpenOffice.org feature, which triggers this
frame formatting property.

Some notes on the history of this feature in OpenOffice.org Writer:
Prior to OpenOffice.org 2.0, text frames, embedded object and graphics
are clipped/captured inside its layout environment and flow with the
text flow, if possible. The reason for this was, that the content
structure also determines the layout structure - e.g. a paragraph inside
a page header have to stay inside the page header.
Shapes (drawing objects in OpenOffice.org) unfortunately doesn't follow
this rule.
For OpenOffice.org 2.0, we needed to unify text frames, embedded
objects, graphics and shapes. Thus, this frame formatting property has
been proposed. This need was also influenced by interoperability
requests for the binary Microsoft Word file format and the Microsoft 
Word layout.

>> I only want to clarify these use cases. I think I can do this, because I
>> am somehow the original author of this frame formatting property, but
>> somehow in the communication process to the OASIS ODF TC some stuff is
>> lost. 
> 
> Luckely I spotted this in time then, or else KOffice would not be able to 
> express its fuller feature set of embedding in ODF :)
> 
> Bottom line; your different 'usecases' here should not be expressed add-ons to 
> the style:flow-with-text property as that will only work for the model that 
> OOo made up. Its not very flexible and it certainly will not work for 
> KOffice.
> I do agree that clipping would be great to have, but that for sure is a 
> different feature which we should get into ODF.
> 
> I suggested "clip-to-parent" as a new property, would that work for you?

 From my point of view this isn't needed.
For me, [style:flow-with-text="true"] <==> [clip-to-parent="true"] and
[style:flow-with-text="false"] <==> [clip-to-parent="false"].
While [style:flow-with-text="true"] has the additional meaning, that the
object flow with the text flow, if it is possible.


I still have the opinion, that my proposed change is a needed 
clarification for this frame formatting property.


Regards, Oliver.

Thomas,

This issue came up for discussion today at the TC call and it was 
suggested that the rest of the TC review the posts and comment.

I have a question about something you say below.

Thomas Zander wrote:
> Morning Oliver.
>
>   

On Monday 17 September 2007 12:32:20 Oliver-Rainer Wittmann - Software 
Engineer - Sun Microsystems wrote:
> reviewing our OpenDocument specification draft 6 I recognized, that
> OpenOffice.org has a more detailed view of the frame formatting
> property style:flow-with-text than our OpenDocument specification has.

Oliver,

can you propose an exact wording to add to the spec?

>  If no next corresponding layout
> environment exists, typical for page header/footer area, the object is
> captured inside its layout environment.

I have been especially surprised by your usage of the word "captured" 
which you later replaced with "clipped".  But I don't think you mean what 
I think those words mean; I think your intention can be better described 
with something more along the lines of  "repositioned" or 
"adjusted to fit".

Cheers.
-- 
Thomas Zander

Hi Thomas,

Thomas Zander wrote:
> On Monday 17 September 2007 12:32:20 Oliver-Rainer Wittmann - Software 
> Engineer - Sun Microsystems wrote:
>> reviewing our OpenDocument specification draft 6 I recognized, that
>> OpenOffice.org has a more detailed view of the frame formatting
>> property style:flow-with-text than our OpenDocument specification has.
> 
> Oliver,
> 
> can you propose an exact wording to add to the spec?
> 
Yes, I can.
Probably, this is the best to do, because I think that due to the used 
wording and terms a lot of confusion occurs. I will work this out in the 
next days.

Can you in the meanwhile reply to/comment my posts:
http://www.oasis-open.org/archives/office/200710/msg00001.html
http://www.oasis-open.org/archives/office/200710/msg00022.html
http://www.oasis-open.org/archives/office/200710/msg00023.html

>>  If no next corresponding layout
>> environment exists, typical for page header/footer area, the object is
>> captured inside its layout environment.
> 
> I have been especially surprised by your usage of the word "captured" 
> which you later replaced with "clipped".  But I don't think you mean what 
> I think those words mean; I think your intention can be better described 
> with something more along the lines of  "repositioned" or 
> "adjusted to fit".
> 
I use "to capture an object inside a certain area" to express, that the 
position and also the size (if needed) of an object is adjusted in order 
to achieve that the object fits into the given area. I've using "to 
capture" in a figurative sense in this context.
I've switched to term "to clip", because you are telling me, that this 
is the correct term for it - see your first reply to my initial posting. 
But now I think that's not correct and thus, the used wording causes 
confusion.

Regards, Oliver.

On Friday 19 October 2007 08:22:11 Oliver-Rainer Wittmann - Software 
Engineer - Sun Microsystems wrote:
> Can you in the meanwhile reply to/comment my posts:
> http://www.oasis-open.org/archives/office/200710/msg00001.html
> http://www.oasis-open.org/archives/office/200710/msg00022.html
> http://www.oasis-open.org/archives/office/200710/msg00023.html

I'd rather wait until you write up your text as I think we were talking about 
quite different things, and if I re-read your proposal with the adjusted 
terms I'd probably be ok with your proposal.

The alignments mail then is not really relevant. As this is a clarification, 
not a new property.  So I'll postpone looking into how the KOffice alignments 
actually map onto the existing ODF stuff.

Thanks!
-- 
Thomas Zander

Dear TC members,

Oliver-Rainer Wittmann - Software Engineer - Sun Microsystems wrote:
> Hi Thomas,
> 
> Thomas Zander wrote:
>> On Monday 17 September 2007 12:32:20 Oliver-Rainer Wittmann - Software 
>> Engineer - Sun Microsystems wrote:
>>> reviewing our OpenDocument specification draft 6 I recognized, that
>>> OpenOffice.org has a more detailed view of the frame formatting
>>> property style:flow-with-text than our OpenDocument specification has.
>>
>> Oliver,
>>
>> can you propose an exact wording to add to the spec?
>>
> Yes, I can.
> Probably, this is the best to do, because I think that due to the used 
> wording and terms a lot of confusion occurs. I will work this out in the 
> next days.
> 

attached you will find the changed ODF specification text regarding my 
clarification for frame formatting property style:flow-with-text.
Please give your questions and comments.

Hopefully, this time we won't get confused by the used wording and used 
terms.

Best regards, Oliver.

On Wednesday 24 October 2007 14:12:29 Oliver-Rainer Wittmann - Software 
Engineer - Sun Microsystems wrote:
> attached you will find the changed ODF specification text regarding my
> clarification for frame formatting property style:flow-with-text.
> Please give your questions and comments.

Thank you for your text, appreciate it.

I have to admit not being able to get through it, a little too much 
germanisms and too long sentences for me ;)
I get the gist and I won't object further.

-- 
Thomas Zander

Hi,

Thomas Zander wrote:
> On Wednesday 24 October 2007 14:12:29 Oliver-Rainer Wittmann - Software 
> Engineer - Sun Microsystems wrote:
>> attached you will find the changed ODF specification text regarding my
>> clarification for frame formatting property style:flow-with-text.
>> Please give your questions and comments.
> 
> Thank you for your text, appreciate it.
> 
> I have to admit not being able to get through it, a little too much 
> germanisms and too long sentences for me ;)
> I get the gist and I won't object further.
> 

Thank you for the review.

Thus, we have the correct wording, now we need better wording and grammar.

Regards, Oliver.

Hi,

Lars and I reworked the wording of the proposed specification text for 
the clarification. Find the new version of the specification text in the 
attached document.

Note: We only reworked the wording - no change in the meaning.

Regards, Oliver.

Oliver-Rainer Wittmann - Software Engineer - Sun Microsystems wrote:
> Hi,
> 
> Thomas Zander wrote:
>> On Wednesday 24 October 2007 14:12:29 Oliver-Rainer Wittmann - 
>> Software Engineer - Sun Microsystems wrote:
>>> attached you will find the changed ODF specification text regarding my
>>> clarification for frame formatting property style:flow-with-text.
>>> Please give your questions and comments.
>>
>> Thank you for your text, appreciate it.
>>
>> I have to admit not being able to get through it, a little too much 
>> germanisms and too long sentences for me ;)
>> I get the gist and I won't object further.
>>
> 
> Thank you for the review.
> 
> Thus, we have the correct wording, now we need better wording and grammar.
> 
> Regards, Oliver.