namespaced_htmldoc 0.2.3

data/History.txt

@@ -0,0 +1,25 @@
+2010-12-21:
+* Forked from github.com/craigw/htmldoc
+* Only the main code and tests were updated; it is likely that the Rakefile is
+  now invalid/broken.
+
+0.2.3
+* The htmldoc command sometimes uses \r in the output. [Jon Wood]
+
+0.2.2
+* Move source code to GitHub: http://github.com/craigw/htmldoc
+* Strings that have linebreaks in are probably not URLs.
+* If a string has a line starting what matches /https?:\/\/ it's not an 
+  URL, it's a string. [Tim Peters <http://rubyforge.org/users/tcp>]
+
+0.2.1
+* Fixed a bug in set_option where the value false would be seen as nil instead of :no
+
+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/LICENSE.txt

@@ -0,0 +1,21 @@
+Copyright (c) 2009 Craig R Webster <http://barkingiguana.com/>
+Copyright (c) 2007 Ronaldo M. Ferraz
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Manifest.txt

@@ -0,0 +1,12 @@
+History.txt
+LICENSE.txt
+Manifest.txt
+README.txt
+Rakefile
+init.rb
+lib/htmldoc.rb
+lib/htmldoc/version.rb
+setup.rb
+test/basic_test.rb
+test/generation_test.rb
+test/test_helper.rb

data/README.txt

@@ -0,0 +1,145 @@
+= HTMLDocPDF::HTMLDoc
+
+HTMLDocPDF::HTMLDoc is a wrapper around HTMLDOC, an open-source application
+that converts HTML input files into formatted HTML, PDF or PostScript
+output.
+
+It was forked from https://github.com/craigw/htmldoc specifically to change
+the root namespace from PDF:: to HTMLDocPDF::, so that it will play nice with
+other gems that use the PDF:: namespace.
+
+
+Home:: http://rubyforge.org/projects/htmldoc/
+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 I know, it will work on all platforms in which HTMLDOC is
+available. Comments, suggestions, and further tests are welcome.
+
+== LICENSE NOTES
+
+Please read the LICENCE.txt file for licensing information on this
+library.
+
+== USAGE
+
+Using HTMLDocPDF::HTMLDoc is trivial. The example below illustrates a simple
+use with an output file:
+
+  require "htmldoc"
+
+  pdf = HTMLDocPDF::HTMLDoc.new
+
+  pdf.set_option :outfile, "/tmp/outfile.pdf"
+  pdf.set_option :bodycolor, :black
+  pdf.set_option :links, true
+
+  pdf.header ".t."
+
+  pdf << "/var/doc/file1.html"
+  pdf << "/var/doc/file2.html"
+
+  pdf.footer ".1."
+
+  if pdf.generate 
+    puts "Successfully generated a PDF file"
+  end
+   
+A similar approach can be used for inline generation:
+
+  require "htmldoc"
+
+  document = HTMLDocPDF::HTMLDoc.create(HTMLDocPDF::PS) do |p|
+
+    p.set_option :bodycolor, :black
+    p.set_option :links, true
+
+    p.header ".t."
+
+    p << "http://example.org/index.html"
+    p << "http://localhost/test/data"
+
+    p << "/var/doc/file1.html"
+    p << "/var/doc/file2.html"
+
+    p << @report.to_html
+    p << "Some other text that will be incorporated in the report"
+
+    p.footer ".1."
+
+  end
+
+In the example above, it's not necessary to call the <tt>generate</tt>
+method since it will be automatically invoked by the block.
+
+You can also configure the program path for HTMLDOC if it differs in
+your system.
+
+  require "htmldoc"
+
+  HTMLDocPDF::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
+HTMLDocPDF::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
+
+* HTMLDocPDF::HTMLDoc is both a Rails plugin and a gem, which means it can be
+  installed system-wide, or just used on a Rails project without
+  further dependencies.
+
+* Under Windows, it's better to point the program path for the HTMLDOC
+  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 HTMLDocPDF::HTMLDOC makes no attempt
+  to convert any input passed to it, it's the caller's responsibility
+  to provide any necessary conversions.

