pdf-writer 1.0.1 → 1.1.0

data/lib/pdf/writer/lang/en.rb

@@ -6,7 +6,7 @@
 #   Licensed under a MIT-style licence. See LICENCE in the main distribution
 #   for full licensing information.
 #
-# $Id: en.rb,v 1.7 2005/06/08 12:16:11 austin Exp $
+# $Id: en.rb,v 1.9 2005/06/28 21:32:17 austin Exp $
 #++
   # PDF::Writer::Lang::EN is the English-language output module. It contains a
   # hash, @message, that contains the messages that may be reported by any
@@ -19,6 +19,26 @@ module PDF::Writer::Lang::EN
     :invalid_pos                    => ":pos must be either :before or :after.",
     :req_FPXO                       => "Pages#<< requires a PDF::Writer::Page, PDF::Writer::Font, or PDF::Writer::ExternalObject.",
     :req_FPXOH                      => "Pages#add requires a PDF::Writer::Page, PDF::Writer::Font, PDF::Writer::ExternalObject, or Hash.",
+    :text_width_parameters_reversed => <<-EOS,
+  %s
+As of PDF::Writer 1.1, the signature for #text_width and #text_line_width
+is (text, size), not (size, text). It appears that the old version is still
+in use in your code. Please change it.
+    EOS
+    :add_text_parameters_reversed   => <<-EOS,
+  %s
+As of PDF::Writer 1.1, the signature for #add_text is (x, y, text, size,
+angle, word_space_adjust), not (x, y, size, text, angle, word_space_adjust).
+It appears that the old version is still in use in your code. Please change
+it.
+    EOS
+    :add_textw_parameters_reversed  => <<-EOS,
+  %s
+As of PDF::Writer 1.1, the signature for #add_text_wrap is (x, y, text,
+size, justification, angle, test), not (x, y, size, text, justification,
+angle, test). It appears that the old version is still in use in your
+code. Please change it.
+    EOS
     :png_invalid_header             => "Invalid PNG header.",
     :png_unsupp_compres             => "Unsupported PNG compression method.",
     :png_unsupp_filter              => "Unsupported PNG filter method.",
@@ -28,9 +48,10 @@ module PDF::Writer::Lang::EN
     :data_must_be_array             => "The table data is not an Array. (Temporary limitation.)",
     :columns_unspecified            => "Columns are unspecified. They must be data[0] and be an array.",
     :no_zlib_no_compress            => "Could not load Zlib. PDF compression is disabled.",
+    :ttf_licence_no_embedding       => "The TrueType font %1s has a licence that does not allow for embedding.",
     :simpletable_columns_undefined  => "Columns are undefined for table.",
     :simpletable_data_empty         => "Table data is empty.",
-    :techbook_eval_exception        => <<-EOS ,
+    :techbook_eval_exception        => <<-EOS,
 
 Error in document around line %d:
   %s

data/lib/pdf/writer/object/font.rb

@@ -6,7 +6,7 @@
 #   Licensed under a MIT-style licence. See LICENCE in the main distribution
 #   for full licensing information.
 #
-# $Id: font.rb,v 1.3 2005/05/25 11:19:50 austin Exp $
+# $Id: font.rb,v 1.5 2005/06/28 21:32:17 austin Exp $
 #++
   # An object to hold the font description
 class PDF::Writer::Object::Font < PDF::Writer::Object
@@ -17,44 +17,36 @@ class PDF::Writer::Object::Font < PDF::Writer::Object
 
     @name     = name
     @subtype  = subtype
-    @encoding = encoding
-
     @font_id  = @parent.__send__(:generate_font_id)
 
     if encoding.kind_of?(PDF::Writer::Object::FontEncoding)
-      @encoding = nil
-      @encodingDictionary = encoding
+      @encoding           = encoding
     elsif encoding == 'none' or encoding.nil?
-      @encoding = nil
+      @encoding           = nil
+    else
+      @encoding           = encoding
     end
 
     @parent.pages << self
 
-    @encodingDictionary = nil
-    @firstchar          = nil
-    @lastchar           = nil
-    @widths             = nil
-    @fontdescriptor     = nil
+    @firstchar      = nil
+    @lastchar       = nil
+    @widths         = nil
+    @fontdescriptor = nil
   end
 
   attr_reader :font_id
-  attr_accessor :subtype
+    # The type of the font: Type1 and TrueType are the only values supported
+    # by 
+  attr_reader :subtype
     # Valid values: WinAnsiEncoding, MacRomanEncoding, MacExpertEncoding,
-    # none, +nil+
-  attr_accessor :encoding
-  attr_reader :encodingDictionary
-  def encodingDictionary=(ed)
-    @encodingDictionary = ed
-  end
-
-  def basefont
+    # none, +nil+, or an instance of PDF::Writer::Object::FontEncoding.
+  attr_reader :encoding
+  attr_reader :basefont
+  def basefont #:nodoc:
     @name
   end
 
-  def basefont=(b)
-    @name = basefont
-  end
-
   Details.each do |d|
     attr_accessor d.downcase.intern
   end
@@ -62,10 +54,10 @@ class PDF::Writer::Object::Font < PDF::Writer::Object
   def to_s
     res = "\n#{@oid} 0 obj\n<< /Type /Font\n/Subtype /#{@subtype}\n"
     res << "/Name /F#{@font_id}\n/BaseFont /#{@name}\n"
-    if @encodingDictionary.nil?
-      res << "/Encoding /#{@encoding}\n"
-    else
-      res << "/Encoding #{@encodingDictionary.oid} 0 R\n"
+    if @encoding.kind_of?(PDF::Writer::Object::FontEncoding)
+      res << "/Encoding #{@encoding.oid} 0 R\n"
+    elsif @encoding
+      res << "/Encoding /#{@encoding}\n" if @encoding
     end
     res << "/FirstChar #{@firstchar}\n" unless @firstchar.nil?
     res << "/LastChar #{@lastchar}\n" unless @lastchar.nil?

data/lib/pdf/writer/object/fontencoding.rb

@@ -6,7 +6,7 @@
 #   Licensed under a MIT-style licence. See LICENCE in the main distribution
 #   for full licensing information.
 #
-# $Id: fontencoding.rb,v 1.2 2005/05/16 03:59:21 austin Exp $
+# $Id: fontencoding.rb,v 1.4 2005/06/28 21:32:17 austin Exp $
 #++
   # The font encoding
 class PDF::Writer::Object::FontEncoding < PDF::Writer::Object
@@ -24,16 +24,17 @@ class PDF::Writer::Object::FontEncoding < PDF::Writer::Object
     res = "\n#{@oid} 0 obj\n<< /Type /Encoding\n"
     enc = @encoding || 'WinAnsiEncoding'
     res << "/BaseEncoding /#{enc}\n" unless enc == 'none'
-    res << "/Differences \n["
-    n = -100
-    differences.each do |k, v|
-      if k != (n + 1)
-        res << "\n#{k} /#{v}" # Cannot make use of consecutive numbering
-      else
-        res << " /#{v}"
+    unless @differences.nil? or @differences.empty?
+      res << "/Differences \n["
+      n = nil
+      @differences.keys.sort.each do |k|
+          # Cannot make use of consecutive numbering
+        res << "\n#{k} " if n.nil? or k != (n + 1)
+        res << " /#{@differences[k]}"
+        n = k
       end
-      n = k
+      res << "\n]"
     end
-    res << "\n]\n>>\nendobj"
+    res << "\n>>\nendobj"
   end
 end

data/manual.pwd

@@ -1,4 +1,4 @@
-# This is the main manual for PDF::Writer. It is interpreted by manual.rb,
+# This is the main manual for PDF::Writer. It is interpreted by PDF::TechBook
 # which implements an interpreter for the simple markup language presented
 # here.
 #
@@ -100,8 +100,8 @@
 pdf.techbook_encoding  = {
   :encoding     => 'WinAnsiEncoding',
   :differences  => {
+    169 => "copyright",
     215 => "multiply",
-    148 => "copyright",
   }
 }
 .endeval }}}
@@ -116,10 +116,10 @@ pdf.open_object do |heading|
 
   s = 6
   t = "PDF::Writer for Ruby ~ Manual"
-  w = pdf.text_width(s, t) / 2.0
+  w = pdf.text_width(t, s) / 2.0
   x = pdf.margin_x_middle
   y = pdf.absolute_top_margin
-  pdf.add_text(x - w, y, s, t)
+  pdf.add_text(x - w, y, t, s)
 
   x = pdf.absolute_left_margin
   w = pdf.absolute_right_margin
@@ -141,7 +141,7 @@ pdf.open_object do |footing|
   t = "http://rubyforge.org/projects/ruby-pdf"
   x = pdf.absolute_left_margin
   y = pdf.absolute_bottom_margin
-  pdf.add_text(x, y, s, t)
+  pdf.add_text(x, y, t, s)
 
   x = pdf.absolute_left_margin
   w = pdf.absolute_right_margin
