From e2f017af7599617065e54b1ad68a0ccc6afaf980 Mon Sep 17 00:00:00 2001
From: gregor herrmann <gregoa@debian.org>
Date: Fri, 15 Dec 2023 21:25:39 +0100
Subject: New upstream version 3.026

---
 lib/PDF/Builder/Annotation.pm                      | 148 +++-
 lib/PDF/Builder/Basic/PDF.pm                       |   2 +-
 lib/PDF/Builder/Basic/PDF/Array.pm                 |  73 +-
 lib/PDF/Builder/Basic/PDF/Bool.pm                  |  24 +-
 lib/PDF/Builder/Basic/PDF/Dict.pm                  |  59 +-
 lib/PDF/Builder/Basic/PDF/File.pm                  | 267 ++++--
 lib/PDF/Builder/Basic/PDF/Filter.pm                |  26 +-
 lib/PDF/Builder/Basic/PDF/Filter/ASCII85Decode.pm  |   2 +-
 lib/PDF/Builder/Basic/PDF/Filter/ASCIIHexDecode.pm |   2 +-
 lib/PDF/Builder/Basic/PDF/Filter/FlateDecode.pm    |  23 +-
 lib/PDF/Builder/Basic/PDF/Filter/LZWDecode.pm      |  71 +-
 .../Builder/Basic/PDF/Filter/RunLengthDecode.pm    |   2 +-
 lib/PDF/Builder/Basic/PDF/Literal.pm               |   2 +-
 lib/PDF/Builder/Basic/PDF/Name.pm                  |  50 +-
 lib/PDF/Builder/Basic/PDF/Null.pm                  |  58 +-
 lib/PDF/Builder/Basic/PDF/Number.pm                |  24 +-
 lib/PDF/Builder/Basic/PDF/Objind.pm                | 109 ++-
 lib/PDF/Builder/Basic/PDF/Page.pm                  |  32 +-
 lib/PDF/Builder/Basic/PDF/Pages.pm                 | 102 ++-
 lib/PDF/Builder/Basic/PDF/String.pm                |  58 +-
 lib/PDF/Builder/Basic/PDF/Utils.pm                 |  92 +-
 lib/PDF/Builder/Content.pm                         | 923 ++++++++++++++++-----
 lib/PDF/Builder/Content/Hyphenate_basic.pm         |   2 +-
 lib/PDF/Builder/Content/Text.pm                    | 226 +++--
 lib/PDF/Builder/Docs.pm                            | 574 +++++++++++--
 lib/PDF/Builder/FontManager.pm                     |  69 +-
 lib/PDF/Builder/Lite.pm                            | 362 ++++++--
 lib/PDF/Builder/Matrix.pm                          |   2 +-
 lib/PDF/Builder/NamedDestination.pm                |  62 +-
 lib/PDF/Builder/Outline.pm                         | 188 ++++-
 lib/PDF/Builder/Outlines.pm                        |   2 +-
 lib/PDF/Builder/Page.pm                            | 322 ++++---
 lib/PDF/Builder/Resource.pm                        |  26 +-
 lib/PDF/Builder/Resource/BaseFont.pm               | 386 +++++++--
 lib/PDF/Builder/Resource/CIDFont.pm                |  87 +-
 lib/PDF/Builder/Resource/CIDFont/CJKFont.pm        |  44 +-
 lib/PDF/Builder/Resource/CIDFont/TrueType.pm       | 127 ++-
 .../Builder/Resource/CIDFont/TrueType/FontFile.pm  |   2 +-
 lib/PDF/Builder/Resource/ColorSpace.pm             |  34 +-
 lib/PDF/Builder/Resource/ColorSpace/DeviceN.pm     |  14 +-
 lib/PDF/Builder/Resource/ColorSpace/Indexed.pm     |  20 +-
 .../Builder/Resource/ColorSpace/Indexed/ACTFile.pm |  16 +-
 lib/PDF/Builder/Resource/ColorSpace/Indexed/Hue.pm |  14 +-
 .../Resource/ColorSpace/Indexed/WebColor.pm        |  18 +-
 lib/PDF/Builder/Resource/ColorSpace/Separation.pm  |  32 +-
 lib/PDF/Builder/Resource/Colors.pm                 |   2 +-
 lib/PDF/Builder/Resource/ExtGState.pm              | 284 ++++++-
 lib/PDF/Builder/Resource/Font.pm                   |  34 +-
 lib/PDF/Builder/Resource/Font/BdFont.pm            |  14 +-
 lib/PDF/Builder/Resource/Font/CoreFont.pm          |  65 +-
 .../Builder/Resource/Font/CoreFont/bankgothic.pm   |   2 +-
 lib/PDF/Builder/Resource/Font/CoreFont/courier.pm  |   2 +-
 .../Builder/Resource/Font/CoreFont/courierbold.pm  |   2 +-
 .../Resource/Font/CoreFont/courierboldoblique.pm   |   2 +-
 .../Resource/Font/CoreFont/courieroblique.pm       |   2 +-
 lib/PDF/Builder/Resource/Font/CoreFont/georgia.pm  |   2 +-
 .../Builder/Resource/Font/CoreFont/georgiabold.pm  |   2 +-
 .../Resource/Font/CoreFont/georgiabolditalic.pm    |   2 +-
 .../Resource/Font/CoreFont/georgiaitalic.pm        |   2 +-
 .../Builder/Resource/Font/CoreFont/helvetica.pm    |   2 +-
 .../Resource/Font/CoreFont/helveticabold.pm        |   2 +-
 .../Resource/Font/CoreFont/helveticaboldoblique.pm |   2 +-
 .../Resource/Font/CoreFont/helveticaoblique.pm     |   2 +-
 lib/PDF/Builder/Resource/Font/CoreFont/symbol.pm   |   2 +-
 .../Builder/Resource/Font/CoreFont/timesbold.pm    |   2 +-
 .../Resource/Font/CoreFont/timesbolditalic.pm      |   2 +-
 .../Builder/Resource/Font/CoreFont/timesitalic.pm  |   2 +-
 .../Builder/Resource/Font/CoreFont/timesroman.pm   |   2 +-
 .../Builder/Resource/Font/CoreFont/trebuchet.pm    |   2 +-
 .../Resource/Font/CoreFont/trebuchetbold.pm        |   2 +-
 .../Resource/Font/CoreFont/trebuchetbolditalic.pm  |   2 +-
 .../Resource/Font/CoreFont/trebuchetitalic.pm      |   2 +-
 lib/PDF/Builder/Resource/Font/CoreFont/verdana.pm  |   2 +-
 .../Builder/Resource/Font/CoreFont/verdanabold.pm  |   2 +-
 .../Resource/Font/CoreFont/verdanabolditalic.pm    |   2 +-
 .../Resource/Font/CoreFont/verdanaitalic.pm        |   2 +-
 lib/PDF/Builder/Resource/Font/CoreFont/webdings.pm |   2 +-
 .../Builder/Resource/Font/CoreFont/wingdings.pm    |   2 +-
 .../Builder/Resource/Font/CoreFont/zapfdingbats.pm |   2 +-
 lib/PDF/Builder/Resource/Font/Postscript.pm        | 101 ++-
 lib/PDF/Builder/Resource/Font/SynFont.pm           |  10 +-
 lib/PDF/Builder/Resource/Glyphs.pm                 |   2 +-
 lib/PDF/Builder/Resource/PaperSizes.pm             |  19 +-
 lib/PDF/Builder/Resource/Pattern.pm                |  16 +-
 lib/PDF/Builder/Resource/Shading.pm                |   2 +-
 lib/PDF/Builder/Resource/UniFont.pm                |  68 +-
 lib/PDF/Builder/Resource/XObject.pm                |  24 +-
 lib/PDF/Builder/Resource/XObject/Form.pm           |  36 +-
 lib/PDF/Builder/Resource/XObject/Form/BarCode.pm   |  37 +-
 .../Resource/XObject/Form/BarCode/codabar.pm       |  17 +-
 .../Resource/XObject/Form/BarCode/code128.pm       |  11 +-
 .../Resource/XObject/Form/BarCode/code3of9.pm      |  17 +-
 .../Builder/Resource/XObject/Form/BarCode/ean13.pm |  17 +-
 .../Resource/XObject/Form/BarCode/int2of5.pm       |  19 +-
 lib/PDF/Builder/Resource/XObject/Form/Hybrid.pm    |  20 +-
 lib/PDF/Builder/Resource/XObject/Image.pm          | 108 ++-
 lib/PDF/Builder/Resource/XObject/Image/GD.pm       |  13 +-
 lib/PDF/Builder/Resource/XObject/Image/GIF.pm      |  19 +-
 lib/PDF/Builder/Resource/XObject/Image/JPEG.pm     |  10 +-
 lib/PDF/Builder/Resource/XObject/Image/PNG.pm      |  19 +-
 lib/PDF/Builder/Resource/XObject/Image/PNG_IPL.pm  |  16 +-
 lib/PDF/Builder/Resource/XObject/Image/PNM.pm      |  13 +-
 lib/PDF/Builder/Resource/XObject/Image/TIFF.pm     |  35 +-
 .../Builder/Resource/XObject/Image/TIFF/File.pm    |  17 +-
 .../Builder/Resource/XObject/Image/TIFF/File_GT.pm |  17 +-
 lib/PDF/Builder/Resource/XObject/Image/TIFF_GT.pm  |  18 +-
 lib/PDF/Builder/UniWrap.pm                         |   2 +-
 lib/PDF/Builder/Util.pm                            |  46 +-
 lib/PDF/Builder/ViewerPreferences.pm               |  40 +-
 109 files changed, 4652 insertions(+), 1372 deletions(-)

(limited to 'lib/PDF/Builder')

diff --git a/lib/PDF/Builder/Annotation.pm b/lib/PDF/Builder/Annotation.pm
index db08e50..150dfe5 100644
--- a/lib/PDF/Builder/Annotation.pm
+++ b/lib/PDF/Builder/Annotation.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Basic::PDF::Dict';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use PDF::Builder::Basic::PDF::Utils;
 use List::Util qw(min max);
@@ -41,14 +41,18 @@ available icon set may be larger or smaller than given here, and some Readers
 activate an annotation on a single mouse click, while others require a double
 click. Not all features provided here may be available on all PDF Readers.
 
-=over
+=head2 new
+
+    $annotation = PDF::Builder::Annotation->new()
 
-=item $annotation = PDF::Builder::Annotation->new()
+=over
 
 Returns an annotation object (called from $page->annotation()).
 
 It is normally I<not> necessary to explicitly call this method (see examples).
 
+=back
+
 =cut
 
 # %opts removed, as there are currently none
@@ -77,13 +81,13 @@ sub new {
 # note that %opts is given as the only format in most cases, as rect
 # is a mandatory "option"
 
-=back
-
 =head2 Annotation types
 
-=over
+=head3 link
+
+    $annotation->link($page, %opts)
 
-=item $annotation->link($page, %opts)
+=over
 
 Defines the annotation as a launch-page with page C<$page> (within I<this>
 document) and opts %opts (rect, border, color, I<fit>: see 
@@ -93,6 +97,8 @@ B<Note> that C<$page> is I<not> a simple page number, but is a page structure
 such as C<$pdf-E<gt>openpage(page_number)>, I<or> a Named Destination defined
 elsewhere. 
 
+=back
+
 =cut
 
 # consider goto() as alias, for consistency with NamedDestination
@@ -123,7 +129,11 @@ sub link {
     return $self;
 }
 
-=item $annotation->pdf($pdffile, $page_number, %opts)
+=head3 pdf, pdfile, pdf_file
+
+    $annotation->pdf($pdffile, $page_number, %opts)
+
+=over
 
 Defines the annotation as a PDF-file with filepath C<$pdffile>, on page 
 C<$page_number>, and opts %opts (rect, border, color, I<fit>: see 
@@ -138,6 +148,8 @@ Originally this method was named C<pdfile>, and then C<pdf_file> but a recent
 PDF::API2 change made it C<pdf>. For compatibility, it has been changed to 
 C<pdf>, with C<pdfile> and C<pdf_file> still available as aliases.
 
+=back
+
 =cut
 
 sub pdfile { return pdf(@_); } ## no critic 
@@ -165,7 +177,11 @@ sub pdf {
     return $self;
 }
 
-=item $annotation->launch($file, %opts)
+=head3 launch, file
+
+    $annotation->launch($file, %opts)
+
+=over
 
 Defines the annotation as a launch-file with filepath C<$file> (a local file)
 and options %opts (rect, border, color: see descriptions below). 
@@ -178,6 +194,8 @@ Originally this method was named C<file>, but a recent PDF::API2 change made it
 C<launch>. For compatibility, it has been changed to C<launch>, with C<file> 
 still available as an alias.
 
+=back
+
 =cut
 
 sub file { return launch(@_); } ## no critic
@@ -201,7 +219,11 @@ sub launch {
     return $self;
 }
 
-=item $annotation->uri($url, %opts)
+=head3 uri, url
+
+    $annotation->uri($url, %opts)
+
+=over
 
 Defines the annotation as a launch-url with url C<$url> and
 options %opts (rect, border, color: see descriptions below). 
@@ -213,6 +235,8 @@ Originally this method was named C<url>, but a recent PDF::API2 change made it
 C<uri>. For compatibility, it has been changed to C<uri>, with C<url> still
 available as an alias.
 
+=back
+
 =cut
 
 sub url { return uri(@_); } ## no critic
@@ -236,7 +260,11 @@ sub uri {
     return $self;
 }
 
-=item $annotation->text($text, %opts)
+=head3 text
+
+    $annotation->text($text, %opts)
+
+=over
 
 Defines the annotation as a text note with content string C<$text> and
 options %opts (rect, color, text, open: see descriptions below). 
@@ -252,6 +280,8 @@ rectangle). The icon size is fixed, and its fill color set by C<color>.
 
 Additional options:
 
+=back
+
 =over
 
 =item icon => name_string
@@ -317,7 +347,11 @@ sub text {
     return $self;
 }
 
-=item $annotation->markup($text, $PointList, $highlight, %opts)
+=head3 markup
+
+    $annotation->markup($text, $PointList, $highlight, %opts)
+
+=over
 
 Defines the annotation as a text note with content string C<$text> and
 options %opts (color, text, open, opacity: see descriptions below). 
@@ -328,6 +362,8 @@ C<text> is the popup's label string, not to be confused with the main C<$text>.
 There is no icon. Instead, the annotated text marked by C<$PointList> is
 highlighted in one of four ways specified by C<$highlight>. 
 
+=back
+
 =over
 
 =item $PointList => [ 8n numbers ]
@@ -428,7 +464,11 @@ sub markup {
     return $self;
 }
 
-=item $annotation->movie($file, $contentType, %opts)
+=head3 movie
+
+    $annotation->movie($file, $contentType, %opts)
+
+=over
 
 Defines the annotation as a movie from C<$file> with 
 content (MIME) type C<$contentType> and
@@ -440,6 +480,8 @@ player. It is known to play .avi and .wav files -- others have not been tested.
 Using Adobe Reader, it will not play .mpg files (unsupported type). More work
 is probably needed on this annotation method.
 
+=back
+
 =cut
 
 sub movie {
@@ -475,7 +517,11 @@ sub movie {
     return $self;
 }
 
-=item $annotation->file_attachment($file, %opts)
+=head3 file_attachment
+
+    $annotation->file_attachment($file, %opts)
+
+=over
 
 Defines the annotation as a file attachment with file $file and options %opts
 (rect, color: see descriptions below). Note that C<color> applies to
@@ -502,6 +548,8 @@ including the path, give the C<notrimpath> option.
 
 Options: 
 
+=back
+
 =over 
 
 =item icon => name_string
@@ -639,13 +687,13 @@ sub file_attachment {
 
 # =============== end of annotation types ========================
 
-=back
-
 =head2 Internal routines and common options
 
-=over
+=head3 rect
 
-=item $annotation->rect($llx,$lly, $urx,$ury)
+    $annotation->rect($llx,$lly, $urx,$ury)
+
+=over
 
 Sets the rectangle (active click area) of the annotation, given by 'rect' 
 option. This is any pair of diagonally opposite corners of the rectangle.
@@ -654,6 +702,8 @@ The default clickable area is the icon itself.
 
 Defining option. I<Note that this "option" is actually B<required>.>
 
+=back
+
 =over
 
 =item rect => [LLx, LLy, URx, URy]
@@ -673,7 +723,11 @@ sub rect {
     return $self;
 }
 
-=item $annotation->border(@b)
+=head3 border
+
+    $annotation->border(@b)
+
+=over
 
 Sets the border-style of the annotation, if applicable, as given by the
 border option. There are three entries in the array:
@@ -692,6 +746,8 @@ border C<[0 0 0]> (solid line of width 0, and thus invisible).
 
 Defining option:
 
+=back
+
 =over
 
 =item border => [CRh, CRv, W]
@@ -731,11 +787,17 @@ sub border {
     return $self;
 }
 
-=item $annotation->content(@lines)
+=head3 content
+
+    $annotation->content(@lines)
+
+=over
 
 Sets the text-content of the C<text()> annotation.
 This is a text string or array of strings.
 
+=back
+
 =cut
 
 sub content {
@@ -753,7 +815,11 @@ sub name {
     return $self;
 }
 
-=item $annotation->open($bool)
+=head3 open
+
+    $annotation->open($bool)
+
+=over
 
 Display the C<text()> annotation either open or closed, if applicable.
 
@@ -762,6 +828,8 @@ already open for editing, while "closed" has to be clicked on to edit it.
 
 Defining option:
 
+=back
+
 =over
 
 =item open => boolean
@@ -779,7 +847,11 @@ sub open {  ## no critic
     return $self;
 }
 
-=item $annotation->dest($page, I<fit_setting>)
+=head3 dest
+
+    $annotation->dest($page, I<fit_setting>)
+
+=over
 
 For certain annotation types (C<link> or C<pdf_file>), the I<fit_setting> 
 specifies how the content of the page C<$page> is to be fit to the window,
@@ -789,11 +861,17 @@ These fit settings are listed in L<PDF::Builder::Docs/Page Fit Options>.
 "xyz" is the B<default> fit setting, with position (left and top) and zoom
 the same as the calling page's ([undef, undef, undef]).
 
-=item $annotation->dest($name)
+=back
+
+    $annotation->dest($name)
+
+=over
 
 Connect the Annotation to a "Named Destination" defined elsewhere, including
 the optional desired I<fit> (default: xyz undef*3).
 
+=back
+
 =cut
 
 sub dest {
@@ -842,7 +920,11 @@ sub dest {
     return $self;
 }
 
-=item $annotation->Color(@color)
+=head3 Color
+
+    $annotation->Color(@color)
+
+=over
 
 Set the icon's fill color. The color is an array of 1, 3, or 4 numbers, each
 in the range 0.0 to 1.0. If 1 number is given, it is the grayscale value (0 = 
@@ -859,7 +941,9 @@ is black.
 
 Defining option:
 
-Named colors are not supported at this time.
+Named colors (e.g., 'black') are not supported at this time.
+
+=back
 
 =over
 
@@ -912,11 +996,17 @@ sub Color {
     return $self;
 }
 
-=item text => string
+=head3 text string
+
+    text => string
+
+=over
 
 Specify an optional B<text label> for annotation. This text or comment only
 shows up I<as a title> in the pop-up containing the file or text.
 
+=back
+
 =cut
 
 sub icon_appearance {
@@ -1039,8 +1129,4 @@ sub icon_appearance {
     return $self;
 }
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Basic/PDF.pm b/lib/PDF/Builder/Basic/PDF.pm
index e997191..f4e9a45 100644
--- a/lib/PDF/Builder/Basic/PDF.pm
+++ b/lib/PDF/Builder/Basic/PDF.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Basic::PDF;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.020'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Basic/PDF/Array.pm b/lib/PDF/Builder/Basic/PDF/Array.pm
index ac4b40e..18ede12 100644
--- a/lib/PDF/Builder/Basic/PDF/Array.pm
+++ b/lib/PDF/Builder/Basic/PDF/Array.pm
@@ -20,8 +20,8 @@ use base 'PDF::Builder::Basic::PDF::Objind';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 =head1 NAME
 
@@ -30,13 +30,17 @@ Inherits from L<PDF::Builder::Basic::PDF::Objind>
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    PDF::Array->new($parent, @values)
 
-=item PDF::Array->new($parent, @values)
+=over
 
 Creates an array with the given storage parent and an optional list of values to
 initialise the array with.
 
+=back
+
 =cut
 
 sub new {
@@ -49,9 +53,16 @@ sub new {
     return $self;
 }
 
-=item $a->outobjdeep($fh, $pdf)
+=head2 outobjdeep
 
-Outputs an array as a PDF array to the given filehandle.
+    $a->outobjdeep($fh, $pdf)
+
+=over
+
+Outputs an array as a PDF array to the given filehandle. It's unusual to
+need to call this method from user code.
+
+=back
 
 =cut
 
@@ -67,26 +78,34 @@ sub outobjdeep {
     return;
 }
 
-=item $a->elements()
+=head2 elements
+
+    $a->elements()
+
+=over
 
 Returns the contents of the array.
 
-Formerly called C<elementsof>, which is now B<deprecated>.
+=back
 
 =cut
 
-sub elementsof { return elements(@_); }
-
 sub elements {
     my $self = shift();
     return @{$self->{' val'}};
 }
 
-=item $a->add_elements(@elements)
+=head2 add_elements
+
+    $a->add_elements(@elements)
+
+=over
 
 Appends the given elements to the array. An element is only added if it
 is defined.
 
+=back
+
 =cut
 
 sub add_elements {
@@ -99,18 +118,18 @@ sub add_elements {
     return $self;
 }
 
-=item $a->remove_element($element)
+=head2 remove_element
+
+    $a->remove_element($element)
+
+=over
 
 Removes all occurrences of an element from an array.
 
-Formerly called C<removeobj>, which is now B<deprecated> and will be removed.
+=back
 
 =cut
 
-# not listed as deprecated, not used internally, should not have been
-# used in external code. remove after July 2021.
-sub removeobj { return remove_element(@_); }
-
 sub remove_element {
     my ($self, $element) = @_;
 
@@ -118,21 +137,33 @@ sub remove_element {
     return $self;
 }
 
-=item $a->val()
+=head2 val
+
+    $a->val()
+
+=over
 
 Returns a reference to the contents of the array.
 
+=back
+
 =cut
 
 sub val {
     return $_[0]->{' val'};
 }
 
-=item $a->copy($pdf)
+=head2 copy
+
+    $a->copy($pdf)
+
+=over
 
 Copies the array with deep-copy on elements which are not full PDF objects
 with respect to a particular $pdf output context.
 
+=back
+
 =cut
 
 sub copy {
@@ -151,8 +182,4 @@ sub copy {
     return $res;
 }
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Basic/PDF/Bool.pm b/lib/PDF/Builder/Basic/PDF/Bool.pm
index c163ca5..5dc796a 100644
--- a/lib/PDF/Builder/Basic/PDF/Bool.pm
+++ b/lib/PDF/Builder/Basic/PDF/Bool.pm
@@ -20,8 +20,8 @@ use base 'PDF::Builder::Basic::PDF::String';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 =head1 NAME
 
@@ -31,30 +31,36 @@ B<true> or B<false>
 
 =head1 METHODS
 
-=over
+=head2 convert
+
+    $b->convert($str)
 
-=item $b->convert($str)
+=over
 
 Converts a string into the string which will be stored.
 
+=back
+
 =cut
 
 sub convert {
     return $_[1] eq 'true';
 }
 
-=item $b->as_pdf()
+=head2 as_pdf
+
+    $b->as_pdf()
+
+=over
 
 Converts the value to a PDF output form.
 
+=back
+
 =cut
 
 sub as_pdf {
     return $_[0]->{'val'}? 'true': 'false';
 }
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Basic/PDF/Dict.pm b/lib/PDF/Builder/Basic/PDF/Dict.pm
index 05264c6..c2a4ecb 100644
--- a/lib/PDF/Builder/Basic/PDF/Dict.pm
+++ b/lib/PDF/Builder/Basic/PDF/Dict.pm
@@ -20,8 +20,8 @@ use base 'PDF::Builder::Basic::PDF::Objind';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 our $mincache = 16 * 1024 * 1024;
 
@@ -60,8 +60,17 @@ source PDF the stream starts.
 
 =head1 METHODS
 
+=head2 new
+
+    $d = PDF::Builder::Basic::PDF->new()
+
 =over
 
+Creates a new instance of a dictionary. The usual practice is to call 
+C<PDFDict()> instead.
+
+=back
+
 =cut
 
 sub new {
@@ -74,10 +83,16 @@ sub new {
     return $self;
 }
 
-=item $type = $d->type($type)
+=head2 type
+
+    $type = $d->type($type)
+
+=over
 
 Get/Set the standard Type key. It can be passed, and will return, a text value rather than a Name object.
 
+=back
+
 =cut
 
 sub type {
@@ -90,10 +105,16 @@ sub type {
     return $self->{'Type'}->val();
 }
 
-=item @filters = $d->filter(@filters)
+=head2 filter
+
+    @filters = $d->filter(@filters)
+
+=over
 
 Get/Set one or more filters being used by the optional stream attached to the dictionary.
 
+=back
+
 =cut
 
 sub filter {
@@ -113,10 +134,14 @@ sub filter {
     return $self->{'Filter'};
 }
 
-# Undocumented alias, which may be removed in a future release
+# Undocumented alias, which may be removed in a future release TBD
 sub filters { return filter(@_); }
 
-=item $d->outobjdeep($fh, $pdf)
+=head2 outobjdeep
+
+    $d->outobjdeep($fh, $pdf)
+
+=over
 
 Outputs the contents of the dictionary to a PDF file. This is a recursive call.
 
@@ -124,6 +149,8 @@ It also outputs a stream if the dictionary has a stream element. If this occurs
 then this method will calculate the length of the stream and insert it into the
 stream's dictionary.
 
+=back
+
 =cut
 
 sub outobjdeep {
@@ -234,7 +261,11 @@ sub outobjdeep {
     return;
 }
 
-=item $d->read_stream($force_memory)
+=head2 read_stream
+
+    $d->read_stream($force_memory)
+
+=over
 
 Reads in a stream from a PDF file. If the stream is greater than
 C<PDF::Dict::mincache> (defaults to 32768) bytes to be stored, then
@@ -243,6 +274,8 @@ file as a data cache. If $force_memory is set, this caching will not
 occur and the data will all be stored in the $self->{' stream'}
 variable.
 
+=back
+
 =cut
 
 sub read_stream {
@@ -316,18 +349,20 @@ sub read_stream {
     return $self;
 }
 
-=item $d->val()
+=head2 val
+
+    $d->val()
+
+=over
 
 Returns the dictionary, which is itself.
 
+=back
+
 =cut
 
 sub val {
     return $_[0];
 }
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Basic/PDF/File.pm b/lib/PDF/Builder/Basic/PDF/File.pm
index beafb51..e6561a3 100644
--- a/lib/PDF/Builder/Basic/PDF/File.pm
+++ b/lib/PDF/Builder/Basic/PDF/File.pm
@@ -20,8 +20,8 @@ package PDF::Builder::Basic::PDF::File;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 =head1 NAME
 
@@ -29,12 +29,12 @@ PDF::Builder::Basic::PDF::File - Holds the trailers and cross-reference tables f
 
 =head1 SYNOPSIS
 
- $p = PDF::Builder::Basic::PDF::File->open("filename.pdf", 1);
- $p->new_obj($obj_ref);
- $p->free_obj($obj_ref);
- $p->append_file();
- $p->close_file();
- $p->release();       # IMPORTANT!
+    $p = PDF::Builder::Basic::PDF::File->open("filename.pdf", 1);
+    $p->new_obj($obj_ref);
+    $p->free_obj($obj_ref);
+    $p->append_file();
+    $p->close_file();
+    $p->release();       # IMPORTANT!
 
 =head1 DESCRIPTION
 
@@ -142,10 +142,6 @@ is in PDF, which contains the location of the previous cross-reference table.
 
 =back
 
-=head1 METHODS
-
-=over
-
 =cut
 
 use Scalar::Util qw(blessed weaken);
@@ -189,12 +185,20 @@ use PDF::Builder::Basic::PDF::Pages;
 use PDF::Builder::Basic::PDF::Null;
 use POSIX qw(ceil floor);
 
-=item PDF::Builder::Basic::PDF::File->new()
+=head1 METHODS
+
+=head2 new
+
+    PDF::Builder::Basic::PDF::File->new()
+
+=over
 
 Creates a new, empty file object which can act as the host to other PDF objects.
 Since there is no file associated with this object, it is assumed that the
 object is created in readiness for creating a new PDF file.
 
+=back
+
 =cut
 
 sub new {
@@ -211,7 +215,11 @@ sub new {
     return $self;
 }
 
-=item $p = PDF::Builder::Basic::PDF::File->open($filename, $update, %options)
+=head2 open
+
+    $p = PDF::Builder::Basic::PDF::File->open($filename, $update, %options)
+
+=over
 
 Opens the file and reads all the trailers and cross reference tables to build
 a complete directory of objects.
@@ -241,6 +249,8 @@ longer fail on them, but merely comment on their existence.
 
 =back
 
+=back
+
 =cut
 
 sub open {
@@ -284,6 +294,7 @@ sub open {
        # out inline comment and create a separate comment further along).
     }
 
+    # there should always be 'startxref' within 16*64 bytes of end
     $fh->seek(0, 2);            # go to end of file
     my $end = $fh->tell();
     $self->{' epos'} = $end;
@@ -297,7 +308,8 @@ sub open {
             warn "Malformed PDF file $filename"; #orig 'die'
         }
     }
-    my $xpos = $1;
+    my $xpos = $1; # offset given after 'startxref'
+    # should point to either xref table ('xref'), or object with xref stream
     $self->{' xref_position'} = $xpos;
 
     my $tdict = $self->readxrtr($xpos, %options);
@@ -308,9 +320,13 @@ sub open {
     return $self;
 } # end of open()
 
-=item $new_version = $p->version($version, %opts) # Set 
+=head2 version
+
+    $new_version = $p->version($version, %opts) # Set 
 
-=item $ver = $p->version() # Get
+    $ver = $p->version() # Get
+
+=over
 
 Gets/sets the PDF version (e.g., 1.5). Setting sets both the header and
 trailer versions. Getting returns the higher of header and trailer versions.
@@ -322,6 +338,8 @@ A warning message is given if you attempt to I<decrease> the PDF version, as you
 might have already read in a higher level file, or used a higher level feature.
 This message is suppressed if the 'silent' option is given with any value.
 
+=back
+
 =cut
 
 sub version {
@@ -368,9 +386,13 @@ sub version {
     return $old_version;
 }
 
-=item $new_version = $p->header_version($version, %opts) # Set
+=head2 header_version
+
+    $new_version = $p->header_version($version, %opts) # Set
 
-=item $version = $p->header_version() # Get
+    $version = $p->header_version() # Get
+
+=over
 
 Gets/sets the PDF version stored in the file header.
 
@@ -381,6 +403,8 @@ A warning message is given if you attempt to I<decrease> the PDF version, as you
 might have already read in a higher level file, or used a higher level feature.
 This message is suppressed if the 'silent' option is given with any value.
 
+=back
+
 =cut
 
 sub header_version {
@@ -415,9 +439,13 @@ sub header_version {
     return $old_version;
 }
 
-=item $new_version = $p->trailer_version($version, %opts) # Set
+=head2 trailer_version
+
+    $new_version = $p->trailer_version($version, %opts) # Set
+
+    $version = $p->trailer_version() # Get
 
-=item $version = $p->trailer_version() # Get
+=over
 
 Gets/sets the PDF version stored in the document catalog.
 
@@ -432,6 +460,8 @@ A warning message is given if you attempt to I<decrease> the PDF version, as you
 might have already read in a higher level file, or used a higher level feature.
 This message is suppressed if the 'silent' option is given with any value.
 
+=back
+
 =cut
 
 sub trailer_version {
@@ -470,11 +500,17 @@ sub trailer_version {
     return $old_version;
 }
 
-=item $prev_version = $p->require_version($version)
+=head2 require_version
+
+    $prev_version = $p->require_version($version)
+
+=over
 
 Ensures that the PDF version is at least C<$version>. 
 Silently sets the version to the higher level.
 
+=back
+
 =cut
 
 sub require_version {
@@ -484,7 +520,11 @@ sub require_version {
     return $current_version;
 }
 
-=item $p->release()
+=head2 release
+
+    $p->release()
+
+=over
 
 Releases ALL of the memory used by the PDF document and all of its
 component objects.  After calling this method, do B<NOT> expect to
@@ -501,6 +541,8 @@ you've called this method, though, don't expect to be able to do
 anything else with the C<PDF::Builder::Basic::PDF::File> object; it'll
 have B<no> internal state whatsoever.
 
+=back
+
 =cut
 
 # Maintainer's Question: Couldn't this be handled by a DESTROY method
@@ -540,11 +582,17 @@ sub release {
     return;
 } # end of release()
 
-=item $p->append_file()
+=head2 append_file
+
+    $p->append_file()
+
+=over
 
 Appends the objects for output to the read file and then appends the 
 appropriate table.
 
+=back
+
 =cut
 
 sub append_file {
@@ -585,7 +633,11 @@ sub append_file {
     return;
 } # end of append_file()
 
-=item $p->out_file($fname)
+=head2 out_file
+
+    $p->out_file($fname)
+
+=over
 
 Writes a PDF file to a file of the given filename, based on the current list of
 objects to be output. It creates the trailer dictionary based on information
@@ -593,6 +645,8 @@ in C<$self>.
 
 $fname may be a string or an IO object.
 
+=back
+
 =cut
 
 sub out_file {
@@ -604,12 +658,18 @@ sub out_file {
     return $self;
 }
 
-=item $p->create_file($fname)
+=head2 create_file
+
+    $p->create_file($fname)
+
+=over
 
 Creates a new output file (no check is made of an existing open file) of
 the given filename or IO object. Note: make sure that C<< $p->{' version'} >>
 is set correctly before calling this function.
 
+=back
+
 =cut
 
 sub create_file {
@@ -638,10 +698,16 @@ sub create_file {
     return $self;
 }
 
-=item $p->close_file()
+=head2 close_file
+
+    $p->close_file()
+
+=over
 
 Closes up the open file for output, by outputting the trailer, etc.
 
+=back
+
 =cut
 
 sub close_file {
@@ -674,7 +740,11 @@ sub close_file {
     return $self;
 } # end of close_file()
 
-=item ($value, $str) = $p->readval($str, %opts)
+=head2 readval
+
+    ($value, $str) = $p->readval($str, %opts)
+
+=over
 
 Reads a PDF value from the current position in the file. If C<$str> is too 
 short, read some more from the current location in the file until the whole 
@@ -684,6 +754,8 @@ object is read. This is a recursive call which may slurp in a whole big stream
 Returns the recursive data structure read and also the current C<$str> that has 
 been read from the file.
 
+=back
+
 =cut
 
 sub readval {
@@ -918,10 +990,16 @@ sub readval {
     return ($result, $str);
 } # end of readval()
 
-=item $ref = $p->read_obj($objind, %opts)
+=head2 read_obj
+
+    $ref = $p->read_obj($objind, %opts)
+
+=over
 
 Given an indirect object reference, locate it and read the object returning
-the read in object.
+the read-in object.
+
+=back
 
 =cut
 
@@ -934,10 +1012,16 @@ sub read_obj {
     return $objind;
 }
 
-=item $ref = $p->read_objnum($num, $gen, %opts)
+=head2 read_objnum
+
+    $ref = $p->read_objnum($num, $gen, %opts)
+
+=over
 
 Returns a fully read object of given number and generation in this file
 
+=back
+
 =cut
 
 sub read_objnum {
@@ -1014,12 +1098,18 @@ sub read_objnum {
     return $object;
 } # end of read_objnum()
 
-=item $objind = $p->new_obj($obj)
+=head2 new_obj
+
+    $objind = $p->new_obj($obj)
+
+=over
 
 Creates a new, free object reference based on free space in the cross reference 
 chain. If nothing is free, then think up a new number. If C<$obj>, then turns 
 that object into this new object rather than returning a new object.
 
+=back
+
 =cut
 
 sub new_obj {
@@ -1072,11 +1162,17 @@ sub new_obj {
     }
 }
 
-=item $p->out_obj($obj)
+=head2 out_obj
+
+    $p->out_obj($obj)
+
+=over
 
 Indicates that the given object reference should appear in the output xref
 table whether with data or freed.
 
+=back
+
 =cut
 
 sub out_obj {
@@ -1095,10 +1191,16 @@ sub out_obj {
     return $obj;
 }
 
-=item $p->free_obj($obj)
+=head2 free_obj
+
+    $p->free_obj($obj)
+
+=over
 
 Marks an object reference for output as being freed.
 
+=back
+
 =cut
 
 sub free_obj {
@@ -1111,10 +1213,16 @@ sub free_obj {
     return;
 }
 
-=item $p->remove_obj($objind)
+=head2 remove_obj
+
+    $p->remove_obj($objind)
+
+=over
 
 Removes the object from all places where we might remember it.
 
+=back
+
 =cut
 
 sub remove_obj {
@@ -1132,9 +1240,13 @@ sub remove_obj {
     return $self;
 }
 
-=item $p->ship_out(@objects)
+=head2 ship_out
 
-=item $p->ship_out()
+    $p->ship_out(@objects)
+
+    $p->ship_out()
+
+=over
 
 Ships the given objects (or all objects for output if C<@objects> is empty) to
 the currently open output file (assuming there is one). Freed objects are not
@@ -1143,6 +1255,8 @@ becomes its source and it will not be shipped again unless out_obj is called
 again. Notice that a shipped out object can be re-output or even freed, but
 that it will not cause the data already output to be changed.
 
+=back
+
 =cut
 
 sub ship_out {
@@ -1185,12 +1299,18 @@ sub ship_out {
     return $self;
 } # end of ship_out()
 
-=item $p->copy($outpdf, \&filter)
+=head2 copy
+
+    $p->copy($outpdf, \&filter)
+
+=over
 
 Iterates over every object in the file reading the object, calling C<filter> 
 with the object, and outputting the result. If C<filter> is not defined, 
 just copies input to output.
 
+=back
+
 =cut
 
 sub copy {
@@ -1237,21 +1357,23 @@ sub copy {
     return $self;
 } # end of copy()
 
-=back
-
 =head1 PRIVATE METHODS & FUNCTIONS
 
 The following methods and functions are considered B<private> to this class. 
 This does not mean you cannot use them if you have a need, just that they 
 aren't really designed for users of this class.
 
-=over
+=head2 locate_obj
 
-=item $offset = $p->locate_obj($num, $gen)
+    $offset = $p->locate_obj($num, $gen)
+
+=over
 
 Returns a file offset to the object asked for by following the chain of cross
 reference tables until it finds the one you want.
 
+=back
+
 =cut
 
 sub locate_obj {
@@ -1274,12 +1396,18 @@ sub locate_obj {
     return;
 }
 
-=item update($fh, $str, $instream)
+=head2 update
+
+    update($fh, $str, $instream)
+
+=over
 
 Keeps reading C<$fh> for more data to ensure that C<$str> has at least a line 
 full for C<readval> to work on. At this point we also take the opportunity to 
 ignore comments.
 
+=back
+
 =cut
 
 sub update {
@@ -1311,11 +1439,17 @@ sub update {
     return $str;
 } # end of update()
 
-=item $objind = $p->test_obj($num, $gen)
+=head2 test_obj
+
+    $objind = $p->test_obj($num, $gen)
+
+=over
 
 Tests the cache to see whether an object reference (which may or may not have
 been getobj()ed) has been cached. Returns it if it has.
 
+=back
+
 =cut
 
 sub test_obj {
@@ -1324,10 +1458,16 @@ sub test_obj {
     return $self->{' objcache'}{$num, $gen};
 }
 
-=item $p->add_obj($objind)
+=head2 add_obj
+
+    $p->add_obj($objind)
+
+=over
 
 Adds the given object to the internal object cache.
 
+=back
+
 =cut
 
 sub add_obj {
@@ -1339,7 +1479,11 @@ sub add_obj {
     return $obj;
 }
 
-=item $tdict = $p->readxrtr($xpos, %options)
+=head2 readxrtr
+
+    $tdict = $p->readxrtr($xpos, %options)
+
+=over
 
 Recursive function which reads each of the cross-reference and trailer tables
 in turn until there are no more.
@@ -1355,6 +1499,8 @@ for details.
 
 See C<open> for options allowed.
 
+=back
+
 =cut
 
 sub _unpack_xref_stream {
@@ -1403,7 +1549,8 @@ sub _unpack_xref_stream {
 
 sub readxrtr {
     my ($self, $xpos, %options) = @_;
-    # $xpos SHOULD be pointing to "xref" keyword
+    # $xpos SHOULD be pointing to "xref" keyword 
+    #    UNLESS an xref stream is in use (v 1.5+)
     # copy dashed option names to preferred undashed names
     if (defined $options{'-diags'} && !defined $options{'diags'}) { $options{'diags'} = delete($options{'-diags'}); }
 
@@ -1423,7 +1570,7 @@ sub readxrtr {
    #    $buf = update($fh, $buf);
    #}
 
-    if ($buf =~ s/^xref$cr//i) {   # remove xrefEOL from buffer
+    if ($buf =~ s/^xref$cr//i) {   # xref table, remove xrefEOL from buffer
         # Plain XRef tables.
         #
         # look to match startobj# count# EOL of first (or only) subsection
@@ -1610,7 +1757,7 @@ sub readxrtr {
 
         ($tdict, $buf) = $self->readval($buf);
 
-    } elsif ($buf =~ m/^(\d+)\s+(\d+)\s+obj/i) {
+    } elsif ($buf =~ m/^(\d+)\s+(\d+)\s+obj/i) { # object for xref stream
         my ($xref_obj, $xref_gen) = ($1, $2);
 	$PDF::Builder::global_pdf->verCheckOutput(1.5, "importing cross-reference stream");
         # XRef streams
@@ -1687,14 +1834,20 @@ sub readxrtr {
     return $tdict;
 } # end of readxrtr()
 
-=item $p->out_trailer($tdict, $update)
+=head2 out_trailer
+
+    $p->out_trailer($tdict, $update)
 
-=item $p->out_trailer($tdict)
+    $p->out_trailer($tdict)
+
+=over
 
 Outputs the body and trailer for a PDF file by outputting all the objects in
 the ' outlist' and then outputting a xref table for those objects and any
 freed ones. It then outputs the trailing dictionary and the trailer code.
 
+=back
+
 =cut
 
 sub out_trailer {
@@ -1838,10 +1991,16 @@ sub out_trailer {
     return;
 } # end of out_trailer()
 
-=item PDF::Builder::Basic::PDF::File->_new()
+=head2 _new
+
+    PDF::Builder::Basic::PDF::File->_new()
+
+=over
 
 Creates a very empty PDF file object (used by new() and open())
 
+=back
+
 =cut
 
 sub _new {
@@ -1860,13 +2019,11 @@ sub _new {
 
 1;
 
-=back
-
 =head1 AUTHOR
 
 Martin Hosken Martin_Hosken@sil.org
 
-Copyright Martin Hosken 1999 and onwards
+Copyright Martin Hosken 1999 
 
 No warranty or expression of effectiveness, least of all regarding anyone's
 safety, is implied in this software or documentation.
diff --git a/lib/PDF/Builder/Basic/PDF/Filter.pm b/lib/PDF/Builder/Basic/PDF/Filter.pm
index f09ac70..1b5c741 100644
--- a/lib/PDF/Builder/Basic/PDF/Filter.pm
+++ b/lib/PDF/Builder/Basic/PDF/Filter.pm
@@ -18,8 +18,8 @@ package PDF::Builder::Basic::PDF::Filter;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use PDF::Builder::Basic::PDF::Filter::ASCII85Decode;
 use PDF::Builder::Basic::PDF::Filter::ASCIIHexDecode;
@@ -56,14 +56,22 @@ the same time.
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    PDF::Builder::Basic::PDF::Filter->new()
 
-=item PDF::Builder::Basic::PDF::Filter->new()
+=over
 
 Creates a new filter object with empty state information ready for processing
 data both input and output.
 
-=item $dat = $f->infilt($str, $isend)
+=back
+
+=head2 infilt
+
+    $dat = $f->infilt($str, $isend)
+
+=over
 
 Filters from output to input the data. Notice that C<$isend == 0> implies that 
 there is more data to come and so following it C<$f> may contain state 
@@ -75,7 +83,13 @@ C<$f> will be that the state information is empty. Error messages are most
 likely to occur here since if there is required state information to be stored 
 following this data, then that would imply an error in the data.
 
-=item $str = $f->outfilt($dat, $isend)
+=back
+
+=head2 outfilt
+
+    $str = $f->outfilt($dat, $isend)
+
+=over
 
 Filter stored data ready for output. Parallels C<infilt>.
 
diff --git a/lib/PDF/Builder/Basic/PDF/Filter/ASCII85Decode.pm b/lib/PDF/Builder/Basic/PDF/Filter/ASCII85Decode.pm
index ea436b8..d5f3e93 100644
--- a/lib/PDF/Builder/Basic/PDF/Filter/ASCII85Decode.pm
+++ b/lib/PDF/Builder/Basic/PDF/Filter/ASCII85Decode.pm
@@ -5,7 +5,7 @@ use base 'PDF::Builder::Basic::PDF::Filter';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.010'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Basic/PDF/Filter/ASCIIHexDecode.pm b/lib/PDF/Builder/Basic/PDF/Filter/ASCIIHexDecode.pm
index b1be2aa..8af79f7 100644
--- a/lib/PDF/Builder/Basic/PDF/Filter/ASCIIHexDecode.pm
+++ b/lib/PDF/Builder/Basic/PDF/Filter/ASCIIHexDecode.pm
@@ -5,7 +5,7 @@ use base 'PDF::Builder::Basic::PDF::Filter';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '2.029'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Basic/PDF/Filter/FlateDecode.pm b/lib/PDF/Builder/Basic/PDF/Filter/FlateDecode.pm
index 712f9d7..7ed60cc 100644
--- a/lib/PDF/Builder/Basic/PDF/Filter/FlateDecode.pm
+++ b/lib/PDF/Builder/Basic/PDF/Filter/FlateDecode.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Basic::PDF::Filter';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.016'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use POSIX qw(ceil floor);
 
@@ -18,18 +18,17 @@ PDF::Builder::Basic::PDF::Filter::FlateDecode - compress and uncompress stream f
 
 =cut
 
+# not specifying a minimum version
 BEGIN {
     eval { require Compress::Zlib };
     $havezlib = !$@;
 }
 
 sub new {
-    return unless $havezlib;
+    return unless $havezlib;  # undef returned should prove fatal
     my ($class, $decode_parms) = @_;
 
-    my ($self) = {
-        DecodeParms => $decode_parms,
-    };
+    my ($self) = { 'DecodeParms' => $decode_parms };
 
     $self->{'outfilt'} = Compress::Zlib::deflateInit(
         -Level   => 9,
@@ -54,7 +53,7 @@ sub infilt {
 
     if ($self->{'DecodeParms'} and $self->{'DecodeParms'}->{'Predictor'}) {
         my $predictor = $self->{'DecodeParms'}->{'Predictor'}->val();
-        if ($predictor == 2) {
+        if      ($predictor == 2) {
             die "The TIFF predictor logic has not been implemented";
         } elsif ($predictor >= 10 and $predictor <= 15) {
             $result = $self->_depredict_png($result);
@@ -74,11 +73,11 @@ sub _depredict_png {
     $stream = $self->{'_depredict_next'} . $stream if defined $self->{'_depredict_next'};
     $prev   = $self->{'_depredict_prev'}           if defined $self->{'_depredict_prev'};
 
-    my $alpha   = $param->{'Alpha'}           ? $param->{'Alpha'}->val(): 0;
-    my $bpc     = $param->{'BitsPerComponent'}? $param->{'BitsPerComponent'}->val(): 8;
-    my $colors  = $param->{'Colors'}          ? $param->{'Colors'}->val(): 1;
-    my $columns = $param->{'Columns'}         ? $param->{'Columns'}->val(): 1;
-    my $height  = $param->{'Height'}          ? $param->{'Height'}->val(): 0;
+    my $alpha   = $param->{'Alpha'}            ? $param->{'Alpha'}->val(): 0;
+    my $bpc     = $param->{'BitsPerComponent'} ? $param->{'BitsPerComponent'}->val(): 8;
+    my $colors  = $param->{'Colors'}           ? $param->{'Colors'}->val(): 1;
+    my $columns = $param->{'Columns'}          ? $param->{'Columns'}->val(): 1;
+    my $height  = $param->{'Height'}           ? $param->{'Height'}->val(): 0;
 
     my $comp     = $colors + $alpha;
     my $bpp      = ceil($bpc * $comp / 8);
diff --git a/lib/PDF/Builder/Basic/PDF/Filter/LZWDecode.pm b/lib/PDF/Builder/Basic/PDF/Filter/LZWDecode.pm
index d4e91dd..7d444e6 100644
--- a/lib/PDF/Builder/Basic/PDF/Filter/LZWDecode.pm
+++ b/lib/PDF/Builder/Basic/PDF/Filter/LZWDecode.pm
@@ -6,8 +6,8 @@ use Carp;
 use POSIX;
 use base 'PDF::Builder::Basic::PDF::Filter::FlateDecode';
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.023'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 =head1 NAME
 
@@ -15,10 +15,12 @@ PDF::Builder::Basic::PDF::Filter::LZWDecode - compress and uncompress stream fil
 
 =cut
 
+# extensively extended from PDF::API2 version, for TIFF support
+
 sub new {
     my ($class, $decode_parms) = @_;
 
-    my $self = { DecodeParms => $decode_parms, };
+    my $self = { 'DecodeParms' => $decode_parms };
 
     bless $self, $class;
     $self->_reset_code();
@@ -38,15 +40,15 @@ sub infilt {
     }
     $self->{'table'} = [ map { chr } 0 .. $self->{'clear_table'} - 1 ];
 
-    while ( $data ne q{} ) {
+    while ($data ne q{}) {
         ($code, $partial_code, $partial_bits) =
           $self->read_dat(\$data, $partial_code, $partial_bits,
             $self->{'code_length'});
         last unless defined $code;
 
         unless ($early_change) {
-            if ($self->{next_code} == (1 << $self->{code_length})
-                and $self->{code_length} < 12) {
+            if ($self->{'next_code'} == (1 << $self->{'code_length'})
+                and $self->{'code_length'} < 12) {
                 $self->{'code_length'}++;
             }
         }
@@ -71,7 +73,7 @@ sub infilt {
 
         if ($early_change) {
             if ($self->{'next_code'} == (1 << $self->{'code_length'})
-                and $self->{code_length} < 12) {
+                and $self->{'code_length'} < 12) {
                 $self->{'code_length'}++;
             }
         }
@@ -80,8 +82,9 @@ sub infilt {
     $self->{'partial_bits'} = $partial_bits;
 
     if ($self->_predictor_type() == 2) {
-        return $self->_depredict($result);
+	return $self->_depredict($result);
     }
+
     return $result;
 }
 
@@ -95,30 +98,30 @@ sub outfilt {
     $self->{'buf'}     = q{};
     $self->{'buf_pos'} = 0;
     $self->_write_code($self->{'clear_table'});
-
+ 
     if ($self->_predictor_type() == 2) {
         $str = $self->_predict($str);
     }
-
+ 
     for my $i (0 .. length($str)) {
         my $char = substr($str, $i, 1);
         $bytes_in += 1;
-
+ 
         if (exists $self->{'table'}{ $seen . $char }) {
             $seen .= $char;
             next;
         }
-
+ 
         $self->_write_code($self->{'table'}{$seen});
-
+ 
         $self->_new_code($seen . $char);
-
+ 
         $seen = $char;
-
+ 
         if ($self->{'at_max_code'}) {
             $self->_write_code($self->{'clear_table'});
             $self->_reset_code();
-
+ 
             undef $checkpoint;
             undef $last_ratio;
         }
@@ -132,10 +135,10 @@ sub outfilt {
     }
     return pack 'B*', $self->{'buf'};
 }
-
+ 
 sub _reset_code {
     my $self = shift;
-
+ 
     $self->{'initial_code_length'} = 9;
     $self->{'max_code_length'}     = 12;
     $self->{'code_length'}         = $self->{'initial_code_length'};
@@ -147,15 +150,15 @@ sub _reset_code {
     $self->{'table'} = { map { chr $_ => $_ } 0 .. $self->{'clear_table'} - 1 };
     return;
 }
-
+ 
 sub _new_code {
     my ($self, $word) = @_;
-
+ 
     if ($self->{'at_max_code'} == 0) {
         $self->{'table'}{$word} = $self->{'next_code'};
         $self->{'next_code'} += 1;
     }
-
+ 
     if ($self->{'next_code'} >= $self->{'next_increase'}) {
         if ($self->{'code_length'} < $self->{'max_code_length'}) {
             $self->{'code_length'}   += 1;
@@ -166,17 +169,17 @@ sub _new_code {
     }
     return;
 }
-
+ 
 sub _write_code {
     my ($self, $code) = @_;
-
+ 
     if (not defined $code) { return; }
-
+ 
     if ($code > (2**$self->{'code_length'})) {
         croak
           "Code $code too large for current code length $self->{'code_length'}";
     }
-
+ 
     for my $bit (reverse 0 .. ($self->{'code_length'} - 1)) {
         if (($code >> $bit) & 1) {
             $self->{'buf'} .= '1';
@@ -184,20 +187,20 @@ sub _write_code {
             $self->{'buf'} .= '0';
         }
     }
-
+ 
     $self->{'buf_pos'} += $self->{'code_length'};
     return;
 }
-
+ 
 sub read_dat {
     my ($self, $data_ref, $partial_code, $partial_bits, $code_length) = @_;
 
     if (not defined $partial_bits) { $partial_bits = 0; }
     if (not defined $partial_code) { $partial_code = 0; }
 
-    while ($partial_bits < $code_length ) {
+    while ($partial_bits < $code_length) {
         return (undef, $partial_code, $partial_bits) unless length($$data_ref);
-        $partial_code = ($partial_code << 8 ) + unpack('C', $$data_ref);
+        $partial_code = ($partial_code << 8) + unpack('C', $$data_ref);
         substr($$data_ref, 0, 1, q{});
         $partial_bits += 8;
     }
@@ -223,7 +226,7 @@ sub _predictor_type {
     }
     return 1;
 }
-
+ 
 sub _depredict {
     my ($self, $data) = @_;
     my $param = $self->{'DecodeParms'};
@@ -233,7 +236,7 @@ sub _depredict {
     my $colors  = $param->{'Colors'}  ? $param->{'Colors'}->val()  : 1;
     my $columns = $param->{'Columns'} ? $param->{'Columns'}->val() : 1;
     my $rows    = $param->{'Rows'}    ? $param->{'Rows'}->val()    : 0;
-
+ 
     my $comp = $colors + $alpha;
     my $bpp  = ceil($bpc * $comp / 8);
     my $max  = 256;
@@ -252,7 +255,7 @@ sub _depredict {
     }
     return $data;
 }
-
+ 
 sub _predict {
     my ($self, $data) = @_;
     my $param = $self->{'DecodeParms'};
@@ -262,7 +265,7 @@ sub _predict {
     my $colors  = $param->{'Colors'}  ? $param->{'Colors'}->val()  : 1;
     my $columns = $param->{'Columns'} ? $param->{'Columns'}->val() : 1;
     my $rows    = $param->{'Rows'}    ? $param->{'Rows'}->val()    : 0;
-
+ 
     my $comp = $colors + $alpha;
     my $bpp  = ceil($bpc * $comp / 8);
     my $max  = 256;
@@ -281,5 +284,5 @@ sub _predict {
     }
     return $data;
 }
-
+ 
 1;
diff --git a/lib/PDF/Builder/Basic/PDF/Filter/RunLengthDecode.pm b/lib/PDF/Builder/Basic/PDF/Filter/RunLengthDecode.pm
index a4ab760..2e44356 100644
--- a/lib/PDF/Builder/Basic/PDF/Filter/RunLengthDecode.pm
+++ b/lib/PDF/Builder/Basic/PDF/Filter/RunLengthDecode.pm
@@ -5,7 +5,7 @@ use base 'PDF::Builder::Basic::PDF::Filter';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '2.029'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Basic/PDF/Literal.pm b/lib/PDF/Builder/Basic/PDF/Literal.pm
index 299d5f0..0e30ea5 100644
--- a/lib/PDF/Builder/Basic/PDF/Literal.pm
+++ b/lib/PDF/Builder/Basic/PDF/Literal.pm
@@ -6,7 +6,7 @@ use base 'PDF::Builder::Basic::PDF::Objind';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
 
 use PDF::Builder::Basic::PDF::Filter;
diff --git a/lib/PDF/Builder/Basic/PDF/Name.pm b/lib/PDF/Builder/Basic/PDF/Name.pm
index fe1b94b..5402a71 100644
--- a/lib/PDF/Builder/Basic/PDF/Name.pm
+++ b/lib/PDF/Builder/Basic/PDF/Name.pm
@@ -20,8 +20,8 @@ use base 'PDF::Builder::Basic::PDF::String';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 =head1 NAME
 
@@ -30,14 +30,18 @@ and stores PDF names (things beginning with /)
 
 =head1 METHODS
 
-=over
+=head2 from_pdf
+
+    $n = PDF::Builder::Basic::PDF::Name->from_pdf($string)
 
-=item $n = PDF::Builder::Basic::PDF::Name->from_pdf($string)
+=over
 
 Creates a new string object (not a full object yet) from a given
-string.  The string is parsed according to input criteria with
+string. The string is parsed according to input criteria with
 escaping working, particular to Names.
 
+=back
+
 =cut
 
 sub from_pdf {
@@ -49,11 +53,17 @@ sub from_pdf {
     return $self;
 }
 
-=item $n->convert($string, $pdf)
+=head2 convert
+
+    $n->convert($string, $pdf)
+
+=over
 
 Converts a name into a string by removing the / and converting any hex
 munging.
 
+=back
+
 =cut
 
 sub convert {
@@ -63,11 +73,17 @@ sub convert {
     return $string;
 }
 
-=item $s->as_pdf($pdf)
+=head2 as_pdf
+
+    $s->as_pdf($pdf)
+
+=over
 
 Returns a name formatted as PDF. C<$pdf> is optional but should be the
 PDF File object for which the name is intended if supplied.
 
+=back
+
 =cut
 
 sub as_pdf {
@@ -84,11 +100,17 @@ sub as_pdf {
 # spaces were implicitly allowed in names as well but it would be best
 # to ignore that (PDF 1.3, section H.3.2.4.3).
 
-=item PDF::Builder::Basic::PDF::Name->string_to_name($string, $pdf)
+=head2 string_to_name
+
+    PDF::Builder::Basic::PDF::Name->string_to_name($string, $pdf)
+
+=over
 
 Suitably encode the string C<$string> for output in the File object C<$pdf>
 (the exact format may depend on the version of $pdf).
 
+=back
+
 =cut
 
 sub string_to_name {
@@ -102,12 +124,18 @@ sub string_to_name {
     return $string;
 }
 
-=item PDF::Builder::Basic::PDF::Name->name_to_string($string, $pdf)
+=head2 name_to_string
+
+    PDF::Builder::Basic::PDF::Name->name_to_string($string, $pdf)
+
+=over
 
 Suitably decode the string C<$string> as read from the File object C<$pdf>
 (the exact decoding may depend on the version of $pdf).  Principally,
 undo the hex encoding for PDF versions > 1.1.
 
+=back
+
 =cut
 
 sub name_to_string {
@@ -123,8 +151,4 @@ sub name_to_string {
     return $string;
 }
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Basic/PDF/Null.pm b/lib/PDF/Builder/Basic/PDF/Null.pm
index ad2ff08..8a8ad71 100644
--- a/lib/PDF/Builder/Basic/PDF/Null.pm
+++ b/lib/PDF/Builder/Basic/PDF/Null.pm
@@ -20,8 +20,8 @@ use base 'PDF::Builder::Basic::PDF::Objind';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 =head1 NAME
 
@@ -30,37 +30,53 @@ PDF::Builder::Basic::PDF::Objind and cannot be subclassed.
 
 =head1 METHODS
 
-=over
-
 =cut
 
 # There is only one null object  (section 3.2.8).
 my $null_obj = bless {}, 'PDF::Builder::Basic::PDF::Null';
 
-=item PDF::Builder::Basic::PDF::Null->new()
+=head2 new
+
+    PDF::Builder::Basic::PDF::Null->new()
+
+=over
 
 Returns the null object. There is only one null object.
 
+=back
+
 =cut
 
 sub new {
     return $null_obj;
 }
 
-=item $s->realise()
+=head2 realise
+
+    $s->realise()
+
+=over
 
 Pretends to finish reading the object.
 
+=back
+
 =cut
 
 sub realise {
     return $null_obj;
 }
 
-=item $s->outobjdeep()
+=head2 outobjdeep
+
+    $s->outobjdeep()
+
+=over
 
 Output the object in PDF format.
 
+=back
+
 =cut
 
 sub outobjdeep {
@@ -70,38 +86,52 @@ sub outobjdeep {
     return;
 }
 
-=item $s->is_obj()
+=head2 is_obj
+
+    $s->is_obj()
+
+=over
 
 Returns false because null is not a full object.
 
+=back
+
 =cut
 
 sub is_obj {
     return 0;
 }
 
-=item $s->copy()
+=head2 copy
+
+    $s->copy()
+
+=over
 
 Another no-op.
 
+=back
+
 =cut
 
 sub copy {
     return $null_obj;
 }
 
-=item $s->val()
+=head2 val
+
+    $s->val()
+
+=over
 
 Return undef.
 
+=back
+
 =cut
 
 sub val {
     return undef; ## no critic (undef is intentional)
 }
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Basic/PDF/Number.pm b/lib/PDF/Builder/Basic/PDF/Number.pm
index 7cdde2c..3426a7b 100644
--- a/lib/PDF/Builder/Basic/PDF/Number.pm
+++ b/lib/PDF/Builder/Basic/PDF/Number.pm
@@ -20,8 +20,8 @@ use base 'PDF::Builder::Basic::PDF::String';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 =head1 NAME
 
@@ -29,30 +29,36 @@ PDF::Builder::Basic::PDF::Number - Numbers in PDF. Inherits from L<PDF::Builder:
 
 =head1 METHODS
 
-=over
+=head2 convert
+
+    $n->convert($str)
 
-=item $n->convert($str)
+=over
 
 Converts a string from PDF to internal, by doing nothing
 
+=back
+
 =cut
 
 sub convert {
     return $_[1];
 }
 
-=item $n->as_pdf()
+=head2 as_pdf
+
+    $n->as_pdf()
+
+=over
 
 Converts a number to PDF format
 
+=back
+
 =cut
 
 sub as_pdf {
     return $_[0]->{'val'};
 }
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Basic/PDF/Objind.pm b/lib/PDF/Builder/Basic/PDF/Objind.pm
index 5553446..628e37c 100644
--- a/lib/PDF/Builder/Basic/PDF/Objind.pm
+++ b/lib/PDF/Builder/Basic/PDF/Objind.pm
@@ -19,8 +19,8 @@ use strict;
 use warnings;
 use Scalar::Util 'isweak';
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 =head1 NAME
 
@@ -63,8 +63,6 @@ Holds a direct reference to the next free object in the free list.
 
 =head1 METHODS
 
-=over
-
 =cut
 
 use Scalar::Util qw(blessed reftype weaken);
@@ -76,10 +74,16 @@ $uidc = "pdfuid000";
 @inst = qw(parent objnum objgen isfree nextfree uid realised);
 $inst{" $_"} = 1 for @inst;
 
-=item PDF::Builder::Basic::PDF::Objind->new()
+=head2 new
+
+    PDF::Builder::Basic::PDF::Objind->new()
+
+=over
 
 Creates a new indirect object
 
+=back
+
 =cut
 
 sub new {
@@ -88,10 +92,16 @@ sub new {
     return bless {}, ref $class || $class;
 }
 
-=item $UID = $r->uid()
+=head2 uid
+
+    $UID = $r->uid()
+
+=over
 
 Returns a Unique id for this object, creating one if it didn't have one before
 
+=back
+
 =cut
 
 sub uid {
@@ -99,7 +109,11 @@ sub uid {
     return $_[0]->{' uid'};
 }
 
-=item $r->release()
+=head2 release
+
+    $r->release()
+
+=over
 
 Releases ALL of the memory used by this indirect object, and all of
 its component/child objects.  This method is called automatically by
@@ -113,6 +127,8 @@ references within our own internal data structures.  Calling
 'C<release()>' forces these circular references to be cleaned up and
 the entire internal data structure purged.
 
+=back
+
 =cut
 
 # Maintainer's Question: Couldn't this be handled by a DESTROY method
@@ -143,7 +159,11 @@ sub release {
     return;
 }
 
-=item $value = $r->val()
+=head2 val
+
+    $value = $r->val()
+
+=over
 
 Returns the value of this object or reads the object and then returns
 its value.
@@ -151,6 +171,8 @@ its value.
 Note that all direct subclasses *must* make their own versions of this
 subroutine otherwise we could be in for a very deep loop!
 
+=back
+
 =cut
 
 sub val {
@@ -170,10 +192,16 @@ sub val {
     }
 }
 
-=item $r->realise()
+=head2 realise
+
+    $r->realise()
+
+=over
 
 Makes sure that the object is fully read in, etc.
 
+=back
+
 =cut
 
 sub realise {
@@ -184,12 +212,18 @@ sub realise {
     return $self;
 }
 
-=item $v = $r->outobjdeep($fh, $pdf)
+=head2 outobjdeep
+
+    $v = $r->outobjdeep($fh, $pdf)
+
+=over
 
 If you really want to output this object, then you need to read it first.
 This also means that all direct subclasses must subclass this method, or they 
 will loop forever!
 
+=back
+
 =cut
 
 sub outobjdeep {
@@ -209,11 +243,17 @@ sub outobjdeep {
     }
 }
 
-=item $r->outobj($fh, $pdf)
+=head2 outobj
+
+    $r->outobj($fh, $pdf)
+
+=over
 
 If this is a full object then outputs a reference to the object, otherwise calls
 outobjdeep to output the contents of the object at this point.
 
+=back
+
 =cut
 
 sub outobj {
@@ -227,18 +267,19 @@ sub outobj {
     return;
 }
 
-=item $s = $r->elements()
+=head2 elements
+
+    $s = $r->elements()
+
+=over
 
 Abstract superclass function filler. Returns self here but should return
 something more useful if an array.
 
-The old name of this method, C<elementsof>, has been B<deprecated> and will
-be removed in the future.
+=back
 
 =cut
 
-sub elementsof { return elements(@_); }
-
 sub elements {
     my ($self) = @_;
 
@@ -249,12 +290,18 @@ sub elements {
     }
 }
 
-=item $s = $r->empty()
+=head2 empty
+
+    $s = $r->empty()
+
+=over
 
 Empties all content from this object to free up memory or to be read to pass
 the object into the free list. Simplistically undefs all instance variables
 other than object number and generation.
 
+=back
+
 =cut
 
 sub empty {
@@ -267,13 +314,19 @@ sub empty {
     return $self;
 }
 
-=item $o = $r->merge($objind)
+=head2 merge
+
+    $o = $r->merge($objind)
+
+=over
 
 This merges content information into an object reference placeholder.
 This occurs when an object reference is read before the object definition
 and the information in the read data needs to be merged into the object
 placeholder.
 
+=back
+
 =cut
 
 sub merge {
@@ -291,19 +344,29 @@ sub merge {
     return bless $self, ref($other);
 }
 
-=item $r->is_obj($pdf)
+=head2 is_obj
+
+    $r->is_obj($pdf)
+
+=over
 
 Returns whether this object is a full object with its own object number or
 whether it is purely a sub-object. C<$pdf> indicates which output file we are
 concerned that the object is an object in.
 
+=back
+
 =cut
 
 sub is_obj {
     return defined $_[1]->{' objects'}{$_[0]->uid()};
 }
 
-=item $r->copy($pdf, $res)
+=head2 copy
+
+    $r->copy($pdf, $res)
+
+=over
 
 Returns a new copy of this object. The object is assumed to be some kind
 of associative array and the copy is a deep copy for elements which are
@@ -317,6 +380,8 @@ new one. It is up to the caller to bless C<$res>, etc. Notice that elements from
 C<$self> are not copied into C<$res> if there is already an entry for them 
 existing in C<$res>.
 
+=back
+
 =cut
 
 sub copy {
@@ -338,8 +403,4 @@ sub copy {
     return $res;
 }
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Basic/PDF/Page.pm b/lib/PDF/Builder/Basic/PDF/Page.pm
index 2f66457..0824e4e 100644
--- a/lib/PDF/Builder/Basic/PDF/Page.pm
+++ b/lib/PDF/Builder/Basic/PDF/Page.pm
@@ -20,8 +20,8 @@ use base 'PDF::Builder::Basic::PDF::Pages';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.022'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use PDF::Builder::Basic::PDF::Dict;
 use PDF::Builder::Basic::PDF::Utils;
@@ -52,9 +52,11 @@ The currently open stream
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    PDF::Builder::Basic::PDF::Page->new($pdf, $parent, $index)
 
-=item PDF::Builder::Basic::PDF::Page->new($pdf, $parent, $index)
+=over
 
 Creates a new page based on a pages object (perhaps the root object).
 
@@ -68,6 +70,8 @@ are either optional or can be inherited.
 The optional index value indicates the index in the parent list that this page
 should be inserted (so that new pages need not be appended)
 
+=back
+
 =cut
 
 sub new {
@@ -87,7 +91,11 @@ sub new {
 # the add() method was deleted from PDF::API2 2.034, but it looks like it
 # still may be used in Builder.pm! apparently calls Content.pm's add().
 
-#=item $p->add($str)
+#=head2 add
+#
+#    $p->add($str)
+#
+#=over
 #
 #Adds the string to the currently active stream for this page. If no stream
 #exists, then one is created and added to the list of streams for this page.
@@ -95,6 +103,8 @@ sub new {
 #The slightly cryptic name is an aim to keep it short given the number of times
 #people are likely to have to type it.
 #
+#=back
+#
 #=cut
 #
 #sub add {
@@ -120,10 +130,16 @@ sub new {
 #    return $self;
 #}
 
-=item $p->ship_out($pdf)
+=head2 ship_out
+
+    $p->ship_out($pdf)
+
+=over
 
 Ships the page out to the given output file context
 
+=back
+
 =cut
 
 sub ship_out {
@@ -137,8 +153,4 @@ sub ship_out {
     return $self;
 }
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Basic/PDF/Pages.pm b/lib/PDF/Builder/Basic/PDF/Pages.pm
index 569304d..707c8f0 100644
--- a/lib/PDF/Builder/Basic/PDF/Pages.pm
+++ b/lib/PDF/Builder/Basic/PDF/Pages.pm
@@ -20,8 +20,8 @@ use warnings;
 
 use base 'PDF::Builder::Basic::PDF::Dict';
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use PDF::Builder::Basic::PDF::Array;
 use PDF::Builder::Basic::PDF::Dict;
@@ -43,9 +43,11 @@ themselves.
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    PDF::Builder::Basic::PDF::Pages->new($pdf, $parent)
 
-=item PDF::Builder::Basic::PDF::Pages->new($pdf, $parent)
+=over
 
 This creates a new Pages object in a PDF. Notice that the C<$parent> here is 
 not the file context for the object, but the parent pages object for these 
@@ -55,6 +57,8 @@ I<Pages>. C<$pdf> is the file object (or a reference to an array of I<one>
 file object [3.016 and later, or multiple file objects earlier]) in which to 
 create the new Pages object.
 
+=back
+
 =cut
 
 sub new {
@@ -96,7 +100,11 @@ sub new {
 #    return $self;
 #}
 
-#=item $p->out_obj($is_new)
+#=head2 out_obj
+#
+#    $p->out_obj($is_new)
+#
+#=over
 #
 #Tells all the files that this thing is destined for that they should output this
 #object, come time to output. If this object has no parent, then it must be the
@@ -104,6 +112,8 @@ sub new {
 #If C<$is_new> is set, then call C<new_obj> rather than C<out_obj> to create as 
 #a new object in the file.
 #
+#=back
+#
 #=cut
 #
 #sub out_obj {
@@ -130,11 +140,17 @@ sub _pdf {
     return $self->get_top()->{' parent'};
 }
 
-=item $p->find_page($page_number)
+=head2 find_page
+
+    $p->find_page($page_number)
+
+=over
 
 Returns the given page, using the page count values in the pages tree. Pages
 start at 0.
 
+=back
+
 =cut
 
 sub find_page {
@@ -165,7 +181,11 @@ sub find_page_recursively {
     return;
 }
 
-=item $p->add_page($page, $page_number)
+=head2 add_page
+
+    $p->add_page($page, $page_number)
+
+=over
 
 Inserts the page before the given C<$page_number>. C<$page_number> can be 
 negative to count backwards from the END of the document. -1 is after the last 
@@ -178,6 +198,8 @@ document may simply be inserted in the appropriate leaf in the pages tree
 without adding any new branches or leaves, leaving it unbalanced (slower
 performance, but still usable). 
 
+=back
+
 =cut
 
 # -- removed from end of second para:
@@ -237,10 +259,10 @@ sub add_page_recursively {
     my ($self, $page, $page_index) = @_;
 
     my $parent = $self;
-    my $max_kids_per_parent = 8; # Why 8?
+    my $max_kids_per_parent = 8; # Why 8? effort to somewhat balance tree?
     if (scalar $parent->{'Kids'}->elements() >= $max_kids_per_parent and 
         $parent->{'Parent'} and 
-        $page_index < 1) {
+        $page_index < 0) {
         my $grandparent = $parent->{'Parent'}->realise();
         $parent = $parent->new($parent->_pdf(), $grandparent);
 
@@ -275,7 +297,11 @@ sub set_modified {
     return;
 }
 
-#=item $root_pages = $p->rebuild_tree([@pglist])
+#=head2 rebuild_tree
+#
+#    $root_pages = $p->rebuild_tree([@pglist])
+#
+#=over
 #
 #B<WARNING: Not yet implemented. Do not attempt to use!>
 #
@@ -285,6 +311,8 @@ sub set_modified {
 #
 #Returns the top of the tree for insertion in the root object.
 #
+#=back
+#
 #=cut
 
 # TBD where's the code?
@@ -293,10 +321,16 @@ sub set_modified {
 #    return;
 #}
 
-=item @objects = $p->get_pages()
+=head2 get_pages
+
+    @objects = $p->get_pages()
+
+=over
 
 Returns a list of page objects in the document, in page order.
 
+=back
+
 =cut
 
 sub get_pages {
@@ -325,10 +359,16 @@ sub get_pages_recursively {
     return @pages;
 }
 
-=item $p->find_prop($key)
+=head2 find_prop
+
+    $p->find_prop($key)
+
+=over
 
 Searches up through the inheritance tree to find a property (key).
 
+=back
+
 =cut
 
 sub find_prop {
@@ -354,7 +394,11 @@ sub find_prop {
     return;
 }
 
-=item $p->add_font($pdf, $font)
+=head2 add_font
+
+    $p->add_font($pdf, $font)
+
+=over
 
 Creates or edits the resource dictionary at this level in the hierarchy. If
 the font is already supported, even through the hierarchy, then it is not added.
@@ -364,6 +408,8 @@ swapped the order of C<$pdf> and C<$font>, requiring ad hoc swapping of
 parameters in user code, contrary to the POD definition above. Now the code
 matches the documentation.
 
+=back
+
 =cut
 
 sub add_font {
@@ -395,14 +441,20 @@ sub add_font {
     return $self;
 } # end of add_font()
 
-=item $p->bbox($xmin,$ymin, $xmax,$ymax, $param)
+=head2 bbox
+
+    $p->bbox($xmin,$ymin, $xmax,$ymax, $param)
 
-=item $p->bbox($xmin,$ymin, $xmax,$ymax)
+    $p->bbox($xmin,$ymin, $xmax,$ymax)
+
+=over
 
 Specifies the bounding box for this and all child pages. If the values are
 identical to those inherited, no change is made. C<$param> specifies the 
 attribute name so that other 'bounding box'es can be set with this method.
 
+=back
+
 =cut
 
 sub bbox {
@@ -428,11 +480,17 @@ sub bbox {
     return $self;
 }
 
-=item $p->proc_set(@entries)
+=head2 proc_set
+
+    $p->proc_set(@entries)
+
+=over
 
 Ensures that the current resource contains all the entries in the proc_sets
 listed. If necessary, it creates a local resource dictionary to achieve this.
 
+=back
+
 =cut
 
 sub proc_set {
@@ -474,10 +532,16 @@ sub empty {
     return $self;
 }
 
-=item $p->get_top()
+=head2 get_top
+
+    $p->get_top()
+
+=over
 
 Returns the top of the pages tree.
 
+=back
+
 =cut
 
 sub get_top {
@@ -489,8 +553,4 @@ sub get_top {
     return $top->realise();
 }
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Basic/PDF/String.pm b/lib/PDF/Builder/Basic/PDF/String.pm
index 526a85b..3371103 100644
--- a/lib/PDF/Builder/Basic/PDF/String.pm
+++ b/lib/PDF/Builder/Basic/PDF/String.pm
@@ -20,8 +20,8 @@ use base 'PDF::Builder::Basic::PDF::Objind';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 =head1 NAME
 
@@ -30,8 +30,6 @@ for simple objects that are basically stringlike (Number, Name, etc.)
 
 =head1 METHODS
 
-=over
-
 =cut
 
 our %trans = (
@@ -56,12 +54,18 @@ our %out_trans = (
     ')' => ')',
 );
 
-=item PDF::Builder::Basic::PDF::String->from_pdf($string)
+=head2 from_pdf
+
+    PDF::Builder::Basic::PDF::String->from_pdf($string)
+
+=over
 
 Creates a new string object (not a full object yet) from a given
 string.  The string is parsed according to input criteria with
 escaping working.
 
+=back
+
 =cut
 
 sub from_pdf {
@@ -74,12 +78,18 @@ sub from_pdf {
     return $self;
 }
 
-=item PDF::Builder::Basic::PDF::String->new($string)
+=head2 new
+
+    PDF::Builder::Basic::PDF::String->new($string)
+
+=over
 
 Creates a new string object (not a full object yet) from a given
 string. The string is parsed according to input criteria with
 escaping working.
 
+=back
+
 =cut
 
 sub new {
@@ -92,10 +102,16 @@ sub new {
     return $self;
 }
 
-=item $s->convert($str)
+=head2 convert
+
+    $s->convert($str)
+
+=over
 
 Returns $str converted as per criteria for input from PDF file
 
+=back
+
 =cut
 
 sub convert {
@@ -171,20 +187,32 @@ sub convert {
     return $output;
 }
 
-=item $s->val()
+=head2 val
+
+    $s->val()
+
+=over
 
 Returns the value of this string (the string itself).
 
+=back
+
 =cut
 
 sub val {
     return $_[0]->{'val'};
 }
 
-=item $s->as_pdf()
+=head2 as_pdf
+
+    $s->as_pdf()
+
+=over
 
 Returns the string formatted for output as PDF for PDF File object $pdf.
 
+=back
+
 =cut
 
 sub as_pdf {
@@ -210,10 +238,16 @@ sub as_pdf {
     }
 }
 
-=item $s->outobjdeep($fh, $pdf)
+=head2 outobjdeep
+
+    $s->outobjdeep($fh, $pdf)
+
+=over
 
 Outputs the string in PDF format, complete with necessary conversions.
 
+=back
+
 =cut
 
 sub outobjdeep {
@@ -223,8 +257,4 @@ sub outobjdeep {
     return;
 }
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Basic/PDF/Utils.pm b/lib/PDF/Builder/Basic/PDF/Utils.pm
index a008c9e..8b3f7ed 100644
--- a/lib/PDF/Builder/Basic/PDF/Utils.pm
+++ b/lib/PDF/Builder/Basic/PDF/Utils.pm
@@ -18,8 +18,8 @@ package PDF::Builder::Basic::PDF::Utils;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 =head1 NAME
 
@@ -29,9 +29,7 @@ PDF::Builder::Basic::PDF::Utils - Utility functions for PDF library
 
 A set of utility functions to save the fingers of the PDF library users!
 
-=head1 FUNCTIONS
-
-=over
+=head1 METHODS
 
 =cut
 
@@ -50,67 +48,107 @@ use vars qw(@EXPORT @ISA);
 @EXPORT = qw(PDFBool PDFArray PDFDict PDFName PDFNull
              PDFNum PDFString PDFStr PDFStrHex PDFUtf);
 
-=item PDFBool()
+=head2 PDFBool
+
+    PDFBool()
+
+=over
 
 Creates a Bool via PDF::Builder::Basic::PDF::Bool->new()
 
+=back
+
 =cut
 
 sub PDFBool {
     return PDF::Builder::Basic::PDF::Bool->new(@_);
 }
 
-=item PDFArray()
+=head2 PDFArray
+
+    PDFArray()
+
+=over
 
 Creates an array via PDF::Builder::Basic::PDF::Array->new()
 
+=back
+
 =cut
 
 sub PDFArray {
     return PDF::Builder::Basic::PDF::Array->new(@_);
 }
 
-=item PDFDict()
+=head2 PDFDict
+
+    PDFDict()
+
+=over
 
 Creates a dict via PDF::Builder::Basic::PDF::Dict->new()
 
+=back
+
 =cut
 
 sub PDFDict {
     return PDF::Builder::Basic::PDF::Dict->new(@_);
 }
 
-=item PDFName()
+=head2 PDFName
+
+    PDFName()
+
+=over
 
 Creates a name via PDF::Builder::Basic::PDF::Name->new()
 
+=back
+
 =cut
 
 sub PDFName {
     return PDF::Builder::Basic::PDF::Name->new(@_);
 }
 
-=item PDFNull()
+=head2 PDFNull
+
+    PDFNull()
+
+=over
 
 Creates a null via PDF::Builder::Basic::PDF::Null->new()
 
+=back
+
 =cut
 
 sub PDFNull {
     return PDF::Builder::Basic::PDF::Null->new(@_);
 }
 
-=item PDFNum()
+=head2 PDFNum
+
+    PDFNum()
+
+=over
 
 Creates a number via PDF::Builder::Basic::PDF::Number->new()
 
+=back
+
 =cut
 
 sub PDFNum {
     return PDF::Builder::Basic::PDF::Number->new(@_);
 }
 
-=item PDFString($text, $usage)
+=head2 PDFString
+
+    PDFString($text, $usage)
+
+=over
 
 Returns either PDFStr($text) or PDFUtf($text), depending on whether C<$text>
 is already in UTF-8 and whether the C<$usage> permits UTF-8. If UTF-8 is I<not>
@@ -155,6 +193,8 @@ Any other usage where UTF-8 text is B<not> permitted.
 
 =back
 
+=back
+
 =cut
 
 sub PDFString {
@@ -184,22 +224,34 @@ sub PDFString {
     }
 }
 
-=item PDFStr()
+=head2 PDFStr
+
+    PDFStr()
+
+=over
 
 Creates a string via PDF::Builder::Basic::PDF::String->new()
 
 B<DEPRECATED.> It is preferable that you use C<PDFString> instead.
 
+=back
+
 =cut
 
 sub PDFStr {
     return PDF::Builder::Basic::PDF::String->new(@_);
 }
 
-=item PDFStrHex()
+=head2 PDFStrHex
+
+    PDFStrHex()
+
+=over
 
 Creates a hex-string via PDF::Builder::Basic::PDF::String->new()
 
+=back
+
 =cut
 
 sub PDFStrHex {
@@ -208,12 +260,18 @@ sub PDFStrHex {
     return $string;
 }
 
-=item PDFUtf()
+=head2 PDFUtf
+
+    PDFUtf()
+
+=over
 
 Creates a utf8-string via PDF::Builder::Basic::PDF::String->new()
 
 B<DEPRECATED.> It is preferable that you use C<PDFString> instead.
 
+=back
+
 =cut
 
 sub PDFUtf {
@@ -222,8 +280,4 @@ sub PDFUtf {
     return $string;
 }
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Content.pm b/lib/PDF/Builder/Content.pm
index e1f7621..1e36edb 100644
--- a/lib/PDF/Builder/Content.pm
+++ b/lib/PDF/Builder/Content.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Basic::PDF::Dict';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use Carp;
 use Compress::Zlib qw();
@@ -132,13 +132,17 @@ translate, rotate, scale, and skew calls I<cancel out> any previous settings.
 If you want to combine multiple transformations for text, use the C<transform>
 call.
 
-=over
+=head3 translate
+
+    $content->translate($dx,$dy)
 
-=item $content->translate($dx,$dy)
+=over
 
-Moves the origin along the x and y axes by 
+Moves the origin along the x and y axes to 
 C<$dx> and C<$dy> respectively.
 
+=back
+
 =cut
 
 sub _translate {
@@ -156,7 +160,11 @@ sub translate {
     return $self;
 }
 
-=item $content->rotate($degrees)
+=head3 rotate
+
+    $content->rotate($degrees)
+
+=over
 
 Rotates the coordinate system counter-clockwise (anti-clockwise) around the
 current origin. Use a negative argument to rotate clockwise. Note that 360 
@@ -172,6 +180,8 @@ This C<rotate()> call permits any angle. Do not confuse it with the I<page>
 rotation C<rotate> call, which only permits increments of 90 degrees (with
 opposite sign!), but I<does> shift the origin to another corner of the sheet.
 
+=back
+
 =cut
 
 sub _rotate {
@@ -189,11 +199,17 @@ sub rotate {
     return $self;
 }
 
-=item $content->scale($sx,$sy)
+=head3 scale
+
+    $content->scale($sx,$sy)
+
+=over
 
 Scales (stretches) the coordinate systems along the x and y axes.
 Separate multipliers are provided for x and y.
 
+=back
+
 =cut
 
 sub _scale {
@@ -211,13 +227,19 @@ sub scale {
     return $self;
 }
 
-=item $content->skew($skx,$sky)
+=head3 skew
+
+    $content->skew($skx,$sky)
+
+=over
 
 Skews the coordinate system by C<$skx> degrees 
 (counter-clockwise/anti-clockwise) from
 the x axis I<and> C<$sky> degrees (clockwise) from the y axis.
 Note that 360 degrees will be treated the same as 0 degrees.
 
+=back
+
 =cut
 
 sub _skew {
@@ -235,7 +257,11 @@ sub skew {
     return $self;
 }
 
-=item $content->transform(%opts)
+=head3 transform
+
+    $content->transform(%opts)
+
+=over
 
 Use one or more of the given %opts:
 
@@ -273,6 +299,8 @@ If C<repeat> is true, and if this is not the first call to a transformation
 method, the previous transformation will be performed again, modified by any
 other provided arguments.
 
+=back
+
 =cut
 
 sub _transform {
@@ -380,7 +408,11 @@ sub transform {
     return $self;
 }
 
-=item $content->transform_rel(%opts)
+=head3 transform_rel
+
+    $content->transform_rel(%opts)
+
+=over
 
 Makes transformations similarly to C<transform>, except that it I<adds>
 to the previously set values, rather than I<replacing> them (except for 
@@ -388,6 +420,8 @@ I<scale>, which B<multiplies> the new values with the old).
 
 Unlike C<transform>, C<matrix> and C<point> are not supported.
 
+=back
+
 =cut
 
 sub transform_rel {
@@ -420,22 +454,28 @@ sub transform_rel {
     return $self;
 }
 
-=item $content->matrix($a, $b, $c, $d, $e, $f)
+=head3 matrix
+
+    $content->matrix($a, $b, $c, $d, $e, $f)
+
+=over
 
 I<(Advanced)> Sets the current transformation matrix manually. Unless
 you have a particular need to enter transformations manually, you
 should use the C<transform> method instead.
 
- $a = cos(rot) * scale factor for X 
- $b = sin(rot) * tan(skew for X)
- $c = -sin(rot) * tan(skew for Y)
- $d = cos(rot) * scale factor for Y 
- $e = translation for X
- $f = translation for Y
+    $a = cos(rot) * scale factor for X 
+    $b = sin(rot) * tan(skew for X)
+    $c = -sin(rot) * tan(skew for Y)
+    $d = cos(rot) * scale factor for Y 
+    $e = translation for X
+    $f = translation for Y
 
 In text mode, the text matrix is B<returned>. 
 In graphics mode, C<$self> is B<returned>.
 
+=back
+
 =cut
 
 sub _matrix_text {
@@ -478,15 +518,15 @@ sub matrix {
     }
 }
 
-=back
-
 =head2 Graphics State Parameters
 
 The following calls also affect the B<text> state.
 
-=over
+=head3 linewidth, line_width
 
-=item $content->linewidth($width)
+    $content->linewidth($width)
+
+=over
 
 Sets the width of the stroke (in points). This is the line drawn in graphics 
 mode, or the I<outline> of a character in text mode (with appropriate C<render> 
@@ -497,6 +537,8 @@ B<Alternate name:> C<line_width>
 
 This is provided for compatibility with PDF::API2.
 
+=back
+
 =cut
 
 sub _linewidth {
@@ -519,7 +561,11 @@ sub linewidth {
     return $self;
 }
 
-=item $content->linecap($style)
+=head3 linecap, line_cap
+
+    $content->linecap($style)
+
+=over
 
 Sets the style to be used at the end of a stroke. This applies to lines
 which come to a free-floating end, I<not> to "joins" ("corners") in 
@@ -551,6 +597,8 @@ being set, C<$self> is B<returned> so that calls may be chained.
 
 Either a number or a string (case-insensitive) may be given.
 
+=back
+
 =cut
 
 sub _linecap {
@@ -584,7 +632,11 @@ sub linecap {
     return $self;
 }
 
-=item $content->linejoin($style)
+=head3 linejoin, line_join
+
+    $content->linejoin($style)
+
+=over
 
 Sets the style of join to be used at corners of a path
 (within a multisegment polyline).
@@ -621,6 +673,8 @@ being set, C<$self> is B<returned> so that calls may be chained.
 
 Either a number or a string (case-insensitive) may be given.
 
+=back
+
 =cut
 
 sub _linejoin {
@@ -654,7 +708,11 @@ sub linejoin {
     return $self;
 }
 
-=item $content->miterlimit($ratio)
+=head3 miterlimit, miter_limit
+
+    $content->miterlimit($ratio)
+
+=over
 
 Sets the miter limit when the line join style is a I<miter> join.
 
@@ -675,6 +733,8 @@ This is provided for compatibility with PDF::API2.
 Long ago, in a distant galaxy, this method was misnamed I<meterlimit>, but
 that was removed a while ago. Any code using that name should be updated!
 
+=back
+
 =cut
 
 sub _miterlimit {
@@ -700,13 +760,17 @@ sub miterlimit {
 # Note: miterlimit was originally named incorrectly to meterlimit, renamed.
 # is available in PDF::API2
 
-=item $content->linedash()
+=head3 linedash, line_dash_pattern
+
+    $content->linedash()
 
-=item $content->linedash($length)
+    $content->linedash($length)
 
-=item $content->linedash($dash_length, $gap_length, ...)
+    $content->linedash($dash_length, $gap_length, ...)
 
-=item $content->linedash('pattern' => [$dash_length, $gap_length, ...], 'shift' => $offset)
+    $content->linedash('pattern' => [$dash_length, $gap_length, ...], 'shift' => $offset)
+
+=over
 
 Sets the line dash pattern.
 
@@ -731,6 +795,9 @@ the reader software to form an even number of elements (pairs).
 If a single argument of B<-1> is given, the current setting is B<returned>. 
 This is an array consisting of two elements: an anonymous array containing the 
 dash pattern (default: empty), and the shift (offset) amount (default: 0). 
+It may be used directly in a linedash() call, as linedash will recognize the 
+special pattern [ array, number ].
+
 If the dash pattern is being I<set>, C<$self> is B<returned> so that calls may 
 be chained.
 
@@ -738,6 +805,8 @@ B<Alternate name:> C<line_dash_pattern>
 
 This is provided for compatibility with PDF::API2.
 
+=back
+
 =cut
 
 sub _linedash {
@@ -769,15 +838,31 @@ sub line_dash_pattern { return linedash(@_); } ## no critic
 sub linedash {
     my ($self, @pat) = @_;
 
+    # request existing pattern and offset?
     if (scalar @pat == 1 && $pat[0] == -1) {
 	return @{$self->{' linedash'}};
     }
+    # request to restore stored pattern and offset?
+    if (scalar @pat == 2 && ref($pat[0]) eq 'ARRAY' && ref($pat[1]) eq '') {
+        @{$self->{' linedash'}} = @pat;
+	if (@{$pat[0]}) {
+	    # not an empty array
+	    return ('[', floats(@{$pat[0]}), '] ', $pat[1], ' d');
+	} else {
+	    return ('[ ] 0 d');
+	}
+    }
+    # anything else, including empty pattern
     $self->add($self->_linedash(@pat));
 
     return $self;
 }
 
-=item $content->flatness($tolerance)
+=head3 flatness, flatness_tolerance
+
+    $content->flatness($tolerance)
+
+=over
 
 I<(Advanced)> Sets the maximum variation in output pixels when drawing
 curves. The defined range of C<$tolerance> is 0 to 100, with 0 meaning I<use 
@@ -795,6 +880,8 @@ B<Alternate name:> C<flatness_tolerance>
 
 This is provided for compatibility with PDF::API2.
 
+=back
+
 =cut
 
 sub _flatness {
@@ -819,11 +906,17 @@ sub flatness {
     return $self;
 }
 
-=item $content->egstate($object)
+=head3 egstate
+
+    $content->egstate($object)
+
+=over
 
 I<(Advanced)> Adds an Extended Graphic State B<object> containing additional
 state parameters.
 
+=back
+
 =cut
 
 sub egstate {
@@ -835,18 +928,20 @@ sub egstate {
     return $self;
 }
 
-=back
-
 =head2 Path Construction (Drawing)
 
-=over
+=head3 move
+
+    $content->move($x,$y)
 
-=item $content->move($x,$y)
+=over
 
 Starts a new path at the specified coordinates.
 Note that multiple x,y pairs I<can> be given, although this isn't that useful
 (only the last pair would have an effect).
 
+=back
+
 =cut
 
 sub _move {
@@ -879,11 +974,17 @@ sub move {
     return $self;
 }
 
-=item $content->close()
+=head3 close
+
+    $content->close()
+
+=over
 
 Closes and ends the current path by extending a line from the current
 position to the starting position.
 
+=back
+
 =cut
 
 sub close {
@@ -896,7 +997,11 @@ sub close {
     return $self;
 }
 
-=item $content->endpath()
+=head3 endpath, end
+
+    $content->endpath()
+
+=over
 
 Ends the current path without explicitly enclosing it.
 That is, unlike C<close>, there is B<no> line segment 
@@ -907,6 +1012,8 @@ B<Alternate name:> C<end>
 This is provided for compatibility with PDF::API2. Do not confuse it with
 the C<$pdf-E<gt>end()> method!
 
+=back
+
 =cut
 
 sub end { return endpath(@_); } ## no critic
@@ -919,18 +1026,18 @@ sub endpath {
     return $self;
 }
 
-=back
-
 =head3 Straight line constructs
 
-B<Note:> None of these will actually be I<visible> until you call C<stroke> or 
-C<fill>. They are merely setting up the path to draw.
+B<Note:> None of these will actually be I<visible> until you call C<stroke>, 
+C<fill>, or C<fillstroke>. They are merely setting up the path to draw.
 
-=over
+=head4 line
+
+    $content->line($x,$y)
 
-=item $content->line($x,$y)
+    $content->line($x,$y, $x2,$y2,...)
 
-=item $content->line($x,$y, $x2,$y2,...)
+=over
 
 Extends the path in a line from the I<current> coordinates to the
 specified coordinates, and updates the current position to be the new
@@ -942,6 +1049,8 @@ because the first C<[$x,$y]> pair in a polyline is a I<move> operation.
 Also, the C<linecap> setting will be used rather than the C<linejoin>
 setting for treating the ends of segments.
 
+=back
+
 =cut
 
 sub _line {
@@ -972,14 +1081,20 @@ sub line {
     return $self;
 }
 
-=item $content->hline($x)
+=head4 hline, vline
 
-=item $content->vline($y)
+    $content->hline($x)
+
+    $content->vline($y)
+
+=over
 
 Shortcuts for drawing horizontal and vertical lines from the current
 position. They are like C<line()>, but to the new x and current y (C<hline>),
 or to the the current x and new y (C<vline>).
 
+=back
+
 =cut
 
 sub hline {
@@ -1010,7 +1125,11 @@ sub vline {
     return $self;
 }
 
-=item $content->polyline($x1,$y1, ..., $xn,$yn)
+=head4 polyline
+
+    $content->polyline($x1,$y1, ..., $xn,$yn)
+
+=over
 
 This is a shortcut for creating a polyline path from the current position. It 
 extends the path in line segments along the specified coordinates.
@@ -1023,6 +1142,8 @@ I<draw> order (unlike the I<move> order in C<poly>).
 Thus, while this is provided for compatibility with PDF::API2, it is I<not>
 really an alias or alternate name for C<poly>!
 
+=back
+
 =cut
 
 # TBD document line_join vs line_cap? (see poly()). perhaps demo in Content.pl?
@@ -1041,7 +1162,11 @@ sub polyline {
     return $self;
 }
 
-=item $content->poly($x1,$y1, ..., $xn,$yn)
+=head4 poly
+
+    $content->poly($x1,$y1, ..., $xn,$yn)
+
+=over
 
 This is a shortcut for creating a polyline path. It moves to C<[$x1,$y1]>, and
 then extends the path in line segments along the specified coordinates.
@@ -1057,6 +1182,8 @@ A critical distinction between the C<polyline> method and the C<poly> method
 is that in this (C<poly>), the first pair of coordinates are treated as a
 I<move> order.
 
+=back
+
 =cut
 
 sub poly {
@@ -1071,7 +1198,11 @@ sub poly {
     return $self;
 }
 
-=item $content = $content->rectangle($x1, $y1, $x2, $y2)
+=head4 rectangle
+
+    $content = $content->rectangle($x1, $y1, $x2, $y2)
+
+=over
 
 Creates a new rectangle-shaped path, between the two corner points C<[$x1, $y1]>
 and C<[$x2, $y2]>. The corner points are swapped if necessary, to make
@@ -1082,6 +1213,8 @@ B<Note> that this is I<not> an alias or alternate name for C<rect>. It handles
 only one rectangle, and takes corner coordinates for corner "2", rather than
 the width and height.
 
+=back
+
 =cut
 
 sub rectangle {
@@ -1107,9 +1240,13 @@ sub rectangle {
     return $self;
 }
 
-=item $content = $content->rect($x,$y, $w,$h)
+=head4 rect
+
+    $content = $content->rect($x,$y, $w,$h)
 
-=item $content = $content->rect($x1,$y1, $w1,$h1, ..., $xn,$yn, $wn,$hn)
+    $content = $content->rect($x1,$y1, $w1,$h1, ..., $xn,$yn, $wn,$hn)
+
+=over
 
 This creates paths for one or more rectangles, with their lower left points
 at C<[$x,$y]> and specified widths (+x direction) and heights (+y direction). 
@@ -1123,6 +1260,8 @@ B<Note> that this differs from the C<rectangle> method in that multiple
 rectangles may be drawn in one call, and the second pair for each rectangle
 are the width and height, not the opposite corner coordinates. 
 
+=back
+
 =cut
 
 sub rect {
@@ -1145,7 +1284,11 @@ sub rect {
     return $self;
 }
 
-=item $content->rectxy($x1,$y1, $x2,$y2)
+=head4 rectxy
+
+    $content->rectxy($x1,$y1, $x2,$y2)
+
+=over
 
 This creates a rectangular path, with C<[$x1,$y1]> and C<[$x2,$y2]>
 specifying I<opposite> corners. They can be Lower Left and Upper Right,
@@ -1156,6 +1299,8 @@ The current position is changed to the C<[$x1,$y1]> (first) pair.
 This is not I<quite> an alias or alternate name for C<rectangle>, as it 
 permits the corner points to be specified in any order.
 
+=back
+
 =cut
 
 # TBD allow multiple rectangles, as in rect()
@@ -1168,20 +1313,22 @@ sub rectxy {
     return $self;
 }
 
-=back
-
 =head3 Curved line constructs
 
-B<Note:> None of these will actually be I<visible> until you call C<stroke> or 
-C<fill>. They are merely setting up the path to draw.
+B<Note:> None of these will actually be I<visible> until you call C<stroke>,
+C<fill>, or C<fillstroke>. They are merely setting up the path to draw.
 
-=over
+=head4 circle
 
-=item $content->circle($xc,$yc, $radius)
+    $content->circle($xc,$yc, $radius)
+
+=over
 
 This creates a circular path centered on C<[$xc,$yc]> with the specified
 radius. It does B<not> change the current position.
 
+=back
+
 =cut
 
 sub circle {
@@ -1193,12 +1340,18 @@ sub circle {
     return $self;
 }
 
-=item $content->ellipse($xc,$yc, $rx,$ry)
+=head4 ellipse
+
+    $content->ellipse($xc,$yc, $rx,$ry)
+
+=over
 
 This creates a closed elliptical path centered on C<[$xc,$yc]>, with axis radii
 (semidiameters) specified by C<$rx> (x axis) and C<$ry> (y axis), respectively.
 It does not change the current position.
 
+=back
+
 =cut
 
 sub ellipse {
@@ -1302,9 +1455,13 @@ sub _arctocurve {
     }
 }
 
-=item $content->arc($xc,$yc, $rx,$ry, $alpha,$beta, $move, $dir)
+=head4 arc
 
-=item $content->arc($xc,$yc, $rx,$ry, $alpha,$beta, $move)
+    $content->arc($xc,$yc, $rx,$ry, $alpha,$beta, $move, $dir)
+
+    $content->arc($xc,$yc, $rx,$ry, $alpha,$beta, $move)
+
+=over
 
 This extends the path along an arc of an ellipse centered at C<[$xc,$yc]>.
 The semidiameters of the elliptical curve are C<$rx> (x axis) and C<$ry> 
@@ -1320,6 +1477,8 @@ The optional C<$dir> arc sweep direction defaults to 0 (I<false>), for a
 counter-clockwise/anti-clockwise sweep. Set to 1 (I<true>) for a clockwise
 sweep.
 
+=back
+
 =cut
 
 sub arc {
@@ -1353,9 +1512,13 @@ sub arc {
     return $self;
 }
 
-=item $content->pie($xc,$yc, $rx,$ry, $alpha,$beta, $dir)
+=head4 pie
 
-=item $content->pie($xc,$yc, $rx,$ry, $alpha,$beta)
+    $content->pie($xc,$yc, $rx,$ry, $alpha,$beta, $dir)
+
+    $content->pie($xc,$yc, $rx,$ry, $alpha,$beta)
+
+=over
 
 Creates a pie-shaped path from an ellipse centered on C<[$xc,$yc]>.
 The x-axis and y-axis semidiameters of the ellipse are C<$rx> and C<$ry>,
@@ -1374,6 +1537,8 @@ sweep.
 This is a shortcut to draw a section of elliptical (or circular) arc and
 connect it to the center of the ellipse or circle, to form a pie shape.
 
+=back
+
 =cut
 
 sub pie {
@@ -1389,10 +1554,14 @@ sub pie {
     return $self;
 }
 
-=item $content->curve($cx1,$cy1, $cx2,$cy2, $x,$y)
+=head4 curve
+
+    $content->curve($cx1,$cy1, $cx2,$cy2, $x,$y)
+
+=over
 
 This extends the path in a curve from the current point to C<[$x,$y]>,
-using the two specified I<control> points to create a cubic Bezier curve, and
+using the two specified I<control> points to create a B<cubic Bezier curve>, and
 updates the current position to be the new point (C<[$x,$y]>).
 
 Within a B<text> object, the text's baseline follows the Bezier curve.
@@ -1401,6 +1570,8 @@ Note that while multiple sets of three C<[x,y]> pairs are permitted, these
 are treated as I<independent> cubic Bezier curves. There is no attempt made to
 smoothly blend one curve into the next!
 
+=back
+
 =cut
 
 sub curve {
@@ -1426,7 +1597,11 @@ sub curve {
     return $self;
 }
 
-=item $content->qbspline($cx1,$cy1, $x,$y)
+=head4 qbspline, spline
+
+    $content->qbspline($cx1,$cy1, $x,$y)
+
+=over
 
 This extends the path in a curve from the current point to C<[$x,$y]>,
 using the two specified points to create a quadratic Bezier curve, and updates 
@@ -1459,6 +1634,8 @@ name is usable here. Since there are both quadratic and cubic splines available
 in PDF, it is preferred to use more descriptive names such as C<qbspline> and
 C<cbspline> to minimize confusion.
 
+=back
+
 =cut
 
 sub spline { return qbspline(@_); } ## no critic
@@ -1491,7 +1668,11 @@ sub qbspline {
     return $self;
 }
 
-=item $content->bspline($ptsRef, %opts)
+=head4 bspline, cbspline
+
+    $content->bspline($ptsRef, %opts)
+
+=over
 
 This extends the path in a curve from the current point to the end of a list
 of coordinate pairs in the array referenced by C<$ptsRef>. Smoothly continuous
@@ -1510,6 +1691,8 @@ of the last line or curve drawn becomes the new current point.
 
 Options %opts:
 
+=back
+
 =over
 
 =item 'firstseg' => 'I<mode>'
@@ -1628,14 +1811,16 @@ Bezier control points.
 
 =back
 
-=back
+=over
 
-=head3 Special cases
+B<Special cases>
 
 Adjacent points which are duplicates are consolidated. 
 An extra coordinate at the end of the input point list (not a full 
 C<[x,y]> pair) will, as usual, be ignored.
 
+=back
+
 =over
 
 =item 0 given points (after duplicate consolidation)
@@ -1663,11 +1848,15 @@ C<firstseg>, C<lastseg>, and C<colinear>.
 
 =back
 
+=over
+
 B<Alternate name:> C<cbspline>
 
 This is to emphasize that it is a I<cubic> Bezier spline, as opposed to a
 I<quadratic> Bezier spline (see C<qbspline> above).
 
+=back
+
 =cut
 
 sub cbspline { return bspline(@_); } ## no critic
@@ -2281,20 +2470,22 @@ sub _sweep {
     return $result;
 }
 
-=over
+=head4 bogen
 
-=item $content->bogen($x1,$y1, $x2,$y2, $radius, $move, $larger, $reverse)
+    $content->bogen($x1,$y1, $x2,$y2, $radius, $move, $larger, $reverse)
 
-=item $content->bogen($x1,$y1, $x2,$y2, $radius, $move, $larger)
+    $content->bogen($x1,$y1, $x2,$y2, $radius, $move, $larger)
 
-=item $content->bogen($x1,$y1, $x2,$y2, $radius, $move)
+    $content->bogen($x1,$y1, $x2,$y2, $radius, $move)
 
-=item $content->bogen($x1,$y1, $x2,$y2, $radius)
+    $content->bogen($x1,$y1, $x2,$y2, $radius)
 
-(German for I<bow>, as in a segment (arc) of a circle. This is a segment
-of a circle defined by the intersection of two circles of a given radius, 
-with the two intersection points as inputs. There are four possible resulting
-arcs, which can be selected with C<$larger> and C<$reverse>.)
+=over
+
+(I<bogen> is German for I<bow>, as in a segment (arc) of a circle. This is a 
+segment of a circle defined by the intersection of two circles of a given 
+radius, with the two intersection points as inputs. There are B<four> possible 
+resulting arcs, which can be selected with C<$larger> and C<$reverse>.)
 
 This extends the path along an arc of a circle of the specified radius
 between C<[$x1,$y1]> to C<[$x2,$y2]>. The current position is then set
@@ -2307,38 +2498,59 @@ I<not> a straight line to I<P1> and then the arc, but a blending into the curve
 from the current point. It will often I<not> pass through I<P1>!
 
 Set C<$larger> to a I<true> value to draw the larger ("outer") arc between the 
-two points, instead of the smaller one. Both arcs are
-drawn I<clockwise> from I<P1> to I<P2>. The default value of I<false> draws
-the smaller arc.
+two points, instead of the smaller one. Both arcs are drawn I<clockwise> from 
+I<P1> to I<P2>. The default value of I<false> draws the smaller arc.
+Note that the "other" circle's larger arc is used (the center point is 
+"flipped" across the line between I<P1> and I<P2>), rather than using the 
+"remainder" of the smaller arc's circle (which would necessitate reversing the
+direction of travel along the arc -- see C<$reverse>).
 
 Set C<$reverse> to a I<true> value to draw the mirror image of the
 specified arc (flip it over, so that its center point is on the other
 side of the line connecting the two points). Both arcs are drawn
 I<counter-clockwise> from I<P1> to I<P2>. The default (I<false>) draws 
-clockwise arcs.
+clockwise arcs. An arc is B<always> drawn from I<P1> to I<P2>; the direction
+(clockwise or counter-clockwise) may be chosen.
 
 The C<$radius> value cannot be smaller than B<half> the distance from 
 C<[$x1,$y1]> to C<[$x2,$y2]>. If it is too small, the radius will be set to
 half the distance between the points (resulting in an arc that is a
-semicircle). This is a silent error.
+semicircle). This is a silent error, as even if the points are correct, due
+to rounding etc. they may not fall I<exactly> on the two circles.
+
+You can think of "looking" from I<P1> to I<P2>. In the dengenerate case, where
+the radius is exactly half the distance between the points, there is no
+difference between "small" and "large" arcs, and both cirles will coincide
+with their center half way between I<P1> and I<P2>. Only the direction matters.
+Once the radius is any larger, the two circles become distinct. The primary 
+circle is centered to your right, whose small arc is CW on your left; the 
+secondary circle is centered to your left, whose small arc is CCW on your 
+right. The "large" arcs are the arcs using the remainder of the circles: CW 
+large is part of the left (secondary) circle, and CCW large is part of the 
+right (primary) circle.
+
+=back
 
 =cut
 
 sub bogen {
-    my ($self, $x1,$y1, $x2,$y2, $r, $move, $larc, $spf) = @_;
+    my ($self, $x1,$y1, $x2,$y2, $r, $move, $larc, $dir) = @_;
+    # in POD description, dir is "reverse" flag
 
     my ($p0_x,$p0_y, $p1_x,$p1_y, $p2_x,$p2_y, $p3_x,$p3_y);
-    my ($dx,$dy, $x,$y, $alpha,$beta, $alpha_rad, $d,$z, $dir, @points);
+    my ($dx,$dy, $x,$y, $alpha,$beta, $alpha_rad, $d,$z, @points);
 
     if ($x1 == $x2 && $y1 == $y2) {
         die "bogen requires two distinct points";
+	# SVG def of (arc) merely leaves it as a point
     }
     if ($r <= 0.0) {
         die "bogen requires a positive radius";
+	# SVG def of (arc) merely takes absolute value
     }
     $move = 0 if !defined $move;
     $larc = 0 if !defined $larc;
-    $spf  = 0 if !defined $spf;
+    $dir  = 0 if !defined $dir;
 
     $dx = $x2 - $x1;
     $dy = $y2 - $y1;
@@ -2350,7 +2562,7 @@ sub bogen {
     $alpha = rad2deg($alpha_rad);
     # use the complementary angle for flipped arc (arc center on other side)
     # effectively clockwise draw from P2 to P1
-    $alpha -= 180 if $spf;
+    $alpha -= 180 if $dir;
 
     $d = 2*$r;
     # z/d must be no greater than 1.0 (arcsine arg)
@@ -2368,7 +2580,7 @@ sub bogen {
     # note that start and end could be well out of +/-360 degree range
     @points = _arctocurve($r,$r, 90+$alpha+$beta/2,90+$alpha-$beta/2, 1);
 
-    if ($spf) {  # flip order of points for reverse arc
+    if ($dir) {  # flip order of points for reverse arc
         my @pts = @points;
         @points = ();
         while (@pts) {
@@ -2406,15 +2618,18 @@ sub bogen {
     return $self;
 }
 
-=back
-
 =head2 Path Painting (Drawing)
 
+=head3 stroke
+
+    $content->stroke()
+
 =over
 
-=item $content->stroke()
+Strokes the current path. That is, it is drawing solid or dashed I<lines>, but
+B<not> filling areas.
 
-Strokes the current path.
+=back
 
 =cut
 
@@ -2430,11 +2645,15 @@ sub stroke {
     return $self;
 }
 
-=item $content->fill($use_even_odd_fill)
+=head3 fill
+
+    $content->fill($use_even_odd_fill)
 
-=item $content->fill('rule' => $rule)
+    $content->fill('rule' => $rule)
 
-=item $content->fill()  # use default nonzero rule
+    $content->fill()  # use default nonzero rule
+
+=over
 
 Fill the current path's enclosed I<area>. 
 It does I<not> stroke the enclosing path around the area.
@@ -2466,6 +2685,8 @@ for more details on filling.
 
 The "rule" parameter is added for PDF::API2 compatibility.
 
+=back
+
 =cut
 
 sub fill {
@@ -2487,11 +2708,15 @@ sub fill {
     return $self;
 }
 
-=item $content->fillstroke($use_even_odd_fill)
+=head3 fillstroke, paint, fill_stroke
+
+    $content->fillstroke($use_even_odd_fill)
+
+    $content->fillstroke('rule' => $rule)
 
-=item $content->fillstroke('rule' => $rule)
+    $content->fillstroke()  # use default nonzero rule
 
-=item $content->fillstroke()  # use default nonzero rule
+=over
 
 B<Fill> the current path's enclosed I<area> and then B<stroke> the enclosing 
 path around the area (possibly with a different color).
@@ -2528,6 +2753,8 @@ B<Alternate names:> C<paint> and C<fill_stroke>
 C<paint> is for compatibility with PDF::API2, while C<fill_stroke> is added
 for compatibility with many other PDF::API2-related renamed methods.
 
+=back
+
 =cut
 
 sub paint { return fillstroke(@_); } ## no critic
@@ -2553,11 +2780,15 @@ sub fillstroke {
     return $self;
 }
 
-=item $content->clip($use_even_odd_fill)
+=head3 clip
+
+    $content->clip($use_even_odd_fill)
 
-=item $content->clip('rule' => $rule)
+    $content->clip('rule' => $rule)
 
-=item $content->clip()  # use default nonzero rule
+    $content->clip()  # use default nonzero rule
+
+=over
 
 Modifies the current clipping path by intersecting it with the current
 path. Initially (a fresh page), the clipping path is the entire media. Each
@@ -2610,6 +2841,8 @@ See the object discussion in L<PDF::Builder::Docs/Rendering Order>.
 
 The "rule" parameter is added for PDF::API2 compatibility.
 
+=back
+
 =cut
 
 sub clip {
@@ -2631,7 +2864,11 @@ sub clip {
     return $self;
 }
 
-=item $content->shade($shade, @coord)
+=head3 shade
+
+    $content->shade($shade, @coord)
+
+=over
 
 Sets the shading matrix.
 
@@ -2648,6 +2885,8 @@ X-scaled and translated, Y-scaled and translated.
 
 =back
 
+=back
+
 =cut
 
 sub shade {
@@ -2668,15 +2907,15 @@ sub shade {
     return $self;
 }
 
-=back
-
 =head2 Colors
 
-=over
+=head3 fillcolor, fill_color, strokecolor, stroke_color
 
-=item $content->fillcolor($color)
+    $content->fillcolor($color)
 
-=item $content->strokecolor($color)
+    $content->strokecolor($color)
+
+=over
 
 Sets the fill (enclosed area) or stroke (path) color. The interior of text
 characters are I<filled>, and (I<if> ordered by C<render>) the outline is
@@ -2749,6 +2988,8 @@ B<Alternate names:> C<fill_color> and C<stroke_color>.
 
 These are provided for PDF::API2 compatibility.
 
+=back
+
 =cut
 
 # TBD document in POD (examples) and add t tests for (pattern/shading space, 
@@ -2918,24 +3159,24 @@ sub strokecolor {
     }
 }
 
-=back
-
 =head2 External Objects
 
-=over
+=head3 image
 
-=item $content->image($image_object, $x,$y, $width,$height)
+    $content->image($image_object, $x,$y, $width,$height)
 
-=item $content->image($image_object, $x,$y, $scale)
+    $content->image($image_object, $x,$y, $scale)
 
-=item $content->image($image_object, $x,$y)
+    $content->image($image_object, $x,$y)
 
-=item $content->image($image_object)
+    $content->image($image_object)
 
     # Example
     my $image_object = $pdf->image_jpeg($my_image_file);
     $content->image($image_object, 100, 200);
 
+=over
+
 Places an image on the page in the specified location (specifies the lower 
 left corner of the image). The default location is C<[0,0]>.
 
@@ -2949,6 +3190,8 @@ For example, if you have a 600x600 image that you would like to be
 shown at 600dpi (i.e., one inch square), set the width and height to 72.
 (72 Big Points is one inch)
 
+=back
+
 =cut
 
 # deprecated in PDF::API2 -- suggests use of object() instead
@@ -2982,13 +3225,17 @@ sub image {
     return $self;
 }
 
-=item $content->formimage($form_object, $x,$y, $scaleX, $scaleY)
+=head3 formimage
 
-=item $content->formimage($form_object, $x,$y, $scale)
+    $content->formimage($form_object, $x,$y, $scaleX, $scaleY)
 
-=item $content->formimage($form_object, $x,$y)
+    $content->formimage($form_object, $x,$y, $scale)
 
-=item $content->formimage($form_object)
+    $content->formimage($form_object, $x,$y)
+
+    $content->formimage($form_object)
+
+=over
 
 Places an XObject on the page in the specified location (giving the lower
 left corner of the image) and scale (applied to the image's native height
@@ -3008,6 +3255,8 @@ by image width and height I<within> C<formimage>, and require scaling of
 C<formimage> and have the user manually scale I<images> by the image width and 
 height (in pixels) in the call to C<formimage>.
 
+=back
+
 =cut
 
 sub formimage {
@@ -3035,11 +3284,20 @@ sub formimage {
     return $self;
 }
 
-=item $content = $content->object($object, $x,$y, $scale_x,$scale_y)
+=head3 object
+
+    $content = $content->object($object, $x,$y, $scale_x,$scale_y)
+
+=over
 
 Places an image or other external object (a.k.a. XObject) on the page in the
 specified location.
 
+Up to four optional arguments may be given, with their defaults as described
+below.
+
+If C<$x> and C<$y> are omitted, the object will be placed at C<[0, 0]>.
+
 For images, C<$scale_x> and C<$scale_y> represent the width and height of the
 image on the page, in points. If C<$scale_x> is omitted, it will default to 72
 pixels per inch. If C<$scale_y> is omitted, the image will be scaled
@@ -3054,13 +3312,19 @@ above), the position and scale will be relative to the updated coordinates.
 If no coordinate transformations are needed, this method can be called directly
 from the L<PDF::Builder::Page> object instead.
 
+=back
+
 =cut
 
-# Behavior based on argument count
-# 0: Place at 0, 0, 100%
-# 2: Place at X, Y, 100%
-# 3: Place at X, Y, scaled
-# 4: Place at X, Y, scale_w, scale_h
+# Behavior based on argument count. xo, x,y, scale_x/w,scale_y/h
+# 1: Place at 0, 0, 100%
+# 2: Place at x, 0, 100%
+# 3: Place at X, Y, 100%
+# 4: Place at X, Y, scaled
+# 5: Place at X, Y, scale_w, scale_h
+# TBD: size=>'points' or 'scale' to override Image usage. can do by finding
+#        an element 'size' (string) and inserting undef's before it to fill
+#        out @_ to 7+ in length.
 
 sub object {
     my ($self, $object, $x, $y, $scale_x, $scale_y) = @_;
@@ -3085,8 +3349,6 @@ sub object {
     return $self;
 }
 
-=back
-
 =head2 Text 
 
 =head3 Text State Parameters
@@ -3095,9 +3357,11 @@ All of the following parameters that take a size are applied before
 any scaling takes place, so you don't need to adjust values to
 counteract scaling.
 
-=over
+=head4 charspace, character_spacing, char_space
 
-=item $spacing = $content->charspace($spacing)
+    $spacing = $content->charspace($spacing)
+
+=over
 
 Sets additional spacing between B<characters> in a line. This is in I<points>,
 and is initially zero.
@@ -3107,10 +3371,28 @@ If C<$spacing> is given, the current setting is replaced by that value and
 C<$self> is B<returned> (to permit chaining).
 If C<$spacing> is not given, the current setting is B<returned>.
 
+One use for character spacing is to adjust I<tracking> in a line of text.
+It is common to adjust inter-word spacing (e.g., TeX "glue" length) to justify 
+a line (see C<wordspace>), but in cases where the result is words too close 
+together (or too far apart), you may want to adjust tracking in order to force 
+spaces back to a more "reasonable" standard size. For example, if you have a 
+fairly "loose" line, with wide spaces between words, you could add a little 
+character spacing between the letters of words, and shrink the spaces down to a 
+more reasonable size. Don't overdo it, and make the words themselves difficult
+to read! You also would want to take care to "drive" the resulting spaces 
+towards a consistent width throughout a document (or at least, a paragraph).
+
+You may also choose to use character spacing for special effects, such as a
+high-level heading expanded with extra space. This is a decorative effect, and
+should be used with restraint.
+
 B<CAUTION:> be careful about using C<charspace> if you are using a connected
-font. This might include Arabic, Devanagari, Latin cursive handwriting, and so 
-on. You don't want to leave gaps between characters, or cause overlaps. For 
-such fonts and typefaces, set the C<charspace> spacing to 0.
+("script") font. This might include Arabic, Devanagari, Latin cursive 
+handwriting, and so on. You don't want to leave gaps between characters, or 
+cause overlaps. For such fonts and typefaces, you I<may> need to explicitly set 
+the C<charspace> spacing to 0, if you have set it to non-zero elsewhere. 
+PDF::Builder may not be able to determine that a given font is a connected
+script font, and automatically suppress non-zero character spacing.
 
 B<Alternate names:> C<character_spacing> and C<char_space>
 
@@ -3118,6 +3400,8 @@ I<character_spacing> is provided for compatibility with PDF::API2, while
 I<char_space> is provided to be consistent with many other method name
 changes in PDF::API2.
 
+=back
+
 =cut
 
 sub _charspace {
@@ -3143,7 +3427,11 @@ sub charspace {
     }
 }
 
-=item $spacing = $content->wordspace($spacing)
+=head4 wordspace, word_spacing, word_space
+
+    $spacing = $content->wordspace($spacing)
+
+=over
 
 Sets additional spacing between B<words> in a line. This is in I<points> and
 is initially zero 
@@ -3153,6 +3441,10 @@ If C<$spacing> is given, the current setting is replaced by that value and
 C<$self> is B<returned> (to permit chaining).
 If C<$spacing> is not given, the current setting is B<returned>.
 
+See the note in C<charspace> in regards to I<tracking> adjustment, and its
+effect on C<wordspace>. The two calls may often be used together for optimal
+results (although resulting in a somewhat increased PDF file size).
+
 Note that it is a limitation of the PDF specification (as of version 1.7, 
 section 9.3.3) that only spacing with an ASCII space (x20) is adjusted. Neither
 required blanks (xA0) nor any multiple-byte spaces (including thin and wide
@@ -3164,6 +3456,8 @@ I<word_spacing> is provided for compatibility with PDF::API2, while
 I<word_space> is provided to be consistent with many other method name
 changes in PDF::API2.
 
+=back
+
 =cut
 
 sub _wordspace {
@@ -3189,7 +3483,11 @@ sub wordspace {
     }
 }
 
-=item $scale = $content->hscale($scale)
+=head4 hscale
+
+    $scale = $content->hscale($scale)
+
+=over
 
 Sets the percentage of horizontal text scaling (relative sizing, I<not> 
 spacing). This is initally 100 (percent, i.e., no scaling). A scale of greater 
@@ -3205,6 +3503,8 @@ justify text, you will usually be better off using C<charspace> and C<wordspace>
 to expand (or slightly condense) a line to fill a desired width. Also see 
 the C<text_justify()> calls for this purpose.
 
+=back
+
 =cut
 
 sub _hscale {
@@ -3230,9 +3530,15 @@ sub hscale {
 # note that the private class data ' hspace' is no longer supported
 # PDF::API2 still provides 'hspace' and '_hspace'
 
-=item $leading = $content->leading($leading)
+# lead() and the associated lead variable have been replaced by leading()
+
+=head4 leading
+
+    $leading = $content->leading($leading)
 
-=item $leading = $content->leading()
+    $leading = $content->leading()
+
+=over
 
 Sets the text leading, which is the distance between baselines. This
 is initially B<zero> (i.e., the lines will be printed on top of each
@@ -3247,20 +3553,10 @@ text baseline distance, in points). In cold metal typesetting, I<leading> was
 usually the I<extra> spacing between lines beyond the font height itself, 
 created by inserting lead (type alloy) shims.
 
-=item $leading = $content->lead($leading)
-
-=item $leading = $content->lead()
-
-B<Deprecated,> to be removed after March 2023. Use C<leading()> now.
-
-Note that the C<$self-E<gt>{' lead'}> internal variable is no longer available,
-having been replaced by C<$self-E<gt>{' leading'}>.
+=back
 
 =cut
 
-# to be removed 3/2023 or later
-sub lead { return leading(@_); }
-
 sub _leading {
     my ($leading) = @_;
 
@@ -3280,7 +3576,11 @@ sub leading {
     }
 }
 
-=item $mode = $content->render($mode)
+=head4 render
+
+    $mode = $content->render($mode)
+
+=over
 
 Sets the text rendering mode.
 
@@ -3308,6 +3608,8 @@ If C<$mode> is given, the current setting is replaced by that value and
 C<$self> is B<returned> (to permit chaining).
 If C<$mode> is not given, the current setting is B<returned>.
 
+=back
+
 =cut
 
 sub _render {
@@ -3330,7 +3632,11 @@ sub render {
     }
 }
 
-=item $dist = $content->rise($dist)
+=head4 rise
+
+    $dist = $content->rise($dist)
+
+=over
 
 Adjusts the baseline up or down from its current location.  This is
 initially zero. A C<$dist> greater than 0 moves the baseline B<up> the page
@@ -3342,6 +3648,8 @@ If C<$dist> is given, the current setting is replaced by that value and
 C<$self> is B<returned> (to permit chaining).
 If C<$dist> is not given, the current setting is B<returned>.
 
+=back
+
 =cut
 
 sub _rise {
@@ -3363,7 +3671,11 @@ sub rise {
     }
 }
 
-=item %state = $content->textstate(charspace => $value, wordspace => $value, ...)
+=head4 textstate
+
+    %state = $content->textstate(charspace => $value, wordspace => $value, ...)
+
+=over
 
 This is a shortcut for setting multiple text state parameters at once.
 If any parameters are set, an I<empty> hash is B<returned>.
@@ -3372,6 +3684,8 @@ state settings (a hash of the state is B<returned>).
 
 B<Note:> This does not work with the C<save> and C<restore> commands.
 
+=back
+
 =cut
 
 sub textstate {
@@ -3419,7 +3733,11 @@ sub textstate {
     return %state;
 }
 
-=item $content->font($font_object, $size)
+=head4 font
+
+    $content->font($font_object, $size)
+
+=over
 
 Sets the font and font size. C<$font> is an object created by calling
 L<PDF::Builder/"font"> to add the font to the document.
@@ -3434,6 +3752,8 @@ L<PDF::Builder/"font"> to add the font to the document.
 
     $pdf->save('sample.pdf');
 
+=back
+
 =cut
 
 sub _font {
@@ -3477,15 +3797,15 @@ sub _fontset {
     return $self;
 }
 
-=back
-
 =head3 Positioning Text
 
-=over
+=head4 position
 
-=item $content = $content->position($x, $y) # Set (also returns object, for ease of chaining)
+    $content = $content->position($x, $y) # Set (also returns object, for ease of chaining)
 
-=item ($x, $y) = $content->position()  # Get
+    ($x, $y) = $content->position()  # Get
+
+=over
 
 If called I<with> arguments (Set), moves to the start of the current line of 
 text, offset by C<$x> and C<$y> (right and up for positive values).
@@ -3496,6 +3816,8 @@ cursor (before the effects of any coordinate transformation methods).
 Note that this is very similar in function to C<distance()>, added recently 
 to PDF::API2 and added here for compatibility.
 
+=back
+
 =cut
 
 sub position {
@@ -3517,7 +3839,11 @@ sub position {
     return @{$self->{' textlinematrix'}};
 }
 
-=item ($tx,$ty) = $content->textpos()
+=head4 textpos, (see also) position
+
+    ($tx,$ty) = $content->textpos()
+
+=over
 
 B<Returns> the current text position on the page (where next write will happen) 
 as an array.
@@ -3527,6 +3853,8 @@ the next write will occur.
 
 B<Alternate name:> C<position> (added for compatibility with PDF::API2)
 
+=back
+
 =cut
 
 sub _textpos {
@@ -3556,7 +3884,11 @@ sub textpos {
     return $self->_textpos(@{$self->{" textlinematrix"}});
 }
 
-=item $content->distance($dx,$dy)
+=head4 distance
+
+    $content->distance($dx,$dy)
+
+=over
 
 This moves to the start of the previously-written line, plus an offset by the 
 given amounts, which are both required. C<[0,0]> would overwrite the previous 
@@ -3569,6 +3901,8 @@ B<Note> that subsequent text writes will be relative to this new starting
 (left) point and Y position! E.g., if you give a non-zero C<$dx>, subsequent
 lines will be indented by that amount.
 
+=back
+
 =cut
 
 sub distance {
@@ -3582,11 +3916,15 @@ sub distance {
     return $self;
 }
 
-=item $content->cr()
+=head4 cr
+
+    $content->cr()
+
+    $content->cr($vertical_offset)
 
-=item $content->cr($vertical_offset)
+    $content->cr(0)
 
-=item $content->cr(0)
+=over
 
 If passed without an argument, moves (down) to the start of the I<next> line 
 (distance set by C<leading>). This is similar to C<nl()>.
@@ -3603,6 +3941,8 @@ That is, it acts as a simple carriage return, without a linefeed.
 Note that any setting for C<leading> is ignored. If you wish to account for
 the C<leading> setting, you may wish to use the C<crlf> method instead.
 
+=back
+
 =cut
 
 sub cr {
@@ -3620,11 +3960,15 @@ sub cr {
     return $self;
 }
 
-=item $content->nl()
+=head4 nl
+
+    $content->nl()
 
-=item $content->nl($indent)
+    $content->nl($indent)
 
-=item $content->nl(0)
+    $content->nl(0)
+
+=over
 
 Moves to the start of the next line (see C<leading>). If C<$indent> is not given,
 or is 0, there is no indentation. Otherwise, indent by that amount (I<out>dent
@@ -3634,6 +3978,8 @@ space", or roughly 88 per em.
 Note that any setting for C<leading> is ignored. If you wish to account for
 the C<leading> setting, you may wish to use the C<crlf> method instead.
 
+=back
+
 =cut
 
 sub nl {
@@ -3653,7 +3999,11 @@ sub nl {
     return $self;
 }
 
-=item $content = $content->crlf()
+=head4 crlf
+
+    $content = $content->crlf()
+
+=over
 
 Moves to the start of the next line, based on the L</"leading"> setting. It
 returns its own object, for ease of chaining.
@@ -3663,6 +4013,8 @@ If leading isn't set, a default distance of 120% of the font size will be used.
 Added for compatibility with PDF::API2 changes; may be used to replace both
 C<cr> and C<nl> methods.
 
+=back
+
 =cut
 
 sub crlf {
@@ -3681,7 +4033,14 @@ sub crlf {
     return $self;
 }
 
-=item $width = $content->advancewidth($string, %opts)
+=head4 advancewidth, text_width
+
+    $width = $content->advancewidth($string, %opts)
+
+=over
+
+Returns the number of points that will be used (horizontally) by the input
+string. This assumes all on one line (no line breaking).
 
 Options %opts:
 
@@ -3727,6 +4086,8 @@ B<Alternate name:> C<text_width>
 
 This is provided for compatibility with PDF::API2.
 
+=back
+
 =cut
 
 sub text_width { return advancewidth(@_); } ## no critic
@@ -3743,6 +4104,10 @@ sub advancewidth {
         $opts{$k} = $self->{" $k"} unless defined $opts{$k};
     }
     # any other options given are ignored
+    
+    # $opts{'font'} (not ' font'}) needs to be defined. fail if not.
+    # other code should first fatal error in text() call, this is a fallback
+    return 0 if !defined $opts{'font'};
 
     $glyph_width = $opts{'font'}->width($text)*$opts{'fontsize'};
     $num_space   = $text =~ y/\x20/\x20/;
@@ -3754,31 +4119,59 @@ sub advancewidth {
     return $advance;
 }
 
-=back
-
 =head3 Rendering Text
 
-=over 
+=head4 Single Lines
 
-=back
+=head4 text
 
-=head4 Single Lines
+    $width = $content->text($text, %opts)
 
 =over
 
-=item $width = $content->text($text, %opts)
-
-Adds text to the page (left justified). 
+Adds text to the page (left justified by default). 
 The width used (in points) is B<returned>.
 
 Options:
 
 =over
 
+=item 'align' => position
+
+Align the text, assuming left-to-right writing direction (RTL/bidirectional is
+not currently supported).
+
+=over
+
+=item 'l' or 'left' (case insensitive).
+
+B<default.> Text I<begins> at the current text position.
+
+=item 'c' or 'center' (case insensitive).
+
+Text is I<centered> at the current text position.
+
+=item 'r' or 'right' (case insensitive). 
+
+Text I<ends> (is right justified to) at the current text position.
+
+=back
+
+In all cases, the ending text position is at the (right) end of the text.
+If mixing various alignments, you should explicitly place the current text
+position so as to not overwrite earlier text.
+
 =item 'indent' => $distance
 
 Indents the text by the number of points (A value less than 0 gives an
 I<outdent>).
+The indentation amount moves the text left (negative indentation) or right 
+(positive indentation), regardless of alignment. This allows desired alignment
+effects (for centered and right) that aren't exactly aligned on the current 
+position. For example, consider a column of decimal numbers centered on a
+desired I<x> position, but aligned on their decimal points. The C<indent>
+would be on a per-line basis, adjusted by the length of the number and the
+decimal position.
 
 =item 'underline' => 'none'
 
@@ -3824,10 +4217,20 @@ Example:
     #   distance 7, thickness 1.5, color yellow
     'strikethru' => [4,[1,'red'],7,[1.5,'yellow']],
 
+=item 'strokecolor' => color_spec
+
+Defines the underline or strikethru line color, if different from the text
+color.
+
+=back
+
 =back
 
 =cut
 
+# TBD: consider 'overline' similar to underline
+#      bidirectional/RTL identation, alignment meanings?
+
 sub _text_underline {
     my ($self, $xy1,$xy2, $underline, $color) = @_;
 
@@ -3953,12 +4356,26 @@ sub _text_strikethru {
 sub text {
     my ($self, $text, %opts) = @_;
     # copy dashed option names to preferred undashed names
+    if (defined $opts{'-align'} && !defined $opts{'align'}) { $opts{'align'} = delete($opts{'-align'}); }
     if (defined $opts{'-indent'} && !defined $opts{'indent'}) { $opts{'indent'} = delete($opts{'-indent'}); }
     if (defined $opts{'-underline'} && !defined $opts{'underline'}) { $opts{'underline'} = delete($opts{'-underline'}); }
     if (defined $opts{'-strokecolor'} && !defined $opts{'strokecolor'}) { $opts{'strokecolor'} = delete($opts{'-strokecolor'}); }
     if (defined $opts{'-strikethru'} && !defined $opts{'strikethru'}) { $opts{'strikethru'} = delete($opts{'-strikethru'}); }
 
-    my $wd = 0;
+    my $align = 'l'; # default
+    if (defined $opts{'align'}) {
+	$align = lc($opts{'align'});
+	if      ($align eq 'l' || $align eq 'left') {
+	    $align = 'l';
+	} elsif ($align eq 'c' || $align eq 'center') {
+	    $align = 'c';
+	} elsif ($align eq 'r' || $align eq 'right') {
+	    $align = 'r';
+	} else {
+	    $align = 'l'; # silent error on bad alignment
+	}
+    }
+
     if ($self->{' fontset'} == 0) {
         unless (defined($self->{' font'}) and $self->{' fontsize'}) {
             croak q{Can't add text without first setting a font and font size};
@@ -3966,24 +4383,48 @@ sub text {
         $self->font($self->{' font'}, $self->{' fontsize'});
         $self->{' fontset'} = 1;
     }
+
+    my $wd = $self->advancewidth($text);
+
+    my $indent = 0; # default
     if (defined $opts{'indent'}) {
-        $wd += $opts{'indent'};
-        $self->matrix_update($wd, 0);
+	$indent = $opts{'indent'};
+	# TBD: later may define indentation for RTL/bidirectional
     }
-    my $ulxy1 = [$self->_textpos2()];
 
-    if (defined $opts{'indent'}) {
-    # changed for Acrobat 8 and possibly others
-    #    $self->add('[', (-$opts{'indent'}*(1000/$self->{' fontsize'})*(100/$self->hscale())), ']', 'TJ');
-        $self->add($self->{' font'}->text($text, $self->{' fontsize'}, (-$opts{'indent'}*(1000/$self->{' fontsize'})*(100/$self->hscale()))));
+    # now have alignment, indentation amount, text width
+    # adjust indentation by text width and alignment. negative to move text left
+    if      ($align eq 'l') {
+	# no change
+    } elsif ($align eq 'c') {
+	$indent -= $wd/2;
+    } else { # 'r'
+	$indent -= $wd;
+    }
+
+    # indent is points to move text left (<0) or right (>0)
+    # per input 'indent' AND alignment AND text width
+    $self->matrix_update($indent, 0) if ($indent); # move current pos to start
+
+    my $ulxy1 = [$self->_textpos2()]; # x,y start of under/thru line
+
+    if ($indent) {
+	# now indent is positive >0 to move left. convert to milliems and scale
+        $self->add(
+	    $self->{' font'}->text(
+		$text, 
+		$self->{' fontsize'}, 
+	        -$indent*(1000/$self->{' fontsize'})*(100/$self->hscale()) ));
     } else {
-        $self->add($self->{' font'}->text($text, $self->{' fontsize'}));
+        $self->add(
+	    $self->{' font'}->text(
+		$text, 
+		$self->{' fontsize'} ));
     }
 
-    $wd = $self->advancewidth($text);
-    $self->matrix_update($wd, 0);
+    $self->matrix_update($wd, 0); # move current position right to end of text
 
-    my $ulxy2 = [$self->_textpos2()];
+    my $ulxy2 = [$self->_textpos2()]; # x,y end of under/thru line
 
     if (defined $opts{'underline'}) {
         $self->_text_underline($ulxy1,$ulxy2, $opts{'underline'}, $opts{'strokecolor'});
@@ -4019,7 +4460,11 @@ sub _metaEnd {
     return $self;
 }
 
-=item $width = $content->textHS($HSarray, $settings, %opts)
+=head4 textHS
+
+    $width = $content->textHS($HSarray, $settings, %opts)
+
+=over
 
 Takes an array of hashes produced by HarfBuzz::Shaper and outputs them to the
 PDF output file. HarfBuzz outputs glyph CIDs and positioning information. 
@@ -4164,13 +4609,15 @@ to HarfBuzz::Shaper (C<ttfont()> only, with .ttf or .otf files), and the font
 size must be the same. The appropriate location on the page must also already
 have been specified.
 
-B<NOTE:> as HarfBuzz::Shaper is still in its early days, it is possible that
-there will be major changes in its API. We hope that all changes will be 
-upwardly compatible, but do not control this package and cannot guarantee that
-there will not be any incompatible changes that in turn require changes to
-PDF::Builder (C<textHS()>).
+=back
 
 =cut
+#B<NOTE:> as HarfBuzz::Shaper is still in its early days, it is possible that
+#there will be major changes in its API. We hope that all changes will be 
+#upwardly compatible, but do not control this package and cannot guarantee that
+#there will not be any incompatible changes that in turn require changes to
+#PDF::Builder (C<textHS()>).
+#
 
 sub textHS {
     my ($self, $HSarray, $settings, %opts) = @_;
@@ -4468,7 +4915,11 @@ sub _outputCID {
     return;
 }
 
-=item $width = $content->advancewidthHS($HSarray, $settings, %opts)
+=head4 advancewidthHS, text_widthHS
+
+    $width = $content->advancewidthHS($HSarray, $settings, %opts)
+
+=over
 
 Returns text chunk width (in points) for Shaper-defined glyph array.
 This is the horizontal width for LTR and RTL direction, and the vertical
@@ -4512,7 +4963,7 @@ This is treated as 0 if an ax override setting is given.
 =item 'minKern' => amount (default 1)
 
 If the amount of kerning (font character width B<differs from> glyph I<ax> 
-value) is I<larger> than this many character grid units, use the unaltered ax 
+value) is I<larger> than this many character grid units, use the unaltered I<ax>
 for the width (C<textHS()> will output a kern amount in the TJ operation). 
 Otherwise, ignore kerning and use ax of the actual character width. The intent 
 is to avoid bloating the PDF code with unnecessary tiny kerning adjustments in 
@@ -4526,6 +4977,8 @@ Returns total width in points.
 
 B<Alternate name:> C<text_widthHS>
 
+=back
+
 =cut
 
 sub text_widthHS { return advancewidthHS(@_); } ## no critic
@@ -4607,19 +5060,26 @@ sub advancewidthHS {
     return $width; # height >0 for TTB and BTT
 }
 
-=back
-
 =head2 Advanced Methods
 
-=over
+=head3 save
 
-=item $content->save()
+    $content->save()
+
+=over
 
 Saves the current I<graphics> state on a PDF stack. See PDF definition 8.4.2 
 through 8.4.4 for details. This includes the line width, the line cap style, 
 line join style, miter limit, line dash pattern, stroke color, fill color,
 current transformation matrix, current clipping port, flatness, and dictname.
-This method applies to both I<text> and I<gfx/graphics> objects.
+
+This method applies to I<only> I<gfx/graphics> objects. If attempted with
+I<text> objects, you will receive a one-time (per run) warning message, and
+should update your code B<not> to do save() and restore() on a text object.
+Only save() generates the message, as presumably each restore() has already had
+a save() performed.
+
+=back
 
 =cut
 
@@ -4645,20 +5105,33 @@ sub _save {
 sub save {
     my ($self) = shift;
 
-   #unless ($self->_in_text_object()) {
+    our @MSG_COUNT;
+    if ($self->_in_text_object()) {
+	# warning in text mode, no other effect
+	if (!$MSG_COUNT[2]) {
+	    print STDERR "Can not call save() or restore() on a text object.\n";
+	    $MSG_COUNT[2]++;
+	}
+    } else {
         $self->add(_save());
-   #}
+    }
 
    return $self;
 }
 
-=item $content->restore()
+=head3 restore
+
+    $content->restore()
+
+=over
 
 Restores the most recently saved graphics state (see C<save>),
 removing it from the stack. You cannot I<restore> the graphics state (pop it off
 the stack) unless you have done at least one I<save> (pushed it on the stack).
 This method applies to both I<text> and I<gfx/graphics> objects.
 
+=back
+
 =cut
 
 sub _restore {
@@ -4668,14 +5141,20 @@ sub _restore {
 sub restore {
     my ($self) = shift;
 
-   #unless ($self->_in_text_object()) {
+    if ($self->_in_text_object()) {
+	# save() already gave any warning
+    } else {
         $self->add(_restore());
-   #}
+    }
 
    return $self;
 }
 
-=item $content->add(@content)
+=head3 add
+
+    $content->add(@content)
+
+=over
 
 Add raw content (arbitrary string(s)) to the PDF stream. 
 You will generally want to use the other methods in this class instead,
@@ -4726,12 +5205,20 @@ PDF into a string and look for a certain pattern of "cm" output
 or similar, which is not within a save/restore (q/Q). If the stream is 
 already compressed, this might not be possible.
 
-=item $content->addNS(@content)
+=back
+
+=head3 addNS
+
+    $content->addNS(@content)
+
+=over
 
 Like C<add()>, but does B<not> make sure there is a space between each element
 and before and after the new content. It is up to I<you> to ensure that any
 necessary spaces in the PDF stream are placed there explicitly!
 
+=back
+
 =cut
 
 # add to 'poststream' string (dumped by ET)
@@ -4779,7 +5266,11 @@ sub _in_text_object {
     return $self->{' apiistext'};
 }
 
-=item $content->compressFlate()
+=head3 compressFlate
+
+    $content->compressFlate()
+
+=over
 
 Marks content for compression on output.  This is done automatically
 in nearly all cases, so you shouldn't need to call this yourself.
@@ -4788,6 +5279,8 @@ The C<new()> call can set the B<compress> parameter to 'flate' (default) to
 compress all object streams, or 'none' to suppress compression and allow you
 to examine the output in an editor.
 
+=back
+
 =cut
 
 sub compressFlate {
@@ -4799,7 +5292,11 @@ sub compressFlate {
     return $self;
 }
 
-=item $content->textstart()
+=head3 textstart
+
+    $content->textstart()
+
+=over
 
 Starts a text object (ignored if already in a text object). You will likely 
 want to use the C<text()> method (text I<context>, not text output) instead.
@@ -4808,6 +5305,8 @@ Note that calling this method, besides outputting a B<BT> marker, will reset
 most text settings to their default values. In addition, B<BT> itself will
 reset some transformation matrices.
 
+=back
+
 =cut
 
 sub textstart {
@@ -4841,13 +5340,19 @@ sub textstart {
     return $self;
 }
 
-=item $content->textend()
+=head3 textend
+
+    $content->textend()
+
+=over
 
 Ends a text object (ignored if not in a text object).
 
 Note that calling this method, besides outputting an B<ET> marker, will output
 any accumulated I<poststream> content.
 
+=back
+
 =cut
 
 sub textend {
@@ -4862,10 +5367,6 @@ sub textend {
     return $self;
 }
 
-=back
-
-=cut
-
 # helper function for many methods
 sub resource {
     my ($self, $type, $key, $obj, $force) = @_;
diff --git a/lib/PDF/Builder/Content/Hyphenate_basic.pm b/lib/PDF/Builder/Content/Hyphenate_basic.pm
index dbf6069..bebb679 100644
--- a/lib/PDF/Builder/Content/Hyphenate_basic.pm
+++ b/lib/PDF/Builder/Content/Hyphenate_basic.pm
@@ -5,7 +5,7 @@ use base 'PDF::Builder::Content::Text';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.025'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Content/Text.pm b/lib/PDF/Builder/Content/Text.pm
index 20a4ef0..6b7565e 100644
--- a/lib/PDF/Builder/Content/Text.pm
+++ b/lib/PDF/Builder/Content/Text.pm
@@ -9,8 +9,8 @@ use List::Util qw(min max);
 #use Data::Dumper;  # for debugging
 #  $Data::Dumper::Sortkeys = 1;  # hash keys in sorted order
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.025'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 =head1 NAME
 
@@ -34,9 +34,11 @@ sub new {
 
 =head2 Single Lines from a String
 
-=over
+=head3 text_left
+
+    $width = $content->text_left($text, %opts)
 
-=item $width = $content->text_left($text, %opts)
+=over
 
 Alias for C<text>. Implemented for symmetry, for those who use a lot of
 C<text_center> and C<text_right>, and desire a matching C<text_left>.
@@ -53,12 +55,15 @@ The width used (in points) is B<returned>.
 sub text_left {
     my ($self, $text, @opts) = @_;
 
-    return $self->text($text, @opts);
+    # override any stray 'align' that got through to here
+    return $self->text($text, @opts, 'align'=>'l');
 }
 
-=over
+=head3 text_center
 
-=item $width = $content->text_center($text, %opts)
+    $width = $content->text_center($text, %opts)
+
+=over
 
 As C<text>, but I<centered> on the current point.
 
@@ -72,13 +77,15 @@ The width used (in points) is B<returned>.
 sub text_center {
     my ($self, $text, @opts) = @_;
 
-    my $width = $self->advancewidth($text, @opts);
-    return $self->text($text, 'indent' => -($width/2), @opts);
+    # override any stray 'align' that got through to here
+    return $self->text($text, @opts, 'align'=>'c');
 }
 
-=over
+=head3 text_right
 
-=item $width = $content->text_right($text, %opts)
+    $width = $content->text_right($text, %opts)
+
+=over
 
 As C<text>, but right-aligned to the current point.
 
@@ -94,13 +101,15 @@ The width used (in points) is B<returned>.
 sub text_right {
     my ($self, $text, @opts) = @_;
 
-    my $width = $self->advancewidth($text, @opts);
-    return $self->text($text, 'indent' => -$width, @opts);
+    # override any stray 'align' that got through to here
+    return $self->text($text, @opts, 'align'=>'r');
 }
 
-=over
+=head3 text_justified
+
+    $width = $content->text_justified($text, $width, %opts)
 
-=item $width = $content->text_justified($text, $width, %opts)
+=over
  
 As C<text>, but stretches text using C<wordspace>, C<charspace>, and (as a  
 last resort) C<hscale>, to fill the desired
@@ -302,7 +311,8 @@ sub text_justified {
 
     } # original $overage was not near 0
     # do the output, with wordspace, charspace, and possiby hscale changed
-    $self->text($text, %opts);
+    # override any stray 'align' that got through to here
+    $self->text($text, %opts, 'align'=>'l');
 
     # restore settings
     $self->hscale($hs); $self->wordspace($ws); $self->charspace($cs);
@@ -316,7 +326,7 @@ The string is split at regular blanks (spaces), x20, to find the longest
 substring that will fit the C<$width>. 
 If a single word is longer than C<$width>, it will overflow. 
 To stay strictly within the desired bounds, set the option
-C<spillover>=>0 to disallow spillover.
+C<spillover>=E<gt>0 to disallow spillover.
 
 =head3 Hyphenation
 
@@ -332,7 +342,7 @@ There are hard coded minimums of 2 letters before the split, and 2 letters after
 the split. See C<Hyphenate_basic.pm>. Note that neither hyphenation nor simple
 line splitting makes any attempt to prevent widows and orphans, prevent 
 splitting of the last word in a column or page, or otherwise engage in 
-I<paragraph shaping>.
+more desirable I<paragraph shaping>.
 
 =over
 
@@ -566,16 +576,22 @@ sub _removeSHY {
     return $out;
 }
 
-=over
+=head4 text_fill_left, text_fill
+
+    ($width, $leftover) = $content->text_fill_left($string, $width, %opts)
 
-=item ($width, $leftover) = $content->text_fill_left($string, $width, %opts)
+=over
 
 Fill a line of 'width' with as much text as will fit, 
 and outputs it left justified.
 The width actually used, and the leftover text (that didn't fit), 
 are B<returned>.
 
-=item ($width, $leftover) = $content->text_fill($string, $width, %opts)
+=back
+
+    ($width, $leftover) = $content->text_fill($string, $width, %opts)
+
+=over
 
 Alias for text_fill_left().
 
@@ -590,7 +606,8 @@ sub text_fill_left {
 
     my $over = (not(defined($opts{'spillover'}) and $opts{'spillover'} == 0));
     my ($line, $ret) = $self->_text_fill_line($text, $width, $over, %opts);
-    $width = $self->text($line, %opts);
+    # override any stray 'align' that got through to here
+    $width = $self->text($line, %opts, 'align'=>'l');
     return ($width, $ret);
 }
 
@@ -599,9 +616,11 @@ sub text_fill {
     return $self->text_fill_left(@_); 
 }
 
-=over
+=head4 text_fill_center
+
+    ($width, $leftover) = $content->text_fill_center($string, $width, %opts)
 
-=item ($width, $leftover) = $content->text_fill_center($string, $width, %opts)
+=over
 
 Fill a line of 'width' with as much text as will fit, 
 and outputs it centered.
@@ -623,9 +642,11 @@ sub text_fill_center {
     return ($width, $ret);
 }
 
-=over
+=head4 text_fill_right
 
-=item ($width, $leftover) = $content->text_fill_right($string, $width, %opts)
+    ($width, $leftover) = $content->text_fill_right($string, $width, %opts)
+
+=over
 
 Fill a line of 'width' with as much text as will fit, 
 and outputs it right justified.
@@ -647,9 +668,11 @@ sub text_fill_right {
     return ($width, $ret);
 }
 
-=over
+=head4 text_fill_justified
+
+    ($width, $leftover) = $content->text_fill_justified($string, $width, %opts)
 
-=item ($width, $leftover) = $content->text_fill_justified($string, $width, %opts)
+=over
 
 Fill a line of 'width' with as much text as will fit, 
 and outputs it fully justified (stretched or condensed).
@@ -696,12 +719,13 @@ sub text_fill_justified {
     # if last line, use $align (don't justify)
     if ($ret eq '') {
 	my $lw = $self->advancewidth($line, %opts);
+        # override any stray 'align' that got through to here
 	if      ($align eq 'l') {
-	    $width = $self->text($line, %opts);
+	    $width = $self->text($line, %opts, 'align'=>'l');
 	} elsif ($align eq 'c') {
-	    $width = $self->text($line, 'indent' => ($width-$lw)/2, %opts);
+	    $width = $self->text($line, 'indent' => ($width-$lw)/2, %opts, 'align'=>'l');
 	} else {  # 'r'
-	    $width = $self->text($line, 'indent' => ($width-$lw), %opts);
+	    $width = $self->text($line, 'indent' => ($width-$lw), %opts, 'align'=>'l');
 	}
     } else {
         $width = $self->text_justified($line, $width, %opts);
@@ -711,11 +735,17 @@ sub text_fill_justified {
 
 =head2 Larger Text Segments
 
-=over
+=head3 paragraph
+
+    ($overflow_text, $unused_height) = $txt->paragraph($text, $width,$height, $continue, %opts)
 
-=item ($overflow_text, $unused_height) = $txt->paragraph($text, $width,$height, $continue, %opts)
+    ($overflow_text, $unused_height) = $txt->paragraph($text, $width,$height, %opts)
 
-=item $overflow_text = $txt->paragraph($text, $width,$height, $continue, %opts)
+    $overflow_text = $txt->paragraph($text, $width,$height, $continue, %opts)
+
+    $overflow_text = $txt->paragraph($text, $width,$height, %opts)
+
+=over
 
 Print a single string into a rectangular area on the page, of given width and
 maximum height. The baseline of the first (top) line is at the current text
@@ -726,6 +756,10 @@ not fit all of it within the rectangle). If called in an array context, the
 unused height is also B<returned> (may be 0 or negative if it just filled the 
 rectangle).
 
+C<$continue> is optional, with a default value of 0. An C<%opts> list may be
+given after the fixed parameters, whether or not C<$continue> is explicitly
+given.
+
 If C<$continue> is 1, the first line does B<not> get special treatment for
 indenting or outdenting, because we're printing the continuation of the 
 paragraph that was interrupted earlier. If it's 0, the first line may be 
@@ -792,7 +826,16 @@ fit to a given width, and nothing is done for "widows and orphans".
 # TBD for bidi/RTL languages, should indenting be on right?
 
 sub paragraph {
-    my ($self, $text, $width,$height, $continue, %opts) = @_;
+    my ($self, $text, $width,$height, @optsA) = @_;
+    # if odd number of elements in optsA, it contains $continue flag and
+    #   remainder is %opts. if even, paragraph is being called PDF::API2 style
+    #   with no $continue (default to 0).
+    my $continue = 0;
+    if (@optsA % 2) {
+	$continue = splice(@optsA, 0, 1);
+    }
+    my %opts = @optsA;
+
     # copy dashed option names to preferred undashed names
     if (defined $opts{'-align'} && !defined $opts{'align'}) { $opts{'align'} = delete($opts{'-align'}); }
     if (defined $opts{'-pndnt'} && !defined $opts{'pndnt'}) { $opts{'pndnt'} = delete($opts{'-pndnt'}); }
@@ -851,11 +894,13 @@ sub paragraph {
     return $text;
 }
 
-=over
+=head3 section, paragraphs
 
-=item ($overflow_text, $continue, $unused_height) = $txt->section($text, $width,$height, $continue, %opts)
+    ($overflow_text, $continue, $unused_height) = $txt->section($text, $width,$height, $continue, %opts)
 
-=item $overflow_text = $txt->section($text, $width,$height, $continue, %opts)
+    $overflow_text = $txt->section($text, $width,$height, $continue, %opts)
+
+=over
 
 The C<$text> contains a string with one or more paragraphs C<$width> wide, 
 starting at the current text position, with a newline \n between each 
@@ -885,6 +930,10 @@ will also be added after the last paragraph printed.
 
 See C<paragraph> for other C<%opts> you can use, such as C<align> and C<pndnt>.
 
+B<Alternate name:> paragraphs
+
+This is for compatibiity with PDF::API2.
+
 =back
 
 =cut
@@ -938,9 +987,11 @@ sub section {
     return $overflow;
 }
 
-=over
+=head3 textlabel
+
+    $width = $txt->textlabel($x,$y, $font, $size, $text, %opts)
 
-=item $width = $txt->textlabel($x,$y, $font, $size, $text, %opts)
+=over
 
 Place a line of text at an arbitrary C<[$x,$y]> on the page, with various text 
 settings (treatments) specified in the call.
@@ -1080,9 +1131,11 @@ sub textlabel {
         $wht = $self->text_center($text, %opts);
     } elsif (defined($opts{'left'}) && $opts{'left'} ||
 	     defined($opts{'align'}) && $opts{'align'} =~ /^l/i) {
-        $wht = $self->text($text, %opts);  # explicitly left aligned
+        # override any stray 'align' that got through to here
+        $wht = $self->text($text, %opts, 'align'=>'l');  # explicitly left aligned
     } else {
-        $wht = $self->text($text, %opts);  # left aligned by default
+        # override any stray 'align' that got through to here
+        $wht = $self->text($text, %opts, 'align'=>'l');  # left aligned by default
     }
 
     $self->textend();
@@ -1097,9 +1150,11 @@ sub textlabel {
 
 =head2 Complex Column Output with Markup
 
-=over
+=head3 column
 
-=item ($rc, $next_y, $unused) = $text->column($page, $text, $grfx, $markup, $txt, %opts)
+    ($rc, $next_y, $unused) = $text->column($page, $text, $grfx, $markup, $txt, %opts)
+
+=over
 
 This method fills out a column of text on a page, returning any unused portion
 that could not be fit, and where it left off on the page.
@@ -1200,6 +1255,7 @@ and CSS. Currently, HTML tags
     'u', 'ins' (underline)
     'ovl' (TBD -- non-HTML, overline)
     'k' (TBD -- non-HTML, kerning left/right shift)
+    'blockquote' (block quote)
 
 are supported (fully or in part I<unless> "TBD"), along with limited CSS for 
 color, font-size, font-family, etc. 
@@ -1226,6 +1282,7 @@ Sorry!
 
 Supported CSS properties: 
 
+    border-* TBD
     color (foreground color)
     display (inline/block)
     font-family (name as defined to FontManager, e.g. Times)
@@ -1236,9 +1293,11 @@ Supported CSS properties:
     list-style-position (outside) TBD inside
     list-style-type (marker description, see also _marker-before/after)
     margin-top/right/bottom/left (pt, bare number = pt, % of font-size)
+      margin TBD update four margin-* properties
     text-decoration (none, underline, line-through, overline)
     text-height (leading, as ratio of baseline-spacing to font-size)
     text-indent (pt, bare number = pt, % of current font-size)
+    text-align (left/right) TBD, future also center/justify?
     width (pt, bare number) width of horizontal rule
 
 Non-standard CSS "properties". You may want to set these in CSS:
@@ -1632,7 +1691,7 @@ It contains nothing to be used.
 
 # TBD, future:
 #  * = not official HTML5 or CSS (i.e., extension)
-# perhaps 3.026?  
+# perhaps 3.027?  
 #   arbitrary paragraph shapes (path)
 #   at a minimum, hyphenate-basic usage including &SHY;
 #   <hr>, <img>, <sup>, <sub>, <pre>, <nobr>, <br>, <dl>/<dt>/<dd>, <center>*
@@ -1669,7 +1728,7 @@ It contains nothing to be used.
 #   <keep>* material to keep together, such as headings and paragraph text
 #   leading (line-height) as a dimension instead of a ratio, convert to ratio
 #
-# 3.027 or later?
+# 3.028 or later?
 #  left/right auto margins? <center> may need this
 #  Text::KnuthLiang hyphenation
 #  <hyp>*, <nohyp>* control hypenation in a word (and remember
@@ -1861,17 +1920,19 @@ sub _default_css {
     $style{'body'}->{'_left'} = '0'; 
     $style{'body'}->{'_right'} = '0'; 
     $style{'body'}->{'text-indent'} = '0'; 
-   #$style{'body'}->{'text-align'} = 'left'; # center, right
+   #$style{'body'}->{'text-align'} = 'left'; # TBD center, right
    #$style{'body'}->{'text-transform'} = 'none'; # capitalize, uppercase, lowercase
-   #$style{'body'}->{'border-style'} = 'none'; # solid, dotted, dashed...
+   #$style{'body'}->{'border-style'} = 'none'; # solid, dotted, dashed... TBD
    #$style{'body'}->{'border-width'} = '1pt'; 
    #$style{'body'}->{'border-color'} = 'inherit'; 
+   #   TBD border-* individually specify for top/right/bottom/left
     $style{'body'}->{'text-decoration'} = 'none';
     $style{'body'}->{'display'} = 'block'; 
     $style{'body'}->{'width'} = '-1';  # TBD currently unused
     $style{'body'}->{'height'} = '-1';  # TBD currently unused ex. hr size
     $style{'body'}->{'_href'} = ''; 
 
+    $style{'p'}->{'display'} = 'block';
     $style{'font'}->{'display'} = 'inline';
     $style{'span'}->{'display'} = 'inline';
 
@@ -1887,12 +1948,12 @@ sub _default_css {
     $style{'ul'}->{'display'} = 'block'; 
     $style{'ul'}->{'margin-bottom'} = '50%'; 
     $style{'ol'}->{'list-style-type'} = '.o'; # decimal, lower-roman, upper-roman, lower-alpha, upper-alpha, none
-    $style{'ol'}->{'list-style-position'} = 'outside'; # inside
+    $style{'ol'}->{'list-style-position'} = 'outside'; # inside TBD
     $style{'ol'}->{'display'} = 'block'; 
     $style{'ol'}->{'margin-bottom'} = '50%'; 
     $style{'ol'}->{'_marker-before'} = ''; # content to add before marker
     $style{'ol'}->{'_marker-after'} = '.'; # content to add after marker
-   #$style{'sl'}->{'list-style-type'} = 'none';
+   #$style{'sl'}->{'list-style-type'} = 'none'; TBD
     $style{'li'}->{'display'} = 'block';  # should inherit from ul or ol
     $style{'li'}->{'margin-top'} = '50%';  # relative to text's font-size
 
@@ -1954,17 +2015,17 @@ sub _default_css {
     $style{'del'}->{'display'} = 'inline';
     $style{'del'}->{'text-decoration'} = 'line-through';
 
-    # non-standard tag for overline
+    # non-standard tag for overline TBD
    #$style{'ovl'}->{'display'} = 'inline';
    #$style{'ovl'}->{'text-decoration'} = 'overline';
     
     # non-standard tag for kerning (+ font-size fraction to move left, - right)
-    # e.g., for vulgar fraction adjust / and denominator <sub>
+    # e.g., for vulgar fraction adjust / and denominator <sub> TBD
    #$style{'k'}->{'display'} = 'inline';
    #$style{'k'}->{'_kern'} = '0.2';
 
     $style{'hr'}->{'display'} = 'block';
-    $style{'hr'}->{'height'} = '1'; # 1pt default thickness
+    $style{'hr'}->{'height'} = '0.5'; # 1/2 pt default thickness
     $style{'hr'}->{'width'} = '-1'; # default width is full column
     $style{'hr'}->{'margin-top'} = '100%'; 
     $style{'hr'}->{'margin-bottom'} = '100%'; 
@@ -1977,9 +2038,9 @@ sub _default_css {
     $style{'blockquote'}->{'text-height'} = '1.00'; # close spacing
     $style{'blockquote'}->{'font-size'} = '80%'; # smaller type
 
-   #$style{'sc'}->{'font-size'} = '80%'; # smaller type
+   #$style{'sc'}->{'font-size'} = '80%'; # smaller type TBD
    #$style{'sc'}->{'_expand'} = '110%'; # wider type   TBD _expand
-   #likewise for pc (petite caps)
+   #likewise for pc (petite caps) TBD
 
     return \%style;
 } # end of _default_css()
@@ -2097,6 +2158,7 @@ sub _output_text {
     my $start = 1; # counter for ordered lists
     my $list_depth = 0; # nesting level of ol and ul
     my $list_marker = ''; # li marker text
+    my $reversed_ol = 0; # count down from start
 
     my $phrase='';
     my $remainder='';
@@ -2227,11 +2289,20 @@ sub _output_text {
 		    $list_depth++;
 		}
 	        if ($tag eq 'ol') { 
+		    # save any existing start and reversed_ol values
+		    $properties[-2]->{'_start'} = $start; # current start
+		    $properties[-2]->{'_reversed_ol'} = $reversed_ol; # cur flag
+
 	            $start = 1;
 	            if (defined $mytext[$el]->{'start'}) {
 	                $start = $mytext[$el]->{'start'};
 		    }
-		    $list_depth++;
+		    if (defined $mytext[$el]->{'reversed'}) {
+			$reversed_ol = 1;
+		    } else {
+			$reversed_ol = 0;
+		    }
+                    $list_depth++;
 	        }
 	        if ($tag eq 'li') {
 		    # paragraph, but label depends on parent (list-style-type)
@@ -2249,7 +2320,11 @@ sub _output_text {
 			# it's a bullet character
 		    } else {
 			# fully formatted ordered list item
-		        $start++;
+			if ($reversed_ol) {
+		            $start--;
+			} else {
+		            $start++;
+			}
 		    }
 		    # sl: use normal marker width, marker is blank. position
 		    #     is always outside (ignore inside if given)
@@ -2378,6 +2453,11 @@ sub _output_text {
 		if ($tag eq 'ol' || $tag eq 'ul') { $list_depth--; }
 		# note that current_prop should be all up to date by the
 		# time you hit the end tag
+		if ($tag eq 'ol') {
+		    # restore any saved start and reversed_ol values
+		    $start = $properties[-2]->{'_start'}; # current start
+		    $reversed_ol = $properties[-2]->{'_reversed_ol'}; # cur flag
+                }
 
 		# ready to pick larger of top and bottom margins (block display)
 		$botm = $current_prop->{'margin-bottom'};
@@ -2462,6 +2542,9 @@ sub _output_text {
 	    # any size as a percentage of font-size will use the current fs
 	    my $fs = $current_prop->{'font-size'};
 
+	    # uncommon to only change font size without also changing something
+	    # else, so make font selection call at the same time, besides,
+	    # there is very little involved in just returning current font.
 	    if ($call_get_font) {
                 $text->font($pdf->get_font(
 		    'face' => $current_prop->{'font-family'}, 
@@ -2536,7 +2619,7 @@ sub _output_text {
 	    $remainder = '';
 
 	    # for now, all whitespace convert to single blanks 
-	    # TBD blank preserve for <code> or <pre>
+	    # TBD blank preserve for <code> or <pre> (CSS white-space)
 	    $phrase =~ s/\s+/ /g;
 
 	    # a phrase may have multiple words. see if entire thing fits, and if
@@ -2775,7 +2858,7 @@ sub _output_text {
 				$pageno = $1;
 				$xpos = $2;
 				$ypos = $3; 
-				$zoom = 1;
+				$zoom = undef;
 			    } elsif ($href =~ m/^#(\d+)-(\d+)-(\d+)-(.+)$/) {
 				# #p-x-y-z format (zoom, at a specific spot)
 				$pageno = $1; # integer > 0
@@ -3021,10 +3104,10 @@ sub _output_text {
 	    # do nothing, leave the font state/colors as-is
 	} else { # 2
 	    # restore to entry with @entry_state
-	    return (2, $next_y, []);
+	    return (2, $next_y-$botm, []);
 	}
 
-	return (0, $next_y, []);
+	return (0, $next_y-$botm, []);
     } else {
 	# we ran out of vertical space in the column. return -1 and 
 	# remainder of mytext list (next_y would be inapplicable)
@@ -3751,6 +3834,25 @@ sub _size2pt {
 # for ordered, returns $prefix.formatted_value.$suffix.blank
 # for unordered, returns string .disc, .circle, .square, or .box
 #   (.box is nonstandard marker)
+#
+# TBD check that 'none' works properly (as <sl>?)
+# TBD for ol, there are many other formats: cjk-decimal, decimal-leading-zero,
+#      lower-greek, upper-greek?, lower-latin = lower-alpha, upper-latin =
+#      upper-alpha, arabic-indic, -moz-arabic-indic, armenian, [-moz-]bengali, 
+#      cambodian (khmer), [-moz-]cjk-earthly-branch, [-moz-]cjk-heavenly-stem, 
+#      cjk-ideographic, [-moz-]devanagari, ethiopi-numeric, georgian,
+#      [-moz-]gujarati, [-moz-]gurmukhi, hebrew, hiragana, hiragana-iroha, 
+#      japanese-formal, japanese-informal, [-moz-]kannada, katakana, 
+#      katakana-iroha, korean-hangul-formal, korean-hanja-formal, 
+#      korean-hanja-informal, [-moz-]lao, lower-armenian, upper-armenian, 
+#      [-moz-]malayalam, mongolian, [-moz-]myanmar, [-moz-]oriya, 
+#      [-moz-]persian, simp-chinese-formal, simp-chinese-informal, [-moz-]tamil,
+#      [-moz-]telugu, [-moz-]thai, tibetan, trad-chinese-formal, 
+#      trad-chinese-informal, disclosure-open, disclosure-closed
+# TBD for ol, some browser-specific formats: -moz-ethiopic-halehame,
+#      -moz-ethiopic-halehame-am, [-moz-]ethiopic-halehame-ti-et, [-moz-]hangul,
+#      [-moz-]hangul-consonant, [-moz-]urdu
+# TBD for ul, ability to select images and possibly other characters
 sub _marker {
     my ($type, $depth, $value, $prefix, $suffix) = @_; 
                                      # type = list-style-type, 
@@ -4007,7 +4109,7 @@ sub _revise_baseline {
 } # end of _revise_baseline()
 
 # just something to pause during debugging
-sub  _pause {
+sub _pause {
     print STDERR "====> Press Enter key to continue...";
     my $input = <>;
     return;
diff --git a/lib/PDF/Builder/Docs.pm b/lib/PDF/Builder/Docs.pm
index a0983f5..b2eac66 100644
--- a/lib/PDF/Builder/Docs.pm
+++ b/lib/PDF/Builder/Docs.pm
@@ -3,8 +3,8 @@ package PDF::Builder::Docs;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.025'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 # originally part of Builder.pm, it was split out due to its length
 
@@ -60,7 +60,13 @@ PDF::Builder can make use of some optional libraries, which are not I<required>
 for a successful installation. If you want improved speed and capabilities for
 certain functions, you may want to install and use these libraries:
 
-B<*> Graphics::TIFF -- PDF::Builder inherited a rather slow, buggy, and limited 
+=over
+
+=item * 
+
+Graphics::TIFF
+
+PDF::Builder inherited a rather slow, buggy, and limited 
 TIFF image library from PDF::API2. If Graphics::TIFF (available on CPAN, uses 
 libtiff.a) is installed, PDF::Builder will use that instead, unless you specify 
 that it is to use the old, pure Perl library. The only time you might want to 
@@ -68,7 +74,11 @@ consider this is when you need to pass an open filehandle to C<image_tiff>
 instead of a file name. See resolved bug reports RT 84665 and RT 118047, as well
 as C<image_tiff>, for more information.
 
-B<*> Image::PNG::Libpng -- PDF::Builder inherited a rather slow and buggy pure 
+=item * 
+
+Image::PNG::Libpng
+
+PDF::Builder inherited a rather slow and buggy pure 
 Perl PNG image library from PDF::API2. If Image::PNG::Libpng (available on 
 CPAN, uses libpng.a) is installed, PDF::Builder will use that instead, unless 
 you specify that it is to use the old, pure Perl library. Using the new library 
@@ -76,22 +86,47 @@ will give you improved speed, the ability to use 16 bit samples, and the
 ability to read interlaced PNG files. See resolved bug report RT 124349, as well
 as C<image_png>, for more information.
 
-B<*> HarfBuzz::Shaper -- This library enables PDF::Builder to handle complex
+=item * 
+
+HarfBuzz::Shaper
+
+This library enables PDF::Builder to handle complex
 scripts (Arabic, Devanagari, etc.) as well as non-LTR writing systems. It is
 also useful for Latin and other simple scripts, for ligatures and improved
 kerning. HarfBuzz::Shaper is based on a set of HarfBuzz libraries, which it
 will attempt to build if they are not found. See C<textHS> for more 
 information.
 
-B<*> Text::Markdown -- This library is used if you want to format "Markdown"
+=item * 
+
+Text::Markdown
+
+This library is used if you want to format "Markdown"
 style code in PDF::Builder, via the C<column()> method. It translates a certain
 dialect of Markdown into HTML, which is then further processed.
 
-B<*> HTML::TreeBuilder -- This library is used to format HTML input into a 
+=item * 
+
+HTML::TreeBuilder
+
+This library is used to format HTML input into a 
 data structure which PDF::Builder can interpret, via the C<column()> method.
 Note that if Markdown input is used, it will also need HTML::TreeBuilder to
 handle the HTML the Markdown is translated to.
 
+=item * 
+
+Pod::Simple::XHTML
+
+This library is used if you wish to generate the HTML documentation from the
+POD and PM source, using C<docs/buildDoc.pl>. Note that the full set of
+documentation can also be found online at 
+https://www.catskilltech.com/FreeSW/product/PDF-Builder/title/PDF%3A%3ABuilder/freeSW_full 
+under the "Documentation" link. This online documentation is updated at 
+every CPAN release, but not necessarily when the GitHub repository is updated.
+
+=back
+
 Note that the installation process will B<not> attempt to install these 
 libraries automatically. If you don't wish to use one or more of them, you are
 free to not install the optional librarie(s). If you may want to make use of
@@ -493,6 +528,43 @@ temporarily exiting (ET) to graphics mode to draw the lines, and then returning
 be easily made. Since "BT" resets some text settings, this needs to be done
 with care!
 
+=head2 Notes on Reader support of features
+
+PDF Readers are complex pieces of software, written by different groups at
+different times. Thus, they may differ in how they support features and handle
+non-standard (i.e., not quite meeting standards) content! Most Readers out 
+there support all or most features up through PDF 1.7, and some support PDF 2.x
+features. Note that PDF::Builder supports PDF 1.4 for the most part, with a few
+PDF 1.5 features added. Most any Reader out there I<should> (in theory) support 
+any PDF produced with PDF::Builder.
+
+There is no official I<reference implementation> of a Reader, although Adobe's
+Acrobat Reader (I<AAR>, a free download) is so prevalent that it is almost a 
+I<de facto> standard. At least, we I<try> to get PDF::Builder and its tests and 
+examples to run on AAR. Sometimes it can be difficult, as, for example, the 
+handling of save (B<q>) and restore (B<Q>) operators (commands) within a text 
+stream. The PDF standard sort of suggests that these apply only to the Graphics 
+Stream, and possibly shouldn't appear in a Text Stream. Most Readers appear to 
+just ignore q and Q within a text stream, and AAR usually seems to, but certain 
+combinations of stream size and compression seem to trigger a warning in AAR 
+upon load! This particular case is now a moot point, as C<save()> and 
+C<restore()> have been reverted to being no-ops (with a single warning message 
+given if found) in a Text Stream.
+
+We have been advised that certain stream operators may not be strictly allowed
+within certain parts of a stream (particularly certain graphics state operators
+after path construction has started). No Reader seems to give problems with 
+this at the moment, but users should be aware that the ordering of their 
+PDF::Builder calls I<may> need to be updated at some point, to get PDFs usable 
+on all Readers. If necessary, we will add code to enforce this (or at least, 
+warn of potential problems). Please feel free to report if you find such
+restrictions are necessary.
+
+Also note that not all I<filters> (including compression methods) may be
+supported on all Readers. For example, at this time, AAR (and a number of other
+Readers) apparently do not support CCITT Group 4 Fax compression (for some TIFF
+images). This remains under investigation.
+
 =head2 PDF Versions Supported
 
 When creating a PDF file using the functions in PDF::Builder, the output is
@@ -531,19 +603,28 @@ In 2017, PDF::Builder was forked by Phil M. Perry, who desired a more aggressive
 schedule of new features and bug fixes than Simms was providing, although some 
 of Simms's work I<has> been ported from PDF::API2.
 
-According to "pdfapi2_for_fun_and_profit_APW2005.pdf" (on 
+According to Alfred Reibenschuh's 2005 presentation 
+"pdfapi2_for_fun_and_profit_APW2005.pdf" (on 
 http://pdfapi2.sourceforge.net, an unmaintained site), the history of PDF::API2
 (the predecessor to PDF::Builder) goes as such:
 
 =over
 
-=item E<nbsp> E<nbsp> E<bull>E<nbsp> First Code implemented based on PDFlib-0.6 (AFPL)
+=item * 
+
+First Code implemented based on PDFlib-0.6 (AFPL)
+
+=item * 
+
+Changed to Text::PDF with a total rewrite as Text::PDF::API (procedural)
+
+=item * 
 
-=item E<nbsp> E<nbsp> E<bull>E<nbsp> Changed to Text::PDF with a total rewrite as Text::PDF::API (procedural)
+Unmaintainable Code triggered rewrite into new Namespace PDF::API2 (object-oriented, LGPL)
 
-=item E<nbsp> E<nbsp> E<bull>E<nbsp> Unmaintainable Code triggered rewrite into new Namespace PDF::API2 (object-oriented, LGPL)
+=item * 
 
-=item E<nbsp> E<nbsp> E<bull>E<nbsp> Object-Structure streamlined in 0.4x
+Object-Structure streamlined in 0.4x
 
 =back
 
@@ -595,21 +676,33 @@ The C<level> parameter accepts the following values:
 
 =over
 
-=item 0 = Do not output any diagnostic messages; just return any version override.
+=item Z<>0 
 
-=item 1 = Output error-level (serious) diagnostic messages, as well as returning any version override.
+Do not output any diagnostic messages; just return any version override.
+
+=item Z<>1 
+
+Output error-level (serious) diagnostic messages, as well as returning any version override.
 
 Errors include, in no place was the /Root object specified, or if it was, the indicated object was not found. An object claims another object as its child (/Kids list), but another object has already claimed that child. An object claims a child, but that child does not list a Parent, or the child lists a different Parent.
 
-=item 2 = Output error- (serious) and warning- (less serious) level diagnostic messages, as well as returning any version override. B<This is the default.>
+=item Z<>2
+
+Output error- (serious) and warning- (less serious) level diagnostic messages, as well as returning any version override. B<This is the default.>
 
-=item 3 = Output error- (serious), warning- (less serious), and note- (informational) level diagnostic messages, as well as returning any version override.
+=item Z<>3
+
+Output error- (serious), warning- (less serious), and note- (informational) level diagnostic messages, as well as returning any version override.
 
 Notes include, in no place was the (optional) /Info object specified, or if it was, the indicated object was not found. An object was referenced, but no entry for it was found among the objects. (This may be OK if the object is not defined, or is on the free list, as the reference will then be ignored.) An object is defined, but it appears that no other object is referencing it.
 
-=item 4 = Output error-, warning-, and note-level diagnostic messages, as well as returning any version override. Also dump the diagnostic data structure.
+=item Z<>4
+
+Output error-, warning-, and note-level diagnostic messages, as well as returning any version override. Also dump the diagnostic data structure.
+
+=item Z<>5
 
-=item 5 = Output error-, warning-, and note-level diagnostic messages, as well as returning any version override. Also dump the diagnostic data structure and the C<$self> data structure (generally useful only if you have already read in the PDF file).
+Output error-, warning-, and note-level diagnostic messages, as well as returning any version override. Also dump the diagnostic data structure and the C<$self> data structure (generally useful only if you have already read in the PDF file).
 
 =back
 
@@ -632,8 +725,6 @@ Controls viewing preferences for the PDF.
 
 =over
 
-=over
-
 =item fullscreen
 
 Full-screen mode, with no menu bar, window controls, or any other window visible.
@@ -648,14 +739,10 @@ Document outline visible.
 
 =back
 
-=back
-
 =head3 Page Layout Options
 
 =over
 
-=over
-
 =item singlepage
 
 Display one page at a time.
@@ -666,13 +753,11 @@ Display the pages in one column.
 
 =item twocolumnleft
 
-Display the pages in two columns, with oddnumbered pages on the left.
+Display the pages in two columns, with odd-numbered pages on the left.
 
 =item twocolumnright
 
-Display the pages in two columns, with oddnumbered pages on the right.
-
-=back
+Display the pages in two columns, with odd-numbered pages on the right.
 
 =back
 
@@ -680,8 +765,6 @@ Display the pages in two columns, with oddnumbered pages on the right.
 
 =over
 
-=over
-
 =item hidetoolbar
 
 Specifying whether to hide tool bars.
@@ -734,8 +817,6 @@ Print duplex by default and flip on the long edge of the sheet.
 
 =back
 
-=back
-
 =head3 Page Fit Options
 
 These options are used for the C<firstpage> layout, as well as for 
@@ -916,11 +997,11 @@ consider what readers and other PDF tools may be used with a PDF you produce!
 Also note that earlier Acrobat readers had coordinate limits as small as 3240
 User Units (45 inches), and I<minimum> media size of 72 or 3 User Units.
 
-=head3 User Units
+=head3 User Units (userunit)
 
-=over
+    $pdf->userunit($number)
 
-=item $pdf->userunit($number)
+=over
 
 The default User Unit in the PDF coordinate system is one point (1/72 inch). You
 can think of it as a scale factor to enable larger (or even, smaller) documents.
@@ -968,19 +1049,19 @@ may be scaled down to the current User Unit.
 
 =back
 
-=head3 Media Box
+=head3 Media Box (mediabox)
 
-=over
+    $pdf->mediabox($name)
 
-=item $pdf->mediabox($name)
+    $pdf->mediabox($name, orient => 'orientation' )
 
-=item $pdf->mediabox($name, orient => 'orientation' )
+    $pdf->mediabox($w,$h)
 
-=item $pdf->mediabox($w,$h)
+    $pdf->mediabox($llx,$lly, $urx,$ury)
 
-=item $pdf->mediabox($llx,$lly, $urx,$ury)
+    ($llx,$lly, $urx,$ury) = $pdf->mediabox()
 
-=item ($llx,$lly, $urx,$ury) = $pdf->mediabox()
+=over
 
 Sets the global Media Box (or page's Media Box, if C<< $page-> >> instead). 
 This defines the width and height (or by corner
@@ -994,8 +1075,8 @@ addition, the Media Box defines the overall I<coordinate system> for text and
 graphics operations.
 
 If no arguments are given, the current Media Box (global or page) coordinates
-are returned instead. The former C<get_mediabox> (page only) function is 
-B<deprecated> and will likely be removed some time in the future. In addition,
+are returned instead. The former C<get_mediabox> (page only) function was 
+B<deprecated> and has been removed. In addition,
 when I<setting> the Media Box, the resulting coordinates are returned. This 
 permits you to specify the page size by a name (alias) and get the dimensions 
 back, all in one call.
@@ -1035,6 +1116,8 @@ can't make C<y> I<increase> from top to bottom!).
 
 B<Example:>
 
+=back
+
     $pdf = PDF::Builder->new();
     $pdf->mediabox('A4'); # A4 size (595 Pt wide by 842 Pt high)
     ...
@@ -1050,6 +1133,8 @@ B<Example:>
     ...
     $pdf->saveas('our/new.pdf');
 
+=over
+
 See the L<PDF::Builder::Resource::PaperSizes> source code for the full list of
 supported names (aliases) and their dimensions in points. You are free to add
 additional paper sizes to this file, if you wish. You might want to do this if
@@ -1060,19 +1145,19 @@ size as the full media (Media Box), and you don't mind their starting at 0,0.
 
 =back
 
-=head3 Crop Box
+=head3 Crop Box (cropbox)
 
-=over
+    $pdf->cropbox($name)
 
-=item $pdf->cropbox($name)
+    $pdf->cropbox($name, orient => 'orientation')
 
-=item $pdf->cropbox($name, orient => 'orientation')
+    $pdf->cropbox($w,$h)
 
-=item $pdf->cropbox($w,$h)
+    $pdf->cropbox($llx,$lly, $urx,$ury)
 
-=item $pdf->cropbox($llx,$lly, $urx,$ury)
+    ($llx,$lly, $urx,$ury) = $pdf->cropbox()
 
-=item ($llx,$lly, $urx,$ury) = $pdf->cropbox()
+=over
 
 Sets the global Crop Box (or page's Crop Box, if C<< $page-> >> instead). 
 This will define the media size to which the output will 
@@ -1092,8 +1177,8 @@ may show you the full media size (Media Box) and a 100 Point wide blank area
 (in this example) around the visible content.
 
 If no arguments are given, the current Crop Box (global or page) coordinates
-are returned instead. The former C<get_cropbox> (page only) function is 
-B<deprecated> and will likely be removed some time in the future. If a Crop Box
+are returned instead. The former C<get_cropbox> (page only) function was 
+B<deprecated> and has been removed. If a Crop Box
 has not been defined, the Media Box coordinates (which always exist) will be
 returned instead. In addition,
 when I<setting> the Crop Box, the resulting coordinates are returned. This 
@@ -1127,19 +1212,19 @@ Crop Box (and other boxes).
 
 =back
 
-=head3 Bleed Box
+=head3 Bleed Box (bleedbox)
 
-=over
+    $pdf->bleedbox($name)
 
-=item $pdf->bleedbox($name)
+    $pdf->bleedbox($name, orient => 'orientation')
 
-=item $pdf->bleedbox($name, orient => 'orientation')
+    $pdf->bleedbox($w,$h)
 
-=item $pdf->bleedbox($w,$h)
+    $pdf->bleedbox($llx,$lly, $urx,$ury)
 
-=item $pdf->bleedbox($llx,$lly, $urx,$ury)
+    ($llx,$lly, $urx,$ury) = $pdf->bleedbox()
 
-=item ($llx,$lly, $urx,$ury) = $pdf->bleedbox()
+=over
 
 Sets the global Bleed Box (or page's Bleed Box, if C<< $page-> >> instead). 
 This is typically used in printing on paper, where you want 
@@ -1156,8 +1241,8 @@ alignment dots, etc., while crop marks (trim guides) are at least partly within
 the bleed area (and should be printed after content is printed).
 
 If no arguments are given, the current Bleed Box (global or page) coordinates
-are returned instead. The former C<get_bleedbox> (page only) function is 
-B<deprecated> and will likely be removed some time in the future. If a Bleed Box
+are returned instead. The former C<get_bleedbox> (page only) function was 
+B<deprecated> and has been removed. If a Bleed Box
 has not been defined, the Crop Box coordinates (if defined) will be returned,
 otherwise the Media Box coordinates (which always exist) will be returned. 
 In addition, when I<setting> the Bleed Box, the resulting coordinates are 
@@ -1177,19 +1262,19 @@ the page Bleed Box (and other boxes).
 
 =back
 
-=head3 Trim Box
+=head3 Trim Box (trimbox)
 
-=over
+    $pdf->trimbox($name)
 
-=item $pdf->trimbox($name)
+    $pdf->trimbox($name, orient => 'orientation')
 
-=item $pdf->trimbox($name, orient => 'orientation')
+    $pdf->trimbox($w,$h)
 
-=item $pdf->trimbox($w,$h)
+    $pdf->trimbox($llx,$lly, $urx,$ury)
 
-=item $pdf->trimbox($llx,$lly, $urx,$ury)
+    ($llx,$lly, $urx,$ury) = $pdf->trimbox()
 
-=item ($llx,$lly, $urx,$ury) = $pdf->trimbox()
+=over
 
 Sets the global Trim Box (or page's Trim Box, if C<< $page-> >> instead). 
 This is supposed to be the actual dimensions of the 
@@ -1199,8 +1284,8 @@ the trim box. The default value is equal to Crop Box, but is often a bit
 smaller than any Bleed Box, to allow the desired "bleed" effect.
 
 If no arguments are given, the current Trim Box (global or page) coordinates
-are returned instead. The former C<get_trimbox> (page only) function is 
-B<deprecated> and will likely be removed some time in the future. If a Trim Box
+are returned instead. The former C<get_trimbox> (page only) function was 
+B<deprecated> and has been removed. If a Trim Box
 has not been defined, the Crop Box coordinates (if defined) will be returned,
 otherwise the Media Box coordinates (which always exist) will be returned. 
 In addition, when I<setting> the Trim Box, the resulting coordinates are 
@@ -1220,19 +1305,19 @@ the page Trim Box (and other boxes).
 
 =back
 
-=head3 Art Box
+=head3 Art Box (artbox)
 
-=over
+    $pdf->artbox($name)
 
-=item $pdf->artbox($name)
+    $pdf->artbox($name, orient => 'orientation')
 
-=item $pdf->artbox($name, orient => 'orientation')
+    $pdf->artbox($w,$h)
 
-=item $pdf->artbox($w,$h)
+    $pdf->artbox($llx,$lly, $urx,$ury)
 
-=item $pdf->artbox($llx,$lly, $urx,$ury)
+    ($llx,$lly, $urx,$ury) = $pdf->artbox()
 
-=item ($llx,$lly, $urx,$ury) = $pdf->artbox()
+=over
 
 Sets the global Art Box (or page's Art Box, if C<< $page-> >> instead). 
 This is supposed to define "the extent of the page's 
@@ -1245,8 +1330,8 @@ used for defining "important" content (e.g., I<excluding> advertisements) that
 may or may not be brought over to another page (e.g., N-up printing).
 
 If no arguments are given, the current Art Box (global or page) coordinates
-are returned instead. The former C<get_artbox> (page only) function is 
-B<deprecated> and will likely be removed some time in the future. If an Art Box
+are returned instead. The former C<get_artbox> (page only) function was 
+B<deprecated> and has been removed. If an Art Box
 has not been defined, the Crop Box coordinates (if defined) will be returned,
 otherwise the Media Box coordinates (which always exist) will be returned. 
 In addition, when I<setting> the Art Box, the resulting coordinates are 
@@ -1283,7 +1368,7 @@ bound together into books or magazines. You would usually just supply a PDF
 with all the pages; they would take care of the signature layout (which 
 includes offsets and 180 degree rotations). 
 
-(As an aside, don't count on a printer having
+(As an aside, don't count on a commercial printer having
 any particular font available, so be sure to ask. Usually they will want you
 to embed all fonts used, but ask first, and double-check before handing over
 the print job! TTF/OTF fonts (C<ttfont()>) are embedded by default, but other 
@@ -1311,8 +1396,9 @@ Crop Box, but crop marks for trimming (if used) should go just outside the Trim
 Box (partly or wholly within the Bleed Box), and
 be drawn I<after> all content. If you're I<not> trimming the paper, don't try 
 to do any bleed effects (including solid background color pages/covers), as 
-you will usually have a white edge around the 
-sheet anyway. Don't count on a PDF document I<never> being physically printed,
+you will usually have a white edge around the sheet anyway (printers leave a 
+clean, dry route for the feed rollers). Don't count on a PDF document I<never> 
+being physically printed,
 and not just displayed (where you can do things like bleed all the way to the
 media edge). Finally, for single sheet printing, an Art Box is 
 probably unnecessary, but if you're combining pages into N-up prints, or doing 
@@ -1432,6 +1518,23 @@ See also L<PDF::Builder::Resource::Font::CoreFont>.
 
 =head3 PS Fonts
 
+=head4 WARNING: End of Adobe Support
+
+B<Adobe has announced an end to support for Type 1 (Postscript/T1) fonts in its 
+products. The announcement wordings are a bit vague, sometimes referring to 
+"all products" and other times just to "authoring software". Presumably, Adobe 
+PDF Readers (as well as Readers supplied by other parties) will continue to 
+display PDFs with Type 1 fonts for quite some time, although this is by no 
+means absolutely certain. Note that this does NOT mean that PDF::Builder or 
+other Third Party authoring tools may not continue to support Type 1 fonts. 
+This termination by Adobe of support of a now old and obsolete font format does 
+not affect the use of PDF::Builder for authoring PDFs, nor is it binding on 
+other non-Adobe readers and authoring tools. However, using Adobe products for 
+editing of PDFs with Type 1 fonts, and possibly of displaying them, may no 
+longer be possible. At any rate, users may want to consider starting to move 
+away from Type 1 font usage and switch to TTF or even core fonts, although it 
+is unknown how long Type 1 Reader support will continue.>
+
 PS (T1) fonts are limited to single byte encodings. You cannot use UTF-8 or 
 other multibyte encodings with T1 fonts.
 The default encoding for the T1 fonts is
@@ -1443,12 +1546,16 @@ guarantee that future changes to font files will permit consistent results>.
 B<Note:> many Type1 fonts are limited to 256 glyphs, but some are available
 with more than 256 glyphs. Still, a maximum of 256 at a time are usable.
 
-C<psfont> accepts both ASCII (.pfa) and binary (.pfb) Type1 glyph files.
+C<psfont> accepts ASCII (.pfa), binary (.pfb), and .t1 Type1 glyph files.
 Font metrics can be supplied in either ASCII (.afm) or binary (.pfm) format,
 as can be seen in the examples given below. It is possible to use .pfa with .pfm
 and .pfb with .afm if that's what's available. The ASCII and binary files have
 the same content, just in different formats.
 
+B<Caution:> the file name given for the glyph file (first argument to C<psfont>)
+I<must> have a file extension of .pfa, .pfb, or .t1; as the extension will
+be checked to see how to parse the file.
+
 To allow UTF-8 text and extended glyph counts in one font, you should 
 consider replacing your use of Type1 fonts with TrueType (.ttf) and OpenType
 (.otf) fonts. There are tools, such as I<FontForge>, which can do a fairly good
@@ -1604,6 +1711,63 @@ the default list for the appropriate OS. If none can be found, find_ms() is
 tried, and as last resort use the C<.cmap> (if available), even if C<usecmf> 
 is not 1.
 
+B<CAUTION:> There is a "gotcha" with TrueType fonts that you need to be aware
+of when using them. PDF::Builder outputs to the text stream a list of I<glyph
+IDs> as four-digit hex codes, rather than the list of character byte codes 
+used by other
+font types. The B<Tw> operator, if used (C<$text->wordspace(n)>) to adjust
+inter-word spacing, B<will be ignored> by most, if not all, PDF Readers
+(including Adobe products). This is because this operator is looking for actual
+ASCII spaces (x20 bytes) in the stream, to apply the width change to. Note that 
+only ASCII spaces are affected (not other spaces), and not at all for TrueType 
+and OpenType fonts! We are considering adding ways to emulate word spacing for 
+TrueType font support, as well as possibly extending it to non-ASCII spaces for 
+all font types. Note that inter-character spacing (via C<$text->charspace(n)> 
+and the B<Tc> operator) still works for all font types.
+
+PDF::Builder has been updated to attempt to respect the B<Tw> operator when
+using TTF/OTF fonts. If the C<Tw> amount is non-zero, it will split up 
+sentences on ASCII spaces (x20) and individually place words on the page. This 
+necessarily bloats the PDF file size, but is the only way to adjust word 
+spacing via the C<wordspace()> method. Note that again, I<only> ASCII spaces
+(x20) are affected (to match the behavior of the B<Tw> operator for other font
+types), and other spaces (xA0 required/non-breaking space, thin space, etc.)
+are not handled.
+
+B<Where is the font I just added?> Well, sometimes you get lucky and can
+specify the exact directory that the C<.ttf> or C<.otf> file will reside in,
+making it easy to specify the path to the font file (for uses such as 
+C<ttfont()>, C<font()>, or Font Manager calls). Other times, the operating
+system will play hide and seek with you, leaving you to expend much time and
+energy to track down where the file is. Linux distributions tend to have their
+own favorite hiding places for font files, but at least they tend to be
+consistent! On the other hand, Windows often decides that it knows better than
+you, and will put files in an unexpected place, and under an unexpected name!
+
+To find out where your TTF or OTF file ended up, if you don't see an obvious 
+entry in /Windows/Fonts (even if you drag and dropped the font file there), 
+you need to look in /Users/XXXX/AppData/Local/Microsoft/Windows/Fonts, 
+depending on what user name you were signed on as when you installed the font. 
+Even then, you may not be done, as the name may have been changed to something 
+unrecognizable. You may need to look at Windows' mapping of font name to 
+filename.
+
+In the command shell (command line), or whatever equivalent you like to use, 
+enter "regedit" to bring up the registry editor. For the top level, choose 
+(click on) either C<HKEY_LOCAL_MACHINE> (for global font settings, in 
+/Windows/Fonts) or C<HKEY_CURRENT_USER> (for fonts installed by whoever is 
+currently signed on, in /Users/XXXX/AppData...). From there, both have the same 
+path: C<SOFTWARE E<gt> Microsoft E<gt> Windows NT E<gt> CurrentVersion E<gt> 
+Fonts>. This should bring up a listing of all the installed fonts (full name, 
+e.g. "Papyrus Regular") and their actual filename ("PAPYRUS.TTF"). For 
+instance, I just installed (drag and drop into /Windows/Fonts) a blackletter 
+"Gothic" font named I<English Towne Medium>. It ended up in my /Users/XXXX... 
+directory as C<EnglishTowne.ttf>.
+
+You don't need to change anything in the registry, just look. You I<do> have 
+the capability to change things, including hiding/showing the font, if you 
+care to get into those things.
+
 =back
 
 =head3 CJK Fonts
@@ -1729,11 +1893,24 @@ in landscape mode)
 I have found some code that should allow the C<image_jpeg> or C<image> routine
 to auto-rotate to (supposedly) the correct orientation, by looking for the Exif
 metadata "Orientation" tag in the file. However, three problems arise: 
-B<1)> if a photo has been edited, and rotated or flipped in the process, there is no guarantee that the Orientation tag has been corrected. 
-B<2)> more than one Orientation tag may exist (e.g., in the binary APP1/Exif header, I<and> in XML data), and they may not agree with each other -- which should be used? 
-B<3)> the code would need to uncompress the raster data, swap and/or transpose rows and/or columns, and recompress the raster data for inclusion into the PDF. This is costly and error-prone.
+
+=over
+
+=item 1.
+
+If a photo has been edited, and rotated or flipped in the process, there is no guarantee that the Orientation tag has been corrected. 
+
+=item 2.
+
+More than one Orientation tag may exist (e.g., in the binary APP1/Exif header, I<and> in XML data), and they may not agree with each other -- which should be used? 
+
+=item 3.
+
+The code would need to uncompress the raster data, swap and/or transpose rows and/or columns, and recompress the raster data for inclusion into the PDF. This is costly and error-prone.
 In any case, the user would need to be able to override any auto-rotate function.
 
+=back
+
 For the time being, PDF::Builder will simply leave it up to the user of the
 library to take care of rotating and/or flipping an image which displays 
 incorrectly. It is possible that we will consider adding some sort of query or warning that the image appears to I<not> be "normally" oriented (Orientation value 1 or "Top-left"), according to the Orientation flag. You can consider either (re-)saving the photo in an editor such as PhotoShop or GIMP, or using PDF::Builder code similar to the following (for images rotated 180 degrees):
@@ -1792,6 +1969,9 @@ it is available, unless explicitly told not to. Your code can test whether
 Graphics::TIFF is available by examining C<< $tiff->usesLib() >> or
 C<< $pdf->LA_GT() >>.
 
+Note that the first query is only available once the C<$tiff> object has been
+created. This may or may not be too late for your purposes.
+
 =over
 
 =item = -1 
@@ -1836,6 +2016,9 @@ if it is available, unless explicitly told not to. Your code can test whether
 Image::PNG::Libpng is available by examining C<< $png->usesLib() >> or
 C<< $pdf->LA_IPL() >>.
 
+Note that the first query is only available once the C<$png> object has been
+created. This may or may not be too late for your purposes.
+
 =over
 
 =item = -1 
@@ -1970,13 +2153,21 @@ means of one of the following:
 
 =over
 
-=item B<axs> is a value to be I<substituted> for 'ax' (points)
+=item B<axs> 
+
+is a value to be I<substituted> for 'ax' (points)
 
-=item B<axsp> is a I<substituted> value (I<percentage>) of the original 'ax'
+=item B<axsp> 
 
-=item B<axr> I<reduces> 'ax' by the value (points). If negative, increase 'ax'
+is a I<substituted> value (I<percentage>) of the original 'ax'
 
-=item B<axrp> I<reduces> 'ax' by the given I<percentage>. Again, negative increases 'ax'
+=item B<axr> 
+
+I<reduces> 'ax' by the value (points). If negative, increase 'ax'
+
+=item B<axrp> 
+
+I<reduces> 'ax' by the given I<percentage>. Again, negative increases 'ax'
 
 =back
 
@@ -2015,6 +2206,207 @@ how fitting to a line length (splitting up an array) could be done, as well as
 how words might be split on hard and soft hyphens. At some point, full paragraph
 and page shaping could be possible.
 
+=head2 MARKUP
+
+This section documents the markup capabilities of the C<column()> method.
+It is expected to be updated over time as more functionality is added.
+
+A certain flavor of I<Markdown> is supported, as translated by the 
+Text::Markdown package into HTML. That I<HTML> (and more, as direct input), 
+along with a subset of CSS, is 
+supported by C<column()>. This is I<not> the full Markdown or HTML languages, 
+by any stretch of the imagination, so check before using! Also, a small I<none> 
+markup which only does paragraphs (separated by empty lines) is provided.
+
+In all markup cases, certain CSS settings can be given as parameters or options
+to the C<column()> call, including a CSS <style> section which applies to both
+'none' and Markdown source input.
+
+=head3 Other input formats
+
+PDF::Builder currently only supports the markup languages described above.
+If you want to use something else (e.g., Perl's POD, or I<man> format, or even 
+MS Word or some other WYSIWYG format), you will need to find a converter 
+utility to convert it to a supported flavor of Markdown or HTML. Many such 
+converters already exist, so take a look (although you may well have to do some 
+cleanup before C<column()> accepts it). 
+
+Perhaps in the future, PDF::Builder will directly support additional formats, 
+but no promises. You will probably never see TeX/LaTeX input, as these already 
+have excellent PDF output (and would be a massive undertaking to process).
+
+=head3 Current HTML/Markdown supported
+
+=over
+
+=item * 
+
+B<<iE<gt>> and B<<emE<gt>> tags (Markdown B<_>, B<*>) as italic font style
+
+=item * 
+
+B<<bE<gt>> and B<<strongE<gt>> tags (Markdown B<**>) as bold font weight
+
+=item * 
+
+B<<pE<gt>> tag (Markdown empty line) as a paragraph
+
+=item * 
+
+B<<font face="font-family" color="color" size="font-size"E<gt>> as selecting face, color and size
+
+=item * 
+
+B<<spanE<gt>> needs style= attribute with CSS to do anything useful
+
+=item * 
+
+B<<ulE<gt>> tag (Markdown B<->) unordered (bulleted) list. type to override marker supported
+
+=item * 
+
+B<<olE<gt>> tag (Markdown B<1.>) ordered (numbered) list. start and type supported.
+
+=item * 
+
+B<<liE<gt>> tag list item. value to override ordered list counter, and type to override marker type supported
+
+=item * 
+
+B<<a href="URL"E<gt>> tag (Markdown B<[]()>) anchor/link, web page URL or this document target C<#p[-x-y[-z]]>
+
+=item * 
+
+B<<h1E<gt>> through B<<h6E<gt>> tags (Markdown B<#> through B<######>) headings
+
+=item * 
+
+B<<hr width="length" size="length"E<gt>> tag (Markdown B<--->) horizontal rule. currently no B<align> property (left alignment only). Default is C<width> = full column, and C<size> = 0.5pt.
+
+=item * 
+
+B<<sE<gt>>, B<<strikeE<gt>>, B<<delE<gt>> tags (Markdown B<~~>) text line-through
+
+=item * 
+
+B<<uE<gt>>, B<<insE<gt>> tags text underline
+
+=item * 
+
+B<<blockquoteE<gt>> tag (Markdown B<E<gt>>) indented both sides block of smaller text
+
+=back
+
+I<Numbered> (decimal and hexadecimal) entities are supported, as well as I<named> entities (e.g., C<E<amp>mdash;>). Both lists get a "gutter" (for the marker) of I<marker_width> points wide, so list formats are consistent over the call.
+
+=head3 Current CSS supported
+
+Note that the default CSS also applies to Markdown, unless you give a C<style =E<gt>> entry to the column() call to revise the CSS.
+
+In HTML, you can define B<<styleE<gt>> tags, but B<caution:> these are pulled out into a global style block (cumulative and global, as though they had all been given in the B<<headE<gt>>), applied after the CSS property defaults are defined and then any column() global C<style =E<gt> 'CSS list'> has been applied.
+
+CSS Selectors are very primitive:: a simple tag name (including B<body>), such as B<ol>; a class name such as B<.error>; or an ID such as B<#myID>. There are no hierarchies or combinations supported (e.g., nothing like B<p.abstract> or B<li E<gt> p>). The (decreasing) order of precedence follows a browser's: in a B<style => attribute, as a tag attribute (which may have a different name from the CSS's), an ID, a class, or a tag name. Comments /* and */ are B<NOT> currently supported in CSS.
+
+=over
+
+=item color
+
+foreground color, in standard PDF::Builder formats
+
+=item display 
+
+I<inline> or I<block>
+
+=item font-family
+
+as defined to Font Manager, e.g., I<Times>
+
+=item font-size
+
+I<n> points, I<n>pt, I<n%> of current font size. more units in future
+
+=item font-style
+
+I<normal> or I<italic>
+
+=item font-weight
+
+I<normal> or I<bold>
+
+=item height
+
+I<n> points or I<n>pt, thickness/size of horizontal rule B<ONLY>
+
+=item list-style-position
+
+I<outside> or I<inside>, currently only I<outside> supported
+
+=item list-style-typemarker 
+
+description, per standard CSS, plus "box" for unordered list to give a box outline marker (not a filled "square")
+
+=item margin-top/right/bottom/left
+
+per standard CSS. combined B<margin> in the future
+
+=item _marker-before
+
+I<extension>: text to insert before ordered list marker
+
+=item _marker-after
+
+I<extension>: text to insert after ordered list marker
+
+=item text-decoration
+
+per standard CSS
+
+=item text-height
+
+change leading, ratio of baseline-to-baseline to font size. future: set as a length or % of font size
+
+=item text-indent
+
+paragraph etc. indentation, I<n> points, I<npt>, I<n%> of font size
+
+=item width
+
+I<n> point or, I<npt>, width of horizontal rule B<ONLY>
+
+=back
+
+=head3 Global Settings
+
+There are a number of global settings either required or available for tuning the behavior of C<column()>. In the parameter list you can set
+
+=over
+
+=item font_size
+
+default initial font size (points) to be used, but can be overridden by CSS or C<<font sizeE<gt>>. Initially C<12>.
+
+=item leading
+
+default leading (text-height) ratio. Initially C<1.125>.
+
+=item marker_width
+
+points, set width of gutter where a list's marker goes. Initially C<2 * <font sizeE<gt>>.
+
+=item para
+
+list of indentation (text-indent) and inter-paragraph spacing (margin-top), both in points. These are the defaults for all formatting modes, unless overridden by a style => entry. Initially C<[ <font sizeE<gt>, 0 ]>.
+
+=item color
+
+initial text and graphics color setting, in standard PDF::Builder formats. Initially C<'black'>.
+
+=item style
+
+CSS declarations to be applied after CSS properties initialization and before any global <style> tags, Initially C<''>.
+
+=back
+
 =cut
 
 sub _docs {
diff --git a/lib/PDF/Builder/FontManager.pm b/lib/PDF/Builder/FontManager.pm
index f4df304..cea295b 100644
--- a/lib/PDF/Builder/FontManager.pm
+++ b/lib/PDF/Builder/FontManager.pm
@@ -3,8 +3,8 @@ package PDF::Builder::FontManager;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.025'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use Carp;
 use Scalar::Util qw(weaken);
@@ -95,9 +95,11 @@ created earlier, the saved C<$font> will be returned.
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    PDF::Builder::FontManager->new(%opts)
 
-=item PDF::Builder::FontManager->new(%opts)
+=over
 
 This is called from Builder.pm's C<new()>. Currently there are no options
 selectable. It will set up the font manager system and preload it with the
@@ -107,6 +109,8 @@ width (fixed pitch) face (core Courier), and a symbol font (core Symbol).
 There is no default for a script (cursive) font unless you set one using
 the C<font_settings()> method.
 
+=back
+
 =cut
 
 sub new {
@@ -118,6 +122,7 @@ sub new {
    #$class = ref($class) if ref($class);
    #my $self = $class->SUPER::new($pdf);
     $self->{' pdf'} = $pdf;
+    weaken $self->{' pdf'};
 
     # current font is default font until face explicitly changed.
     # Times face should be element 0 of the font-list array.
@@ -148,9 +153,13 @@ sub new {
     return $self;
 } # end of new()
 
-=item @list = $pdf->font_settings()  # Get
+=head2 font_settings
 
-=item $pdf->font_settings(%info)  # Set
+    @list = $pdf->font_settings()  # Get
+
+    $pdf->font_settings(%info)  # Set
+
+=over
 
 Get or set some information about fonts, particularly the fonts to be used for
 "generic" purposes.
@@ -173,6 +182,8 @@ generic script face is C<undef>).
     'symbol' => face to use for the generic symbol face 
                 (initialized to Symbol)
 
+=back
+
 =cut
 
 sub font_settings {
@@ -251,7 +262,11 @@ sub font_settings {
     return;
 }
 
-=item $rc = $pdf->add_font_path("a directory path", %opts)
+=head2 add_font_path
+
+    $rc = $pdf->add_font_path("a directory path", %opts)
+
+=over
 
 This method adds one search path to the list of paths to search. In the
 C<get_font()> method, each defined search path will be prepended to the C<file> 
@@ -300,6 +315,8 @@ was a problem encountered (and a message was issued).
 
 No options are currently defined.
 
+=back
+
 =cut
 
 sub add_font_path {
@@ -314,7 +331,11 @@ sub add_font_path {
     return $rc;
 } # end of add_font_path()
 
-=item $rc = add_font(%info)
+=head2 add_font
+
+    $rc = add_font(%info)
+
+=over
 
 Add a new font entry (by face and variants) to the Font Manager's list of
 known fonts.
@@ -487,6 +508,8 @@ perhaps a subdirectory) for the path here in C<add_font()>.
 
 =back
 
+=back
+
 =cut
 
 sub add_font {
@@ -698,9 +721,11 @@ sub _initialize_core {
 
 ## for some reason, this is uncallable from Content::Text
 ## try to fix it... it belongs here and not in Text.pm
-#=over
+#=head2 get_fv_extents
 #
-#=item ($ascender, $descender, $d_leading) = $pdf->get_fv_extents($font_size, $leading)
+#    ($ascender, $descender, $d_leading) = $pdf->get_fv_extents($font_size, $leading)
+#
+#=over
 #
 #Get the I<current> font's vertical extents (points above and below the
 #baseline), scaled by font_size, and leading is added to the descender amount.
@@ -711,6 +736,8 @@ sub _initialize_core {
 #I<font>, and not what the particular text's ascenders and descenders are 
 #actually using.
 #
+#=back
+#
 #=cut
 #
 #sub get_fv_extents {
@@ -729,9 +756,13 @@ sub _initialize_core {
 #    return ($ascender, $descender, $descender-($leading-1.0)*$font_size);
 #} # end of get_fv_extents()
 
-=item @current = $pdf->get_font()  # Get
+=head2 get_font
 
-=item $font = $pdf->get_font(%info)  # Set
+    @current = $pdf->get_font()  # Get
+
+    $font = $pdf->get_font(%info)  # Set
+
+=over
 
 If no parameters are given (C<@current = $pdf-E<gt>get_font()>), a list
 (array) is returned giving the I<current> font setting: I<face> name, I<italic> 
@@ -780,6 +811,8 @@ value is 0 or 1 for "off" (medium weight) and "on" (heavy weight).
 
 =back
 
+=back
+
 =cut
 
 sub get_font {
@@ -1039,10 +1072,16 @@ sub _filepath {
     return @out_list;
 }
 
-=item $pdf->dump_font_tables()
+=head2 dump_font_tables
+
+    $pdf->dump_font_tables()
+
+=over
 
 Print (to STDOUT) all the Font Manager font information on hand.
 
+=back
+
 =cut
 
 # a debug routine to dump everything about defined fonts
@@ -1121,8 +1160,4 @@ sub dump_font_tables {
     return;
 } # end of dump_font_tables()
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Lite.pm b/lib/PDF/Builder/Lite.pm
index 76ce2fe..379649e 100644
--- a/lib/PDF/Builder/Lite.pm
+++ b/lib/PDF/Builder/Lite.pm
@@ -3,8 +3,8 @@ package PDF::Builder::Lite;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 # NOTE that this sub-package has not been tested and is not well documented!
 #      It is possible that it will be deprecated and removed.
 
@@ -45,11 +45,11 @@ It remains solely for compatibility with existing legacy code.
 
 =head1 METHODS
 
-=over
+=head2 new
 
-=item $pdf = PDF::Builder::Lite->new(%opts)
+    $pdf = PDF::Builder::Lite->new(%opts)
 
-=item $pdf = PDF::Builder::Lite->new()
+    $pdf = PDF::Builder::Lite->new()
 
 =cut
 
@@ -63,14 +63,20 @@ sub new {
     return $self;
 }
 
-=item $pdf->page()
+=head2 page
+
+    $pdf->page()
 
-=item $pdf->page($width,$height)
+    $pdf->page($width,$height)
 
-=item $pdf->page($llx,$lly, $urx,$ury)
+    $pdf->page($llx,$lly, $urx,$ury)
+
+=over
 
 Opens a new page.
 
+=back
+
 =cut
 
 sub page {
@@ -82,12 +88,18 @@ sub page {
     return $self;
 }
 
-=item $pdf->mediabox($w,$h)
+=head2 mediabox
+
+    $pdf->mediabox($w,$h)
 
-=item $pdf->mediabox($llx,$lly, $urx,$ury)
+    $pdf->mediabox($llx,$lly, $urx,$ury)
+
+=over
 
 Sets the global mediabox.
 
+=back
+
 =cut
 
 sub mediabox {
@@ -100,7 +112,11 @@ sub mediabox {
     return $self;
 }
 
-=item $pdf->saveas($file)
+=head2 saveas
+
+    $pdf->saveas($file)
+
+=over
 
 Saves the document (may B<not> be modified later) and
 deallocates the PDF structures.
@@ -108,6 +124,8 @@ deallocates the PDF structures.
 If C<$file> is just a hyphen '-', the stringified copy is returned, otherwise
 the file is saved, and C<$self> is returned (for chaining calls).
 
+=back
+
 =cut
 
 sub saveas {
@@ -133,8 +151,11 @@ sub saveas {
     return;
 }
 
+=head2 corefont
 
-=item $font = $pdf->corefont($fontname)
+    $font = $pdf->corefont($fontname)
+
+=over
 
 Returns a new or existing Adobe core font object.
 
@@ -145,6 +166,8 @@ B<Examples:>
     $font = $pdf->corefont('Helvetica');
     $font = $pdf->corefont('ZapfDingbats');
 
+=back
+
 =cut
 
 sub corefont {
@@ -154,7 +177,11 @@ sub corefont {
     return $obj;
 }
 
-=item $font = $pdf->ttfont($ttfile)
+=head2 ttfont
+
+    $font = $pdf->ttfont($ttfile)
+
+=over
 
 Returns a new or existing TrueType font object.
 
@@ -164,6 +191,8 @@ B<Examples:>
     $font = $pdf->ttfont('/fonts/Univers-Bold.ttf');
     $font = $pdf->ttfont('../Democratica-SmallCaps.ttf');
 
+=back
+
 =cut
 
 sub ttfont {
@@ -172,9 +201,13 @@ sub ttfont {
     return $self->{'api'}->ttfont($file, @opts);
 }
 
-=item $font = $pdf->psfont($ps_file, %options)
+=head2 psfont
+
+    $font = $pdf->psfont($ps_file, %options)
 
-=item $font = $pdf->psfont($ps_file)
+    $font = $pdf->psfont($ps_file)
+
+=over
 
 Returns a new Type1 (PS) font object.
 
@@ -183,6 +216,8 @@ B<Examples:>
     $font = $pdf->psfont('TimesRoman.pfa', 'afmfile' => 'TimesRoman.afm', 'encode' => 'latin1');
     $font = $pdf->psfont('/fonts/Univers.pfb', 'pfmfile' => '/fonts/Univers.pfm', 'encode' => 'latin2');
 
+=back
+
 =cut
 
 sub psfont {
@@ -191,9 +226,13 @@ sub psfont {
     return $self->{'api'}->psfont(@args);
 }
 
-#=item @color = $pdf->color($colornumber [, $lightdark ])
+#=head2 color
 #
-#=item @color = $pdf->color($basecolor [, $lightdark ])
+#    @color = $pdf->color($colornumber [, $lightdark ])
+#
+#    @color = $pdf->color($basecolor [, $lightdark ])
+#
+#=over
 #
 #Returns a color.
 #
@@ -206,6 +245,8 @@ sub psfont {
 #    @color = $pdf->color('red',+1);     # red, +10% white
 #    @color = $pdf->color('green',-2);   # green, +20% black
 #
+#=back
+#
 #=cut
 #
 #sub color {
@@ -214,7 +255,11 @@ sub psfont {
 #    return $self->{'api'}->businesscolor(@_);
 #}
 
-=item $egs = $pdf->create_egs()
+=head2 create_egs
+
+    $egs = $pdf->create_egs()
+
+=over
 
 Returns a new extended-graphics-state object.
 
@@ -222,6 +267,8 @@ B<Examples:>
 
     $egs = $pdf->create_egs();
 
+=back
+
 =cut
 
 sub create_egs {
@@ -230,10 +277,16 @@ sub create_egs {
     return $self->{'api'}->egstate();
 }
 
-=item $img = $pdf->image_jpeg($file)
+=head2 image_jpeg
+
+    $img = $pdf->image_jpeg($file)
+
+=over
 
 Returns a new JPEG image object.
 
+=back
+
 =cut
 
 sub image_jpeg {
@@ -242,10 +295,16 @@ sub image_jpeg {
     return $self->{'api'}->image_jpeg($file);
 }
 
-=item $img = $pdf->image_png($file)
+=head2 image_png
+
+    $img = $pdf->image_png($file)
+
+=over
 
 Returns a new PNG image object.
 
+=back
+
 =cut
 
 sub image_png {
@@ -254,12 +313,18 @@ sub image_png {
     return $self->{'api'}->image_png($file);
 }
 
-=item $img = $pdf->image_tiff($file, %opts)
+=head2 image_tiff
+
+    $img = $pdf->image_tiff($file, %opts)
 
-=item $img = $pdf->image_tiff($file)
+    $img = $pdf->image_tiff($file)
+
+=over
 
 Returns a new TIFF image object.
 
+=back
+
 =cut
 
 sub image_tiff {
@@ -268,10 +333,16 @@ sub image_tiff {
     return $self->{'api'}->image_tiff($file, @opts);
 }
 
-=item $img = $pdf->image_pnm($file)
+=head2 image_pnm
+
+    $img = $pdf->image_pnm($file)
+
+=over
 
 Returns a new PNM image object.
 
+=back
+
 =cut
 
 sub image_pnm {
@@ -280,10 +351,16 @@ sub image_pnm {
     return $self->{'api'}->image_pnm($file);
 }
 
-=item $pdf->savestate()
+=head2 savestate
+
+    $pdf->savestate()
+
+=over
 
 Saves the state of the page.
 
+=back
+
 =cut
 
 sub savestate {
@@ -292,10 +369,16 @@ sub savestate {
     return $self->{'gfx'}->save();
 }
 
-=item $pdf->restorestate()
+=head2 restorestate
+
+    $pdf->restorestate()
+
+=over
 
 Restores the state of the page.
 
+=back
+
 =cut
 
 sub restorestate {
@@ -304,10 +387,16 @@ sub restorestate {
     return $self->{'gfx'}->restore();
 }
 
-=item $pdf->egstate($egs)
+=head2 egstate
+
+    $pdf->egstate($egs)
+
+=over
 
 Sets extended-graphics state.
 
+=back
+
 =cut
 
 sub egstate {
@@ -317,10 +406,16 @@ sub egstate {
     return $self;
 }
 
-=item $pdf->fillcolor($color)
+=head2 fillcolor
+
+    $pdf->fillcolor($color)
+
+=over
 
 Sets the fill color. See C<strokecolor> for color names and specifications.
 
+=back
+
 =cut
 
 sub fillcolor {
@@ -330,7 +425,11 @@ sub fillcolor {
     return $self;
 }
 
-=item $pdf->strokecolor($color)
+=head2 strokecolor
+
+    $pdf->strokecolor($color)
+
+=over
 
 Sets the stroke color.
 
@@ -371,6 +470,8 @@ or the hsv-hex-notation:
 
     !hsv, !hhssvv, !hhhsssvvv and !hhhhssssvvvv
 
+=back
+
 =cut
 
 sub strokecolor {
@@ -380,10 +481,16 @@ sub strokecolor {
     return $self;
 }
 
-=item $pdf->linedash(@dash)
+=head2 linedash
+
+    $pdf->linedash(@dash)
+
+=over
 
 Sets the line dash pattern.
 
+=back
+
 =cut
 
 sub linedash {
@@ -392,10 +499,16 @@ sub linedash {
     return $self;
 }
 
-=item $pdf->linewidth($width)
+=head2 linewidth
+
+    $pdf->linewidth($width)
+
+=over
 
 Sets the line width.
 
+=back
+
 =cut
 
 sub linewidth {
@@ -405,7 +518,11 @@ sub linewidth {
     return $self;
 }
 
-=item $pdf->transform(%opts)
+=head2 transform
+
+    $pdf->transform(%opts)
+
+=over
 
 Sets transformations (i.e., translate, rotate, scale, skew) in PDF-canonical order.
 
@@ -418,6 +535,8 @@ B<Example:>
         'skew'      => [$sa,$sb],
     )
 
+=back
+
 =cut
 
 sub transform {
@@ -427,10 +546,16 @@ sub transform {
     return $self;
 }
 
-=item $pdf->move($x,$y)
+=head2 move
+
+    $pdf->move($x,$y)
+
+=over
 
 Move to a new drawing location at C[$x,$y].
 
+=back
+
 =cut
 
 sub move { # x,y ...
@@ -440,10 +565,16 @@ sub move { # x,y ...
     return $self;
 }
 
-=item $pdf->line($x,$y)
+=head2 line
+
+    $pdf->line($x,$y)
+
+=over
 
 Draw a line to C[$x,$y].
 
+=back
+
 =cut
 
 sub line { # x,y ...
@@ -453,10 +584,16 @@ sub line { # x,y ...
     return $self;
 }
 
-=item $pdf->curve($x1,$y1, $x2,$y2, $x3,$y3)
+=head2 curve
+
+    $pdf->curve($x1,$y1, $x2,$y2, $x3,$y3)
+
+=over
 
 Draw a Bezier curve with three control points.
 
+=back
+
 =cut
 
 sub curve { # x1,y1,x2,y2,x3,y3 ...
@@ -465,15 +602,21 @@ sub curve { # x1,y1,x2,y2,x3,y3 ...
     return $self;
 }
 
-=item $pdf->arc($xc,$yc, $rx,$ry, $alpha,$beta, $move, $dir)
+=head2 arc
 
-=item $pdf->arc($xc,$yc, $rx,$ry, $alpha,$beta, $move)
+    $pdf->arc($xc,$yc, $rx,$ry, $alpha,$beta, $move, $dir)
+
+    $pdf->arc($xc,$yc, $rx,$ry, $alpha,$beta, $move)
+
+=over
 
 Draw an arc centered at C[$xc,$yc], with x radius C[$rx] and y radius C[$ry],
 from C[$alpha] degrees to C[$beta] degrees. If C[$move] is I<true>, do B<not>
 draw a line to the start of the arc. C[$dir] defaults to 0 for counter-clockwise
 sweep, and may be set to 1 for a clockwise sweep.
 
+=back
+
 =cut
 
 sub arc { # xc,yc, rx,ry, alpha,beta ,move [,dir]
@@ -483,10 +626,16 @@ sub arc { # xc,yc, rx,ry, alpha,beta ,move [,dir]
     return $self;
 }
 
-=item $pdf->ellipse($xc,$yc, $rx,$ry)
+=head2 ellipse
+
+    $pdf->ellipse($xc,$yc, $rx,$ry)
+
+=over
 
 Draw an ellipse centered at C[$xc,$yc], with x radius C[$rx] and y radius C[$ry].
 
+=back
+
 =cut
 
 sub ellipse {
@@ -496,10 +645,16 @@ sub ellipse {
     return $self;
 }
 
-=item $pdf->circle($xc,$yc, $r)
+=head2 circle
+
+    $pdf->circle($xc,$yc, $r)
+
+=over
 
 Draw a circle centered at C[$xc,$yc], of radius C[$r].
 
+=back
+
 =cut
 
 sub circle {
@@ -509,11 +664,17 @@ sub circle {
     return $self;
 }
 
-=item $pdf->rect($x,$y, $w,$h)
+=head2 rect
+
+    $pdf->rect($x,$y, $w,$h)
+
+=over
 
 Draw a rectangle with lower left corner at C[$x,$y], width (+x) C[$w] and
 height (+y) C[$h].
 
+=back
+
 =cut
 
 sub rect { # x,y, w,h ...
@@ -523,10 +684,16 @@ sub rect { # x,y, w,h ...
     return $self;
 }
 
-=item $pdf->rectxy($x1,$y1, $x2,$y2)
+=head2 rectxy
+
+    $pdf->rectxy($x1,$y1, $x2,$y2)
+
+=over
 
 Draw a rectangle with opposite corners C[$x1,$y1] and C[$x2,$y2].
 
+=back
+
 =cut
 
 sub rectxy {
@@ -536,11 +703,17 @@ sub rectxy {
     return $self;
 }
 
-=item $pdf->poly($x1,$y1, ..., $xn,$yn)
+=head2 poly
+
+    $pdf->poly($x1,$y1, ..., $xn,$yn)
+
+=over
 
 Draw a polyline (multiple line segments) starting at (I<move> to) C[$x1,$y1] and
 continuing on to C[$x2,$y2], ..., C[$xn,$yn].
 
+=back
+
 =cut
 
 sub poly {
@@ -550,10 +723,16 @@ sub poly {
     return $self;
 }
 
-=item $pdf->close()
+=head2 close
+
+    $pdf->close()
+
+=over
 
 Close a shape (draw a line back to the beginning).
 
+=back
+
 =cut
 
 sub close {
@@ -563,11 +742,17 @@ sub close {
     return $self;
 }
 
-=item $pdf->stroke()
+=head2 stroke
+
+    $pdf->stroke()
+
+=over
 
 Stroke (actually draw) a shape whose path has already been laid out, using
 the requested C<strokecolor>.
 
+=back
+
 =cut
 
 sub stroke {
@@ -577,11 +762,17 @@ sub stroke {
     return $self;
 }
 
-=item $pdf->fill()
+=head2 fill
+
+    $pdf->fill()
+
+=over
 
 Fill in a closed geometry (path), using the requested C<fillcolor>.
 The I<non-zero winding rule> is used if the path crosses itself.
 
+=back
+
 =cut
 
 sub fill { # nonzero winding rule
@@ -591,11 +782,17 @@ sub fill { # nonzero winding rule
     return $self;
 }
 
-=item $pdf->fillstroke()
+=head2 fillstroke
+
+    $pdf->fillstroke()
+
+=over
 
 Fill (using C<fillcolor>) I<and> stroke (using C<strokecolor>) a closed path.
 The I<non-zero winding rule> is used if the path crosses itself.
 
+=back
+
 =cut
 
 sub fillstroke { # nonzero winding rule
@@ -605,11 +802,15 @@ sub fillstroke { # nonzero winding rule
     return $self;
 }
 
-=item $pdf->image($imgobj, $x,$y, $w,$h)
+=head2 image
+
+    $pdf->image($imgobj, $x,$y, $w,$h)
 
-=item $pdf->image($imgobj, $x,$y, $scale)
+    $pdf->image($imgobj, $x,$y, $scale)
 
-=item $pdf->image($imgobj, $x,$y)
+    $pdf->image($imgobj, $x,$y)
+
+=over
 
 B<Please Note:> The width/height or scale given
 is in user-space coordinates, which are subject to
@@ -619,6 +820,8 @@ Per default this has a 72dpi resolution, so if you want an
 image to have a 150 or 300dpi resolution, you should specify
 a scale of 72/150 (or 72/300) or adjust width/height accordingly.
 
+=back
+
 =cut
 
 sub image {
@@ -628,10 +831,16 @@ sub image {
     return $self;
 }
 
-=item $pdf->textstart()
+=head2 textstart
+
+    $pdf->textstart()
+
+=over
 
 Forces the start of text mode while in graphics.
 
+=back
+
 =cut
 
 sub textstart {
@@ -641,10 +850,16 @@ sub textstart {
     return $self;
 }
 
-=item $pdf->textfont($fontobj, $size)
+=head2 textfont
+
+    $pdf->textfont($fontobj, $size)
+
+=over
 
 Define the current font to be an (already defined) font object at the given size.
 
+=back
+
 =cut
 
 sub textfont {
@@ -654,23 +869,18 @@ sub textfont {
     return $self;
 }
 
-=item $txt->textleading($leading)
+=head2 textleading
 
-Set the baseline-to-baseline "leading" to be used for text lines.
+    $txt->textleading($leading)
 
-=item $txt->textlead($leading)
+=over
 
 Set the baseline-to-baseline "leading" to be used for text lines.
 
-B<Deprecated,> will be removed March 2023 or later. Use textleading().
+=back
 
 =cut
 
-# remove on or after March 2023
-sub textlead {
-    return $_[0]->textleading($_[1]);
-}
-
 sub textleading {
     my $self = shift();
 
@@ -678,11 +888,17 @@ sub textleading {
     return $self;
 }
 
-=item $pdf->text($string)
+=head2 text
+
+    $pdf->text($string)
+
+=over
 
 Applies (writes out) the given text at the current text location, using the
 already-specified font.
 
+=back
+
 =cut
 
 sub text {
@@ -691,10 +907,16 @@ sub text {
     return $self->{'gfx'}->text(@_) || $self;
 }
 
-=item $pdf->nl()
+=head2 nl
+
+    $pdf->nl()
+
+=over
 
 Write a newline (drop down to the next line).
 
+=back
+
 =cut
 
 sub nl {
@@ -704,10 +926,16 @@ sub nl {
     return $self;
 }
 
-=item $pdf->textend()
+=head2 textend
+
+    $pdf->textend()
+
+=over
 
 Force an end to text output and return to graphics.
 
+=back
+
 =cut
 
 sub textend {
@@ -717,7 +945,11 @@ sub textend {
     return $self;
 }
 
-=item $pdf->print($font, $size, $x,$y, $rot, $just, $text)
+=head2 print
+
+    $pdf->print($font, $size, $x,$y, $rot, $just, $text)
+
+=over
 
 Convenience wrapper for shortening the textstart..textend sequence.
 
@@ -725,6 +957,8 @@ Go into text mode, set the font to the object and size, go to the location,
 set any rotation, set justification, and write the array of text.
 Justification is 0 for left, 1 for center, and 2 for right.
 
+=back
+
 =cut
 
 sub print {
@@ -753,8 +987,6 @@ sub print {
 
 __END__
 
-=back
-
 =head1 AUTHOR
 
 This module was originally written by Alfred Reibenschuh. It has had some
diff --git a/lib/PDF/Builder/Matrix.pm b/lib/PDF/Builder/Matrix.pm
index 12f5fe3..e97a2ad 100644
--- a/lib/PDF/Builder/Matrix.pm
+++ b/lib/PDF/Builder/Matrix.pm
@@ -13,7 +13,7 @@ use strict;
 use warnings;
 use Carp;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.020'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/NamedDestination.pm b/lib/PDF/Builder/NamedDestination.pm
index c7188ae..ad9f039 100644
--- a/lib/PDF/Builder/NamedDestination.pm
+++ b/lib/PDF/Builder/NamedDestination.pm
@@ -8,8 +8,8 @@ use warnings;
 use Carp;
 use Encode qw(:all);
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 # TBD: do rect and border apply to Named Destinations (link, url, file)? 
 #      There is nothing to implement these options. Perhaps the code was copied 
@@ -25,19 +25,17 @@ PDF::Builder::NamedDestination - Add named destinations (views) to a PDF
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    $dest = PDF::Builder::NamedDestination->new($pdf, ...)
 
-=item $dest = PDF::Builder::NamedDestination->new($pdf, ...)
+=over
 
 Creates a new named destination object. Any optional additional arguments
 will be passed on to C<destination>.
 
 =back
 
-=head2 Destination types
-
-=over
-
 =cut
 
 sub new {
@@ -67,7 +65,13 @@ sub new_api {
     return $destination;
 }
 
-=item $dest->dest($page, %opts)
+=head2 Destination types
+
+=head3 dest
+
+    $dest->dest($page, %opts)
+
+=over
 
 A destination (dest) is a particular view of a PDF, consisting of a page 
 object, the
@@ -155,11 +159,17 @@ sub dest {
     return $self;
 }
 
+# These targets are similar to what is given in Annotations, and are used to
+# provide an Action when the externally visible name is given to the PDF Reader
+# (see Named Destination issue #202 for #nameddest= ).
+
 =head2 Target Destinations
 
-=over
+=head3 link, goto
 
-=item $dest->link($page, %opts)
+    $dest->link($page, %opts)
+
+=over
 
 A go-to (link) action changes the view to a specified destination (page, 
 location, and magnification factor).
@@ -171,6 +181,8 @@ B<Alternate name:> C<goto>
 Originally this method was C<link>, but recently PDF::API2 changed the name
 to C<goto>. "goto" is added for compatibility.
 
+=back
+
 =cut
 
 sub link { 
@@ -185,7 +197,11 @@ sub goto {
     return $self->dest(@_);
 }
 
-=item $dest->uri($url)
+=head3 uri, url
+
+    $dest->uri($url)
+
+=over
 
 Defines the destination as launch-url with uri C<$url>.
 
@@ -194,6 +210,8 @@ B<Alternate name:> C<url>
 Originally this method was C<url>, but recently PDF::API2 changed the name
 to C<uri>. "url" is retained for compatibility.
 
+=back
+
 =cut
 
 sub url { return uri(@_); } ## no critic
@@ -208,7 +226,11 @@ sub uri {
     return $self;
 }
 
-=item $dest->launch($file)
+=head3 launch, file
+
+    $dest->launch($file)
+
+=over
 
 Defines the destination as launch-file with filepath C<$file> and
 page-fit options %opts. The target application is run. Note that this is
@@ -219,6 +241,8 @@ B<Alternate name:> C<file>
 Originally this method was C<file>, but recently PDF::API2 changed the name
 to C<launch>. "file" is retained for compatibility.
 
+=back
+
 =cut
 
 sub file { return launch(@_); } ## no critic
@@ -233,7 +257,11 @@ sub launch {
     return $self;
 }
 
-=item $dest->pdf($pdf_file, $pagenum, %opts)
+=head3 pdf, pdf_file, pdfile
+
+    $dest->pdf($pdf_file, $pagenum, %opts)
+
+=over
 
 Defines the destination as a PDF-file with filepath C<$pdf_file>, on page
 C<$pagenum>, and options %opts (same as dest()).
@@ -246,6 +274,8 @@ C<pdf_file>, but recently PDF::API2 changed the name to C<pdf>. "pdfile" and
 information is still given as a hash element in PDF::Builder, while PDF::API2
 has changed to a position string and an array of dimensions.
 
+=back
+
 =cut
 
 sub pdf_file { return pdf(@_); } ## no critic
@@ -263,8 +293,4 @@ sub pdf{
     return $self;
 }
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Outline.pm b/lib/PDF/Builder/Outline.pm
index 61339b7..8e5e5a8 100644
--- a/lib/PDF/Builder/Outline.pm
+++ b/lib/PDF/Builder/Outline.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Basic::PDF::Dict';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use Carp qw(croak);
 use PDF::Builder::Basic::PDF::Utils;
@@ -28,12 +28,16 @@ PDF::Builder::Outline - Manage PDF outlines (a.k.a. I<bookmarks>)
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    $outline = PDF::Builder::Outline->new($api, $parent, $prev)
 
-=item $outline = PDF::Builder::Outline->new($api, $parent, $prev)
+=over
 
 Returns a new outline object (called from $outlines->outline()).
 
+=back
+
 =cut
 
 sub new {
@@ -50,16 +54,18 @@ sub new {
     return $self;
 }
 
-=back
-
 =head2 Examine the Outline Tree
 
-=over
+=head3 has_children
+
+    $boolean = $outline->has_children()
 
-=item $boolean = $outline->has_children()
+=over
 
 Return true if the current outline item has children (child items).
 
+=back
+
 =cut
 
 sub has_children {
@@ -74,11 +80,17 @@ sub has_children {
     return;
 }
 
-=item $integer = $outline->count()
+=head3 count
+
+    $integer = $outline->count()
+
+=over
 
 Return the number of descendants that are visible when the current outline item
 is open (expanded).
 
+=back
+
 =cut
 
 sub count {
@@ -129,10 +141,16 @@ sub _load_children {
     return $self;
 }
 
-=item $child = $outline->first()
+=head3 first
+
+    $child = $outline->first()
+
+=over
 
 Return the first child of the current outline level, if one exists.
 
+=back
+
 =cut
 
 sub first {
@@ -144,10 +162,16 @@ sub first {
     return $self->{'First'};
 }
 
-=item $child = $outline->last()
+=head3 last
+
+    $child = $outline->last()
+
+=over
 
 Return the last child of the current outline level, if one exists.
 
+=back
+
 =cut
 
 sub last {
@@ -159,11 +183,17 @@ sub last {
     return $self->{'Last'};
 }
 
-=item $parent = $outline->parent()
+=head3 parent
+
+    $parent = $outline->parent()
+
+=over
 
 Return the parent of the current item, if not at the top level of the outline
 tree.
 
+=back
+
 =cut
 
 sub parent {
@@ -173,10 +203,16 @@ sub parent {
     return $self->{'Parent'};
 }
 
-=item $sibling = $outline->prev()
+=head3 prev
+
+    $sibling = $outline->prev()
+
+=over
 
 Return the previous item of the current level of the outline tree.
 
+=back
+
 =cut
 
 sub prev {
@@ -186,10 +222,16 @@ sub prev {
     return $self->{'Prev'};
 }
 
-=item $sibling = $outline->next()
+=head3 next
+
+    $sibling = $outline->next()
+
+=over
 
 Return the next item of the current level of the outline tree.
 
+=back
+
 =cut
 
 sub next {
@@ -199,17 +241,19 @@ sub next {
     return $self->{'Next'};
 }
 
-=back
-
 =head2 Modify the Outline Tree
 
-=over 
+=head3 outline
 
-=item $child_outline = $parent_outline->outline()
+    $child_outline = $parent_outline->outline()
+
+=over
 
 Returns a new sub-outline (nested outline) added at the end of the
 current outline's children.
 
+=back
+
 =cut
 
 sub outline {
@@ -228,10 +272,16 @@ sub outline {
     return $child;
 }
 
-=item $sibling = $outline->insert_after()
+=head3 insert_after
+
+    $sibling = $outline->insert_after()
+
+=over
 
 Add an outline item immediately following the current item.
 
+=back
+
 =cut
 
 sub insert_after {
@@ -249,10 +299,16 @@ sub insert_after {
     return $sibling;
 }
 
-=item $sibling = $outline->insert_before()
+=head3 insert_before
+
+    $sibling = $outline->insert_before()
+
+=over
 
 Add an outline item immediately preceding the current item.
 
+=back
+
 =cut
 
 sub insert_before {
@@ -284,12 +340,18 @@ sub _reset_children {
     return $self;
 }
 
-=item $outline->delete()
+=head3 delete
+
+    $outline->delete()
+
+=over
 
 Remove the current outline item from the outline tree. If the item has any
 children, they will effectively be deleted as well, since they will no longer 
 be linked.
 
+=back
+
 =cut
 
 sub delete {
@@ -307,12 +369,18 @@ sub delete {
     return;
 }
 
-=item $boolean = $outline->is_open() # Get
+=head3 is_open
 
-=item $outline = $outline->is_open($boolean) # Set
+    $boolean = $outline->is_open() # Get
+
+    $outline = $outline->is_open($boolean) # Set
+
+=over
 
 Get/set whether the outline is expanded (open) or collapsed (closed).
 
+=back
+
 =cut
 
 sub is_open {
@@ -337,12 +405,18 @@ sub is_open {
     return $self;
 }
 
-=item $outline->open()
+=head3 open
+
+    $outline->open()
+
+=over
 
 Set the status of the outline to open (i.e., expanded).
 
 This is an B<alternate> method to using is_open(true).
 
+=back
+
 =cut
 
 # deprecated in API2
@@ -352,12 +426,18 @@ sub open {
     return $self;
 }
 
-=item $outline->closed()
+=head3 closed
+
+    $outline->closed()
+
+=over
 
 Set the status of the outline to closed (i.e., collapsed).
 
 This is an B<alternate> method to using is_open(false).
 
+=back
+
 =cut
 
 # deprecated in API2
@@ -367,18 +447,20 @@ sub closed {
     return $self;
 }
 
-=back
-
 =head2 Set Outline Attributes
 
-=over
+=head3 title
 
-=item $title = $outline->title() # Get
+    $title = $outline->title() # Get
 
-=item $outline = $outline->title($text) # Set
+    $outline = $outline->title($text) # Set
+
+=over
 
 Get/set the title of the outline item.
 
+=back
+
 =cut
 
 sub title {
@@ -396,9 +478,13 @@ sub title {
     return $self;
 }
 
-=item $outline->dest($page_object, %position)
+=head3 dest
+
+    $outline->dest($page_object, %position)
 
-=item $outline->dest($page_object)
+    $outline->dest($page_object)
+
+=over
 
 Sets the destination page and optional position of the outline.
 
@@ -407,13 +493,15 @@ Sets the destination page and optional position of the outline.
 "xyz" is the B<default> fit setting, with position (left and top) and zoom
 the same as the calling page's.
 
-=item $outline->dest($name, %position)
+    $outline->dest($name, %position)
 
-=item $outline->dest($name)
+    $outline->dest($name)
 
 Connect the Outline to a "Named Destination" defined elsewhere,
 and optional positioning as described above.
 
+=back
+
 =cut
 
 sub dest {
@@ -470,13 +558,13 @@ sub _fit {
     return $self;
 }
 
-=back
-
 =head2 Destination targets
 
-=over
+=head3 uri, url
 
-=item $outline->uri($url)
+    $outline->uri($url)
+
+=over
 
 Defines the outline as launch-url with url C<$url>, typically a web page.
 
@@ -484,6 +572,8 @@ B<Alternate name:> C<url>
 
 Either C<uri> or C<url> may be used; C<uri> is for compatibility with PDF::API2.
 
+=back
+
 =cut
 
 sub url { return uri(@_); }  # alternate name
@@ -500,7 +590,11 @@ sub uri {
     return $self;
 }
 
-=item $outline->launch($file)
+=head3 launch, file
+
+    $outline->launch($file)
+
+=over
 
 Defines the outline as launch-file with filepath C<$file>. This is typically
 a local application or file.
@@ -509,6 +603,8 @@ B<Alternate name:> C<file>
 
 Either C<launch> or C<file> may be used; C<launch> is for compatibility with PDF::API2.
 
+=back
+
 =cut
 
 sub file { return launch(@_); } # alternate name
@@ -525,9 +621,13 @@ sub launch {
     return $self;
 }
 
-=item $outline->pdf($pdffile, $page_number, %position, %args)
+=head3 pdf, pdf_file, pdfile
 
-=item $outline->pdf($pdffile, $page_number)
+    $outline->pdf($pdffile, $page_number, %position, %args)
+
+    $outline->pdf($pdffile, $page_number)
+
+=over
 
 Defines the destination of the outline as a PDF-file with filepath 
 C<$pdffile>, on page C<$pagenum> (default 0), and position C<%position> 
@@ -538,6 +638,8 @@ B<Alternate names:> C<pdf_file> and C<pdfile>
 Either C<pdf> or C<pdf_file> (or the older C<pdfile>) may be used; C<pdf> is 
 for compatibility with PDF::API2. 
 
+=back
+
 =cut
 
 sub pdf_file { return pdf(@_); } # alternative method
@@ -591,8 +693,4 @@ sub outobjdeep {
     return $self->SUPER::outobjdeep(@_);
 }
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Outlines.pm b/lib/PDF/Builder/Outlines.pm
index bb3cd52..0abd9c7 100644
--- a/lib/PDF/Builder/Outlines.pm
+++ b/lib/PDF/Builder/Outlines.pm
@@ -5,7 +5,7 @@ use base 'PDF::Builder::Outline';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
 
 use PDF::Builder::Basic::PDF::Utils;
diff --git a/lib/PDF/Builder/Page.pm b/lib/PDF/Builder/Page.pm
index 568fbe6..351744b 100644
--- a/lib/PDF/Builder/Page.pm
+++ b/lib/PDF/Builder/Page.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Basic::PDF::Pages';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.025'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use Carp;
 use POSIX qw(floor);
@@ -55,12 +55,16 @@ PDF::Builder::Page - Methods to interact with individual pages
     
 =head1 METHODS
 
-=over
+=head2 new
+
+    $page = PDF::Builder::Page->new($pdf, $parent, $index)
 
-=item $page = PDF::Builder::Page->new($pdf, $parent, $index)
+=over
 
 Returns a page object (called from $pdf->page()).
 
+=back
+
 =cut
 
 sub new {
@@ -94,10 +98,16 @@ sub new {
     return $self;
 }
 
-#=item $page = PDF::Builder::Page->coerce($pdf, $pdfpage)
+#=head2 coerce
+#
+#    $page = PDF::Builder::Page->coerce($pdf, $pdfpage)
+#
+#=over
 #
 #Returns a page object converted from $pdfpage (called from $pdf->open_page()).
 #
+#=back
+#
 #=cut
 
 # appears to be unused TBD
@@ -111,10 +121,16 @@ sub coerce {
     return $self;
 }
 
-#=item $page->update()
+#=head2 update
+#
+#    $page->update()
+#
+#=over
 #
 #Marks a page to be updated (by $pdf->update()).
 #
+#=back
+#
 #=cut
 
 # appears to be internal routine
@@ -133,17 +149,19 @@ sub update {
     return $self;
 }
 
-=back
-
 =head2 Page Size Methods
 
-=over
+=head3 userunit
+
+    $page->userunit($value)
 
-=item $page->userunit($value)
+=over
 
 Sets the User Unit for this one page.  
 See L<PDF::Builder::Docs/User Units> for more information.
 
+=back
+
 =cut
 
 sub userunit {
@@ -235,183 +253,247 @@ sub _bbox {
     return @corners;
 }
 
-=item $page->mediabox($alias)
+=head3 mediabox
+
+    $page->mediabox($alias)
 
-=item $page->mediabox($alias, 'orient' => 'orientation')
+    $page->mediabox($alias, 'orient' => 'orientation')
 
-=item $page->mediabox($w,$h)
+    $page->mediabox($w,$h)
 
-=item $page->mediabox($llx,$lly, $urx,$ury)
+    $page->mediabox($llx,$lly, $urx,$ury)
 
-=item ($llx,$lly, $urx,$ury) = $page->mediabox()
+    ($llx,$lly, $urx,$ury) = $page->mediabox()
+
+=over
 
 Sets or gets the Media Box for this one page.  
 See L<PDF::Builder::Docs/Media Box> for more information.
 The method always returns the current bounds (after any set operation).
 
+=back
+
 =cut
 
 sub mediabox {
     return _bbox('MediaBox', @_);
 }
 
-=item ($llx,$lly, $urx,$ury) = $page->get_mediabox()
+=head4 get_mediabox
+
+    ($llx,$lly, $urx,$ury) = $page->get_mediabox()
+
+=over
 
 Gets the Media Box corner coordinates based on best estimates or the default.
 These are in the order given in a mediabox call (4 coordinates).
 
-This method is B<Deprecated>, and will likely be removed in the future. Use
+This method is B<Deprecated>, and has been B<removed>. Use
 the global (C<$pdf>) or page (C<$page>) mediabox() call with no parameters
 instead.
 
+=back
+
 =cut
 
-sub get_mediabox {
-    my $self = shift();
-    return $self->mediabox();
-}
+#sub get_mediabox {
+#    my $self = shift();
+#    return $self->mediabox();
+#}
+
+=head3 cropbox
+
+    $page->cropbox($alias)
 
-=item $page->cropbox($alias)
+    $page->cropbox($alias, 'orient' => 'orientation')
 
-=item $page->cropbox($alias, 'orient' => 'orientation')
+    $page->cropbox($w,$h)
 
-=item $page->cropbox($w,$h)
+    $page->cropbox($llx,$lly, $urx,$ury)
 
-=item $page->cropbox($llx,$lly, $urx,$ury)
+    ($llx,$lly, $urx,$ury) = $page->cropbox()
 
-=item ($llx,$lly, $urx,$ury) = $page->cropbox()
+=over
 
 Sets or gets the Crop Box for this one page.  
 See L<PDF::Builder::Docs/Crop Box> for more information.
 The method always returns the current bounds (after any set operation).
 
+=back
+
 =cut
 
 sub cropbox {
     return _bbox('CropBox', @_);
 }
 
-=item ($llx,$lly, $urx,$ury) = $page->get_cropbox()
+=head4 get_cropbox
+
+    ($llx,$lly, $urx,$ury) = $page->get_cropbox()
+
+=over
 
 Gets the Crop Box based on best estimates or the default.
 
-This method is B<Deprecated>, and will likely be removed in the future. Use
+This method is B<Deprecated>, and has been B<removed>. Use
 the global (C<$pdf>) or page (C<$page>) cropbox() call with no parameters
 instead.
 
+=back
+
 =cut
 
-sub get_cropbox {
-    my $self = shift();
-    return $self->cropbox();
-}
+#sub get_cropbox {
+#    my $self = shift();
+#    return $self->cropbox();
+#}
+
+=head3 bleedbox
+
+    $page->bleedbox($alias)
 
-=item $page->bleedbox($alias)
+    $page->bleedbox($alias, 'orient' => 'orientation')
 
-=item $page->bleedbox($alias, 'orient' => 'orientation')
+    $page->bleedbox($w,$h)
 
-=item $page->bleedbox($w,$h)
+    $page->bleedbox($llx,$lly, $urx,$ury)
 
-=item $page->bleedbox($llx,$lly, $urx,$ury)
+    ($llx,$lly, $urx,$ury) = $page->bleedbox()
 
-=item ($llx,$lly, $urx,$ury) = $page->bleedbox()
+=over
 
 Sets or gets or gets the Bleed Box for this one page.  
 See L<PDF::Builder::Docs/Bleed Box> for more information.
 The method always returns the current bounds (after any set operation).
 
+=back
+
 =cut
 
 sub bleedbox {
     return _bbox('BleedBox', @_);
 }
 
-=item ($llx,$lly, $urx,$ury) = $page->get_bleedbox()
+=head4 get_bleedbox
+
+    ($llx,$lly, $urx,$ury) = $page->get_bleedbox()
+
+=over
 
 Gets the Bleed Box based on best estimates or the default.
 
-This method is B<Deprecated>, and will likely be removed in the future. Use
+This method is B<Deprecated>, and has been B<removed>. Use
 the global (C<$pdf>) or page (C<$page>) bleedbox() call with no parameters
 instead.
 
+=back
+
 =cut
 
-sub get_bleedbox {
-    my $self = shift();
-    return $self->bleedbox();
-}
+#sub get_bleedbox {
+#    my $self = shift();
+#    return $self->bleedbox();
+#}
+
+=head3 trimbox
 
-=item $page->trimbox($alias)
+    $page->trimbox($alias)
 
-=item $page->trimbox($alias, 'orient' => 'orientation')
+    $page->trimbox($alias, 'orient' => 'orientation')
 
-=item $page->trimbox($w,$h)
+    $page->trimbox($w,$h)
 
-=item $page->trimbox($llx,$lly, $urx,$ury)
+    $page->trimbox($llx,$lly, $urx,$ury)
 
-=item ($llx,$lly, $urx,$ury) = $page->trimbox()
+    ($llx,$lly, $urx,$ury) = $page->trimbox()
+
+=over
 
 Sets or gets the Trim Box for this one page.  
 See L<PDF::Builder::Docs/Trim Box> for more information.
 The method always returns the current bounds (after any set operation).
 
+=back
+
 =cut
 
 sub trimbox {
     return _bbox('TrimBox', @_);
 }
 
-=item ($llx,$lly, $urx,$ury) = $page->get_trimbox()
+=head4 get_trimbox
+
+    ($llx,$lly, $urx,$ury) = $page->get_trimbox()
+
+=over
 
 Gets the Trim Box based on best estimates or the default.
 
-This method is B<Deprecated>, and will likely be removed in the future. Use
+This method is B<Deprecated>, and has been B<removed>. Use
 the global (C<$pdf>) or page (C<$page>) trimbox() call with no parameters
 instead.
 
+=back
+
 =cut
 
-sub get_trimbox {
-    my $self = shift();
-    return $self->trimbox();
-}
+#sub get_trimbox {
+#    my $self = shift();
+#    return $self->trimbox();
+#}
+
+=head3 artbox
 
-=item $page->artbox($alias)
+    $page->artbox($alias)
 
-=item $page->artbox($alias, 'orient' => 'orientation')
+    $page->artbox($alias, 'orient' => 'orientation')
 
-=item $page->artbox($w,$h)
+    $page->artbox($w,$h)
 
-=item $page->artbox($llx,$lly, $urx,$ury)
+    $page->artbox($llx,$lly, $urx,$ury)
 
-=item ($llx,$lly, $urx,$ury) = $page->artbox()
+    ($llx,$lly, $urx,$ury) = $page->artbox()
+
+=over
 
 Sets or gets the Art Box for this one page.  
 See L<PDF::Builder::Docs/Art Box> for more information.
 The method always returns the current bounds (after any set operation).
 
+=back
+
 =cut
 
 sub artbox {
     return _bbox('ArtBox', @_);
 }
 
-=item ($llx,$lly, $urx,$ury) = $page->get_artbox()
+=head4 get_artbox
+
+    ($llx,$lly, $urx,$ury) = $page->get_artbox()
+
+=over
 
 Gets the Art Box based on best estimates or the default.
 
-This method is B<Deprecated>, and will likely be removed in the future. Use
+This method is B<Deprecated>, and has been B<removed>. Use
 the global (C<$pdf>) or page (C<$page>) artbox() call with no parameters
 instead.
 
+=back
+
 =cut
 
-sub get_artbox {
-    my $self = shift();
-    return $self->artbox();
-}
+#sub get_artbox {
+#    my $self = shift();
+#    return $self->artbox();
+#}
 
-=item $page->rotate($deg)
+=head3 rotate, rotation
+
+    $page->rotate($deg)
+
+=over
 
 Rotates the page by the given degrees, which must be a multiple of 90.
 An angle that is not a multiple of 90 will be rounded to the nearest 90 
@@ -442,6 +524,8 @@ B<Alternate name:> C<rotation>
 
 This has been added for PDF::API2 compatibility.
 
+=back
+
 =cut
 
 sub rotation { return rotate(@_); } ## no critic
@@ -464,9 +548,13 @@ sub rotate {
     return $self;
 }
 
-=item $page->size($size)  # Set
+=head3 size
+
+    $page->size($size)  # Set
 
-=item @rectangle = $page->size()  # Get
+    @rectangle = $page->size()  # Get
+
+=over
 
 Set the physical page size or return the coordinates of the rectangle enclosing
 the physical page size.
@@ -492,6 +580,8 @@ to the following:
     # Get
     @rectangle = $page->boundaries()->{'media'}->@*;
 
+=back
+
 =cut
    
 sub size {
@@ -505,9 +595,13 @@ sub size {
     }
 }
 
-=item $page = $page->boundaries(%boundaries)
+=head3 boundaries
+
+    $page = $page->boundaries(%boundaries)
+
+    \%boundaries = $page->boundaries()
 
-=item \%boundaries = $page->boundaries()
+=over
 
 Set prepress page boundaries to facilitate printing. Returns the current page 
 boundaries if called without arguments.
@@ -647,6 +741,8 @@ directly as an array.
 Finally, the absolute (raw) coordinates of the bottom-left and top-right corners
 of a rectangle can be specified.
 
+=back
+
 =cut
 
 sub _to_rectangle {
@@ -817,11 +913,15 @@ sub precontent {
     return;
 }
 
-=item $gfx = $page->gfx(%opts)
+=head3 gfx, graphics
+
+    $gfx = $page->gfx(%opts)
 
-=item $gfx = $page->gfx($prepend)
+    $gfx = $page->gfx($prepend)
 
-=item $gfx = $page->gfx()
+    $gfx = $page->gfx()
+
+=over
 
 Returns a graphics content object, for drawing paths and shapes. 
 
@@ -880,25 +980,23 @@ at the first call to each object, so that you are starting from a known base.
 This may most easily be done by using $I<type>->restore() and ->save() just
 after creating $I<type>:
 
-=over
-
- $text1 = $page->text(); 
-   $text1->save();
- $grfx1 = $page->gfx();
-   $grfx1->restore();
-   $grfx1->save();
- $text2 = $page->text();
-   $text2->restore();
-   $text2->save();
- $grfx2 = $page->gfx();
-   $grfx1->restore();
-
-=back
+    $text1 = $page->text(); 
+      $text1->save();
+    $grfx1 = $page->gfx();
+      $grfx1->restore();
+      $grfx1->save();
+    $text2 = $page->text();
+      $text2->restore();
+      $text2->save();
+    $grfx2 = $page->gfx();
+      $grfx1->restore();
 
 B<Alternate name:> C<graphics>
 
 This has been added for PDF::API2 compatibility.
 
+=back
+
 =cut
 
 sub graphics { return gfx(@_); } ## no critic
@@ -927,8 +1025,8 @@ sub gfx {
 	if (defined $hash{'compress'}) { $compress = $hash{'compress'}; }
     }
     if ($prepend) { $prepend = 1; }
-    $compress //= $self->{' api'}->{'forcecompress'} eq 'flate' ||
-                  $self->{' api'}->{'forcecompress'} =~ m/^[1-9]\d*$/;
+    if ($self->{' api'}->{'forcecompress'} eq 'flate' ||
+        $self->{' api'}->{'forcecompress'} =~ m/^[1-9]\d*$/) { $compress = 1; }
 
     my $gfx = PDF::Builder::Content->new();
     $gfx->compressFlate() if $compress;
@@ -937,11 +1035,15 @@ sub gfx {
     return $gfx;
 }
 
-=item $text = $page->text(%opts)
+=head3 text
+
+    $text = $page->text(%opts)
 
-=item $text = $page->text($prepend)
+    $text = $page->text($prepend)
 
-=item $text = $page->text()
+    $text = $page->text()
+
+=over
 
 Returns a text content object, for writing text.
 See L<PDF::Builder::Content> for details.
@@ -984,6 +1086,8 @@ with graphics (I<gfx>), such as strokecolor, fillcolor, linewidth, linedash,
 and the like. Thus there is some overlap in attributes, and graphics and text
 calls can affect each other.
 
+=back
+
 =cut
 
 sub text {
@@ -1010,8 +1114,8 @@ sub text {
 	if (defined $hash{'compress'}) { $compress = $hash{'compress'}; }
     }
     if ($prepend) { $prepend = 1; }
-    $compress //= $self->{' api'}->{'forcecompress'} eq 'flate' ||
-                  $self->{' api'}->{'forcecompress'} =~ m/^[1-9]\d*$/;
+    if ($self->{' api'}->{'forcecompress'} eq 'flate' ||
+        $self->{' api'}->{'forcecompress'} =~ m/^[1-9]\d*$/) { $compress = 1; }
 
     my $text = PDF::Builder::Content::Text->new();
     $text->compressFlate() if $compress;
@@ -1020,11 +1124,17 @@ sub text {
     return $text;
 }
 
-=item $page = $page->object($object, $x,$y, $scale_x,$scale_y)
+=head3 object
+
+    $page = $page->object($object, $x,$y, $scale_x,$scale_y)
+
+=over
 
 Places an image or other external object (a.k.a. XObject) on the page in the
 specified location.
 
+If C<$x> and C<$y> are omitted, the object will be placed at C<[0, 0]>.
+
 For images, C<$scale_x> and C<$scale_y> represent the width and height of the
 image on the page in points.  If C<$scale_x> is omitted, it will default to 72
 pixels per inch.  If C<$scale_y> is omitted, the image will be scaled
@@ -1037,6 +1147,8 @@ If the object to be placed depends on a coordinate transformation (e.g. rotation
 or skew), first create a content object using L</"graphics">, then call
 L<PDF::Builder::Content/"object"> after making the appropriate transformations.
 
+=back
+
 =cut
 
 sub object {
@@ -1045,10 +1157,16 @@ sub object {
     return $self;
 }
 
-=item $ant = $page->annotation()
+=head3 annotation
+
+    $ant = $page->annotation()
+
+=over
 
 Returns a new annotation object.
 
+=back
+
 =cut
 
 sub annotation {
@@ -1077,7 +1195,11 @@ sub annotation {
     return $ant;
 }
 
-=item $page->resource($type, $key, $obj)
+=head3 resource
+
+    $page->resource($type, $key, $obj)
+
+=over
 
 Adds a resource to the page-inheritance tree.
 
@@ -1092,6 +1214,8 @@ B<Note:> You only have to add the required resources if
 they are NOT handled by the *font*, *image*, *shade* or *space*
 methods.
 
+=back
+
 =cut
 
 sub resource {
@@ -1144,8 +1268,4 @@ sub ship_out {
 #    return $self->SUPER::outobjdeep(@opts);
 #}
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Resource.pm b/lib/PDF/Builder/Resource.pm
index 28b185c..68728b4 100644
--- a/lib/PDF/Builder/Resource.pm
+++ b/lib/PDF/Builder/Resource.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Basic::PDF::Dict';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use PDF::Builder::Util qw(pdfkey);
 use PDF::Builder::Basic::PDF::Utils; # PDFName
@@ -19,12 +19,16 @@ PDF::Builder::Resource - Base class for PDF resources. Inherit from L<PDF::Build
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    $resource = PDF::Builder::Resource->new($pdf, $name)
 
-=item $resource = PDF::Builder::Resource->new($pdf, $name)
+=over
 
 Returns a resource object.
 
+=back
+
 =cut
 
 sub new {
@@ -47,12 +51,18 @@ sub new {
 # Note: new_api() removed in favor of new():
 #   new_api($api, ...)  replace with new($api->{'pdf'}, ...)
 
-=item $name = $resource->name() # Get
+=head2 name
+
+    $name = $resource->name() # Get
+
+    $resource->name($name) # Set
 
-=item $resource->name($name) # Set
+=over
 
 Get or set the name of the resource.
 
+=back
+
 =cut
 
 sub name {
@@ -71,8 +81,4 @@ sub name {
 #    return $self->SUPER::outobjdeep($fh, $pdf, %options);
 #}
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Resource/BaseFont.pm b/lib/PDF/Builder/Resource/BaseFont.pm
index c5a57cf..be9e814 100644
--- a/lib/PDF/Builder/Resource/BaseFont.pm
+++ b/lib/PDF/Builder/Resource/BaseFont.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use Compress::Zlib;
 #use Encode qw(:all);
@@ -20,12 +20,16 @@ PDF::Builder::Resource::BaseFont - Base class for font resources
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    $font = PDF::Builder::Resource::BaseFont->new($pdf, $name)
 
-=item $font = PDF::Builder::Resource::BaseFont->new($pdf, $name)
+=over
 
 Return a font resource object.
 
+=back
+
 =cut
 
 sub new {
@@ -50,10 +54,16 @@ sub data {
     return $_[0]->{' data'}; 
 }
 
-=item $descriptor = $font->descrByData()
+=head2 descrByData
+
+    $descriptor = $font->descrByData()
+
+=over
 
 Return the font's FontDescriptor key structure based on the font's data.
 
+=back
+
 =cut
 
 sub descrByData {
@@ -152,82 +162,116 @@ sub tounicodemap {
     return $self;
 }
 
-=back
-
 =head1 FONT-MANAGEMENT RELATED METHODS
 
-=over
+=head2 fontname
+
+    $name = $font->fontname()
 
-=item $name = $font->fontname()
+=over
 
 Return the font's name (a.k.a. display name).
 
+=back
+
 =cut
 
 sub fontname { 
     return $_[0]->data()->{'fontname'}; 
 }
 
-=item $name = $font->altname()
+=head2 altname
+
+    $name = $font->altname()
+
+=over
 
 Return the font's alternative name (a.k.a. Windows name for a PostScript font).
 
+=back
+
 =cut
 
 sub altname { 
     return $_[0]->data()->{'altname'}; 
 }
 
-=item $name = $font->subname()
+=head2 subname
+
+    $name = $font->subname()
+
+=over
 
 Return the font's subname (a.k.a. font variant).
 
+=back
+
 =cut
 
 sub subname { 
     return $_[0]->data()->{'subname'}; 
 }
 
-=item $name = $font->apiname()
+=head2 apiname
+
+    $name = $font->apiname()
+
+=over
 
 Return the font's name to be used internally (should be equal to $font->name()).
 
+=back
+
 =cut
 
 sub apiname { 
     return $_[0]->data()->{'apiname'}; 
 }
 
-=item $issymbol = $font->issymbol()
+=head2 issymbol
+
+    $issymbol = $font->issymbol()
+
+=over
 
 Return the font's symbol flag (i.e., is this a symbol font).
 
+=back
+
 =cut
 
 sub issymbol { 
     return $_[0]->data()->{'issymbol'}; 
 }
 
-=item $iscff = $font->iscff()
+=head2 iscff
+
+    $iscff = $font->iscff()
+
+=over
 
 Return the font's Compact Font Format flag.
 
+=back
+
 =cut
 
 sub iscff { 
     return $_[0]->data()->{'iscff'}; 
 }
 
-=back
-
 =head1 TYPOGRAPHY-RELATED METHODS
 
-=over
+=head2 fontbbox
 
-=item ($llx,$lly, $urx,$ury) = $font->fontbbox()
+    ($llx,$lly, $urx,$ury) = $font->fontbbox()
+
+=over
 
 Return the font's bounding box.
 
+=back
+
 =cut
 
 sub fontbbox { 
@@ -239,50 +283,80 @@ sub fontbbox {
     return @bbox;
 }
 
-=item $capheight = $font->capheight()
+=head2 capheight
+
+    $capheight = $font->capheight()
+
+=over
 
 Return the font's capheight value.
 
+=back
+
 =cut
 
 sub capheight { 
     return $_[0]->data()->{'capheight'}; 
 }
 
-=item $xheight = $font->xheight()
+=head2 xheight
+
+    $xheight = $font->xheight()
+
+=over
 
 Return the font's xheight value.
 
+=back
+
 =cut
 
 sub xheight { 
     return $_[0]->data()->{'xheight'}; 
 }
 
-=item $missingwidth = $font->missingwidth()
+=head2 missingwidth
+
+    $missingwidth = $font->missingwidth()
+
+=over
 
 Return the font's missingwidth value.
 
+=back
+
 =cut
 
 sub missingwidth { 
     return $_[0]->data()->{'missingwidth'}; 
 }
 
-=item $maxwidth = $font->maxwidth()
+=head2 maxwidth
+
+    $maxwidth = $font->maxwidth()
+
+=over
 
 Return the font's maxwidth value.
 
+=back
+
 =cut
 
 sub maxwidth { 
     return $_[0]->data()->{'maxwidth'}; 
 }
 
-=item $avgwidth = $font->avgwidth()
+=head2 avgwidth
+
+    $avgwidth = $font->avgwidth()
+
+=over
 
 Return the font's avgwidth (average width) value.
 
+=back
+
 =cut
 
 sub avgwidth {
@@ -351,39 +425,63 @@ sub avgwidth {
     return int($aw);
 }
 
-=item $flags = $font->flags()
+=head2 flags
+
+    $flags = $font->flags()
+
+=over
 
 Return the font's flags value.
 
+=back
+
 =cut
 
 sub flags { 
     return $_[0]->data()->{'flags'}; 
 }
 
-=item $stemv = $font->stemv()
+=head2 stemv
+
+    $stemv = $font->stemv()
+
+=over
 
 Return the font's stemv value.
 
+=back
+
 =cut
 
 sub stemv { 
     return $_[0]->data()->{'stemv'}; 
 }
 
-=item $stemh = $font->stemh()
+=head2 stemh
+
+    $stemh = $font->stemh()
+
+=over
 
 Return the font's stemh value.
 
+=back
+
 =cut
 
 sub stemh { 
     return $_[0]->data()->{'stemh'}; 
 }
 
-=item $italicangle = $font->italicangle()
+=head2 italicangle
 
-Return the font's italicangle value.
+    $italicangle = $font->italicangle()
+
+=over
+
+Return the font's italicangle (slant, obliqueness) value.
+
+=back
 
 =cut
 
@@ -391,76 +489,114 @@ sub italicangle {
     return $_[0]->data()->{'italicangle'}; 
 }
 
-=item $isfixedpitch = $font->isfixedpitch()
+=head2 isfixedpitch
+
+    $isfixedpitch = $font->isfixedpitch()
+
+=over
 
 Return the font's isfixedpitch flag.
 
+=back
+
 =cut
 
 sub isfixedpitch { 
     return $_[0]->data()->{'isfixedpitch'}; 
 }
 
-=item $underlineposition = $font->underlineposition()
+=head2 underlineposition
+
+    $underlineposition = $font->underlineposition()
+
+=over
 
 Return the font's underlineposition value.
 
+=back
+
 =cut
 
 sub underlineposition { 
     return $_[0]->data()->{'underlineposition'}; 
 }
 
-=item $underlinethickness = $font->underlinethickness()
+=head2 underlinethickness
+
+    $underlinethickness = $font->underlinethickness()
+
+=over
 
 Return the font's underlinethickness value.
 
+=back
+
 =cut
 
 sub underlinethickness { 
     return $_[0]->data()->{'underlinethickness'}; 
 }
 
-=item $ascender = $font->ascender()
+=head2 ascender
+
+    $ascender = $font->ascender()
+
+=over
 
 Return the font's ascender value.
 
+=back
+
 =cut
 
 sub ascender { 
     return $_[0]->data()->{'ascender'}; 
 }
 
-=item $descender = $font->descender()
+=head2 descender
+
+    $descender = $font->descender()
+
+=over
 
 Return the font's descender value.
 
+=back
+
 =cut
 
 sub descender { 
     return $_[0]->data()->{'descender'}; 
 }
 
-=back
-
 =head1 GLYPH-RELATED METHODS
 
-=over 4
+=head2 glyphNames
 
-=item @names = $font->glyphNames()
+    @names = $font->glyphNames()
+
+=over
 
 Return the defined glyph names of the font.
 
+=back
+
 =cut
 
 sub glyphNames { 
     return keys %{$_[0]->data()->{'wx'}}; 
 }
 
-=item $glNum = $font->glyphNum()
+=head2 glyphNum
+
+    $glNum = $font->glyphNum()
+
+=over
 
 Return the number of defined glyph names of the font.
 
+=back
+
 =cut
 
 sub glyphNum { 
@@ -469,10 +605,16 @@ sub glyphNum {
     return scalar keys %{$_[0]->data()->{'wx'}}; 
 }
 
-=item $uni = $font->uniByGlyph($char)
+=head2 uniByGlyph
+
+    $uni = $font->uniByGlyph($char)
+
+=over
 
 Return the unicode by glyph name.
 
+=back
+
 =cut
 
 sub uniByGlyph { 
@@ -481,10 +623,16 @@ sub uniByGlyph {
     return $_[0]->data()->{'n2u'}->{$_[1]}; 
 }
 
-=item $uni = $font->uniByEnc($char)
+=head2 uniByEnc
+
+    $uni = $font->uniByEnc($char)
+
+=over
 
 Return the Unicode by the font's encoding map.
 
+=back
+
 =cut
 
 sub uniByEnc { 
@@ -495,30 +643,48 @@ sub uniByEnc {
     return $uni;
 }
 
-=item $uni = $font->uniByMap($char)
+=head2 uniByMap
+
+    $uni = $font->uniByMap($char)
+
+=over
 
 Return the Unicode by the font's default map.
 
+=back
+
 =cut
 
 sub uniByMap { 
     return $_[0]->data()->{'uni'}->[$_[1]]; 
 }
 
-=item $char = $font->encByGlyph($glyph)
+=head2 encByGlyph
+
+    $char = $font->encByGlyph($glyph)
+
+=over
 
 Return the character by the given glyph name of the font's encoding map.
 
+=back
+
 =cut
 
 sub encByGlyph { 
     return $_[0]->data()->{'n2e'}->{$_[1]} || 0; 
 }
 
-=item $char = $font->encByUni($uni)
+=head2 encByUni
+
+    $char = $font->encByUni($uni)
+
+=over
 
 Return the character by the given Unicode of the font's encoding map.
 
+=back
+
 =cut
 
 sub encByUni { 
@@ -527,65 +693,101 @@ sub encByUni {
 	   0; 
 }
 
-=item $char = $font->mapByGlyph($glyph)
+=head2 mapByGlyph
+
+    $char = $font->mapByGlyph($glyph)
+
+=over
 
 Return the character by the given glyph name of the font's default map.
 
+=back
+
 =cut
 
 sub mapByGlyph { 
     return $_[0]->data()->{'n2c'}->{$_[1]} || 0; 
 }
 
-=item $char = $font->mapByUni($uni)
+=head2 mapByUni
+
+    $char = $font->mapByUni($uni)
+
+=over
 
 Return the character by the given Unicode of the font's default map.
 
+=back
+
 =cut
 
 sub mapByUni { 
     return $_[0]->data()->{'u2c'}->{$_[1]} || 0; 
 }
 
-=item $name = $font->glyphByUni($unicode)
+=head2 glyphByUni
+
+    $name = $font->glyphByUni($unicode)
+
+=over
 
 Return the glyph's name by the font's Unicode map.
 B<CAUTION:> non-standard glyph-names are mapped onto
 the ms-symbol area (0xF000).
 
+=back
+
 =cut
 
 sub glyphByUni { 
     return $_[0]->data()->{'u2n'}->{$_[1]} || '.notdef'; 
 }
 
-=item $name = $font->glyphByEnc($char)
+=head2 glyphByEnc
+
+    $name = $font->glyphByEnc($char)
+
+=over
 
 Return the glyph's name by the font's encoding map.
 
+=back
+
 =cut
 
 sub glyphByEnc {
     return $_[0]->data()->{'e2n'}->[$_[1]];
 }
 
-=item $name = $font->glyphByMap($char)
+=head2 glyphByMap
+
+    $name = $font->glyphByMap($char)
+
+=over
 
 Return the glyph's name by the font's default map.
 
+=back
+
 =cut
 
 sub glyphByMap { 
     return $_[0]->data()->{'char'}->[$_[1]]; 
 }
 
-=item $width = $font->wxByGlyph($glyph)
+=head2 wxByGlyph
+
+    $width = $font->wxByGlyph($glyph)
+
+=over
 
 Return the glyph's width.
 This is a value, that when divided by 1000 and multiplied by
 the font size (height in points), gives the advance width to the
 next character's start. Typically, the width will be under 1000.
 
+=back
+
 =cut
 
 sub wxByGlyph {
@@ -604,13 +806,19 @@ sub wxByGlyph {
     return $width;
 }
 
-=item $width = $font->wxByUni($uni)
+=head2 wxByUni
+
+    $width = $font->wxByUni($uni)
+
+=over
 
 Return the Unicode character's width.
 This is a value, that when divided by 1000 and multiplied by
 the font size (height in points), gives the advance width to the
 next character's start. Typically, the width will be under 1000.
 
+=back
+
 =cut
 
 sub wxByUni {
@@ -625,13 +833,19 @@ sub wxByUni {
     return $width;
 }
 
-=item $width = $font->wxByEnc($char)
+=head2 wxByEnc
+
+    $width = $font->wxByEnc($char)
+
+=over
 
 Return the character's width based on the current encoding.
 This is a value, that when divided by 1000 and multiplied by
 the font size (height in points), gives the advance width to the
 next character's start. Typically, the width will be under 1000.
 
+=back
+
 =cut
 
 sub wxByEnc {
@@ -648,11 +862,17 @@ sub wxByEnc {
     return $width;
 }
 
-=item $flag = $font->wxMissingByEnc($char)
+=head2 wxMissingByEnc
+
+    $flag = $font->wxMissingByEnc($char)
+
+=over
 
 Return true if the character's width (based on the current encoding) is
 supplied by "missing width" of font.
 
+=back
+
 =cut
 
 sub wxMissingByEnc {
@@ -664,13 +884,19 @@ sub wxMissingByEnc {
     return !defined($width);
 }
 
-=item $width = $font->wxByMap($char)
+=head2 wxByMap
+
+    $width = $font->wxByMap($char)
+
+=over
 
 Return the character's width based on the font's default encoding.
 This is a value, that when divided by 1000 and multiplied by
 the font size (height in points), gives the advance width to the
 next character's start. Typically, the width will be under 1000.
 
+=back
+
 =cut
 
 sub wxByMap {
@@ -686,12 +912,18 @@ sub wxByMap {
     return $width;
 }
 
-=item $wd = $font->width($text)
+=head2 width
+
+    $wd = $font->width($text)
 
-Return the width of $text as if it were at size 1.
+=over
+
+Return the width of $text as if it were at font size 1 (unscaled).
 B<CAUTION:> works correctly only if a proper Perl string
 is used, either in native or UTF-8 format (check utf8-flag).
 
+=back
+
 =cut
 
 sub width {
@@ -716,10 +948,16 @@ sub width {
     return $width;
 }
 
-=item @widths = $font->width_array($text)
+=head2 width_array
+
+    @widths = $font->width_array($text)
+
+=over
 
 Return (as an array) the widths of the words in $text as if they were at size 1.
 
+=back
+
 =cut
 
 sub width_array {
@@ -730,16 +968,16 @@ sub width_array {
     return @widths;
 }
 
-=back
+=head2 utfByStr
 
-=head1 STRING METHODS
+    $utf8string = $font->utfByStr($string)
 
 =over
 
-=item $utf8string = $font->utfByStr($string)
-
 Return the utf8-string from string based on the font's encoding map.
 
+=back
+
 =cut
 
 sub utfByStr {
@@ -750,10 +988,16 @@ sub utfByStr {
     return $string;
 }
 
-=item $string = $font->strByUtf($utf8_string)
+=head2 strByUtf
+
+    $string = $font->strByUtf($utf8_string)
+
+=over
 
 Return the encoded string from utf8-string based on the font's encoding map.
 
+=back
+
 =cut
 
 sub strByUtf {
@@ -764,10 +1008,16 @@ sub strByUtf {
     return $utf8_string;
 }
 
-=item $pdf_string = $font->textByStr($string)
+=head2 textByStr
+
+    $pdf_string = $font->textByStr($string)
+
+=over
 
 Return a properly formatted representation of $string for use in the PDF.
 
+=back
+
 =cut
 
 sub textByStr {
@@ -783,11 +1033,17 @@ sub textByStr {
     return $text;
 }
 
-=item $pdf_string = $font->textByStrKern($string)
+=head2 textByStrKern
+
+    $pdf_string = $font->textByStrKern($string)
+
+=over
 
 Return a properly formatted representation of $string, with kerning, 
 for use in the PDF.
 
+=back
+
 =cut
 
 sub textByStrKern {
@@ -844,8 +1100,4 @@ sub isvirtual {
     return; 
 }
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Resource/CIDFont.pm b/lib/PDF/Builder/Resource/CIDFont.pm
index 3857fc8..7ad0c58 100644
--- a/lib/PDF/Builder/Resource/CIDFont.pm
+++ b/lib/PDF/Builder/Resource/CIDFont.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource::BaseFont';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use Encode qw(:all);
 
@@ -19,12 +19,16 @@ PDF::Builder::Resource::CIDFont - Base class for CID fonts
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    $font = PDF::Builder::Resource::CIDFont->new($pdf, $name)
 
-=item $font = PDF::Builder::Resource::CIDFont->new($pdf, $name)
+=over
 
 Returns a cid-font object, base class for all CID-based fonts.
 
+=back
+
 =cut
 
 sub new {
@@ -129,10 +133,16 @@ sub width_cid {
     return $width;
 }
 
-=item $cidstring = $font->cidsByStr($string)
+=head2 cidsByStr
+
+    $cidstring = $font->cidsByStr($string)
+
+=over
 
 Returns the cid-string from string based on the font's encoding map.
 
+=back
+
 =cut
 
 sub _cidsByStr {
@@ -171,10 +181,16 @@ sub cidsByStr {
     return $text;
 }
 
-=item $cidstring = $font->cidsByUtf($utf8string)
+=head2 cidsByUtf
+
+    $cidstring = $font->cidsByUtf($utf8string)
+
+=over
 
 Returns the CID-encoded string from utf8-string.
 
+=back
+
 =cut
 
 sub cidsByUtf {
@@ -204,19 +220,50 @@ sub textByStrKern {
 sub text {
     my ($self, $text, $size, $indent) = @_;
 
-    my $newtext = $self->textByStr($text);
-    if      (defined $size && $self->{'-dokern'}) {
-        $newtext = $self->textByStrKern($text, $size, $indent);
-        return $newtext;
-    } elsif (defined $size) {
-        if (defined($indent) && $indent!=0) {
-	    return("[ $indent $newtext ] TJ");
-        } else {
-	    return "$newtext Tj";
-        }
-    } else {
-        return $newtext;
+    # need to break up $text into fragments ending with x20
+    # TBD: handle other spaces (espec. xA0) "appropriately" (control by flag)
+    #      0 = x20 space only
+    #      1 (default) = x20 and same/longer spaces
+    #      2 = all spaces
+    #      the problem is, other font types handle only x20 in Reader
+    my $latest_page = $self->{' apipdf'}->{' outlist'}[0]->{'Pages'}->{'Kids'}->{' val'}[-1];
+    my $wordspace = $latest_page->{'Contents'}->{' val'}[0]->{' wordspace'};
+    my $fontsize = $latest_page->{'Contents'}->{' val'}[0]->{' fontsize'};
+    my @fragments = ( $text ); # default for wordspace = 0
+    # TBD: get list of different lengths of spaces found, split on all of them
+    #      could have null fragments where two or more spaces in a row, or
+    #        text ended with a space
+    if ($wordspace) {
+	# split appears to drop trailing blanks, so need a guard
+        @fragments = split / /, $text."|";
+	chop($fragments[-1]);
     }
+
+    my $out_str = '';
+    for (my $i = 0; $i <= $#fragments; $i++) {
+	if ($fragments[$i] ne '') {
+            my $newtext = $self->textByStr($fragments[$i]);  # '<glyphIDsList>'
+            if      (defined $size && $self->{'-dokern'}) {
+                $newtext = $self->textByStrKern($fragments[$i], $size, $indent);
+                $out_str .= $newtext;
+            } elsif (defined $size) {
+                if (defined($indent) && $indent!=0) {
+	            $out_str .= "[ $indent $newtext ] TJ";
+                } else {
+	            $out_str .= "$newtext Tj";
+                }
+            } else {
+                $out_str .= $newtext;
+            }
+	}
+	# unless this is the last fragment (no space follows), add a "kerned"
+	# space to out_str (reduce its effective width by moving left).
+	# TBD: different spaces of different lengths with different "kerns"
+	if ($i < $#fragments) {
+	    $out_str .= "[ ".$self->textByStrKern(' ')." ".(-$wordspace/$fontsize*1000)." ] TJ";
+	}
+    }
+    return $out_str;
 }
 
 sub text_cid {
@@ -337,8 +384,4 @@ sub glyphNum {
 #    return $self->SUPER::outobjdeep($fh, $pdf, %opts);
 #}
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Resource/CIDFont/CJKFont.pm b/lib/PDF/Builder/Resource/CIDFont/CJKFont.pm
index 822200f..7c3665e 100644
--- a/lib/PDF/Builder/Resource/CIDFont/CJKFont.pm
+++ b/lib/PDF/Builder/Resource/CIDFont/CJKFont.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource::CIDFont';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use PDF::Builder::Util;
 use PDF::Builder::Basic::PDF::Utils;
@@ -22,29 +22,49 @@ PDF::Builder::Resource::CIDFont::CJKFont - Base class for CJK fonts
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    $font = PDF::Builder::Resource::CIDFont::CJKFont->new($pdf, $cjkname, %options)
 
-=item $font = PDF::Builder::Resource::CIDFont::CJKFont->new($pdf, $cjkname, %options)
+=over
 
 Returns a cjk-font object.
 
+=back
+
 =over
 
-* Traditional Chinese: Ming Ming-Bold Ming-Italic Ming-BoldItalic
+=item * 
+
+Traditional Chinese: Ming, Ming-Bold, Ming-Italic, Ming-BoldItalic
+
+=item * 
+
+Simplified Chinese: Song, Song-Bold, Song-Italic, Song-BoldItalic
+
+=item * 
+
+Korean: MyungJo, MyungJo-Bold, MyungJo-Italic, MyungJo-BoldItalic
 
-* Simplified Chinese: Song Song-Bold Song-Italic Song-BoldItalic
+=item * 
 
-* Korean: MyungJo MyungJo-Bold MyungJo-Italic MyungJo-BoldItalic
+Japanese (Mincho): KozMin, KozMin-Bold, KozMin-Italic, KozMin-BoldItalic
 
-* Japanese (Mincho): KozMin KozMin-Bold KozMin-Italic KozMin-BoldItalic
+=item * 
 
-* Japanese (Gothic): KozGo KozGo-Bold KozGo-Italic KozGo-BoldItalic
+Japanese (Gothic): KozGo, KozGo-Bold, KozGo-Italic, KozGo-BoldItalic
 
 =back
 
 Defined Options:
 
-    encode ... specify fonts encoding for non-utf8 text.
+=over
+
+=item encode
+
+specify fonts encoding for non-utf8 text.
+
+=back
 
 =cut
 
@@ -319,8 +339,4 @@ BEGIN {
 
 }
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Resource/CIDFont/TrueType.pm b/lib/PDF/Builder/Resource/CIDFont/TrueType.pm
index 4d2bf0a..89cad31 100644
--- a/lib/PDF/Builder/Resource/CIDFont/TrueType.pm
+++ b/lib/PDF/Builder/Resource/CIDFont/TrueType.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource::CIDFont';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use PDF::Builder::Basic::PDF::Utils;
 use PDF::Builder::Resource::CIDFont::TrueType::FontFile;
@@ -18,9 +18,11 @@ PDF::Builder::Resource::CIDFont::TrueType - TrueType font support
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    $font = PDF::Builder::Resource::CIDFont::TrueType->new($pdf, $file, %options)
 
-=item $font = PDF::Builder::Resource::CIDFont::TrueType->new($pdf, $file, %options)
+=over
 
 Returns a font object.
 
@@ -31,6 +33,8 @@ Defined Options:
     nosubset ... disables subsetting. Any value causes the full font to be
                  embedded, rather than only the glyphs needed.
 
+=back
+
 =cut
 
 sub new {
@@ -82,14 +86,50 @@ sub new {
     return $self;
 }
 
+=head2 fontfile
+
+    $font->fontfile()
+
+=over
+
+Returns font file object (' ff' element), so its methods may be invoked.
+
+=back
+
+=cut
+
 sub fontfile { 
     return $_[0]->{' ff'};
 }
 
+=head2 fontobj
+
+    $font->fontobj()
+
+=over
+
+Returns font object, so its methods and properties may be used.
+
+=back
+
+=cut
+
 sub fontobj {
     return $_[0]->data()->{'obj'};
 }
 
+=head2 wxByCId
+
+    $font->wxByCId($gID)
+
+=over
+
+Returns unscaled glyph width, given the glyph ID (CID).
+
+=back
+
+=cut
+
 sub wxByCId {
     my ($self, $g) = @_;
 
@@ -105,18 +145,57 @@ sub wxByCId {
     return $w;
 }
 
+=head2 haveKernPairs
+
+    $flag = $font->haveKernPairs()
+
+=over
+
+Does the font include kerning data? Invokes fontfile's haveKernPairs().
+Not clear what additional optional arguments are.
+
+=back
+
+=cut
+
 sub haveKernPairs {
     my $self = shift;
 
     return $self->fontfile()->haveKernPairs(@_);
 }
 
+=head2 kernPairCid
+
+    $flag = $font->kernPairCid($gID, $n)
+
+=over
+
+Returns kerning information for? Not clear what additional arguments are.
+Invokes fontfile's kernPairCid() method.
+
+=back
+
+=cut
+
 sub kernPairCid {
     my $self = shift;
 
     return $self->fontfile()->kernPairCid(@_);
 }
 
+=head2 subsetByCid
+
+    $font->subsetByCid($gID)
+
+=over
+
+Invokes subsetByCId() method from fontfile() to put the glyph into the embedded
+font cache in the PDF.
+
+=back
+
+=cut
+
 sub subsetByCId {
     my $self = shift;
 
@@ -125,6 +204,18 @@ sub subsetByCId {
     return $self->fontfile()->subsetByCId($g);
 }
 
+=head2 subvec
+
+    $font->subvec($gID)
+
+=over
+
+(No Information) invokes fontfile's subvec() method.
+
+=back
+
+=cut
+
 sub subvec {
     my $self = shift;
 
@@ -133,10 +224,34 @@ sub subvec {
     return $self->fontfile()->subvec($g);
 }
 
+=head2 glyphNum
+
+    $count = $font->glyphNum()
+
+=over
+
+Number of glyphs in the font.
+
+=back
+
+=cut
+
 sub glyphNum {
     return $_[0]->fontfile()->glyphNum();
 }
 
+=head2 outobjdeep
+
+    $font->outobjdeep()
+
+=over
+
+(No Information) output to PDF
+
+=back
+
+=cut
+
 sub outobjdeep {
     my ($self, $fh, $pdf) = @_;
 
@@ -176,8 +291,4 @@ sub outobjdeep {
     return $self->SUPER::outobjdeep($fh, $pdf);
 }
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Resource/CIDFont/TrueType/FontFile.pm b/lib/PDF/Builder/Resource/CIDFont/TrueType/FontFile.pm
index 82c25d7..9b8ba17 100644
--- a/lib/PDF/Builder/Resource/CIDFont/TrueType/FontFile.pm
+++ b/lib/PDF/Builder/Resource/CIDFont/TrueType/FontFile.pm
@@ -5,7 +5,7 @@ use base 'PDF::Builder::Basic::PDF::Dict';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.025'; # manually update whenever code is changed
 
 use Carp;
diff --git a/lib/PDF/Builder/Resource/ColorSpace.pm b/lib/PDF/Builder/Resource/ColorSpace.pm
index aa22011..d494a51 100644
--- a/lib/PDF/Builder/Resource/ColorSpace.pm
+++ b/lib/PDF/Builder/Resource/ColorSpace.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Basic::PDF::Array';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use PDF::Builder::Basic::PDF::Utils;
 use PDF::Builder::Util;
@@ -18,12 +18,16 @@ PDF::Builder::Resource::ColorSpace - Base class for PDF color spaces
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    $cs = PDF::Builder::Resource::ColorSpace->new($pdf, $key, %opts)
 
-=item $cs = PDF::Builder::Resource::ColorSpace->new($pdf, $key, %opts)
+=over
 
 Returns a new colorspace object, base class for all colorspaces.
 
+=back
+
 =cut
 
 sub new {
@@ -39,12 +43,18 @@ sub new {
     return $self;
 }
 
-=item $name = $res->name($name) # Set
+=head2 name
 
-=item $name = $res->name() # Get
+    $name = $res->name($name) # Set
+
+    $name = $res->name() # Get
+
+=over
 
 Returns or sets the Name of the resource.
 
+=back
+
 =cut
 
 sub name {
@@ -65,10 +75,16 @@ sub type {
     return $self->{' type'};
 }
 
-=item @param = $cs->param(@param)
+=head2 param
+
+    @param = $cs->param(@param)
+
+=over
 
 Returns properly formatted color-parameters based on the colorspace.
 
+=back
+
 =cut
 
 sub param {
@@ -87,8 +103,4 @@ sub param {
 #    return $self->SUPER::outobjdeep(@opts);
 #}
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Resource/ColorSpace/DeviceN.pm b/lib/PDF/Builder/Resource/ColorSpace/DeviceN.pm
index adc918e..dc8a547 100644
--- a/lib/PDF/Builder/Resource/ColorSpace/DeviceN.pm
+++ b/lib/PDF/Builder/Resource/ColorSpace/DeviceN.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource::ColorSpace';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use PDF::Builder::Basic::PDF::Utils;
 use PDF::Builder::Util;
@@ -17,6 +17,16 @@ use Scalar::Util qw(weaken);
 PDF::Builder::Resource::ColorSpace::DeviceN - colorspace handling for Device 
 CMYK. Inherits from L<PDF::Builder::Resource::ColorSpace>
 
+=head2 new
+
+    PDF::Builder::Resource::ColorSpace:DeviceN->new($pdf, $key, $clrs)
+
+=over
+
+Create a new DeviceN ColorSpace object.
+
+=back
+
 =cut
 
 sub new {
diff --git a/lib/PDF/Builder/Resource/ColorSpace/Indexed.pm b/lib/PDF/Builder/Resource/ColorSpace/Indexed.pm
index 884b6e8..7220af5 100644
--- a/lib/PDF/Builder/Resource/ColorSpace/Indexed.pm
+++ b/lib/PDF/Builder/Resource/ColorSpace/Indexed.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource::ColorSpace';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use PDF::Builder::Basic::PDF::Utils;
 use PDF::Builder::Util;
@@ -16,6 +16,16 @@ use Scalar::Util qw(weaken);
 
 PDF::Builder::Resource::ColorSpace::Indexed - base colorspace support for indexed color models. Inherits from L<PDF::Builder::Resource::ColorSpace>
 
+=head2 new
+
+    PDF::Builder::Resource::ColorSpace::Indexed->new($pdf, $key, %opts)
+
+=over
+
+Create a new Indexed ColorSpace object.
+
+=back
+
 =cut
 
 sub new {
@@ -33,6 +43,8 @@ sub new {
     return $self;
 }
 
+# unknown -- not used anywhere
+
 sub enumColors {
     my $self = shift;
 
@@ -45,6 +57,8 @@ sub enumColors {
     return %col;
 }
 
+# unknown -- not used anywhere
+
 sub nameColor {
     my ($self, $n) = @_;
 
@@ -54,6 +68,8 @@ sub nameColor {
     return $k;
 }
 
+# unknown -- not used anywhere
+
 sub resolveNearestRGB {
     my $self = shift;
     my ($r, $g, $b) = @_; # need to be in 0-255
diff --git a/lib/PDF/Builder/Resource/ColorSpace/Indexed/ACTFile.pm b/lib/PDF/Builder/Resource/ColorSpace/Indexed/ACTFile.pm
index 4cc3532..1117f4f 100644
--- a/lib/PDF/Builder/Resource/ColorSpace/Indexed/ACTFile.pm
+++ b/lib/PDF/Builder/Resource/ColorSpace/Indexed/ACTFile.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource::ColorSpace::Indexed';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use PDF::Builder::Basic::PDF::Utils;
 use PDF::Builder::Util;
@@ -18,9 +18,11 @@ PDF::Builder::Resource::ColorSpace::Indexed::ACTFile - Adobe Color Table support
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    $cs = PDF::Builder::Resource::ColorSpace::Indexed::ACTFile->new($pdf, $actfile)
 
-=item $cs = PDF::Builder::Resource::ColorSpace::Indexed::ACTFile->new($pdf, $actfile)
+=over
 
 Returns a new colorspace object created from an adobe color table file (ACT/8BCT).
 See
@@ -29,6 +31,8 @@ File Formats Specification Version 6.0 Release 2,
 November 2000
 for details.
 
+=back
+
 =cut
 
 sub new {
@@ -63,8 +67,4 @@ sub new {
     return $self;
 }
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Resource/ColorSpace/Indexed/Hue.pm b/lib/PDF/Builder/Resource/ColorSpace/Indexed/Hue.pm
index 4ba76d0..2d2b54f 100644
--- a/lib/PDF/Builder/Resource/ColorSpace/Indexed/Hue.pm
+++ b/lib/PDF/Builder/Resource/ColorSpace/Indexed/Hue.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource::ColorSpace::Indexed';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use PDF::Builder::Basic::PDF::Utils;
 use PDF::Builder::Util;
@@ -16,6 +16,16 @@ use Scalar::Util qw(weaken);
 
 PDF::Builder::Resource::ColorSpace::Indexed::Hue - colorspace support for Device RGB. Inherits from L<PDF::Builder::Resource::ColorSpace::Indexed>
 
+=head1 METHODS
+
+=head2 new
+
+=over
+
+Create a new Indexed Hue colorspace object.
+
+=back
+
 =cut
 
 sub new {
diff --git a/lib/PDF/Builder/Resource/ColorSpace/Indexed/WebColor.pm b/lib/PDF/Builder/Resource/ColorSpace/Indexed/WebColor.pm
index d7e30d0..d4c21d6 100644
--- a/lib/PDF/Builder/Resource/ColorSpace/Indexed/WebColor.pm
+++ b/lib/PDF/Builder/Resource/ColorSpace/Indexed/WebColor.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource::ColorSpace::Indexed';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 =head1 NAME
 
@@ -18,6 +18,20 @@ use PDF::Builder::Basic::PDF::Utils;
 use PDF::Builder::Util;
 use Scalar::Util qw(weaken);
 
+=head1 METHODS
+
+=head2 new
+
+     PDF::Builder::Resource::ColorSpace::Indexed::WebColor->new()
+
+=over
+
+Create a new "web-safe" indexed colorspace object.
+
+=back
+
+=cut
+
 sub new {
     my ($class, $pdf) = @_;
 
diff --git a/lib/PDF/Builder/Resource/ColorSpace/Separation.pm b/lib/PDF/Builder/Resource/ColorSpace/Separation.pm
index 5d63931..dc47a14 100644
--- a/lib/PDF/Builder/Resource/ColorSpace/Separation.pm
+++ b/lib/PDF/Builder/Resource/ColorSpace/Separation.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource::ColorSpace';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use PDF::Builder::Basic::PDF::Utils;
 use PDF::Builder::Util;
@@ -18,12 +18,16 @@ PDF::Builder::Resource::ColorSpace::Separation - Support for color space separat
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    $cs = PDF::Builder::Resource::ColorSpace::Separation->new($pdf, $key, @colors)
 
-=item $cs = PDF::Builder::Resource::ColorSpace::Separation->new($pdf, $key, @colors)
+=over
 
 Returns a new colorspace object.
 
+=back
+
 =cut
 
 sub new {
@@ -114,10 +118,16 @@ sub new {
     return $self;
 }
 
-=item @color = $res->color()
+=head2 color
+
+    @color = $res->color()
+
+=over
 
 Returns the base-color of the Separation-Colorspace.
 
+=back
+
 =cut
 
 sub color {
@@ -129,10 +139,16 @@ sub color {
     return @{$self->{' color'}};
 }
 
-=item $tintname = $res->tintname($tintname)
+=head2 tintname
+
+    $tintname = $res->tintname($tintname)
+
+=over
 
 Returns the tint-name of the Separation-Colorspace.
 
+=back
+
 =cut
 
 sub tintname {
@@ -150,8 +166,4 @@ sub param {
     return $_[0];
 }
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Resource/Colors.pm b/lib/PDF/Builder/Resource/Colors.pm
index 0ec5c0b..e942fac 100644
--- a/lib/PDF/Builder/Resource/Colors.pm
+++ b/lib/PDF/Builder/Resource/Colors.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Colors;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/ExtGState.pm b/lib/PDF/Builder/Resource/ExtGState.pm
index c1facb4..30e47be 100644
--- a/lib/PDF/Builder/Resource/ExtGState.pm
+++ b/lib/PDF/Builder/Resource/ExtGState.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use PDF::Builder::Basic::PDF::Utils;
 use PDF::Builder::Util;
@@ -17,12 +17,16 @@ PDF::Builder::Resource::ExtGState - Graphics state dictionary support
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    $egs = PDF::Builder::Resource::ExtGState->new(@parameters)
 
-=item $egs = PDF::Builder::Resource::ExtGState->new(@parameters)
+=over
 
 Returns a new extgstate object (called from $pdf->egstate()).
 
+=back
+
 =cut
 
 sub new {
@@ -34,7 +38,15 @@ sub new {
     return $self;
 }
 
-=item $egs->strokeadjust($boolean)
+=head2 strokeadjust
+
+    $egs->strokeadjust($boolean)
+
+=over
+
+(No information)
+
+=back
 
 =cut
 
@@ -45,7 +57,15 @@ sub strokeadjust {
     return $self;
 }
 
-=item $egs->strokeoverprint($boolean)
+=head2 strokeoverprint
+
+    $egs->strokeoverprint($boolean)
+
+=over
+
+(No information)
+
+=back
 
 =cut
 
@@ -56,7 +76,15 @@ sub strokeoverprint {
     return $self;
 }
 
-=item $egs->filloverprint($boolean)
+=head2 filloverprint
+
+    $egs->filloverprint($boolean)
+
+=over
+
+(No information)
+
+=back
 
 =cut
 
@@ -67,7 +95,15 @@ sub filloverprint {
     return $self;
 }
 
-=item $egs->overprintmode($num)
+=head2 overprintmode
+
+    $egs->overprintmode($num)
+
+=over
+
+(No information)
+
+=back
 
 =cut
 
@@ -78,7 +114,15 @@ sub overprintmode {
     return $self;
 }
 
-=item $egs->blackgeneration($obj)
+=head2 blackgeneration
+
+    $egs->blackgeneration($obj)
+
+=over
+
+(No information)
+
+=back
 
 =cut
 
@@ -89,7 +133,15 @@ sub blackgeneration {
     return $self;
 }
 
-=item $egs->blackgeneration2($obj)
+=head2 blackgeneration2
+
+    $egs->blackgeneration2($obj)
+
+=over
+
+(No information)
+
+=back
 
 =cut
 
@@ -100,7 +152,15 @@ sub blackgeneration2 {
     return $self;
 }
 
-=item $egs->undercolorremoval($obj)
+=head2 undercolorremoval
+
+    $egs->undercolorremoval($obj)
+
+=over
+
+(No information)
+
+=back
 
 =cut
 
@@ -111,7 +171,15 @@ sub undercolorremoval {
     return $self;
 }
 
-=item $egs->undercolorremoval2($obj)
+=head2 undercolorremoval2
+
+    $egs->undercolorremoval2($obj)
+
+=over
+
+(No information)
+
+=back
 
 =cut
 
@@ -122,7 +190,15 @@ sub undercolorremoval2 {
     return $self;
 }
 
-=item $egs->transfer($obj)
+=head2 transfer
+
+    $egs->transfer($obj)
+
+=over
+
+(No information)
+
+=back
 
 =cut
 
@@ -133,7 +209,15 @@ sub transfer {
     return $self;
 }
 
-=item $egs->transfer2($obj)
+=head2 transfer2
+
+    $egs->transfer2($obj)
+
+=over
+
+(No information)
+
+=back
 
 =cut
 
@@ -144,7 +228,15 @@ sub transfer2 {
     return $self;
 }
 
-=item $egs->halftone($obj)
+=head2 halftone
+
+    $egs->halftone($obj)
+
+=over
+
+(No information)
+
+=back
 
 =cut
 
@@ -155,7 +247,15 @@ sub halftone {
     return $self;
 }
 
-=item $egs->halftonephase($obj)
+=head2 halftonephase
+
+    $egs->halftonephase($obj)
+
+=over
+
+(No information)
+
+=back
 
 =cut
 
@@ -168,7 +268,15 @@ sub halftonephase {
     return $self;
 }
 
-=item $egs->smoothness($num)
+=head2 smoothness
+
+    $egs->smoothness($num)
+
+=over
+
+(No information)
+
+=back
 
 =cut
 
@@ -179,7 +287,15 @@ sub smoothness {
     return $self;
 }
 
-=item $egs->font($font, $size)
+=head2 font
+
+    $egs->font($font, $size)
+
+=over
+
+(No information)
+
+=back
 
 =cut
 
@@ -190,7 +306,15 @@ sub font {
     return $self;
 }
 
-=item $egs->linewidth($size)
+=head2 linewidth
+
+    $egs->linewidth($size)
+
+=over
+
+(No information)
+
+=back
 
 =cut
 
@@ -201,7 +325,15 @@ sub linewidth {
     return $self;
 }
 
-=item $egs->linecap($cap)
+=head2 linecap
+
+    $egs->linecap($cap)
+
+=over
+
+(No information)
+
+=back
 
 =cut
 
@@ -212,7 +344,15 @@ sub linecap {
     return $self;
 }
 
-=item $egs->linejoin($join)
+=head2 linejoin
+
+    $egs->linejoin($join)
+
+=over
+
+(No information)
+
+=back
 
 =cut
 
@@ -223,7 +363,15 @@ sub linejoin {
     return $self;
 }
 
-=item $egs->miterlimit($limit)
+=head2 miterlimit
+
+    $egs->miterlimit($limit)
+
+=over
+
+(No information)
+
+=back
 
 =cut
 
@@ -236,7 +384,15 @@ sub miterlimit {
 
 # Note: miterlimit was originally named incorrectly as meterlimit, renamed
 
-=item $egs->dash(@dash)
+=head2 dash
+
+    $egs->dash(@dash)
+
+=over
+
+(No information)
+
+=back
 
 =cut
 
@@ -247,7 +403,15 @@ sub dash {
     return $self;
 }
 
-=item $egs->flatness($flat)
+=head2 flatness
+
+    $egs->flatness($flat)
+
+=over
+
+(No information)
+
+=back
 
 =cut
 
@@ -258,7 +422,15 @@ sub flatness {
     return $self;
 }
 
-=item $egs->renderingintent($intentName)
+=head2 renderingintent
+
+    $egs->renderingintent($intentName)
+
+=over
+
+(No information)
+
+=back
 
 =cut
 
@@ -269,12 +441,18 @@ sub renderingintent {
     return $self;
 }
 
-=item $egs->strokealpha($alpha)
+=head2 strokealpha
+
+    $egs->strokealpha($alpha)
+
+=over
 
 The current stroking alpha constant, specifying the
 constant shape or constant opacity value to be used
 for stroking operations in the transparent imaging model.
 
+=back
+
 =cut
 
 sub strokealpha {
@@ -284,10 +462,16 @@ sub strokealpha {
     return $self;
 }
 
-=item $egs->fillalpha($alpha)
+=head2 fillalpha
+
+    $egs->fillalpha($alpha)
+
+=over
 
 Same as strokealpha, but for nonstroking (fill) operations.
 
+=back
+
 =cut
 
 sub fillalpha {
@@ -297,12 +481,18 @@ sub fillalpha {
     return $self;
 }
 
-=item $egs->blendmode($blendname)
+=head2 blendmode
+
+    $egs->blendmode($blendname)
 
-=item $egs->blendmode($blendfunctionobj)
+    $egs->blendmode($blendfunctionobj)
+
+=over
 
 The current blend mode to be used in the transparent imaging model.
 
+=back
+
 =cut
 
 sub blendmode {
@@ -316,13 +506,19 @@ sub blendmode {
     return $self;
 }
 
-=item $egs->alphaisshape($boolean)
+=head2 alphaisshape
+
+    $egs->alphaisshape($boolean)
+
+=over
 
 The alpha source flag (alpha is shape), specifying
 whether the current soft mask and alpha constant
 are to be interpreted as shape values (I<true>) or
 opacity values (I<false>).
 
+=back
+
 =cut
 
 sub alphaisshape {
@@ -332,12 +528,18 @@ sub alphaisshape {
     return $self;
 }
 
-=item $egs->textknockout($boolean)
+=head2 textknockout
+
+    $egs->textknockout($boolean)
+
+=over
 
 The text knockout flag, which determines the behavior
 of overlapping glyphs within a text object in the
 transparent imaging model.
 
+=back
+
 =cut
 
 sub textknockout {
@@ -347,12 +549,18 @@ sub textknockout {
     return $self;
 }
 
-=item $egs->transparency($t)
+=head2 transparency
+
+    $egs->transparency($t)
+
+=over
 
 The graphics transparency, with 0 being fully opaque and 1 being fully 
 transparent. This is a convenience method, setting proper values for 
 C<strokealpha> and C<fillalpha>.
 
+=back
+
 =cut
 
 sub transparency {
@@ -363,12 +571,18 @@ sub transparency {
     return $self;
 }
 
-=item $egs->opacity($op)
+=head2 opacity
+
+    $egs->opacity($op)
+
+=over
 
 The graphics opacity, with 1 being fully opaque and 0 being fully transparent.
 This is a convenience method, setting proper values for C<strokealpha> and 
 C<fillalpha>.
 
+=back
+
 =cut
 
 sub opacity {
@@ -389,8 +603,4 @@ sub opacity {
 #    return $self->SUPER::outobjdeep(@opts);
 #}
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Resource/Font.pm b/lib/PDF/Builder/Resource/Font.pm
index d493940..fb1b88e 100644
--- a/lib/PDF/Builder/Resource/Font.pm
+++ b/lib/PDF/Builder/Resource/Font.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource::BaseFont';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use Encode qw(:all);
 
@@ -17,6 +17,18 @@ use PDF::Builder::Basic::PDF::Utils;
 
 PDF::Builder::Resource::Font - some common support routines for font files. Inherits from L<PDF::Builder::Resource::BaseFont>
 
+=head1 METHODS
+
+=head2 encodeByData
+
+     $font->encodeByData($enc)
+
+=over
+
+(No Information)
+
+=back
+
 =cut
 
 sub encodeByData {
@@ -102,11 +114,11 @@ sub encodeByData {
     return $self;
 }
 
-=head1 METHODS
+=head2 automap
 
-=over
+    $font->automap()
 
-=item $font->automap()
+=over
 
 This applies to core fonts (C<< $pdf->corefont() >>) and PostScript fonts 
 (C<< $pdf->psfont() >>). These cannot use UTF-8 (or other multibyte character) 
@@ -222,6 +234,18 @@ sub automap {
     return @fonts;
 }
 
+=head2 remap
+
+    $font->remap($enc)
+
+=over
+
+(No Information)
+
+=back
+
+=cut
+
 sub remap {
     my ($self, $enc) = @_;
 
diff --git a/lib/PDF/Builder/Resource/Font/BdFont.pm b/lib/PDF/Builder/Resource/Font/BdFont.pm
index bb4c23e..ffb026f 100644
--- a/lib/PDF/Builder/Resource/Font/BdFont.pm
+++ b/lib/PDF/Builder/Resource/Font/BdFont.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource::Font';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use PDF::Builder::Util;
 use PDF::Builder::Basic::PDF::Utils;
@@ -40,14 +40,16 @@ for body text!
 
 =head1 METHODS
 
-=over 4
+=head2 new
 
-=cut
+    $font = PDF::Builder::Resource::Font::BdFont->new($pdf, $font, %options)
 
-=item $font = PDF::Builder::Resource::Font::BdFont->new($pdf, $font, %options)
+=over
 
 Returns a BmpFont object.
 
+=back
+
 =cut
 
 #I<encode>
@@ -438,8 +440,6 @@ sub filled_circle {
 
 __END__
 
-=back
-
 =head1 AUTHOR
 
 Alfred Reibenschuh, extensively rewritten by Phil Perry
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont.pm b/lib/PDF/Builder/Resource/Font/CoreFont.pm
index f615f9a..4c4da67 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource::Font';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use File::Basename;
 
@@ -38,9 +38,11 @@ PDF::Builder::Resource::Font::CoreFont - Module for using the 14 standard PDF bu
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    $font = PDF::Builder::Resource::Font::CoreFont->new($pdf, $fontname, %options)
 
-=item $font = PDF::Builder::Resource::Font::CoreFont->new($pdf, $fontname, %options)
+=over
 
 Returns a corefont object.
 
@@ -48,12 +50,15 @@ Valid %options are:
 
 =over
 
-I<encode>
-... changes the encoding of the font from its default.
+=item encode
+
+Changes the encoding of the font from its default.
 See I<perl's Encode> for the supported values. B<Warning:> only single byte 
 encodings are permitted. Multibyte encodings such as 'utf8' are forbidden.
 
-I<pdfname> ... changes the reference-name of the font from its default.
+=item pdfname
+
+Changes the reference-name of the font from its default.
 The reference-name is normally generated automatically and can be
 retrieved via C<$pdfname=$font->name()>.
 
@@ -67,23 +72,19 @@ B<standard PDF types>
 
 =over
 
-=over
-
-=item * helvetica helveticaoblique helveticabold helvetiaboldoblique
+=item * helvetica, helveticaoblique, helveticabold, helvetiaboldoblique
 
 May have Arial substituted on some systems (e.g., Windows)
 
-=item * courier courieroblique courierbold courierboldoblique
+=item * courier, courieroblique, courierbold, courierboldoblique
 
 Fixed pitch, may have Courier New substituted on some systems (e.g., Windows)
 
-=item * timesroman timesitalic timesbold timesbolditalic
+=item * timesroman, timesitalic, timesbold, timesbolditalic
 
 May have Times New Roman substituted on some systems (e.g., Windows)
 
-=item * symbol zapfdingbats
-
-=back
+=item * symbol, zapfdingbats
 
 =back
 
@@ -91,21 +92,17 @@ B<Primarily Windows typefaces>
 
 =over
 
-=over
-
-=item * georgia georgiaitalic georgiabold georgiabolditalic
-
-=item * verdana verdanaitalic verdanabold verdanabolditalic
+=item * georgia, georgiaitalic, georgiabold, georgiabolditalic
 
-=item * trebuchet trebuchetitalic trebuchetbold trebuchetbolditalic
+=item * verdana, verdanaitalic, verdanabold, verdanabolditalic
 
-=item * bankgothic bankgothicitalic bankgothicbold bankgothicitalic
+=item * trebuchet, trebuchetitalic, trebuchetbold, trebuchetbolditalic
 
-Free versions of Bank Gothic are often only medium weight.
+=item * bankgothic, bankgothicitalic, bankgothicbold, bankgothicitalic
 
-=item * webdings wingdings
+Free versions of Bank Gothic are often only medium weight Roman (bankgothic).
 
-=back
+=item * webdings, wingdings
 
 =back
 
@@ -253,13 +250,17 @@ sub new {
     return $self;
 }
 
-=over
+=head2 is_standard
+
+    $bool = $class->is_standard($name)
 
-=item $bool = $class->is_standard($name)
+=over
 
 Returns true if C<$name> is an exact, case-sensitive match for one of the
 standard font names shown above.
 
+=back
+
 =cut
 
 sub is_standard {
@@ -288,10 +289,16 @@ sub is_standard {
     return;
 }
 
-=item PDF::Builder::Resource::Font::CoreFont->loadallfonts()
+=head2 loadallfonts
+
+    PDF::Builder::Resource::Font::CoreFont->loadallfonts()
+
+=over
 
 "Requires in" all fonts available as corefonts.
 
+=back
+
 =cut
 
 sub loadallfonts {
@@ -426,8 +433,6 @@ BEGIN
 
 __END__
 
-=back
-
 =head1 AUTHOR
 
 Alfred Reibenschuh
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/bankgothic.pm b/lib/PDF/Builder/Resource/Font/CoreFont/bankgothic.pm
index f27f6ee..38c55d0 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/bankgothic.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/bankgothic.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::bankgothic;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.013'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/courier.pm b/lib/PDF/Builder/Resource/Font/CoreFont/courier.pm
index fc4131c..1f51b22 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/courier.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/courier.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::courier;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.019'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/courierbold.pm b/lib/PDF/Builder/Resource/Font/CoreFont/courierbold.pm
index 4d57b24..0ca600e 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/courierbold.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/courierbold.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::courierbold;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.019'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/courierboldoblique.pm b/lib/PDF/Builder/Resource/Font/CoreFont/courierboldoblique.pm
index 1d97ebd..dfd06d9 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/courierboldoblique.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/courierboldoblique.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::courierboldoblique;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.019'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/courieroblique.pm b/lib/PDF/Builder/Resource/Font/CoreFont/courieroblique.pm
index 0817c06..30fa9af 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/courieroblique.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/courieroblique.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::courieroblique;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.019'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/georgia.pm b/lib/PDF/Builder/Resource/Font/CoreFont/georgia.pm
index 12c16f9..b1993b4 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/georgia.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/georgia.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::georgia;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.018'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/georgiabold.pm b/lib/PDF/Builder/Resource/Font/CoreFont/georgiabold.pm
index 034514e..006ebeb 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/georgiabold.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/georgiabold.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::georgiabold;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.018'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/georgiabolditalic.pm b/lib/PDF/Builder/Resource/Font/CoreFont/georgiabolditalic.pm
index f55159b..b2d319d 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/georgiabolditalic.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/georgiabolditalic.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::georgiabolditalic;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.018'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/georgiaitalic.pm b/lib/PDF/Builder/Resource/Font/CoreFont/georgiaitalic.pm
index 2cef3b3..4cbb3e8 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/georgiaitalic.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/georgiaitalic.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::georgiaitalic;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.018'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/helvetica.pm b/lib/PDF/Builder/Resource/Font/CoreFont/helvetica.pm
index 23d4825..dee3ec4 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/helvetica.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/helvetica.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::helvetica;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.019'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/helveticabold.pm b/lib/PDF/Builder/Resource/Font/CoreFont/helveticabold.pm
index 6d73bc0..a4479d9 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/helveticabold.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/helveticabold.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::helveticabold;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.019'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/helveticaboldoblique.pm b/lib/PDF/Builder/Resource/Font/CoreFont/helveticaboldoblique.pm
index 111137d..3381eed 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/helveticaboldoblique.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/helveticaboldoblique.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::helveticaboldoblique;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.019'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/helveticaoblique.pm b/lib/PDF/Builder/Resource/Font/CoreFont/helveticaoblique.pm
index f7fd3ac..5158348 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/helveticaoblique.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/helveticaoblique.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::helveticaoblique;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.019'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/symbol.pm b/lib/PDF/Builder/Resource/Font/CoreFont/symbol.pm
index d010f89..baa9a03 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/symbol.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/symbol.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::symbol;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.019'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/timesbold.pm b/lib/PDF/Builder/Resource/Font/CoreFont/timesbold.pm
index 88bf02f..138d0ff 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/timesbold.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/timesbold.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::timesbold;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.019'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/timesbolditalic.pm b/lib/PDF/Builder/Resource/Font/CoreFont/timesbolditalic.pm
index eba4bca..c14edd9 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/timesbolditalic.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/timesbolditalic.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::timesbolditalic;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.019'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/timesitalic.pm b/lib/PDF/Builder/Resource/Font/CoreFont/timesitalic.pm
index ea4a9d9..6c8b9b4 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/timesitalic.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/timesitalic.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::timesitalic;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.019'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/timesroman.pm b/lib/PDF/Builder/Resource/Font/CoreFont/timesroman.pm
index 1a162d7..45eacce 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/timesroman.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/timesroman.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::timesroman;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.019'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/trebuchet.pm b/lib/PDF/Builder/Resource/Font/CoreFont/trebuchet.pm
index 421c8e5..b0f8c43 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/trebuchet.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/trebuchet.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::trebuchet;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.018'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/trebuchetbold.pm b/lib/PDF/Builder/Resource/Font/CoreFont/trebuchetbold.pm
index 9f36303..c0d15f7 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/trebuchetbold.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/trebuchetbold.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::trebuchetbold;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.018'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/trebuchetbolditalic.pm b/lib/PDF/Builder/Resource/Font/CoreFont/trebuchetbolditalic.pm
index dbac4e1..7cd6010 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/trebuchetbolditalic.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/trebuchetbolditalic.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::trebuchetbolditalic;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.018'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/trebuchetitalic.pm b/lib/PDF/Builder/Resource/Font/CoreFont/trebuchetitalic.pm
index 0898a60..368f921 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/trebuchetitalic.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/trebuchetitalic.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::trebuchetitalic;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.018'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/verdana.pm b/lib/PDF/Builder/Resource/Font/CoreFont/verdana.pm
index a89e690..be6a4c0 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/verdana.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/verdana.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::verdana;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.018'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/verdanabold.pm b/lib/PDF/Builder/Resource/Font/CoreFont/verdanabold.pm
index 4f941ad..3509f2b 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/verdanabold.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/verdanabold.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::verdanabold;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.018'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/verdanabolditalic.pm b/lib/PDF/Builder/Resource/Font/CoreFont/verdanabolditalic.pm
index a55484a..50019f0 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/verdanabolditalic.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/verdanabolditalic.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::verdanabolditalic;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.018'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/verdanaitalic.pm b/lib/PDF/Builder/Resource/Font/CoreFont/verdanaitalic.pm
index dc08552..0ac50eb 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/verdanaitalic.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/verdanaitalic.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::verdanaitalic;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.018'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/webdings.pm b/lib/PDF/Builder/Resource/Font/CoreFont/webdings.pm
index 58ec60d..df8d45e 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/webdings.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/webdings.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::webdings;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '2.029'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/wingdings.pm b/lib/PDF/Builder/Resource/Font/CoreFont/wingdings.pm
index 2aed6b9..5376345 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/wingdings.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/wingdings.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::wingdings;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '2.029'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/CoreFont/zapfdingbats.pm b/lib/PDF/Builder/Resource/Font/CoreFont/zapfdingbats.pm
index c39bf82..0547fe9 100644
--- a/lib/PDF/Builder/Resource/Font/CoreFont/zapfdingbats.pm
+++ b/lib/PDF/Builder/Resource/Font/CoreFont/zapfdingbats.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Font::CoreFont::zapfdingbats;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.019'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/Font/Postscript.pm b/lib/PDF/Builder/Resource/Font/Postscript.pm
index d7d98b8..544d7d5 100644
--- a/lib/PDF/Builder/Resource/Font/Postscript.pm
+++ b/lib/PDF/Builder/Resource/Font/Postscript.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource::Font';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use Encode qw(:all);
 use IO::File qw();
@@ -18,6 +18,19 @@ use PDF::Builder::Basic::PDF::Utils;
 
 PDF::Builder::Resource::Font::Postscript - support routines for using PostScript fonts. Inherits from L<PDF::Builder::Resource::Font>
 
+=head1 METHODS
+
+=head2 new
+
+    PDF::Builder::Resource::Font::Postscript->new($pdf, $psfile, %opts)
+
+=over
+
+Create an object for a PostScript font. Handles ASCII (.pfa), binary (.pfb), and
+T1 (.t1) font files, as well as ASCII (.afm) and binary (.pfm) metrics files.
+
+=back
+
 =cut
 
 sub new {
@@ -95,17 +108,29 @@ sub readPFAPFB {
     die "Cannot find PFA/PFB font file '$file' ..." unless -f $file;
 
     my $l = -s $file;
+    $l1 = $l2 = $l3 = 0;
+    $head = $body = $tail = '';
+
+    my $type = 'pfa';
+    if      ($file =~ m/\.pfb$/i) {
+	$type = 'pfb';
+    } elsif ($file =~ m/\.t1$/i) {
+	$type = 't1';
+    }
 
     open(my $inf, "<", $file) or die "$!: $file";
     binmode($inf,':raw');
-    read($inf, $line, 2);
+    read($inf, $line, 2); # read 2 bytes to check header
     @lines = unpack('C*', $line);
-    if      ($lines[0] == 0x80 && $lines[1] == 1) {
+
+    if      ($lines[0] == 0x80 && $lines[1] == 1) {  # .pfb
+	# first 6 bytes are 80 01, 4 byte LSB $l1 head length
         read($inf, $line, 4);
-        $l1 = unpack('V', $line);
+        $l1 = unpack('V', $line); # length of head
         seek($inf, $l1, 1);
         read($inf, $line, 2);
         @lines = unpack('C*', $line);
+	# at start of binary body, 6 bytes 80 01, 4 byte LSB $l2 body length
         if ($lines[0] == 0x80 && $lines[1] == 2) {
             read($inf, $line, 4);
             $l2 = unpack('V', $line);
@@ -115,6 +140,7 @@ sub readPFAPFB {
         seek($inf, $l2, 1);
         read($inf, $line, 2);
         @lines = unpack('C*', $line);
+	# after body, 6 bytes 80 01, 4 byte LSB $l3 tail length
         if ($lines[0] == 0x80 && $lines[1] == 1) {
             read($inf, $line, 4);
             $l3 = unpack('V', $line);
@@ -124,33 +150,84 @@ sub readPFAPFB {
         seek($inf, 0, 0);
         @lines = <$inf>;
         $stream = join('', @lines);
+	# each section, skip over 80 01, length; read in length of section
         $t1stream = substr($stream, 6, $l1);
         $t1stream .= substr($stream, 12+$l1, $l2);
         $t1stream .= substr($stream, 18+$l1+$l2, $l3);
-    } elsif ($line eq '%!') {
+
+    } elsif ($line eq '%!' && $type eq 'pfa') { 
         seek($inf, 0, 0);
         while ($line = <$inf>) {
-            if      (!$l1) {
-                $head .= $line;
+            if      (!$l1) {  # $head empty or not complete yet?
+                $head .= $line; # up through and including currentfile eexec
                 if ($line=~/eexec$/) {
                     chomp($head);
                     $head .= "\x0d";
                     $l1 = length($head);
                 }
-            } elsif (!$l2) {
-                if ($line =~ /^0+$/) {
+            } elsif (!$l2) {  # $body empty or not complete yet?
+                if ($line =~ /^0+$/) {  # at block of 0's, marking end of body
                     $l2 = length($body);
                     $tail = $line;
                 } else {
                     chomp($line);
-                    $body .= pack('H*', $line);
+                    $body .= pack('H*', $line); # binary form of hex codes
                 }
-            } else {
+            } else {  # rest goes into the $tail
                 $tail .= $line;
             }
         }
         $l3 = length($tail);
+	# head = individual lines (^M terminated) with settings list
+	# body = one long string of bytes (binary)
+	# tail = 8 lines x 64 0's ^M terminated, cleartomark (no ^M)
+        $t1stream = "$head$body$tail";
+
+    } elsif ($line eq '%!' && $type eq 't1') { 
+	# .t1
+	my $pos;
+        seek($inf, 0, 0);
+        while (1) { # head
+            read($inf, $line, 200);
+	    $head .= $line;
+	    $pos = index($head, "currentfile eexec\x0D");
+	    if ($pos > 0) {
+		# found end of head, so split there
+		$body = substr($head, $pos+18);
+		$head = substr($head, 0, $pos+18);
+		$l1 = length($head);
+		last;
+	    }
+	}
+	while (1) { # body
+            read($inf, $line, 200);
+	    $body .= $line;
+	    #                             1111111111222222222233333333334444444444555555555566666
+	    #                    1234567890123456789012345678901234567890123456789012345678901234
+	    $pos = index($body, "0000000000000000000000000000000000000000000000000000000000000000");
+	    if ($pos > 0) {
+		# found end of body, so split there
+		$tail = substr($body, $pos);
+		$body = substr($body, 0, $pos);
+		$l2 = length($body);
+		last;
+	    }
+	}
+	while (1) { # remainder into tail
+            read($inf, $line, 200);
+	    $tail .= $line;
+	    if (length($line) == 0) {
+		# found end of tail
+		$l3 = length($tail);
+		last;
+	    }
+	}
+
+	# head = individual lines (^M terminated) with settings list
+	# body = one long string of bytes (binary)
+	# tail = 8 lines x 64 0's ^M terminated, cleartomark (no ^M)
         $t1stream = "$head$body$tail";
+
     } else {
         die "Unsupported font-format in file '$file' at marker='1'.";
     }
diff --git a/lib/PDF/Builder/Resource/Font/SynFont.pm b/lib/PDF/Builder/Resource/Font/SynFont.pm
index 47a9712..906a7d9 100644
--- a/lib/PDF/Builder/Resource/Font/SynFont.pm
+++ b/lib/PDF/Builder/Resource/Font/SynFont.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource::Font';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use Math::Trig;    # CAUTION: deg2rad(0) = deg2rad(360) = 0!
 use Unicode::UCD 'charinfo';
@@ -49,9 +49,11 @@ This is for compatibility with recent changes to PDF::API2.
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    $font = PDF::Builder::Resource::Font::SynFont->new($pdf, $fontobj, %opts)
 
-=item $font = PDF::Builder::Resource::Font::SynFont->new($pdf, $fontobj, %opts)
+=over
 
 Returns a synfont object. C<$fontobj> is a normal font object read in from
 a file, and C<$font> is the modified output.
diff --git a/lib/PDF/Builder/Resource/Glyphs.pm b/lib/PDF/Builder/Resource/Glyphs.pm
index 7a5fe99..8ccfda7 100644
--- a/lib/PDF/Builder/Resource/Glyphs.pm
+++ b/lib/PDF/Builder/Resource/Glyphs.pm
@@ -3,7 +3,7 @@ package PDF::Builder::Resource::Glyphs;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/PaperSizes.pm b/lib/PDF/Builder/Resource/PaperSizes.pm
index 2ec08e2..73e1bcb 100644
--- a/lib/PDF/Builder/Resource/PaperSizes.pm
+++ b/lib/PDF/Builder/Resource/PaperSizes.pm
@@ -3,8 +3,8 @@ package PDF::Builder::Resource::PaperSizes;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 =head1 NAME
 
@@ -45,8 +45,6 @@ lot of work!
 
 =head3 Metric sizes
 
-=over
-
       4a0 --  4760 x 6716 (1679 mm x 2639 mm)
 
       2a0 --  3368 x 4760 (1188 mm x 1679 mm)
@@ -157,24 +155,17 @@ lot of work!
 
       p6 --  303 x 397 (107 mm x 140 mm)
 
-=back
-
 =head3 Mixed sizes
 
-=over
-
       universal --  595 x 792 (210 mm x 11 in)
 
 This is not a standard or official size, but a PDF::Builder size, which should 
 print OK on either A4 or US Letter paper size. It is narrow (like A4) and short 
-(like letter).
-
-=back
+(like letter). Your content will be in the lower left of the paper, when
+printed, with extra top margin on A4 or extra right margin on Letter.
 
 =head3 US/British (non-metric) sizes
 
-=over
-
       broadsheet --  1296 x 1584 (18 in x 22 in) sometimes 1224 x 1584!
 
       executive --  522 x 756 (7.25 in x 10.5 in)
@@ -261,8 +252,6 @@ print OK on either A4 or US Letter paper size. It is narrow (like A4) and short
 
       imperial --  540 x 792 (7.5 in x 11 in)
 
-=back
-
 =cut
 
 # see sites such as https://www.papersizes.org/ for all the paper size
diff --git a/lib/PDF/Builder/Resource/Pattern.pm b/lib/PDF/Builder/Resource/Pattern.pm
index 2ef547f..95867d2 100644
--- a/lib/PDF/Builder/Resource/Pattern.pm
+++ b/lib/PDF/Builder/Resource/Pattern.pm
@@ -5,13 +5,25 @@ use base 'PDF::Builder::Resource';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '2.031'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 =head1 NAME
 
 PDF::Builder::Resource::Pattern - support stub for patterns. Inherits from L<PDF::Builder::Resource>
 
+=head1 METHODS
+
+=head2 new
+
+    PDF::Builder::Resource::Pattern->new()
+
+=over
+
+Create a new pattern object.
+
+=back
+
 =cut
 
 sub new {
diff --git a/lib/PDF/Builder/Resource/Shading.pm b/lib/PDF/Builder/Resource/Shading.pm
index 747477e..ad51f1c 100644
--- a/lib/PDF/Builder/Resource/Shading.pm
+++ b/lib/PDF/Builder/Resource/Shading.pm
@@ -5,7 +5,7 @@ use base 'PDF::Builder::Resource';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '2.029'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Resource/UniFont.pm b/lib/PDF/Builder/Resource/UniFont.pm
index 69afdcc..a7a6452 100644
--- a/lib/PDF/Builder/Resource/UniFont.pm
+++ b/lib/PDF/Builder/Resource/UniFont.pm
@@ -3,8 +3,8 @@ package PDF::Builder::Resource::UniFont;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use Carp;
 use Encode qw(:all);
@@ -15,15 +15,13 @@ PDF::Builder::Resource::UniFont - Unicode Font Support
 
 =head1 METHODS
 
-=over
-
-=item $font = PDF::Builder::Resource::UniFont->new($pdf, @fontspecs, %options)
+=head2 new
 
-Returns a uni-font object.
+    $font = PDF::Builder::Resource::UniFont->new($pdf, @fontspecs, %options)
 
-=cut
+=over
 
-=pod
+Returns a uni-font object.
 
 B<FONTSPECS:> fonts can be registered using the following hash-ref:
 
@@ -55,6 +53,8 @@ Valid %options are:
   'encode' ... changes the encoding of the font from its default.
     (see "perldoc Encode" for a list of valid tags)
 
+=back
+
 =cut
 
 sub new {
@@ -134,16 +134,52 @@ sub new {
     return $self;
 }
 
+=head2 isvirtual
+
+    $flag = $font->isvirtual()
+
+=over
+
+(No Information)
+
+=back
+
+=cut
+
 sub isvirtual { 
     return 1; 
 }
 
+=head2 fontlist
+
+    $font->fontlist()
+
+=over
+
+(No Information)
+
+=back
+
+=cut
+
 sub fontlist {
     my $self = shift;
 
     return [@{ $self->{'fonts'} }];
 }
 
+=head2 width
+
+    $w = $font->width($string)
+
+=over
+
+(No Information)
+
+=back
+
+=cut
+
 sub width {
     my ($self, $text) = @_;
 
@@ -176,6 +212,18 @@ sub width {
     return $width;
 }
 
+=head2 text
+
+    $font->text($string, $size, $indent)
+
+=over
+
+(No Information)
+
+=back
+
+=cut
+
 sub text {
     my ($self, $text, $size, $indent) = @_;
 
@@ -218,8 +266,4 @@ sub text {
     return $newtext;
 }
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Resource/XObject.pm b/lib/PDF/Builder/Resource/XObject.pm
index 93355e0..e2b2ee5 100644
--- a/lib/PDF/Builder/Resource/XObject.pm
+++ b/lib/PDF/Builder/Resource/XObject.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '2.031'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use PDF::Builder::Basic::PDF::Utils;
 
@@ -16,12 +16,16 @@ PDF::Builder::Resource::XObject - Base class for external objects
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    $xobject = PDF::Builder::Resource::XObject->new($pdf, $name)
 
-=item $xobject = PDF::Builder::Resource::XObject->new($pdf, $name)
+=over
 
 Creates an XObject resource.
 
+=back
+
 =cut
 
 sub new {
@@ -34,10 +38,16 @@ sub new {
     return $self;
 }
 
-=item $type = $xobject->subtype($type)
+=head2 subtype
+
+    $type = $xobject->subtype($type)
+
+=over
 
 Get or set the Subtype of the XObject resource.
 
+=back
+
 =cut
 
 sub subtype {
@@ -49,8 +59,4 @@ sub subtype {
     return $self->{'Subtype'}->val();
 }
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Resource/XObject/Form.pm b/lib/PDF/Builder/Resource/XObject/Form.pm
index a251b4c..16ab2af 100644
--- a/lib/PDF/Builder/Resource/XObject/Form.pm
+++ b/lib/PDF/Builder/Resource/XObject/Form.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource::XObject';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '2.031'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use PDF::Builder::Basic::PDF::Utils;
 
@@ -16,12 +16,16 @@ PDF::Builder::Resource::XObject::Form - Base class for external form objects
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    $form = PDF::Builder::Resource::XObject::Form->new($pdf)
 
-=item $form = PDF::Builder::Resource::XObject::Form->new($pdf)
+=over
 
 Creates a form resource.
 
+=back
+
 =cut
 
 sub new {
@@ -35,9 +39,15 @@ sub new {
     return $self;
 }
 
-=item ($llx, $lly, $urx, $ury) = $form->bbox($llx, $lly, $urx, $ury)
+=head2 bbox
 
-Get or set the coordinates of the form object's bounding box
+    ($llx, $lly, $urx, $ury) = $form->bbox($llx, $lly, $urx, $ury)
+
+=over
+
+Get or set the coordinates of the form object's bounding box.
+
+=back
 
 =cut
 
@@ -51,14 +61,20 @@ sub bbox {
     return map { $_->val() } $self->{'BBox'}->elements();
 }
 
-=item $resource = $form->resource($type, $key)
+=head2 resource
 
-=item $form->resource($type, $key, $object, $force)
+    $resource = $form->resource($type, $key)
+
+    $form->resource($type, $key, $object, $force)
+
+=over
 
 Get or add a resource required by the form's contents, such as a Font, XObject, ColorSpace, etc.
 
 By default, an existing C<$key> will not be overwritten. Set C<$force> to override this behavior.
 
+=back
+
 =cut
 
 sub resource {
@@ -87,8 +103,4 @@ sub resource {
     return $dict;
 }
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Resource/XObject/Form/BarCode.pm b/lib/PDF/Builder/Resource/XObject/Form/BarCode.pm
index caf94ac..dc410e4 100644
--- a/lib/PDF/Builder/Resource/XObject/Form/BarCode.pm
+++ b/lib/PDF/Builder/Resource/XObject/Form/BarCode.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource::XObject::Form::Hybrid';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use PDF::Builder::Util;
 use PDF::Builder::Basic::PDF::Utils;
@@ -17,12 +17,16 @@ PDF::Builder::Resource::XObject::Form::BarCode - Base class for one-dimensional
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    $barcode = PDF::Builder::Resource::XObject::Form::BarCode->new($pdf, %options)
 
-=item $barcode = PDF::Builder::Resource::XObject::Form::BarCode->new($pdf, %options)
+=over
 
 Creates a barcode form resource.
 
+=back
+
 =cut
 
 sub new {
@@ -179,7 +183,15 @@ sub drawbar {
     return;
 }
 
-=item $width = $barcode->width()
+=head2 width
+
+    $width = $barcode->width()
+
+=over
+
+Returns the width of the bar code.
+
+=back
 
 =cut
 
@@ -189,18 +201,23 @@ sub width {
     return $self->{' w'};
 }
 
-=item $height = $barcode->height()
+=head2 height
+
+    $height = $barcode->height()
+
+=over
+
+Returns the height of the bar code.
+
+=back
 
 =cut
 
+
 sub height {
     my $self = shift;
 
     return $self->{' h'};
 }
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Resource/XObject/Form/BarCode/codabar.pm b/lib/PDF/Builder/Resource/XObject/Form/BarCode/codabar.pm
index f6276aa..dbc3c7e 100644
--- a/lib/PDF/Builder/Resource/XObject/Form/BarCode/codabar.pm
+++ b/lib/PDF/Builder/Resource/XObject/Form/BarCode/codabar.pm
@@ -5,13 +5,26 @@ use base 'PDF::Builder::Resource::XObject::Form::BarCode';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 =head1 NAME
 
 PDF::Builder::Resource::XObject::Form::BarCode::codabar - specific information for CodaBar bar codes. Inherits from L<PDF::Builder::Resource::XObject::Form::BarCode>
 
+=head1 METHODS
+
+=head2 new
+
+    PDF::Builder::Resource::XObject::Form::BarCode::codabar->new()
+
+=over
+
+Create a Codabar bar code object. Note that it is invoked from the Builder.pm
+level method!
+
+=back
+
 =cut
 
 # TBD document code, caption options
diff --git a/lib/PDF/Builder/Resource/XObject/Form/BarCode/code128.pm b/lib/PDF/Builder/Resource/XObject/Form/BarCode/code128.pm
index 1d582ae..93fc5bc 100644
--- a/lib/PDF/Builder/Resource/XObject/Form/BarCode/code128.pm
+++ b/lib/PDF/Builder/Resource/XObject/Form/BarCode/code128.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource::XObject::Form::BarCode';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 =head1 NAME
 
@@ -14,11 +14,14 @@ PDF::Builder::Resource::XObject::Form::BarCode::code128 - Code 128 and EAN-128 b
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    $res = PDF::Builder::Resource::XObject::Form::BarCode::code128->new($pdf, %options)
 
-=item $res = PDF::Builder::Resource::XObject::Form::BarCode::code128->new($pdf, %options)
+=over
 
 Returns a code128 object. Use 'ean' option to encode using EAN128 mode.
+Note that this should be invoked via the Builder.pm method!
 
 =back
 
diff --git a/lib/PDF/Builder/Resource/XObject/Form/BarCode/code3of9.pm b/lib/PDF/Builder/Resource/XObject/Form/BarCode/code3of9.pm
index eba3c9f..d937786 100644
--- a/lib/PDF/Builder/Resource/XObject/Form/BarCode/code3of9.pm
+++ b/lib/PDF/Builder/Resource/XObject/Form/BarCode/code3of9.pm
@@ -5,13 +5,26 @@ use base 'PDF::Builder::Resource::XObject::Form::BarCode';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 =head1 NAME
 
 PDF::Builder::Resource::XObject::Form::BarCode::code3of9 - specific information for 3-of-9 bar codes. Inherits from L<PDF::Builder::Resource::XObject::Form::BarCode>
 
+=head1 METHODS
+
+=head2 new
+
+    PDF::Builder::Resource::XObject::Form::BarCode::code3of9->new()
+
+=over
+
+Create a Code 3 of 9 bar code object. Note that it is invoked from the 
+Builder.pm level method!
+
+=back
+
 =cut
 
 sub new {
diff --git a/lib/PDF/Builder/Resource/XObject/Form/BarCode/ean13.pm b/lib/PDF/Builder/Resource/XObject/Form/BarCode/ean13.pm
index ecdd89e..57bd07c 100644
--- a/lib/PDF/Builder/Resource/XObject/Form/BarCode/ean13.pm
+++ b/lib/PDF/Builder/Resource/XObject/Form/BarCode/ean13.pm
@@ -5,13 +5,26 @@ use base 'PDF::Builder::Resource::XObject::Form::BarCode';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 =head1 NAME
 
 PDF::Builder::Resource::XObject::Form::BarCode::ean13 - specific information for EAN-13 bar codes. Inherits from L<PDF::Builder::Resource::XObject::Form::BarCode>
 
+=head1 METHODS
+
+=head2 new
+
+    PDF::Builder::Resource::XObject::Form::BarCode::ean13->new()
+
+=over
+
+Create an EAN-13 bar code object. Note that it is invoked from the Builder.pm
+level method!
+
+=back
+
 =cut
 
 sub new {
diff --git a/lib/PDF/Builder/Resource/XObject/Form/BarCode/int2of5.pm b/lib/PDF/Builder/Resource/XObject/Form/BarCode/int2of5.pm
index 8294a65..a0a7387 100644
--- a/lib/PDF/Builder/Resource/XObject/Form/BarCode/int2of5.pm
+++ b/lib/PDF/Builder/Resource/XObject/Form/BarCode/int2of5.pm
@@ -5,12 +5,25 @@ use base 'PDF::Builder::Resource::XObject::Form::BarCode';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 =head1 NAME
 
-PDF::Builder::Resource::XObject::Form::BarCode::int2of5 - specific information for int 2-of-5 bar codes. Inherits from L<PDF::Builder::Resource::XObject::Form::BarCode>
+PDF::Builder::Resource::XObject::Form::BarCode::int2of5 - specific information for interleaved 2-of-5 bar codes. Inherits from L<PDF::Builder::Resource::XObject::Form::BarCode>
+
+=head1 METHODS
+
+=head2 new
+
+    PDF::Builder::Resource::XObject::Form::BarCode::int2of5->new()
+
+=over
+
+Create an Interleaved 2 of 5 bar code object. Note that it is invoked from the 
+Builder.pm level method!
+
+=back
 
 =cut
 
diff --git a/lib/PDF/Builder/Resource/XObject/Form/Hybrid.pm b/lib/PDF/Builder/Resource/XObject/Form/Hybrid.pm
index 182672c..97238bf 100644
--- a/lib/PDF/Builder/Resource/XObject/Form/Hybrid.pm
+++ b/lib/PDF/Builder/Resource/XObject/Form/Hybrid.pm
@@ -5,8 +5,8 @@ use base qw(PDF::Builder::Content PDF::Builder::Content::Text PDF::Builder::Reso
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.016'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use PDF::Builder::Basic::PDF::Dict;
 use PDF::Builder::Basic::PDF::Utils;
@@ -15,6 +15,18 @@ use PDF::Builder::Resource::XObject::Form;
 
 PDF::Builder::Resource::XObject::Form::Hybrid - support routines for Forms. Inherits from L<PDF::Builder::Content>, L<PDF::Builder::Content::Text>, and L<PDF::Builder::Resource::XObject::Form>
 
+=head1 METHODS
+
+=head2 new
+
+    PDF::Builder::Resource::XObject::Form->new(args)
+
+=over
+
+Create a new object for a form.
+
+=back
+
 =cut
 
 sub new {
@@ -27,7 +39,7 @@ sub new {
     $self->{' charspace'}   = 0;
     $self->{' hscale'}      = 100;
     $self->{' wordspace'}   = 0;
-    $self->{' lead'}        = 0;
+    $self->{' leading'}     = 0;
     $self->{' rise'}        = 0;
     $self->{' render'}      = 0;
     $self->{' matrix'}      = [1, 0, 0, 1, 0, 0];
@@ -57,7 +69,7 @@ sub outobjdeep {
 #   # missing: stream, poststream, apiistext
 #   # added:   api, apipdf, apipage
 #   foreach my $key (qw(api apipdf apipage font fontsize charspace hscale
-#                       wordspace lead rise render matrix fillcolor
+#                       wordspace leading rise render matrix fillcolor
 #                       strokecolor translate scale skew rotate)) {
 #       delete $self->{" $key"};
 #   }
diff --git a/lib/PDF/Builder/Resource/XObject/Image.pm b/lib/PDF/Builder/Resource/XObject/Image.pm
index fec9b71..5428f08 100644
--- a/lib/PDF/Builder/Resource/XObject/Image.pm
+++ b/lib/PDF/Builder/Resource/XObject/Image.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource::XObject';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.017'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use PDF::Builder::Basic::PDF::Utils;
 
@@ -16,12 +16,16 @@ PDF::Builder::Resource::XObject::Image - Base class for external raster image ob
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    $image = PDF::Builder::Resource::XObject::Image->new($pdf, $name)
 
-=item $image = PDF::Builder::Resource::XObject::Image->new($pdf, $name)
+=over
 
 Returns an image resource object.
 
+=back
+
 =cut
 
 sub new {
@@ -34,9 +38,22 @@ sub new {
     return $self;
 }
 
-=item $width = $image->width($width)
+=head2 width
+
+    $width = $image->width()
+
+=over
+
+Get the width (in points) of the image object.
+
+B<Note> that this function also has the ability to I<set> the width,
+by giving the new width (in points), but it appears that it never 
+worked correctly. The I<set> capability has been B<deprecated>, and 
+is scheduled to be removed some time after October, 2025. If you are
+using the C<width()> method in some manner to I<set> the image width,
+please let us know, so we can plan to keep it enabled!
 
-Get or set the width value for the image object.
+=back
 
 =cut
 
@@ -47,9 +64,22 @@ sub width {
     return $self->{'Width'}->val();
 }
 
-=item $height = $image->height($height)
+=head2 height
+
+    $height = $image->height()
+
+=over
+
+Get the height (in points) of the image object.
 
-Get or set the height value for the image object.
+B<Note> that this function also has the ability to I<set> the height,
+by giving the new height (in points), but it appears that it never 
+worked correctly. The I<set> capability has been B<deprecated>, and 
+is scheduled to be removed some time after October, 2025. If you are
+using the C<height()> method in some manner to I<set> the image height,
+please let us know, so we can plan to keep it enabled!
+
+=back
 
 =cut
 
@@ -60,10 +90,38 @@ sub height {
     return $self->{'Height'}->val();
 }
 
-=item $image->smask($xobject)
+## probably not useful, so do not add, for now
+#=head2 bbox
+#
+#    ($x1,$x2, $w,$h) = $image->bbox()
+#
+#=over
+#
+#Get the image dimensions similarly to a form's I<bounding box>. 
+#Note that the C<$x1> and C<$x2> values will always be 0.
+#
+#This method is offered as an alternative to the C<width> and C<height> methods.
+#
+#=back
+#
+#=cut
+#
+#sub bbox {
+#    my $self = shift();
+#    my @bb = (0,0, $self->width(),$self->height());
+#    return @bb;
+#}
+
+=head2 smask
+
+    $image->smask($xobject)
+
+=over
 
 Set the soft-mask image object.
 
+=back
+
 =cut
 
 sub smask {
@@ -73,13 +131,19 @@ sub smask {
     return $self;
 }
 
-=item $image->mask(@color_range)
+=head2 mask
+
+    $image->mask(@color_range)
 
-=item $image->mask($xobject)
+    $image->mask($xobject)
+
+=over
 
 Set the mask to an image mask XObject or an array containing a range
 of colors to be applied as a color key mask.
 
+=back
+
 =cut
 
 sub mask {
@@ -96,9 +160,13 @@ sub mask {
 
 # imask() functionality rolled into mask()
 
-=item $image->colorspace($name)
+=head2 colorspace
+
+    $image->colorspace($name)
 
-=item $image->colorspace($array)
+    $image->colorspace($array)
+
+=over
 
 Set the color space used by the image. Depending on the color space,
 this will either be just the name of the color space, or it will be an
@@ -108,6 +176,8 @@ If passing an array, parameters must already be encoded as PDF
 objects. The array itself may also be a PDF object. If not, one will
 be created.
 
+=back
+
 =cut
 
 sub colorspace {
@@ -124,10 +194,16 @@ sub colorspace {
     return $self;
 }
 
-=item $image->bits_per_component($integer)
+=head2 bits_per_component
+
+    $image->bits_per_component($integer)
+
+=over
 
 Set the number of bits used to represent each color component.
 
+=back
+
 =cut
 
 sub bits_per_component {
@@ -140,8 +216,4 @@ sub bits_per_component {
 
 # bpc() renamed to bits_per_component()
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Resource/XObject/Image/GD.pm b/lib/PDF/Builder/Resource/XObject/Image/GD.pm
index c3e091a..2514bde 100644
--- a/lib/PDF/Builder/Resource/XObject/Image/GD.pm
+++ b/lib/PDF/Builder/Resource/XObject/Image/GD.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource::XObject::Image';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use PDF::Builder::Util;
 use PDF::Builder::Basic::PDF::Utils;
@@ -18,9 +18,11 @@ PDF::Builder::Resource::XObject::Image::GD - support routines for Graphics Devel
 
 =head1 METHODS
 
-=over 
+=head2 new
 
-=item $res = PDF::Builder::Resource::XObject::Image::GD->new($pdf, $file, %opts)
+    $res = PDF::Builder::Resource::XObject::Image::GD->new($pdf, $file, %opts)
+
+=over
 
 Options:
 
@@ -36,6 +38,9 @@ Use lossless compression.
 
 =back
 
+An image object is created from GD input. Note that this should be invoked
+from Builder.pm's method.
+
 =back
 
 =cut
diff --git a/lib/PDF/Builder/Resource/XObject/Image/GIF.pm b/lib/PDF/Builder/Resource/XObject/Image/GIF.pm
index 6617a48..e8e91b7 100644
--- a/lib/PDF/Builder/Resource/XObject/Image/GIF.pm
+++ b/lib/PDF/Builder/Resource/XObject/Image/GIF.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource::XObject::Image';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use IO::File;
 use PDF::Builder::Util;
@@ -162,6 +162,21 @@ sub deGIF {
     return $out;
 }
 
+=head1 METHODS
+
+=head2 new
+
+     PDF::Builder::Resource::XObject::Image::GIF->new()
+
+=over
+
+Create an image object from a GIF input file.
+Remember that this should be invoked via the Builder.pm method!
+
+=back
+
+=cut
+
 sub new {
     my ($class, $pdf, $file, %opts) = @_;
     # copy dashed option names to preferred undashed names
diff --git a/lib/PDF/Builder/Resource/XObject/Image/JPEG.pm b/lib/PDF/Builder/Resource/XObject/Image/JPEG.pm
index ed2307e..86b1ef2 100644
--- a/lib/PDF/Builder/Resource/XObject/Image/JPEG.pm
+++ b/lib/PDF/Builder/Resource/XObject/Image/JPEG.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource::XObject::Image';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use IO::File;
 use PDF::Builder::Util;
@@ -19,9 +19,11 @@ PDF::Builder::Resource::XObject::Image::JPEG - support routines for JPEG image l
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    $res = PDF::Builder::Resource::XObject::Image::JPEG->new($pdf, $file, %opts)
 
-=item $res = PDF::Builder::Resource::XObject::Image::JPEG->new($pdf, $file, %opts)
+=over
 
 Options:
 
diff --git a/lib/PDF/Builder/Resource/XObject/Image/PNG.pm b/lib/PDF/Builder/Resource/XObject/Image/PNG.pm
index ae04d3a..f44a8f6 100644
--- a/lib/PDF/Builder/Resource/XObject/Image/PNG.pm
+++ b/lib/PDF/Builder/Resource/XObject/Image/PNG.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource::XObject::Image';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use Compress::Zlib;
 use POSIX qw(ceil floor);
@@ -24,9 +24,11 @@ Inherits from L<PDF::Builder::Resource::XObject::Image>
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    $res = PDF::Builder::Resource::XObject::Image::PNG->new($pdf, $file, %opts)
 
-=item $res = PDF::Builder::Resource::XObject::Image::PNG->new($pdf, $file, %opts)
+=over
 
 Returns a PNG-image object. C<$pdf> is the PDF object being added to, C<$file>
 is the input PNG file, and the optional C<$name> of the new parent image object
@@ -51,6 +53,9 @@ This is the name you can give for the PNG image object. The default is Pxnnnn.
 
 =back
 
+Remember that you need to invoke the image_png method from Builder.pm in
+order to use this functionality.
+
 =back 
 
 =head2 Supported PNG types
@@ -385,9 +390,11 @@ sub new {
     return($self);
 }
 
-=over 
+=head2 usesLib
+
+    $mode = $png->usesLib()
 
-=item  $mode = $png->usesLib()
+=over
 
 Returns 1 if Image::PNG::Libpng installed and used, 0 if not installed, or -1 
 if installed but not used (nouseIPL option given to C<image_png>).
diff --git a/lib/PDF/Builder/Resource/XObject/Image/PNG_IPL.pm b/lib/PDF/Builder/Resource/XObject/Image/PNG_IPL.pm
index 0070633..00f20d4 100644
--- a/lib/PDF/Builder/Resource/XObject/Image/PNG_IPL.pm
+++ b/lib/PDF/Builder/Resource/XObject/Image/PNG_IPL.pm
@@ -5,7 +5,7 @@ use base 'PDF::Builder::Resource::XObject::Image';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
 
 use Compress::Zlib;
@@ -26,9 +26,11 @@ Inherits from L<PDF::Builder::Resource::XObject::Image>
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    $res = PDF::Builder::Resource::XObject::Image::PNG_IPL->new($pdf, $file, %opts)
 
-=item $res = PDF::Builder::Resource::XObject::Image::PNG_IPL->new($pdf, $file, %opts)
+=over
 
 Returns a PNG-image object. C<$pdf> is the PDF object being added to, C<$file>
 is the input PNG file, and the optional C<$name> of the new parent image object
@@ -58,6 +60,8 @@ This is the name you can give for the PNG image object. The default is Pxnnnn.
 
 =back
 
+Remember that you need to use Builder.pm's image_png to process PNG images.
+
 =back 
 
 =head2 Supported PNG types
@@ -578,9 +582,11 @@ sub new {
     return($self);
 }
 
-=over
+=head2 usesLib
+
+    $mode = $png->usesLib()
 
-=item  $mode = $png->usesLib()
+=over
 
 Returns 1 if Image::PNG::Libpng installed and used, 0 if not installed, or -1 
 if installed but not used (nouseIPL option given to C<image_png>).
diff --git a/lib/PDF/Builder/Resource/XObject/Image/PNM.pm b/lib/PDF/Builder/Resource/XObject/Image/PNM.pm
index 87617c3..f36f10a 100644
--- a/lib/PDF/Builder/Resource/XObject/Image/PNM.pm
+++ b/lib/PDF/Builder/Resource/XObject/Image/PNM.pm
@@ -7,8 +7,8 @@ use base 'PDF::Builder::Resource::XObject::Image';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use IO::File;
 use PDF::Builder::Util;
@@ -24,9 +24,11 @@ PDF::Builder::Resource::XObject::Image::PNM - support routines for PNM (Portable
 
 =head2 METHODS
 
-=over
+=head2 new
+
+    $res = PDF::Builder::Resource::XObject::Image::PNM->new($pdf, $file, %opts)
 
-=item $res = PDF::Builder::Resource::XObject::Image::PNM->new($pdf, $file, %opts)
+=over
 
 Options:
 
@@ -59,6 +61,9 @@ color) may be anything from 1 to 65535 (the same maximum for all three colors),
 with 0 being full black. If the maximum sample value is 255 or smaller, three
 bytes of raw binary data per pixel, otherwise six bytes.
 
+Remember that you need to use Builder.pm's image_pnm method to use this
+functionality.
+
 =cut
 
 # -------------------------------------------------------------------
diff --git a/lib/PDF/Builder/Resource/XObject/Image/TIFF.pm b/lib/PDF/Builder/Resource/XObject/Image/TIFF.pm
index 3391b69..0e28d26 100644
--- a/lib/PDF/Builder/Resource/XObject/Image/TIFF.pm
+++ b/lib/PDF/Builder/Resource/XObject/Image/TIFF.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource::XObject::Image';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use Compress::Zlib;
 
@@ -21,9 +21,11 @@ PDF::Builder::Resource::XObject::Image::TIFF - TIFF image support
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    $res = PDF::Builder::Resource::XObject::Image::TIFF->new($pdf, $file, %opts)
 
-=item  $res = PDF::Builder::Resource::XObject::Image::TIFF->new($pdf, $file, %opts)
+=over
 
 Returns a TIFF-image object.
 
@@ -41,6 +43,11 @@ This is the name you can give for the TIFF image object. The default is Ixnnnn.
 
 =back
 
+Remember that you need to use the Builder.pm method image_tiff in order to
+display a TIFF file.
+
+=back
+
 =cut
 
 sub new {
@@ -89,7 +96,11 @@ sub new {
     return $self;
 }
 
-=item  $mode = $tif->usesLib()
+=head2 usesLib
+
+    $mode = $tif->usesLib()
+
+=over
 
 Returns 1 if Graphics::TIFF installed and used, 0 if not installed, or -1 if
 installed but not used (nouseGT option given to C<image_tiff>).
@@ -100,6 +111,8 @@ advance of actually using it, in case you want to use some functionality
 available only in TIFF_GT. See the <PDF::Builder> LA_GT() call if you
 need to know in advance.
 
+=back
+
 =cut
 
 sub usesLib {
@@ -313,7 +326,11 @@ sub read_tiff {
     return $self;
 }
 
-=item $value = $tif->tiffTag($tag)
+=head2 tiffTag
+
+    $value = $tif->tiffTag($tag)
+
+=over
 
 returns the value of the internal tiff-tag.
 
@@ -323,6 +340,8 @@ B<Useful Tags:>
     xRes, yRes (dpi; pixel/cm if resUnit==3)
     resUnit
 
+=back
+
 =cut
 
 sub tiffTag {
@@ -330,8 +349,4 @@ sub tiffTag {
     return $self->{' tiff'}->{$tag};
 }
 
-=back
-
-=cut
-
 1;
diff --git a/lib/PDF/Builder/Resource/XObject/Image/TIFF/File.pm b/lib/PDF/Builder/Resource/XObject/Image/TIFF/File.pm
index c94aaab..37f960e 100644
--- a/lib/PDF/Builder/Resource/XObject/Image/TIFF/File.pm
+++ b/lib/PDF/Builder/Resource/XObject/Image/TIFF/File.pm
@@ -3,8 +3,8 @@ package PDF::Builder::Resource::XObject::Image::TIFF::File;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.023'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use IO::File;
 
@@ -12,6 +12,19 @@ use IO::File;
 
 PDF::Builder::Resource::XObject::Image::TIFF::File - support routines for TIFF image library
 
+=head1 METHODS
+
+=head2 new
+
+    PDF::Builder::Resource::XObject::Image::TIFF::File->new()
+
+=over
+
+Create a TIFF image object, I<not> using the Graphics::TIFF library.
+Remember to use the Builder.pm method image_tiff.
+
+=back
+
 =cut
 
 sub new {
diff --git a/lib/PDF/Builder/Resource/XObject/Image/TIFF/File_GT.pm b/lib/PDF/Builder/Resource/XObject/Image/TIFF/File_GT.pm
index 8c15d8d..985c384 100644
--- a/lib/PDF/Builder/Resource/XObject/Image/TIFF/File_GT.pm
+++ b/lib/PDF/Builder/Resource/XObject/Image/TIFF/File_GT.pm
@@ -3,8 +3,8 @@ package PDF::Builder::Resource::XObject::Image::TIFF::File_GT;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.023'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use IO::File;
 use Graphics::TIFF ':all';  # already confirmed to be installed
@@ -13,6 +13,19 @@ use Graphics::TIFF ':all';  # already confirmed to be installed
 
 PDF::Builder::Resource::XObject::Image::TIFF::File_GT - support routines for TIFF image library (Graphics::TIFF enabled)
 
+=head1 METHODS
+
+=head2 new
+
+    PDF::Builder::Resource::XObject::Image::TIFF::File_GT->new()
+
+=over
+
+Create an image object from TIFF input, using the Graphics::TIFF library.
+Remember to use the Builder.pm method image_tiff for this functionality.
+
+=back
+
 =cut
 
 sub new {
diff --git a/lib/PDF/Builder/Resource/XObject/Image/TIFF_GT.pm b/lib/PDF/Builder/Resource/XObject/Image/TIFF_GT.pm
index b3b8e46..c2c91e7 100644
--- a/lib/PDF/Builder/Resource/XObject/Image/TIFF_GT.pm
+++ b/lib/PDF/Builder/Resource/XObject/Image/TIFF_GT.pm
@@ -5,8 +5,8 @@ use base 'PDF::Builder::Resource::XObject::Image';
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use Compress::Zlib;
 
@@ -23,9 +23,11 @@ PDF::Builder::Resource::XObject::Image::TIFF_GT - TIFF image support
 
 =head1 METHODS
 
-=over
+=head2 new
+
+    $res = PDF::Builder::Resource::XObject::Image::TIFF_GT->new($pdf, $file, %opts)
 
-=item  $res = PDF::Builder::Resource::XObject::Image::TIFF_GT->new($pdf, $file, %opts)
+=over
 
 Returns a TIFF-image object. C<$pdf> is the PDF object being added to, C<$file>
 is the input TIFF file, and the optional C<$name> of the new parent image object
@@ -69,6 +71,8 @@ look into adding it as an option. According to Graphic::TIFF's owner
 (ticket RT 133955), this is coming directly from libtiff (as write to STDERR), 
 so he can't do anything about it!
 
+=back
+
 =cut
 
 sub new {
@@ -137,7 +141,11 @@ sub new {
     return $self;
 } # end of new()
 
-=item  $mode = $tif->usesLib()
+=head2 usesLib
+
+    $mode = $tif->usesLib()
+
+=over
 
 Returns 1 if Graphics::TIFF installed and used, 0 if not installed, or -1 if
 installed but not used (nouseGT option given to C<image_tiff>).
diff --git a/lib/PDF/Builder/UniWrap.pm b/lib/PDF/Builder/UniWrap.pm
index 97e162b..801d1c5 100644
--- a/lib/PDF/Builder/UniWrap.pm
+++ b/lib/PDF/Builder/UniWrap.pm
@@ -3,7 +3,7 @@ package PDF::Builder::UniWrap;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
 
 =head1 NAME
diff --git a/lib/PDF/Builder/Util.pm b/lib/PDF/Builder/Util.pm
index 9bbd076..ae40a9a 100644
--- a/lib/PDF/Builder/Util.pm
+++ b/lib/PDF/Builder/Util.pm
@@ -3,8 +3,8 @@ package PDF::Builder::Util;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.024'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 # note: $a and $b are "Magic variables" according to perlcritic, and so it
 # has conniptions over using them as variable names (even with "my"). so, I
@@ -686,26 +686,42 @@ sub defineName {
 
 Dimensions are in points.
 
-=over
+=head3 paper_size
+
+    @box_corners = paper_size($x1,$y1, $x2,$y2);
 
-=item @box_corners = paper_size($x1,$y1, $x2,$y2);
+=over
 
 Returns an array ($x1,$y1, $x2,$y2) (full bounding box).
 
-=item @box_corners = paper_size($x1,$y1);
+=back
+
+    @box_corners = paper_size($x1,$y1);
+
+=over
 
 Returns an array (0,0, $x1,$y1) (half bounding box).
 
-=item @box_corners = paper_size($media_name);
+=back
+
+    @box_corners = paper_size($media_name);
+
+=over
 
 Returns an array (0,0, paper_width,paper_height) for the named media.
 
-=item @box_corners = paper_size($x1);
+=back
+
+    @box_corners = paper_size($x1);
+
+=over
 
 Returns an array (0,0, $x1,$x1) (single quadratic).
 
 Otherwise, array (0,0, 612,792) (US Letter dimensions) is returned.
 
+=back
+
 =cut
 
 sub page_size {
@@ -729,13 +745,19 @@ sub page_size {
     }
 }
 
-=item %sizes = getPaperSizes();
+=head3 getPaperSizes
+
+    %sizes = getPaperSizes();
+
+=over
 
 Returns a hash containing the available paper size aliases as keys and
 their dimensions as a two-element array reference.
 
 See the source of L<PDF::Builder::Resource::PaperSizes> for the complete list.
 
+=back
+
 =cut
 
 sub getPaperSizes {
@@ -746,8 +768,6 @@ sub getPaperSizes {
     return %sizes;
 }
 
-=back
-
 =head2 STRING TO DIMENSION
 
 Convert a string "number [unit]" to the value in desired units. Units are
@@ -758,9 +778,11 @@ point, 72.27/inch), pc (pica, 6/inch), dd (Didot point, 67.5532/inch), and
 cc (Ciceros, 5.62943/inch). More can be added easily. 
 Invalid units are a fatal error.
 
-=over
+=head3 str2dim
+
+    $value = str2dim($string, $type, $default_units);
 
-=item $value = str2dim($string, $type, $default_units);
+=over
 
 C<$string> contains a number and optionally, a unit. Space(s) between the number
 and the unit are optional. E.g., '200', '35.2 mm', and '1.5in' are all allowable
diff --git a/lib/PDF/Builder/ViewerPreferences.pm b/lib/PDF/Builder/ViewerPreferences.pm
index bb7bb84..a5e326c 100644
--- a/lib/PDF/Builder/ViewerPreferences.pm
+++ b/lib/PDF/Builder/ViewerPreferences.pm
@@ -3,8 +3,8 @@ package PDF::Builder::ViewerPreferences;
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.025'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 use Carp;
 use PDF::Builder::Basic::PDF::Utils;
@@ -26,8 +26,6 @@ PDF::Builder::ViewerPreferences - How the PDF should be displayed or printed
 
 This has been split out from C<preferences()> in L<PDF::Builder>.
 
-=over
-
 =cut
 
 sub _snake_case {
@@ -47,10 +45,16 @@ sub _camel_case {
     return $name;
 }
 
-=item $self = $class->new($pdf)
+=head2 new
+
+    $self = $class->new($pdf)
+
+=over
 
 Creates a new ViewerPreferences object from a PDF::Builder object.
 
+=back
+
 =cut
 
 sub new {
@@ -60,11 +64,17 @@ sub new {
     return $self;
 }
 
-=item %preferences = $self->get_preferences()
+=head2 get_preferences
+
+    %preferences = $self->get_preferences()
+
+=over
 
 Returns a hash containing all of the viewer preferences that are defined in the
 PDF.
 
+=back
+
 =cut
 
 sub get_preferences {
@@ -107,11 +117,17 @@ sub get_preferences {
     return %values;
 }
 
-=item $value = $self->get_preference($name)
+=head2 get_preference
+
+    $value = $self->get_preference($name)
+
+=over
 
 Returns the value of the specified viewer preference if present, or C<undef> if
 not.
 
+=back
+
 =cut
 
 sub get_preference {
@@ -120,11 +136,17 @@ sub get_preference {
     return $values{$name};
 }
 
-=item $self->set_preferences(%values)
+=head2 set_preferences
+
+    $self->set_preferences(%values)
+
+=over
 
 Sets one or more viewer preferences, as described in the preferences section
 below.
 
+=back
+
 =cut
 
 sub _init_preferences {
@@ -215,8 +237,6 @@ sub set_preferences {
     return $self;
 }
 
-=back
-
 =head1 PREFERENCES
 
 Viewer Preferences describe how the document should be presented on screen or in
-- 
cgit v1.2.3