crawdad 0.0.1 → 0.1.0

data/CHANGELOG

@@ -0,0 +1,13 @@
+= Version 0.1.0 (April 22, 2010)
+
+* Add support for centered, ragged-right, and ragged-left text.
+
+* Work around an issue with hyphenating some words like "to" using
+text-hyphen.
+
+* Fix segfault when a token stream starts with glue.
+
+
+= Version 0.0.1 (March 19, 2010)
+
+* Initial release.

data/README.markdown

@@ -0,0 +1,61 @@
+# Crawdad: Knuth-Plass linebreaking for Ruby
+
+Crawdad is a basic implementation of the Knuth-Plass linebreaking
+algorithm for breaking paragraphs of text into lines. It uses a total-fit
+method to ensure consistency across the entire paragraph at once. The
+algorithm is a simplified version of the one used in the TeX typesetting
+system.
+
+## References
+
+The canonical reference for this algorithm is "Breaking Paragraphs Into
+Lines", by Donald E. Knuth and Michael F. Plass, originally published in
+Software Practice and Experience 11 (1981), pp. 1119-1184. It is reprinted
+in the excellent monograph Digital Typography (Knuth 1999).
+
+This implementation was inspired by Bram Stein's TypeSet project, an
+implementation of Knuth-Plass in Javascript that uses HTML5 Canvas.
+
+http://www.bramstein.com/projects/typeset/
+
+## To Do
+
+### Short-Term
+
+* Collect all of our constants and magic numbers and expose them somewhat to
+  the user. Survey other software (TeX?) to harvest good starting values for
+  these parameters.
+
+* Fix the demerits calculation to the TeX "improved" formula (Digital
+  Typography p. 154). Thanks to Bram Stein for pointing this out.
+
+* Implement the looseness parameter q (algorithm "Choose the appropriate
+  active node", Digital Typography p. 120).
+
+### Long-Term
+
+* Bring this into Prawn, and integrate (if possible) with the Text::Box API.
+
+* The tokenizer could be smarter; it should recognize more than just
+  low-ASCII hyphens as hyphens / dashes, and it can get confused when
+  whitespace and hyphens interact.
+
+* Automatically relax the thresholds when the constraints cannot be
+  satisfied? Or we could look into TeX's two-pass method (pp. 121-122).
+
+## Acknowledgements
+
+Thanks are due to the following individuals:
+
+* Donald Knuth and Michael Plass created the original algorithm and data
+  structures.
+
+* Bram Stein wrote the aforementioned Javascript implementation of the
+  Knuth-Plass algorithm. His code was helpful in exposing some of the darker
+  corners of the original authors' description of the method.
+
+## License
+
+Crawdad is copyrighted free software, written by Brad Ediger. See the
+LICENSE file for details.
+

data/Rakefile

@@ -4,10 +4,10 @@ require 'rake/testtask'
 require 'rake/rdoctask'
 require 'rake/gempackagetask'
 
-CRAWDAD_VERSION = '0.0.1'
-
+# Build must be the default task, to fake out using a Makefile to build a
+# non-Ruby extension with Rubygems. There's probably an easier way, but I can't
+# find it.
 task :default => [:build]
-
 task :build do
   system "make -Cext/crawdad"
 end
@@ -27,29 +27,7 @@ Rake::RDocTask.new do |rdoc|
   rdoc.title    = "Crawdad Documentation"
 end     
 
-spec = Gem::Specification.new do |spec|
-  spec.name = 'crawdad'
-  spec.version = CRAWDAD_VERSION
-  spec.platform = Gem::Platform::RUBY
-  spec.summary = "Knuth-Plass linebreaking for Ruby"
-  spec.files = FileList["lib/**/**/*"] + FileList["ext/crawdad/*"]
-  spec.require_paths << 'ext'
-
-  binaries = FileList['ext/crawdad/*.bundle', 'ext/crawdad/*.so']
-  spec.extensions << 'Rakefile'
-  spec.files += binaries.to_a
-
-  spec.has_rdoc = true
-  spec.rdoc_options << '--title' << 'Crawdad Documentation' << '-q'
-  spec.author = 'Brad Ediger'
-  spec.email = 'brad.ediger@madriska.com'
-  spec.homepage = 'http://github.com/madriska/crawdad'
-  spec.description = <<END_DESC
-  Crawdad is an implementation of Knuth-Plass linebreaking (justification)
-  for Ruby.
-END_DESC
-end
-
+spec = Gem::Specification.load("crawdad.gemspec")
 Rake::GemPackageTask.new(spec) do |pkg|
   pkg.need_tar = true
 end

data/crawdad.gemspec

@@ -0,0 +1,24 @@
+Gem::Specification.new do |spec|
+  spec.name = 'crawdad'
+  spec.version = '0.1.0'
+  spec.platform = Gem::Platform::RUBY
+  spec.summary = "Knuth-Plass linebreaking for Ruby"
+  spec.files = FileList["lib/**/**/*", "ext/crawdad/*", "README.markdown",
+		"crawdad.gemspec", "CHANGELOG"]
+  spec.require_paths << 'ext'
+
+  binaries = FileList['ext/crawdad/*.bundle', 'ext/crawdad/*.so']
+  spec.extensions << 'Rakefile'
+  spec.files += binaries.to_a
+
+  spec.has_rdoc = true
+  spec.rdoc_options << '--title' << 'Crawdad Documentation' << '-q'
+  spec.author = 'Brad Ediger'
+  spec.email = 'brad.ediger@madriska.com'
+  spec.homepage = 'http://github.com/madriska/crawdad'
+  spec.description = <<END_DESC
+  Crawdad is an implementation of Knuth-Plass linebreaking (justification)
+  for Ruby.
+END_DESC
+end
+

data/ext/crawdad/Makefile

@@ -1,6 +1,6 @@
 OS:=$(shell uname | sed 's/[-_].*//')
 CFLAGS=-Wall -O2 -fPIC
-#CFLAGS=-Wall -fPIC -g
+#CFLAGS=-Wall -fPIC -ggdb
 SHARED=-shared
 SOEXT:=.so
 

data/ext/crawdad/paragraph.c

@@ -107,7 +107,7 @@ void foreach_legal_breakpoint(token *stream[], float width, float threshold,
         tw += t->box.width;
         break;
       case GLUE:
-        if(stream[i-1]->box.type == BOX)
+        if((i > 0) && (stream[i-1]->box.type == BOX))
           fn(stream, i, tw, ty, tz, width, threshold);
         tw += t->glue.width;
         ty += t->glue.stretch;

data/lib/crawdad/ffi/tokens.rb

@@ -14,6 +14,10 @@ module Crawdad
       layout :type,    Type,
              :width,   :float,
              :content, :string
+
+      def inspect
+        "(box %.2f %s)" % [self[:width], self[:content].inspect]
+      end
     end
 
     def box(width, content)
@@ -29,6 +33,10 @@ module Crawdad
              :width,   :float,
              :stretch, :float,
              :shrink,  :float
+
+      def inspect
+        "(glue %.2f %.2f %.2f)" % [self[:width], self[:stretch], self[:shrink]]
+      end
     end
 
     def glue(width, stretch, shrink)
@@ -48,6 +56,11 @@ module Crawdad
              :width,   :float,
              :penalty, :float,
              :flagged, :int
+
+      def inspect
+        "(penalty %.2f %.2f#{" F" if self[:flagged] == 1})" %
+          [self[:penalty], self[:width]]
+      end
     end
     
     def penalty(penalty, width=0.0, flagged=false)

data/lib/crawdad/prawn_tokenizer.rb

@@ -36,7 +36,15 @@ module Crawdad
     #   number of PDF points.
     #
     def paragraph(text, options={})
+      @align = options[:align] || :justify
+
       hyphenator = if options[:hyphenation]
+        # Box-glue-penalty model does not easily permit optional hyphenation
+        # with the construction we use for centered text.
+        if @align == :center
+          raise ArgumentError, "Hyphenation is not supported with centered text"
+        end
+
         begin
           gem 'text-hyphen'
           require 'text/hyphen'
@@ -49,78 +57,125 @@ module Crawdad
         @hyphenators[language] ||= Text::Hyphen.new(:language => language)
       end
 
-      stream = []
-
-      if w = options[:indent]
-        stream << box(w, "")
-      end
-
-      # Interword glue can stretch by half and shrink by a third.
-      # TODO: optimal stretch/shrink ratios
-      space_width = @pdf.width_of(" ")
-      interword_glue = glue(space_width, 
-                            space_width / 2.0,
-                            space_width / 3.0)
-
-      # TODO: optimal values for sentence space w/y/z
-      sentence_space_width = space_width * 1.5
-      sentence_glue = glue(sentence_space_width,
-                           sentence_space_width / 2.0,
-                           sentence_space_width / 3.0)
+      stream = starting_tokens(options[:indent])
 
       # Break paragraph on whitespace.
       # TODO: how should "battle-\nfield" be tokenized?
-      text.strip.split(/\s+/).each do |word|
+      words = text.strip.split(/\s+/)
+      
+      words.each_with_index do |word, i|
         w = StringScanner.new(word)
 
         # For hyphenated words, follow each hyphen by a zero-width flagged
         # penalty.
-        # TODO: recognize dashes in all their variants
         while seg = w.scan(/[^-]+-/) # "night-time" --> "<<night->>time"
-          stream.concat add_word_segment(seg, hyphenator)
+          stream += word_segment(seg, hyphenator)
         end
 
-        stream.concat(add_word_segment(w.rest, hyphenator))
-
-        # TODO: add ties (~) or some other way to denote a period that
-        # doesn't end a sentence.
-        if w.rest =~ /\.$/
-          stream << sentence_glue
-        else
-          stream << interword_glue
+        stream += word_segment(w.rest, hyphenator)
+        
+        unless i == words.length - 1
+          stream += interword_tokens
         end
       end
 
-      # Remove extra glue at the end.
-      stream.pop if token_type(stream.last) == :glue
-
-      # Finish paragraph with a penalty inhibiting a break, finishing glue (to
-      # pad out the last line), and a forced break to finish the paragraph.
-      stream << penalty(Infinity)
-      stream << glue(0, Infinity, 0)
-      stream << penalty(-Infinity)
+      # Add needed tokens to finish off the paragraph.
+      stream += finishing_tokens
 
       stream
     end
 
     protected
 
-    # Returns a series of tokens representing the given word. Hyphenates using
-    # the given +hyphenator+, if provided. Appends a zero-width flagged penalty
-    # if the given word ends in a hyphen.
+    # Width of one space.
+    #
+    def space
+      @space ||= @pdf.width_of(" ")
+    end
+
+    # Tokens used to start a paragraph. Accepts one argument, +indent_width+,
+    # the amount by which to indent the first line, which only really makes
+    # sense for justified or ragged-left text.
+    #
+    def starting_tokens(indent_width)
+      if @align == :center
+        [box(0, ""), glue(0, 3*space, 0)]
+      elsif indent_width
+        [box(w, "")]
+      else
+        []
+      end
+    end
+
+    # Tokens used between words in a sentence. This depends on @align; the
+    # box-glue-penalty model is flexible enough to accommodate ragged (right or
+    # left), centered, or justified text.
     #
-    def add_word_segment(word, hyphenator)
+    # See Digital Typography pp. 93-95 for details.
+    #
+    def interword_tokens
+      case @align
+      when :justify
+        [glue(space, space / 2.0, space / 3.0)]
+      when :center
+        [glue(0, 3*space, 0), penalty(0), glue(space, -6*space, 0), box(0, ""),
+          penalty(Infinity), glue(0, 3*space, 0)]
+      else # :right, :left
+        [glue(0, 3*space, 0), penalty(0), glue(space, -3*space, 0)]
+      end
+    end
+
+    # Tokens representing a possible hyphenation point.
+    #
+    def optional_hyphen
+      hyphen = @pdf.width_of('-')
+
+      if @align == :justify
+        [penalty(50, hyphen, true)]
+      else # :left or :right (:center is incompatible with hyphenation)
+        # Hyphens cost 10 times more in unjustified text because we can usually
+        # do better to avoid them.
+        [penalty(Infinity), glue(0, 3*space, 0), penalty(500, hyphen, true), 
+          glue(0, -3*space, 0)]
+      end
+    end
+
+    # Tokens to finish out a paragraph -- pad out the last line if needed, and
+    # force a break.
+    #
+    def finishing_tokens
+      if @align == :center
+        [glue(0, 3*space, 0), penalty(-Infinity)]
+      else
+        [penalty(Infinity), glue(0, Infinity, 0), penalty(-Infinity)]
+      end
+    end
+
+    # Returns tokens representing the given word. Hyphenates using the given
+    # +hyphenator+, if provided. Appends a zero-width flagged penalty if the
+    # given word ends in a hyphen.
+    #
+    def word_segment(word, hyphenator)
       tokens = []
 
       if hyphenator
-        hyphen_width = @pdf.width_of('-')
+        begin
+          splits = hyphenator.hyphenate(word)
+        rescue NoMethodError => e
+          if e.message =~ /each_with_index/
+            # known issue wth text-hyphen 1.0.0:
+            # http://rubyforge.org/tracker/index.php?func=detail&aid=28128&group_id=294&atid=1195
+            splits = []
+          else
+            raise
+          end
+        end
 
-        splits = hyphenator.hyphenate(word)
-        # For each hyphenated segment, add the box with an optional penalty.
+        # For each hyphenated segment, add the box with an optional hyphen.
         [0, *splits].each_cons(2) do |a, b|
           seg = word[a...b]
           tokens << box(@pdf.width_of(seg), seg)
-          tokens << penalty(50, @pdf.width_of('-'), true)
+          tokens += optional_hyphen
         end
 
         last = word[(splits.last || 0)..-1]

metadata

@@ -1,7 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: crawdad
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
 platform: ruby
 authors: 
 - Brad Ediger
@@ -9,11 +14,11 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-03-19 00:00:00 -05:00
+date: 2010-04-22 00:00:00 -05:00
 default_executable: 
 dependencies: []
 
-description: Crawdad is an implementation of Knuth-Plass linebreaking (justification) for Ruby.
+description: "  Crawdad is an implementation of Knuth-Plass linebreaking (justification)\n  for Ruby.\n"
 email: brad.ediger@madriska.com
 executables: []
 
@@ -22,28 +27,34 @@ extensions:
 extra_rdoc_files: []
 
 files: 
-- lib/crawdad
-- lib/crawdad/prawn_tokenizer.rb
 - lib/crawdad/breakpoint.rb
-- lib/crawdad/native.rb
-- lib/crawdad/ffi.rb
-- lib/crawdad/paragraph.rb
 - lib/crawdad/compatibility.rb
-- lib/crawdad/tokens.rb
-- lib/crawdad/ffi
+- lib/crawdad/ffi/breakpoint_node.rb
 - lib/crawdad/ffi/paragraph.rb
 - lib/crawdad/ffi/tokens.rb
-- lib/crawdad/ffi/breakpoint_node.rb
+- lib/crawdad/ffi.rb
+- lib/crawdad/native.rb
+- lib/crawdad/paragraph.rb
+- lib/crawdad/prawn_tokenizer.rb
+- lib/crawdad/tokens.rb
 - lib/crawdad.rb
 - ext/crawdad/breakpoint.h
-- ext/crawdad/tokens.c
-- ext/crawdad/paragraph.h
+- ext/crawdad/crawdad.bundle
 - ext/crawdad/Makefile
-- ext/crawdad/tokens.h
 - ext/crawdad/paragraph.c
+- ext/crawdad/paragraph.h
+- ext/crawdad/paragraph.o
+- ext/crawdad/tokens.c
+- ext/crawdad/tokens.h
+- ext/crawdad/tokens.o
+- README.markdown
+- crawdad.gemspec
+- CHANGELOG
 - Rakefile
 has_rdoc: true
 homepage: http://github.com/madriska/crawdad
+licenses: []
+
 post_install_message: 
 rdoc_options: 
 - --title
@@ -56,20 +67,22 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
-  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
-  version: 
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.1
+rubygems_version: 1.3.6
 signing_key: 
-specification_version: 2
+specification_version: 3
 summary: Knuth-Plass linebreaking for Ruby
 test_files: []