@@ -163,6 +163,9 @@ pnx = pdf.absolute_right_margin
 pdf.margins_pt(54)    # 54 point (3/4") margins on all sides...
 pdf.left_margin = 72  # ...except the left margin (1")
 
+image = File.join(pdf.techbook_source_dir, "images", "bluesmoke.jpg")
+pdf.add_image_from_file(image, 300, 50)
+
   # Draw the title page.
 title = "PDF::Writer for Ruby"
 size  = 72
@@ -174,7 +177,7 @@ pdf.stroke_color  Color::Red
 pdf.rectangle(pdf.absolute_left_margin, 0, fh, pdf.page_height).fill
 pdf.fill_color    Color::White
 pdf.stroke_color  Color::White
-pdf.add_text(pdf.absolute_left_margin + fh + fd, 70, size, title, -90)
+pdf.add_text(pdf.absolute_left_margin + fh + fd, 70, title, size, 90)
 pdf.restore_state
 
 pdf.select_font   pdf.techbook_textfont, pdf.techbook_encoding
@@ -196,8 +199,6 @@ Copyright
 INFO
 
 pdf.text(info, :font_size => 18, :justification => :right)
-image = File.join(pdf.techbook_source_dir, "images", "pdfwriter-small.jpg")
-pdf.add_image_from_file(image, 400, 100)
 pdf.open_here('Fit')
 
 pdf.start_page_numbering(pnx, pny, 6, :right, "<PAGENUM>", 1)
@@ -217,10 +218,11 @@ but it implements a substantial portion of it, with more to come. It also
 implements a more complex document layer on top of the portion that is
 implemented.
 
-The program (manual.rb) and text file (manual.txt) that generate this manual
-(manual.pdf) are a good introduction to both the use of PDF::Writer and a
-sample markup language. PDF::Writer itself only implements a few markup
-items, mostly relating to bold and italic text.
+This manual (manual.pdf) is generated by PDF::TechBook using the application
+runner (bin/techbook) and the text version of the manual (manual.pwd). It is
+a comprehesive introduction to the use of PDF::Writer and a simple markup
+language interpreter. PDF::Writer itself only implements a few markup items,
+mostly relating to bold and italic text.
 
 PDF::Writer is based on Adobe�s PDF Reference, Fifth Edition, version 1.6.
 This and earlier editions are available from the
@@ -230,6 +232,29 @@ website</c:alink>. The original implementation was a port of the public
 domain <c:alink uri="http://www.ros.co.nz/pdf/">R&OS PDF Class for PHP</c:alink>.
 
 Other demo programs are available in the <b>demo/</b> directory.
+Alternatively, they may be downloaded separately from the <c:alink
+uri="http://rubyforge.org/projects/ruby-pdf">Ruby PDF Tools</c:alink> project on RubyForge.
+
+2<Installation>
+If this manual was generated from a local installation of PDF::Writer, then
+congratulations! PDF::Writer is installed. Otherwise, you are reading a
+manual generated otherwise. If you want to install PDF::Writer, you can
+download it from the Ruby PDF Tools project on RubyForge or install it with
+RubyGems.
+
+PDF::Writer has dependencies on <c:alink
+uri="http://rubyforge.org/frs/?group_id=295&release_id=2130">Transaction::Simple
+1.3.0</c:alink> or later and <c:alink
+uri="http://rubyforge.org/frs/?group_id=81&release_id=2127">color-tools
+1.0.0</c:alink> or later. These must be installed for PDF::Writer to work.
+RubyGems installation will automatically detect and offer to download and
+install these dependencies.
+
+PDF::Writer is installed with:
+
+.code {{{
+  % ruby setup.rb
+.endcode }}}
 .newpage
 1<Making Documents with PDF::Writer>MakingDocuments
 
@@ -338,25 +363,24 @@ both the x and y directions. See the following discussion on PDF Coordinate
 Space for the limitation of performing transformations on the coordinate
 axis.
 
+PDF::Writer provides utility methods to convert between normal measurement
+units and and points. These utility methods are available either as class
+mehods or as instance methods.
 .eval {{{
 $rm = pdf.right_margin
 pdf.right_margin += 175
 
-y = pdf.absolute_bottom_margin
+y = pdf.absolute_bottom_margin + 40
 pdf.stroke_style(PDF::Writer::StrokeStyle.new(1))
 pdf.rectangle(400, y, 150, 200).stroke
 x0y0 = "(0, 0)"
 hh = pdf.font_height(9) + pdf.font_descender(9)
-pdf.add_text(405, y + hh - 2, 9, x0y0)
+pdf.add_text(405, y + hh - 2, x0y0, 9)
 x1y1 = "(150, 200)"
-ww = pdf.text_width(9, x1y1)
-pdf.add_text(545 - ww, y + 198 - hh, 9, x1y1)
+ww = pdf.text_width(x1y1, 9)
+pdf.add_text(545 - ww, y + 198 - hh, x1y1, 9)
 .endeval }}}
 
-PDF::Writer provides utility methods to convert between normal measurement
-units and and points. These utility methods are available either as class
-mehods or as instance methods.
-
 4<PDF::Writer.cm2pts(x)>
     Converts from centimetres to points.
 
@@ -378,11 +402,16 @@ pdf.right_margin = $rm
 PDF::Writer uses the standard coordinate space. Any transformations on the
 coordinate space (or, more accurately, on the coordinate axis) may affect the
 usability of PDF::Writer. Standard transformations available against the
-coordinate space axis are rotations (clockwise), scaling, translation
+coordinate space axis are rotations (counter-clockwise), scaling, translation
 (repositioning of the base coordinate) and skew. Each of these will be
 discussed in more detail in a later section of this manual, after other
 concepts have been introduced.
 
+<b>NOTE:</b> As of PDF::Writer 1.1.0, angle rotations are now
+counter-clockwise, not clockwise as in earlier versions. This is a necessary
+incompatible change to make transformations more compatible with other vector
+graphics systems.
+
 2<Fonts, Special Characters, and Character Maps in PDF::Writer>FontBasics
 All PDF readers support fourteen standard fonts; twelve of these fonts are
 bold, italic (or oblique), and bold-italic (bold-oblique) variants of three
@@ -492,19 +521,23 @@ The encoding directive will be effective <b>only when the font is first
 loaded</b>.
 
 .code {{{
-// use a Times-Roman font with MacExpertEncoding
+  # use a Times-Roman font with MacExpertEncoding
 pdf.select_font("Times-Roman", "MacExpertEncoding")
-// this next line should be equivalent
-pdf.select_font("Times-Roman", {:encoding=>"MacExpertEncoding"})
-
-// setup the helvetica font for use with german characters
-diff={196=>'Adieresis', 228=>'adieresis',
-             214=>'Odieresis', 246=>'odieresis',
-             220=>'Udieresis', 252=>'udieresis',
-             223=>'germandbls'}
-pdf.select_font("Helvetica"
-       , {:encoding=>"WinAnsiEncoding"
-             , :differences=>diff})
+  # this next line should be equivalent
+pdf.select_font("Times-Roman", { :encoding =&gt; "MacExpertEncoding" })
+
+  # Set up the Helvetica font for use with German characters as an offset
+  # of the WinAnsiEncoding.
+diff= {
+  196 =&gt; 'Adieresis',
+  228 =&gt; 'adieresis',
+  214 =&gt; 'Odieresis',
+  246 =&gt; 'odieresis',
+  220 =&gt; 'Udieresis',
+  252 =&gt; 'udieresis',
+  223 =&gt; 'germandbls'
+}
+pdf.select_font("Helvetica", { :encoding =&gt; "WinAnsiEncoding", :differences => diff })
 .endcode }}}
 
 3<Font Families>FontFamilies
@@ -565,10 +598,11 @@ PDF project, this requirement should be eliminated.
 4<Embedded Font Licensing Restrictions>
 As noted above, PDF::Writer will embed Type 1 or TrueType font programs in
 the PDF document. Fonts are recognised as copyrightable intellectual property
-in some jurisdictions. PDF::Writer does not have the ability to check the
-licensing rights for these fonts. It is up to the users of this library to
-ensure that there are no license violations of any fonts embedded in a PDF
-document created with PDF::Writer.
+in some jurisdictions. TrueType fonts encode some licensing rights in the
+font programs and PDF::Writer will check and warn if fonts not licensed for
+inclusion in a document are selected. It is up to the users of PDF::Writer to
+ensure that there are no licence violations of fonts embedded in the
+generated PDF documents.
 
 3<Special Characters, Character Maps, and Unicode>SpecialCharacters
 Fonts in PDF documents can include encoding information. The PDF standard
@@ -606,6 +640,10 @@ values are the characters
 the font and therefore require additional information to present and space
 these characters properly.
 
+#TODO
+As of PDF::Writer version 1.1, these difference maps will be inserted into
+the PDF documents as well. This change is experimental but should be safe.
+
 4<Unicode>
 PDF supports UTF-16BE encoding of strings�but each such string must begin
 with the UTF-16BE byte order mark (BOM) of U+FEFF (0xFE followed by 0xFF).
