Re: commenting the Knuth code/centering issue
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 - 1.2
+++ KnuthBox.java 11 Nov 2004 17:56:22 -
@@ -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 - 1.2
+++ KnuthElement.java 11 Nov 2004 17:56:23 -
@@ -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 - 1.2
+++ KnuthGlue.java 11 Nov 2004 17:56:23 -
@@ -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 - 1.2
+++ KnuthPenalty.java 11 Nov 2004 17:56:23 -
@@ -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
Re: commenting the Knuth code/centering issue
On Nov 11, 2004, at 10:03 AM, 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. The English appears good to me. There are even words in there I've never even used (unsuppressible?! stretchability?! shrinkability?!) although they appear to be used correctly! This will be well-commented (IMHO) when you're done... Web Maestro Clay -- Clay Leeds - [EMAIL PROTECTED] Webmaster/Developer - Medata, Inc. - http://www.medata.com/ PGP Public Key: https://mail.medata.com/pgp/cleeds.asc
Re: commenting the Knuth code/centering issue
Excellent, although indentation of paragraphs in comments is somewhat
less common (but if done, should probably be three or four spaces indent
instead of just one). Instead of indenting, it would probably be better
(easier to read) if you placed a blank line between paragraphs. Also,
if you can comment the methods -- one sentence each for the simple ones
are OK -- that would also be appreciated. I know it's a chore but it
has to be done for the JavaDocs.
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 - 1.2
+++ KnuthBox.java 11 Nov 2004 17:56:22 -
@@ -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 - 1.2
+++ KnuthElement.java 11 Nov 2004 17:56:23 -
@@ -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 - 1.2
+++ KnuthGlue.java 11 Nov 2004 17:56:23 -
@@ -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 - 1.2
+++ KnuthPenalty.java 11 Nov 2004 17:56:23 -
@@ -18,6 +18,21 @@
package org.apache.fop.layoutmgr;
+/**
+ * An instance of this class represents information
Re: commenting the Knuth code/centering issue
Luca, On Thu, Nov 11, 2004 at 07:03:33PM +0100, 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. These comments are fine. Simon -- Simon Pepping home page: http://www.leverkruid.nl
Re: commenting the Knuth code/centering issue
Glen Mazza wrote: [BTW, I'm considering getting that Digital Typography book by Knuth you had mentioned earlier. Do you recommend it? (I was thinking that given all the time I spend on FOP I should start looking a little more at the scientific aspects of this work.)] Yes, a must read if you are into computer assisted typesetting. J.Pietschmann
Re: commenting the Knuth code/centering issue
Jeremias Maerki wrote: No, I don't think Luca has write access, yet. I know by now that the CLA is recorded but the account hasn't been created, yet, although I've already sent a reminder. I have just received the e-mail confirming the creation of my account. I am now reading the http://www.apache.org/dev/ documents, so I should soon be able to work. Regards, Luca
Re: commenting the Knuth code/centering issue
Glen Mazza wrote: [BTW, I'm considering getting that Digital Typography book by Knuth you had mentioned earlier. Do you recommend it? (I was thinking that given all the time I spend on FOP I should start looking a little more at the scientific aspects of this work.)] I think it's very interesting. It is a collection of essays on various topics, and besides the one about line breaking (with fabulous features like paragraphs with different sized lines ...) there is one about bidirectional text, one about fonts ... It is surely an authoritative source on such matters. Regards, Luca
Re: commenting the Knuth code/centering issue
On Thu, Nov 04, 2004 at 02:59:52PM -0800, Glen Mazza wrote: --- Luca Furini [EMAIL PROTECTED] wrote: [BTW, I'm considering getting that Digital Typography book by Knuth you had mentioned earlier. Do you recommend it? (I was thinking that given all the time I spend on FOP I should start looking a little more at the scientific aspects of this work.)] I have it. The chapter on the line breaking algorithm is very enlightening. Simon -- Simon Pepping home page: http://www.leverkruid.nl
Re: commenting the Knuth code/centering issue
Glen Mazza wrote: The title centers correctly in 0.20.5, but is left-justified in 1.0. [...] Luca, are you looking at this issue of text alignment in general? Yes, this happens when the text is short and the algorithm is not able to find a set of breaking points: the fallback method can't compute the needed indent, and the text is left-aligned instead of centered. One way to solve this problem is to use, instead of the constant DEFAULT_SPACE_WIDTH, a value computed according to the line width and the maximum acceptable adjustment; this would prevent the algorithm from failing. This value should be computed by the LineLM, and the InlineLMs have to know it. Another way is to use, instead of considerLegalBreak(), a different method to evaluate a possible break point if no breakpoints are found: this alternative method would be much simpler, and would re-create the behaviour of the old getNextBreakPoss method (add content to the existing line if possible, otherwise start another line). I think this could be a much better solution: - it's simpler: it's just another private method in the LineLM - it would solve not only this issue with centered text, but also the other situations in which the Knuth's algorithm fails (for example, when there is a word larger than the line: see Simon's test file id=12494 for bug 29124) I have already done it, so if you agree I could create a patch in a short time. Also, any chance we can get the Knuth classes commented so we have a better idea what KnuthBox, KnuthPenalty, KnuthGlue, etc. are for? Sure, I should have done this before! I'll try and comment these files as soon as possible. Regards, Luca
Re: commenting the Knuth code/centering issue
--- Luca Furini [EMAIL PROTECTED] wrote: Another way is to use, instead of considerLegalBreak(), a different method to evaluate a possible break point if no breakpoints are found: this alternative method would be much simpler, and would re-create the behaviour of the old getNextBreakPoss method (add content to the existing line if possible, otherwise start another line). I think this could be a much better solution: - it's simpler: it's just another private method in the LineLM - it would solve not only this issue with centered text, but also the other situations in which the Knuth's algorithm fails (for example, when there is a word larger than the line: see Simon's test file id=12494 for bug 29124) I have already done it, so if you agree I could create a patch in a short time. Please do--this solution sounds great! (BTW, you have write access already, correct?) Also, any chance we can get the Knuth classes commented so we have a better idea what KnuthBox, KnuthPenalty, KnuthGlue, etc. are for? Sure, I should have done this before! I'll try and comment these files as soon as possible. Much appreciated--30 minutes or so of aggressive commenting of the Knuth classes on your part would make a *wonderful* grokkability improvement to this important area of the code. (Please do the commenting in English though, as I'm three generations removed from understanding Italian. ;) [BTW, I'm considering getting that Digital Typography book by Knuth you had mentioned earlier. Do you recommend it? (I was thinking that given all the time I spend on FOP I should start looking a little more at the scientific aspects of this work.)] Thanks, Glen
Re: commenting the Knuth code/centering issue
No, I don't think Luca has write access, yet. I know by now that the CLA is recorded but the account hasn't been created, yet, although I've already sent a reminder. On 04.11.2004 23:59:52 Glen Mazza wrote: Please do--this solution sounds great! (BTW, you have write access already, correct?) Jeremias Maerki
