Update upstream source from tag 'upstream/3.026'

Update to upstream version '3.026' with Debian dir d8536bf85ae20bcf7ac21ae3322a229ea3f49b28
author: gregor herrmann <gregoa@debian.org> 2023-12-15 21:25:55 +0100
committer: gregor herrmann <gregoa@debian.org> 2023-12-15 21:25:55 +0100
commit: 900134cb227e50fe9047d0f48707ec7899c8c1f0 (patch)
tree: fe5bc6f0e7e00ccf9ad39ee858720d842bb82a1f
parent: 00c23136faf4a0a7015ba5f8daecb98fb33ba6cc (diff)
parent: e2f017af7599617065e54b1ad68a0ccc6afaf980 (diff)
157 files changed, 6882 insertions, 2035 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 37f85ea..10ab6f0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,61 +1,62 @@
-# Contributing to the development of PDF::Builder
-
-**Working on your first Pull Request?** You can learn how from this *free* series [How to Contribute to an Open Source Project on GitHub](https://kcd.im/pull-request) 
-
-We would appreciate the community around us chipping in with code, tests, 
-documentation, and even just bug reports and feature requests. It's better 
-knowing what users of PDF::Builder want and need, than for us to guess. It's 
-not good to spend a lot of time working on something that no one is interested 
-in!
-
-You can contribute to the discussion by posting bug reports, feature requests, 
-observations, etc. to the [GitHub issues area](https://github.com/PhilterPaper/Perl-PDF-Builder/issues?q=is%3Aissue+sort%3Aupdated-desc "issues")
-(please tag new threads accordingly, using ["Labels"], if possible).
-
-Please also read INFO/RoadMap to get an idea of where we would like for 
-PDF::Builder to be heading, and may give you an idea of where you could
-usefully contribute. Don't be afraid to discuss or propose taking PDF::Builder
-off in a direction not in the RoadMap -- the worst that could happen is that
-we say, "thanks, but no thanks."
-
-First of all, please read the section "Sofware Development Kit" under 
-PDF::Builder::Docs. This will be of interest if you want to do anything beyond 
-simply installing PDF::Builder as a prerequisite for some other package. You 
-can also get to this via "SOME SPECIAL NOTES" section of the root documentation 
-(PDF::Builder). You should create all the HTML documentation by running 
-"docs/buildDoc.pl --all" and read it before starting any serious work.
-
-For code changes, a GitHub pull request, a formal patch file (e.g., "diff"), or 
-even a replacement file or manual patch will do, so long as it's clear where it 
-goes and what it does. If the volume of such work becomes excessive (i.e., a 
-burden to us), we reserve the right to limit the ways that code changes can be 
-submitted. At this point, the volume is low enough that almost anything can be 
-handled. Please DO NOT send us code changes "out of the blue" (without prior
-discussion), unless they are very small, so that you're not out a lot of
-effort if we decline the offer.
-
-## Do NOT...
-
-Do NOT under ANY circumstances open a PR (Pull Request) to **report a _bug_.** 
-It is a waste of both _your_ and _our_ time and effort. Open a regular ticket
-(issue), and attach a Perl (.pl) program illustrating the problem, if possible.
-If you believe that you have a program patch (i.e., a permanent change to the
-code), and offer to share it as a PR, we may give the go-ahead. Unsolicited PRs
-may be closed without further action.
-
-Please do not start on a massive project (especially, new function), without 
-discussing it with us first (via email or one of the discussion areas). This 
-will save you the disappointment of seeing your hard work rejected because it 
-doesn't fit in with what's going on with the rest of the PDF::Builder project. 
-You are free to try contributing anything you want, or even to fork the project 
-if you don't like the direction it's taking (that's how PDF::Builder split off 
-from PDF::API2). Keeping in touch and coordinating with us ensures that your 
-work won't be wasted. If you have something dependent on PDF::Builder 
-functionality, but it doesn't fit our roadmap for core functionality, we may 
-suggest that you release it as a separate package on CPAN (dependent on 
-PDF::Builder), or as a new sub-package under PDF::Builder (e.g., like 
-PDF::API2::Ladder), under either our ownership or yours.
-
-Good luck, and best wishes using and helping with PDF::Builder!
-
-December, 2022
+# Contributing to the development of PDF::Builder
+
+**Working on your first Pull Request?** You can learn how from this *free* series [How to Contribute to an Open Source Project on GitHub](https://kcd.im/pull-request) 
+
+We would appreciate the community around us chipping in with code, tests, 
+documentation, and even just bug reports and feature requests. It's better 
+knowing what users of PDF::Builder want and need, than for us to guess. It's 
+not good to spend a lot of time working on something that no one is interested 
+in!
+
+You can contribute to the discussion by posting bug reports, feature requests, 
+observations, etc. to the [GitHub issues area](https://github.com/PhilterPaper/Perl-PDF-Builder/issues?q=is%3Aissue+sort%3Aupdated-desc "issues")
+(please tag new threads accordingly, using ["Labels"], if possible).
+
+Please also read INFO/RoadMap to get an idea of where we would like for 
+PDF::Builder to be heading, and may give you an idea of where you could
+usefully contribute. Don't be afraid to discuss or propose taking PDF::Builder
+off in a direction not in the RoadMap -- the worst that could happen is that
+we say, "thanks, but no thanks."
+
+First of all, please read the section "Sofware Development Kit" under 
+PDF::Builder::Docs. This will be of interest if you want to do anything beyond 
+simply installing PDF::Builder as a prerequisite for some other package. You 
+can also get to this via "SOME SPECIAL NOTES" section of the root documentation 
+(PDF::Builder). You should create all the HTML documentation by running 
+"docs/buildDoc.pl --all" and read it before starting any serious work.
+
+For code changes, a GitHub pull request, a formal patch file (e.g., "diff"), or 
+even a replacement file or manual patch will do, so long as it's clear where it 
+goes and what it does. If the volume of such work becomes excessive (i.e., a 
+burden to us), we reserve the right to limit the ways that code changes can be 
+submitted. At this point, the volume is low enough that almost anything can be 
+handled. Please DO NOT send us code changes "out of the blue" (without prior
+discussion), unless they are very small, so that you're not out a lot of
+effort if we decline the offer.
+
+## Do NOT...
+
+Do NOT under ANY circumstances open a PR (Pull Request) to **report a _bug_.** 
+It is a waste of both _your_ and _our_ time and effort. Instead, simply open a 
+regular ticket (_issue_) in GitHub, and attach a Perl (.pl) program that 
+illustrates the problem, if possible.
+If you believe that you have a program patch (i.e., a permanent change to the
+code), and offer to share it as a PR, we may give the go-ahead. Unsolicited PRs
+may be closed without further action.
+
+Please do not start on a massive project (especially, new function), without 
+discussing it with us first (via email or one of the discussion areas). This 
+will save you the disappointment of seeing your hard work rejected because it 
+doesn't fit in with what's going on with the rest of the PDF::Builder project. 
+You are free to try contributing anything you want, or even to fork the project 
+if you don't like the direction it's taking (that's how PDF::Builder split off 
+from PDF::API2). Keeping in touch and coordinating with us ensures that your 
+work won't be wasted. If you have something dependent on PDF::Builder 
+functionality, but it doesn't fit our roadmap for core functionality, we may 
+suggest that you release it as a separate package on CPAN (dependent on 
+PDF::Builder), or as a new sub-package under PDF::Builder (e.g., like 
+PDF::API2::Ladder), under either our ownership or yours.
+
+Good luck, and best wishes using and helping with PDF::Builder!
+
+May, 2023
diff --git a/Changes b/Changes
index 02ae504..f65d35b 100644
--- a/Changes
+++ b/Changes
@@ -2,6 +2,230 @@ See also INFO/Changes-ver_2 for changes released for PDF::API2, and
 incorporated into PDF::Builder.
 See also INFO/Changes_2021 for earlier version 3 release logs.
 
+3.026     2023-12-07
+
+    lib/PDF/Builder/Content/Text.pm, examples/Column.pl
+     Add HTML "reversed" (boolean) to <ol> tag to count down instead of up 
+      (needs "start" value to make any sense). 
+
+      I wanted to fix a few more minor problems with column(), including the
+      color of the first text in a <li> overriding the marker color, a bunch
+      of redundant font and color change commands and some other 
+      inefficiencies, and some other stuff. Unfortunately, that looks like a 
+      considerable rewrite of column(), and I ran out of runway, so I'll have 
+      to put it off to the next release.
+
+    lib/PDF/Builder/Content.pm
+     Add some POD notes about the use of charspace for tracking adjustments,
+      and the interaction with wordspace adjustments for a more balanced
+      appearance of justified text.
+
+    devtools/
+     A collection of various utilities I use to build PDF::Builder (the CPAN
+      package), as well as do the PHP conversion of HTML code for the web page
+      display of documentation (see catskilltech.com). Note that buildDoc.pl
+      (to build all the HTML files from POD) is already shipped with the
+      package. Further note that tools/1_pc.pl (Perl Critic) will complain
+      a LOT about the code in devtools/ ... maybe some day I'll get around to
+      cleaning it up.
+
+    (many .pm files), META.yml, Makefile.PL, README.md, docs/buildDoc.pl,
+      t/00-all-usable.t, tools/optional_update.pl, version
+     Cleanup of POD so that unordered/bulleted lists, ordered/numbered lists,
+      definition/description lists, and indented paragraphs are properly
+      handled upon conversion to HTML. Change optional POD-to-HTML generation 
+      from the old pod2html to Pod::Simple::XHTML.
+
+    lib/PDF/Builder/Content.pm
+     The linedash() method was not properly handling a restore of a saved
+      dash pattern, resulting in PDF "dash pattern" values that could be
+      unusable by a Reader.
+
+    lib/PDF/Builder.pm, lib/PDF/Builder/FontManager.pm, 
+      lib/PDF/Builder/Content/Text.pm, t/03-xrefstm-index.t
+     Continuing Issue #197, clean up handling of newly-created PDF object
+      in from_string() method (used by open() method). Also knock-on effects
+      on some t-tests.
+
+    lib/PDF/Basic/PDF/Pages.pm
+     Issue #203 a new page was being inserted in the wrong place. Thanks to
+      Vadim Repin for finding a "one off" index error that's apparently been 
+      there for at least a decade, and the fix.
+
+    lib/PDF/Builder.pm, lib/PDF/Builder/Basic/PDF/File.pm
+     Improve upon the Integrity Check, acknowledging that missing objects
+      might be hidden in an object stream. The open() function was also 
+      sometimes seeing a class reference rather than a pure class, which has
+      been fixed. See issue #196 and especially #197.
+
+    lib/PDF/Builder.pm, lib/PDF/Builder/Content.pm, examples/060_transparency,
+      INFO/KNOWN_INCOMP, tools/1_pc.pl
+     Remove ability to generate save() ("q") and restore() ("Q") while in a
+      text object. If attempted in text, it is now a no-op with a one-time
+      (per run) warning message reminding users to update their code NOT to
+      attempt save and restore in text mode. This was prompted by PDF::TableX 
+      t-tests using text save and restore, which isn't permitted by the PDF
+      definition. Updated one PDF::Builder example that (unnecessarily) did a
+      save/restore in text mode. Thanks to Vadim Repin for troubleshooting this
+      and determining the problem and fix. While in here, make the warning 
+      message that a request for 'Times' core font is changed to 'Times-Roman'
+      a one-time (per run) output, rather than every time.
+
+    lib/PDF/Builder/Page.pm, INFO/DEPRECATED, t/deprecations-page.t 
+     Obsolete and deprecated methods get_mediabox(), get_cropbox(), 
+      get_bleedbox(), get_trimbox(), and get_artbox() have been removed. Please
+      use the regular methods (in $pdf or $page) with no arguments, to retrieve
+      the current box values.
+
+    lib/PDF/Builder/Resource/XObject/Image.pm, INFO/DEPRECATED
+     Deprecate Image object methods width() and height() ability to SET the 
+      width and height of an image. This setting apparently has never worked 
+      properly, but in case someone is actually using it for some purpose, it 
+      has not been immediately removed. It is planned to be removed after
+      October, 2025, unless someone shows that they are using it.
+
+    (most .pm files)
+     Reformat POD to make navigation easier, including the listing of all user-
+      accessible methods in a POD's Table of Contents at the top.
+
+    lib/PDF/Builder/Content.pm, lib/PDF/Resource/XObject/Form/Hybrid.pm,
+      lib/PDF/Builder/Lite.pm, INFO/DEPRECATED, examples/021_psfonts,
+      t/content-deprecated.t, t/deprecations.t
+     Remove long-deprecated method and global variable "lead". Use "leading" 
+      instead, which is the correct typographical term. Although the "Lite" 
+      subpackage isn't really maintained, "textlead()" has been replaced by 
+      "textleading()".
+    
+    lib/PDF/Builder/Basic/PDF/Array.pm, /lib/PDF/Builder/Basic/PDF/Objind.pm, 
+      INFO/DEPRECATED, t/deprecations.t
+     Remove long-deprecated method "elementsof()" in favor of "elements()".
+     Remove long-deprecated method "removeobj()" in favor of "remove_element()".
+
+    README.md, Makefile.PL, META.yml, META.json, lib/PDF/Builder.pm, 
+      examples/Column.pl
+     Minimum Perl version changed from 5.24 to 5.26. Update list of expected
+      end-of-service against various Perl versions.
+
+    lib/PDF/Builder/Content.pm
+     Clarify description of "bogen()" method's "larger" and "reverse" options.
+
+    lib/PDF/Builder/Content.pm, lib/PDF/Builder/Content/Text.pm
+     Implement 'align' option for text() left/center/right, l/c/r.
+
+    README.md, examples/020_textunderline
+     Add pointer to README to online documentation, and clarify underline 
+      example (that first text is NOT underlined).
+
+    lib/PDF/Builder.pm
+     Clarify documentation on page_labels() versus pageLabel(), add code to
+      check differences in starting page index and form of options, in response
+      to PDF::API2 Issue #61.
+
+    lib/PDF/Builder/Content/Text.pm
+     A number of minor fixes: explicitly make paragraph <p> a block level, 
+       any pending margin-bottom at the end of a column (if ran out of input) 
+       should be accounted for in the returned $start_y.
+
+    INFO/ACKNOWLEDGE.md (new), README.md, MANIFEST 
+     Add acknowledgements and thanks.
+
+    lib/PDF/Builder/Basic/PDF/Filter/LZWDecode.pm
+     Revert an earlier change that broke some filtering.
+
+    README.md  Update to point to new PDF::Builder Home Page structure (on 
+      catskilltech.com).
+
+    t/info.t
+     Add test of modified() method.
+
+    lib/PDF/Builder.pm
+     Incorrect check on date format (missing last '). Reported by Johan Vromans
+      against PDF::API2 #62. The _is_date() method has been updated to reflect
+      a number of date/time formats found "in the wild", although the PDF
+      documentation is a bit inconsistent over time, as well as ambiguous, so
+      this may allow through some invalid formats.
+
+    lib/PDF/Builder.pm, examples/050_pagelabels
+     Fix an incompatibility with PDF::API2 recent changes (page_labels method).
+      Now starts page index (for page_labels) at 1 instead of 0, and warns
+      if 0 page index (page number) is given for page_labels (per API2 ticket
+      #61). The old pageLabel method, kept for compatibility, is unaffected. 
+      The example script has been updated to show both styles.
+
+    lib/PDF/Builder/Content/Text.pm
+     Make paragraph() method compatible with PDF::API2's, i.e., $continue
+      parameter is optional. It should make no difference in calls to paragraph
+      whether there is a fourth parameter (continue) before the options. This
+      incompatibility showed up in PDF::TableX t-tests.
+
+    lib/PDF/Builder/Docs.pm
+     Full writeup of what's supported for markup input (Markdown, HTML).
+
+    tools/3_examples.pl, examples/020_corefonts, examples/021_synfonts,
+      examples/023_cjkfonts
+     Add -s flag to run a small subset of the lengthy test list for three of
+      the examples, plus overall when running all examples.
+
+    lib/PDF/Builder/Page.pm, lib/PDF/Builder/Resource/CIDFont.pm
+     Clean up some typos preventing synfont t-test from running.
+
+    lib/PDF/Builder.pm, lib/PDF/Builder/Resource/CIDFont.pm
+     It has come to our attention (#193) that PDF Readers (Adobe Reader and a 
+      number of Third Party readers) do not properly handle the "Tw" operator 
+      with TrueType fonts. Other font types work as expected. This operator, 
+      set by the $text->wordspace(n) method, is ignored for TTF and OTF fonts
+      ($pdf->ttfont()) because Tw works only for inputs in the stream where 
+      words are separated by ASCII spaces (x20). TrueType fonts, on the other 
+      hand, uses an input list of glyph IDs (4 digit hex numbers). Thus, there 
+      are never any ASCII spaces to detect and adjust their widths. 
+
+      We have updated the TTF/OTF handling code to honor the Tw operator value
+      and emulate its actions, even though a native PDF Reader does not. In
+      order to match the effects of the Tw operator on other font types, only
+      ASCII spaces (x20) in the original text strings are affected, and not 
+      other flavors of spaces. Finally, TextHS() and advancewidthHS() still do
+      not handle charspace or wordspace settings (perhaps in the future).
+
+    lib/PDF/Builder/Content/Text.pm
+     When linking to a page via Markdown or HTML (URL #p-x-y), the default
+      zoom was 1 (100%) when given just the x and y coordinates on a page. This
+      has been changed to leave the zoom factor unchanged by default (unless,
+      of course, you choose to specify a zoom amount). Also, the thickness
+      (height) of the horizontal rule defaulted to 1pt, which was a bit heavy
+      in appearance. It has been changed to default to 0.5pt.
+
+    lib/PDF/Builder.pm
+     GD image call was not working in some circumstances, due to image_gd()
+      being called incorrectly. Reported and fixed by Hakon Hagland against
+      PDF::API2 (#60).
+
+    lib/PDF/Builder/Resource/Font/Postscript.pm, lib/PDF/Builder/Docs.pm,
+      examples/021_psfonts, t/font-type1.t
+     Update Type 1 font (PS font) handling to allow T1 fonts (.t1 filetype,
+      variant of .afm/.pfm). Also some new font paths to search on. Per request 
+      #194 from Red Hat packager (@ppisar).
+
+    ===== IMPORTANT NOTICE =====
+    lib/PDF/Builder.pm, lib/PDF/Builder/Docs.pm, 
+      lib/PDF/Builder/Resource/Font/Postscript.pm
+     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 soon no 
+      longer be possible. At any rate, users may want to consider starting to 
+      move away from Type 1 font usage (psfont), and switch to TTF/OTF (ttfont)
+      or even core fonts (corefont), as it is unknown how long Type 1 Reader 
+      support will continue.
+    ============================
+
 3.025     2023-01-19
 
     ===== many thanks to Amtivo Group for sponsoring this work!
diff --git a/INFO/ACKNOWLEDGE.md b/INFO/ACKNOWLEDGE.md
new file mode 100644
index 0000000..1d6046a
--- /dev/null
+++ b/INFO/ACKNOWLEDGE.md
@@ -0,0 +1,60 @@
+# Acknowledgements and Thanks
+
+_PDF::Builder_ did not spring fully formed from the forehead of the current 
+maintainer, ready for use. It is the product of many dozens, if not
+hundreds, of people working on many projects over many years.
+
+_PDF::Builder_ makes use of many Perl libraries and packages, as well as (in
+many cases) underlying open source libraries -- too many to list here (but you
+can follow the trail of all the `use XXX` entries in the code, if you are so 
+inclined).
+
+- Starting with the origins of the package, **Alfred Reibenschuh** built the 
+original _PDF::API2_ library, drawing on work by **Martin Hosken** 
+(_Text::PDF_, via the _Text::PDF::API_ wrapper).
+- **Steve Simms** took over _PDF::API2_ and has continued to maintain it and
+extend its functionality. Much of his work is incorporated into _PDF::Builder_
+after the latter was forked from the former.
+- **Cary Gravel** (_Graphics::TIFF_ package) and **Jeffrey Ratcliffe** 
+contributed much work to TIFF image support.
+- **Ben Bullock** added features to the PNG library to support the needs of
+this package.
+- **Johan Vromans** wrote a number of packages, which, while not used by (or 
+directly contributing code to) _PDF::Builder_, did inspire the Font Manager 
+and some aspects of markup language support. His _HarfBuzz::Shaper_ can be
+used by _PDF::Builder_ applications to support many text shaping features. He 
+also has discussed with us many aspects of text processing that may prove 
+useful in future code and may show up later.
+- **Vadim Repin** contributed a number of fixes and minor enhancements.
+- **Davide Cervone** contributed support for allowing _PDF::Builder_ to 
+interface with _MathJax_ (NodeJS) for equation support `(upcoming feature)`.
+
+And of course, many thanks to those who reported bugs and requested needed
+enhancements, sometimes even contributing some code and test cases. These
+people are usually listed in the `Changes` file, or in the GitHub bug report
+ticket. 
+
+A special shout-out goes to **Gregor Herrmann** and **Petr Pisar** for working 
+with us to report and fix problems discovered during packaging of their 
+_Linux_ distributions (which redistribute _PDF::Builder_).
+
+## Sponsorships
+
+Thanks also go out to **Andy Beverley** of _Amtivo Group_ for financial 
+sponsorship of the Markdown and HTML formatted input.
+
+See also _INFO/SPONSORS_.
+
+## Carrying On...
+
+_PDF::Builder_ is Open Source software, built upon the efforts not only of the
+current maintainer, but also of many people before me. Therefore, it's perfectly
+fair to make use of the algorithms and even code (within the terms of the
+LICENSE) for other projects, and even to port them to other languages and 
+platforms (Java, Rust, Python, Typescript, etc.), as well as package 
+_PDF::Builder_ into Linux and other OS distributions. That's how the State of 
+the Art progresses! Just please be considerate and acknowledge the work of 
+others that you are building on, as well as pointing back to this package. 
+Drop us a note with news of your project (if based on the code and algorithms 
+in _PDF::Builder_, or even just heavily inspired by it) and we'll be happy to 
+make a pointer to your work. The more cross-pollination, the better!
diff --git a/INFO/DEPRECATED b/INFO/DEPRECATED
index d3bc5b0..ce07504 100644
--- a/INFO/DEPRECATED
+++ b/INFO/DEPRECATED
@@ -15,32 +15,12 @@ NOTE for maintainer: update t/deprecations.t with tests for both old
 
 In order of scheduled removal date:
 
-elementsof()    method in a number of Basic/PDF/ routines
-   This method was renamed to elements(). elementsof() is scheduled to be
-   removed on or after August, 2021.
-
-removeobj()     method in Array.pm
-   Not used internally and not documented. To be removed on or after August,
-   2021.
-
-get_*box()      methods in Page.pm
-   now *box() methods (both $pdf and $page) with no arguments return the 
-   global and current page bounding boxes (media, crop, bleed, trim, art).
-   The get routines are now obsolete, and may be removed on or after 
-   August, 2021.
-
 PDFStr()        method in Basic/PDF/Utils.pm
    NOT scheduled to be removed, but use PDFString() instead. 
 
 PDFUtf()        method in Basic/PDF/Utils.pm
    NOT scheduled to be removed, but use PDFString() instead. 
 
-lead()          method in Content.pm
-   Use leading() instead. May be removed on or after March, 2023.
-
-textlead()      method in Lite.pm
-   Use textleading() instead. May be removed on or after March, 2023.
-
 openpage()      method in Builder.pm
    Use open_page() instead. May be removed on or after June, 2023.
 
@@ -48,6 +28,11 @@ default()       method in Builder.pm
    May be renamed in the future, as is flagged by Perl::Critic as reserved.
    Use with caution.
 
+width(w),height(h)  methods in Resource/XObject/Image.pm
+   The ability to SET an image's width and/or height is scheduled to be removed
+   after October 2025. This setting ability appears not to work, but in case
+   someone IS using it in some manner, it has not been immediately removed.
+
 *** If I have missed any deprecated interfaces, please let me know! ***
 
 ======= Deprecated items that already have been removed ======================
@@ -159,3 +144,26 @@ pdfile          method in Outline.pm, NamedDestination.pm
    Use "-condense" instead. -slant is scheduled to be removed on or after
    January, 2021. [Removed February, 2021]
 
+lead()          method in Content.pm
+   Use leading() instead. lead is scheduled to be removed on or after 
+   March, 2023. Notice that the associated global variable 'lead' has also
+   been changed to 'leading'. [Removed September, 2023]
+
+textlead()      method in Lite.pm
+   Use textleading() instead. textlead is scheduled to be removed on or after 
+   March, 2023. [Removed September, 2023]
+
+elementsof()    method in a number of Basic/PDF/ routines
+   This method was renamed to elements(). elementsof() is scheduled to be
+   removed on or after August, 2021. [Removed September, 2023]
+
+removeobj()     method in Array.pm
+   Not used internally and not documented. To be removed on or after August,
+   2021. Replaced by remove_element(). [Removed September, 2023]
+
+get_*box()      methods in Page.pm
+   now *box() methods (both $pdf and $page) with no arguments return the 
+   global and current page bounding boxes (media, crop, bleed, trim, art).
+   The get routines are now obsolete, and may be removed on or after 
+   August, 2021. [Removed October, 2023]
+
diff --git a/INFO/KNOWN_INCOMP b/INFO/KNOWN_INCOMP
index e99755e..a189435 100644
--- a/INFO/KNOWN_INCOMP
+++ b/INFO/KNOWN_INCOMP
@@ -7,6 +7,20 @@ Bug fixes to PDF::API2 (in PDF::Builder) are not mentioned if they correct
 an error (that produces an error message and/or incorrect output) and do not 
 affect the operation or results of otherwise correct code.
 
+==== A VERY IMPORTANT NOTE =================================================
+
+These notes describe ONLY function known to differ from behavior found in
+PDF::API2. That is, you may well see (somewhat) different behavior or output 
+converting over a program that runs on PDF::API2, to PDF::Builder. It does 
+NOT cover new function such as extended splines, HTML and Markdown 
+formatting of columns, etc. Be aware that using such new function in 
+PDF::Builder may make your code NOT portable to PDF::API2 (i.e., you are now 
+locked in to PDF::Builder). The documentation may or may not mention that
+this is new functionality exclusive to PDF::Builder, so be sure to test on
+PDF::API2 if you have a package or library intended to run on both!
+
+============================================================================
+
 3.024     2022-09-12
 
    PDF::API2 now initializes page display to a fairly tightly zoomed-in
@@ -130,6 +144,9 @@ affect the operation or results of otherwise correct code.
    lib/PDF/Builder/Content.pm  [ref CTS 7] $text->save() and restore() are no
      longer no-ops, if you had them in your code. They issue the same q and Q
      commands as a graphics save() and restore().
+   *** Removed in release 3.26. save/restore are only for graphics context
+   *** and should not be used in text context (will see a one-time warning,
+   *** and the calls are now no-ops)
 
    lib/PDF/Builder.pm
    lib/PDF/Builder/Content.pm
diff --git a/INFO/RoadMap b/INFO/RoadMap
index 4fe86a6..4600903 100644
--- a/INFO/RoadMap
+++ b/INFO/RoadMap
@@ -1,4 +1,4 @@
-Road Map for Future Development of PDF::Builder                   27 Nov 2022
+Road Map for Future Development of PDF::Builder                   01 Apr 2023
 
 In order to encourage others to contribute code and/or algorithms to the
 effort, I am publishing this road map of where I would like the product to go.
@@ -121,6 +121,14 @@ F. Fix Bar Code generation (CTS 1): there seems to be something quite wrong
    the interesting feature is using a code monkey to integrate itself (like
    a retrovirus) into PDF::Builder, and can be called $gfx->qrcode(parms).
 
+   Long term: consider a new package that generates an output-agnostic generic
+   graphics list, along with sample GD, PS, PDF::Builder drivers; as well as 
+   PDF::Builder generic barcode. Grab all sorts of Perl and non-Perl open
+   source generators and snag their algorithms to incorporate into the library.
+   incl PHP tecnickcom/tc-lib/barcode, Perl PDF::QRCode, etc. Allow qw/code1
+   code2/ in use BarCodes statement, as most users will just want to import a
+   very small subset of available codes.
+
 G. Fix Small Caps (and capitalization in general) for ligatures (CTS 13):
    some ligatures given in Unicode or single byte encodings don't get properly
    uppercased. The probable solution would be to decompose ligatures to their
diff --git a/MANIFEST b/MANIFEST
index 3e10e2e..4f699bd 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -2,6 +2,7 @@
 # if add or delete a .pm file, also update META.yml and META.json files
 # if add or delete a .t file, also update tools/2_t-tests.pl
 # if add or delete an example file, also update tools/3_examples.pl
+#    as well as the list of examples and expected results
 # if add or delete a contribution, also update tools/4_contrib.pl
 .perlcriticrc
 Changes
@@ -18,6 +19,7 @@ tools/3_examples.pl
 tools/4_contrib.pl
 #tools/optional_update.pl
 tools/TTFdump.pl
+INFO/ACKNOWLEDGE.md
 INFO/Changes_2017
 INFO/Changes_2018
 INFO/Changes_2019
diff --git a/META.json b/META.json
index cd13b15..d64938f 100644
--- a/META.json
+++ b/META.json
@@ -4,7 +4,7 @@
       "Phil Perry"
    ],
    "dynamic_config" : 1,
-   "generated_by" : "ExtUtils::MakeMaker version 7.66, CPAN::Meta::Converter version 2.150010",
+   "generated_by" : "ExtUtils::MakeMaker version 7.70, CPAN::Meta::Converter version 2.150010",
    "license" : [
       "lgpl_2_1"
    ],
@@ -34,7 +34,7 @@
          "requires" : {
             "Compress::Zlib" : "1",
             "Font::TTF" : "1.04",
-            "perl" : "5.024000"
+            "perl" : "5.026000"
          }
       },
       "test" : {
@@ -56,6 +56,6 @@
          "web" : "https://github.com/PhilterPaper/Perl-PDF-Builder"
       }
    },
-   "version" : "3.025",
+   "version" : "3.026",
    "x_serialization_backend" : "JSON::PP version 4.16"
 }
diff --git a/META.yml b/META.yml
index 1f4a4f8..f8f5c36 100644
--- a/META.yml
+++ b/META.yml
@@ -9,7 +9,7 @@ build_requires:
 configure_requires:
   ExtUtils::MakeMaker: '6.66'
 dynamic_config: 1
-generated_by: 'ExtUtils::MakeMaker version 7.66, CPAN::Meta::Converter version 2.150010'
+generated_by: 'ExtUtils::MakeMaker version 7.70, CPAN::Meta::Converter version 2.150010'
 license: lgpl
 meta-spec:
   url: http://module-build.sourceforge.net/META-spec-v1.4.html
@@ -22,10 +22,10 @@ no_index:
 requires:
   Compress::Zlib: '1'
   Font::TTF: '1.04'
-  perl: '5.024000'
+  perl: '5.026000'
 resources:
   bugtracker: https://github.com/PhilterPaper/Perl-PDF-Builder/issues
   homepage: https://metacpan.org/pod/PDF::Builder
   repository: git://github.com/PhilterPaper/Perl-PDF-Builder.git
-version: '3.025'
+version: '3.026'
 x_serialization_backend: 'CPAN::Meta::YAML version 0.018'
diff --git a/Makefile.PL b/Makefile.PL
index fbabaf0..b5ad67a 100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -2,13 +2,13 @@
 
 use strict;
 use warnings;
-use 5.024000;
+use 5.026000;
 use ExtUtils::MakeMaker 6.66;
 
-my $PERL_version = '5.024000';  # Both here and in "use" statement above,
+my $PERL_version = '5.026000';  # Both here and in "use" statement above,
                                 # PDFbuild.pl updates from 'version' file
 my $MakeMaker_version = '6.66';
-my $version = '3.025';          # PDFbuild.pl updates from 'version' file
+my $version = '3.026';          # PDFbuild.pl updates from 'version' file
 
 # optional libraries... most users will attempt to install full set. they are
 # nice to have but not vital for many users. if one fails to install, it might 
@@ -110,6 +110,8 @@ my %WriteMakefileArgs =
     #  Text::Markdown => 1.000031,
     #  # 'md1' and 'html' markup
     #  HTML::TreeBuilder => 5.07,
+    #  # use of buildDoc.pl to build HTML documentation from POD
+    #  Pod::Simple::XHTML => 3.45,
     #},     
 
   }
diff --git a/README.md b/README.md
index 147017c..876d0ce 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,23 @@
 
 A Perl library to facilitate the creation and modification of PDF files
 
+## What is it?
+
+PDF::Builder is a **fork** of the popular PDF::API2 Perl library. It provides a 
+library of modules and functions so that a PDF file (document) may be built and 
+maintained from Perl programs. It is not a WYSIWYG editor; nor is it a canned 
+utility or converter. It does _not_ have a GUI -- it is driven by your Perl 
+program. It is a set of **building blocks** with which you can perform a wide 
+variety of operations, ranging from basic operations such as selecting a font 
+face, to defining an entire page at a time in the document, using a large 
+subset of either Markdown or HTML markup languages. You can call it from 
+arbitrary Perl programs, which may even create content on-the-fly (or read it 
+in from other sources). Quite a few code examples are provided, to help you to 
+get started with the process of creating a PDF document. Many enhancements are 
+in the pipeline to make PDF::Builder even more powerful and versatile.
+
+[Home Page](https://www.catskilltech.com/FreeSW/product/PDF%2DBuilder/title/PDF%3A%3ABuilder/freeSW_full), including Documentation and Examples.
+
 [![Open Issues](https://img.shields.io/github/issues/PhilterPaper/Perl-PDF-Builder)](https://github.com/PhilterPaper/Perl-PDF-Builder/issues)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://makeapullrequest.com)
 [![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://GitHub.com/PhilterPaper/Perl-PDF-Builder/graphs/commit-activity)
@@ -33,7 +50,7 @@ By default, none are installed.
 
 ### Perl
 
-**Perl 5.24** or higher. It will likely run on somewhat earlier versions, but
+**Perl 5.26** or higher. It will likely run on somewhat earlier versions, but
 the CPAN installer may refuse to install it. The reason this version was
 chosen was so that LTS (Long Term Support) versions of Perl going back about
 6 years are officially supported (by PDF::Builder), and older versions are not
@@ -42,14 +59,14 @@ are an artifact of old Perl releases.
 
 #### Older Perls
 
-If you MUST install on an older (pre 5.24) Perl, you can try the following for
+If you MUST install on an older (pre 5.26) Perl, you can try the following for
 Strawberry Perl (Windows). NO PROMISES! Something similar MAY work for other
 OS's and Perl installations:
 
 1. Unpack installation file (`.tar.gz`, via a utility such as 7-Zip) into a directory, and cd to that directory
-1. Edit META.json and change 5.024000 to 5.016000 or whatever level desired
-1. Edit META.yml and change 5.024000 to 5.016000 or whatever level desired
-1. Edit Makefile.PL and change `use 5.024000;` to `use 5.016000;`, change `$PERL_version` from `5.024000` to `5.016000`
+1. Edit META.json and change 5.026000 to 5.016000 or whatever level desired
+1. Edit META.yml and change 5.026000 to 5.016000 or whatever level desired
+1. Edit Makefile.PL and change `use 5.026000;` to `use 5.016000;`, change `$PERL_version` from `5.026000` to `5.016000`
 1. `cpan .`
 
 Note that some Perl installers MAY have a means to override or suppress the
@@ -84,11 +101,13 @@ matters, especially if an optional package fails to install. You can always
 manually install them later, if you desire to make use of their added 
 functionality.
 
+* Perl::Critic (1.150 or higher, need if running tools/1\_pc.pl)
 * Graphics::TIFF (19 or higher, recommended if using TIFF image functions)
 * Image::PNG::Libpng (0.57 or higher, recommended for enhanced PNG image function processing)
 * HarfBuzz::Shaper (0.024 or higher, needed for Latin script ligatures and kerning, as well as for any complex script such as Arabic, Indic scripts, or Khmer)
 * Text::Markdown (1.000031 or higher, needed if using 'md1' markup)
 * HTML::TreeBuilder (5.07 or higher, needed if using 'html' or 'md1' markup)
+* Pod::Simple::XHTML (3.45 or higher, needed if using buildDoc utility to create HTML documentation)
 
 If an optional package is needed, but not installed, sometimes PDF::Builder
 will be able to fall back to built-in partial functionality (TIFF and PNG 
@@ -119,7 +138,8 @@ have it under a different name, such as dmake (Strawberry Perl on Windows),
 gmake, or nmake.
 
 PDF::Builder does not currently compile and link anything, so `gcc`, `g++`,
-etc. will not be used. The build process merely copies .pm files around.
+etc. will not be used. The build process merely copies .pm files around, and
+runs the "t" tests to confirm the proper installation.
 
 ## Copyright
 
@@ -145,11 +165,24 @@ redistribute and/or modify this software (those portions under LGPL) at an
 LGPL version greater than 2.1. See INFO/LICENSE for more information on the
 licenses and warranty statement.
 
+### Carrying On...
+
+PDF::Builder is Open Source software, built upon the efforts not only of the
+current maintainer, but also of many people before me. Therefore, it's perfectly
+fair to make use of the algorithms and even code (within the terms of the
+LICENSE). That's exactly how the State of the
+Art progresses! Just please be considerate and acknowledge the work of others
+that you are building on, as well as pointing back to this package. Drop us a
+note with news of your project (if based on the code and algorithms in
+PDF::Builder, or even just heavily inspired by it) and we'll be happy to make
+a pointer to your work. The more cross-pollination, the better!
+
 ## See Also
 
-* INFO/RoadMap file for the PDF::Builder road map
 * CONTRIBUTING file for how to contribute to the project
 * LICENSE file for more on the license term
+* INFO/RoadMap file for the PDF::Builder road map
+* INFO/ACKNOWLEDGE.md for "thank yous" to those who contributed to this product
 * INFO/SUPPORT file for information on reporting bugs, etc. via GitHub Issues 
 * INFO/DEPRECATED file for information on deprecated features
 * INFO/KNOWN\_INCOMP file for known incompatibilities with PDF::API2
@@ -166,6 +199,10 @@ and go to the `docs/` directory. Run `buildDoc.pl --all` to generate the full
 tree of documentation. There's a lot of additional information in the
 PDF::Builder::Docs module (it's all documentation).
 
+You may find it more convenient to point your browser to our 
+[Home Page](https://www.catskilltech.com/FreeSW/product/PDF-Builder/title/PDF%3A%3ABuilder/freeSW_full)
+to see the full documentation build (as well as most of the example outputs).
+
 We admit that the documentation is a bit light on "how to" task orientation.
 We hope to more fully address this in the future, but for now, get the full
 installation and look at the `examples/` and `contrib/` directories for sample
diff --git a/contrib/combine_pdfs.pl b/contrib/combine_pdfs.pl
index 654ced4..ef71bf4 100644
--- a/contrib/combine_pdfs.pl
+++ b/contrib/combine_pdfs.pl
@@ -3,7 +3,7 @@
 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
 
 use PDF::Builder;
diff --git a/contrib/pdf-debug.pl b/contrib/pdf-debug.pl
index 633ba2a..b5296f8 100644
--- a/contrib/pdf-debug.pl
+++ b/contrib/pdf-debug.pl
@@ -4,7 +4,7 @@ use warnings;
 
 use PDF::Builder::Basic::PDF::File;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.010'; # manually update whenever code is changed
 
 my $file = shift(@ARGV);
diff --git a/contrib/pdf-deoptimize.pl b/contrib/pdf-deoptimize.pl
index 5a4838c..b112612 100644
--- a/contrib/pdf-deoptimize.pl
+++ b/contrib/pdf-deoptimize.pl
@@ -3,7 +3,7 @@
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.016'; # manually update whenever code is changed
 
 use PDF::Builder::Basic::PDF::File;
diff --git a/contrib/pdf-optimize.pl b/contrib/pdf-optimize.pl
index 5a3c133..837905e 100644
--- a/contrib/pdf-optimize.pl
+++ b/contrib/pdf-optimize.pl
@@ -3,7 +3,7 @@
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.016'; # manually update whenever code is changed
 
 use PDF::Builder::Basic::PDF::File;
diff --git a/contrib/text2pdf.pl b/contrib/text2pdf.pl
index 2312ace..dbb15eb 100644
--- a/contrib/text2pdf.pl
+++ b/contrib/text2pdf.pl
@@ -5,6 +5,8 @@
 # $Date: 2013/08/14 20:26:56 $
 # $RCSfile: text2pdf.pl,v $
 #
+# Revision: by Phil M Perry  September 2023
+#   change textlead() reference to textleading()
 # Revision: by Phil M Perry  June 2018
 #   make Perl::Critic happy over handling of bareword filehandles and loop
 #     iterator declarations
@@ -72,7 +74,7 @@
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.021'; # manually update whenever code is changed
 
 use PDF::Builder;
@@ -108,7 +110,7 @@ my $CLFontName;     		# cmd line fontname
   my $DEFFontName = 'Courier';	#  default font Courier (fixed pitch)
 my $CLfontsize;               	# font size
   my $DEFfontsize = 7;          #   default = 7pt
-my $CLspacing;              	# text spacing ($pdf->textlead)
+my $CLspacing;              	# text spacing ($pdf->textleading)
   				#   default = 115% of font size
 my $CLtabs; 			# tab expansion definition
   my $DEFtabs = '9 17';		#   default = at 9, 17, 25, 33,...
diff --git a/docs/buildDoc.pl b/docs/buildDoc.pl
index f1b0e8a..6662ef7 100644
--- a/docs/buildDoc.pl
+++ b/docs/buildDoc.pl
@@ -15,9 +15,10 @@
 use strict;
 use warnings;
 use Getopt::Long;
+use Pod::Simple::XHTML;
 
-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
 
 # =============
 # CONFIGURATION  these may be overridden by command-line flags. If reading from
@@ -319,48 +320,48 @@ do {
  	    mkdir_list($target);
 	    # assuming no problem with overwriting .html output
 
-	    # run pod2html and produce .html file
-	    if (-e "pod2html.stderr") {
-	        unlink "pod2html.stderr";
-	    }
 	    print STDERR "processing $source\n";
-	    system("pod2html --podpath=$libtop $source --outfile=$target 2>pod2html.stderr");
-	    # always produces pod2html.stderr, hopefully empty
-
-	    if (-e $target) {
-	        # will stick any error messages in just-created 
-	        #   .html file
-	        $htmlfile = slurp($target);
-	        $file_list[$i]{'status'} = 1;  # OK (so far)
-            } else {
-	        # create dummy .html file to hold error messages
-	        $htmlfile = empty();
-	        $file_list[$i]{'status'} = 3;  # serious error
-	    }
-	    # always put in a title
-	    $htmlfile =~ s#<title></title>#<title>$file_list[$i]{'pmname'}</title>#;
-	    # is it empty?
-	    if ($htmlfile =~ m#<body>\s*</body>#) {
+            # run Pod::Simple::XHTML and produce .html string
+            # see https://metacpan.org/pod/Pod::Simple::XHTML for args
+            my $p = Pod::Simple::XHTML->new();
+             
+            # output to $htmlfile variable, later to $target file
+            my $htmlfile;
+            $p->output_string(\$htmlfile);
+
+	    $p->html_charset('UTF-8');
+	    $p->html_encode_chars(q{&<>'"});
+	    $p->html_doctype('<!DOCTYPE html>');
+
+            # want an index at the top
+            $p->index(1);
+            # parse the file containing POD
+            $p->parse_file($source);
+            # if errors, a section "POD errors" is inserted at the end (also index)
+	    # $htmlfile is a string containing output HTML, including errors
+            # no separate .stderr file
+#if ($target =~ m/Issue155/) { spew($htmlfile, "raw.html"); }
+	     
+	    # also if only invalid POD
+ 	    if ($htmlfile eq '') {
 		print "$source INFO  no POD content\n";
 		$file_list[$i]{'status'} = 0;
-		$htmlfile =~ s#</body>#No documentation (POD) in this module</body>#;
-	    }
-	    # POD errors and warnings reported?
-	    if ($htmlfile =~ m#id="POD-ERRORS"#) {
-		print "$source WARNING  internal POD errors reported by pod2html\n";
-		$file_list[$i]{'status'} = 2;
+		$htmlfile = "<html>\n<head>\n<title>$source</title>\n</head>\n";
+		$htmlfile .= "<body>\nNo documentation (POD) in this module</body>\n</html>\n";
+	    } else {
+	        # possibly a good run (OK so far)
+		$file_list[$i]{'status'} = 1;
+	        # always put in a title
+	        $htmlfile =~ s#<title></title>#<title>$file_list[$i]{'pmname'}</title>#;
+	        # add lang="en" to html tag
+	        $htmlfile =~ s#<html>#<html lang="en">#;
 	    }
-	    # errors output to STDERR?
-	    if (!-z "pod2html.stderr") {
-		print "$source ERROR  POD errors reported by pod2html\n";
+
+            # POD conversion errors reported? already in index section
+	    # empty string if no valid POD at all
+	    if ($htmlfile =~ m#id="POD_ERRORS"#) {
+		print "$source ERROR  POD errors reported\n";
 		$file_list[$i]{'status'} = 3;
-		my $errorfile = slurp("pod2html.stderr");
-		$htmlfile =~ s#</body>#<h1 id="POD-STDERR">SEVERE ERRORS</h1><pre>$errorfile</pre>\n</body>#;
-		# put entry in "index" section, if exists
-		if ($htmlfile =~ m#<ul id="index">#) {
-		# first end-list at beginning of line
-		    $htmlfile =~ s#\n</ul>#\n  <li><a href="\#POD-STDERR">SEVERE ERRORS</a></li>\n</ul>#;
-	        }
 	    }
 
 	    # examine and modify $htmlfile contents:
@@ -470,9 +471,9 @@ do {
 		my $abstract = $1;
 		$abstract =~ s#^[^ ]*##;
 		$abstract =~ s#^$abstract_sep##;
-		# kill any links in the abstract
-		$abstract =~ s#<a href="[^"]+">##g;
-		$abstract =~ s#</a>##g;
+	       ## kill any links in the abstract
+	       #$abstract =~ s#<a href="[^"]+">##s;
+	       #$abstract =~ s#</a>##s;
 		$file_list[$i]{'abstract'} = $abstract;
 	    }
 
@@ -510,11 +511,12 @@ if ($leading ne '') { $fname .= "/$leading"; }
 
 open my $fh, '>', "$fname/$TOC" or 
     die "$fname/$TOC ERROR  unable to open output index file\n";
-print $fh "<html>\n<head>\n<title>Master index for $file_list[0]{'pmname'}";
-print $fh "</title>\n<meta http-equiv=\"content-type\" content=\"text/html; charset=utf-8\" />\n";
+print $fh "<!DOCTYPE html>\n";
+print $fh "<html lang=\"en\">\n<head>\n<title>Master index for $file_list[0]{'pmname'}";
+print $fh "</title>\n<meta http-equiv=\"content-type\" content=\"text/html; charset=utf-8\">\n";
 print $fh "<style>\n";
-#print $fh "body { max-width: 50em; margins: 10px; }\n";
-print $fh "body { margins: 10px; }\n";
+#print $fh "body { max-width: 50em; margin: 10px; }\n";
+print $fh "body { margin: 10px; }\n";
 print $fh "h1, h2, h3 { text-align: center; }\n";
 print $fh ".fixedwidth { display: inline-block; width: 2em; }\n";
 print $fh ".dummy {color: #999; }\n";
@@ -524,10 +526,10 @@ print $fh "</style>\n";
 print $fh "</head>\n<body>\n";
 
 print $fh "<h1>T A B L E &nbsp; O F &nbsp; C O N T E N T S</h1>\n";
-print $fh "X = not accessible from root via chain of links<br/>\n";
-print $fh "<span class=\"errormsg\">ERROR</span> = POD errors of some sort reported<br/>\n";
-print $fh "(<span class=\"dummy\">no link</span>) = no POD, so empty .html file generated<br/>\n";
-print $fh " <br/>\n";
+print $fh "X = not accessible from root via chain of links<br>\n";
+print $fh "<span class=\"errormsg\">ERROR</span> = POD errors of some sort reported<br>\n";
+print $fh "(<span class=\"dummy\">no link</span>) = no POD, so empty .html file generated<br>\n";
+print $fh " <br>\n";
 
 for (my $i=0; $i<scalar @file_list; $i++) {
     # should not have any status -2 or -1 at this point
@@ -565,10 +567,40 @@ for (my $i=0; $i<scalar @file_list; $i++) {
 	# rather than one long line that wraps to left side. div with
 	# display:inline-block almost does it, but if too long doesn't 
 	# wrap, but puts entire div onto next line
-       #print $fh " &nbsp; - &nbsp; <div>$file_list[$i]{'abstract'}</div>";
-	print $fh " &nbsp; - &nbsp; $file_list[$i]{'abstract'}";
+	#
+	# Pod::Simple::XHTML has expanded L<> to metacpan URL, want our own
+	#
+	# change links to https://metacpan.org/pod/PDF::Builder::... to
+	# ../.. etc. /PDF/Builder/... .html
+	# don't forget some will have #id anchor on the end
+	my $string = $file_list[$i]{'abstract'};
+	my $pos = 0;
+	while ($pos > -1) {
+	    $pos = index $string, "href=\"https://metacpan.org/pod/PDF::";
+	    if ($pos < 0) { last; }
+	    $pos += 6;
+	    # $pos points to start of a link to metacpan https://...
+            my $pos2 = index $string, "\">", $pos;
+	    # $pos2 points to closing "> (which we'll keep)
+	    my $strLink = substr($string, $pos+25, $pos2-$pos-25);
+	    # $strLink should contain something like "PDF::Builder::Content"
+	    # if it contains an anchor (#), split off #anchor_id move $pos2
+	    my $pos3 = index $strLink, "#";
+	    if ($pos3 >= 0) {
+                $pos2 -= length($strLink)-$pos3;  # should start at # now
+		$strLink = substr($strLink, 0, $pos3);
+	    }
+	    # change :: to directory structure
+	    $strLink =~ s#::#/#g;
+	    # go up by one level, leading PDF/ not needed at this level
+	    $strLink = go_up($file_list[$i]{'depth'}) . "../$strLink.html";
+	    $string = substr($string, 0, $pos) . $strLink . substr($string, $pos2);
+	}
+
+       #print $fh " &nbsp; - &nbsp; <div>$string</div>";
+	print $fh " &nbsp; - &nbsp; $string";
     }
-    print $fh "<br/>\n";
+    print $fh "<br>\n";
 }
 print $fh "<h3>###</h3>\n";
 
@@ -582,8 +614,6 @@ print $fh "</body>\n</html>\n";
 close $fh;
 
 # cleanup
-unlink "pod2htmd.tmp";
-unlink "pod2html.stderr";
 
 # now that the individual HTML files and the master index are done,
 # 1) generate pmnameA array for each entry in @file_list
@@ -645,17 +675,22 @@ sub update_HTML{
 
 	# update link directory at top of file
 	# guaranteed there's at least one parent entry
-	$pos = index $string, '<ul id="index">';
-	if ($pos < 0) {
-	    print "ERROR: can't find link index in file $fname.\n";
-	    next;
+	# TBD shouldn't there be </li> at end of indexItem li's?
+	# if empty index list, replace by a real one
+	$pos = index $string, "<div class='indexgroupEmpty'></div>";
+	if ($pos > 0) {
+	    # is empty, replace with skeleton of real one
+	    $newstring = "<div class='indexgroup'>\n" .
+	                 "<ul   class='indexList indexList1'>\n" .
+			 "</ul>\n</div>";
+            $string = substr($string, 0, $pos) . $newstring . substr($string, $pos+36);
 	}
-	$pos = index $string, "\n</ul>", $pos;
+	$pos = index $string, "<h1 id=\"NAME\">";
 	if ($pos < 0) {
-	    print "ERROR: can't find end of link index in file $fname.\n";
+	    print "ERROR: can't find link index in file $fname.\n";
 	    next;
 	}
-	# split point is $pos+1 (just before </ul>)
+	$pos -= 8; # new last item in top level list
 	
         $newstring =  "  <li><a href=\"#NAVIGATION-LINKS\">NAVIGATION LINKS</a>\n" .
 	              "    <ul>\n" .
@@ -673,7 +708,8 @@ sub update_HTML{
 	$string = substr($string, 0, $pos+1) . $newstring . substr($string, $pos+1);
 	
 	# just before </body> will be location of new section
-	$pos = index $string, "\n</body>\n";
+	$pos = index $string, "</body>";
+	$pos--;
 
 	$newstring =  "<h1 id=\"NAVIGATION-LINKS\">NAVIGATION LINKS</h1>\n";
 
@@ -681,10 +717,10 @@ sub update_HTML{
 	$newstring .= "\n<h2 id=\"Up-Parents\">Up (Parents)</h2>\n";
 	# add ever-present master index entry at same level as [0] entry
 	# note: omitting id= because it's not used anywhere
-	# emulate a 'simple' (unbulleted) list with definition list empty dd
-	$newstring .= "\n<dl>\n\n<dt>" .
+	# just a paragraph with each line ending in a break
+	$newstring .= "\n<p>" .
 	              "<a href=\"".go_up($file_list[$i]{'depth'}-1) .
-		      "${rootname}_index.html\">Master Index</a>&nbsp;</dt>\n<dd>\n\n</dd>\n";
+		      "${rootname}_index.html\">Master Index</a><br>\n";
 
         $ref = $file_list[$i]{'parents'};
         if (defined $ref && scalar(@$ref)) {
@@ -693,24 +729,24 @@ sub update_HTML{
 	    @list = @$ref;
 	    foreach (@list) {
 	        $newstring .= "<a href=\"".go_up($file_list[$i]{'depth'}) .
-		              "$file_list[$_]{'htmlname'}\">$file_list[$_]{'pmname'}</a> -- $file_list[$_]{'abstract'}</dt>\n<dd>\n\n</dd>\n";
+		              "$file_list[$_]{'htmlname'}\">$file_list[$_]{'pmname'}</a> -- $file_list[$_]{'abstract'}<br>\n";
             }
         }
-	$newstring .= "</dl>\n";
+	$newstring .= "</p>\n";
 
         # if any siblings, output that section
 	if ($count[1]) {
             $ref = $file_list[$i]{'siblings'};
             if (defined $ref && scalar(@$ref)) {
-	        $newstring .= "\n<h2 id=\"Siblings\">Siblings</h2>\n";
+	        $newstring .= "\n<h2 id=\"Siblings\">Siblings</h2>\n<p>\n";
 	        # @$ref is an ordered array of @file_list indice(s)
 	        # pointing back to any siblings
 	        @list = @$ref;
 	        foreach (@list) {
 	            $newstring .= "<a href=\"".go_up($file_list[$i]{'depth'}) .
-		                  "$file_list[$_]{'htmlname'}\">$file_list[$_]{'pmname'}</a> -- $file_list[$_]{'abstract'}</dt>\n<dd>\n\n</dd>\n";
+		                  "$file_list[$_]{'htmlname'}\">$file_list[$_]{'pmname'}</a> -- $file_list[$_]{'abstract'}<br>\n";
                 }
-	        $newstring .= "</dl>\n";
+	        $newstring .= "</p>\n";
             }
         }
 
@@ -718,22 +754,74 @@ sub update_HTML{
 	if ($count[2]) {
             $ref = $file_list[$i]{'children'};
             if (defined $ref && scalar(@$ref)) {
-	        $newstring .= "\n<h2 id=\"Down-Children\">Down (Children)</h2>\n";
+	        $newstring .= "\n<h2 id=\"Down-Children\">Down (Children)</h2>\n<p>\n";
 	        # @$ref is an ordered array of @file_list indice(s)
 	        # pointing back to any children
 	        @list = @$ref;
 	        foreach (@list) {
 	            $newstring .= "<a href=\"".go_up($file_list[$i]{'depth'}) .
-		                  "$file_list[$_]{'htmlname'}\">$file_list[$_]{'pmname'}</a> -- $file_list[$_]{'abstract'}</dt>\n<dd>\n\n</dd>\n";
+		                  "$file_list[$_]{'htmlname'}\">$file_list[$_]{'pmname'}</a> -- $file_list[$_]{'abstract'}<br>\n";
                 }
-	        $newstring .= "</dl>\n";
+	        $newstring .= "</p>\n";
             }
         }
 
 	# bottom of page mark
-	$newstring .= "<p><center>###</center></p>\n";
+	$newstring .= "<h3>###</h3>\n";
         # write file back out
 	$string = substr($string, 0, $pos+1) . $newstring . substr($string, $pos+1);
+	# change links to https://metacpan.org/pod/PDF::Builder::... to
+	# ../.. etc. /PDF/Builder/... .html
+	# don't forget some will have #id anchor on the end
+	$pos = 0;
+	while ($pos > -1) {
+	    $pos = index $string, "href=\"https://metacpan.org/pod/PDF::";
+	    if ($pos < 0) { last; }
+	    $pos += 6;
+	    # $pos points to start of a link to metacpan https://...
+            my $pos2 = index $string, "\">", $pos;
+	    # $pos2 points to closing "> (which we'll keep)
+	    my $strLink = substr($string, $pos+25, $pos2-$pos-25);
+	    # $strLink should contain something like "PDF::Builder::Content"
+	    # if it contains an anchor (#), split off #anchor_id move $pos2
+	    my $pos3 = index $strLink, "#";
+	    if ($pos3 >= 0) {
+                $pos2 -= length($strLink)-$pos3;  # should start at # now
+		$strLink = substr($strLink, 0, $pos3);
+	    }
+	    # change :: to directory structure
+	    $strLink =~ s#::#/#g;
+	    $strLink = go_up($file_list[$i]{'depth'}) . "$strLink.html";
+	    $string = substr($string, 0, $pos) . $strLink . substr($string, $pos2);
+	}
+	# FIXUP of Pod::Simple::XHTML problems
+	#  self-closing tags disallowed in HTML 5
+	$string =~ s# />#>#g;
+	#  current bug: indented paragraphs are <p> under <ul>, which the
+	#    validator dislikes. remove <ul> and change <p> to <blockquote>
+	#    (other solutions would be preferable, but PSX owner has
+	#    indicated he plans to do this)
+	$pos = 0;
+	while (1) {
+	    $pos = index($string, "<ul>\n\n<p>", $pos);
+	    if ($pos < 0) { last; }
+
+	    # $pos marks beginning of problem section
+	    my $pos2 = index($string, "\n</ul>\n", $pos);
+	    if ($pos2 < 0) { last; } # SHOULDN'T happen!
+	    # $pos2 marks end of problem section
+
+            $newstring = substr($string, $pos+6, $pos2-$pos-7);
+	    # should be <p> through last </p> of section
+            $newstring =~ s#<p>#<blockquote>#gs;
+            $newstring =~ s#</p>#</blockquote>#gs;
+
+	    # put it back together, omitting the <ul> and </ul> tags
+	    $string = substr($string, 0, $pos) . 
+	              $newstring . 
+		      substr($string, $pos2+6);
+	}
+
 	spew($string, $fname);
     }
     return;
@@ -923,6 +1011,17 @@ sub make_pmnameA {
 sub spew {
     my ($string, $fname) = @_;
     open(my $fh, '>', $fname) or die "$fname ERROR  can't open file for output\n";
+    # warn if a wide character and give string and offset
+    my $first = 1;  # only one dump of string
+    for (my $i=0; $i<length($string); $i++) {
+	if (ord(substr($string, $i, 1)) > 127) {
+	    if ($first) {
+		print "String: '$string'\n";
+		$first = 0;
+	    }
+	    print "Wide character ".ord(substr($string, $i, 1))." found at $i\n";
+	}
+    }
     print $fh $string;
     close $fh;
     return;
@@ -1064,8 +1163,9 @@ sub toFP {
 sub help {
     my $message = <<"END_OF_TEXT";
 
-buildDoc.pl: build, using pod2html utility, all the .html documentation files
-  for a package, from all the .pm (or .pod) files in the package.
+buildDoc.pl: build, using the Pod::Simple::XHTML utility, all the .html 
+documentation files for a package, from all the .pm (or .pod) files in 
+the package.
 
 Using buildDoc.pl
 
@@ -1169,10 +1269,10 @@ in Builder/docs (also on the Desktop), run
 
     buildDoc.pl --leading='' --libtop=../../SVG-2.87/lib -rootname=SVG
 
-  The .pod or .pm file(s) are fed to pod2html utility (usually part of Perl 
-installation) to produce .html files stored in the current directory or below 
-(see configuration section). .html files with any links in them (L<> tag) are 
-fixed up to correct the href (path) to the referenced HTML files.
+  The .pod or .pm file(s) are fed to Pod::Simple::XHTML utility to produce 
+.html files stored in the current directory or below (see configuration 
+section). .html files with any links in them (L<> tag) are fixed up to correct 
+the href (path) to the referenced HTML files.
 
 If there are both .pod and .pm versions of a given filename, the .pod version
 will be preferably used. Presumably it has the documentation in it.
@@ -1219,7 +1319,7 @@ Messages:
   <filename> WARNING  top-level .pod or .pm file not readable
      One or more of the top level .pod or .pm files (<rootname> .pod or .pm) 
      was missing or not readable.
-  <filename> WARNING  internal POD errors reported by pod2html
+  <filename> WARNING  internal POD errors reported by Pod::Simple::XHTML
      At the end of the .html file, problems are listed. You should examine them 
      and attempt to correct the issue(s). Usually these are formatting issues.
   <filename> WARNING  is not a directory or file, ignored
@@ -1231,7 +1331,7 @@ Messages:
      and cannot be an empty string. It must be a name.
   <filename> ERROR  no <rootname> .pod or .pm files found
      The specified file(s) were not found.
-  <filename> ERROR  POD errors reported by pod2html
+  <filename> ERROR  POD errors reported by Pod::Simple::XHTML
      One or more error messages were written to STDERR. You should examine them 
      and attempt to correct the issue(s).
   <PMname> ERROR  does not appear to exist, called from <sourcefile>
@@ -1279,8 +1379,8 @@ sub empty {
 <html xmlns="http://www.w3.org/1999/xhtml">
 <head>
 <title></title>
-<meta http-equiv="content-type" content="text/html; charset=utf-8" />
-<link rev="made" href="mailto:" />
+<meta http-equiv="content-type" content="text/html; charset=utf-8">
+<link rev="made" href="mailto:">
 </head>
 
 <body>
diff --git a/examples/020_corefonts b/examples/020_corefonts
index bd99bfa..515e785 100644
--- a/examples/020_corefonts
+++ b/examples/020_corefonts
@@ -1,7 +1,7 @@
 #!/usr/bin/perl
 
-# wants one or more font names on the command line. If none, use list of
-# core fonts.
+# wants one or more font names on the command line. If none given, use full
+# list of core fonts. If -s given as first arg, use the short list.
 
 # CAUTION: the displayed Unicode value (U=xxxx) appears to be correct in most
 # cases, except that the MS Smart Quotes (32 characters) are given as U=0080
@@ -21,8 +21,8 @@ use lib '../lib';
 use PDF::Builder;
 use PDF::Builder::Util;
 
-my $compress = 'none';  # uncompressed streams
-#my $compress = 'flate';  # compressed streams
+#my $compress = 'none';  # uncompressed streams
+my $compress = 'flate';  # compressed streams
 
 my $sx = 33;
 my $sy = 45;
@@ -70,6 +70,16 @@ my @fns=qw{
 #   bankgothicbolditalic
 #   bankgothicitalic
 
+my @ARGVcopy = @ARGV;
+# 'short' (-s flag)?
+if (@ARGVcopy > 0 && $ARGVcopy[0] eq '-s') {
+    @ARGVcopy = qw{
+        Courier-Bold
+	Times-Italic
+	Symbol
+    };
+}
+
 # use only with single byte encodings, as multibyte (including UTF-8) don't
 # appear to be compatible with these core fonts
 # there may be a number of aliases available for each encoding.
@@ -111,8 +121,8 @@ my @ecs = qw{
 my ($y, $pdf, $f1);
 
 # override default list with command line entries
-if (scalar @ARGV) {
-    @fns = @ARGV;
+if (scalar @ARGVcopy && $ARGVcopy[0] ne '-s') {
+    @fns = @ARGVcopy;
 }
 
 # loop through list of font names
diff --git a/examples/020_textunderline b/examples/020_textunderline
index 4ae916b..8e5e361 100644
--- a/examples/020_textunderline
+++ b/examples/020_textunderline
@@ -19,7 +19,7 @@ my $page = $pdf->page();
 $page->mediabox(595,842);
 
 my $text = $page->text();
-$text->textlabel(50,700, $f2, 20, 'Normal Text in Red', -color=>'red');
+$text->textlabel(50,700, $f2, 20, 'Normal Text in Red (no underline)', -color=>'red');
 $text->textlabel(50,600, $f2, 20, 'Normal Text in Blue Underline in Red+Yellow',
     -color=>'#0000CC',
     -rotate=>-45,
diff --git a/examples/021_psfonts b/examples/021_psfonts
index 23feead..b9b21e1 100644
--- a/examples/021_psfonts
+++ b/examples/021_psfonts
@@ -1,8 +1,8 @@
 #!/usr/bin/perl
 
 # wants one or more font names on the command line. They must have a file
-# extension of .pfa or .pfb, and have an associated metrics file of the same
-# path and name, except with extension .afm or .pfm respectively.
+# extension of .pfa, .pfb, or .t1 and have an associated metrics file of the 
+# same path and name, except with extension .afm or .pfm respectively.
 
 # CAUTION: the displayed Unicode value (U+xxxx) appears to be correct in most
 # cases, except that the MS Smart Quotes (32 characters) are given as U+0080
@@ -102,6 +102,7 @@ for ($i=0; $i<scalar @gns; $i++) {
     $base =~ m#([^/\\]+)$#;
     $base = $1;
     $base =~ s#\.pf[ab]$##i;
+    $base =~ s#\.t1$##i;
 
     # at least one page for each encoding 
     foreach my $ec (split / /, $ecs[$i]) {
@@ -228,7 +229,7 @@ for ($i=0; $i<scalar @gns; $i++) {
         $txt->transform(-translate => [50, 800]);
         $txt->fillcolor('black');
         $txt->font($fnt, 18);
-        $txt->lead(18*1.25);
+        $txt->leading(18*1.25);
         my $toprint;
         while ($textL ne '') {
         	($toprint, $textL) = $txt->_text_fill_line($textL, 500, 0);
@@ -268,7 +269,7 @@ flags_1 --
      following glyph file names until a new -e.
 
 glyph_file --
-  a .pfa or .pfb extension T1 (PS) glyph file (with path)
+  a .pfa or .pfb or .t1 extension Type 1 (PS) glyph file (with path)
 
 flags_2 --
   -m  metrics files paths
@@ -300,7 +301,7 @@ Going through glyph file names, the complete path, name, and extension
   will search for the metrics file (.afm or .pfm) using each metrics
   file path entry appended to the glyph file path, the base name of
   the glyph file, and each extension .afm and .pfm are tried (in that
-  order for a .pfa glyph file, and in the reverse order for a .pfb
+  order for a .pfa or .t1 glyph file, and in the reverse order for a .pfb
   glyph file). Matching of extensions is case-insensitive, even on
   Linux systems (e.g., times-roman.AFM is considered a match for
   times-roman.pfb).
@@ -408,10 +409,10 @@ sub processCMD {
           
         # split into path, basename, extension
         ($path, $basename, $extension) = splitPath($token);
-        if ($extension =~ m/^pf[ab]$/i) {
+        if ($extension =~ m/^pf[ab]$/i || $extension =~ m/^t1$/i) {
 	    # acceptable extension name
         } else {
-	    print "expected glyph file extension .pfa or .pfb not found in glyph file '$token' (arg $tokenNumber)\n";
+	    print "expected glyph file extension .pfa, .pfb, or .t1 not found in glyph file '$token' (arg $tokenNumber)\n";
 	    return 1;
         }
 
@@ -559,7 +560,7 @@ sub makeMPath {
 
     # try each gPath + gName + afm or pfm
     # .pfa tries .afm before .pfm, .pfb tries .pfm before .afm
-    my @extList = qw/ .afm .pfm /;
+    my @extList = qw/ .afm .pfm /; # also use for .t1
     if ($gExt =~ m#^pfb$#i) {
         @extList = qw/ .pfm .afm /; # or reverse @extList
     }
diff --git a/examples/021_synfonts b/examples/021_synfonts
index 2d108a5..0fa9b0f 100644
--- a/examples/021_synfonts
+++ b/examples/021_synfonts
@@ -1,5 +1,8 @@
 #!/usr/bin/perl
 
+# command line defaults to 0 (full list of core fonts). 1 or -s is for a
+# short list, 2 is a single TTF, and 3 is a single Type 1
+
 use strict;
 use warnings;
 
@@ -8,7 +11,7 @@ use PDF::Builder;
 use PDF::Builder::Util;
 
 my $type = 0;  # 0 = full list of core fonts 
-               # 1 = single core font (for testing)
+               # 1 or -s = single core font (for testing)
 	       # 2 = TTF font(s)
 	       # 3 = Type1 (PS) font(s)
 my $encoding = 'latin1';  # normally latin1
@@ -16,7 +19,9 @@ my $encoding = 'latin1';  # normally latin1
 
 # for testing, command line number is type
 if (scalar @ARGV > 0) {
-    if ($ARGV[0] > -1 && $ARGV[0] < 4) {
+    if      ($ARGV[0] eq '-s') {
+	$type = 1;  # -s is alias for 1
+    } elsif ($ARGV[0] > -1 && $ARGV[0] < 4) {
 	# command line type 0 1 2 or 3
 	$type = $ARGV[0];
     }
@@ -37,8 +42,8 @@ push @varLabels, 'bold 4';
 push @variants, {-caps=>1};
 push @varLabels, 'caps 1';
 
-my $compress = 'none'; # no stream compression
-#my $compress = 'flate'; # compress streams
+#my $compress = 'none'; # no stream compression
+my $compress = 'flate'; # compress streams
 
 my $sx = 33;
 my $sy = 45;
@@ -47,6 +52,7 @@ my $fx = 20;
 my ($ci, $y, $k);
 
 my (@font_list, @short_name, @T1_metrics);
+
 # core
 if ($type == 0) {
   @font_list = qw(
@@ -82,7 +88,7 @@ if ($type == 0) {
   );
 }
 if ($type == 1) {
-  @font_list = qw( Times-Roman ); 
+  @font_list = qw( Courier-Oblique ); 
 }
   
 # note that for TTF and Type1, spaces in names (Windows) replaced by ~
diff --git a/examples/023_cjkfonts b/examples/023_cjkfonts
index 3545107..0fd78f7 100644
--- a/examples/023_cjkfonts
+++ b/examples/023_cjkfonts
@@ -1,5 +1,8 @@
 #!/usr/bin/perl -w
 
+# wants one or more font names on the command line. If none given, use full
+# list of CJK fonts. If -s given as first arg, use the short list.
+
 use strict;
 use warnings;
 
@@ -31,6 +34,18 @@ my @fontnames = qw[
   KozGo KozGo-Bold KozGo-Italic KozGo-BoldItalic 
 ];
 
+# 'short' (-s flag)?
+if (@ARGV > 0 && $ARGV[0] eq '-s') {
+    @fontnames = qw[
+      KozGo  Ming-Bold
+    ];
+}
+
+# override default list with command line entries
+if (scalar @ARGV && $ARGV[0] ne '-s') {
+    @fontnames = @ARGV;
+}
+
 foreach my $fn (@fontnames) {
    #if ($fn eq 'Ming-Bold') { last; } # for testing
 
diff --git a/examples/050_pagelabels b/examples/050_pagelabels
index 4795d7c..58f8b46 100644
--- a/examples/050_pagelabels
+++ b/examples/050_pagelabels
@@ -10,7 +10,9 @@ use PDF::Builder::Util;
 #my $compress = 'none'; # uncompressed streams
 my $compress = 'flate'; # compressed streams
 
+my $section_length = 32;  # examples per old and new methods
 my @labels = (
+# new method page_labels()
 	'upper case Roman numeral I',
 	'upper case Roman numeral II',
 	'upper case Roman numeral III',
@@ -31,12 +33,57 @@ my @labels = (
 	'prefixed B-2',
 	'prefixed C-1',
 	'prefixed C-2',
+	'decimal (Arabic) number 11',
+	'decimal (Arabic) number 12',
+	'upper case letter A',
+	'upper case letter B',
+	'lower case Roman numeral i',
+	'lower case Roman numeral ii',
+	'no counter (blank)',
+	'no counter (blank)',
+	'prefix, no counter Z',
+	'prefix, no counter Z',
+	'prefix, uc Roman Index I',
+	'prefix, uc Roman Index II',
+
+# old method pageLabel()
+	'upper case Roman numeral I',
+	'upper case Roman numeral II',
+	'upper case Roman numeral III',
+	'upper case Roman numeral IV',
+	'decimal (Arabic) number 1',
+	'decimal (Arabic) number 2',
+	'decimal (Arabic) number 3',
+	'decimal (Arabic) number 4',
+	'decimal (Arabic) number 5',
+	'decimal (Arabic) number 6',
+	'decimal (Arabic) number 7',
+	'decimal (Arabic) number 8',
+	'decimal (Arabic) number 9',
 	'decimal (Arabic) number 10',
+	'prefixed A-1',
+	'prefixed A-2',
+	'prefixed B-1',
+	'prefixed B-2',
+	'prefixed C-1',
+	'prefixed C-2',
 	'decimal (Arabic) number 11',
+	'decimal (Arabic) number 12',
 	'upper case letter A',
 	'upper case letter B',
 	'lower case Roman numeral i',
 	'lower case Roman numeral ii',
+	'no counter (blank)',
+	'no counter (blank)',
+	'prefix, no counter Z',
+	'prefix, no counter Z',
+	'prefix, uc Roman Index I',
+	'prefix, uc Roman Index II',
+# extra: these two styles (4 pages) combined one call, pageLabel only
+	'lower case letter c', 
+	'lower case letter d',
+	'lc Roman and prefixed App-iv',
+	'lc Roman and prefixed App-v',
 );
 
 my $pdf = PDF::Builder->new(-compress => $compress);
@@ -44,42 +91,93 @@ my $pdf = PDF::Builder->new(-compress => $compress);
 my $f1=$pdf->corefont('Helvetica', -encode=>'latin1');      # unused?
 my $f2=$pdf->corefont('Helvetica-Bold', -encode=>'latin1'); # "Page Index=" text
 
-# initial pass, create 26 pages labeled "Page Index=n" for n=0-25
-foreach my $i (0 .. 25) {
+# initial pass, create 2 x $section_length-1 pages labeled 
+#   "Page Index=n" for n=0-$section_length
+#   extra pages for pageLabel combined -1 -> +3
+foreach my $i (0 .. 2*$section_length+3) {
 	my $page = $pdf->page();
 	$page->mediabox(595,842);
 	
 	my $text=$page->text();
-	$text->textlabel(40,700, $f2, 20, 'Page Index='.$i.',');
+	$text->textlabel(40,700, $f2, 20, 'Page Index='.$i.', Physical Page='.($i+1));
 	$text->textlabel(40,670, $f2, 20, 'thumbnail label should be '.$labels[$i]);
 }
 
 # modify page numbering /Catalog /PageLabels entries
 # note that each style change resets page to 1
 # this number NOT on printed page... only in reader thumbnail
+#                                     and possibly the reader's display page
+
+# ---------- NEW method using page_labels()
+# pages 1..4 should be Upper Case Roman (I..IV)
+$pdf->page_labels(1, -style => 'Roman' );  # << /S /R >> default St 1
+
+# pages 5..14 s/b decimal, restart at 1 (1..10)
+$pdf->page_labels(5, -start => 1 );  # << /S /D /St 1 >>
+
+# pages 15..16 s/b A-decimal, restart at 1 (A-1, A-2)
+$pdf->page_labels(15, -start => 1, -prefix => 'A-' ); # << /P (A-) /S /D /St 1 >>
+# pages 17..18 s/b B-1, B-2
+$pdf->page_labels(17, -start => 1, -prefix => 'B-' ); # << /P (B-) /S /D /St 1 >>
+# pages 19..20 s/b C-1, C-2
+$pdf->page_labels(19, -start => 1, -prefix => 'C-' ); # << /P (C-) /S /D /St 1 >>
+
+# pages 21..22 s/b decimal, restart at 11 (11..12)
+$pdf->page_labels(21, -start => 11 ); # << /S /D /St 11 >>
+
+# pages 23..24 s/b Alpha, auto-restarts at 1 (A, B)
+$pdf->page_labels(23, -style => 'Alpha' ); # << /S /A >>
+
+# pages 25..26 s/b lowercase roman, auto-restarts at 1 (i, ii)
+$pdf->page_labels(25, -style => 'roman' ); # << /S /r >>
+
+# pages 27..28 s/b blank (nocounter)
+$pdf->page_labels(27, -style => 'nocounter' ); 
+
+# pages 29..30 s/b blank (nocounter) with Z prefix
+$pdf->page_labels(29, -style => 'nocounter', -prefix => 'Z' ); 
+
+# pages 31..32 s/b prefix Index plus UC Roman
+$pdf->page_labels(31, style => 'Roman', prefix => 'Index ' ); 
+
+# ---------- OLD method using pageLabel()
+# pages $section_length+0..3 should be Upper Case Roman (I..IV)
+$pdf->pageLabel($section_length+0, { -style => 'Roman' });  # << /S /R >> default St 1
+
+# pages $section_length+4..13 s/b decimal, restart at 1 (1..10)
+$pdf->pageLabel($section_length+4, { -start => 1 });  # << /S /D /St 1 >>
+
+# pages $section_length+14..15 s/b A-decimal, restart at 1 (A-1, A-2)
+$pdf->pageLabel($section_length+14, { -start => 1, -prefix => 'A-' }); # << /P (A-) /S /D /St 1 >>
+# pages $section_length+16..17 s/b B-1, B-2
+$pdf->pageLabel($section_length+16, { -start => 1, -prefix => 'B-' }); # << /P (B-) /S /D /St 1 >>
+# pages $section_length+18..19 s/b C-1, C-2
+$pdf->pageLabel($section_length+18, { -start => 1, -prefix => 'C-' }); # << /P (C-) /S /D /St 1 >>
+
+# pages $section_length+20..21 s/b decimal, restart at 11 (10..11)
+$pdf->pageLabel($section_length+20, { -start => 11 }); # << /S /D /St 11 >>
 
-# pages 0..3 should be Upper Case Roman (I..IV)
-$pdf->pageLabel(0, { -style => 'Roman' });  # 0 << /S /R >> default St 1
+# pages $section_length+22..23 s/b Alpha, auto-restarts at 1 (A, B)
+$pdf->pageLabel($section_length+22, { -style => 'Alpha' }); # << /S /A >>
 
-# pages 4..13 s/b decimal, restart at 1 (1..10)
-$pdf->pageLabel(4, { -start => 1 });  # 4 << /S /D /St 1 >>
+# pages $section_length+24..25 s/b lowercase roman, auto-restarts at 1 (i, ii)
+$pdf->pageLabel($section_length+24, { -style => 'roman' }); # << /S /r >>
 
-# pages 14..15 s/b A-decimal, restart at 1 (A-1, A-2)
-$pdf->pageLabel(14, { -start => 1, -prefix => 'A-' }); # 14 << /P (A-) /S /D /St 1 >>
-# pages 16..17 s/b B-1, B-2
-$pdf->pageLabel(16, { -start => 1, -prefix => 'B-' }); # 16 << /P (B-) /S /D /St 1 >>
-# pages 18..19 s/b C-1, C-2
-$pdf->pageLabel(18, { -start => 1, -prefix => 'C-' }); # 18 << /P (C-) /S /D /St 1 >>
+# pages $section_length+26..27 s/b blank (nocounter)
+$pdf->pageLabel($section_length+26, { -style => 'nocounter' }); 
 
-# pages 20..21 s/b decimal, restart at 10 (10..11)
-$pdf->pageLabel(20, { -start => 10 }); # 20 << /S /D /St 10 >>
+# pages $section_length+28..29 s/b blank (nocounter) with Z prefix
+$pdf->pageLabel($section_length+28, { -style => 'nocounter', -prefix => 'Z' }); 
 
-# pages 22..23 s/b Alpha, auto-restarts at 1 (A, B)
-$pdf->pageLabel(22, { -style => 'Alpha' }); # 22 << /S /A >>
+# pages $section_length+30..31 s/b prefix Index plus UC Roman
+$pdf->pageLabel($section_length+30, { 'style' => 'Roman', 'prefix' => 'Index ' }); 
 
-# pages 24..25 s/b lowercase roman, auto-restarts at 1 (i, ii)
-$pdf->pageLabel(24, { -style => 'roman' }); # 24 << /S /r >>
+# -------------
 
+# combine two calls into one for pageLabel only!
+$pdf->pageLabel($section_length+32, { style => 'alpha', start => 3 },
+	        $section_length+34, { style => 'roman', start => 4, prefix => 'App-' });
+# -------------
 $pdf->saveas("$0.pdf");
 $pdf->end();
 
diff --git a/examples/055_outlines b/examples/055_outlines
index f3eb9d9..99efae3 100644
--- a/examples/055_outlines
+++ b/examples/055_outlines
@@ -10,6 +10,7 @@ my $infile  = 'examples/resources/sample_55.pdf';
 my $outfile = 'examples/055_outlines.sample_55.pdf';
 
 my $doc = PDF::Builder-> open($infile);
+print "Use 'outline' or 'bookmark' feature on your PDF Reader to move around\n";
 
 $doc-> outlines
     -> outline
diff --git a/examples/060_transparency b/examples/060_transparency
index fe01248..ed92fc1 100644
--- a/examples/060_transparency
+++ b/examples/060_transparency
@@ -28,32 +28,28 @@ my $text = $page->text();
 # both texts bleed off right side of page
 $text->textlabel(30,750, $fnt,100, '100% Opaque', -color=>'#F00');
 
-#$text->save();
 $text->egstate($TRANSPARENT);
 $text->textlabel(30,720, $fnt,100, '40% Transparent', -color=>'#000');
-#$text->restore();
 
 # page 2: similar to page 1, but using different methods. bleed off left side.
 $page = $pdf->page();
 $text = $page->text();
 
-#$text->save();
 $text->font($fnt, 100);
 $text->fillcolor('red');
 $text->translate(570,750);
 $text->text_right('Opaque 100%');
-#$text->restore();
-$text->textend();
+$text->textend(); # back into graphics state so can do transparency
 
-$text->save();
+#$text->save();  # unnecessary, as this is the last segment
 $text->egstate($TRANSPARENT);
-$text->textstart();
+$text->textstart(); # back into text mode
 $text->font($fnt, 100);
 $text->fillcolor('black');
 $text->translate(570,720);
 $text->text_right('Transparent 40%');
 $text->textend();
-$text->restore();
+#$text->restore();
 
 $pdf->saveas("$0.pdf");
 $pdf->end();
diff --git a/examples/BarCode.pl b/examples/BarCode.pl
index 5c1707e..c82f088 100644
--- a/examples/BarCode.pl
+++ b/examples/BarCode.pl
@@ -9,7 +9,7 @@
 use warnings;
 use strict;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.023'; # manually update whenever code is changed
 
 use Math::Trig;
diff --git a/examples/Boxes.pl b/examples/Boxes.pl
index 89eeb14..3841168 100644
--- a/examples/Boxes.pl
+++ b/examples/Boxes.pl
@@ -21,7 +21,7 @@ my $trimbox_adj = 1/mm;  # in from bleed box
 my $bleedbox_adj = 36/pt;  # in from crop box on top and right for printer inst.
 my $cropbox_adj = 0.25/in;  # in from media edge
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.023'; # manually update whenever code is changed
 
 my $PDFname = $0;
diff --git a/examples/Bspline.pl b/examples/Bspline.pl
index c1f3c4e..e530961 100644
--- a/examples/Bspline.pl
+++ b/examples/Bspline.pl
@@ -33,7 +33,7 @@
 use warnings;
 use strict;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.021'; # manually update whenever code is changed
 
 use Math::Trig;
diff --git a/examples/Column.pl b/examples/Column.pl
index c85c1c0..36ee777 100644
--- a/examples/Column.pl
+++ b/examples/Column.pl
@@ -6,8 +6,8 @@ use PDF::Builder;
 #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
 
 my $use_Table = 1; # if 1, use PDF::Table for table example
 # TBD automatically check if PDF::Table available, and if so, use it
@@ -288,41 +288,41 @@ if ($use_Table) {
     my $table = PDF::Table->new();
     my $table_data = [
         # row 1, solid color lines
-    	[   
- 	    [ 'html', '<font color="red">This is some red text</font>',
-	      { 'font_size' => 12, 'para' => [ 0, 0 ] } ], 
+	[
+	    [ 'html', '<font color="red">This is some red text</font>',
+	      { 'font_size' => 12, 'para' => [ 0, 0 ] } ],
             [ 'html', "<span style=\"color:green\">This is some green text</span>",
-	      { 'font_size' => 12, 'para' => [ 0, 0 ] } ], 
-	], 
+	      { 'font_size' => 12, 'para' => [ 0, 0 ] } ],
+	],
 
         # row 2, special symbols, colored
 	[
-    	    [ 'html', 'This is a red cross: <font face="ZapfDingbats" color="red">8</font>.', 
-	      { 'font_size' => 12, 'para' => [ 0, 0 ] } ], 
-    	    [ 'html', "This is a green tick: <span style=\"font-family:ZapfDingbats; color:green\">4</span>.", 
+	    [ 'html', 'This is a red cross: <font face="ZapfDingbats" color="red">8</font>.',
+	      { 'font_size' => 12, 'para' => [ 0, 0 ] } ],
+	    [ 'html', "This is a green tick: <span style=\"font-family:ZapfDingbats; color:green\">4</span>.",
 	      { 'font_size' => 12, 'para' => [ 0, 0 ] } ], 
         ],
 
         # row 3, like row 2, but using macro substitutions
 	[
-    	    [ 'html', "This is a red cross substitute: %cross%.", 
-	      { 'font_size'=>12, 'para'=>[ 0, 0 ], 
-    		'substitute'=>[
-    		    ['%cross%','<font face="ZapfDingbats" color="red">', '8', '</font>'],
-    		    ['%tick%','<span style="font-family: ZapfDingbats; color: green;">', '4', '</span>'] ]
-	      } 
+	    [ 'html', "This is a red cross substitute: %cross%.",
+	      { 'font_size'=>12, 'para'=>[ 0, 0 ],
+		'substitute'=>[
+		    ['%cross%','<font face="ZapfDingbats" color="red">', '8', '</font>'],
+		    ['%tick%','<span style="font-family: ZapfDingbats; color: green;">', '4', '</span>'] ]
+	      }
             ],
-    	    [ 'html', "This is a green tick substitute: %tick%.", 
-    	      { 'font_size'=>12, 'para'=>[ 0, 0 ], 
-    		'substitute'=>[
-    		    ['%cross%','<font face="ZapfDingbats" color="red">', '8', '</font>'],
-    		    ['%tick%','<span style="font-family: ZapfDingbats; color: green;">', '4', '</span>'] ]
+	    [ 'html', "This is a green tick substitute: %tick%.",
+	      { 'font_size'=>12, 'para'=>[ 0, 0 ],
+		'substitute'=>[
+		    ['%cross%','<font face="ZapfDingbats" color="red">', '8', '</font>'],
+		    ['%tick%','<span style="font-family: ZapfDingbats; color: green;">', '4', '</span>'] ]
 	      }
             ],
-	],
+  	],
 
         # row 4, non-markup text
-	[ 'Plain old text', 
+	[ 'Plain old text',
 	  'More plain text'
         ],
 	             ];
@@ -447,6 +447,23 @@ $content = <<"END_OF_CONTENT";
 
 A Perl library to facilitate the creation and modification of PDF files
 
+## What is it?
+
+PDF::Builder is a **fork** of the popular PDF::API2 Perl library. It provides a 
+library of modules and functions so that a PDF file (document) may be built and 
+maintained from Perl programs. It is not a WYSIWYG editor; nor is it a canned 
+utility or converter. It does _not_ have a GUI -- it is driven by your Perl 
+program. It is a set of **building blocks** with which you can perform a wide 
+variety of operations, ranging from basic operations such as selecting a font 
+face, to defining an entire page at a time in the document, using a large 
+subset of either Markdown or HTML markup languages. You can call it from 
+arbitrary Perl programs, which may even create content on-the-fly (or read it 
+in from other sources). Quite a few code examples are provided, to help you to 
+get started with the process of creating a PDF document. Many enhancements are 
+in the pipeline to make PDF::Builder even more powerful and versatile.
+
+[Home Page](https://www.catskilltech.com/FreeSW/product/PDF%2DBuilder/title/PDF%3A%3ABuilder/freeSW_full), including Documentation and Examples.
+
 [![Open Issues](https://img.shields.io/github/issues/PhilterPaper/Perl-PDF-Builder)](https://github.com/PhilterPaper/Perl-PDF-Builder/issues)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://makeapullrequest.com)
 [![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://GitHub.com/PhilterPaper/Perl-PDF-Builder/graphs/commit-activity)
@@ -478,7 +495,7 @@ By default, none are installed.
 
 ### Perl
 
-**Perl 5.24** or higher. It will likely run on somewhat earlier versions, but
+**Perl 5.26** or higher. It will likely run on somewhat earlier versions, but
 the CPAN installer may refuse to install it. The reason this version was
 chosen was so that LTS (Long Term Support) versions of Perl going back about
 6 years are officially supported (by PDF::Builder), and older versions are not
@@ -487,14 +504,14 @@ are an artifact of old Perl releases.
 
 #### Older Perls
 
-If you MUST install on an older (pre 5.24) Perl, you can try the following for
+If you MUST install on an older (pre 5.26) Perl, you can try the following for
 Strawberry Perl (Windows). NO PROMISES! Something similar MAY work for other
 OS's and Perl installations:
 
 1. Unpack installation file (`.tar.gz`, via a utility such as 7-Zip) into a directory, and cd to that directory
-1. Edit META.json and change 5.024000 to 5.016000 or whatever level desired
-1. Edit META.yml and change 5.024000 to 5.016000 or whatever level desired
-1. Edit Makefile.PL and change `use 5.024000;` to `use 5.016000;`, change `\$PERL_version` from `5.024000` to `5.016000`
+1. Edit META.json and change 5.026000 to 5.016000 or whatever level desired
+1. Edit META.yml and change 5.026000 to 5.016000 or whatever level desired
+1. Edit Makefile.PL and change `use 5.026000;` to `use 5.016000;`, change `\$PERL_version` from `5.026000` to `5.016000`
 1. `cpan .`
 
 Note that some Perl installers MAY have a means to override or suppress the
@@ -529,11 +546,13 @@ matters, especially if an optional package fails to install. You can always
 manually install them later, if you desire to make use of their added 
 functionality.
 
+* Perl::Critic (1.150 or higher, need if running tools/1\_pc.pl)
 * Graphics::TIFF (19 or higher, recommended if using TIFF image functions)
 * Image::PNG::Libpng (0.57 or higher, recommended for enhanced PNG image function processing)
 * HarfBuzz::Shaper (0.024 or higher, needed for Latin script ligatures and kerning, as well as for any complex script such as Arabic, Indic scripts, or Khmer)
 * Text::Markdown (1.000031 or higher, needed if using 'md1' markup)
 * HTML::TreeBuilder (5.07 or higher, needed if using 'html' or 'md1' markup)
+* Pod::Simple::XHTML (3.45 or higher, needed if using buildDoc utility to create HTML documentation)
 
 If an optional package is needed, but not installed, sometimes PDF::Builder
 will be able to fall back to built-in partial functionality (TIFF and PNG 
@@ -564,7 +583,8 @@ have it under a different name, such as dmake (Strawberry Perl on Windows),
 gmake, or nmake.
 
 PDF::Builder does not currently compile and link anything, so gcc, g++, etc.
-will not be used. The build process merely copies .pm files around.
+will not be used. The build process merely copies .pm files around, and
+runs the "t" tests to confirm the proper installation.
 
 ## Copyright
 
@@ -590,11 +610,24 @@ redistribute and/or modify this software (those portions under LGPL) at an
 LGPL version greater than 2.1. See INFO/LICENSE for more information on the
 licenses and warranty statement.
 
+### Carrying On...
+
+PDF::Builder is Open Source software, built upon the efforts not only of the
+current maintainer, but also of many people before me. Therefore, it's perfectly
+fair to make use of the algorithms and even code (within the terms of the
+LICENSE). That's exactly how the State of the
+Art progresses! Just please be considerate and acknowledge the work of others
+that you are building on, as well as pointing back to this package. Drop us a
+note with news of your project (if based on the code and algorithms in
+PDF::Builder, or even just heavily inspired by it) and we'll be happy to make
+a pointer to your work. The more cross-pollination, the better!
+
 ## See Also
 
-* INFO/RoadMap file for the PDF::Builder road map
 * CONTRIBUTING file for how to contribute to the project
 * LICENSE file for more on the license term
+* INFO/RoadMap file for the PDF::Builder road map
+* INFO/ACKNOWLEDGE.md for "thank yous" to those who contributed to this product
 * INFO/SUPPORT file for information on reporting bugs, etc. via GitHub Issues 
 * INFO/DEPRECATED file for information on deprecated features
 * INFO/KNOWN\_INCOMP file for known incompatibilities with PDF::API2
@@ -611,6 +644,10 @@ and go to the `docs/` directory. Run `buildDoc.pl --all` to generate the full
 tree of documentation. There's a lot of additional information in the
 PDF::Builder::Docs module (it's all documentation).
 
+You may find it more convenient to point your browser to our 
+[Home Page](https://www.catskilltech.com/FreeSW/product/PDF-Builder/title/PDF%3A%3ABuilder/freeSW_full)
+to see the full documentation build (as well as most of the example outputs).
+
 We admit that the documentation is a bit light on "how to" task orientation.
 We hope to more fully address this in the future, but for now, get the full
 installation and look at the `examples/` and `contrib/` directories for sample
@@ -774,8 +811,53 @@ if ($rc) {
     print STDERR "list example overflowed column!\n";
 }
 
-# block quotes and font extent changes
+# Counting down (reversed) ordered lists
 print "======================================================= pg 11\n";
+print "---- Count down list examples\n";
+$page = $pdf->page();
+$text = $page->text();
+$grfx = $page->gfx();
+
+$content = <<"END_OF_CONTENT";
+<h2>Test reversed ordered lists</h2>
+<ol reversed="1" start="10">
+  <li>ten</li>
+  <li>nine</li>
+  <li>eight</li>
+  <li>seven</li>
+  <li>six</li>
+  <li>five
+  <ol>
+    <li>holding</li>
+    <li>resume countdown</li>
+  </ol></li>
+  <li>four</li>
+  <li>three</li>
+  <li>two</li>
+  <li>one</li>
+</ol>
+<h2>Reversed ordered list run past 1</h2>
+<ol reversed="1" start="3">
+  <li>three</li>
+  <li>two</li>
+  <li>one</li>
+  <li>zero... blast off!</li>
+  <li>minus one... the clock is running</li>
+</ol>
+END_OF_CONTENT
+
+restore_props($text, $grfx);
+($rc, $next_y, $unused) =
+    $text->column($page, $text, $grfx, 'html', $content, 
+	          'rect'=>[50,750, 500,450], 'outline'=>$magenta, 
+		  'para'=>[ 0, 0 ] );
+if ($rc) {
+    print STDERR "list example overflowed column!\n";
+}
+
+
+# block quotes and font extent changes
+print "======================================================= pg 12\n";
 print "---- Block quotes\n";
 $page = $pdf->page();
 $text = $page->text();
@@ -841,7 +923,7 @@ if ($rc) {
 }
 
 # setting your own CSS for Markdown or none
-print "======================================================= pg 12\n";
+print "======================================================= pg 13\n";
 $page = $pdf->page();
 $text = $page->text();
 $grfx = $page->gfx();
@@ -965,11 +1047,18 @@ if ($rc) {
 
 # might have to go to a column2.pl!
 # demonstrate balanced columns two long columns and one short, first pass
-#   fill blindly, then by trial-and-error shorten long columns until short
-#   one just fills (show initial and final runs)
+#   fill blindly, overflowing to column 2 then 3, then by trial-and-error
+#   shorten long two columns until short one just fills (show initial and
+#   final runs). graphic X-out block for ad.
+#   headline in English Towne Medium (.otf) "New Yawk Times" ("All the news
+#   that fits, we print!"). Headline under it (across 3 columns): "Congress
+#   Does Something Stoopid". Lorem Ipsum for body text.
+#   continuation to page __ method? text to output for very last line in col.
 # demonstrate column shapes that split line in two (only first part used)
 # demonstrate irregularly shaped columns, including a bowtie scaled 3 times
-# demonstrate two column layout with insets and marginpar
+# demonstrate two column layout with insets and marginpar (inset routine to
+#   place text w/ hr's, return cutout outline for columns outline creation,
+#   intersect with rectangles for columns)
 # demonstrate a circular column, etc.
 # demonstrate a spline column cutout, with image in background with edges
 #   that fade away so text can overlap outer fringes of image
diff --git a/examples/Content.pl b/examples/Content.pl
index da32d1d..9b70b04 100644
--- a/examples/Content.pl
+++ b/examples/Content.pl
@@ -6,7 +6,7 @@
 use warnings;
 use strict;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.023'; # manually update whenever code is changed
 
 use Math::Trig;
diff --git a/examples/ContentText.pl b/examples/ContentText.pl
index dfa9ff3..9af7192 100644
--- a/examples/ContentText.pl
+++ b/examples/ContentText.pl
@@ -6,7 +6,7 @@
 use warnings;
 use strict;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.023'; # manually update whenever code is changed
 
 use Math::Trig;
diff --git a/examples/FontManager.pl b/examples/FontManager.pl
index 7ccdbf8..bb39d8c 100644
--- a/examples/FontManager.pl
+++ b/examples/FontManager.pl
@@ -7,7 +7,7 @@
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.024_002'; # manually update whenever code is changed
 
 use PDF::Builder;
diff --git a/examples/HarfBuzz.pl b/examples/HarfBuzz.pl
index 7a051dd..3cd9183 100644
--- a/examples/HarfBuzz.pl
+++ b/examples/HarfBuzz.pl
@@ -6,7 +6,7 @@
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.021'; # manually update whenever code is changed
 
 my $PDFname = $0;
diff --git a/examples/Rotated.pl b/examples/Rotated.pl
index c225966..7785e36 100644
--- a/examples/Rotated.pl
+++ b/examples/Rotated.pl
@@ -7,7 +7,7 @@
 use warnings;
 use strict;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.023'; # manually update whenever code is changed
 
 use PDF::Builder;
diff --git a/examples/ShowFont.pl b/examples/ShowFont.pl
index 9ff58a9..a663512 100644
--- a/examples/ShowFont.pl
+++ b/examples/ShowFont.pl
@@ -7,7 +7,7 @@
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.021'; # manually update whenever code is changed
 
 use PDF::Builder;
diff --git a/examples/Windows/Win32.pm b/examples/Windows/Win32.pm
index b75560a..3a78125 100644
--- a/examples/Windows/Win32.pm
+++ b/examples/Windows/Win32.pm
@@ -4,7 +4,7 @@ use strict;
 use warnings;
 #no warnings qw[ deprecated recursion uninitialized ];
 
-our $VERSION = '3.025'; # VERSION
+our $VERSION = '3.026'; # VERSION
 our $LAST_UPDATE = '3.021'; # manually update whenever code is changed
 
 use Win32::TieRegistry qw( :KEY_ );  # creates $Registry, et al.
diff --git a/lib/PDF/Builder.pm b/lib/PDF/Builder.pm
index f1daad6..96518fe 100644
--- a/lib/PDF/Builder.pm
+++ b/lib/PDF/Builder.pm
@@ -5,8 +5,8 @@ use warnings;
 
 # $VERSION defined here so developers can run PDF::Builder from git.
 # it should be automatically updated as part of the CPAN build.
-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
 
 # updated during CPAN build
 my $GrTFversion  = 19;       # minimum version of Graphics::TIFF
@@ -14,6 +14,7 @@ my $HBShaperVer  = 0.024;    # minimum version of HarfBuzz::Shaper
 my $LpngVersion  = 0.57;     # minimum version of Image::PNG::Libpng
 my $TextMarkdown = 1.000031; # minimum version of Text::Markdown
 my $HTMLTreeBldr = 5.07;     # minimum version of HTML::TreeBuilder
+my $PodSimpleXHTML = 3.45;   # minimum version of Pod::Simple::XHTML
 
 use Carp;
 use Encode qw(:all);
@@ -47,17 +48,21 @@ my @font_path = __PACKAGE__->set_font_path(
 		  '/usr/local/share/fonts',
 		  '/usr/share/fonts/type1/gsfonts',
 		  '/usr/share/X11/fonts/urw-fonts',
+		  '/usr/share/fonts/urw-base35',
 		  '/usr/share/fonts/dejavu-sans-fonts',
 		  '/usr/share/fonts/truetype/ttf-dejavu',
 		  '/usr/share/fonts/truetype/dejavu',
 		  '/var/lib/defoma/gs.d/dirs/fonts',
 		  '/Windows/Fonts',
+		  '/Users/XXXX/AppData/Local/Microsoft/Windows/Fonts',
 		  '/WinNT/Fonts'
 	                                  );
 
 our @MSG_COUNT = (0,  # [0] Graphics::TIFF not installed
 	          0,  # [1] Image::PNG::Libpng not installed
-		  0,  # [2] TBD...
+		  0,  # [2] save/restore in text mode
+		  0,  # [3] Times-Roman core font substituted for Times
+		  0,  # [4] TBD...
 	         );
 our $outVer = 1.4; # desired PDF version for output, bump up w/ warning on read or feature output
 our $msgVer = 1;   # 0=don't, 1=do issue message when PDF output version is bumped up
@@ -156,24 +161,39 @@ The intent is to avoid expending unnecessary effort in supporting very old
 
 =head3 Anticipated Support Cutoff Dates
 
-B<Note that these are I<not> hard and fast dates. In particular, we develop
-on Strawberry Perl, which is currently stuck at release 5.32! We'll have to
-see whether we can get around this problem in the summer of 2023, if Strawberry
-hasn't yet gotten up to at least 5.36 by then.>
+B<Note> that these are I<not> hard and fast dates. In particular, we develop
+on Strawberry Perl, which sometimes falls a little behind the official Perl
+release!
 
 =over
 
-=item * 5.24 current minimum supported version, until next PDF::Builder release after 30 May, 2023
+=item * 
 
-=item * 5.26 future minimum supported version, until next PDF::Builder release after 23 June, 2024
+5.26 current minimum supported version, until next PDF::Builder release after 23 June, 2024. This is currently the minimum tested version.
 
-=item * 5.28 future minimum supported version, until next PDF::Builder release after 22 May, 2025
+=item * 
 
-=item * 5.30 future minimum supported version, until next PDF::Builder release after 20 June, 2026
+5.28 future minimum supported version, until next PDF::Builder release after 22 May, 2025
 
-=item * 5.32 future minimum supported version, until next PDF::Builder release after 20 May, 2027
+=item * 
 
-=item * 5.34 future minimum supported version, until next PDF::Builder release after 28 May, 2028
+5.30 future minimum supported version, until next PDF::Builder release after 20 June, 2026
+
+=item * 
+
+5.32 future minimum supported version, until next PDF::Builder release after 20 May, 2027. This is currently our primary development version.
+
+=item * 
+
+5.34 future minimum supported version, until next PDF::Builder release after 28 May, 2028
+
+=item * 
+
+5.36 future minimum supported version, until next PDF::Builder release after 02 Jul, 2029
+
+=item * 
+
+5.38 future minimum supported version, until next PDF::Builder release some time after 02 Jul, 2029. This is currently the maximum tested version.
 
 =back
 
@@ -261,14 +281,18 @@ PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
 
 =head1 GENERAL PURPOSE METHODS
 
-=over
+=head2 new
+
+    $pdf = PDF::Builder->new(%opts)
 
-=item $pdf = PDF::Builder->new(%opts)
+=over
 
 Creates a new PDF object. 
 
 B<Options>
 
+=back
+
 =over
 
 =item file
@@ -414,9 +438,13 @@ sub new {
     return $self;
 } # end of new()
 
-=item $pdf->default_page_size($size); # Set
+=head2 default_page_size
+
+    $pdf->default_page_size($size); # Set
+
+    @rectangle = $pdf->default_page_size() # Get
 
-=item @rectangle = $pdf->default_page_size() # Get
+=over
 
 Set the default physical size for pages in the PDF.  If called without
 arguments, return the coordinates of the rectangle describing the default
@@ -427,6 +455,8 @@ and added for compatibility with PDF::API2.
 
 See L<PDF::Builder::Page/Page Sizes> for possible values.
 
+=back
+
 =cut
 
 sub default_page_size {
@@ -442,9 +472,13 @@ sub default_page_size {
     return @{$boundaries->{'media'}};
 }
 
-=item $pdf->default_page_boundaries(%boundaries); # Set
+=head2 default_page_boundaries
 
-=item %boundaries = $pdf->default_page_boundaries(); # Get
+    $pdf->default_page_boundaries(%boundaries); # Set
+
+    %boundaries = $pdf->default_page_boundaries(); # Get
+
+=over
 
 Set default prepress page boundaries for pages in the PDF.  If called without
 arguments, returns the coordinates of the rectangles describing each of the
@@ -453,6 +487,8 @@ supported page boundaries.
 See the equivalent C<page_boundaries> method in L<PDF::Builder::Page> for 
 details.
 
+=back
+
 =cut
 
 # Called by PDF::Builder::Page::boundaries via the default_page_* methods below
@@ -517,18 +553,20 @@ sub default_page_boundaries {
 #    return $self->_bounding_box('ArtBox', page_size(@_));
 #}
 
-=back
-
 =head1 INPUT/OUTPUT METHODS
 
-=over
+=head2 open
+
+    $pdf = PDF::Builder->open($pdf_file, %opts)
 
-=item $pdf = PDF::Builder->open($pdf_file, %opts)
+=over
 
 Opens an existing PDF file. See C<new()> for options.
 
 B<Example:>
 
+=back
+
     $pdf = PDF::Builder->open('our/old.pdf');
     ...
     $pdf->saveas('our/new.pdf');
@@ -572,10 +610,16 @@ sub open {  ## no critic
     return $self;
 } # end of open()
 
-=item $pdf = PDF::Builder->from_string($pdf_string, %opts)
+=head2 from_string, open_scalar, openScalar
+
+    $pdf = PDF::Builder->from_string($pdf_string, %opts)
+
+=over
 
 Opens a PDF contained in a string. See C<new()> for other options.
 
+=back
+
 =over
 
 =item diags => 1
@@ -596,6 +640,8 @@ B<Example:>
     ...
     $pdf->saveas('our/new.pdf');
 
+=over
+
 B<Alternate name:> C<open_scalar>
 
 C<from_string> was formerly known as C<open_scalar> (and even before that,
@@ -604,6 +650,8 @@ valid as an alternative to C<from_string>. It is I<possible> that C<open_scalar>
 will be deprecated and then removed some time in the future, so it may be
 advisable to use C<from_string> in new work.
 
+=back
+
 =cut
 
 sub open_scalar { return from_string(@_); } ## no critic
@@ -616,11 +664,13 @@ sub from_string {
     if (defined $opts{'-compress'} && !defined $opts{'compress'}) { $opts{'compress'} = delete($opts{'-compress'}); }
     if (defined $opts{'-diaglevel'} && !defined $opts{'diaglevel'}) { $opts{'diaglevel'} = delete($opts{'-diaglevel'}); }
 
-    my $self = {};
-    bless $self, $class;
-    foreach my $parameter (keys %opts) {
-        $self->default($parameter, $opts{$parameter});
-    }
+    if (ref($class)) { $class = ref($class); }
+#   my $self = {};
+#   bless $self, $class;
+#   foreach my $parameter (keys %opts) {
+#       $self->default($parameter, $opts{$parameter});
+#   }
+    my $self = $class->new(%opts);
 
     $self->{'content_ref'} = \$content;
     my $diaglevel = 2;
@@ -701,7 +751,11 @@ sub from_string {
     return $self;
 } # end of from_string()
 
-=item $string = $pdf->to_string()
+=head2 to_string, stringify
+
+    $string = $pdf->to_string()
+
+=over
 
 Return the document as a string and remove the object structure from memory.
 
@@ -711,10 +765,14 @@ messages about "can't call method new_obj on an undefined value".
 
 B<Example:>
 
+=back
+
     $pdf = PDF::Builder->new();
     ...
     print $pdf->to_string();
 
+=over
+
 B<Alternate name:> C<stringify>
 
 C<to_string> was formerly known as C<stringify>, and this older name is still
@@ -722,6 +780,8 @@ valid as an alternative to C<to_string>. It is I<possible> that C<stringify>
 will be deprecated and then removed some time in the future, so it may be
 advisable to use C<to_string> in new work.
 
+=back
+
 =cut
 
 # Maintainer's note: The object is being destroyed because it contains
@@ -760,24 +820,34 @@ sub to_string {
     return $string;
 }
 
-=item $pdf->finishobjects(@objects)
+=head2 finishobjects
+
+    $pdf->finishobjects(@objects)
+
+=over
 
 Force objects to be written to file if possible.
 
 B<Example:>
 
+=back
+
     $pdf = PDF::Builder->new(file => 'our/new.pdf');
     ...
     $pdf->finishobjects($page, $gfx, $txt);
     ...
     $pdf->save();
 
+=over
+
 B<Note:> this method is now considered obsolete, and may be deprecated. It
 allows for objects to be written to disk in advance of finally
 saving and closing the file.  Otherwise, it's no different than just calling
 C<save()> when all changes have been made.  There's no memory advantage since
 C<ship_out> doesn't remove objects from memory.
 
+=back
+
 =cut
 
 # obsolete, use save instead
@@ -831,20 +901,30 @@ sub _proc_pages {
     return @pages;
 } # end of _proc_pages()
 
-=item $pdf->update()
+=head2 update
+
+    $pdf->update()
+
+=over
 
 Saves a previously opened document.
 
 B<Example:>
 
+=back
+
     $pdf = PDF::Builder->open('our/to/be/updated.pdf');
     ...
     $pdf->update();
 
+=over
+
 B<Note:> it is considered better to simply C<save()> the file, rather than
 calling C<update()>. They end up doing the same thing, anyway. This method
 may be deprecated in the future.
 
+=back
+
 =cut
 
 # obsolete, use save instead
@@ -854,7 +934,11 @@ sub update {
     return;
 }
 
-=item $pdf->saveas($file)
+=head2 saveas
+
+    $pdf->saveas($file)
+
+=over
 
 Save the document to $file and remove the object structure from memory.
 
@@ -864,6 +948,8 @@ messages about "can't call method new_obj on an undefined value".
 
 B<Example:>
 
+=back
+
     $pdf = PDF::Builder->new();
     ...
     $pdf->saveas('our/new.pdf');
@@ -890,9 +976,13 @@ sub saveas {
     return;
 }
 
-=item $pdf->save()
+=head2 save
 
-=item $pdf->save(filename)
+    $pdf->save()
+
+    $pdf->save(filename)
+
+=over
 
 Save the document to an already-defined file (or filename) and 
 remove the object structure from memory.
@@ -904,10 +994,14 @@ messages about "can't call method new_obj on an undefined value".
 
 B<Example:>
 
+=back
+
     $pdf = PDF::Builder->new(file => 'file_to_output');
     ...
     $pdf->save();
 
+=over
+
 B<Note:> now that C<save()> can take a filename as an argument, it effectively
 is interchangeable with C<saveas()>. This is strictly for compatibility with
 recent changes to PDF::API2. Unlike PDF::API2, we are not deprecating
@@ -915,6 +1009,8 @@ the C<saveas()> method, because in user interfaces, "save" normally means that
 the current filename is known and is to be used, while "saveas" normally means
 that (whether or not there is a current filename) a new filename is to be used.
 
+=back
+
 =cut
 
 sub save {
@@ -939,7 +1035,11 @@ sub save {
     return;
 }
 
-=item $pdf->close();
+=head2 close, release, end
+
+    $pdf->close();
+
+=over
 
 Close an open file (if relevant) and remove the object structure from memory.
 
@@ -952,9 +1052,15 @@ files and not writing them.
 
 B<Alternate names:> C<release> and C<end>
 
+=back
+
 =cut
 
-=item $pdf->end()
+=head2 end
+
+    $pdf->end()
+
+=over
 
 Remove the object structure from memory. PDF::Builder contains circular
 references, so this call is necessary in long-running processes to
@@ -968,6 +1074,8 @@ This (and I<release>) are older and now deprecated names formerly used in
 PDF::API2 and PDF::Builder. You should try to avoid having to explicitly
 call them.
 
+=back
+
 =cut
 
 # Deprecated (renamed)
@@ -986,18 +1094,20 @@ sub close {
     return;
 }
 
-=back
-
 =head2 METADATA METHODS
 
-=over
+=head3 title
 
-=item $title = $pdf->title();
+    $title = $pdf->title();
 
-=item $pdf = $pdf->title($title);
+    $pdf = $pdf->title($title);
+
+=over
 
 Get/set/clear the document's title.
 
+=back
+
 =cut
 
 sub title {
@@ -1005,12 +1115,18 @@ sub title {
     return $self->info_metadata('Title', @_);
 }
 
-=item $author = $pdf->author();
+=head3 author
+
+    $author = $pdf->author();
 
-=item $pdf = $pdf->author($author);
+    $pdf = $pdf->author($author);
+
+=over
 
 Get/set/clear the name of the person who created the document.
 
+=back
+
 =cut
 
 sub author {
@@ -1018,12 +1134,18 @@ sub author {
     return $self->info_metadata('Author', @_);
 }
 
-=item $subject = $pdf->subject();
+=head3 subject
+
+    $subject = $pdf->subject();
 
-=item $pdf = $pdf->subject($subject);
+    $pdf = $pdf->subject($subject);
+
+=over
 
 Get/set/clear the subject of the document.
 
+=back
+
 =cut
 
 sub subject {
@@ -1031,12 +1153,18 @@ sub subject {
     return $self->info_metadata('Subject', @_);
 }
 
-=item $keywords = $pdf->keywords();
+=head3 keywords
+
+    $keywords = $pdf->keywords();
 
-=item $pdf = $pdf->keywords($keywords);
+    $pdf = $pdf->keywords($keywords);
+
+=over
 
 Get/set/clear a space-separated string of keywords associated with the document.
 
+=back
+
 =cut
 
 sub keywords {
@@ -1044,13 +1172,19 @@ sub keywords {
     return $self->info_metadata('Keywords', @_);
 }
 
-=item $creator = $pdf->creator();
+=head3 creator
 
-=item $pdf = $pdf->creator($creator);
+    $creator = $pdf->creator();
+
+    $pdf = $pdf->creator($creator);
+
+=over
 
 Get/set/clear the name of the product that created the document prior to its
 conversion to PDF.
 
+=back
+
 =cut
 
 sub creator {
@@ -1058,15 +1192,21 @@ sub creator {
     return $self->info_metadata('Creator', @_);
 }
 
-=item $producer = $pdf->producer();
+=head3 producer
+
+    $producer = $pdf->producer();
+
+    $pdf = $pdf->producer($producer);
 
-=item $pdf = $pdf->producer($producer);
+=over
 
 Get/set/clear the name of the product that converted the original document to
 PDF.
 
 PDF::Builder fills in this field when creating a PDF.
 
+=back
+
 =cut
 
 sub producer {
@@ -1074,9 +1214,13 @@ sub producer {
     return $self->info_metadata('Producer', @_);
 }
 
-=item $date = $pdf->created();
+=head3 created
 
-=item $pdf = $pdf->created($date);
+    $date = $pdf->created();
+
+    $pdf = $pdf->created($date);
+
+=over
 
 Get/set/clear the document's creation date.
 
@@ -1085,8 +1229,13 @@ identifying the string as a PDF date.  The date may be truncated at any point
 after the year.  C<O> is one of C<+>, C<->, or C<Z>, with the following C<HH'mm>
 representing an offset from UTC.
 
+See comments in the internal function C<_is_date()> for more information on
+the inconsistency of PDF standards on exactly what the date format should be!
+
 When setting the date, C<D:> will be prepended automatically if omitted.
 
+=back
+
 =cut
 
 sub created {
@@ -1094,13 +1243,22 @@ sub created {
     return $self->info_metadata('CreationDate', @_);
 }
 
-=item $date = $pdf->modified();
+=head3 modified
+
+    $date = $pdf->modified();
 
-=item $pdf = $pdf->modified($date);
+    $pdf = $pdf->modified($date);
+
+=over
 
 Get/set/clear the document's modification date.  The date format is as described
 in C<created> above.
 
+See comments in the internal function C<_is_date()> for more information on
+the inconsistency of PDF standards on exactly what the date format should be!
+
+=back
+
 =cut
 
 sub modified {
@@ -1111,58 +1269,225 @@ sub modified {
 sub _is_date {
     my $value = shift();
 
+    # there are lists of leap seconds floating around, such as
+    # https://www.ietf.org/timezones/data/leap-seconds.list
+    # https://en.wikipedia.org/wiki/Leap_second
+    my %leap_sec = ('06'=>{
+	    1972=>1, 1981=>1, 1982=>1, 1983=>1, 1985=>1, 1992=>1, 
+	    1993=>1, 1994=>1, 1997=>1, 2012=>1, 2015=>1},
+                    '12'=>{
+	    1972=>1, 1973=>1, 1974=>1, 1975=>1, 1976=>1, 1977=>1, 
+	    1978=>1, 1979=>1, 1987=>1, 1989=>1, 1990=>1, 1995=>1, 
+	    1998=>1, 2005=>1, 2008=>1, 2016=>1});
+    # some sources list Dec 1971 as having a leap second, others don't
+
     # PDF 1.7 section 7.9.4 describes the required date format.  Other than the
     # D: prefix and the year, all components are optional but must be present if
-    # a later component is present.  No provision is made in the specification
-    # for leap seconds, etc.
-    return unless $value =~ /^D:([0-9]{4})        # D:YYYY (required)
-                             (?:([01][0-9])       # Month (01-12)
-                             (?:([0123][0-9])     # Day (01-31)
-                             (?:([012][0-9])      # Hour (00-23)
-                             (?:([012345][0-9])   # Minute (00-59)
-                             (?:([012345][0-9])   # Second (00-59)
-                             (?:([Z+-])           # UT Offset Direction
-                             (?:([012][0-9])      # UT Offset Hours
-                             (?:\'([012345][0-9]) # UT Offset Minutes
-                             )?)?)?)?)?)?)?)?$/x;
-    my ($year, $month, $day, $hour, $minute, $second, $od, $oh, $om)
-        = ($1, $2, $3, $4, $5, $6, $7, $8, $9);
-
-    # Do some basic validation to catch accidental date formatting issues.
-    # Complete date validation is out of scope.
-    if (defined $month) {
-        return unless $month >= 1 and $month <= 12;
-    }
-    if (defined $day) {
-        return unless $day >= 1 and $day <= 31;
-    }
-    if (defined $hour) {
-        return unless $hour <= 23;
-    }
-    if (defined $minute) {
-        return unless $minute <= 59;
+    # a later component is present.
+    #
+    # comments by PM Perry:
+    # There is some conflict among various Adobe/ISO reference documents, as
+    # well as ambiguity within them (e.g., the example drops the seconds
+    # field, a trailing ' may or may not be required in a TZ offset). In 
+    # addition, the PDF format seems to be something of a subset of ISO 8601. 
+    # I have attempted to satisfy as many of the Adobe PDF reference documents 
+    # as I could, but there are no guarantees that all PDF editors and readers 
+    # will accept any given date/timestamp! 
+    # See https://www.rfc-editor.org/rfc/rfc3339#section-5.6, remembering that 
+    # many ISO 8601-compliant stamps will be considered invalid here. If there
+    # is demand for it, additional formats might be supported, and even a 
+    # format or flag that says, "Here is my timestamp. Do not validate -- trust
+    # me, I know what I'm doing!"
+     
+    my ($year, $month, $day, $hour, $minute, $second, $od, $oh, $om, $ts, $tz);
+    if ($value =~ /([Z+-])/) { # should be only zero (leave od undef) or one
+        $od = $1;
+    } else {
+	$od = undef; # in case value left over from previous data
     }
-    if (defined $second) {
-        return unless $second <= 59;
+    # make sure od defined (and not empty)
+    $od ||= 'Z';
+    # ts must always have something, tz might not
+    ($ts, $tz) = split /[Z+-]/, $value;
+    $tz ||= '';
+
+    return 0 unless $ts =~ /^D:([0-9]{4})        # D:YYYY (required)
+                            (?:([0-1][0-9])      # Month (01-12)
+                            (?:([0-3][0-9])      # Day (01-31)
+                            (?:([0-2][0-9])      # Hour (00-23)
+                            (?:([0-5][0-9])      # Minute (00-59)
+                            (?:([0-6][0-9])      # Second (00-59), also leap sec
+                            ?)?)?)?)?)?$/x;
+    ($year, $month, $day, $hour, $minute, $second)
+        = ($1, $2, $3, $4, $5, $6);
+    $month  ||= 1;
+    $day    ||= 1;
+    $hour   ||= 0;
+    $minute ||= 0;
+    $second ||= 0;
+
+    # od is Z (tz s/b ''), or od is + or - with hh or more
+    if ($od ne 'Z') {
+	# must be + or -, and at least an hour given
+	# ' before minutes (if given), optional ' after minutes
+        # regexp should fail if tz is ''
+        return 0 unless $tz =~ /^([0-2][0-9])        # UT Offset Hours   
+                                (?:'?([0-5][0-9])    # UT Offset Minutes
+	                        (?:'                 # optional '
+                                ?)?)?$/x;
+        ($oh, $om) = ($1, $2);
+	$oh ||= 0;
+	$om ||= 0;
+	if ($oh == 0 && $om  == 0) {
+	    # +/- 0 offset, so just make it Z
+	    $od = 'Z';
+	}
+    } else {
+        # explicit Z spec, shouldn't have an offset
+	if ($tz ne '') {
+            carp "Ignoring hour['minute] offset with Z timezone\n";
+	}
+	$oh = $om = 0;
     }
-    if (defined $od) {
-        return if $od eq 'Z' and defined($oh);
+    $oh ||= 0;
+    $om ||= 0;
+    if ($oh == 0 && $om == 0) { $od = 'Z'; 
     }
-    if (defined $oh) {
-        return unless $oh <= 23;
+
+    # Do some basic validation to catch accidental date formatting issues.
+    # Complete date validation is out of scope.
+    # add determination of leap year and leap day
+    # treat ALL years as Gregorian calendar!
+    my $is_leap;
+    if      ($year % 400 == 0) { 
+	$is_leap = 1; 
+    } elsif ($year % 100 == 0) {
+	$is_leap = 0; 
+    } elsif ($year % 4   == 0) {
+	$is_leap = 1; 
+    } else {
+	$is_leap = 0; 
     }
-    if (defined $om) {
-        return unless $om <= 59;
+    my @mon_len = (31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31);
+    if ($is_leap) { $mon_len[1]++; }
+
+    return 0 unless $month >= 1 and $month <= 12;
+    return 0 unless $day >= 1 and $day <= 31;
+    return 0 if $day > $mon_len[$month-1];  # added exact month length check
+    return 0 unless $hour <= 23;
+    return 0 unless $minute <= 59;
+    return 0 unless $oh <= 23;
+    return 0 unless $om <= 59;
+    return 0 if $second > 60;
+    if ($second == 60) {
+	# claimed leap second -- verify
+	# remember that +oh/om can place local date into next year!
+	# correct local date and time (per offset) to UTC (Z)
+	my $newy = $year;
+	my $newM = $month;
+	my $newd = $day;
+	my $newh = $hour;
+	my $newm = $minute;
+	# assuming tz offset won't move more than 1 day either way
+	# (max offset 12 or 13 hours?)
+	# we're really only interested if date/time adjusted to Z is
+	#   June 30 or December 31 at 23:59:60Z, for certain years
+	if      ($od eq '+') {
+	    # sub h:m could put us in previous day (and month, but not year)
+	    # if not, it's not possibly 23:59:60Z
+	    $newh -= $oh;
+	    $newm -= $om;
+	    if ($newm < 0) {
+	        $newm += 60; 
+		$newh--;
+	    }
+	    if ($newh < 0) { 
+		$newh += 24;
+		$newd--;
+		if ($newd == 0) {
+		    # local was first day of Jan or Jul?
+		    $newM--;
+		    if ($newM == 0) {
+			$newM = 12;
+			$newd = 31;
+			$newy--;
+		    } elsif ($newM == 6) {
+			$newd = 30;
+		    } else {
+			# last day of previous month, not Dec or Jun
+			return 0;
+		    }
+		} else {
+		    return 0; # wasn't last day of Dec or Jun (local date)
+		}
+       	    } else {
+	        # if got to here, didn't back up to previous day
+		return 0;
+	    }
+
+	} elsif ($od eq '-') {
+	    # add h:m could put us in next day (and month, and even year)
+	    $newh += $oh;
+	    $newm += $om;
+	    if ($newm > 59) {
+	        $newm -= 60; 
+		$newh++;
+	    }
+	    if ($newh > 23) { 
+		$newh -= 24;
+		$newd++;
+		if ($newd > $mon_len[$month-1]) {
+		    # local was last day of month, now (Z) 1st, wrong date
+		    $newM++;
+		    $newd = 1;
+		    if ($newM > 12) {
+			$newM = 1;
+			$newy++;
+		    }
+		    return 0; # ended up on 1st of a month, invalid leap second
+		}
+	    }
+	    # only Dec 31 and Jun 30 are eligible for consideration
+	    if (!($newM ==  6 && $newd == 30 ||
+	          $newM == 12 && $newd == 31)) {
+	        return 0;
+            }
+
+	} else {
+	    # local time is already Z, just use newh and newm
+	    if (!($newM == 6 && $newd == 30 ||
+		  $newM == 12 && $newd == 31)) {
+	        return 0;  # not Dec 31 or Jun 30
+	    }
+	}
+
+	# time newh:newm corrected to Z. check if 23:59.
+	# date corrected to Z, is OK (Dec 31 or Jun 30), 
+	#   check if is actual leap second date.
+        if ($newh == 23 && $newm == 59 && # second is 60
+	    defined $leap_sec{$newM}->{$newy}
+	    # assuming value is +1. if ever -1, need more code TBD
+	    #  (23:59:58 would be last second of month)
+	    # already on last day of listed month. at 23:59:60Z?
+	    # valid leap second
+	   ) {
+	} else {
+	    return 0;
+	}
     }
 
     return 1;
 }
 
-=item %info = $pdf->info_metadata(); # Get all keys and values
+=head3 info_metadata
+
+    %info = $pdf->info_metadata(); # Get all keys and values
 
-=item $value = $pdf->info_metadata($key); # Get the value of one key
+    $value = $pdf->info_metadata($key); # Get the value of one key
 
-=item $pdf = $pdf->info_metadata($key, $value); # Set the value of one key
+    $pdf = $pdf->info_metadata($key, $value); # Set the value of one key
+
+=over
 
 Get/set/clear a key in the document's information dictionary.  The standard keys
 (title, author, etc.) have their own accessors, so this is primarily intended
@@ -1170,6 +1495,12 @@ for interacting with custom metadata.
 
 Pass C<undef> as the value in order to remove the key from the dictionary.
 
+See comments in the internal function C<_is_date()> for more information on
+the inconsistency of PDF standards on exactly what the date format should be!
+This applies to CreationDate and ModDate keys.
+
+=back
+
 =cut
 
 sub info_metadata {
@@ -1196,6 +1527,7 @@ sub info_metadata {
 
         if ($field eq 'CreationDate' or $field eq 'ModDate') {
             if (defined ($value)) {
+		# make sure date/timestamp starts with D:
                 $value = 'D:' . $value unless $value =~ /^D:/;
                 croak "Invalid date string: $value" unless _is_date($value);
             }
@@ -1227,9 +1559,13 @@ sub info_metadata {
     return $self->{'pdf'}->{'Info'}->{$field}->val();
 }
 
-=item %infohash = $pdf->info()
+=head3 info
+
+    %infohash = $pdf->info()
 
-=item %infohash = $pdf->info(%infohash)
+    %infohash = $pdf->info(%infohash)
+
+=over
 
 Gets/sets the info structure of the document.
 
@@ -1239,6 +1575,8 @@ of this method.
 B<Note:> this method is still available, for compatibility purposes. It is
 better to use individual accessors or C<info_metadata> instead.
 
+=back
+
 =cut
 
 sub info {
@@ -1275,23 +1613,33 @@ sub info {
     return %opt;
 } # end of info()
 
-=item @metadata_attributes = $pdf->infoMetaAttributes()
+=head3 infoMetaAttributes
+
+    @metadata_attributes = $pdf->infoMetaAttributes()
 
-=item @metadata_attributes = $pdf->infoMetaAttributes(@metadata_attributes)
+    @metadata_attributes = $pdf->infoMetaAttributes(@metadata_attributes)
+
+=over
 
 Gets/sets the supported info-structure tags.
 
 B<Example:>
 
+=back
+
     @attributes = $pdf->infoMetaAttributes;
     print "Supported Attributes: @attr\n";
 
     @attributes = $pdf->infoMetaAttributes('CustomField1');
     print "Supported Attributes: @attributes\n";
 
+=over
+
 B<Note:> this method is still available for compatibility purposes, but the
 use of C<info_metadata> instead is encouraged.
 
+=back
+
 =cut
 
 sub infoMetaAttributes {
@@ -1305,12 +1653,18 @@ sub infoMetaAttributes {
     return @{$self->{'infoMeta'}};
 }
 
-=item $xml = $pdf->xml_metadata();
+=head3 xml_metadata
+
+    $xml = $pdf->xml_metadata();
 
-=item $pdf = $pdf->xml_metadata($xml);
+    $pdf = $pdf->xml_metadata($xml);
+
+=over
 
 Gets/sets the document's XML metadata stream.
 
+=back
+
 =cut
 
 sub xml_metadata {
@@ -1342,9 +1696,13 @@ sub xml_metadata {
     return $md->{' stream'};
 }
 
-=item $xml = $pdf->xmpMetadata()  # Get
+=head3 xmpMetadata
+
+    $xml = $pdf->xmpMetadata()  # Get
 
-=item $xml = $pdf->xmpMetadata($xml)  # Set (also returns $xml value)
+    $xml = $pdf->xmpMetadata($xml)  # Set (also returns $xml value)
+
+=over
 
 Gets/sets the XMP XML data stream.
 
@@ -1353,6 +1711,8 @@ of this method.
 
 This method is considered B<obsolete>. Use C<xml_metadata> instead.
 
+=back
+
 =cut
 
 sub xmpMetadata {
@@ -1368,14 +1728,20 @@ sub xmpMetadata {
     return $self->xml_metadata();
 } 
 
-=item $val = $pdf->default($parameter)
+=head3 default
+
+    $val = $pdf->default($parameter)
 
-=item $pdf->default($parameter, $value)
+    $pdf->default($parameter, $value)
+
+=over
 
 Gets/sets the default value for a behavior of PDF::Builder.
 
 B<Supported Parameters:>
 
+=back
+
 =over
 
 =item nounrotate
@@ -1394,10 +1760,14 @@ enables importing of annotations (B<*EXPERIMENTAL*>).
 
 =back
 
+=over
+
 B<CAUTION:> Perl::Critic (tools/1_pc.pl) has started flagging the name 
 "default" as a reserved keyword in higher Perl versions. Use with caution, and
 be aware that this name I<may> have to be changed in the future.
 
+=back
+
 =cut
 
 sub default {
@@ -1415,9 +1785,13 @@ sub default {
     return $previous_value;
 }
 
-=item $version = $pdf->version() # Get
+=head3 version
+
+    $version = $pdf->version() # Get
 
-=item $version = $pdf->version($version) # Set (also returns newly set version)
+    $version = $pdf->version($version) # Set (also returns newly set version)
+
+=over
 
 Gets/sets the PDF version (e.g., 1.5). 
 For compatibility with earlier releases, if no decimal point is given, assume
@@ -1429,6 +1803,8 @@ might have already read in a higher level file, or used a higher level feature.
 See L<PDF::Builder::Basic::PDF::File> for additional information on the
 C<version> method.
 
+=back
+
 =cut
 
 sub version {
@@ -1498,7 +1874,11 @@ sub verCheckInput {
     }
 }
 
-=item $bool = $pdf->is_encrypted()
+=head3 is_encrypted, isEncrypted
+
+    $bool = $pdf->is_encrypted()
+
+=over
 
 Checks if the previously opened PDF is encrypted.
 
@@ -1506,6 +1886,8 @@ B<Alternate name:> C<isEncrypted>
 
 This is the older name; it is kept for compatibility with PDF::API2.
 
+=back
+
 =cut
 
 sub isEncrypted { return is_encrypted(@_); } ## no critic
@@ -1515,13 +1897,13 @@ sub is_encrypted {
     return defined($self->{'pdf'}->{'Encrypt'}) ? 1 : 0;
 }
 
-=back
-
 =head1 INTERACTIVE FEATURE METHODS
 
-=over
+=head2 outline, outlines
 
-=item $otls = $pdf->outline()
+    $otls = $pdf->outline()
+
+=over
 
 Creates (if needed) and returns the document's 'outline' tree, which is also 
 known as its 'bookmarks' or the 'table of contents', depending on the 
@@ -1533,6 +1915,8 @@ B<Alternate name:> C<outlines>
 
 This is the older name; it is kept for compatibility.
 
+=back
+
 =cut
 
 sub outlines { return outline(@_); } ## no critic
@@ -1586,14 +1970,20 @@ sub outline {
 #    return $self;
 #}
 
-=item $layout = $pdf->page_layout();
+=head2 page_layout
 
-=item $pdf = $pdf->page_layout($layout);
+    $layout = $pdf->page_layout();
+
+    $pdf = $pdf->page_layout($layout);
+
+=over
 
 Gets/sets the page layout that should be used when the PDF is opened.
 
 C<$layout> is one of the following:
 
+=back
+
 =over
 
 =item single_page (or undef)
@@ -1622,9 +2012,13 @@ Display two pages at a time, with odd-numbered pages on the right.
 
 =back
 
+=over
+
 This has been split out from C<preferences()> for compatibility with PDF::API2.
 It also can both set (assign) and get (query) the settings used.
 
+=back
+
 =cut
 
 sub page_layout {
@@ -1657,15 +2051,21 @@ sub page_layout {
     return $self;
 }
 
-=item $mode = $pdf->page_mode(); # Get
+=head2 page_mode
+
+    $mode = $pdf->page_mode(); # Get
+
+    $pdf = $pdf->page_mode($mode); # Set
 
-=item $pdf = $pdf->page_mode($mode); # Set
+=over
 
 Gets/sets the page mode, which describes how the PDF should be displayed when
 opened.
 
 C<$mode> is one of the following:
 
+=back
+
 =over
 
 =item none (or undef)
@@ -1695,9 +2095,13 @@ Show the attachments panel.
 
 =back
 
+=over
+
 This has been split out from C<preferences()> for compatibility with PDF::API2.
 It also can both set (assign) and get (query) the settings used.
 
+=back
+
 =cut
 
 sub page_mode {
@@ -1730,9 +2134,13 @@ sub page_mode {
     return $self;
 }
 
-=item %preferences = $pdf->viewer_preferences(); # Get
+=head2 viewer_preferences
+
+    %preferences = $pdf->viewer_preferences(); # Get
 
-=item $pdf = $pdf->viewer_preferences(%preferences); # Set
+    $pdf = $pdf->viewer_preferences(%preferences); # Set
+
+=over
 
 Gets/sets PDF viewer preferences, as described in
 L<PDF::Builder::ViewerPreferences>.
@@ -1740,6 +2148,8 @@ L<PDF::Builder::ViewerPreferences>.
 This has been split out from C<preferences()> for compatibility with PDF::API2.
 It also can both set (assign) and get (query) the settings used.
 
+=back
+
 =cut
 
 sub viewer_preferences {
@@ -1752,7 +2162,11 @@ sub viewer_preferences {
     return $prefs->set_preferences(@_);
 }
 
-=item $pdf->preferences(%opts)
+=head2 preferences
+
+    $pdf->preferences(%opts)
+
+=over
 
 Controls viewing preferences for the PDF, including the B<Page Mode>, 
 B<Page Layout>, B<Viewer>, and B<Initial Page> Options. See 
@@ -1763,6 +2177,8 @@ option groups, and L<PDF::Builder::Docs/Page Fit Options> for page positioning.
 B<Note:> the various preferences have been split out into their own methods.
 It is preferred that you use these specific methods.
 
+=back
+
 =cut
 
 sub preferences {
@@ -1950,15 +2366,15 @@ sub proc_pages {
     return @pages;
 }
 
-=back
-
 =head1 PAGE METHODS
 
-=over
+=head2 page
 
-=item $page = $pdf->page()
+    $page = $pdf->page()
 
-=item $page = $pdf->page($page_number)
+    $page = $pdf->page($page_number)
+
+=over
 
 Returns a I<new> page object.  By default, the page is added to the end
 of the document.  If you give an existing page number, the new page
@@ -1979,6 +2395,8 @@ B<Example:>
     # Add a new first page.  $page becomes page 2.
     $another_page = $pdf->page(1);
 
+=back
+
 =cut
 
 sub page {
@@ -2030,7 +2448,11 @@ sub page {
     return $page;
 } # end of page()
 
-=item $page = $pdf->open_page($page_number)
+=head2 open_page, openpage
+
+    $page = $pdf->open_page($page_number)
+
+=over
 
 Returns the L<PDF::Builder::Page> object of page $page_number.
 This is similar to C<< $page = $pdf->page() >>, except that C<$page> is 
@@ -2042,6 +2464,8 @@ If the requested page is out of range, the C<$page> returned will be undefined.
 
 B<Example:>
 
+=back
+
     $pdf  = PDF::Builder->open('our/99page.pdf');
     $page = $pdf->open_page(1);   # returns the first page
     $page = $pdf->open_page(99);  # returns the last page
@@ -2050,11 +2474,15 @@ B<Example:>
     $page = $pdf->open_page(0);   # returns the last page
     $page = $pdf->open_page();    # returns the last page
 
+=over
+
 B<Alternate name:> C<openpage>
 
 This is the older name; it is kept for compatibility until after June 2023
 (deprecated, as previously announced).
 
+=back
+
 =cut
 
 sub openpage { return open_page(@_); } ## no critic
@@ -2149,13 +2577,17 @@ sub open_page {
     return $page;
 } # end of open_page()
 
-=item $page = $pdf->import_page($source_pdf)
+=head2 import_page, importpage
+
+    $page = $pdf->import_page($source_pdf)
 
-=item $page = $pdf->import_page($source_pdf, $source_page_number)
+    $page = $pdf->import_page($source_pdf, $source_page_number)
 
-=item $page = $pdf->import_page($source_pdf, $source_page_number, $target_page_number)
+    $page = $pdf->import_page($source_pdf, $source_page_number, $target_page_number)
 
-=item $page = $pdf->import_page($source_pdf, $source_page_number, $target_page_object)
+    $page = $pdf->import_page($source_pdf, $source_page_number, $target_page_object)
+
+=over
 
 Imports a page from $source_pdf and adds it to the specified position
 in $pdf.
@@ -2173,6 +2605,8 @@ existing page.
 
 B<Example:>
 
+=back
+
     my $pdf = PDF::Builder->new();
     my $source = PDF::Builder->open('source.pdf');
 
@@ -2181,8 +2615,16 @@ B<Example:>
 
     $pdf->saveas('sample.pdf');
 
+=over
+
 B<Note:> You can only import a page from an existing PDF file.
 
+B<Alternate name:> importpage
+
+This name is still valid in PDF::API2, so it is included here for compatiblity.
+
+=back
+
 =cut
 
 # removed years ago, but is still in API2, so for code compatibility...
@@ -2310,7 +2752,11 @@ sub import_page {
     return $t_page;
 } # end of import_page()
 
-=item $xoform = $pdf->embed_page($source_pdf, $source_page_number)
+=head2 embed_page, importPageIntoForm
+
+    $xoform = $pdf->embed_page($source_pdf, $source_page_number)
+
+=over
 
 Returns a Form XObject created by extracting the specified page from 
 C<$source_pdf>.
@@ -2319,16 +2765,22 @@ This is useful if you want to transpose the imported page somewhat
 differently onto a page (e.g. two-up, four-up, etc.).
 
 If C<$source_page_number> is 0 or -1, it will return the last page in the
-document.
+document. The B<default> value for the C<$source_page_number> is 0 (return
+last page).
 
 B<Example:>
 
-    my $pdf = PDF::Builder->new();
-    my $source = PDF::Builder->open('source.pdf');
-    my $page = $pdf->page();
+=back
+
+    # take page 2 of source.pdf and add to empty doc sample.pdf at half size
+    # note that sample.pdf could be an existing document!
+    #
+    my $pdf = PDF::Builder->new();                      # so far, empty document
+    my $source = PDF::Builder->open('source.pdf');        # content to copy over
+    my $page = $pdf->page();                      # place to be actually updated
 
     # Import Page 2 from the source PDF
-    my $object = $pdf->embed_page($source, 2);
+    my $xo = $pdf->embed_page($source, 2);
 
     # Add it to the new PDF's first page at 1/2 scale
     my ($x, $y) = (0, 0);
@@ -2336,12 +2788,16 @@ B<Example:>
 
     $pdf->save('sample.pdf');
 
+=over
+
 B<Note:> You can only import a page from an existing PDF file.
 
 B<Alternate name:> C<importPageIntoForm>
 
 This is the older name; it is kept for compatibility.
 
+=back
+
 =cut
 
 sub importPageIntoForm { return embed_page(@_); } ## no critic
@@ -2475,7 +2931,11 @@ sub _walk_obj {
     return $target_object;
 } # end of _walk_obj()
 
-=item $count = $pdf->page_count()
+=head2 page_count, pages
+
+    $count = $pdf->page_count()
+
+=over
 
 Returns the number of pages in the document.
 
@@ -2483,6 +2943,8 @@ B<Alternate name:> C<pages>
 
 This is the old name; it is kept for compatibility.
 
+=back
+
 =cut
 
 sub pages { return page_count(@_); } ## no critic
@@ -2492,16 +2954,49 @@ sub page_count {
     return scalar @{$self->{'pagestack'}};
 }
 
-=item $pdf->page_labels($page_number, $opts)
+=head2 page_labels, pageLabel
 
-Sets page label numbering format, for the Reader's page-selection slider thumb 
-(I<not> the outline/bookmarks). At this time, there is no method to 
+    $pdf->page_labels($page_number, %opts)
+
+=over
+
+Sets page label numbering format, for the PDF Reader's page-selection slider 
+thumb (I<not> the outline/bookmarks). At this time, there is no method to 
 automatically synchronize a page's label with the outline/bookmarks, or to 
 somewhere on the printed page.
+Depending on the PDF Reader you are using, this formatted page label I<may> 
+show up in the reader control area as the current page number.
+
+B<CAUTIONS:> 
+
+=back
+
+=over
+
+=item 1.
+
+The given page index started at 0 for the old method (C<pageLabel()>),
+which is the internal PDF array index, while for the new method 
+(C<page_labels()>) it starts with 1, the visible page number! Don't get
+confused.
+
+=item 2.
 
-Note that many PDF Readers ignore these settings, and (at most) simply give
-you the physical page number 1, 2, 3,... instead of the page label specified 
-here.
+Options for the old method (C<pageLabel>) were a hashref, while for the
+new method (C<page_labels>) it is a hash. This permits pageLabel() to accept
+I<multiple> page number schemes in one call, rather than one per call as per
+page_labels().
+
+=item 3.
+
+Many PDF readers do not support page labels; they simply (at most)
+label the sliding thumb with the physical page number. Adobe Acrobat Reader 
+(free version) appears to have a bug in some versions, where if the only
+page label is 'decimal' (the default), it labels the thumb as though no page 
+labels were defined ("Page I<m> of I<n>"). You may be able to get around this
+problem by using an explicit B<start> option value, e.g., C<'start' =E<gt> 1>.
+
+=back
 
     # Generate a 30-page PDF
     my $pdf = PDF::Builder->new();
@@ -2512,6 +3007,12 @@ here.
     $pdf->page_labels(6, 'style' => 'decimal');
     $pdf->page_labels(26, 'style' => 'decimal', 'prefix' => 'A-');
 
+    or...
+
+    $pdf->pageLabel(0,  { style => 'roman' },
+                    5,  { style => 'decimal' },
+                    25, { style => 'decimal', prefix => 'A-' });
+
     $pdf->save('sample.pdf');
 
 B<Supported Options:>
@@ -2551,63 +3052,101 @@ the counter).
 
 =back
 
+=over
+
+B<Dotted inserted page numbers>
+
+To easily insert a range of pages, e.g., 3 pages between existing pages 37 and 
+38, use a C<prefix> of '37.' and decimal numbering starting (C<start>) at 1 or 
+a specified point. This would produce pages 37.1, 37.2, and 37.3. To put 
+leading 0's on the numbers, if you find that you later need to insert additional
+pages between those, e.g., page 37.05 between 37 and 37.1, use a C<prefix> of 
+'37.0' and C<start> at 5. 
+
+Just remember that only the (rightmost) I<counter>, which begins at the 
+C<start> value, is incremented (and formatted) by the PDF Reader. Everything 
+else (the C<prefix>) is a constant string. At worst, you might have to define 
+a page label for each individual page.
+
 B<Example:>
 
+=back
+
     # Start with lowercase Roman Numerals at the 1st page, starting with i (1)
-    $pdf->page_labels(0, 
+    $pdf->page_labels(1, 
         'style' => 'roman',
     );
 
+    or,
+
+    $pdf->pageLabel(0, 
+	{ 'style' => 'roman' },
+    );
+
     # Switch to Arabic (decimal) at the 5th page, starting with 1
-    $pdf->page_labels(4, 
+    $pdf->page_labels(5, 
         'style' => 'decimal',
     );
 
+    or, 
+
+    $pdf->pageLabel(4, 
+	{ 'style' => 'decimal' },
+    );
+
     # invalid style at the 25th page, should just continue 
     # with decimal at the current counter
-    $pdf->page_labels(24, 
+    $pdf->page_labels(25, 
         'style' => 'raman_noodles',  # fail over to decimal
-	   # note that PDF::API2 will see the 'r' and treat it as 'roman'
-	'start' => 21,  # necessary, otherwise would restart at 1
+	   # note that older versions of PDF::API2 may see the 'r' and 
+	   #   treat it as 'roman'
+	'start' => 25,  # necessary, otherwise would restart at 1
     );
 
     # No page label at the 31st and 32nd pages. Note that this could be
     # confusing to the person viewing the PDF, but may be appropriate if
     # the page itself has no numbering.
-    $pdf->page_labels(30, 
+    $pdf->page_labels(31, 
         'style' => 'nocounter',
     );
 
     # Numbering for Appendix A at the 33rd page, A-1, A-2,...
-    $pdf->page_labels(32, 
+    $pdf->page_labels(33, 
         'start' => 1,  # unnecessary
         'prefix' => 'A-'
     );
 
     # Numbering for Appendix B at the 37th page, B-1, B-2,...
-    $pdf->page_labels( 36, 
+    $pdf->page_labels(37, 
         'prefix' => 'B-'
     );
 
     # Numbering for the Index at the 41st page, Index I, Index II,...
-    $pdf->page_labels(40, 
+    $pdf->page_labels(41, 
         'style' => 'Roman',
         'start' => 1,  # unnecessary
         'prefix' => 'Index '  # note trailing space
     );
 
     # Unnumbered 'Index' at the 45th page, Index, Index,...
-    $pdf->page_labels(40, 
+    $pdf->page_labels(45, 
         'style' => 'nocounter',
         'prefix' => 'Index '
     );
 
+=over
+
 B<Alternate name:> C<pageLabel>
 
 This old method name is retained for compatibility with old user code.
 Note that with C<pageLabel>, you need to make the "options" list an anonymous
 hash by placing B<{ }> around the entire list, even if it has only one item
-in it.
+in it. Also remember that the page number (index) for C<pageLabel> starts at 0
+(same as the PDF page index), rather than 1 (as in C<page_labels>).
+Finally, pageLabel() still permits you to define multiple page numbering schemes
+in one call.
+
+=back
 
 =cut
 
@@ -2615,7 +3154,16 @@ in it.
 # old pageLabel(). rather than an opts hashref, it is a hash.
 sub page_labels { 
     my ($self, $page_number, %opts) = @_;
-    return pageLabel($self, $page_number, \%opts);
+    if ($page_number <= 0) {
+	carp "page_labels() start at 1, not 0. page changed to 1.";
+	$page_number = 1;
+    }
+    # check if opts is a hash?
+    if (ref(%opts) ne '') {
+	carp "page_labels() options must be a hash. Ignored.";
+	%opts = ();
+    }
+    return pageLabel($self, $page_number-1, \%opts);
 }
 
 # actually, the old code
@@ -2628,7 +3176,16 @@ sub pageLabel {
     my $nums = $self->{'catalog'}->{'PageLabels'}->{'Nums'};
     while (scalar @_) { # should we have only one trip through here?
         my $index = shift();
+        if ($index < 0) {
+	    carp "page labels start at 0. page changed to 0.";
+	    $index = 0;
+        }
         my $opts = shift();
+        # check if opts is a hashref?
+        if (ref($opts) ne 'HASH') {
+	    carp "pageLabels() options must be a hash ref. Ignored.";
+	    $opts = {};
+        }
         # copy dashed options to preferred undashed option names
         if (defined $opts->{'-style'} && !defined $opts->{'style'}) { $opts->{'style'} = delete($opts->{'-style'}); }
         if (defined $opts->{'-prefix'} && !defined $opts->{'prefix'}) { $opts->{'prefix'} = delete($opts->{'-prefix'}); }
@@ -2643,7 +3200,8 @@ sub pageLabel {
                 $d->{'S'} = PDFName($opts->{'style'} eq 'Roman' ? 'R' :
                                     $opts->{'style'} eq 'roman' ? 'r' :
                                     $opts->{'style'} eq 'Alpha' ? 'A' :
-                                    $opts->{'style'} eq 'alpha' ? 'a' : 'D');
+                                    $opts->{'style'} eq 'alpha' ? 'a' :
+                                    $opts->{'style'} eq 'decimal' ? 'D' : 'D');
 	    } else {
 		# for nocounter (no styled counter), do not create /S entry
 	    }
@@ -2669,7 +3227,11 @@ sub pageLabel {
 
 # set global User Unit scale factor (default 1.0)
 
-=item $pdf->userunit($value)
+=head2 userunit
+
+    $pdf->userunit($value)
+
+=over
 
 Sets the global UserUnit, defining the scale factor to multiply any size or
 coordinate by. For example, C<userunit(72)> results in a User Unit of 72 points,
@@ -2677,6 +3239,8 @@ or 1 inch.
 
 See L<PDF::Builder::Docs/User Units> for more information.
 
+=back
+
 =cut
 
 sub userunit {
@@ -2766,15 +3330,19 @@ sub _get_bbox {
 
 } # end of _get_bbox()
 
-=item $pdf->mediabox($name)
+=head2 mediabox
+
+    $pdf->mediabox($name)
 
-=item $pdf->mediabox($name, 'orient' => 'orientation')
+    $pdf->mediabox($name, 'orient' => 'orientation')
 
-=item $pdf->mediabox($w,$h)
+    $pdf->mediabox($w,$h)
 
-=item $pdf->mediabox($llx,$lly, $urx,$ury)
+    $pdf->mediabox($llx,$lly, $urx,$ury)
 
-=item ($llx,$lly, $urx,$ury) = $pdf->mediabox()
+    ($llx,$lly, $urx,$ury) = $pdf->mediabox()
+
+=over
 
 Sets (or gets) the global MediaBox, defining the width and height (or by 
 corner coordinates, or by standard name) of the output page itself, such as 
@@ -2783,6 +3351,8 @@ the physical paper size.
 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 {
@@ -2795,15 +3365,19 @@ sub mediabox {
     return $self->_get_bbox('MediaBox');
 }
 
-=item $pdf->cropbox($name)
+=head2 cropbox
+
+    $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 (or gets) the global CropBox. This will define the media size to which 
 the output will later be clipped. 
@@ -2811,6 +3385,8 @@ the output will later be clipped.
 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 {
@@ -2823,15 +3399,19 @@ sub cropbox {
     return $self->_get_bbox('CropBox');
 }
 
-=item $pdf->bleedbox($name)
+=head2 bleedbox
+
+    $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 (or gets) the global BleedBox. This is typically used for hard copy 
 printing where you want ink to go to the edge of the cut paper.
@@ -2839,6 +3419,8 @@ printing where you want ink to go to the edge of the cut paper.
 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 {
@@ -2851,15 +3433,19 @@ sub bleedbox {
     return $self->_get_bbox('BleedBox');
 }
 
-=item $pdf->trimbox($name)
+=head2 trimbox
+
+    $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 (or gets) the global TrimBox. This is supposed to be the actual 
 dimensions of the finished page (after trimming of the paper). 
@@ -2867,6 +3453,8 @@ dimensions of the finished page (after trimming of the paper).
 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 {
@@ -2879,22 +3467,30 @@ sub trimbox {
     return $self->_get_bbox('TrimBox');
 }
 
-=item $pdf->artbox($name)
+=head2 artbox
+
+    $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 (or gets) the global ArtBox. This is supposed to define "the extent of 
-the page's I<meaningful> content". 
+the page's I<meaningful> content". What is considered "meaningful" is up to 
+the author of the page, but would usually exclude "decorative" graphics and
+such; and possibly titles, headers, footers, and page numbers.
 
 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 {
@@ -2907,13 +3503,24 @@ sub artbox {
     return $self->_get_bbox('ArtBox');
 }
 
-=back
-
 =head1 FONT METHODS
 
-=over
+=head2 Embedding of Fonts
+
+B<CAUTION:> Some font routines (currently only C<ttfont()>) automatically embed
+font definitions for the purpose of improving portability of PDF files. Note 
+that font copyright and licensing terms vary by font provider, and some may 
+prohibit embedding of their fonts, either entirely, or allowing only the subset 
+of glyphs actually used in the document. You should be aware of the terms, and 
+use the C<noembed> or C<nosubset> flags as appropriate. The PDF::Builder font
+routines currently have no means to automatically detect any embedding 
+limitations for a given font, and cannot default their behavior accordingly!
+
+=head3 corefont
 
-=item $font = $pdf->corefont($fontname, %opts)
+    $font = $pdf->corefont($fontname, %opts)
+
+=over
 
 Returns a new Adobe core font object. For details, 
 see L<PDF::Builder::Docs/Core Fonts>. Note that this is an Adobe-standard
@@ -2921,6 +3528,8 @@ corefont I<name>, and not a file name.
 
 See also L<PDF::Builder::Resource::Font::CoreFont>.
 
+=back
+
 =cut
 
 sub corefont {
@@ -2933,7 +3542,11 @@ sub corefont {
         if ($name =~ /^Times$/i) {
 	    # Accept Times as an alias for Times-Roman to follow the pattern 
 	    # set by Courier and Helvetica
-	    carp "Times is not a standard font; substituting Times-Roman";
+	    if (!$MSG_COUNT[3]) {
+		# one message (per run) reminding user
+	        carp "Times is not a standard font; substituting Times-Roman";
+	        $MSG_COUNT[3]++;
+	    }
             $name = 'Times-Roman';
         }
     }
@@ -2944,13 +3557,19 @@ sub corefont {
     return $obj;
 }
 
-=item $font = $pdf->psfont($ps_file, %opts)
+=head3 psfont
 
-Returns a new Adobe Type1 ("PostScript") font object.
+    $font = $pdf->psfont($ps_file, %opts)
+
+=over
+
+Returns a new Adobe Type1 ("PostScript", "T1") font object.
 For details, see L<PDF::Builder::Docs/PS Fonts>.
 
 See also L<PDF::Builder::Resource::Font::Postscript>.
 
+=back
+
 =cut
 
 sub psfont {
@@ -2974,11 +3593,17 @@ sub psfont {
     return $obj;
 }
 
-=item $font = $pdf->ttfont($ttf_file, %opts)
+=head3 ttfont
+
+    $font = $pdf->ttfont($ttf_file, %opts)
+
+=over
 
 Returns a new TrueType (or OpenType) font object.
 For details, see L<PDF::Builder::Docs/TrueType Fonts>.
 
+=back
+
 =cut
 
 sub ttfont {
@@ -3004,13 +3629,20 @@ sub ttfont {
     return $obj;
 }
 
-=item $font = $pdf->bdfont($bdf_file, @opts)
+=head3 bdfont
+
+    $font = $pdf->bdfont($bdf_file, @opts)
+
+=over
 
 Returns a new BDF (bitmapped distribution format) font object, based on the 
-specified Adobe BDF file.
+specified Adobe BDF file. These are very low resolution fonts that appear to
+have come off a dot-matrix printer.
 
 See also L<PDF::Builder::Resource::Font::BdFont>
 
+=back
+
 =cut
 
 sub bdfont {
@@ -3025,7 +3657,11 @@ sub bdfont {
     return $obj;
 }
 
-=item $font = $pdf->cjkfont($cjkname, %opts)
+=head3 cjkfont
+
+    $font = $pdf->cjkfont($cjkname, %opts)
+
+=over
 
 Returns a new CJK font object. These are TrueType-like fonts for East Asian
 languages (Chinese, Japanese, Korean).
@@ -3045,6 +3681,8 @@ base for synthetic fonts.
 
 See also L<PDF::Builder::Resource::CIDFont::CJKFont>
 
+=back
+
 =cut
 
 sub cjkfont {
@@ -3061,7 +3699,11 @@ sub cjkfont {
     return $obj;
 }
 
-=item $font = $pdf->font($name, %opts)
+=head3 font
+
+    $font = $pdf->font($name, %opts)
+
+=over
 
 A convenience function to add a font to the PDF without having to specify the
 format. Returns the font object, to be used by L<PDF::Builder::Content>.
@@ -3073,6 +3715,8 @@ There are 15 additional core fonts on a Windows system.
 Note that the exact name of a core font needs to be given.
 The file extension (if path given) determines what type of font file it is.
 
+=back
+
     my $pdf = PDF::Builder->new();
     my $font1 = $pdf->font('Helvetica-Bold');
     my $font2 = $pdf->font('/path/to/ComicSans.ttf');
@@ -3089,6 +3733,8 @@ The file extension (if path given) determines what type of font file it is.
 
     $pdf->saveas('sample.pdf');
 
+=over
+
 The path can be omitted if the font file is in the current directory or one of
 the directories returned by C<font_path>.
 
@@ -3097,6 +3743,8 @@ Distribution Format (bdf) fonts are supported.
 
 The following options (C<%opts>) are available:
 
+=back
+
 =over
 
 =item format
@@ -3184,19 +3832,29 @@ sub font {
     }
 }
 
-=item @directories = PDF::Builder->font_path()
+=head3 font_path
+
+    @directories = PDF::Builder->font_path()
+
+=over
 
 Return the list of directories that will be searched (in order) in addition to
 the current directory when you add a font to a PDF without including the full
 path to the font file.
 
+=back
+
 =cut
 
 sub font_path {
     return @font_path;
 }
 
-=item @directories = PDF::Builder::add_to_font_path('/my/fonts', '/path/to/fonts', ...)
+=head3 add_to_font_path, addFontDirs
+
+    @directories = PDF::Builder::add_to_font_path('/my/fonts', '/path/to/fonts', ...)
+
+=over
 
 Adds one or more directories to the list of paths to be searched for font files.
 
@@ -3207,6 +3865,8 @@ B<Alternate name:> C<addFontDirs>
 Prior to recent changes to PDF::API2, this method was addFontDirs(). This 
 method is still available, but may be deprecated some time in the future.
 
+=back
+
 =cut
 
 sub addFontDirs { return add_to_font_path(@_); } ## no critic
@@ -3220,7 +3880,11 @@ sub add_to_font_path {
     return @font_path;
 }
 
-=item @directories = PDF::Builder->set_font_path('/my/fonts', '/path/to/fonts');
+=head3 set_font_path
+
+    @directories = PDF::Builder->set_font_path('/my/fonts', '/path/to/fonts');
+
+=over
 
 Replace the existing font search path. This should only be necessary if you
 need to remove a directory from the path for some reason, or if you need to
@@ -3228,6 +3892,8 @@ reorder the list.
 
 Returns the font search path.
 
+=back
+
 =cut
 
 # I don't know why there are separate set and query methods, but to maintain
@@ -3258,7 +3924,11 @@ sub _findFont {
     return;
 }
 
-=item $font = $pdf->synfont($basefont, %opts)
+=head3 synfont, synthetic_font
+
+    $font = $pdf->synfont($basefont, %opts)
+
+=over
 
 Returns a new synthetic font object. These are modifications to a core (or 
 PS/T1 or TTF/OTF) font, where the font may be replaced by a Type1 or Type3 
@@ -3278,6 +3948,8 @@ There are also some minor option differences (incompatibilities)
 discussed in C<SynFont>, including the value of 'bold' between the two entry
 points.
 
+=back
+
 =cut
 
 sub synthetic_font { return synfont(@_, '-entry_point'=>'synthetic_font'); } ## no critic
@@ -3304,7 +3976,11 @@ sub synfont {
     return $obj;
 }
 
-=item $font = $pdf->unifont(@fontspecs, %opts)
+=head3 unifont
+
+    $font = $pdf->unifont(@fontspecs, %opts)
+
+=over
 
 Returns a new uni-font object, based on the specified fonts and options.
 
@@ -3314,6 +3990,8 @@ See also L<PDF::Builder::Resource::UniFont>.
 
 Valid options (C<%opts>) are:
 
+=back
+
 =over
 
 =item encode
@@ -3339,17 +4017,17 @@ sub unifont {
     return $obj;
 }
 
-=back
-
 =head2 Font Manager methods
 
 The Font Manager is automatically initialized.
 
-=over
+=head3 font_settings
 
-=item @list = $pdf->font_settings()  # Get
+    @list = $pdf->font_settings()  # Get
 
-=item $pdf->font_settings(%info)  # Set
+    $pdf->font_settings(%info)  # Set
+
+=over
 
 Change one or more default settings. 
 See L<PDF::Builder::FontManager>/font_settings for details.
@@ -3363,9 +4041,11 @@ sub font_settings {
     return $self->{' FM'}->font_settings(@_);
 }
 
-=over
+=head3 add_font_path
 
-=item $rc = $pdf->add_font_path("a directory path", %opts)
+    $rc = $pdf->add_font_path("a directory path", %opts)
+
+=over
 
 Add a search path for Font Manager font entries.
 See L<PDF::Builder::FontManager>/add_font_path for details.
@@ -3379,9 +4059,11 @@ sub add_font_path {
     return $self->{' FM'}->add_font_path(@_);
 }
 
-=over
+=head3 add_font
 
-=item $rc = $pdf->add_font(%info)
+    $rc = $pdf->add_font(%info)
+
+=over
 
 Add a font (face) definition to the Font Manager list.
 See L<PDF::Builder::FontManager>/add_font for details.
@@ -3395,11 +4077,13 @@ sub add_font {
     return $self->{' FM'}->add_font(@_);
 }
 
-=over
+=head3 get_font
+
+    @current = $pdf->get_font()  # Get
 
-=item @current = $pdf->get_font()  # Get
+    $font = $pdf->get_font(%info)  # Set
 
-=item $font = $pdf->get_font(%info)  # Set
+=over
 
 Retrieve a ready-to-use font, or find out what the current one is.
 See L<PDF::Builder::FontManager>/get_font for details.
@@ -3413,9 +4097,11 @@ sub get_font {
     return $self->{' FM'}->get_font(@_);
 }
 
-=over
+=head3 dump_font_tables
 
-=item $pdf->dump_font_tables()
+    $pdf->dump_font_tables()
+
+=over
 
 Dump all known font information to STDOUT.
 See L<PDF::Builder::FontManager>/dump_font_tables for details.
@@ -3431,14 +4117,18 @@ sub dump_font_tables {
 
 =head1 IMAGE METHODS
 
-=over
+=head2 image
 
-=item $object = $pdf->image($file, %opts);
+    $object = $pdf->image($file, %opts);
+
+=over
 
 A convenience function to attempt to determine the image type, and import a 
 file of that type and return an object that can be placed as part of a page's 
 content:
 
+=back
+
     my $pdf = PDF::Builder->new();
     my $page = $pdf->page();
 
@@ -3447,6 +4137,8 @@ content:
 
     $pdf->save('sample.pdf');
 
+=over
+
 C<$file> may be either a file name, a filehandle, or a 
 L<PDF::Builder::Resource::XObject::Image::GD> object.
 
@@ -3480,6 +4172,8 @@ B<Note:> TIFF image processing is very slow if using the pure Perl decoder.
 We highly recommend using the Graphics::TIFF library to improve performance.
 See the C<image_tiff> method for details.
 
+=back
+
 =cut
 
 sub image {
@@ -3488,7 +4182,7 @@ sub image {
     my $format = lc($opts{'format'} // '');
 
     if (ref($file) eq 'GD::Image') {
-        return image_gd($file, %opts);
+        return $self->image_gd($file, %opts);
     }
     elsif (ref($file)) {
         $format ||= _detect_image_format($file);
@@ -3554,7 +4248,11 @@ sub _detect_image_format {
     return;
 }
 
-=item $jpeg = $pdf->image_jpeg($file, %opts)
+=head2 image_jpeg
+
+    $jpeg = $pdf->image_jpeg($file, %opts)
+
+=over
 
 Imports and returns a new JPEG image object. C<$file> may be either a filename 
 or a filehandle.
@@ -3562,6 +4260,8 @@ or a filehandle.
 See L<PDF::Builder::Resource::XObject::Image::JPEG> for additional information
 and C<examples/Content.pl> for some examples of placing an image on a page.
 
+=back
+
 =cut
 
 sub image_jpeg {
@@ -3575,7 +4275,11 @@ sub image_jpeg {
     return $obj;
 }
 
-=item $tiff = $pdf->image_tiff($file, %opts)
+=head2 image_tiff
+
+    $tiff = $pdf->image_tiff($file, %opts)
+
+=over
 
 Imports and returns a new TIFF image object. C<$file> may be either a filename 
 or a filehandle.
@@ -3590,6 +4294,8 @@ There is an optional TIFF library (TIFF_GT) described, that gives more
 capability than the default one. However, note that C<$file> can only be
 a filename when using this library.
 
+=back
+
 =cut
 
 sub image_tiff {
@@ -3635,12 +4341,18 @@ sub image_tiff {
     return $obj;
 }
 
-=item $rc = $pdf->LA_GT()
+=head3 LA_GT
+
+    $rc = $pdf->LA_GT()
+
+=over
 
 Returns 1 if the library name (package) Graphics::TIFF is installed, and 
 0 otherwise. For this optional library, this call can be used to know if it 
 is safe to use certain functions. For example:
 
+=back
+
     if ($pdf->LA_GT() {
         # is installed and usable
     } else {
@@ -3668,7 +4380,11 @@ sub LA_GT {
     return $rc;
 }
 
-=item $pnm = $pdf->image_pnm($file, %opts)
+=head2 image_pnm
+
+    $pnm = $pdf->image_pnm($file, %opts)
+
+=over
 
 Imports and returns a new PNM image object. C<$file> may be either a filename 
 or a filehandle.
@@ -3677,6 +4393,8 @@ See L<PDF::Builder::Resource::XObject::Image::PNM> for additional information
 and C<examples/Content.pl> for some examples of placing an image on a page
 (JPEG, but the principle is the same).
 
+=back
+
 =cut
 
 sub image_pnm {
@@ -3692,7 +4410,11 @@ sub image_pnm {
     return $obj;
 }
 
-=item $png = $pdf->image_png($file, %opts) 
+=head2 image_png
+
+    $png = $pdf->image_png($file, %opts) 
+
+=over
 
 Imports and returns a new PNG image object. C<$file> may be either 
 a filename or a filehandle.
@@ -3708,6 +4430,8 @@ There is an optional PNG library (PNG_IPL) described, that gives more
 capability than the default one. However, note that C<$file> can only be
 a filename when using this library.
 
+=back
+
 =cut
 
 sub image_png {
@@ -3752,12 +4476,18 @@ sub image_png {
     return $obj;
 }
 
-=item $rc = $pdf->LA_IPL()
+=head3 LA_IPL
+
+    $rc = $pdf->LA_IPL()
+
+=over
 
 Returns 1 if the library name (package) Image::PNG::Libpng is installed, and 
 0 otherwise. For this optional library, this call can be used to know if it 
 is safe to use certain functions. For example:
 
+=back
+
     if ($pdf->LA_IPL() {
         # is installed and usable
     } else {
@@ -3785,7 +4515,11 @@ sub LA_IPL {
     return $rc;
 }
 
-=item $gif = $pdf->image_gif($file, %opts)
+=head2 image_gif
+
+    $gif = $pdf->image_gif($file, %opts)
+
+=over
 
 Imports and returns a new GIF image object. C<$file> may be either a filename 
 or a filehandle.
@@ -3794,6 +4528,8 @@ See L<PDF::Builder::Resource::XObject::Image::GIF> for additional information
 and C<examples/Content.pl> for some examples of placing an image on a page 
 (JPEG, but the principle is the same).
 
+=back
+
 =cut
 
 sub image_gif {
@@ -3806,7 +4542,11 @@ sub image_gif {
     return $obj;
 }
 
-=item $gdf = $pdf->image_gd($gd_object, %opts)
+=head2 image_gd
+
+    $gdf = $pdf->image_gd($gd_object, %opts)
+
+=over
 
 Imports and returns a new image object from Image::GD.
 
@@ -3814,6 +4554,8 @@ See L<PDF::Builder::Resource::XObject::Image::GD> for additional information
 and C<examples/Content.pl> for some examples of placing an image on a page 
 (JPEG, but the principle is the same).
 
+=back
+
 =cut
 
 sub image_gd {
@@ -3826,13 +4568,13 @@ sub image_gd {
     return $obj;
 }
 
-=back
-
 =head1 COLORSPACE METHODS
 
-=over
+=head2 colorspace
 
-=item $colorspace = $pdf->colorspace($type, @arguments)
+    $colorspace = $pdf->colorspace($type, @arguments)
+
+=over
 
 Colorspaces can be added to a PDF to either specifically control the output
 color on a particular device (spot colors, device colors) or to save space by
@@ -3842,6 +4584,8 @@ file).
 Once added to the PDF, they can be used in place of regular hex codes or named
 colors:
 
+=back
+
     my $pdf = PDF::Builder->new();
     my $page = $pdf->page();
     my $content = $page->graphics();
@@ -3862,14 +4606,16 @@ colors:
 
     $pdf->save('sample.pdf');
 
+=over
+
 The following types of colorspaces are supported
 
+=back
+
 =over
 
 =item spot
 
-    my $spot = $pdf->colorspace('spot', $tint, $alt_color);
-
 Spot colors are used to instruct a device (usually a printer) to use or emulate
 a particular ink color (C<$tint>) for parts of the document. An C<$alt_color>
 is provided for devices (e.g. PDF viewers) that don't know how to produce the
@@ -3877,30 +4623,50 @@ named color. It can either be an approximation of the color in RGB, CMYK, or
 HSV formats, or a wildly different color (e.g. 100% magenta, C<%0F00>) to make
 it clear if the spot color isn't being used as expected.
 
-=item web
+=back
 
-    my $web = $pdf->colorspace('web');
+    my $spot = $pdf->colorspace('spot', $tint, $alt_color);
+
+=over
+
+=item web
 
 The web-safe color palette is a historical collection of colors that was used
 when many display devices only supported 256 colors.
 
-=item act
+=back
 
-    my $act = $pdf->colorspace('act', $filename);
+    my $web = $pdf->colorspace('web');
+
+=over
+
+=item act
 
 An Adobe Color Table (ACT) file provides a custom palette of colors that can be
 referenced by PDF graphics and text drawing commands.
 
-=item device
+=back
 
-    my $devicen = $pdf->colorspace('device', @colorspaces);
+    my $act = $pdf->colorspace('act', $filename);
+
+=over
+
+=item device
 
 A device-specific colorspace allows for precise color output on a given device
 (typically a printing press), bypassing the normal color interpretation
 performed by raster image processors (RIPs).
 
+=back
+
+    my $devicen = $pdf->colorspace('device', @colorspaces);
+
+=over
+
 Device colorspaces are also needed if you want to blend spot colors:
 
+=back
+
     my $pdf = PDF::Builder->new();
     my $page = $pdf->page();
     my $content = $page->graphics();
@@ -3922,8 +4688,6 @@ Device colorspaces are also needed if you want to blend spot colors:
 
     $pdf->save('sample.pdf');
 
-=back
-
 =cut
 
 sub colorspace {
@@ -3952,13 +4716,19 @@ sub colorspace {
     }
 }
 
-=item $cs = $pdf->colorspace_act($file)
+=head2 colorspace_act
+
+    $cs = $pdf->colorspace_act($file)
+
+=over
 
 Returns a new colorspace object based on an Adobe Color Table file.
 
 See L<PDF::Builder::Resource::ColorSpace::Indexed::ACTFile> for a
 reference to the file format's specification.
 
+=back
+
 =cut
 
 sub colorspace_act {
@@ -3968,10 +4738,16 @@ sub colorspace_act {
     return PDF::Builder::Resource::ColorSpace::Indexed::ACTFile->new($self->{'pdf'}, $file);
 }
 
-=item $cs = $pdf->colorspace_web()
+=head2 colorspace_web
+
+    $cs = $pdf->colorspace_web()
+
+=over
 
 Returns a new colorspace-object based on the "web-safe" color palette.
 
+=back
+
 =cut
 
 sub colorspace_web {
@@ -3981,12 +4757,18 @@ sub colorspace_web {
     return PDF::Builder::Resource::ColorSpace::Indexed::WebColor->new($self->{'pdf'});
 }
 
-=item $cs = $pdf->colorspace_hue()
+=head2 colorspace_hue
+
+    $cs = $pdf->colorspace_hue()
+
+=over
 
 Returns a new colorspace-object based on the hue color palette.
 
 See L<PDF::Builder::Resource::ColorSpace::Indexed::Hue> for an explanation.
 
+=back
+
 =cut
 
 sub colorspace_hue {
@@ -3996,7 +4778,11 @@ sub colorspace_hue {
     return PDF::Builder::Resource::ColorSpace::Indexed::Hue->new($self->{'pdf'});
 }
 
-=item $cs = $pdf->colorspace_separation($tint, $color)
+=head2 colorspace_separation
+
+    $cs = $pdf->colorspace_separation($tint, $color)
+
+=over
 
 Returns a new separation colorspace object based on the parameters.
 
@@ -4010,6 +4796,8 @@ I<$color> must be a valid color specification limited to: '#rrggbb',
 The colorspace model will automatically be chosen based on the
 specified color.
 
+=back
+
 =cut
 
 sub colorspace_separation {
@@ -4022,14 +4810,20 @@ sub colorspace_separation {
 							       @clr);
 }
 
-=item $cs = $pdf->colorspace_devicen(\@tintCSx, $samples)
+=head2 colorspace_devicen
+
+    $cs = $pdf->colorspace_devicen(\@tintCSx, $samples)
 
-=item $cs = $pdf->colorspace_devicen(\@tintCSx)
+    $cs = $pdf->colorspace_devicen(\@tintCSx)
+
+=over
 
 Returns a new DeviceN colorspace object based on the parameters.
 
 B<Example:>
 
+=back
+
     $cy = $pdf->colorspace_separation('Cyan',    '%f000');
     $ma = $pdf->colorspace_separation('Magenta', '%0f00');
     $ye = $pdf->colorspace_separation('Yellow',  '%00f0');
@@ -4039,9 +4833,13 @@ B<Example:>
 
     $dncs = $pdf->colorspace_devicen( [ $cy,$ma,$ye,$bk, $pms023 ] );
 
+=over
+
 The colorspace model will automatically be chosen based on the first
 colorspace specified.
 
+=back
+
 =cut
 
 sub colorspace_devicen {
@@ -4055,29 +4853,29 @@ sub colorspace_devicen {
 							    $samples);
 }
 
-=back
-
 =head1 BARCODE METHODS
 
-=over
-
 These are glue routines to the actual barcode rendering routines found
 elsewhere.
 
-=over
+=head2 xo_* Bar Code routines
 
-=item $bc = $pdf->xo_codabar(%opts)
+    $bc = $pdf->xo_codabar(%opts)
 
-=item $bc = $pdf->xo_code128(%opts)
+    $bc = $pdf->xo_code128(%opts)
 
-=item $bc = $pdf->xo_2of5int(%opts)
+    $bc = $pdf->xo_2of5int(%opts)
 
-=item $bc = $pdf->xo_3of9(%opts)
+    $bc = $pdf->xo_3of9(%opts)
 
-=item $bc = $pdf->xo_ean13(%opts)
+    $bc = $pdf->xo_ean13(%opts)
+
+=over
 
 Creates the specified barcode object as a form XObject.
 
+=back
+
 =cut
 
 # TBD PDF::API2 now has a convenience function to handle all the barcodes,
@@ -4136,18 +4934,18 @@ sub xo_ean13 {
     return $obj;
 }
 
-=back
+=head1 OTHER METHODS
 
-=back
+=head2 xo_form
 
-=head1 OTHER METHODS
+    $xo = $pdf->xo_form()
 
 =over
 
-=item $xo = $pdf->xo_form()
-
 Returns a new form XObject.
 
+=back
+
 =cut
 
 sub xo_form {
@@ -4159,11 +4957,17 @@ sub xo_form {
     return $obj;
 }
 
-=item $egs = $pdf->egstate()
+=head2 egstate
+
+    $egs = $pdf->egstate()
+
+=over
 
 Returns a new extended graphics state object, as described
 in L<PDF::Builder::Resource::ExtGState>.
 
+=back
+
 =cut
 
 sub egstate {
@@ -4175,10 +4979,16 @@ sub egstate {
     return $obj;
 }
 
-=item $obj = $pdf->pattern(%opts)
+=head2 pattern
+
+    $obj = $pdf->pattern(%opts)
+
+=over
 
 Returns a new pattern object.
 
+=back
+
 =cut
 
 sub pattern {
@@ -4190,10 +5000,16 @@ sub pattern {
     return $obj;
 }
 
-=item $obj = $pdf->shading(%opts)
+=head2 shading
+
+    $obj = $pdf->shading(%opts)
+
+=over
 
 Returns a new shading object.
 
+=back
+
 =cut
 
 sub shading {
@@ -4205,10 +5021,16 @@ sub shading {
     return $obj;
 }
 
-=item $ndest = $pdf->named_destination()
+=head2 named_destination
+
+    $ndest = $pdf->named_destination()
+
+=over
 
 Returns a new or existing named destination object.
 
+=back
+
 =cut
 
 sub named_destination {
@@ -4243,10 +5065,6 @@ sub named_destination {
     return $obj;
 } # end of named_destination()
 
-=back
-
-=cut
-
 # ==================================================
 # input: level of checking, PDF as a string
 #   level: 0 just return with any version override
@@ -4283,6 +5101,10 @@ sub IntegrityCheck {
     # intialize each element to [ 0 0 -1 -1 -1 [] ]
 
     return $Version if !length($string);  # nothing to examine?
+    # basic PDF version on line 1
+    if ($string =~ m/^%PDF-([\d.]+)/) {
+        $Version = $1;
+    }
     # even if $level 0, still want to get any higher /Version
     # build analysis data and issue errors/warnings at appropriate $level
     my @major = split /%%EOF/, $string; # typically [0] entire PDF [1] empty
@@ -4462,9 +5284,17 @@ sub IntegrityCheck {
     if (!defined $Root) {
 	print STDERR "$IC No Root object defined!\n" if $level >= $level_error;
     } else {
+	# Look for expected Root object
         if (!defined $objList{$Root}) {
+	    if ($Version > 1.4) {
+		# PDF 1.5 and up, Root could be hiding in an Object Stream
+		# TBD: disassemble object stream(s) to expose all objects
+	        print STDERR "$IC Root object $Root not found, but this may be\n  the result of putting it in an Object Stream.\n" if $level >= $level_warning;
+	    } else {
+		# PDF 1.4 or below, definitely an error if no Root found
+	        print STDERR "$IC Root object $Root not found!\n" if $level >= $level_error;
+	    }
 	    $objList{$Root} = [1, 0, -1, -1, -1, []];
-	    print STDERR "$IC Root object $Root not found!\n" if $level >= $level_error;
         }
         $objList{$Root}->[$idx_refcount]++;
     }
@@ -4475,7 +5305,15 @@ sub IntegrityCheck {
     } else {
         if (!defined $objList{$Info}) {
 	    $objList{$Info} = [1, 0, -1, -1, -1, []];
-	    print STDERR "$IC Info object $Info not found!\n" if $level >= $level_note;
+	    if ($Version > 1.4) {
+		# PDF 1.5 and up, Info could be hiding in an Object Stream
+		# TBD: disassemble object stream(s) to expose all objects
+	        print STDERR "$IC Info object $Root not found, but this may be\n  the result of putting it in an Object Stream, or it may have been deleted.\n" if $level >= $level_warning;
+	    } else {
+		# PDF 1.4 or below, definitely a warning if no Info found
+	        print STDERR "$IC Root object $Root not found!\n" if $level >= $level_warning;
+	    }
+	    print STDERR "$IC Info object $Info not found!\n" if $level >= $level_warning;
 	    # possibly in a deleted object (on free list)
         }
         $objList{$Info}->[$idx_refcount]++;
@@ -4493,7 +5331,11 @@ sub IntegrityCheck {
 	# was an object actually defined for this entry?
 	# missing Info and Root messages already given, so flag is 1 ("defined")
 	if ($objList{$thisObj}->[$idx_defined] == 0) {
-	    print STDERR "$IC object $thisObj referenced, but no entry found.\n" if $level >= $level_note;
+	    if ($Version > 1.4) {
+	        print STDERR "$IC object $thisObj referenced, but no entry found\n  (might be on the free list, or defined in an object stream).\n" if $level >= $level_note;
+	    } else {
+	        print STDERR "$IC object $thisObj referenced, but no entry found (might be on the free list).\n" if $level >= $level_warning;
+	    }
 	    # it's apparently OK if the missing object is on the free list --
 	    # it will just be ignored
 	}
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
diff --git a/t/00-all-usable.t b/t/00-all-usable.t
index 4f16486..4d7db86 100644
--- a/t/00-all-usable.t
+++ b/t/00-all-usable.t
@@ -11,6 +11,7 @@ my $HBShaperVer  = 0.024;    # minimum version of HarfBuzz::Shaper
 my $LpngVersion  = 0.57;     # minimum version of Image::PNG::Libpng
 my $TextMarkdown = 1.000031; # minimum version of Text::Markdown
 my $HTMLTreeBldr = 5.07;     # minimum version of HTML::TreeBuilder
+my $PodSimpleXHTML = 3.45;   # minimum version of Pod::Simple::XHTML
 
 # Test all of the modules to make sure that a simple "use Module"
 # won't result in a crash.
@@ -22,6 +23,11 @@ find(\&add_to_files, 'lib');
 sub add_to_files {
     return unless -f $_;
     return unless $_ =~ /\.pm$/;
+    ### 3 currently disabled
+    return if ($_ =~ m/CCITTFaxDecode\.pm$/);
+    return if ($_ =~ m/Reader\.pm$/);
+    return if ($_ =~ m/Writer\.pm$/);
+    ###
     push @files, $File::Find::name;
     return;
 }
@@ -82,6 +88,7 @@ foreach my $file (@files) {
     # HarfBuzz::Shaper is built into Content.pm, doesn't have its own module
     # Text::Markdown is built into Content/Text.pm, doesn't have its own module
     # HTML::TreeBuilder is built into Content/Text.pm, doesn't have its own module
+    # Pod::Simple::XHTML is built into buildDoc.pl, doesn't have its own module
     use_ok($file);
 }
 
diff --git a/t/03-xrefstm-index.t b/t/03-xrefstm-index.t
index 939d42a..f675ced 100644
--- a/t/03-xrefstm-index.t
+++ b/t/03-xrefstm-index.t
@@ -6,8 +6,7 @@ use Test::More tests => 3;
 
 use PDF::Builder;
 
-my $pdf = PDF::Builder->new(-outver => 1.5);
-$pdf = PDF::Builder->open('t/resources/sample-xrefstm-index.pdf');
+my $pdf = PDF::Builder->open('t/resources/sample-xrefstm-index.pdf', 'outver'=>1.5);
 
 isa_ok($pdf,
        'PDF::Builder',
diff --git a/t/content-deprecated.t b/t/content-deprecated.t
index ea91d2f..e84f155 100644
--- a/t/content-deprecated.t
+++ b/t/content-deprecated.t
@@ -277,13 +277,13 @@ $gfx = $pdf->page->gfx();
 $gfx->wordspace(2);
 like($pdf->to_string, qr/2 Tw/, q{wordspace(2)});
 
-# Text Leading
-
-$pdf = PDF::Builder->new('compress' => 0);
-$gfx = $pdf->page->gfx();
-
-$gfx->lead(14);
-like($pdf->to_string, qr/14 TL/, q{lead(14) (deprecated)});
+## Text Leading
+#
+#$pdf = PDF::Builder->new('compress' => 0);
+#$gfx = $pdf->page->gfx();
+#
+#$gfx->lead(14);
+#like($pdf->to_string, qr/14 TL/, q{lead(14) (deprecated)});
 
 # distance
 
diff --git a/t/deprecations.t b/t/deprecations.t
index 83f26b9..60cd3cf 100644
--- a/t/deprecations.t
+++ b/t/deprecations.t
@@ -2,7 +2,7 @@
 use strict;
 use warnings;
 
-use Test::More tests => 71;
+use Test::More tests => 49;
 
 use PDF::Builder;
 my ($pdf, $page, $pdf2, $pdf_string, $media, $sizes_PDF, $sizes_page, @box);
@@ -55,15 +55,14 @@ is(ref($page), 'PDF::Builder::Page',
 
 # PDF::Builder-specific cases to ADD tests for (deprecated but NOT yet removed):
 #
-# ===== scheduled to be REMOVED 8/2021
-#  elementsof() -> elements()
+##  elementsof() -> elements()
 $pdf2 = PDF::Builder->new();
 $page = $pdf2->page();
 # should be US letter [ 0 0 612 792 ] for default media
-$media = $page->find_prop('MediaBox');
-$media = [ map { $_->val() } $media->elementsof() ];
-ok($media->[0]==0 && $media->[1]==0 && $media->[2]==612 && $media->[3]==792,
-    q{elementsof still works});
+#$media = $page->find_prop('MediaBox');
+#$media = [ map { $_->val() } $media->elementsof() ];
+#ok($media->[0]==0 && $media->[1]==0 && $media->[2]==612 && $media->[3]==792,
+    #q{elementsof still works});
 $media = $page->find_prop('MediaBox');
 $media = [ map { $_->val() } $media->elements() ];
 ok($media->[0]==0 && $media->[1]==0 && $media->[2]==612 && $media->[3]==792,
@@ -78,9 +77,9 @@ $sizes_PDF  = [0, 0, 612, 792];
 $sizes_page = [0, 0, 612, 792];
 $pdf2 = PDF::Builder->new();
 $page = $pdf2->page();
-@box = $page->get_mediabox();
-ok(array_comp($sizes_page, @box),
-    q{get_mediabox still works for default page media size});
+#@box = $page->get_mediabox();
+#ok(array_comp($sizes_page, @box),
+#    q{get_mediabox still works for default page media size});
 @box = $pdf2->mediabox();
 ok(array_comp($sizes_PDF, @box),
     q{mediabox IS available for default PDF media size});
@@ -94,9 +93,9 @@ $sizes_page = [ 0, 0, 100, 150 ];
 $pdf2 = PDF::Builder->new();
 $pdf2->mediabox(0, 0, 100, 150);
 $page = $pdf2->page();
-@box = $page->get_mediabox();
-ok(array_comp($sizes_page, @box),
-    q{get_mediabox still works for PDF-set page media size});
+#@box = $page->get_mediabox();
+#ok(array_comp($sizes_page, @box),
+#    q{get_mediabox still works for PDF-set page media size});
 @box = $pdf2->mediabox();
 ok(array_comp($sizes_PDF, @box),
     q{mediabox IS available for PDF-set PDF media size});
@@ -110,9 +109,9 @@ $sizes_page = [ 0, 0, 100, 150 ];
 $pdf2 = PDF::Builder->new();
 $page = $pdf2->page();
 $page->mediabox(0, 0, 100, 150);
-@box = $page->get_mediabox();
-ok(array_comp($sizes_page, @box),
-    q{get_mediabox still works for page-set page media size});
+#@box = $page->get_mediabox();
+#ok(array_comp($sizes_page, @box),
+#    q{get_mediabox still works for page-set page media size});
 @box = $pdf2->mediabox();
 ok(array_comp($sizes_PDF, @box),
     q{mediabox IS available for default PDF media size});
@@ -127,9 +126,9 @@ $pdf2 = PDF::Builder->new();
 $pdf2->mediabox(0, 0, 200, 300);
 $page = $pdf2->page();
 $page->mediabox(0, 0, 100, 150);
-@box = $page->get_mediabox();
-ok(array_comp($sizes_page, @box),
-    q{get_mediabox still works for page-set page media size});
+#@box = $page->get_mediabox();
+#ok(array_comp($sizes_page, @box),
+#    q{get_mediabox still works for page-set page media size});
 @box = $pdf2->mediabox();
 ok(array_comp($sizes_PDF, @box),
     q{mediabox IS available for PDF-set PDF media size});
@@ -144,9 +143,9 @@ $sizes_PDF  = [0, 0, 612, 792];
 $sizes_page = [0, 0, 612, 792];
 $pdf2 = PDF::Builder->new();
 $page = $pdf2->page();
-@box = $page->get_cropbox();
-ok(array_comp($sizes_page, @box),
-    q{get_cropbox still works for default page cropbox size});
+#@box = $page->get_cropbox();
+#ok(array_comp($sizes_page, @box),
+#    q{get_cropbox still works for default page cropbox size});
 @box = $pdf2->cropbox();
 ok(array_comp($sizes_PDF, @box),
     q{cropbox IS available for default PDF cropbox size});
@@ -160,9 +159,9 @@ $sizes_page = [ 0, 0, 100, 150 ];
 $pdf2 = PDF::Builder->new();
 $pdf2->cropbox(0, 0, 100, 150);
 $page = $pdf2->page();
-@box = $page->get_cropbox();
-ok(array_comp($sizes_page, @box),
-    q{get_cropbox still works for PDF-set page cropbox size});
+#@box = $page->get_cropbox();
+#ok(array_comp($sizes_page, @box),
+#    q{get_cropbox still works for PDF-set page cropbox size});
 @box = $pdf2->cropbox();
 ok(array_comp($sizes_PDF, @box),
     q{cropbox IS available for PDF-set PDF cropbox size});
@@ -176,9 +175,9 @@ $sizes_page = [ 0, 0, 100, 150 ];
 $pdf2 = PDF::Builder->new();
 $page = $pdf2->page();
 $page->cropbox(0, 0, 100, 150);
-@box = $page->get_cropbox();
-ok(array_comp($sizes_page, @box),
-    q{get_cropbox still works for page-set page cropbox size});
+#@box = $page->get_cropbox();
+#ok(array_comp($sizes_page, @box),
+#    q{get_cropbox still works for page-set page cropbox size});
 @box = $pdf2->cropbox();
 ok(array_comp($sizes_PDF, @box),
     q{cropbox IS available for default PDF cropbox size});
@@ -193,9 +192,9 @@ $pdf2 = PDF::Builder->new();
 $pdf2->cropbox(0, 0, 200, 300);
 $page = $pdf2->page();
 $page->cropbox(0, 0, 100, 150);
-@box = $page->get_cropbox();
-ok(array_comp($sizes_page, @box),
-    q{get_cropbox still works for page-set page cropbox size});
+#@box = $page->get_cropbox();
+#ok(array_comp($sizes_page, @box),
+#    q{get_cropbox still works for page-set page cropbox size});
 @box = $pdf2->cropbox();
 ok(array_comp($sizes_PDF, @box),
     q{cropbox IS available for PDF-set PDF cropbox size});
@@ -210,9 +209,9 @@ $sizes_PDF  = [0, 0, 612, 792];
 $sizes_page = [0, 0, 612, 792];
 $pdf2 = PDF::Builder->new();
 $page = $pdf2->page();
-@box = $page->get_bleedbox();
-ok(array_comp($sizes_page, @box),
-    q{get_bleedbox still works for default page bleedbox size});
+#@box = $page->get_bleedbox();
+#ok(array_comp($sizes_page, @box),
+#    q{get_bleedbox still works for default page bleedbox size});
 @box = $pdf2->bleedbox();
 ok(array_comp($sizes_PDF, @box),
     q{bleedbox IS available for default PDF bleedbox size});
@@ -226,9 +225,9 @@ $sizes_page = [ 0, 0, 100, 150 ];
 $pdf2 = PDF::Builder->new();
 $pdf2->bleedbox(0, 0, 100, 150);
 $page = $pdf2->page();
-@box = $page->get_bleedbox();
-ok(array_comp($sizes_page, @box),
-    q{get_bleedbox still works for PDF-set page bleedbox size});
+#@box = $page->get_bleedbox();
+#ok(array_comp($sizes_page, @box),
+#    q{get_bleedbox still works for PDF-set page bleedbox size});
 @box = $pdf2->bleedbox();
 ok(array_comp($sizes_PDF, @box),
     q{bleedbox IS available for PDF-set PDF bleedbox size});
@@ -242,9 +241,9 @@ $sizes_page = [ 0, 0, 100, 150 ];
 $pdf2 = PDF::Builder->new();
 $page = $pdf2->page();
 $page->bleedbox(0, 0, 100, 150);
-@box = $page->get_bleedbox();
-ok(array_comp($sizes_page, @box),
-    q{get_bleedbox still works for page-set page bleedbox size});
+#@box = $page->get_bleedbox();
+#ok(array_comp($sizes_page, @box),
+#    q{get_bleedbox still works for page-set page bleedbox size});
 @box = $pdf2->bleedbox();
 ok(array_comp($sizes_PDF, @box),
     q{bleedbox IS available for default PDF bleedbox size});
@@ -259,9 +258,9 @@ $pdf2 = PDF::Builder->new();
 $pdf2->bleedbox(0, 0, 200, 300);
 $page = $pdf2->page();
 $page->bleedbox(0, 0, 100, 150);
-@box = $page->get_bleedbox();
-ok(array_comp($sizes_page, @box),
-    q{get_bleedbox still works for page-set page bleedbox size});
+#@box = $page->get_bleedbox();
+#ok(array_comp($sizes_page, @box),
+#    q{get_bleedbox still works for page-set page bleedbox size});
 @box = $pdf2->bleedbox();
 ok(array_comp($sizes_PDF, @box),
     q{bleedbox IS available for PDF-set PDF bleedbox size});
@@ -276,9 +275,9 @@ $sizes_PDF  = [0, 0, 612, 792];
 $sizes_page = [0, 0, 612, 792];
 $pdf2 = PDF::Builder->new();
 $page = $pdf2->page();
-@box = $page->get_trimbox();
-ok(array_comp($sizes_page, @box),
-    q{get_trimbox still works for default page trimbox size});
+#@box = $page->get_trimbox();
+#ok(array_comp($sizes_page, @box),
+#    q{get_trimbox still works for default page trimbox size});
 @box = $pdf2->trimbox();
 ok(array_comp($sizes_PDF, @box),
     q{trimbox IS available for default PDF trimbox size});
@@ -292,9 +291,9 @@ $sizes_page = [ 0, 0, 100, 150 ];
 $pdf2 = PDF::Builder->new();
 $pdf2->trimbox(0, 0, 100, 150);
 $page = $pdf2->page();
-@box = $page->get_trimbox();
-ok(array_comp($sizes_page, @box),
-    q{get_trimbox still works for PDF-set page trimbox size});
+#@box = $page->get_trimbox();
+#ok(array_comp($sizes_page, @box),
+#    q{get_trimbox still works for PDF-set page trimbox size});
 @box = $pdf2->trimbox();
 ok(array_comp($sizes_PDF, @box),
     q{trimbox IS available for PDF-set PDF trimbox size});
@@ -308,9 +307,9 @@ $sizes_page = [ 0, 0, 100, 150 ];
 $pdf2 = PDF::Builder->new();
 $page = $pdf2->page();
 $page->trimbox(0, 0, 100, 150);
-@box = $page->get_trimbox();
-ok(array_comp($sizes_page, @box),
-    q{get_trimbox still works for page-set page trimbox size});
+#@box = $page->get_trimbox();
+#ok(array_comp($sizes_page, @box),
+#    q{get_trimbox still works for page-set page trimbox size});
 @box = $pdf2->trimbox();
 ok(array_comp($sizes_PDF, @box),
     q{trimbox IS available for default PDF trimbox size});
@@ -325,9 +324,9 @@ $pdf2 = PDF::Builder->new();
 $pdf2->trimbox(0, 0, 200, 300);
 $page = $pdf2->page();
 $page->trimbox(0, 0, 100, 150);
-@box = $page->get_trimbox();
-ok(array_comp($sizes_page, @box),
-    q{get_trimbox still works for page-set page trimbox size});
+#@box = $page->get_trimbox();
+#ok(array_comp($sizes_page, @box),
+#    q{get_trimbox still works for page-set page trimbox size});
 @box = $pdf2->trimbox();
 ok(array_comp($sizes_PDF, @box),
     q{trimbox IS available for PDF-set PDF trimbox size});
@@ -342,9 +341,9 @@ $sizes_PDF  = [0, 0, 612, 792];
 $sizes_page = [0, 0, 612, 792];
 $pdf2 = PDF::Builder->new();
 $page = $pdf2->page();
-@box = $page->get_artbox();
-ok(array_comp($sizes_page, @box),
-    q{get_artbox still works for default page artbox size});
+#@box = $page->get_artbox();
+#ok(array_comp($sizes_page, @box),
+#    q{get_artbox still works for default page artbox size});
 @box = $pdf2->artbox();
 ok(array_comp($sizes_PDF, @box),
     q{artbox IS available for default PDF artbox size});
@@ -358,9 +357,9 @@ $sizes_page = [ 0, 0, 100, 150 ];
 $pdf2 = PDF::Builder->new();
 $pdf2->artbox(0, 0, 100, 150);
 $page = $pdf2->page();
-@box = $page->get_artbox();
-ok(array_comp($sizes_page, @box),
-    q{get_artbox still works for PDF-set page artbox size});
+#@box = $page->get_artbox();
+#ok(array_comp($sizes_page, @box),
+#    q{get_artbox still works for PDF-set page artbox size});
 @box = $pdf2->artbox();
 ok(array_comp($sizes_PDF, @box),
     q{artbox IS available for PDF-set PDF artbox size});
@@ -374,9 +373,9 @@ $sizes_page = [ 0, 0, 100, 150 ];
 $pdf2 = PDF::Builder->new();
 $page = $pdf2->page();
 $page->artbox(0, 0, 100, 150);
-@box = $page->get_artbox();
-ok(array_comp($sizes_page, @box),
-    q{get_artbox still works for page-set page artbox size});
+#@box = $page->get_artbox();
+#ok(array_comp($sizes_page, @box),
+#    q{get_artbox still works for page-set page artbox size});
 @box = $pdf2->artbox();
 ok(array_comp($sizes_PDF, @box),
     q{artbox IS available for default PDF artbox size});
@@ -391,9 +390,9 @@ $pdf2 = PDF::Builder->new();
 $pdf2->artbox(0, 0, 200, 300);
 $page = $pdf2->page();
 $page->artbox(0, 0, 100, 150);
-@box = $page->get_artbox();
-ok(array_comp($sizes_page, @box),
-    q{get_artbox still works for page-set page artbox size});
+#@box = $page->get_artbox();
+#ok(array_comp($sizes_page, @box),
+#    q{get_artbox still works for page-set page artbox size});
 @box = $pdf2->artbox();
 ok(array_comp($sizes_PDF, @box),
     q{artbox IS available for PDF-set PDF artbox size});
@@ -410,19 +409,19 @@ ok(array_comp($sizes_page, @box),
 	 q{pageLabel defaults to decimal if given invalid input});
 }
 
-# 
-# ===== scheduled to be REMOVED 3/2023
-#  lead() -> leading() 
+## 
+## ===== scheduled to be REMOVED 3/2023
+##  lead() -> leading() 
+#$pdf2 = PDF::Builder->new('compress' => 'none');
+#my $text = $pdf2->page()->text();
+#$text->lead(15);
+#like($pdf2->to_string(), qr/15 TL/, q{lead still works });
 $pdf2 = PDF::Builder->new('compress' => 'none');
 my $text = $pdf2->page()->text();
-$text->lead(15);
-like($pdf2->to_string(), qr/15 TL/, q{lead still works });
-$pdf2 = PDF::Builder->new('compress' => 'none');
-$text = $pdf2->page()->text();
 $text->leading(15);
 like($pdf2->to_string(), qr/15 TL/, q{leading replacement for lead IS available});
-#
-#  textlead() -> textleading()   Lite.pm only, no t test
+##
+##  textlead() -> textleading()   Lite.pm only, no t test
 
 # if nothing left to check...
 #is(ref($pdf), 'PDF::Builder',
diff --git a/t/font-type1.t b/t/font-type1.t
index 1163cdd..3eeddaa 100644
--- a/t/font-type1.t
+++ b/t/font-type1.t
@@ -21,6 +21,8 @@ if ($OSname eq 'MSWin32') {
     push @pfm_list, 'C:/Program Files/MikTex 2.9/fonts/type1/urw/bookman/ubkd8a.pfm';
     push @pfb_list, 'C:/Program Files (x86)/MikTex 2.9/fonts/type1/urw/bookman/ubkd8a.pfb';
     push @pfm_list, 'C:/Program Files (x86)/MikTex 2.9/fonts/type1/urw/bookman/ubkd8a.pfm';
+    push @pfb_list, 'C:/Users/Phil/fonts/T1fonts/URWGothic-Book.t1';
+    push @pfm_list, 'C:/Users/Phil/fonts/T1fonts/URWGothic-Book.afm';
 
 } else {
     # Unix/Linux systems assumed. is this a standard location everyone has?
@@ -28,6 +30,8 @@ if ($OSname eq 'MSWin32') {
     push @pfm_list, '/usr/share/fonts/type1/gsfonts/a010013l.pfm';
     push @pfb_list, '/usr/share/X11/fonts/urw-fonts/a010013l.pfb';
     push @pfm_list, '/usr/share/X11/fonts/urw-fonts/a010013l.pfm';
+    push @pfb_list, '/usr/share/fonts/urw-base35/URWGothic-Book.t1';
+    push @pfm_list, '/usr/share/fonts/urw-base35/URWGothic-Book.afm';
 }
 
 # This may or may not work on Macs ("darwin" string) and other platforms
@@ -54,8 +58,15 @@ SKIP: {
         unless (defined $pfb_file and defined $pfm_file);
 
     my $pdf = PDF::Builder->new();
-#   my $font = $pdf->font($pfb_file, 'pfmfile' => $pfm_file); # was psfont()
-    my $font = $pdf->psfont($pfb_file, 'pfmfile' => $pfm_file); # was psfont()
+    my $font;
+    # handle both afm and pfm metric files
+    if ($pfm_file =~ m/\.pfm$/i) {
+#       $font = $pdf->font($pfb_file, 'pfmfile' => $pfm_file);
+        $font = $pdf->psfont($pfb_file, 'pfmfile' => $pfm_file);
+    } else {
+#       $font = $pdf->font($pfb_file, 'afmfile' => $pfm_file);
+        $font = $pdf->psfont($pfb_file, 'afmfile' => $pfm_file);
+    }
 
     # Do something with the font to see if it appears to have opened
     # properly.
diff --git a/t/info.t b/t/info.t
index 2c1ca51..5783c79 100644
--- a/t/info.t
+++ b/t/info.t
@@ -8,23 +8,36 @@ use PDF::Builder;
 
 my $pdf = PDF::Builder->new();
 
+# 1
 like($pdf->producer(), qr/PDF::Builder/,
      q{Producer is set on PDF creation});
 
 $pdf->producer('Test');
 
+# 2
 is($pdf->producer(), 'Test',
    q{Producer can be changed});
 
+# 3
 $pdf->producer(undef);
 
 ok(!$pdf->producer(),
    q{Producer can be cleared});
 
+# 4
 $pdf->created('D:20000101000000Z');
 
 like($pdf->to_string(),
      qr{/CreationDate \(D:20000101000000Z\)},
      q{CreationDate is correctly encoded});
 
+# 5
+$pdf = PDF::Builder->new();  # not sure why have to get a fresh PDF object...
+                             # did some test upstream corrupt it?
+$pdf->modified("D:20230402144932-04'00");
+
+like($pdf->to_string(),
+     qr{/ModDate \(D:20230402144932-04'00\)},
+     q{ModDate is correctly encoded});
+
 done_testing();
diff --git a/t/page.t b/t/page.t
index 7798b4d..8a0ba98 100644
--- a/t/page.t
+++ b/t/page.t
@@ -9,38 +9,38 @@ use PDF::Builder;
 my $pdf = PDF::Builder->new();
 my $page = $pdf->page();
 
-# Global Boxes (deprecated get_* names)
+# notice that page->*box is used to GET the values just SET
 
 $pdf->mediabox(100, 200);
-my @mediabox = $page->get_mediabox();
+my @mediabox = $page->mediabox();
 is($mediabox[0], 0, 'Global Mediabox LLX');
 is($mediabox[1], 0, 'Global Mediabox LLY');
 is($mediabox[2], 100, 'Global Mediabox URX');
 is($mediabox[3], 200, 'Global Mediabox URY');
 
 $pdf->cropbox(200, 300);
-my @cropbox = $page->get_cropbox();
+my @cropbox = $page->cropbox();
 is($cropbox[0], 0, 'Global Cropbox LLX');
 is($cropbox[1], 0, 'Global Cropbox LLY');
 is($cropbox[2], 200, 'Global Cropbox URX');
 is($cropbox[3], 300, 'Global Cropbox URY');
 
 $pdf->bleedbox(200, 300);
-my @bleedbox = $page->get_bleedbox();
+my @bleedbox = $page->bleedbox();
 is($bleedbox[0], 0, 'Global Bleedbox LLX');
 is($bleedbox[1], 0, 'Global Bleedbox LLY');
 is($bleedbox[2], 200, 'Global Bleedbox URX');
 is($bleedbox[3], 300, 'Global Bleedbox URY');
 
 $pdf->trimbox(200, 300);
-my @trimbox = $page->get_trimbox();
+my @trimbox = $page->trimbox();
 is($trimbox[0], 0, 'Global Trimbox LLX');
 is($trimbox[1], 0, 'Global Trimbox LLY');
 is($trimbox[2], 200, 'Global Trimbox URX');
 is($trimbox[3], 300, 'Global Trimbox URY');
 
 $pdf->artbox(200, 300);
-my @artbox = $page->get_artbox();
+my @artbox = $page->artbox();
 is($artbox[0], 0, 'Global Artbox LLX');
 is($artbox[1], 0, 'Global Artbox LLY');
 is($artbox[2], 200, 'Global Artbox URX');
@@ -108,59 +108,57 @@ is($box[1],   36, q{Single-argument trim Y1});
 is($box[2],  828, q{Single-argument trim X2});
 is($box[3], 1260, q{Single-argument trim Y2});
 
-# Page-Specific Boxes (deprecated get_* names)
-
 $page->mediabox(720, 1440);
-@mediabox = $page->get_mediabox();
+@mediabox = $page->mediabox();
 is($mediabox[0], 0, 'Mediabox LLX');
 is($mediabox[1], 0, 'Mediabox LLY');
 is($mediabox[2], 720, 'Mediabox URX');
 is($mediabox[3], 1440, 'Mediabox URY');
 
 $page->mediabox('LEDGER');
-@mediabox = $page->get_mediabox();
+@mediabox = $page->mediabox();
 is($mediabox[0], 0, 'Mediabox LLX (ledger)');
 is($mediabox[1], 0, 'Mediabox LLY (ledger)');
 is($mediabox[2], 1224, 'Mediabox URX (ledger)');
 is($mediabox[3], 792, 'Mediabox URY (ledger)');
 
 $page->mediabox('non-existent');
-@mediabox = $page->get_mediabox();
+@mediabox = $page->mediabox();
 is($mediabox[0], 0, 'Mediabox LLX (unknown named type)');
 is($mediabox[1], 0, 'Mediabox LLY (unknown named type)');
 is($mediabox[2], 612, 'Mediabox URX (unknown named type)');
 is($mediabox[3], 792, 'Mediabox URY (unknown named type)');
 
 $page->mediabox(1, 2, 3, 4);
-@mediabox = $page->get_mediabox();
+@mediabox = $page->mediabox();
 is($mediabox[0], 1, 'Mediabox LLX (offset)');
 is($mediabox[1], 2, 'Mediabox LLY (offset)');
 is($mediabox[2], 3, 'Mediabox URX (offset)');
 is($mediabox[3], 4, 'Mediabox URY (offset)');
 
 $page->cropbox(10, 20);
-@cropbox = $page->get_cropbox();
+@cropbox = $page->cropbox();
 is($cropbox[0], 0, 'Cropbox LLX');
 is($cropbox[1], 0, 'Cropbox LLY');
 is($cropbox[2], 10, 'Cropbox URX');
 is($cropbox[3], 20, 'Cropbox URY');
 
 $page->bleedbox(30, 40);
-@bleedbox = $page->get_bleedbox();
+@bleedbox = $page->bleedbox();
 is($bleedbox[0], 0, 'Bleedbox LLX');
 is($bleedbox[1], 0, 'Bleedbox LLY');
 is($bleedbox[2], 30, 'Bleedbox URX');
 is($bleedbox[3], 40, 'Bleedbox URY');
 
 $page->trimbox(50, 60);
-@trimbox = $page->get_trimbox();
+@trimbox = $page->trimbox();
 is($trimbox[0], 0, 'Trimbox LLX');
 is($trimbox[1], 0, 'Trimbox LLY');
 is($trimbox[2], 50, 'Trimbox URX');
 is($trimbox[3], 60, 'Trimbox URY');
 
 $page->artbox(70, 80);
-@artbox = $page->get_artbox();
+@artbox = $page->artbox();
 is($artbox[0], 0, 'Artbox LLX');
 is($artbox[1], 0, 'Artbox LLY');
 is($artbox[2], 70, 'Artbox URX');
diff --git a/tools/1_pc.pl b/tools/1_pc.pl
index a99b0be..2ea4ecc 100644
--- a/tools/1_pc.pl
+++ b/tools/1_pc.pl
@@ -7,14 +7,14 @@
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.021'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 # command line:
 # -5  run perlcritic -5 .  (should be clean)
 # -5x                      exclude certain common errors (none at this time)
 # -4  run perlcritic -4 .  should get a number of common errors
-# -4x                      exclude certain common errors  DEFAULT
+# -4x                      exclude certain common errors  ** DEFAULT **
 # -3  run perlcritic -3 .  should get a number of errors
 # -3x                      exclude certain common errors
 # -2  run perlcritic -2 .  should get more errors
@@ -22,6 +22,8 @@ our $LAST_UPDATE = '3.021'; # manually update whenever code is changed
 # -1  run perlcritic -1 .  should get even more errors
 # -1x                      exclude certain common errors
 # 
+# level 5 is apparently the MOST severe set of errors (all should be fixed);
+#   level 1 the LEAST severe (and most numerous)
 # levels 1,2,3 are only for the morbidly curious! 
 #   (although some warnings look like they should be addressed)
 
@@ -60,6 +62,8 @@ my @ignore_list = (
                               # e.g., we define "open" when there is already a 
 			      # system (CORE::) open (ambiguous unless CORE:: 
 			      # added)      TBD consider removing
+     "Subroutine name is a homonym for builtin keyword", 
+                              # e.g., "sub default"
      "Symbols are exported by default", 
                               # it doesn't like something about our use of 
 			      # @EXPORT and @EXPORT_OK
diff --git a/tools/2_t-tests.pl b/tools/2_t-tests.pl
index 4203d1a..27fa827 100644
--- a/tools/2_t-tests.pl
+++ b/tools/2_t-tests.pl
@@ -7,7 +7,7 @@
 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
 
 # command line flags, mutually exclusive:
@@ -89,6 +89,10 @@ if      (scalar @ARGV == 0) {
 }
 
 foreach my $file (@test_list) {
+    if ($file eq 'tiff') {
+	print "\nNote: t/tiff.t takes quite a bit longer than the others to run. Don't Panic!";
+    }
+
     my @results = `perl t/$file.t`;
     # TBD: detect if a FAILED test, and remark at end if any failures
     print "\nt/$file.t\n";
diff --git a/tools/3_examples.pl b/tools/3_examples.pl
index 892c34e..13102ba 100644
--- a/tools/3_examples.pl
+++ b/tools/3_examples.pl
@@ -2,13 +2,14 @@
 # run examples test suite
 # roughly equivalent to examples.bat
 #   you will need to update the %args list before running
+# -s flag to run short lists for 020_corefonts, 021_synfonts, 023_cjkfonts
 # author: Phil M Perry
 
 use strict;
 use warnings;
 
-our $VERSION = '3.025'; # VERSION
-our $LAST_UPDATE = '3.018'; # manually update whenever code is changed
+our $VERSION = '3.026'; # VERSION
+our $LAST_UPDATE = '3.026'; # manually update whenever code is changed
 
 # dependent on optional packages:
 my $HS_installed = 1; # HarfBuzz::Shaper IS installed and you want to use it.
@@ -18,6 +19,7 @@ my $HS_installed = 1; # HarfBuzz::Shaper IS installed and you want to use it.
 # command line:
 #   -step  = stop after each test to let the tester look at the PDF file
 #   -cont  = (default) run continuously to the end, to not tie up tester
+#   -s     = short list for corefont, synfont, cjkfont tests
 my $pause;
 
 my (@example_list, @example_results);
@@ -89,7 +91,7 @@ my (@example_list, @example_results);
   push @example_results, "create examples/050_pagelabels.pdf, showing a number of pages, each with its\n own page label in different formats. You will see them when you drag the\n vertical scroll thumb and you see a thumbnail of each page,\n each with its own label.\n";
 
   push @example_list, "055_outlines";
-  push @example_results, "create examples/055_outlines.sample_55.pdf, showing a 12 page document.\n Click on the \"bookmark\" icon to see three pages in the outline, where you\n can click to jump to any of them.\n";
+  push @example_results, "create examples/055_outlines.sample_55.pdf, showing a 12 page document.\n Click on the \"bookmark\" or \"outline\" icon to see three pages in the\n outline, where you\n can click to jump to any of them.\n";
 
   push @example_list, "060_transparency";
   push @example_results, "create examples/060_transparency.pdf, showing 2 pages with red opaque text\n partly covered by 40% transparent black text.\n";
@@ -155,6 +157,7 @@ my %args;
   $args{'ShowFont.pl'} = "Helvetica";
 
 my $type;
+my $short_list = 0;  # no -s flag seen
 # one command line arg allowed (-cont is default)
 if      (scalar @ARGV == 0) {
     $type = '-cont';
@@ -164,6 +167,9 @@ if      (scalar @ARGV == 0) {
     } elsif ($ARGV[0] eq '-cont') {
 	# default
         $type = '-cont';
+    } elsif ($ARGV[0] eq '-s') {
+	$type = '-cont';
+	$short_list = 1;
     } else {
 	die "Unknown command line argument '$ARGV[0]'\n";
     }
@@ -205,7 +211,13 @@ for ($i=0; $i<scalar(@example_list); $i++) {
     print "\n=== Running test examples/$file $arg\n";
     print $desc;
 
-    system("perl examples/$file $arg");
+    if ($short_list && ($file eq '020_corefonts' ||
+		        $file eq '021_synfonts' ||
+			$file eq '023_cjkfonts')) {
+	system("perl examples/$file -s");
+    } else {
+        system("perl examples/$file $arg");
+    }
 
     if ($type eq '-cont') { next; }
     print "Press Enter to continue: ";
diff --git a/tools/4_contrib.pl b/tools/4_contrib.pl
index 341330d..812446e 100644
--- a/tools/4_contrib.pl
+++ b/tools/4_contrib.pl
@@ -7,7 +7,7 @@
 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
 
 # command line:
@@ -96,6 +96,7 @@ system("contrib".$dirSep."text2pdf.pl contrib/text2pdf.pl");
 print "Press Enter to continue\n";
 $pause = <>;
 
+print "I will NOT erase the input files from examples/ -- you have to do that\n";
 print "\nIf you are done with the output files, should I erase them now?[n]\n";
 $pause = <>;
 if ($pause =~ m/^y/i) {
author	gregor herrmann <gregoa@debian.org>	2023-12-15 21:25:55 +0100
committer	gregor herrmann <gregoa@debian.org>	2023-12-15 21:25:55 +0100
commit	900134cb227e50fe9047d0f48707ec7899c8c1f0 (patch)
tree	fe5bc6f0e7e00ccf9ad39ee858720d842bb82a1f
parent	00c23136faf4a0a7015ba5f8daecb98fb33ba6cc (diff)
parent	e2f017af7599617065e54b1ad68a0ccc6afaf980 (diff)