@@ -821,7 +859,9 @@ name="ColumnOutput" label="title" />
 
 5<Text Size>
 If the <b>:font_size</b> is not specified, then the last font size
-or the default font size of 12 points will be used.
+or the default font size of 12 points will be used. If this value is
+provided, this <b>changes</b> the current font size just as if the #font_size
+attribute were set.
 
 .code {{{
   pdf.text("Ruby is fun!", :font_size =&gt; 16)
@@ -892,7 +932,7 @@ return <b>true</b> if the text will be overflowed to a new page or column.
 Text can also be placed starting with specific X and Y coordinates using
 either <b>PDF::Writer#add_text_wrap</b> or <b>PDF::Writer#add_text</b>.
 
-4<PDF::Writer#add_text_wrap(x, y, width, size, text, justification = :left, angle = 0, test = false)>
+4<PDF::Writer#add_text_wrap(x, y, width, text, size = nil, justification = :left, angle = 0, test = false)>
 This will add text to the page at position <b>(x, y)</b>, but ensures that it
 fits within the provided <b>width</b>. If it does not fit, then as much as
 possible will be written using the wrapping rules on page <r:xref
@@ -900,9 +940,13 @@ name="TextWrapping" label="page" />. The remaining text to be written will be
 returned to the caller.
 
 .code {{{
-rest = pdf.add_text_wrap(150, pdf.y, 150, 72, "Ruby is fun!")
+rest = pdf.add_text_wrap(150, pdf.y, 150, "Ruby is fun!", 72)
 .endcode }}}
 
+If <b>size</b> is not specified, the current #font_size will be used. This
+parameter has changed position with <b>text</b> in PDF::Writer 1.1. If your
+code appears to be using the old parameter call, it will be warned.
+
 The optional justification parameter works just as described on page <r:xref
 name="TextJustification" label="page" />, except that instead of margin
 width, it is the boundaries defined by the <b>x</b> and <b>width</b>
@@ -914,33 +958,34 @@ Text may be drawn at an angle. This will be discussed fully in the section on
 If the <b>test</b> parameter is <b>true</b>, the text will not be written,
 but the remainder of the text will be returned.
 
-4<PDF::Writer#add_text(x, y, size, text, angle = 0, word_space_adjust = 0)>
+4<PDF::Writer#add_text(x, y, text, size = nil, angle = 0, word_space_adjust = 0)>
 This places the full text string at the <b>(x, y)</b> position and the
-specified <b>angle</b> (measured in degrees of a circle, in a clockwise
-direction) with respect to the angle of the coordinate axis.
+specified <b>angle</b> (measured in degrees of a circle, in a
+counter-clockwise direction) with respect to the angle of the coordinate
+axis.
+
+<b>NOTE:</b> As of PDF::Writer 1.1.0, angle rotations are now
+counter-clockwise, not clockwise as in earlier versions. This is a necessary
+incompatible change to make transformations more compatible with other vector
+graphics systems.
+
+If <b>size</b> is not specified, the current #font_size will be used. This
+parameter has changed position with <b>text</b> in PDF::Writer 1.1. If your
+code appears to be using the old parameter call, it will be warned.
 
 .code {{{
-pdf.add_text(pdf.margin_x_middl, pdf.y, 12, "    0�", 0)
-pdf.add_text(pdf.margin_x_middl, pdf.y, 12, "   45�", 45)
-pdf.add_text(pdf.margin_x_middl, pdf.y, 12, "   90�", 90)
-pdf.add_text(pdf.margin_x_middl, pdf.y, 12, "  135�", 135)
-pdf.add_text(pdf.margin_x_middl, pdf.y, 12, "  180�", 180)
-pdf.add_text(pdf.margin_x_middl, pdf.y, 12, "  225�", 225)
-pdf.add_text(pdf.margin_x_middl, pdf.y, 12, "  270�", 270)
-pdf.add_text(pdf.margin_x_middl, pdf.y, 12, "  305�", 305)
+0.step(315, 45) do |angle|
+  pdf.add_text(pdf.margin_x_middle, pdf.y, "#{angle}�".rjust(8), 12,
+               angle)
+end
 .endcode }}}
 .eval {{{
 x = pdf.margin_x_middle
 y = pdf.y - 50
 
-pdf.add_text(x, y, 12, "      0�", 0)
-pdf.add_text(x, y, 12, "     45�", 45)
-pdf.add_text(x, y, 12, "     90�", 90)
-pdf.add_text(x, y, 12, "    135�", 135)
-pdf.add_text(x, y, 12, "    180�", 180)
-pdf.add_text(x, y, 12, "    225�", 225)
-pdf.add_text(x, y, 12, "    270�", 270)
-pdf.add_text(x, y, 12, "    305�", 305)
+0.step(315, 45) do |angle|
+  pdf.add_text(x, y, "#{angle}�".rjust(8), 12, angle)
+end
 
 pdf.y = y - 30
 .endeval }}}
@@ -1291,27 +1336,36 @@ appends a page number; it is implemented and used in
 <b>PDF::TechBook::TagTocDots</b>. It is of limited configurability in this
 version.
 
-5<&lt;r:xref name="XREFNAME" label="page|label"&gt;>
+5<&lt;r:xref name="XREFNAME" label="page|label" text="TEXT"/&gt;>
 This replacement callback returns an internal link (&lt;c:ilink...&gt;) with
 either the name (label="title") or the page number (label="page") of the
-cross-reference. The page number will only be used if it is known at the time
-that the &lt;r:xref&gt; tag is processed; forward cross-references will
-always use the label. This is implemented through
-<b>PDF::TechBook::TagXref</b>.
+cross-reference, or an indicator for arbitrary text (label="text") drawn from
+the text attribute (e.g., text="random text here"). The page number will only
+be used if it is known at the time that the &lt;r:xref&gt; tag is processed;
+forward cross-references will always use the text (if present) or the label.
+This is implemented through <b>PDF::TechBook::TagXref</b>.
 
 3<Text Height and Width>
+These methods return the height of the font or the width of the
+text.
 
-4<PDF::Writer#font_height(font_size)>
+4<PDF::Writer#font_height(font_size = nil)>
 Returns the height of the current font for the given size, measured in PDF
 userspace units. This is the distance from the bottom of the descender to the
-top of the capitals or ascenders.
+top of the capitals or ascenders. Uses the current #font_size if size is not
+provided.
 
-4<PDF::Writer#font_descender(font_size)>
+4<PDF::Writer#font_descender(font_size = nil)>
 Returns the size of the descender�the distance below the baseline of the
-font�which will normally be a negative number.
+font�which will normally be a negative number. Uses the current #font_size if
+size is not provided.
 
-4<PDF::Writer#text_width(font_size, text)>
-Returns the width of the given text string at the given font size.
+4<PDF::Writer#text_width(text, font_size = nil)>
+4<PDF::Writer#text_line_width(text, font_size = nil)>
+Returns the width of the given text string at the given font size using the
+current font, or the current default font size if none is given. The
+difference between #text_width and #text_line_width is that the former will
+give the width of the largest line in a multiline string.
 
 2<Document Margins and Page Dimensions>DocumentMargins
 A document canvas should not be written from edge to edge in most cases;
@@ -1756,10 +1810,9 @@ is not turned on.
 It is common in documents to see items repeated from page to page. These may
 be watermarks, headers, footers, or other elements that must appear on
 multiple pages�aside from page numbering. PDF::Writer supports this through a
-mechanism called �loose objects.�
-
-3<Loose Objects>
+mechanism called �loose content objects.�
 
+3<Loose Content Objects>
 Up until this point, a page has been presented as the only canavas available
 to write and draw upon. This is a useful fiction, but it <i>is</i> a fiction.
 Any contents object may be drawn upon, and an implicit contents object is
@@ -1769,28 +1822,30 @@ and should only be written to with explicit locations, as #text is not aware
 of non-page canvases.
 
 4<PDF::Writer#open_object>
-Make a loose object. Output will go into this object until it is closed. This
-object will not appear until it is included within a page. The method will
-return the object reference. To aid in the conceptual grouping of
-modifications to a loose object, this method will yield the opened object if
-a block is provided.
+Makes a loose content object. Output will go into this object until it is
+closed. This object will not appear until it is included within a page. The
+method will return the object reference. To aid in the conceptual grouping of
+modifications to a loose content object, this method will yield the opened
+object if a block is provided.
 
 4<PDF::Writer#reopen_object(id)>
 Makes the object for current content insertion the object specified by
 <b>id</b>, which is a value returned by either #open_object or #new_page.
 
 4<PDF::Writer#close_object>
-Closes the currently open loose object, preventing further writing against
-the object.
+Closes the currently open loose content object, preventing further writing
+against the object.
 
-3<Using Loose Objects>
-
-Once a loose object has been created, it must be added 
+3<Using Loose Content Objects>
+Once a loose contents object has been created, it must be added to the
+collection of loose objects before it can be seen in the PDF document.
+PDF::Writer makes it easy to write these objects to the contents of pages
+when the pages are created.
 
 4<PDF::Writer#add_object(id, where = :this_page)>
-After a loose object has been created, it will only show if it has been added
-to a page or page(s) with this method. Where the loose object will be added
-is controlled by the <b>where</b> option.
+After a loose content object has been created, it will only show if it has
+been added to a page or page(s) with this method. Where the loose content
+object will be added is controlled by the <b>where</b> option.
 
 The object will not be added to itself.
 
@@ -1808,7 +1863,6 @@ The object will not be added to itself.
 Stops adding the specified object to pages <i>after</i> this page.
 
 3<Example>
-
 The following example is used to create the heading of this manual.
 
 .code {{{
@@ -1819,10 +1873,10 @@ pdf.open_object do |heading|
 
   s = 6
   t = "PDF::Writer for Ruby ~ Manual"
-  w = pdf.text_width(s, t) / 2.0
+  w = pdf.text_width(t, s) / 2.0
   x = pdf.margin_x_middle
   y = pdf.absolute_top_margin
-  pdf.add_text(x - w, y, s, t)
+  pdf.add_text(x - w, y, t, s)
 
   x = pdf.absolute_left_margin
   w = pdf.absolute_right_margin
@@ -1891,8 +1945,7 @@ viewport is set to <b>top</b>.
 Fits the page vertically to the bounding box of the page. The left of the
 viewport is set to <b>left</b>.
 
-3<PDF::Writer#add_internal_link(label, x0, y0, x1, y1)>
-
+3<PDF::Writer#add_internal_link(label, x0, y0, x1, y1)>internal_links
 Creates an internal link in the document, �label� is the name of an target
 point, and the other settings are the coordinates of the enclosing rectangle
 of the clickable area from <b>(x0, y0)</b> to <b>(x1, y1)</b>.
@@ -1901,8 +1954,7 @@ Note that the destination markers are created using the #add_destination
 method described below. This the manual way of doing what &lt;c:ilink&gt;
 does.
 
-3<PDF::Writer#add_link(uri, x0, y0, x1, y1)>
-
+3<PDF::Writer#add_link(uri, x0, y0, x1, y1)>external_links
 Creates a clickable rectangular area from <b>(x0, y0)</b> to <b>(x1, y1)</b>
 within the current page of the document, which takes the user to the
 specified URI when clicked. This is the manual way of doing what
@@ -1934,7 +1986,6 @@ the way that text is rendered.
 3<#text_render_style(style)>
 3<#text_render_style!(style)>
 3<#text_render_style?>
-
 The first and second methods will set the text rendering style; the second
 forces the style to be set in the PDF document even if it�s the same as the
 currently known text rendering style. The third method returns the current
@@ -1957,7 +2008,7 @@ clipping paths at this point.
 .endblist }}}
 
 .eval {{{
-pdf.move_pointer(200, true)
+pdf.move_pointer(160, true)
 y = pdf.y + 90
 
 pdf.select_font "Times-Roman"
@@ -1970,12 +2021,13 @@ pdf.rectangle(pdf.absolute_left_margin, y + 64, pdf.margin_width, -100).fill_str
 pdf.fill_color    Color::Black
 
 (0..7).each do |style|
-  pdf.add_text(pdf.absolute_left_margin + 20 + (60 * style), y + 48, 12, style.to_s)
+  pdf.add_text(pdf.absolute_left_margin + 20 + (60 * style), y + 48,
+               style.to_s, 12)
 end
 
 (0..7).each do |style|
   pdf.text_render_style!(style)
-  pdf.add_text(pdf.absolute_left_margin + 5 + (60 * style), y, 64, "Q")
+  pdf.add_text(pdf.absolute_left_margin + 5 + (60 * style), y, "Q", 64)
 end
 .endeval }}}
 .newpage
@@ -2828,8 +2880,7 @@ document.
 Images are inserted into PDF documents as one pixel per PDF userspace unit,
 making a 320�240 image approximately 4���3�� (113mm�85mm) in size.
 
-3<#add_image(image, x, y, width = nil, height = nil, image_info = nil)>
-
+3<#add_image(image, x, y, width = nil, height = nil, image_info = nil, link = nil)>
 Adds an image to the PDF document. The image must be a String that represents
 the binary contents of a PNG or JPEG file <i>or</i> it must be a PDF image
 that has previously been inserted by one of the image insertion methods
@@ -2849,14 +2900,22 @@ If both width and height are specified, the set values will be used.
 If the width and/or height values are negative, the image will be flipped
 horizontally or vertically, as appropriate.
 
-The last parameter, <b>image_info</b>, must either be unspecified or a valid
+The <b>image_info</b> parameter must either be unspecified, nil, or a valid
 instance of PDF::Writer::Graphics::ImageInfo (see �<r:xref name="ImageInfo"
 label="title" />�).
 
-The image object will be returned so that it can be used again in the future.
+The <b>link</b> parameter allows the image to be made as a clickable link to
+internal or external targets. It must be specified as a hash with two
+options:
 
-3<#add_image_from_file(image, x, y, width = nil, height = nil)>
+.blist {{{
+<b>:type</b> is the type of the link, either <b>:internal</b> or <b>:external</b>. This affects the interpretation of <b>:target</b>.
+<b>:target</b> is the destination of the link. For <b>:type =&gt; :internal</b> links, this is an internal destination. For <b>:type =&gt; :external</b> links, this is an URI. See <r:xref name="internal_links" label="text" text="#add_internal_link" /> and <r:xref name="external_links" label="text" text="#add_link" /> for more information.
+.endblist }}}
 
+The image object will be returned so that it can be used again in the future.
+
+3<#add_image_from_file(image, x, y, width = nil, height = nil, link = nil)>
 Adds an image to the PDF document from a file. The <b>image</b> parameter may
 be an IO-like object (it must respond to #read and return the full image data
 in a single read) or a filename. If <i>open-uri</i> is active, the filename
@@ -2865,7 +2924,6 @@ may also be an URI to a remote image.
 In all other ways, it behaves just like #add_image.
 
 3<#image(image, options = {})>
-
 This third method for inserting images into a PDF document holds much the
 same relationship to #add_image and #add_image_from_file as #text holds to
 the text insertion methods #add_text and #add_text_wrap. This method will
@@ -2919,6 +2977,16 @@ border. The parameter may also be a hash with two values.
 <b>:style</b> specifies the stroke style of the border.
 .endblist }}}
 
