I have tried to add some comments to the Knuth[Element, Box, Glue,
Penalty] classes.
As I am not sure they are clear enough (I'm not even sure they are written
in a proper English! :-) ) I'd like to hear your opinions before
committing them.
Regards,
Luca
Index: KnuthBox.java
===================================================================
RCS file:
/home/cvspublic/xml-fop/src/java/org/apache/fop/layoutmgr/KnuthBox.java,v
retrieving revision 1.2
diff -u -r1.2 KnuthBox.java
--- KnuthBox.java 6 Sep 2004 19:07:12 -0000 1.2
+++ KnuthBox.java 11 Nov 2004 17:56:22 -0000
@@ -18,6 +18,16 @@
package org.apache.fop.layoutmgr;
+/**
+ * An instance of this class represents an unbreakable piece of content with
+ * fixed width: for example an image, a syllable (but only if letter spacing
+ * is constant), ...
+ * A KnuthBox is never a feasible breaking point.
+ * The represented piece of content is never suppressed.
+ * Besides the inherited methods and attributes, this class has some more
+ * attributes to store information about the content height and its vertical
+ * positioning, and the methods used to get them.
+ */
public class KnuthBox extends KnuthElement {
private int lead;
private int total;
Index: KnuthElement.java
===================================================================
RCS file:
/home/cvspublic/xml-fop/src/java/org/apache/fop/layoutmgr/KnuthElement.java,v
retrieving revision 1.2
diff -u -r1.2 KnuthElement.java
--- KnuthElement.java 6 Sep 2004 19:07:12 -0000 1.2
+++ KnuthElement.java 11 Nov 2004 17:56:23 -0000
@@ -18,6 +18,13 @@
package org.apache.fop.layoutmgr;
+/**
+ * This is the super class for KnuthBox, KnuthGlue and KnuthPenalty.
+ * It stores information common to all sub classes, and the methods to get it:
+ * the width, a Position and a boolean marking KnuthElements used for some
+ * special feature (for example, the additional elements used to represent
+ * a space when text alignment is right, left or center).
+ */
public abstract class KnuthElement {
public static final int KNUTH_BOX = 0;
Index: KnuthGlue.java
===================================================================
RCS file:
/home/cvspublic/xml-fop/src/java/org/apache/fop/layoutmgr/KnuthGlue.java,v
retrieving revision 1.2
diff -u -r1.2 KnuthGlue.java
--- KnuthGlue.java 6 Sep 2004 19:07:12 -0000 1.2
+++ KnuthGlue.java 11 Nov 2004 17:56:23 -0000
@@ -18,6 +18,28 @@
package org.apache.fop.layoutmgr;
+/**
+ * An instance of this class represents a piece of content with adjustable
+ * width: for example a space between words of justified text.
+ * A KnuthGlue is a feasible breaking point only if it immediately follows
+ * a KnuthBox.
+ * The represented piece of content is suppressed if either the KnuthGlue
+ * is a chosen breaking point or there isn't any KnuthBox between the
+ * previous breaking point and the KnuthGlue itself.
+ * So, an unsuppressible piece of content with adjustable width, for example
+ * a leader or a word with adjustable letter space, cannot be represented
+ * by a single KnuthGlue; it can be represented using the sequence:
+ * KnuthBox(width = 0)
+ * KnuthPenalty(width = 0, penalty = infinity)
+ * KnuthGlue(...)
+ * KnuthBox(width = 0)
+ * where the infinity penalty avoids choosing the KnuthGlue as a breaking point
+ * and the 0-width KnuthBoxes prevent suppression.
+ * Besides the inherited methods and attributes, this class has two attributes
+ * used to store the stretchability (difference between max and opt width) and
+ * the shrinkability (difference between opt and min width), and the methods
+ * to get these values.
+ */
public class KnuthGlue extends KnuthElement {
private int stretchability;
private int shrinkability;
Index: KnuthPenalty.java
===================================================================
RCS file:
/home/cvspublic/xml-fop/src/java/org/apache/fop/layoutmgr/KnuthPenalty.java,v
retrieving revision 1.2
diff -u -r1.2 KnuthPenalty.java
--- KnuthPenalty.java 6 Sep 2004 19:07:12 -0000 1.2
+++ KnuthPenalty.java 11 Nov 2004 17:56:23 -0000
@@ -18,6 +18,21 @@
package org.apache.fop.layoutmgr;
+/**
+ * An instance of this class represents information about a feasible
+ * breaking point; it does not represent any piece of content.
+ * A KnuthPenalty is a feasible breaking point unless its value is infinity;
+ * a KnuthPenalty whose value is -infinity represents a forced break.
+ * A KnuthPenalty is suppressed, and its width is ignored, if it is not a
+ * chosen breaking point; for example, a KnuthPenalty representing a
+ * hyphenation point has a width (the "-" width), which must be ignored if
+ * that point is not chosen as a breaking point.
+ * Besides the inherited methods and attributes, this class has two more
+ * attributes and the methods used to get them: the penalty value, which is
+ * a kind of "aesthetic cost" (the higher the value, the more unsightly the
+ * breaking point), and a boolean that marks KnuthPenalties which should not
+ * be chosen as breaking points for consecutive lines.
+ */
public class KnuthPenalty extends KnuthElement {
private int penalty;
private boolean bFlagged;
