html2odt 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f17ae59439de60f02d2bb78494d27c6e4107638b
-  data.tar.gz: 598800a2f2928bc4bfcfda35383dbb825ffd4f7f
+  metadata.gz: d2e147b6eecf0af3652facf38559813053546c6a
+  data.tar.gz: 303a83ca4cd9e86ecfe5091d911847358a79f77c
 SHA512:
-  metadata.gz: eb6e4267022ff572028c42632c6edd03f3660bd91fa013933880052ecc71de6c4009cf878c440d16bb264243bf145b9478ab73e837be30d46bc3d9c8008d7293
-  data.tar.gz: dbe23ef34a73cdbfa7661863178fc02161be4fd405ba4817a7ec4cd432f5c4c52e52b8fa41afda2b2a72c6f0fc173885a7da56423654713c81b20fcb9d3024e7
+  metadata.gz: 9d3086df185e177ea423c7a886503463918933a032741d25c96a0fe847ac089043e32275d0b533f3295124021c696d9f0af9fd83d0b6ab4f10065e417b9c24b8
+  data.tar.gz: 5114655368d6cbcd5df9b0f404f9bdc5b7d8203e3308d33eb9c86f60641cbaca2c153ccc034f890d3394559aa55b698125ce7c42ded667d9e63bc45268a36c6b

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+# v0.3.0 - 2016-05-25
+
+Adding support for `base_uri` configuration to expand links and download images
+without fully qualified URI.
+
+Adding html2odt.rb binary.
+
 # v0.2.1 - 2016-05-25
 
 Adding workarounds for HTML structures not supported by xhtml2odt.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    html2odt (0.2.1)
+    html2odt (0.3.0)
       dimensions (~> 1.3.0)
       nokogiri (~> 1.6.7.2)
       rubyzip (~> 1.0)

data/README.md