+4<:link>
+The image may be made a clickable link to internal or external targets. This
+option must be specified as a hash with two options:
+
+.blist {{{
+<b>:type</b> is the type of the link, either <b>:internal</b> or <b>:external</b>. This affects the interpretation of <b>:target</b>.
+<b>:target</b> is the destination of the link. For <b>:type =&gt; :internal</b> links, this is an internal destination. For <b>:type =&gt; :external</b> links, this is an URI. See <r:xref name="internal_links" label="text" text="#add_internal_link" /> and <r:xref name="external_links" label="text" text="#add_link" /> for more information.
+.endblist }}}
+
+3<Limitations>
 Because #text and #image comprise a <i>simple</i> layout engine, the
 limitations of these methods must be understood. The image will be inserted
 and text will be inserted after it. There is no option to place the image and
@@ -2933,12 +3001,13 @@ left-hand corner of the canvas. PDF::Writer
 behaviour, but the axis can be transformed in several ways. It can be
 translated, rotated, scaled, and skewed.
 
-Axis transformations are cumulative within a graphics state stack level (see
-the next section). It is recommended that axis transformations are performed
-within a #save_state/#restore_state combination.
+Axis transformations are cumulative (matrix multiplicative; see the
+description of #transform_matrix for a full explanation) within a graphics
+state stack level (see the next section). It is recommended that axis
+transformations are performed within a #save_state/#restore_state
+combination.
 
 3<translate_axis(x, y)>
-
 Translates the coordinate space so that <b>(x, y)</b> under the old
 coordinate space is now <b>(0, 0)</b>. The <i>direction</i> of the old
 coordinate space is unchanged (y values are increasing). The example code
@@ -2949,12 +3018,15 @@ pdf.translate_axis(pdf.margin_x_middle, pdf.margin_y_middle)
 .endcode }}}
 
 3<rotate_axis(angle)>
+The entire coordinate space is rotated by the specified angle in a
+counter-clockwise direction.
 
-The entire coordinate space is rotated by the specified angle in a clockwise
-direction.
+<b>NOTE:</b> As of PDF::Writer 1.1.0, angle rotations are now
+counter-clockwise, not clockwise as in earlier versions. This is a necessary
+incompatible change to make transformations more compatible with other vector
+graphics systems.
 
 3<scale_axis(x = 1, y = 1)>
-
 Changes the size of PDF userspace units. This changes the scale of all
 operations in PDF documents. With <b>#scale_axis(0.5, 1)</b>, the x-axis is
 modified so that PDF userspace units are 1/144� in width, instead of the
