Mailing-List: contact fop-commits-help@xmlgraphics.apache.org; run by ezmlm
Precedence: bulk
Reply-To: fop-dev@xmlgraphics.apache.org
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: quoted-printable
From: Apache Wiki <wikidiffs@apache.org>
To: Apache Wiki <wikidiffs@apache.org>
Date: Wed, 15 Jun 2011 16:54:16 -0000
Message-ID: <20110615165416.26690.64870@eos.apache.org>
Subject: 
 =?utf-8?q?=5BXmlgraphics-fop_Wiki=5D_Update_of_=22FootnotesAndBeforeFloat?=
 =?utf-8?q?s/Footnotes=22_by_AndreasLDelmelle?=
Auto-Submitted: auto-generated

Dear Wiki user,

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

The "FootnotesAndBeforeFloats/Footnotes" page has been changed by AndreasLD=
elmelle:
http://wiki.apache.org/xmlgraphics-fop/FootnotesAndBeforeFloats/Footnotes

New page:
''This page is a work-in-progress, and aims to serve as documentation of ho=
w FOP's layout engine processes footnotes, mainly to save interested contri=
butors the hassle of having to find out the hard way...''
----
=3D Introduction =3D

[[http://www.w3.org/TR/xsl/|XSL-FO]] defines the {{{fo:footnote}}} formatti=
ng object to allow authors to insert citations into their documents. =

These footnotes are attached to the line area in which they would appear, a=
nd are to be rendered in a reserved footnote-area on the after-edge of the =
region-reference-area, preceded by a footnote-separator if one is defined i=
n the source.
This page intends to describe only the approach with respect to the layout =
engine. The initial validation of out-of-line descendants during parsing is=
 considered out of scope.

FOP's layout engine has to deal with footnote content in two phases (most g=
eneral use case; see further below for the special cases):
 * Line layout: the footnotes are attached to the box representing the line=
 area that holds the surrounding inline content in the source
 * Page layout: the footnotes are placed on the page that contains the line=
 area that holds the anchor

=3D Line layout =3D

During the initial collection of the inline {{{KnuthElements}}}, if footnot=
es are encountered, a {{{KnuthInlineBox}}} is generated for the anchor, tha=
t holds a reference to the {{{FootnoteBodyLayoutManager}}}. If the anchor i=
s empty, a dummy auxiliary box will be inserted to make sure the footnote i=
s rendered at the appropriate place. (see: {{{org.apache.fop.layoutmgr.inli=
ne.FootnoteLayoutManager.getNextKnuthElements()}}})

The {{{LineLayoutManager}}} is responsible for making sure that the LMs for=
 the footnote-bodies are attached to the appropriate line box (see: {{{org.=
apache.fop.layoutmgr.inline.LineLayoutManager.postProcessLineBreaks()}}}).

=3D=3D Special cases: lists and tables =3D=3D

As lists and tables 'aggregate' their content and return {{{KnuthBoxes}}} e=
ncompassing multiple line areas, they (currently) have to take care of prop=
agating the footnotes from the contained line boxes upward, so that the {{{=
PageBreaker}}} will be able to access them. TODOs have been left in the cod=
e, and concerns have been raised that the related classes should actually r=
emain footnote-agnostic. Ultimately, there is a certain duplication of what=
 {{{LineLayoutManager}}} does...

One possible strategy to avoid that, would be to push this out of the LMs, =
and into a factory that constructs boxes based on (lists of) element lists.=
 All this logic would then be contained in a single class. The LMs, instead=
 of explicitly instantiating the boxes, would just pass the sublist(s) that=
 represent the contained content, and get back the appropriate type of box =
to add to their element list.

see also: [[https://issues.apache.org/bugzilla/show_bug.cgi?id=3D37579|Bugz=
illa 37579]]

=3D Page layout =3D

=3D=3D Initial pass - Layout of the footnote bodies =3D=3D

During an initial pass over the block list returned by the {{{FlowLayoutMan=
ager}}}, the {{{PageBreaker}}} first triggers line layout of all the footno=
te-bodies, so that the footnotes' lists of line boxes are directly accessib=
le in the corresponding content boxes. The reason this was deferred from li=
ne layout, is that the context will not always be the same. In case of mult=
i-column layout, the footnotes will span the whole region-reference-area, r=
ather than follow the flow's column-count.

If footnotes were encountered, layout of the footnote-separator is done her=
e, so that its block-progression-dimension will be readily available when n=
eeded later by the {{{PageBreakingAlgorithm}}}.

see: {{{org.apache.fop.layoutmgr.PageBreaker.getNextKnuthElements()}}}

=3D=3D Calculating the breaks =3D=3D

A (line) box with anchors triggers {{{PageBreakingAlgorithm.handleFootnotes=
()}}}, which:

 * adds the corresponding element lists to footnoteList
 * computes the total length of each of the element lists
 * for each element list, stores the accumulated length of all preceding no=
tes plus its own, in {{{lengthList}}}

Additionally, {{{totalFootnotesLength}}} is increased with the length of ea=
ch footnote.

For all following legal breaks, this will result in {{{PageBreakingAlgorith=
m.computeDifference()}}} taking into account the additional width required =
for the footnote separator and the footnotes up to that point.
If the total length of content + separator + all footnotes does not fit wit=
hin the available width, and it is allowed to defer part of the footnotes t=
o the following page, the footnote length will be split here.

The chosen strategy is to:
 * first try adding all footnotes that can no longer be deferred (i.e. were=
 already carried over from a previous break)
 * then add whole footnotes, until we reach one that doesn't fit in its ent=
irety
 * from the next footnote, try adding more parts, until we reach the part t=
hat doesn't fit anymore


=3D Remaining Issues =3D

=3D=3D Footnotes and multi-column flows =3D=3D

Since there is no hard distinction between page- and column-breaks, with re=
spect to footnotes, each column acts as its own page. The best node for eac=
h column is determined by only looking at the footnotes whose anchors are i=
n ''that'' particular column. This leads to overlaps between footnotes and =
the flow content.

see: [[https://issues.apache.org/bugzilla/show_bug.cgi?id=3D51304|Bugzilla =
51304]]

=3D=3D Infinite loops in footnote deferral =3D=3D

There are currently multiple open Bugzilla reports about infinite loops bei=
ng triggered under certain circumstances. Closer inspection reveals that th=
e culprit is the footnote deferral mechanism, very likely in the interactio=
n between {{{PageBreakingAlgorithm.getFootnoteSplit()}}} and {{{.createFoot=
notePages()}}}. Certain assumptions are made in {{{getFootnoteSplit()}}} th=
at do not always seem to hold. One such assumption is that the local variab=
le {{{splitLength}}} will eventually always exceed the {{{availableLength}}=
}.

see: [[https://issues.apache.org/bugzilla/show_bug.cgi?id=3D47424|Bugzilla =
47424]]
or [[https://issues.apache.org/bugzilla/show_bug.cgi?id=3D48397|Bugzilla 48=
397]]

=3D=3D Space resolution between footnotes =3D=3D

When the {{{PageBreakingAlgorithm}}} adds a box's footnotes, space-resoluti=
on is triggered for each footnote separately. This does not take into accou=
nt potential stacking constraints ''between'' the footnotes.

see code comment in: {{{PageBreakingAlgorithm.handleFootnotes()}}}

----

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