htmldoc 0.1.0 → 0.2.0

data/CHANGELOG.txt

@@ -1,3 +1,27 @@
+2007-03-07 ronaldo <ronaldo@reflectivesurface.com>
+
+	* Changed the instance variable result to a hash of information
+	about the generation, including bytes and pages generated, and the
+	raw result of the program's execution
+
+	* Added an errors instance variable to register all the errors
+	generated in the course of the program's execution
+	
+	* Refactored generate
+	
+	* Changed generate so it now raises an exception if the program
+	path cannot be found
+
+	* Improved the tests
+
+	* Improved the documentation
+	
+2007-03-06 ronaldo <ronaldo@reflectivesurface.com>
+
+	* Fixed spelling and grammatical error in README.txt
+	
+	* Fixed a couple of naming issues in Rakefile
+	
 2007-03-05 ronaldo <ronaldo@reflectivesurface.com>
 
 	* Initial release

data/History.txt

@@ -1,2 +1,8 @@
+0.2.0
+* Improved the way results are reported
+* Added information about errors generated in the course of execution
+* Refactored a couple of internal methods
+* Improved the tests and documentation
+
 0.1.0
 * Initial release

data/README.txt

@@ -5,11 +5,11 @@ that converts HTML input files into formatted HTML, PDF or PostScript
 output.
 
 Home:: http://rubyforge.org/projects/pdf-htmldoc/
-HTMLDOC Home: http://www.htmldoc.org/
+HTMLDOC Home:: http://www.htmldoc.org/
 Copyright:: 2007, Ronaldo M. Ferraz
 
 This is a preview release, which means it had only limited testing. As
-far as it's know, it will work on all platforms in which HTMLDOC is
+far as I know, it will work on all platforms in which HTMLDOC is
 available. Comments, suggestions, and further tests are welcome.
 
 == LICENSE NOTES
@@ -59,7 +59,7 @@ A similar approach can be used for inline generation:
     p << "/var/doc/file2.html"
 
     p << @report.to_html
-    p << "Some other text that will be incorporated to the report"
+    p << "Some other text that will be incorporated in the report"
 
     p.footer ".1."
 
@@ -73,10 +73,46 @@ your system.
 
   require "htmldoc"
 
-  PDF::HTMLDoc.program_path = "\"C:\Program Files\HTMLDOC\ghtmldoc.exe\""
+  PDF::HTMLDoc.program_path = "\"C:\\Program Files\\HTMLDOC\\ghtmldoc.exe\""
 
 See the notes below for usage considerations.
 