@@ -2965,10 +3037,98 @@ If the scale value is negative, the coordinate axis is reversed and graphics
 or text will be drawn in reverse.
 
 3<skew_axis(xangle = 0, yangle = 0)>
-
 Rotates the x and y axes independently of one another, creating a skewed
 appearance.
 
+3<transform_matrix(a, b, c, d, e, f)>
+Transforms the coordinate axis with the transformation vector interpreted as
+a coordinate transformation matrix:
+
+.eval {{{
+  def bracket(pdf, x, y, width, height, size)
+    y -= (height / 1.75)
+    tw = pdf.text_width("[", size * 4)
+    pdf.add_text(x - tw, y, "[", size * 4)
+    tw = pdf.text_width("]", size * 3)
+    pdf.add_text(x + width - tw, y, "]", size * 4)
+    x + width + tw
+  end
+
+  rowh = pdf.font_height(14)
+
+  pdf.move_pointer(rowh * 5, true)
+
+  mw  = pdf.text_width("MMMM", 14)
+  _x  = pdf.margin_x_middle - (mw / 2.0)
+  _y  = pdf.y + (rowh * 3)
+
+  pdf.add_text(_x, _y + rowh, "a  c  e", 14)
+  pdf.add_text(_x, _y,        "b  d  f", 14)
+  pdf.add_text(_x, _y - rowh, "0  0  1", 14)
+  bracket(pdf, _x, _y, mw, rowh, 14)
+
+  pdf.move_pointer(rowh)
+.endeval }}}
+
+The matrix transforms the new coordinates (x1, y1) to the old coordinates
+(x0, y0) through the dot product:
+
+.eval {{{
+  def bracket(pdf, x, y, width, height, size)
+    y -= (height / 1.75)
+    tw = pdf.text_width("[", size * 4)
+    pdf.add_text(x - tw, y, "[", size * 4)
+    tw = pdf.text_width("]", size * 3)
+    pdf.add_text(x + width - tw, y, "]", size * 4)
+    x + width + tw
+  end
+
+  rowh = pdf.font_height(14)
+  mtxw = pdf.text_width("MM", 14)
+
+  pdf.move_pointer(rowh * 5, true)
+  _y  = pdf.y + (rowh * 3)
+
+  _x = 100
+  pdf.add_text(_x, _y + rowh, "x0", 14)
+  pdf.add_text(_x, _y, "y0", 14)
+  pdf.add_text(_x, _y - rowh, " 1", 14)
+  _x = bracket(pdf, _x, _y, mtxw, rowh, 14)
+
+  pdf.add_text(_x, _y - (rowh / 1.5), '=', 42)
+
+  mtxw  = pdf.text_width("MMMM", 14)
+  _x += mtxw
+
+  pdf.add_text(_x, _y + rowh, "a  c  e", 14)
+  pdf.add_text(_x, _y,        "b  d  f", 14)
+  pdf.add_text(_x, _y - rowh, "0  0  1", 14)
+  _x = bracket(pdf, _x, _y, mtxw, rowh, 14)
+
+  pdf.circle_at(_x - 3, _y + 3, 3).fill
+
+  mtxw = pdf.text_width("MM", 14)
+  _x += mtxw
+
+  pdf.add_text(_x, _y + rowh, "x1", 14)
+  pdf.add_text(_x, _y, "y1", 14)
+  pdf.add_text(_x, _y - rowh, " 1", 14)
+  bracket(pdf, _x, _y, mtxw, rowh, 14)
+
+  pdf.move_pointer(rowh)
+.endeval }}}
+
+In practice, the six variables (a�f) be represented as a six-element vector:
+[ a b c d e f ].
+
+.blist {{{
+Axis translation uses [ 1 0 0 1 x y ] where x and y are the new (0,0) coordinates in the old axis system.
+Scaling uses [ sx 0 0 sy 0 0 ] where sx and sy are the scaling factors.
+Rotation uses [ cos(a) sin(a) -sin(a) cos(a) 0 0 ] where a is the angle, measured in radians.
+X axis skewing uses [ 1 0 tan(a) 1 0 0 ] where a is the angle, measured in radians.
+Y axis skewing uses [ 1 tan(a) 0 1 0 0 ] where a is the angle, measured in radians.
+.endblist }}}
+
 2<Graphics State>
 PDF allows for multiple independent levels of graphics state to be saved in a
 last-in first-out stack. Graphics states may not remain open over page
@@ -3039,9 +3199,11 @@ Indicates or sets document compression. If the value is true, the document
 will be compressed on writing using the �deflate� compression method. If the
 �zlib� library cannot be loaded, compression settings will be ignored.
 
+<b>NOTE:</b> This value should be set as early as possible during the
+document generation, or only some sections of the PDF will be compressed.
+
 3<PDF::Writer#media_box(x0, y0, x1, y1)>
 3<PDF::Writer#trim_box(x0, y0, x1, y1)>
-
 The #trim_box and the #media_box are both expressed in default (unscaled)
 user space units. The #media_box defines the boundaries of the physical
 medium on which the page is intended to be displayed or printed. As of this
@@ -3099,7 +3261,6 @@ A name object indicating whether the document has been modified to include
 trapping information. This is not currently supported by PDF::Writer.
 
 3<PDF::Writer#viewer_preferences(label, value = 0)>
-
 This will set values that indicate to the viewer how it should display the
 itself with respect to this document.
 
@@ -3160,7 +3321,6 @@ value of +style+ affects the interpretation of +params+.
 PDF::Writer#open_here uses the current page as the starting location.
 
 3<PDF::Writer#encrypt(user_pass = nil, owner_pass = nil, permissions = [])>
-
 Encrypts the document using Adobe RC4. This will set the user and owner
 passwords that will be used to access the document and set the permissions
 the user has with the document. The passwords are limited to 32 characters.
@@ -3191,6 +3351,10 @@ printing and copy/paste operations.
 .code {{{
 pdf.encrypt('trees', 'frogs', [ :copy, :print ])
 .endcode }}}
+
+3<PDF::Writer#save_as(filename)>
+Saves the PDF document as a file to disk.
+
 .newpage
 1<Tables in PDF Documents>TablesInPDF
 
@@ -3222,7 +3386,6 @@ elements (required and optional), text options, border and shading options,
 positioning options, and pagination opitons.
 
 3<PDF::SimpleTable.new>
-
 This creates a SimpleTable with default values. It will yield the created
 table if a block is provided.
 
@@ -3237,7 +3400,6 @@ end
 .endcode }}}
 
 3<Structural Elements>
-
 A SimpleTable cannot render itself if it does not know what columns are to be
 displayed or if it does not have any data. Thus, #data and #column_order must
 be defined before the table rendering code will work. Optionally, options can
@@ -3373,7 +3535,6 @@ Sets this table cell heading to be rendered bold. Independent of the
 table-wide #bold_headings setting.
 
 3<Text Options>
-
 These options control the display of the text in and around the table.
 
 4<SimpleTable#title, SimpleTable#title=>
@@ -3407,7 +3568,6 @@ The text colour of the body cells. Defaults to Color::Black.
 Makes the heading text bold if <b>true</b>. The default is <b>false</b>.
 
 3<Border and Shading Options>
-
 These options control the appearance of the borders (if shown) and row
 shading (if enabled).
 
@@ -3456,7 +3616,6 @@ Defines the inner and outer line styles. The default style for both is
 PDF::Writer::StrokeStyle::DEFAULT.
 
 3<Positioning Options>
-
 These options control how and where the table, or some elements of a table,
 will be positioned. All measurements here are in normal PDF userspace units.
 
@@ -3550,7 +3709,6 @@ The space added to the bottom of each row between the text and the lines of
 the cell. Default: 2 units.
 
 3<Pagination Options>
-
 These options tell SimpleTable what to do when the table crosses a page
 boundary. All measurements here are in PDF userspace units.
 
@@ -3575,7 +3733,6 @@ typically used for a repeating text header or other similar items. Default: 0
 units.
 
 3<Drawing the Table>
-
 The table is drawn with the #render_on method.
 
 4<SimpleTable#render_on(pdf)>
@@ -3600,7 +3757,6 @@ table.data = [
 .endcode }}}
 
 3<Basic Table>
-
 This table shows the �row,� �name,� and �race� columns with default settings.
 
 .code {{{
@@ -3648,7 +3804,6 @@ end
 .endeval }}}
 
 3<Table with Custom Column Headings>
-
 This table creates custom column headings for display. For completeness�
 sake, a title has been added to the table.
 
@@ -3691,7 +3846,6 @@ end
 .endeval }}}
 
 3<No Headings, Shadings, or Lines>
-
 This table isn�t quite the same as the one above. Close, though. Sort of.
 
 .code {{{
@@ -3740,7 +3894,6 @@ end
 .endeval }}}
 
 3<Controlled Width and Positioning>
