BTW, got the Digital Typography book in the mail yesterday--started reading it yesterday, very interesting so far. Hope to be able to add to the comments myself sometime soon!
Thanks, Glen
Luca Furini wrote:
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;
