Re: commenting the Knuth code/centering issue

2004-11-11 Thread Luca Furini

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

2004-11-11 Thread Clay Leeds
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

2004-11-11 Thread Glen Mazza
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

2004-11-11 Thread Simon Pepping
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

2004-11-07 Thread Glen Mazza
Thanks for the input--with three people recommending the book here and 5 out
of 5 reviewers giving it five stars on Amazon, I went ahead and ordered it
last night.

Glen

- Original Message - 
From: Luca Furini [EMAIL PROTECTED]
To: [EMAIL PROTECTED]
Sent: Saturday, November 06, 2004 12:57 PM
Subject: 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

2004-11-06 Thread J.Pietschmann
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

2004-11-06 Thread Luca Furini
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

2004-11-06 Thread Luca Furini
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

2004-11-05 Thread Simon Pepping
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

2004-11-04 Thread Luca Furini
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

2004-11-04 Thread Glen Mazza
--- 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

2004-11-04 Thread Jeremias Maerki
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