caracal 1.4.1 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07032410054f6b6e5b8d640aa391c24382eda9461832b7f3fb0fe2bb9203164f
-  data.tar.gz: 780ae708802f68185d556d6ec0dc28b5fdb86adefc6043ec18bf32027440278b
+  metadata.gz: c06f9a2d1fafe9fc3cbc91db5bab3d08a374ef0b688ff188a200e175f0c72073
+  data.tar.gz: 7dd9194ecb1a0d84e9e5953a334f0fc5754fbd696305e8fa21a8563f95c2a3fa
 SHA512:
-  metadata.gz: 136540cd7409584e274462d2f43b7b21f4533a4351611ea41f0db03fd6282a366d01c0a5d1f6b4d05d7674d9bdd9f939b536ba569189407abcfe253e8fc524c8
-  data.tar.gz: d9c61a1f362f43625aaa3160639f903ebd003df993dc8e78c17e456bb1a1205aef94b5e1dc8cdf9b69136ba71786bb2eeee03f8e26ae35c1862ea329d1fe9162
+  metadata.gz: 56a868f230d4ae1ad7ab96f1e001aca3efac537026cf3e23f66936e18f8779e692fccc52c1118a55b25a5750e8aeda51e7e347c16b37264c598682cc9aba0748
+  data.tar.gz: '02099d9534ed1c0d950028f7dc937e47394082d2f05a4909f554a68a052f1d58f8ed84be30a55f2e91a15e240dc805b65b2e42ac1104b6989965b797ad573f98'