@@ -3,6 +3,20 @@
 This gem provides a Ruby wrapper around the set of XLST stylesheets published as
 [xhtml2odt](https://github.com/abompard/xhtml2odt).
 
+
+## html2odt vs. xhtml2odt
+
+So, why is this project called `html2odt` while the original library and command
+line tools by Aurélien Bompard are called **`x`**`html2odt`?
+
+This project uses [nokogiri](http://www.nokogiri.org) to parse the HTML and
+apply the XSLT transformations. Nokogiri implements a forgiving HTML parser and
+tries be as forgiving as possible. Furthermore, the basic API expects HTML
+fragments, not full documents. We are not expecting the users of this library to
+pass in a complete, valid XHTML document. A reasonably good piece of HTML should
+be good enough. Therefore we skipped the `X` in the name as well.
+
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -19,9 +33,27 @@ Or install it yourself as:
 
     $ gem install html2odt
 
+
 ## Usage
 
-### Basic usage
+### Command line Usage
+
+
+```
+Usage: html2odt.rb [options] -i input.html -o output.odt
+    -i, --input input.html
+    -o, --output output.odt
+    -t, --template <template.odt>    The file that should be filled with the input's content.
+                                     Defaults to basic template file which is part of this gem.
+    -r, --replace <KEYWORD>          A keyword in the template document to replace with the converted text.
+                                     Defaults to `{{content}}`.
+    -u, --url <URL>                  The remote URL you downloaded the page from.
+                                     This is required to include remote images and to resolve links properly.
+    -h, --help                       Show this message
+```
+
+
+### Ruby API usage
 
 ```ruby
 # Create an Html2Odt::Document instance
@@ -77,20 +109,47 @@ doc = Html2Odt::Document.new(html: <<HTML)
 HTML
 ```
 
+
+
+
+Furthermore, you may specify a `base_uri`, which will most likely be the place,
+the original HTML fragment belongs to. The `base_uri` will be used to convert
+links to fully qualified URLs, so that they still work when placed in the ODT
+document. Furthermore the setting will be used to identify the sources of
+image's found within the HTML fragments (see below for some detail).
+
+```ruby
+# Provide base_uri
+doc = Html2Odt::Document.new
+doc.base_uri = "https://www.example.com"
+```
+
+You may also pass a `URI` instance directly.
+
+```ruby
+# Provide base_uri
+doc = Html2Odt::Document.new
+doc.base_uri = URI::parse("https://www.example.com")
+```
+
+It is expected, that the URI refers to a `http(s)` location.
+
+
 ### Image handling
 
 `html2odt` provides basic image inlining, i.e. images referenced in the HTML
 code will be embeded into the ODT file by default. This is true for images
 referenced with a full `file://`, `http://`, or `https://` URL. Absolute URLs
-(i.e. starting `/`) and relative URLs are not supported, since `html2odt` has no
-idea, which server or document they are relating to.
+(i.e. starting `/`) and relative URLs are only supported if the `base_uri`
+option is set. Otherwise `html2odt` has no idea, which server or document they
+are relating to.
 
 Images referencing an unsupported resource will be replaced with a link
 containing the alt text of the image.
 
 If you are using `html2odt` in a web application context, you will probably want
 to provide some special handling for resources residing on your own server. This
-should be done for security reasons or to save roundtrips.
+should be done for security reasons and to save roundtrips.
 
 `html2odt` provides the following API to map image `src` attributes to local
 file locations.

data/bin/html2odt.rb

@@ -0,0 +1,100 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'html2odt'
+
+options = {}
+parser = OptionParser.new do |opts|
+  opts.banner = "Usage: html2odt.rb [options] -i input.html -o output.odt"
+
+  opts.on("-i", "--input input.html") do |input|
+    options[:input] = input
+  end
+
+  opts.on("-o", "--output output.odt") do |output|
+    options[:output] = output
+  end
+
+  opts.on("-t", "--template <template.odt>",
+          "The file that should be filled with the input's content.", "Defaults to basic template file which is part of this gem.") do |template|
+    options[:template] = template
+  end
+
+  opts.on("-r", "--replace <KEYWORD>",
+          "A keyword in the template document to replace with the converted text.", "Defaults to `{{content}}`.") do |replace|
+    options[:replace] = replace
+  end
+
+  opts.on("-u", "--url <URL>",
+          "The remote URL you downloaded the page from.", "This is required to include remote images and to resolve links properly.") do |url|
+    options[:url] = url
+  end
+
+  opts.on("-h", "--help",
+          "Show this message") do
+    puts opts
+    exit
+  end
+end
+
+parser.parse!
+
+if options.empty?
+  puts parser
+  exit
+end
+
+if options[:replace]
+  warn "-r option is not yet implemented, please use the default `{{content}}` place holder for now."
+  exit 1
+end
+
+
+if options[:input].nil?
+  warn "Missing -i option"
+  puts parser
+  exit 1
+end
+
+
+if options[:output].nil?
+  warn "Missing -o option"
+  puts parser
+  exit 1
+end
+
+
+
+doc = if options[:template].nil?
+  Html2Odt::Document.new
+else
+  begin
+    Html2Odt::Document.new(template: options[:template])
+  rescue ArgumentError
+    warn "Template does not match expectations - #{$!.message}"
+    exit 2
+  end
+end
+
+
+if File.readable? options[:input]
+  doc.html = File.read(options[:input])
+else
+  warn "Input does not match expectations - Cannot read input file #{options[:input].inspect}"
+  exit 3
+end
+
+
+if options[:url]
+  begin
+    doc.base_uri = options[:url]
+  rescue ArgumentError
+    warn "URL does not match expectations - #{$!.message}"
+    exit 4
+  end
+end
+
+
+doc.write_to options[:output]
+
+puts "Wrote document to: #{options[:output]}"

data/html2odt.gemspec

@@ -1,7 +1,7 @@
 # coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
+lib = File.expand_path("../lib", __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'html2odt/version'
+require "html2odt/version"
 
 Gem::Specification.new do |spec|
   spec.name          = "html2odt"
@@ -13,10 +13,11 @@ Gem::Specification.new do |spec|
   spec.description   = %q{html2odt generates ODT documents based on HTML fragments using xhtml2odt}
   spec.homepage      = "https://github.com/planio-gmbh/html2odt"
 
-  spec.license       = 'MIT'
+  spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   spec.require_paths = ["lib"]
+  spec.executables   << "html2odt.rb"
 
   spec.add_dependency "dimensions", "~> 1.3.0"
   spec.add_dependency "nokogiri", "~> 1.6.7.2"

data/lib/html2odt/document.rb

@@ -30,6 +30,25 @@ class Html2Odt::Document
     @html
   end
 
+  def base_uri=(uri)
+    if uri.is_a? URI
+      @base_uri = uri
+    else
+      @base_uri = URI::parse(uri)
+    end
+
+    unless @base_uri.is_a? URI::HTTP
+      raise ArgumentError, "Invalid URI - Expecting http(s) scheme."
+    end
+
+  rescue URI::InvalidURIError
+    raise ArgumentError, "Invalid URI - #{$!.message}"
+  end
+
+  def base_uri
+    @base_uri
+  end
+
   def content_xml
     @content_xml ||= begin
 
@@ -177,7 +196,7 @@ class Html2Odt::Document
     end
 
   rescue Zip::Error
-    raise ArgumentError, "Template file does not look like a ODT file - #{$!.message}"
+    raise ArgumentError, "Template file does not look like an ODT file - #{$!.message}"
   rescue Errno::ENOENT
     raise ArgumentError, "Template file does not contain expected file - #{$!.message}"
   end
@@ -187,6 +206,7 @@ class Html2Odt::Document
     html = self.html
     html = fix_images_in_html(html)
     html = fix_document_structure(html)
+    html = fix_links(html) if base_uri
     html = create_document(html)
     html
   end
@@ -243,6 +263,16 @@ class Html2Odt::Document
     doc.to_xml(:save_with => Nokogiri::XML::Node::SaveOptions::AS_XML)
   end
 
+  def fix_links(html)
+    doc = Nokogiri::HTML::DocumentFragment.parse(html)
+
+    doc.css("a").each do |a|
+      a["href"] = (base_uri + a["href"]).to_s
+    end
+
+    doc.to_xml(:save_with => Nokogiri::XML::Node::SaveOptions::AS_XML)
+  end
+
   def create_document(html)
     %Q{<html xmlns="http://www.w3.org/1999/xhtml">#{html}</html>}
   end
@@ -252,22 +282,27 @@ class Html2Odt::Document
       return image_location_mapping.call(src)
     end
 
-    case src
-    when /\Afile:\/\//
+    if src =~ /\Afile:\/\//
       # local file URL
       #
       # TODO: Verify, that this does not pose a security threat, maybe make
       # this optional. In any case, it's useful for testing.
 
-      src[7..-1]
+      return src[7..-1]
+    end
 
-    when /\Ahttps?:\/\//
+    if src =~ /\Ahttps?:\/\// or !base_uri.nil?
       # remote image URL
       #
       # TODO: Verify, that this does not pose a security threat, maybe make
       # this optional.
 
-      uri = URI.parse(src)
+      if base_uri
+        uri = base_uri + src
+      else
+        uri = URI.parse(src)
+      end
+
       file = Tempfile.new("html2odt")
       file.binmode
 
@@ -279,11 +314,11 @@ class Html2Odt::Document
         file
       end
 
-      file.path
-    else
-      # cannot handle image properly, return nil
-      nil
+      return file.path
     end
+
+    # cannot handle image properly, return nil
+    nil
   end
 
   def update_img_tag(img, image)

data/lib/html2odt/version.rb

@@ -1,3 +1,3 @@
 module Html2Odt
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: html2odt
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Gregor Schmidt (Planio)
@@ -112,7 +112,8 @@ description: html2odt generates ODT documents based on HTML fragments using xhtm
 email:
 - gregor@plan.io
 - support@plan.io
-executables: []
+executables:
+- html2odt.rb
 extensions: []
 extra_rdoc_files: []
 files:
@@ -125,6 +126,7 @@ files:
 - README.md
 - Rakefile
 - bin/console
+- bin/html2odt.rb
 - html2odt.gemspec
 - lib/html2odt.rb
 - lib/html2odt/document.rb