-
 A version of the table with an explicitly too-small width, forcing content to
 wrap. This table is positioned at the right margin and oriented to the left
 of the right margin.
@@ -3909,7 +4062,6 @@ R&amp;OS PDF class. It has been adapted to PDF::Writer with some improvements
 in configurability and capability.
 
 3<PDF::Charts::StdDev.new>
-
 This will create the standard deviation chart with default values. If a block
 is provided, the created chart will be yielded.
 
@@ -4193,11 +4345,10 @@ and 6 are matched. This will use a Z-fold that places columns 5 and 6 face to
 face and columns 2 and 3 face to face. In the folded reference sheet, columns
 1 and 4 will be facing out. The illustrations below are useful for
 understanding this.
-
 .eval {{{
-pdf.move_pointer(200, true)
+pdf.move_pointer(150, true)
 
-_y = pdf.y + 190
+_y = pdf.y + 140
 
 pdf.save_state
 pdf.stroke_color! Color::Black
@@ -4207,17 +4358,17 @@ pdf.rectangle(100, _y, 75, -50).line(125, _y, 125, _y - 50)
 pdf.line(150, _y, 150, _y - 50).stroke
 
 pdf.fill_color  Color::Grey60
-pdf.add_text(105, _y - 36, 36, "1")
-pdf.add_text(130, _y - 36, 36, "2")
-pdf.add_text(155, _y - 36, 36, "3")
+pdf.add_text(105, _y - 36, "1", 36)
+pdf.add_text(130, _y - 36, "2", 36)
+pdf.add_text(155, _y - 36, "3", 36)
 
 pdf.rectangle(215, _y - 15, 25, -50).stroke
-pdf.add_text(220, _y - 51, 36, "3")
+pdf.add_text(220, _y - 51, "3", 36)
 pdf.line(225, _y, 215, _y - 15).line(225, _y - 50, 215, _y - 65).stroke
 pdf.fill_color  Color::White
 pdf.rectangle(200, _y, 25, -50).fill_stroke
 pdf.fill_color  Color::Grey60
-pdf.add_text(205, _y - 36, 36, "1")
+pdf.add_text(205, _y - 36, "1", 36)
 
 pdf.fill_color  Color::Black
 pdf.line(200, _y + 5, 225, _y + 5).stroke
@@ -4229,9 +4380,8 @@ pdf.move_to(218, _y - 70).line_to(225, _y - 67.5).line_to(225, _y - 72.5)
 pdf.close_fill
 pdf.restore_state
 
-pdf.move_pointer(-90)
+pdf.move_pointer(-60)
 .endeval }}}
-
 2<Brochures>
 Brochures differ in their design and intent than a reference sheet. A common
 brochure is also three columns (although parts of a brochure�especially
@@ -4247,10 +4397,9 @@ brochure will be folded so that columns 2 and 3 are face to face. After this,
 column 1 will face column 4 (exposed by the first fold). In the folded
 brochure, columns 5 and 6 are facing out. The illustrations below are useful
 for understanding this.
-
 .eval {{{
-pdf.move_pointer(200, true)
-_y = pdf.y + 190
+pdf.move_pointer(150, true)
+_y = pdf.y + 140
 pdf.save_state
 
 pdf.stroke_color! Color::Black
@@ -4259,16 +4408,16 @@ pdf.rectangle(100, _y, 75, -50).line(125, _y, 125, _y - 50)
 pdf.line(150, _y, 150, _y - 50).stroke
 
 pdf.fill_color  Color::Grey60
-pdf.add_text(103, _y - 36, 36, "1")
-pdf.add_text(128, _y - 36, 36, "2")
-pdf.add_text(153, _y - 36, 36, "3")
+pdf.add_text(103, _y - 36, "1", 36)
+pdf.add_text(128, _y - 36, "2", 36)
+pdf.add_text(153, _y - 36, "3", 36)
 
 pdf.rectangle(225, _y, 25, -50)
 pdf.line(220, _y + 10, 220, _y - 40).line(220, _y + 10, 225, _y)
 pdf.line(220, _y - 40, 225, _y - 50)
 pdf.line(255, _y + 10, 255, _y - 40).line(255, _y + 10, 250, _y)
 pdf.line(255, _y - 40, 250, _y - 50).stroke
-pdf.add_text(228, _y - 36, 36, "2")
+pdf.add_text(228, _y - 36, "2", 36)
 
 pdf.save_state
 pdf.fill_color  Color::Black
@@ -4280,7 +4429,7 @@ pdf.restore_state
 pdf.rectangle(325, _y, 25, -50)
 pdf.line(320, _y + 10, 320, _y - 40).line(320, _y + 10, 325, _y)
 pdf.line(320, _y - 40, 325, _y - 50).stroke
-pdf.add_text(328, _y - 36, 36, "4")
+pdf.add_text(328, _y - 36, "4", 36)
 pdf.save_state
 pdf.line(300, _y - 60, 325, _y - 60).stroke
 pdf.fill_color  Color::Black
@@ -4289,12 +4438,11 @@ pdf.close_fill
 pdf.restore_state
 
 pdf.rectangle(425, _y, 25, -50).stroke
-pdf.add_text(428, _y - 36, 36, "6")
+pdf.add_text(428, _y - 36, "6", 36)
 pdf.restore_state
 
-pdf.move_pointer(-90)
+pdf.move_pointer(-60)
 .endeval }}}
-
 2<Using PDF::QuickRef>
 PDF::QuickRef implements a domain-specific language (DSL) for creating
 reference sheets or brochures. It is intended to flow from column 1 to column
@@ -4326,7 +4474,6 @@ operations.
 3<QuickRef#title_font, QuickRef#title_font=>
 3<QuickRef#title_font_encoding, QuickRef#title_font_encoding=>
 3<QuickRef#title_font_size, QuickRef#title_font_size=>
-
 The name, encoding, and size of the font that will be used when drawing
 title text with #title. The default font is Times-Roman 14 point with the
 standard �WinAnsiEncoding� encoding.
@@ -4337,7 +4484,6 @@ standard
 3<QuickRef#h2_font_size, QuickRef#h2_font_size=>
 3<QuickRef#h3_font_size, QuickRef#h3_font_size=>
 3<QuickRef#h4_font_size, QuickRef#h4_font_size=>
-
 The name, encoding, and size of the font that will be used when drawing
 heading text with #h1, #h2, #h3, or #h4. The default font is Times-Roman with
 �WinAnsiEncoding� as the encoding. #h1 defaults to 11 points; #h2 to 9
@@ -4348,7 +4494,6 @@ points, #h3 to 8 points, and #h4 to 7 points.
 3<QuickRef#body_font_encoding, QuickRef#body_font_encoding=>
 3<QuickRef#code_font_encoding, QuickRef#code_font_encoding=>
 3<QuickRef#body_font_size, QuickRef#body_font_size=>
-
 Text drawn with #body, #lines, and #pairs will be drawn with the #body_font
 using #body_font_encoding at #body_font_size. Text drawn with #pre,
  #codelines, and #codepairs will be drawn with the #code_font using
@@ -4358,14 +4503,12 @@ default. The default #body_font_size is 7 points.
 
 3<QuickRef#pairs(text)>
 3<QuickRef#codepairs(text)>
-
 Creates a two-column shaded table using #body_font (#pairs) or #code_font
 (#codepairs). Each line of the text is a separate row. The two columns are
 separated by tab characters.
 
 3<QuickRef#lines(text)>
 3<QuickRef#codelines(text)>
-
 Creates a one-column shaded table using #body_font (#pairs) or #code_font
 (#codepairs). Each line of the text is a separate row.
 
@@ -4402,7 +4545,7 @@ Writes code text. Newlines and spaces will be preserved.
 Draws a horizontal line with the specified style and colour across the width
 of the column.
 
-3<QuickRef#save_as(filename, compressed = true)>
+3<QuickRef#save_as(filename)>
 Writes the Quick Reference to disk.
 
 3<QuickRef#render, QuickRef#to_s>
@@ -4421,6 +4564,274 @@ PDF::QuickRef.make do # 3-column LETTER
   save_as "MyQuickRef.pdf"
 end
 .endcode }}}
