= PDF::HTMLDoc

PDF::HTMLDoc is a wrapper around HTMLDOC, an open-source application
that converts HTML input files into formatted HTML, PDF or PostScript
output.

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 PDF::HTMLDoc is trivial. The example below illustrates a simple
use with an output file:

  require "htmldoc"

  pdf = PDF::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 = PDF::HTMLDoc.create(PDF::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"

  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
  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 PDF::HTMLDOC makes no attempt
  to convert any input passed to it, it's the caller's responsibility
  to provide any necessary conversions.