data/Rakefile

@@ -0,0 +1,51 @@
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/contrib/rubyforgepublisher'
+require 'fileutils'
+require 'hoe'
+
+include FileUtils
+require File.join(File.dirname(__FILE__), 'lib', 'htmldoc', 'version')
+
+AUTHOR = "Craig R Webster"
+EMAIL = "craig@barkingiguana.com"
+DESCRIPTION = "A wrapper around HTMLDOC, a PDF generation utility"
+GEM_NAME = "htmldoc"
+RUBYFORGE_PROJECT = "htmldoc"
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+
+NAME = "HTMLDOC"
+RDOC_OPTS = ['--quiet', '--title', "htmldoc documentation",
+    "--opname", "index.html",
+    "--line-numbers", 
+    "--main", "README",
+    "--inline-source"]
+
+class Hoe
+  def extra_deps 
+    @extra_deps.reject { |x| Array(x).first == 'hoe' } 
+  end 
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+hoe = Hoe.new(GEM_NAME, HTMLDocPDF::HTMLDOC::VERSION::STRING) do |p|
+
+  p.author = AUTHOR 
+  p.email = EMAIL
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/*_test.rb"]
+  p.clean_globs = CLEAN  #An array of file patterns to delete on clean.
+  p.description = p.paragraphs_of('README.txt', 1..1).join("\n\n")
+  p.changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
+
+  #p.extra_deps     - An array of rubygem dependencies.
+  #p.spec_extras    - A hash of extra values to set in the gemspec.
+end

data/init.rb

@@ -0,0 +1 @@
+require "htmldoc"

data/lib/htmldoc/version.rb

@@ -0,0 +1,17 @@
+module HTMLDocPDF
+
+  module HTMLDOC #:nodoc:
+
+    module VERSION #:nodoc:
+
+      MAJOR = 0
+      MINOR = 2
+      TINY  = 3
+
+      STRING = [MAJOR, MINOR, TINY].join(".")
+
+    end
+
+  end
+
+end

data/lib/htmldoc.rb

@@ -0,0 +1,248 @@
+require "tempfile"
+
+module HTMLDocPDF
+
+  HTML = "html"
+  HTMLSEP = "htmlsep"
+  PDF = "pdf"
+  PDF11 = "pdf11"
+  PDF12 = "pdf12"
+  PDF13 = "pdf13"
+  PDF14 = "pdf14"
+  PS = "ps"
+  PS1 = "ps1"
+  PS2 = "ps2"
+  PS3 = "ps3"
+
+  # Exception class representing an internal error in the HTMLDoc
+  # class.
+  class HTMLDocException < StandardError; end
+
+  # The wrapper class around HTMLDOC, providing methods for setting
+  # the options for the application and retriving the generate output
+  # either as a file, diretory or string.
+  class HTMLDoc
+
+    @@basic_options = [:bodycolor, :bodyfont, :bodyimage, :bottom, :browserwidth,
+                       :charset, :continuous, :cookies, :datadir, :effectduration,
+                       :firstpage, :fontsize, :fontspacing, :footer, :gray, :header,
+                       :headerfontfoot, :headfontsize, :headingfont, :landscape,
+                       :left, :linkcolor, :linkstyle, :logoimage, :nup, :outdir,
+                       :outfile, :owner_password, :pageduration, :pageeffect,
+                       :pagelayout, :pagemode, :path, :permissions, :portrait,
+                       :referer, :right, :size, :textcolor, :textfont, :titlefile,
+                       :titleimage, :tocfooter, :tocheader, :toclevels, :toctitle,
+                       :user_password, :webpage]
+
+    @@extra_options = [:compression, :duplex, :embedfonts, :encryption, :jpeg,
+                       :links, :localfiles, :numbered, :pscommands, :strict, :title,
+                       :toc, :xrxcomments]
+
+    @@all_options = @@basic_options + @@extra_options
+
+    # The path to HTMLDOC in the system. E.g, <code>/usr/bin/html</code> or
+    # <code>"C:\Program Files\HTMLDOC\HTMLDOC.exe"</code>.
+    @@program_path = "htmldoc"
+
+    # 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
+    # contants.
+    def initialize(format = PDF)
+      @format = format
+      @options = {}
+      @pages = []
+      @tempfiles = []
+      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 <tt>generate</tt> is then
+    # passed back to the application.
+    def self.create(format = PDF, &block)
+      pdf = HTMLDoc.new(format)
+      if block_given?
+        yield pdf
+        pdf.generate
+      end
+    end
+
+    # Gets the current path for the HTMLDOC executable. This is a
+    # class method.
+    def self.program_path
+      @@program_path
+    end
+
+    # Sets the current path for the HTMLDOC executable. This is a
+    # class method.
+    def self.program_path=(value)
+      @@program_path = value
+    end
+
+    # Sets an option for the wrapper. Only valid HTMLDOC options will
+    # be accepted. The name of the option is a symbol, but the value
+    # can be anything. Invalid options will throw an exception. To
+    # unset an option, use <tt>nil</tt> as the value. Options with
+    # negated counterparts, like <tt>:encryption</tt>, can be set
+    # using false, :no or :none as the value.
+    def set_option(option, value)
+      if @@all_options.include?(option)
+        if !value.nil?
+          @options[option] = value
+        else
+          @options.delete(option)
+        end
+      else
+        raise HTMLDocException.new("Invalid option #{option.to_s}")
+      end
+    end
+
+    # Sets the header. It's the same as set_option :header, value.
+    def header(value)
+      set_option :header, value
+    end
+
+    # Sets the footer. It's the same as set_option :footer, value.
+    def footer(value)
+      set_option :footer, value
+    end
+
+    # Adds a page for generation. The page can be a URL beginning with
+    # either <tt>http://</tt> or <tt>https://</tt>; a file, which will
+    # be verified for existence; or any text.
+    def add_page(page)
+      if /\A(http|https)/ =~ page && page !~ /\r|\n/
+        type = :url
+      elsif File.exists?(page)
+        type = :file
+      else
+        type = :text
+      end
+      @pages << { :type => type, :value => page }
+    end
+
+    alias :<< :add_page
+
+    # Invokes HTMLDOC and generates the output. If an output directory
+    # 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. Generate will raise a HTMLDocPDF::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
+      execute
+      if @result[:bytes]
+        if tempfile
+          File.open(tempfile.path, "rb") { |f| f.read }
+        else
+          true
+        end
+      else
+        false
+      end
+    ensure
+      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(/\r|\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]
+          when :file, :url
+            page[:value]
+          else
+            t = Tempfile.new("htmldoc.temp")
+            t.binmode
+            t.write(page[:value])
+            t.flush
+            @tempfiles << t
+            t.path
+        end
+      end
+      pages.join(" ")
+    end
+
+    def get_command_options
+      options = @options.dup.merge({ :format => @format })
+      options = options.collect { |key, value| get_final_value(key, value) }
+      options.sort.join(" ")
+    end
+
+    def get_final_value(option, value)
+      option_name = "--" + option.to_s.gsub("_", "-")
+      if value.kind_of?(TrueClass)
+        option_name
+      elsif value.kind_of?(Hash)
+        items = value.collect { |name, contents| "#{name.to_s}=#{contents.to_s}" }
+        option_name + " '" + items.sort.join(";") + "'"
+      elsif @@basic_options.include?(option)
+        option_name + " " + value.to_s
+      else
+        if [false, :no, :none].include?(value)
+          option_name.sub("--", "--no-")
+        else
+          option_name + " " + value.to_s
+        end
+      end
+    end
+
+  end
+
+end