+.newpage
+1<PDF::TechBook>
+
+The TechBook class is a markup language interpreter. This will read a file
+containing the �TechBook� markukp, described below, and create a PDF document
+from it. This is intended as a complete document language, but it does have a
+number of limitations.
+
+The TechBook markup language and class are used to format the PDF::Writer
+manual, represented in the distrubtion by the file �manual.pwd�.
+
+The TechBook markup language is <b>primarily</b> stream-oriented with
+awareness of lines. That is to say that the document will be read and
+generated from beginning to end in the order of the markup stream.
+
+2<TechBook Markup>
+TechBook markup is relatively simple. The simplest markup is no markup at all
+(flowed paragraphs). This means that two lines separated by a single line
+separator will be treaed as part of the same paragraph and formatted
+appropriately by PDF::Writer. Paragaphs are terminated by empty lines, valid
+line markup directives, or valid headings.
+
+Certain XML entitites will need to be escaped as they would in normal XML
+usage, that is, �&lt;� must be written as �&amp;lt;�; �&gt;� must be written
+as �&amp;gt;�; and �&amp;� must be written as �&amp;amp;�.
+
+Comments, headings, and directives are line-oriented where the first
+mandatory character is in the first column of the document and take up the
+whole line. Styling and callback tags may appear anywhere in the text.
+
+3<Comments>
+Comments begin with the hash-mark (�#�) at the beginning of the line. Comment
+lines are ignored.
+
+3<Styling and Callback Tags>
+Within normal, preserved, or code text, or in headings, HTML-like markup may
+be used for bold (�&lt;b&gt;�) and italic (�&lt;i&gt;�) text. TechBook
+supports standard PDF::Writer callback tags (&lt;c:alink&gt;,
+&lt;c:ilink&gt;, &lt;C:bullet/&gt;, and &lt;C:disc/&gt;) and adds two new
+ones (&lt;r:xref/&gt;, &lt;C:tocdots/&gt;). See �<r:xref name="TextTags"
+label="label" />� for more information.
+
+3<Directives>
+Directives begin with a period (�.�) and are followed by a letter (�a�..�z�)
+and then any combination of word characters (�a�..�z�, �0�..�9�, and �_�).
+Directives are case-insensitive. A directive may have arguments; if there are
+arguments, they must follow the directive name after whitespace. After the
+arguments for a directive, if any, all other text is ignored and may be
+considered a comment.
+
+4<<b>.newpage [force]</b>>
+The <b>.newpage</b> directive starts a new page. If multicolumn mode is on, a
+new column will be started if the current column is not the last column. If
+the optional argument <b>force</b> follows the <b>.newpage</b> directive, a
+new page will be started even if multicolumn mode is on.
+
+.code {{{
+  .newpage
+  .newpage force
+.endcode }}}
+
+4<<b>.pre</b>, <b>.endpre</b>>
+The <b>.pre</b> and <b>.endpre</b> directives enclose a block of text with
+preserved newlines. This is similar to normal text, but the lines in the
+<b>.pre</b> block are not flowed together. This is useful for poetic forms or
+other text that must end when each line ends. <b>.pre</b> blocks may not be
+nested in any other formatting block. When an <b>.endpre</b> directive is
+encountered, the text format will be returned to normal (flowed text) mode.
+
+.code {{{
+  .pre
+  The Way that can be told of is not the eternal Way;
+  The name that can be named is not the eternal name.
+  The Nameless is the origin of Heaven and Earth;
+  The Named is the mother of all things.
+  Therefore let there always be non-being,
+    so we may see their subtlety,
+  And let there always be being,
+    so we may see their outcome.
+  The two are the same,
+  But after they are produced,
+    they have different names.
+  .endpre
+.endcode }}}
+
+This will look like the following:
+
+.pre {{{
+The Way that can be told of is not the eternal Way;
+The name that can be named is not the eternal name.
+The Nameless is the origin of Heaven and Earth;
+The Named is the mother of all things.
+Therefore let there always be non-being,
+  so we may see their subtlety,
+And let there always be being,
+  so we may see their outcome.
+The two are the same,
+But after they are produced,
+  they have different names.
+.endpre }}}
+
+4<<b>.code</b>, <b>.endcode</b>>
+The <b>.code</b> and <b>.endcode</b> directives enclose a block of text with
+preserved newlines. In addition, the font is changed from the normal
+ #techbook_textfont to #techbook_codefont. The #techbook_codefont is normally
+a fixed pitched font and defaults to Courier. At the end of the code block,
+the text state is restored to its prior state, which will either be
+<b>.pre</b> or normal. 
+
+.code {{{
+  .code
+  require 'pdf/writer'
+  PDF::Writer.prepress # US Letter, portrait, 1.3, prepress
+  .endcode
+.endcode }}}
+
+4<<b>.blist</b>, <b>.endblist</b>>
+These directives enclose a bulleted list block. Lists may be nested within
+other text states. If lists are nested, each list will be appropriately
+indented. Each line in the list block will be treated as a single list item
+with a bullet inserted in front using either the &lt;C:bullet/&gt; or
+&lt;C:disc/&gt; callbacks. Nested lists are successively indented.
+<b>.blist</b> directives accept one optional argument, the name of the type
+of bullet callback desired (e.g., �bullet� for &lt;C:bullet/&gt; and �disc�
+for &lt;C:disc/&gt;).
+
+.code {{{
+  .blist
+  Item 1
+  .blist disc
+  Item 1.1
+  .endblist
+  .endblist
+.endcode }}}
+
+4<<b>.eval</b>, <b>.endeval</b>>
+With these directives, the block enclosed will collected and passed to Ruby�s
+Kernel#eval. <b>.eval</b> blocks may be present within normal text,
+<b>.pre</b>, <b>.code</b>, and <b>.blist</b> blocks. No other block may be
+embedded within an <b>.eval</b> block.
+
+.code {{{
+  .eval
+  puts "Hello"
+  .endeval
+.endcode }}}
+
+4<<b>.columns</b>>
+Multi-column output is controlled with this directive, which accepts one or
+two parameters. The first parameter is mandatory and is either the number of
+columns (2 or more) or the word �off� (turning off multi-column output). When
+starting multi-column output, a second parameter with the gutter size may be
+specified.
+
+.code {{{
+  .columns 3
+  Column 1
+  .newpage
+  Column 2
+  .newpage
+  Column 3
+  .columns off
+.endcode }}}
+
+4<<b>.toc [TITLE]</b>>
+This directive is used to tell TechBook to generate a table of contents after
+the first page (assumed to be a title page). If this is not present, then a
+table of contents will not be generated. The title of the table of contents
+can be provided after this directive.
+
+4<<b>.author</b>, <b>.title</b>, <b>.subject</b>, <b>.keywords</b>>
+Sets values in the PDF information object. The arguments�to the end of the
+line�are used to populate the values.
+
+4<<b>.done</b>>
+Stops the processing of the document at this point.
+
+3<Headings>
+Headings begin with a number followed by the rest of the heading format. This
+format is �#&lt;heading-text&gt;� or �#&lt;heading-text&gt;xref_name�.
+TechBook supports five levels of headings. Headings may include markup, but
+should not exceed a single line in size; those headings which have boxes as
+part of their layout are not currently configured to work with multiple lines
+of heading output. If an xref_name is specified, then the &lt;r:xref/&gt; tag
+can use this name to find the target for the heading. If xref_name is not
+specified, then the �name� associated with the heading is the index of the
+order of insertion. The xref_name is case sensitive.
+
+.code {{{
+  1<Chapter>xChapter
+  2<Section>Section23
+  3<Subsection>
+  4<Subsection>
+  5<Subsection>
+.endcode }}}
+
+4<Heading Level 1>
+First level headings are generally chapters. As such, the standard
+implementation of the heading level 1 method (#__heading1), will be rendered
+as �chapter#. heading-text� in centered white on a black background, at 26
+point (H1_STYLE). First level headings are added to the table of contents.
+
+4<Heading Level 2>
+Second level headings are major sections in chapters. The headings are
+rendered by default as black on 80% grey, left-justified at 18 point
+(H2_STYLE). The text is unchanged (#__heading2). Second level headings are
+added to the table of contents.
+
+4<Heading Level 3, 4, and 5>
+The next three heading levels are used for varying sections within second
+level chapter sections. They are rendered by default in black on the
+background (there is no bar) at 18, 14, and 12 points, respectively
+(H3_STYLE, H4_STYLE, and H5_STYLE). Third level headings are bold-faced
+(#__heading3); fourth level headings are italicised (#__heading4), and fifth
+level headings are underlined (#__heading5).
+
+2<Configuring TechBook>
+TechBook is reasonably configurable. Formatting options may be changed with
+methods in the techbook object. Text transformations and directives must be
+done either as a subclass of TechBook or by reopening the TechBook class.
+
+3<Formatting Options>
+These options are configurable as a client and can be configured within the
+document source with an .eval directive.
+
+4<#techbook_codefont>
+4<#techbook_textfont>
+4<#techbook_encoding>
+4<#techbook_fontsize>
+These values configure the fonts and encoding for TechBook documents.
+
+3<Code Extensions>
+
+# TBD
+
+2<techbook Command>
+The TechBook class is also available with a command-line program, techbook
+(bin/techbook). The command-line interface is:
+
+.code {{{
+Usage: techbook [options] [INPUT FILE]
+  INPUT FILE, if not specified, will be 'manual.pwd', either in the
+  current directory or relative to this file.
+
+    -f, --force-regen                Forces the regeneration of the document,
+                                     ignoring the cached document version.
+    -n, --no-cache                   Disables generated document caching.
+    -z, --compress                   Compresses the resulting PDF.
+
+        --help                       Shows this text.
+.endcode }}}
+
+3<--no-cache>
+By default, the techbook command will generate the PDF document and a cached
+version of the document. If the input file is �test.pwd�, then both
+�test.pdf� and �test._mc� will be generated. This can be disabled by using
+the <b>--no-cache</b> option.
+
+3<--force-regen>
+If the input file is older than the generated cache document (if one exists),
+then techbook command will regenerate the document from the input file. This
+option forces this regeneration.
+
+3<--compress>
+The document will not be compressed by default. This option will compress the
+document. This can <em>only</em> be applied if the document is being
+generated from the original document, not the cached document.
+
 .newpage
 1<PDF::Writer Dependencies>
 
@@ -4552,7 +4963,6 @@ v.transaction_open?             # -> false
 .endcode }}}
 
 3<Grouped Transactions>
-
 .code {{{
 require 'transaction/simple/group'
 
@@ -4588,8 +4998,10 @@ y                               = -> "And you, too."
 .endcode }}}
 
 3<Methods>
+These are the methods that objects extended with Transaction::Simple will
+know.
 
-4<#transaction_open?(name = nil)
+4<#transaction_open?(name = nil)>
 Returns <b>true</b> if a transaction is currently open if the <em>name</em>
 parameter is <b>nil</b>. If a name is requested, then returns <b>true</b> if
 a transaction with that name is currently open.
@@ -4673,7 +5085,7 @@ must be understood. Transaction::Simple:
 �does not necessarily maintain Object#__id__ values on rewind or abort. This may change for future versions that will be Ruby 1.8 or better <b>only</b>. Certain objects that support #replace will maintain Object#__id__.
 �can be a memory hog if you use many levels of transactions on many objects.
 .endblist }}}