+== COMMON OPTIONS
+
+Here are a few of the common options that can be used to control
+HTMLDOC's output (assuming that <tt>pdf</tt> is a valid instance of
+PDF::HTMLDoc):
+
+To change the orientation to portrait mode, use:
+  pdf.set_option :portrait, true 
+
+To change the orientation to landscape mode, use:
+  pdf.set_option :landscape, true 
+
+To set the margins use:
+  pdf.set_option :top, "15"
+  pdf.set_option :right, "3cm"
+  pdf.set_option :left, "0.25in"
+  pdf.set_option :bottom, "20mm"
+
+To disable the automatic table of contents, use:
+  pdf.set_option :toc, false
+
+To control the header and footer, use:
+  pdf.header "lcr"
+  pdf.footer "lcr"
+
+In the code above, "lcr" is a thee-character string representing the
+left, center, and right fields of the header or footer. A ".1."
+string, for example, indicates that the left and right fields should
+be blank, and that the center field should contain the current page
+number in decimal format. You can find more information about the
+possible options in the HTMLDOC
+documentation[http://www.htmldoc.org/htmldoc.html#footer].
+
+More information about other options can be found in the HTMLDOC
+command-line reference[http://www.htmldoc.org/htmldoc.html#CMDREF].
+
 == NOTES
 
 * PDF::HTMLDoc is both a Rails plugin and a gem, which means it can be
@@ -84,13 +120,21 @@ See the notes below for usage considerations.
   further dependencies.
 
 * Under Windows, it's better to point the program path for the HTMLDOC
-  executable to the GUI vesion. It will avoid a DOS command window from
-  popping-up in your application,
-
-* Keep in mind that HTMLDOC is not fast over large documents. If you
-  need to generate very large documents, you be better off spawning an
-  additional thread if your are in a traditional application or
-  farming off the generation for a background deamon that will
-  communicate with your application using some RPC
+  executable to the GUI version. It will prevent a DOS command window
+  from popping-up in your application,
+
+* Keep in mind that HTMLDOC is not very fast over large documents. If
+  you need to generate very large documents, you'll be better off
+  spawning an additional thread if you are developing a traditional
+  application or farming off the generation for a background deamon
+  that will communicate with your application using some RPC
   mechanism. BackgrounDRb[http://backgroundrb.rubyforge.org] is a good
   choice for that.
+
+* HTMLDOC doesn't support CSS files in its current stable version
+  (1.8.27). The development version (1.9) does support CSS, but in a
+  limited way. 
+
+* HTMLDOC doesn't support UTF-8. Since PDF::HTMLDOC makes no attempt
+  to convert any input passed to it, it's the caller's responsibility
+  to provide any necessary conversions.

data/Rakefile

@@ -19,7 +19,7 @@ GEM_NAME = "htmldoc"
 RUBYFORGE_PROJECT = "htmldoc"
 HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
 
-NAME = "htmldoc"
+NAME = "HTMLDOC"
 REV = File.read(".svn/entries")[/committed-rev="(d+)"/, 1] rescue nil
 VERS = ENV['VERSION'] || (PDF::HTMLDOC::VERSION::STRING + (REV ? ".#{REV}" : ""))
                           CLEAN.include ['**/.*.sw?', '*.gem', '.config']

data/lib/htmldoc.rb

@@ -44,9 +44,21 @@ module PDF
     # <code>"C:\Program Files\HTMLDOC\HTMLDOC.exe"</code>.
     @@program_path = "htmldoc"
 
-    # The last result from the generation of the output file(s).
+    # The last result from the generation of the output file(s). It's
+    # a hash comprising three pairs:
+    # <tt>bytes</tt>:: The number of bytes generated in the last request or <tt>nil</tt>
+    # <tt>pages</tt>:: The number of pages generated in the last request or <tt>nil</tt>
+    # <tt>output</tt>:: The raw output of the command
     attr_reader :result
 
+    # The last error messages generate by the command. It's a hash
+    # where they key represents the error number, and the value
+    # represents the error message. If the error number is zero,
+    # HTMLDOC was called with invalid parameters. Errors can happen
+    # even if generation succeeds, for example, if an image can't be
+    # found in the course of the generation.
+    attr_reader :errors
+
     # Creates a blank HTMLDOC wrapper, using <tt>format</tt> to
     # indicate whether the output will be HTML, PDF or PS. The format
     # defaults to PDF, and can change using one of the module
@@ -56,13 +68,13 @@ module PDF
       @options = {}
       @pages = []
       @tempfiles = []
-      @result = ""
+      reset
     end
 
     # Creates a blank HTMLDOC wrapper and passes it to a block. When
     # the block finishes running, the <tt>generate</tt> method is
-    # automatically called. The result of generate is then passed back
-    # to the application.
+    # automatically called. The result of <tt>generate</tt> is then
+    # passed back to the application.
     def self.create(format = PDF, &block)
       pdf = HTMLDoc.new(format)
       if block_given?
@@ -131,16 +143,16 @@ module PDF
     # or file is provided, the method will return <tt>true</tt> or
     # <tt>false</tt> to indicate completion. If no output directory or
     # file is provided, it will return a string representing the
-    # entire output.
+    # entire output. Generate will raise a PDF::HTMLDocException if
+    # the program path can't be found.
     def generate
       tempfile = nil
       unless @options[:outdir] || @options[:outfile]
         tempfile = Tempfile.new("htmldoc.temp")
         @options[:outfile] = tempfile.path
       end
-      command = @@program_path + " " + get_command_options + " " + get_command_pages + " 2>&1"
-      @result = IO.popen(command) { |s| s.read }
-      if (/BYTES/ =~ @result)
+      execute
+      if @result[:bytes]
         if tempfile
           File.open(tempfile.path, "rb") { |f| f.read }
         else
@@ -150,12 +162,46 @@ module PDF
         false
       end
     ensure
-      tempfile.close if tempfile
+      if tempfile
+        tempfile.close
+        @options[:outfile] = nil
+      end
       @tempfiles.each { |t| t.close }
     end
 
     private
 
+    def execute
+      # Reset internal variables
+      reset
+      # Execute
+      command = @@program_path + " " + get_command_options + " " + get_command_pages + " 2>&1"
+      result = IO.popen(command) { |s| s.read }
+      # Check whether the program really was executed
+      if $?.exitstatus == 127
+        raise HTMLDocException.new("Invalid program path: #{@@program_path}")
+      else
+        @result[:output] = result
+        result.split("\n").each do |line|
+          case line
+            when /^BYTES: (\d+)/
+              @result[:bytes] = $1.to_i
+            when /^PAGES: (\d+)/
+              @result[:pages] = $1.to_i
+            when /^ERROR: (.*)$/
+              @errors[0] = $1.strip
+            when /^ERR(\d+): (.*)$/
+              @errors[$1.to_i] = $2.strip
+          end
+        end
+      end
+    end
+
+    def reset
+      @result = { :bytes => nil, :pages => nil, :output => nil }
+      @errors = { }
+    end
+
     def get_command_pages
       pages = @pages.collect do |page|
         case page[:type]

data/lib/htmldoc/version.rb

@@ -5,7 +5,7 @@ module PDF
     module VERSION #:nodoc:
 
       MAJOR = 0
-      MINOR = 1
+      MINOR = 2
       TINY  = 0
 
       STRING = [MAJOR, MINOR, TINY].join(".")

data/test/generation_test.rb

@@ -23,65 +23,101 @@ class GenerationTest < Test::Unit::TestCase
     basic_test(PDF::PDF)
   end
 
+  def test_generation_results
+    pdf = PDF::HTMLDoc.new
+    pdf.set_option :webpage, true
+    pdf.set_option :toc, false
+    pdf << "<h1>Random title</h1>"
+    assert_kind_of String, pdf.generate
+    assert_not_nil pdf.result[:bytes]
+    assert_not_nil pdf.result[:pages]
+    assert_equal 0, pdf.errors.size
+    assert_equal 1, pdf.result[:pages]
+  end
+
+  def test_invalid_program_path
+    PDF::HTMLDoc.program_path = @program_path + "-non-existing-path"
+    assert_raise(PDF::HTMLDocException) { PDF::HTMLDoc.new.generate }
+  ensure
+    PDF::HTMLDoc.program_path = @program_path
+  end
+
+  def test_generation_errors
+    # This test can fail if the collapsing wavefront of the Internet
+    # somehow becomes random.
+    # Test invalid input
+    pdf = PDF::HTMLDoc.new
+    pdf.set_option :outfile, "test.pdf"
+    pdf << "http://#{simple_uid(".com")}:12345/#{simple_uid(".html")}"
+    pdf.generate
+    assert_not_equal 0, pdf.errors.size
+    assert_nil pdf.result[:bytes]
+    assert_nil pdf.result[:pages]
+    # Test an invalid option
+    pdf = PDF::HTMLDoc.new
+    pdf.set_option :outfile, "test.pdf"
+    pdf << "http://#{simple_uid(".com")}:12345/#{simple_uid(".html")} --non-existing-option"
+    pdf.generate
+    assert_not_equal 0, pdf.errors.size
+    assert_nil pdf.result[:bytes]
+    assert_nil pdf.result[:pages]
+  end
+
   private
 
   def basic_test(format)
+    # Temporary files
     path1, path2 = (1..2).collect { |i| Dir.tmpdir + "/#{i}.#{format}" }
+    # Create a temporary file for the duration of the test
     Tempfile.open("htmldoc.test") do |tempfile|
+      # Load the temporary file with some test datas
       page = "<h1>Page 1</h1><p>Test.</p><h1>Page 2</h1><p>Test.</p>"
       tempfile.binmode
       tempfile.write(page)
       tempfile.flush
-      begin
-        pdf = PDF::HTMLDoc.new(format)
-        pdf.set_option :outfile, path1
-        pdf.add_page tempfile.path
-        assert_equal true, pdf.generate
-        assert_equal pdf.result, execute_htmldoc(path2, tempfile.path, "--format #{format}")
-      ensure
-        File.delete(path1)
-        File.delete(path2)
-      end
-      begin
-        pdf = PDF::HTMLDoc.new(format)
-        pdf.set_option :outfile, path1
-        pdf.set_option :webpage, true
-        pdf.add_page tempfile.path
-        assert_equal true, pdf.generate
-        assert_equal pdf.result, execute_htmldoc(path2, tempfile.path, "--webpage --format #{format}")
-      ensure
-        File.delete(path1)
-        File.delete(path2)
-      end
-      begin
-        pdf = PDF::HTMLDoc.new(format)
-        pdf.set_option :outfile, path1
-        pdf.set_option :bodycolor, :black
-        pdf.add_page tempfile.path
-        assert_equal true, pdf.generate
-        assert_equal pdf.result, execute_htmldoc(path2, tempfile.path, "--bodycolor black --format #{format}")
-      ensure
-        File.delete(path1)
-        File.delete(path2)
-      end
-      begin
-        pdf = PDF::HTMLDoc.new(format)
-        pdf.add_page page
-        pdf.generate
-        assert_equal pdf.result, execute_htmldoc(path2, tempfile.path, "--format #{format}")
-      ensure
-        File.delete(path2)
-      end
-      begin
-        result = PDF::HTMLDoc.create(format) do |p|
-          p.set_option :outfile, path1
-          p.set_option :bodycolor, :black
-          p.add_page tempfile.path
-        end
-        assert_equal true, result
-      ensure
-        File.delete(path1)
+      # Simple format test
+      pdf = PDF::HTMLDoc.new(format)
+      pdf.set_option :outfile, path1
+      pdf.add_page tempfile.path
+      assert_equal true, pdf.generate
+      assert_equal pdf.result[:output], execute_htmldoc(path2, tempfile.path, "--format #{format}")
+      # Delete temporary files
+      File.delete(path1) if File.exists?(path1)
+      File.delete(path2) if File.exists?(path2)
+      # Simple webpag format test
+      pdf = PDF::HTMLDoc.new(format)
+      pdf.set_option :outfile, path1
+      pdf.set_option :webpage, true
+      pdf.add_page tempfile.path
+      assert_equal true, pdf.generate
+      assert_equal pdf.result[:output], execute_htmldoc(path2, tempfile.path, "--webpage --format #{format}")
+      # Delete temporary files
+      File.delete(path1) if File.exists?(path1)
+      File.delete(path2) if File.exists?(path2)
+      # Simple options test
+      pdf = PDF::HTMLDoc.new(format)
+      pdf.set_option :outfile, path1
+      pdf.set_option :bodycolor, :black
+      pdf.add_page tempfile.path
+      assert_equal true, pdf.generate
+      assert_equal pdf.result[:output], execute_htmldoc(path2, tempfile.path, "--bodycolor black --format #{format}")
+      # Delete temporary files
+      File.delete(path1) if File.exists?(path1)
+      File.delete(path2) if File.exists?(path2)
+      # Free text generate test
+      pdf = PDF::HTMLDoc.new(format)
+      pdf.add_page page
+      pdf.generate
+      assert_equal pdf.result[:output], execute_htmldoc(path2, tempfile.path, "--format #{format}")
+      # Delete temporary files
+      File.delete(path2) if File.exists?(path2)
+      # Inline generation test
+      result = PDF::HTMLDoc.create(format) do |p|
+        p.set_option :outfile, path1
+        p.set_option :bodycolor, :black
+        p.add_page tempfile.path
       end
+      assert_equal true, result
     end
   end
 
@@ -89,4 +125,11 @@ class GenerationTest < Test::Unit::TestCase
     IO.popen("#{@program_path} #{options} -f #{output} #{input} 2>&1") { |s| s.read }
   end
 
+  def simple_uid(extension)
+    chars = ('A'..'Z').to_a + ('0'..'9').to_a
+    (1..100).inject("") { |r, i| r + chars[rand(chars.length)] }
+  end
+
 end
+
+#  LocalWords:  HTMLDOC

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.0
 specification_version: 1
 name: htmldoc
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
-date: 2007-03-05 00:00:00 -03:00
+  version: 0.2.0
+date: 2007-03-07 00:00:00 -03:00
 summary: A wrapper around HTMLDOC, a PDF generation utility
 require_paths: 
 - lib