data/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Ruby ${{ matrix.ruby }} / rubyzip ${{ matrix.rubyzip }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ['3.1', '3.2', '3.3', '3.4', '4.0']
+        rubyzip: ['~> 1.3', '~> 3.4']
+    env:
+      RUBYZIP_VERSION: ${{ matrix.rubyzip }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - run: bundle exec rspec

data/.github/workflows/push_gem.yml

@@ -0,0 +1,29 @@
+name: Push gem
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  push:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+      id-token: write
+
+    environment: release
+
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+          ruby-version: ruby
+
+      - uses: rubygems/release-gem@v1

data/CHANGELOG.md

@@ -1,10 +1,59 @@
+#### v1.6.0
+
+* Enhancements
+  * Added `header` and `footer`, which accept the same content as the document body: paragraphs, images, tables and links. Images and links resolve through each part's own relationships. (@benjaminketron, @jamesridgway, @dlauer)
+  * Added the `field` paragraph method, which inserts a `:page` or `:numpages` field, so a footer can read "Page 2 of 7". (@benjaminketron, @jamesridgway, @dlauer)
+  * Added a different first page: `header first: true` and `footer first: true` give the first page its own header or footer, or leave it blank when called without a block, and `page_numbers first_page: false` leaves the number off the first page. (@dlauer)
+  * Added the `start` option to `page_numbers`, which sets the number of the first page. (@dlauer)
+  * `img` now accepts `data:` and `ppi:` as options, not only inside its block. Previously the options were silently dropped and the image was read from the path instead. (@victorpolko, @dlauer)
+  * `keep_next`, `header_rows`, the list style `restart` and the page number `size` are likewise accepted as options. (@dlauer)
+  * Entries read from documents embedded with `iframe` are capped by `IFrameModel.max_entry_size` (50MB by default), so a small upload cannot expand into an arbitrarily large allocation. (@dlauer)
+  * Raised the nokogiri floor to 1.16.2 and added source, changelog and issue tracker links to the gem metadata. (@dlauer)
+
+* Changes
+  * `footer` and `page_numbers` now combine, with the page number rendered below the footer content. Previously `page_numbers` replaced the footer.
+  * `header` and `footer` raise `InvalidModelError` when given an empty block.
+
+* Bug Fixes
+  * Page numbers are rendered as a complete complex field, so viewers that do not evaluate fields, such as WPS Office, show the number rather than "PAGE". (@dlauer)
+  * Text added to a list item after a nested list now appears after that list, aligned with the item's text, rather than before it. An item can also hold more than one nested list. (@dlauer)
+  * Documents written with rubyzip 3 no longer carry zip64 records, which LibreOffice 7.4 and earlier refuse to open. (@dlauer)
+
+
+#### v1.5.0
+
+* Enhancements
+  * Added the `keep_next` paragraph property, which keeps a paragraph on the same page as the one following it. (@benjaminketron)
+  * Added the `header_rows` table method, which repeats the leading rows of a table after each page break. (@benjaminketron)
+  * Added the `cant_split` and `cant_split?` table methods, which keep a row from splitting across a page break. (@benjaminketron)
+  * Added the `column_widths` table method, which sets the table grid explicitly instead of deriving it from the first row. (@martinsp)
+  * Widened the rubyzip dependency to `>= 1.1.6, < 4.0`, allowing rubyzip 3.x. (@acwertman)
+  * Added continuous integration across Ruby 3.1-4.0 and both supported rubyzip lines. (@dlauer)
+  * Declared `required_ruby_version >= 3.1`. (@dlauer)
+  * Documented the trust contract for image and iframe sources in a new Security section. (@dlauer)
+
+* Bug Fixes
+  * Images and iframes are no longer loaded through `Kernel#open`, which executed a target beginning with `|` as a shell command, stopped fetching URLs entirely on Ruby 3.0 and later, and read in text mode on Windows, corrupting image data. Both are now read in binary, with `URI.open` for http(s) targets and `File.binread` for local paths. (@LItterBoy-GB, @dlauer)
+  * Removed control characters that XML does not permit from text, links, table cells, page number labels and custom properties. A single such character made Word reject the entire document. (@dlauer)
+  * Image part names and content types are now derived from the image data when it is supplied, rather than from the URL. This fixes presigned URLs, extensionless URLs and images carried in embedded documents. Registered content types for bmp, tiff and svg. (@dlauer)
+  * `iframe` now works inside table cells. (@catmando, @dlauer)
+  * Raised the rubyzip floor past versions whose `write_buffer` required an argument, which raised `ArgumentError` on save. (@acwertman)
+  * Corrected the documented units for table border and rule spacing, which are points rather than twips or eighths of a point. (@dlauer)
+
+
+#### v1.4.1
+
+* Bug Fixes
+  * Corrected rowspan logic to handle all cases. (@martinsp)
+
+
 #### v1.4.0
 
 * Enhancements
   * Changed `file_name` method to accept absolute and relative paths. (@jdugan)
   * Added instance save method so documents can be created via commands instead of blocks, if desired. (@jdugan)
   * Removed extra paragraph tag inserted after tables; added logic to ensure final tag of table cells is always a paragraph. (@jdugan)
-  
+
 
 #### v1.3.0
 

data/Gemfile

@@ -1,3 +1,6 @@
 source 'https://rubygems.org'
 
 gemspec
+
+# lets CI test against specific rubyzip versions
+gem 'rubyzip', ENV['RUBYZIP_VERSION'] if ENV['RUBYZIP_VERSION']

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2014 Trade Informatics, Inc.
+Copyright (c) 2014 Urvin LLC
 
 MIT License
 

data/README.md

@@ -11,7 +11,7 @@ Caracal is not a magical HTML to Word translator. Instead, it is a markup langua
 
 Or, said differently, if you use [Prawn](https://github.com/prawnpdf/prawn) for PDF generation, you'll probably like Caracal. Only you'll probably like it better. :)
 
-Please see the [caracal-example](https://github.com/trade-informatics/caracal-example) repository for
+Please see the [caracal-example](https://github.com/urvin-compliance/caracal-example) repository for
 a working demonstration of the library's capabilities.
 
 
@@ -207,6 +207,19 @@ All Caracal models perform basic validations on their attributes, but this is, w
 In forthcoming versions of Caracal, we'll be looking to expand the `InvalidModelError` class to provide broader error reporting abilities across the entire library.
 
 
+## Security
+
+Caracal reads whatever path or URL you hand it. Both `img` and `iframe` accept a local filesystem path or an http(s) URL, and Caracal reads or fetches it while the document renders.
+
+**Treat those values as trusted input.** If a path or URL can be influenced by an end user, validate it before passing it to Caracal:
+
+* **Local paths** are read with the permissions of your application's process. Any file that process can read can be embedded in the generated document, so `docx.img '/etc/passwd'` embeds the contents of that file.
+* **URLs** are fetched from your application's network position, and redirects are followed. A user-supplied URL can therefore reach internal services, `localhost`, or cloud metadata endpoints that are not otherwise reachable from outside.
+* **Documents embedded with `iframe`** are parsed, and their markup is copied into your output. Only embed documents you trust. See [IFrames](#iframes).
+
+Caracal deliberately does not restrict paths, hosts, or directories, because it cannot know what is legitimate for your application. That policy belongs in your code: an allowlist of permitted directories or hosts, or simply never passing user-supplied values through to Caracal.
+
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -308,14 +321,61 @@ Page numbers can be added to the footer via the `page_numbers` method.  The meth
 docx.page_numbers true do
   align        :right  # sets the alignment. accepts :left, :center, and :right.
   label        'Page'  # sets the text that will go to the left of the page number. Defaults to nil.
-  size:        24      # sets the label and number size simultaneously. units in half points.
-  label_size:  24      # sets the label size only. units in half points.
-  number_size: 20      # sets the number size only. units in half points.
+  size         24      # sets the label and number size simultaneously. units in half points.
+  label_size   24      # sets the label size only. units in half points.
+  number_size  20      # sets the number size only. units in half points.
 end
 ```
 
 The `size` option and the `label_size` and `number_size` options are mutually exclusive.
 
+The `start` option sets the number of the first page, which is useful when the document continues another one, or has a cover page you don't want counted. It also applies to `field :page` in a custom footer, so it can be set without showing the built-in page number:
+
+```ruby
+docx.page_numbers true, start: 0   # the cover page is page 0, so the next page is page 1
+docx.page_numbers start: 12        # number from 12 without the built-in page number
+```
+
+### Headers and Footers
+
+A header or footer that appears on every page can be added with the `header` and `footer` methods. Their blocks accept the same paragraph, list, table, rule and image methods as the document body.
+
+```ruby
+docx.header do
+  img 'logo.png', width: 120, height: 32, align: :right
+  p 'Quarterly Report', align: :center
+end
+
+docx.footer do
+  p align: :center do
+    text 'Page '
+    field :page
+    text ' of '
+    field :numpages
+  end
+end
+```
+
+If you also turn on `page_numbers`, the page number is rendered below the footer content.
+
+*Headers and footers must contain content. Calling `header` or `footer` with an empty block raises an `InvalidModelError`.*
+
+#### Different First Page
+
+Pass `first: true` to give the first page its own header or footer, such as a cover page. Without a block, it leaves the first page's header or footer blank. Use `first_page: false` to leave the page number off the first page.
+
+```ruby
+docx.header first: true do       # replaces the header on the first page only
+  p 'Annual Report 2026', align: :center, size: 36
+end
+
+docx.header first: true          # no header on the first page
+docx.footer first: true          # no footer content on the first page
+
+docx.page_numbers true, first_page: false   # no page number on the first page
+```
+
+When the first page has its own header or footer, any part you don't set for it falls back to the default. So `first_page: false` on its own hides only the page number, and the default header and footer content still appear.
 
 ### Fonts
 
@@ -415,6 +475,7 @@ docx.p 'Sample text.' do
   bgcolor         'cccccc'          # sets the background color.
   highlight_color 'yellow'          # sets the highlight color. only accepts OOXML enumerations. see http://www.datypic.com/sc/ooxml/t-w_ST_HighlightColor.html.
   vertical_align  'superscript'     # sets the vertical alignment.
+  keep_next       false             # sets whether or not to keep this paragraph with the next paragraph when separated by page break.
 end
 ```
 
@@ -432,6 +493,16 @@ docx.p do
 end
 ```
 
+Fields that Word fills in can be added with the `field` method. It accepts `:page` (the current page number) and `:numpages` (the total number of pages), along with the same formatting options as `text`.
+
+```ruby
+docx.p do
+  text 'Page '
+  field :page, bold: true
+  text ' of '
+  field :numpages
+end
+```
 
 ### Links
 
@@ -505,7 +576,7 @@ docx.hr do
   color   '333333'   # sets the color of the line. defaults to auto.
   line    :double    # sets the line style (single or double). defaults to single.
   size    8          # sets the thickness of the line. units in 1/8 points. defaults to 4.
-  spacing 4          # sets the spacing around the line. units in 1/8 points. defaults to 1.
+  spacing 4          # sets the space between the line and the surrounding text. units in points. defaults to 1.
 end
 ```
 
@@ -561,7 +632,7 @@ docx.ul do
 end
 ```
 
-Lists can nested as many levels deep as you wish and mixed in any combination.
+Lists can be nested as many levels deep as you wish and mixed in any combination. An item can contain more than one nested list. Text that follows a nested list renders after it, as an unnumbered paragraph aligned with the item's text.
 
 ```ruby
 docx.ul do
@@ -610,6 +681,7 @@ Images can be added by using the `img` method.  The method accepts several optio
 ```ruby
 docx.img 'https://www.example.com/logo.png' do
   data    raw_data  # sets the file data directly instead of opening the url
+  ppi     72        # sets the pixels per inch used to convert width and height. defaults to 72.
   width   396       # sets the image width. units specified in pixels.
   height  216       # sets the image height. units specified in pixels.
   align   :right    # controls the justification of the image. default is :left.
@@ -620,11 +692,23 @@ docx.img 'https://www.example.com/logo.png' do
 end
 ```
 
+Every setting can also be passed as an option instead of in a block:
+
+```ruby
+docx.img 'logo.png', data: File.binread('path/to/logo.png'), width: 396, height: 216
+```
+
+*Note: `data` must be the raw bytes of the image, not Base64. Caracal writes it
+into the document unchanged, so Base64-encoded data produces a corrupt image.
+Read files with `File.binread` so line endings are not translated on Windows.*
+
 *Note: If you provide the image data, you should still supply a URL. I know this
 is a bit hacky, but it allows the library to key the image more effectively and
 Caracal needs a file extension to apply to the renamed media file. This seemed
 the simplest solution to both problems.*
 
+*If the URL or path can come from user input, read [Security](#security) first. Caracal will read any local file your process can read, and will fetch any URL you give it.*
+
 
 ### Tables
 
@@ -632,7 +716,7 @@ the simplest solution to both problems.*
 Release v1.4.0 deprecated the behaviour of automatically adding an empty paragraph tag after every table. If you are upgrading from an older version of the library, you will need to control such spacing in your own code.
 ```
 
-Tables can be added using the `table` method.  The method accepts several optional paramters to control the layout and style of the table cells.
+Tables can be added using the `table` method.  The method accepts several optional parameters to control the layout and style of the table cells.
 
 The `table` command accepts data in the form of a two-dimensional arrays. This corresponds to rows and column cells within those rows.  Each array item can be a string, a Hash of options, a Proc (which will be passed as a block), or a `TableCellModel`.  The command will normalize all array contents into a two-dimensional array of `TableCellModel` instances.
 
@@ -640,8 +724,20 @@ The `table` command accepts data in the form of a two-dimensional arrays. This c
 docx.table [['Header 1','Header 2'],['Cell 1', 'Cell 2']] do
   border_color   '666666'   # sets the border color. defaults to 'auto'.
   border_line    :single    # sets the border style. defaults to :single. see OOXML docs for details.
-  border_size    4          # sets the border width. defaults to 0. units in twips.
-  border_spacing 4          # sets the spacing around the border. defaults to 0. units in twips.
+  border_size    4          # sets the border width. defaults to 0. units in 1/8 points.
+  border_spacing 4          # sets the space between the border and the cell text. defaults to 0. units in points.
+  column_widths  [2400, 1200]
+                            # sets an explicit width for each column in the table grid. units in twips.
+                            # defaults to the widths of the cells in the first row.
+end
+```
+
+By default, the table grid is built from the cells in the first row. When that row contains a cell with a `colspan`, the grid can't be derived from it correctly and every column ends up the same width. `column_widths` sets the grid explicitly instead, taking one width per column.
+
+```ruby
+docx.table [['Spans two columns'], ['Cell 1', 'Cell 2']] do
+  cell_style rows[0][0], colspan: 2
+  column_widths [2400, 1200]
 end
 ```
 
@@ -683,6 +779,31 @@ end
 
 *Note: content of cells 21 and 24 will disappear*
 
+Table rows can be marked as header rows using the `header_rows` method which takes a number indicating how many rows from the top of the table should be marked as such. This has the effect of repeating these rows after each page break.
+
+```ruby
+docx.table [['Header 1', 'Header 2'],['Cell 1', 'Cell 2']] do
+  header_rows 1
+end
+```
+
+Row can be marked as can't split rows that re-position themselves at the top of the next if they would have otherwise split across a page break.
+
+```
+docx.table [['11', '22'], ['14', '25'], ['64', '23']] do
+  cant_split rows[1]
+end
+```
+
+or
+
+```
+docx.table [['11', '22'], ['14', '25'], ['64', '23']] do
+  cant_split rows[1...-1]
+end
+```
+
+
 ### Table Cells
 
 If your table contains more complex data (multiple paragraphs, images, lists, etc.), you will probably want to instantiate your `TableCellModel` instances directly.  With the exception of page breaks, table cells can contain anything the document can contain, including another table.
@@ -760,17 +881,19 @@ will not operate as expected in the parent Caracal document.
 
 Again, this feature is considered experimental.  Use at your own risk/discretion.
 
+**Only embed documents you trust.** Caracal parses the file you supply and copies its markup into your output, so the embedded document controls part of the result. Caracal also places no limit on how much data it will decompress while reading the file, so a small crafted document can expand to an arbitrarily large one in memory. Documents uploaded by untrusted users should not be passed to `iframe` without your own validation. See [Security](#security).
+
 
 ## Template Rendering
 
 Caracal includes [Tilt](https://github.com/rtomayko/tilt) integration to facilitate its inclusion in other frameworks.
 
-Rails integration can be added via the [Caracal-Rails](https://github.com/trade-informatics/caracal-rails) gem.
+Rails integration can be added via the [Caracal-Rails](https://github.com/urvin-compliance/caracal-rails) gem.
 
 
 ## Using Variables
 
-Lexical scope is a pretty big challenge for Caracal and it often confuses new users. This [closed issue](https://github.com/trade-informatics/caracal/issues/71) covers the discussion both from the user and library persepctive.
+Lexical scope is a pretty big challenge for Caracal and it often confuses new users. This [closed issue](https://github.com/urvin-compliance/caracal/issues/71) covers the discussion both from the user and library persepctive.
 
 
 ## Filing an Issue
@@ -789,7 +912,7 @@ happy to answer questions and provide what guidance we can. We just won't write
 
 For those using reasonably current versions of Word, please consider the following:
 
-- Before you file an issue, please run the example Caracal project [caracal-example](https://github.com/trade-informatics/caracal-example) in your development environment and
+- Before you file an issue, please run the example Caracal project [caracal-example](https://github.com/urvin-compliance/caracal-example) in your development environment and
 check the output.  This project implements nearly every feature Caracal supports and renders the expected output
 correctly.  It can be thought of as a canonical implementation of the library.
 
@@ -818,7 +941,7 @@ for 2010/2013, a set for 2016, etc.).
 
 ## Contributing
 
-1. Fork it ( https://github.com/trade-informatics/caracal/fork )
+1. Fork it ( https://github.com/urvin-compliance/caracal/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
@@ -837,6 +960,6 @@ A tip of the hat to the wonderful PDF generation library [Prawn](https://github.
 
 ## License
 
-Copyright (c) 2014 Trade Informatics, Inc
+Copyright (c) 2014 Urvin LLC
 
-[MIT License](https://github.com/trade-informatics/caracal/blob/master/LICENSE.txt)
+[MIT License](https://github.com/urvin-compliance/caracal/blob/master/LICENSE.txt)

data/caracal.gemspec

@@ -6,23 +6,31 @@ require 'caracal/version'
 Gem::Specification.new do |spec|
   spec.name          = 'caracal'
   spec.version       = Caracal::VERSION
-  spec.authors       = ['Trade Infomatics', 'John Dugan']
-  spec.email         = ['jpdugan@gmail.com']
+  spec.authors       = ['Urvin LLC', 'Dave Lauer']
+  spec.email         = ['dave@plia.com']
   spec.summary       = %q{ Fast, professional Microsoft Word (docx) writer for Ruby. }
   spec.description   = %q{ Caracal is a pure Ruby Microsoft Word generation library that produces professional quality MSWord documents (docx) using a simple, HTML-style DSL. }
-  spec.homepage      = 'https://github.com/trade-informatics/caracal'
+  spec.homepage      = 'https://github.com/urvin-compliance/caracal'
   spec.license       = 'MIT'
 
+  spec.metadata      = {
+    'source_code_uri' => 'https://github.com/urvin-compliance/caracal',
+    'changelog_uri'   => 'https://github.com/urvin-compliance/caracal/blob/master/CHANGELOG.md',
+    'bug_tracker_uri' => 'https://github.com/urvin-compliance/caracal/issues'
+  }
+
   spec.files         = `git ls-files -z`.split("\x0")
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'nokogiri', '~> 1.6'
-  spec.add_dependency 'rubyzip',  '~> 1.1'
+  spec.required_ruby_version = '>= 3.1'
+
+  spec.add_dependency 'nokogiri', '>= 1.16.2', '< 2.0'
+  spec.add_dependency 'rubyzip',  '>= 1.1.6', '< 4.0'
   spec.add_dependency 'tilt',     '>= 1.4'
 
-  spec.add_development_dependency 'bundler',  '~> 1.3'
-  spec.add_development_dependency 'rake',     '~> 10.0'
+  spec.add_development_dependency 'bundler',  '>= 1.3'
+  spec.add_development_dependency 'rake',     '>= 10.0'
   spec.add_development_dependency 'rspec',    '~> 3.0'
 end

data/lib/caracal/core/footer.rb

@@ -0,0 +1,50 @@
+require 'caracal/core/models/footer_model'
+require 'caracal/errors'
+
+
+module Caracal
+  module Core
+
+    # This module encapsulates all the functionality related to adding a
+    # footer on every page of the document.
+    #
+    module Footer
+      def self.included(base)
+        base.class_eval do
+
+          #-------------------------------------------------------------
+          # Public Methods
+          #-------------------------------------------------------------
+
+          # With `first: true` the footer replaces the default one on the
+          # first page only. Without a block it leaves the first page's
+          # footer blank.
+          #
+          def footer(*args, &block)
+            options = Caracal::Utilities.extract_options!(args)
+            first   = options.delete(:first)
+
+            model = Caracal::Core::Models::FooterModel.new(options, &block)
+            if first
+              @first_footer_content = model
+            elsif model.valid?
+              @footer_content = model
+            else
+              raise Caracal::Errors::InvalidModelError, 'footer must contain at least one paragraph, list, table, rule or image.'
+            end
+            model
+          end
+
+          def footer_content
+            @footer_content
+          end
+
+          def first_footer_content
+            @first_footer_content
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/caracal/core/header.rb

@@ -0,0 +1,49 @@
+require 'caracal/core/models/header_model'
+require 'caracal/errors'
+
+
+module Caracal
+  module Core
+
+    # This module encapsulates all the functionality related to adding a header
+    # to every page of the document.
+    #
+    module Header
+      def self.included(base)
+        base.class_eval do
+
+          #-------------------------------------------------------------
+          # Public Methods
+          #-------------------------------------------------------------
+
+          # With `first: true` the header replaces the default one on the
+          # first page only. Without a block it leaves the first page's
+          # header blank.
+          #
+          def header(*args, &block)
+            options = Caracal::Utilities.extract_options!(args)
+            first   = options.delete(:first)
+
+            model = Caracal::Core::Models::HeaderModel.new(options, &block)
+            if first
+              @first_header_content = model
+            elsif model.valid?
+              @header_content = model
+            else
+              raise Caracal::Errors::InvalidModelError, 'header must contain at least one paragraph, list, table, rule or image.'
+            end
+            model
+          end
+
+          def header_content
+            @header_content
+          end
+
+          def first_header_content
+            @first_header_content
+          end
+        end
+      end
+    end
+  end
+end

data/lib/caracal/core/iframes.rb

@@ -20,11 +20,16 @@ module Caracal
             model = Caracal::Core::Models::IFrameModel.new(options, &block)
             if model.valid?
               model.preprocess!
-              model.namespaces.each do |(prefix, href)|
-                namespace({ prefix: prefix, href: href })
-              end
-              model.ignorables.each do |prefix|
-                ignorable(prefix)
+
+              # table cells can't hold namespaces; the document
+              # collects those when it renders.
+              if respond_to?(:namespace)
+                model.namespaces.each do |(prefix, href)|
+                  namespace({ prefix: prefix, href: href })
+                end
+                model.ignorables.each do |prefix|
+                  ignorable(prefix)
+                end
               end
 
               contents << model

data/lib/caracal/core/models/border_model.rb

@@ -18,7 +18,7 @@ module Caracal
         const_set(:DEFAULT_BORDER_COLOR,    'auto')
         const_set(:DEFAULT_BORDER_LINE,     :single) 
         const_set(:DEFAULT_BORDER_SIZE,     4)        # 0.5pt in 1/8 points
-        const_set(:DEFAULT_BORDER_SPACING,  1)        # 0.125pt in 1/8 points
+        const_set(:DEFAULT_BORDER_SPACING,  1)        # 1pt. w:space is measured in points, not 1/8 points.
         const_set(:DEFAULT_BORDER_TYPE,     :top)
         
         # accessors