-
+.newpage
 2<color-tools>ColorTools
 The color-tools package was created to abstract out the colour needs for
 PDF::Writer and make them available for other uses as well (such as web
@@ -4911,7 +5323,15 @@ Loops through the palette
 .newpage
 1<PDF::Writer Demos>
 
-A quick overview of the demo programs and what they are expected to do.
+A quick overview of the demo programs and what they are expected to do. These
+may be downloaded separately from the main PDF::Writer package at the
+RubyForge project for PDF::Writer.
+
+If PDF::Writer has been installed with RubyGems, then the demos will need to
+be run explicitly referencing RubyGems:
+.code {{{
+  % ruby -rubygems chunkybacon.rb
+.endcode }}}
 
 2<chunkybacon.rb>
 Creates a single-page document with three copies of an image from <i>Why�s
@@ -4953,21 +5373,50 @@ original text.
 .newpage
 1<Future Plans>
 
+There are great plans for future versions of PDF::Writer.
+
 .blist {{{
 Support for Text::Hyphen hyphenation in text wrapping methods.
 Widow/orphan support (so that paragraphs never have less than two lines on a page).
 First line indent, hanging indent.
 More chart types: pie chart, bar chart, line chart.
-Sparklines (inline, text-sized charts, first described by Malcolm Gladwell).
+Sparklines (inline, text-sized charts, first described by Edward Tufte).
 Drop-caps.
 In-line font changes, such as &lt;c:code&gt;.
 Slideshows (both plain PDF and SVG).
 Event detection: callbacks on page change, etc. This will be necessary to support multiple page sizes and orientations within a single document.
+Support for code page maps; these are predefined encodings and encoding difference sets.
+Unicode support�at least UTF-16.
 .endblist }}}
 .newpage
 1<Revision History>
 
+2<Version 1.1.0: June 29, 2005>
+<b>NOTE</b>: The first two changes are <em>incompatible</em> with previous
+versions of PDF::Writer. A 90� angle in the PDF::Writer 1.0.x must be
+represented as a -90� (or 270�) angle in PDF::Writer 1.1 or later.
+
+.blist {{{
+Axis transformations in PDF::Writer::Graphics have been fixed.
+Text axis transformation in PDF::Writer#add_text has been fixed.
+Changed #text_width and #text_line_width so that the text value is the first parameter and the size parameter is second and optional. The code warns about it now, but it will break in PDF::Writer 2.0.
+Changed #add_text and #add_text_wrap so that the text parameter is before the now-optional size parameter. The code warns about it now, but it will break in PDF::Writer 2.0.
+Added #transform_matrix.
+Fixed compression. <b>NOTE</b>: Compression must be set early in the documentation process, or only some items will be compressed in the document. The various #save_as methods have been changed to reflect this fact.
+Enabled the placement of encoding differences dictionaries in the resulting PDF document. This change should be considered experimental.
+Added TTF licence checking. The embedding of a file not licenced for inclusion in a document will continue, but a warning will be output to standard error. This code has been gakked from FPDF (http://www.fpdf.org).
+Properly supporting symbolic font flags now.
+Added the ability to make images clickable links with any of the three image insertion methods.
+.endblist }}}
+
 2<Version 1.0.1: June 13, 2005>
+.blist {{{
+Fixed a few minor gem issues.
+Renamed bin/manual to bin/techbook.
+Fixed the manual.pwd locator for the default install.
+Added support and documentation for a separately downloadable demo package.
+Expanded the installation documentation.
+.endblist }}}
 
 2<Version 1.0.0: June 12, 2005>
 .blist {{{
@@ -5026,7 +5475,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 3<Works Included Under Other Licences>
-4<lib/pdf/writer/graphics/imageinfo.rb>
+4<pdf/writer/graphics/imageinfo.rb>
 PDF::Writer includes a derivative of Keisuke Minami�s ImageSize library,
 which can be found at
 <c:alink uri="http://www.rubycgi.org/tools/index.en.htm">rubycgi</c:alink>.
@@ -5049,14 +5498,13 @@ Ruby
 Commons Attributions ShareAlike</c:alink> licence.
 
 4<Adobe PostScript AFM Files>
-The file �lib/pdf/writer/fonts/MustRead.html� and the 14 PostScript� AFM
-files it accompanies may be used, copied, and distributed for any purpose and
-without charge, with or without modification, provided that all copyright
-notices are retained; that the AFM files are not distributed without this
-file; that all modifications to this file or any of the AFM files are
-prominently noted in the modified file(s); and that this paragraph is not
-modified. Adobe Systems has no responsibility or obligation to support the
-use of the AFM files.
+The file �pdf/writer/fonts/MustRead.html� and the 14 PostScript� AFM files it
+accompanies may be used, copied, and distributed for any purpose and without
+charge, with or without modification, provided that all copyright notices are
+retained; that the AFM files are not distributed without this file; that all
+modifications to this file or any of the AFM files are prominently noted in
+the modified file(s); and that this paragraph is not modified. Adobe Systems
+has no responsibility or obligation to support the use of the AFM files.
 
 3<Other Credits>
 4<R & OS PDF Class for PDF>
@@ -5065,16 +5513,18 @@ uri="http://www.ros.co.nz/pdf/">R & OS PDF class for PHP</c:alink>, which is
 released as public domain.
 
 4<Standard Deviation Chart>
-The standard deviation chart (lib/pdf/charts/stddev.rb) class is based on
+The standard deviation chart (pdf/charts/stddev.rb) class is based on
 work by <c:alink uri="mailto:cewing@u.washington.edu">Cris Ewing</c:alink> of
 the University of Washington School of Medicine, originally created for the R
 & OS PDF class for PHP. He has graciously donated the code for PDF::Writer
 for Ruby.
 
-4<Code Pages and Encoding>
-The code page handling routines are loosely based on routines in FPDF, both
-the <c:alink uri="http://www.fpd.org">PHP</c:alink> and <c:alink
-uri="http://brian.imxcc.com/">Ruby</c:alink> versions.
+4<bluesmoke.jpg>
+The logo image for PDF::Writer, bluesmoke.jpg, is modified from a picture
+taken by <c:alink uri="mailto:matthewbowden@gmail.com">Matthew "TheSaint"
+Bowden</c:alink> and is available on the stock.xchng� at <c:alink
+uri="http://www.sxc.hu/browse.phtml?f=view&id=275430">http://www.sxc.hu/browse.phtml?f=view&id=275430</c:alink>.
+Many thanks to Matthew for the use of this image.
 
 3<Patents Covering the Adobe PDF Format>
 4<ADOBE PATENTS>
@@ -5146,9 +5596,6 @@ pdf.stop_page_numbering(true, :current)
 #   Licensed under a MIT-style licence. See LICENCE in the main distribution
 #   for full licensing information.
 #
-# $Id: manual.pwd,v 1.41 2005/06/13 19:32:37 austin Exp $
+# $Id: manual.pwd,v 1.50 2005/06/29 19:32:07 austin Exp $
 # vim: sts=2 sw=2 ts=4 et ai tw=77 foldmethod=marker foldcolumn=2
 #++
-# Blue Smoke image by Matthew "thesaint" Bowden, <matthewbowden@gmail.com>. 
-# http://www.sxc.hu/browse.phtml?f=view&id=275430
-# http://www.sxc.hu/browse.phtml?f=profile&l=thesaint