htmldoc

= 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 generate 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 pdf 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.