[Xmlgraphics-fop Wiki] Update of "Design/XslFo/Wrapper" by GlennAdams

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Xmlgraphics-fop Wiki" for change notification.

The "Design/XslFo/Wrapper" page has been changed by GlennAdams:
http://wiki.apache.org/xmlgraphics-fop/Design/XslFo/Wrapper

Comment:
new hierarchy (and an instance) page to document design, design/xslfo, and design/xslfo/wrapper

New page:
= XslFo/Wrapper Design =

== Existing Design Review (circa FOP1.1dev) ==

=== Specification Compliance ===

 * erroneously generates a (zero size, leaf) block or inline area regardless of whether children generate a normal area, and regardless of whether `@id` is present or not;
 * `marker` children of `wrapper` are ignored, which prevents `retrieve-marker` from cloning content from these children
 * `page-number-citation` and `page-number-citation-last` that refer to wrapper's `@id` fail to resolve

=== org.apache.fop.layoutmgr.LayoutManagerMapping.WrapperLayoutManagerMaker ===

 * instantiates the LMs of `wrapper` and its children as sibling child LMs of the parent LM of the `wrapper` LM; as such, there is no parent/child relationship between the `wrapper` LM and the `wrapper`'s child LMs;

=== org.apache.fop.layoutmgr.inline.WrapperLayoutManager ===

 * subclasses `LeafNodeLayoutManager`, so cannot directly employ child LMs

=== Open Bugs ===

 * [[https://issues.apache.org/bugzilla/show_bug.cgi?id=47530|Bug 47530]] - `(%block;)+` context problems
 * [[https://issues.apache.org/bugzilla/show_bug.cgi?id=50724|Bug 50724]] - `marker`, `page-number-citation` don't work
 * [[https://issues.apache.org/bugzilla/show_bug.cgi?id=52526|Bug 52526]] - generates extraneous line

== Possible New Design ==

=== Goals ===

 * preserve parent/child LM relation for wrapper and its children;
 * ensure specification compliance with respect to generation of areas (or not); i.e., generate area iff no child LM returns a normal area and `@id` is specified;
 * when area is generated (per above), ensure that it is a block or inline area according to the permissible content of the nearest non-wrapper ancestor;
 * preserve `marker` semantics, where `retrieve-marker` references a `marker` child of `wrapper`;
 * preserve `page-number-citation{-last}` semantics, when referencing a wrapper or wrapper's descendant;
 * ensure that areas generated by children of wrapper are processed appropriately as block or inline content according to the semantics of the nearest non-wrapper LM;

=== Approach ===

 * employ two distinct Wrapper LMs depending on whether processing block or inline content:
  * `org.apache.fop.layoutmgr.BlockWrapperLayoutManager` - block content contexts
   * subclasses `BlockStackingLayoutManager`
  * `org.apache.fop.layoutmgr.inline.InlineWrapperLayoutManager` - inline content contexts
   * subclasses `InlineStackingLayoutManager`
  * `WrapperLayoutManagerMaker` makes determination of which to instantiate based on `Wrapper` ''node'' parameter

=== Considerations ===

==== On Using InlineLayoutManager instead of InlineStackingLayoutManager ====

If possible, it would be better to have `InlineWrapperLayoutManager` subclass `InlineLayoutManager` than `InlineStackingLayoutManager`, due to the more completely implemented semantics of the former. However, this is complicated by two issues:

 * `InlineLayoutManager` always generates an enclosing parent area, either an `InlineBlockParent` or `InlineParent` area. This is a problem for satisfying specification compliance since no area is supposed to be generated unless no child returns a normal area and `@id` is specified.
 * `InlineLayoutManager` currently requires its associated FObj to implement `InlineLevel` and not merely `FObjMixed`. [This is contrary to the code comments that says `FObjMixed` is sufficient.] The problem here is that `Wrapper` subclasses `FObjMixed` and not `InlineLevel`, and changing to the latter would become a problem when `Wrapper` is used in a block only context.

---------------------------------------------------------------------
To unsubscribe, e-mail: fop-commits-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: fop-commits-help@xmlgraphics.apache.org