.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "PDF::Builder 3pm"
.TH PDF::Builder 3pm "2023-12-15" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
PDF::Builder \- Facilitates the creation and modification of PDF files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use PDF::Builder;
\&
\&    # Create a blank PDF file
\&    $pdf = PDF::Builder\->new();
\&
\&    # Open an existing PDF file
\&    $pdf = PDF::Builder\->open(\*(Aqsome.pdf\*(Aq);
\&
\&    # Add a blank page
\&    $page = $pdf\->page();
\&
\&    # Retrieve an existing page
\&    $page = $pdf\->open_page($page_number);
\&
\&    # Set the page size
\&    $page\->size(\*(AqLetter\*(Aq);  # or mediabox(\*(AqLetter\*(Aq)
\&
\&    # Add a built\-in font to the PDF
\&    $font = $pdf\->font(\*(AqHelvetica\-Bold\*(Aq); # or corefont(\*(AqHelvetica\-Bold\*(Aq)
\&
\&    # Add an external TrueType (TTF) font to the PDF
\&    $font = $pdf\->font(\*(Aq/path/to/font.ttf\*(Aq);  # or ttfont() in this case
\&
\&    # Add some text to the page
\&    $text = $page\->text();
\&    $text\->font($font, 20);
\&    $text\->position(200, 700);  # or translate()
\&    $text\->text(\*(AqHello World!\*(Aq);
\&
\&    # Save the PDF
\&    $pdf\->saveas(\*(Aq/path/to/new.pdf\*(Aq);
.Ve
.SH "SOME SPECIAL NOTES"
.IX Header "SOME SPECIAL NOTES"
See the file \s-1README\s0.md (in downloadable package and on \s-1CPAN\s0) for a summary of 
prerequisites and tools needed to install PDF::Builder, both mandatory and 
optional.
.SS "\s-1SOFTWARE DEVELOPMENT KIT\s0"
.IX Subsection "SOFTWARE DEVELOPMENT KIT"
There are four levels of involvement with PDF::Builder. Depending on what you
want to do, different kinds of installs are recommended.
See \*(L"Software Development Kit\*(R" in PDF::Builder::Docs for suggestions.
.SS "\s-1OPTIONAL LIBRARIES\s0"
.IX Subsection "OPTIONAL LIBRARIES"
PDF::Builder can make use of some optional libraries, which are not \fIrequired\fR
for a successful installation, but improve speed and capabilities. See 
\&\*(L"Optional Libraries\*(R" in PDF::Builder::Docs for more information.
.SS "\s-1STRINGS\s0 (\s-1CHARACTER TEXT\s0)"
.IX Subsection "STRINGS (CHARACTER TEXT)"
There are some things you should know about character encoding (for text),
before you dive in to coding. Please go to \*(L"Strings (Character Text)\*(R" in PDF::Builder::Docs and have a read.
.SS "\s-1RENDERING ORDER\s0"
.IX Subsection "RENDERING ORDER"
Invoking \*(L"text\*(R" and \*(L"graphics\*(R" methods can lead to unexpected results (a 
different ordering of output than intended). See \*(L"Rendering Order\*(R" in PDF::Builder::Docs for more information.
.SS "\s-1PDF VERSIONS SUPPORTED\s0"
.IX Subsection "PDF VERSIONS SUPPORTED"
PDF::Builder is mostly \s-1PDF 1\s0.4\-compliant, but there \fIare\fR complications you
should be aware of. Please read \*(L"\s-1PDF\s0 Versions Supported\*(R" in PDF::Builder::Docs
for details.
.SS "\s-1SUPPORTED PERL VERSIONS\s0 (\s-1BACKWARDS COMPATIBILITY GOALS\s0)"
.IX Subsection "SUPPORTED PERL VERSIONS (BACKWARDS COMPATIBILITY GOALS)"
PDF::Builder intends to support all major Perl versions that were released in
the past six years, plus one, in order to continue working for the life of
most long-term-stable (\s-1LTS\s0) server distributions.
See the <https://www.cpan.org/src/> table 
\&\fBFirst release in each branch of Perl\fR x.xxxx0 \*(L"Major\*(R" release dates.
.PP
For example, a version of PDF::Builder released on 2018\-06\-05 would support 
the last major version of Perl released \fIon or after\fR 2012\-06\-05 (5.18), and 
then one before that, which would be 5.16. Alternatively, the last major 
version of Perl released \fIbefore\fR 2012\-06\-05 is 5.16.
.PP
The intent is to avoid expending unnecessary effort in supporting very old
(obsolete) versions of Perl.
.PP
\fIAnticipated Support Cutoff Dates\fR
.IX Subsection "Anticipated Support Cutoff Dates"
.PP
\&\fBNote\fR that these are \fInot\fR hard and fast dates. In particular, we develop
on Strawberry Perl, which sometimes falls a little behind the official Perl
release!
.IP "\(bu" 4
5.26 current minimum supported version, until next PDF::Builder release after 23 June, 2024. This is currently the minimum tested version.
.IP "\(bu" 4
5.28 future minimum supported version, until next PDF::Builder release after 22 May, 2025
.IP "\(bu" 4
5.30 future minimum supported version, until next PDF::Builder release after 20 June, 2026
.IP "\(bu" 4
5.32 future minimum supported version, until next PDF::Builder release after 20 May, 2027. This is currently our primary development version.
.IP "\(bu" 4
5.34 future minimum supported version, until next PDF::Builder release after 28 May, 2028
.IP "\(bu" 4
5.36 future minimum supported version, until next PDF::Builder release after 02 Jul, 2029
.IP "\(bu" 4
5.38 future minimum supported version, until next PDF::Builder release some time after 02 Jul, 2029. This is currently the maximum tested version.
.PP
If you need to use this module on a server with an extremely out-of-date version
of Perl, consider using either plenv or Perlbrew to run a newer version of Perl
without needing admin privileges.
.PP
On the other hand, any feature in PDF::Builder should continue to work 
unchanged for the life of most long-term-stable (\s-1LTS\s0) server distributions.
Their lifetime is usually about six (6) years. Note that this does \fBnot\fR
constitute a statement of warranty, but that we \fIintend\fR to try to keep any
particular release of PDF::Builder working for a period of years. Of course,
it helps if you periodically update your Perl installation to something
released in the recent past.
.SS "\s-1KNOWN ISSUES\s0"
.IX Subsection "KNOWN ISSUES"
This module does not work with perl's \-l command-line switch.
.PP
There is a file \s-1INFO/KNOWN_INCOMP\s0 which lists known incompatibilities with 
\&\s-1PDF::API2,\s0 in case you're thinking of porting over something from that world, 
or have experience there and want to try PDF::Builder. There is also a file 
\&\s-1INFO/DEPRECATED,\s0 which lists things which are planned to be removed at some 
point.
.SS "\s-1HISTORY\s0"
.IX Subsection "HISTORY"
The history of PDF::Builder is a complex and exciting saga... \s-1OK,\s0 it may be
mildly interesting. Have a look at \*(L"History\*(R" in PDF::Builder::Docs section.
.SS "\s-1AUTHOR\s0"
.IX Subsection "AUTHOR"
\&\s-1PDF::API2\s0 was originally written by Alfred Reibenschuh. See the \s-1HISTORY\s0 section
for more information.
.PP
It was maintained by Steve Simms, who is still contributing new code to it
(which often ends up in PDF::Builder).
.PP
PDF::Builder is currently being maintained by Phil M. Perry.
.SS "\s-1SUPPORT\s0"
.IX Subsection "SUPPORT"
The full source is on https://github.com/PhilterPaper/Perl\-PDF\-Builder.
.PP
The release distribution is on \s-1CPAN:\s0 https://metacpan.org/pod/PDF::Builder.
.PP
Bug reports are on https://github.com/PhilterPaper/Perl\-PDF\-Builder/issues?q=is%3Aissue+sort%3Aupdated\-desc 
(with \*(L"bug\*(R" label), feature requests have an \*(L"enhancement\*(R" label, and general 
discussions (architecture, roadmap, etc.) have a \*(L"general discussion\*(R" label.
.PP
Do \fBnot\fR under \fIany\fR circumstances open a \s-1PR\s0 (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, and offer to share it as a \s-1PR,\s0 we 
may give the go-ahead. Unsolicited PRs may be closed without further action.
.SS "\s-1LICENSE\s0"
.IX Subsection "LICENSE"
This software is Copyright (c) 2017\-2023 by Phil M. Perry.
.PP
This is free software, licensed under:
.PP
The \s-1GNU\s0 Lesser General Public License (\s-1LGPL\s0) Version 2.1, February 1999
.PP
.Vb 2
\&  (The master copy of this license lives on the GNU website.)
\&  (A copy is provided in the INFO/LICENSE file for your convenience.)
.Ve
.PP
This section of Builder.pm is intended only as a very brief summary 
of the license; please consider \s-1INFO/LICENSE\s0 to be the controlling version, 
if there is any conflict or ambiguity between the two.
.PP
This program is free software; you can redistribute it and/or modify it under
the terms of the \s-1GNU\s0 Lesser General Public License, as published by the Free
Software Foundation, either version 2.1 of the License, or (at your option) any
later version of this license.
.PP
\&\s-1NOTE:\s0 there are several files in this distribution which were incorporated from
outside sources and carry different licenses. If a file states that it is under 
a license different than \s-1LGPL 2.1,\s0 that license and its terms will apply to 
that file, and not \s-1LGPL 2.1.\s0
.PP
This library is distributed in the hope that it will be useful, but \s-1WITHOUT ANY
WARRANTY\s0; without even the implied warranty of \s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A
PARTICULAR PURPOSE.\s0 See the \s-1GNU\s0 Lesser General Public License for more details.
.SH "GENERAL PURPOSE METHODS"
.IX Header "GENERAL PURPOSE METHODS"
.SS "new"
.IX Subsection "new"
.Vb 1
\&    $pdf = PDF::Builder\->new(%opts)
.Ve
.Sp
.RS 4
Creates a new \s-1PDF\s0 object.
.Sp
\&\fBOptions\fR
.RE
.IP "file" 4
.IX Item "file"
If you will be saving it as a file and
already know the filename, you can give the 'file' option to minimize
possible memory requirements later on (the file is opened immediately for
writing, rather than waiting until the \f(CW\*(C`save\*(C'\fR). The \f(CW\*(C`file\*(C'\fR may also be
a filehandle.
.IP "compress" 4
.IX Item "compress"
The 'compress' option can be
given to specify stream compression: default is 'flate', 'none' (or 0) is no
compression. No other compression methods are currently supported.
.IP "outver" 4
.IX Item "outver"
The 'outver' option defaults to 1.4 as the output \s-1PDF\s0 version and the highest 
allowed feature version (attempts to use anything higher will give a warning).
If an existing \s-1PDF\s0 with a higher version is read in, \f(CW\*(C`outver\*(C'\fR will be 
increased to that version, with a warning.
.IP "msgver" 4
.IX Item "msgver"
The 'msgver' option value of 1 (default) gives a warning message if the 
\&'outver' \s-1PDF\s0 level has to be bumped up due to either a higher \s-1PDF\s0 level file 
being read in, or a higher level feature was requested. A value of 0 
suppresses the warning message.
.IP "diaglevel" 4
.IX Item "diaglevel"
The 'diaglevel' option can be
given to specify the level of diagnostics given by \fBIntegrityCheck()\fR. The
default is level 2 (errors and warnings). 
See \*(L"IntegrityCheck\*(R" in PDF::Builder::Docs for more information.
.PP
\&\fBExample:\fR
.PP
.Vb 3
\&    $pdf = PDF::Builder\->new();
\&    ...
\&    print $pdf\->to_string();
\&
\&    $pdf = PDF::Builder\->new(compress => \*(Aqnone\*(Aq);
\&    # equivalent to $pdf\->{\*(Aqforcecompress\*(Aq} = \*(Aqnone\*(Aq; (or older, 0)
\&
\&    $pdf = PDF::Builder\->new();
\&    ...
\&    $pdf\->saveas(\*(Aqour/new.pdf\*(Aq);
\&
\&    $pdf = PDF::Builder\->new(file => \*(Aqour/new.pdf\*(Aq);
\&    ...
\&    $pdf\->save();
.Ve
.SS "default_page_size"
.IX Subsection "default_page_size"
.Vb 1
\&    $pdf\->default_page_size($size); # Set
\&
\&    @rectangle = $pdf\->default_page_size() # Get
.Ve
.Sp
.RS 4
Set the default physical size for pages in the \s-1PDF.\s0  If called without
arguments, return the coordinates of the rectangle describing the default
physical page size.
.Sp
This is essentially an alternate method of defining the \f(CW\*(C`mediabox()\*(C'\fR call,
and added for compatibility with \s-1PDF::API2.\s0
.Sp
See \*(L"Page Sizes\*(R" in PDF::Builder::Page for possible values.
.RE
.SS "default_page_boundaries"
.IX Subsection "default_page_boundaries"
.Vb 1
\&    $pdf\->default_page_boundaries(%boundaries); # Set
\&
\&    %boundaries = $pdf\->default_page_boundaries(); # Get
.Ve
.Sp
.RS 4
Set default prepress page boundaries for pages in the \s-1PDF.\s0  If called without
arguments, returns the coordinates of the rectangles describing each of the
supported page boundaries.
.Sp
See the equivalent \f(CW\*(C`page_boundaries\*(C'\fR method in PDF::Builder::Page for 
details.
.RE
.SH "INPUT/OUTPUT METHODS"
.IX Header "INPUT/OUTPUT METHODS"
.SS "open"
.IX Subsection "open"
.Vb 1
\&    $pdf = PDF::Builder\->open($pdf_file, %opts)
.Ve
.Sp
.RS 4
Opens an existing \s-1PDF\s0 file. See \f(CW\*(C`new()\*(C'\fR for options.
.Sp
\&\fBExample:\fR
.RE
.PP
.Vb 3
\&    $pdf = PDF::Builder\->open(\*(Aqour/old.pdf\*(Aq);
\&    ...
\&    $pdf\->saveas(\*(Aqour/new.pdf\*(Aq);
\&
\&    $pdf = PDF::Builder\->open(\*(Aqour/to/be/updated.pdf\*(Aq);
\&    ...
\&    $pdf\->update();
.Ve
.SS "from_string, open_scalar, openScalar"
.IX Subsection "from_string, open_scalar, openScalar"
.Vb 1
\&    $pdf = PDF::Builder\->from_string($pdf_string, %opts)
.Ve
.Sp
.RS 4
Opens a \s-1PDF\s0 contained in a string. See \f(CW\*(C`new()\*(C'\fR for other options.
.RE
.IP "diags => 1" 4
.IX Item "diags => 1"
Display warnings when non-conforming \s-1PDF\s0 structure is found, and fix up
where possible. See PDF::Builder::Basic::PDF::File for more information.
.PP
\&\fBExample:\fR
.PP
.Vb 4
\&    # Read a PDF into a string, for the purpose of demonstration
\&    open $fh, \*(Aqour/old.pdf\*(Aq or croak $@;
\&    undef $/;  # Read the whole file at once
\&    $pdf_string = <$fh>;
\&
\&    $pdf = PDF::Builder\->from_string($pdf_string);
\&    ...
\&    $pdf\->saveas(\*(Aqour/new.pdf\*(Aq);
.Ve
.Sp
.RS 4
\&\fBAlternate name:\fR \f(CW\*(C`open_scalar\*(C'\fR
.Sp
\&\f(CW\*(C`from_string\*(C'\fR was formerly known as \f(CW\*(C`open_scalar\*(C'\fR (and even before that,
as \f(CW\*(C`openScalar\*(C'\fR), and this older name is still
valid as an alternative to \f(CW\*(C`from_string\*(C'\fR. It is \fIpossible\fR that \f(CW\*(C`open_scalar\*(C'\fR
will be deprecated and then removed some time in the future, so it may be
advisable to use \f(CW\*(C`from_string\*(C'\fR in new work.
.RE
.SS "to_string, stringify"
.IX Subsection "to_string, stringify"
.Vb 1
\&    $string = $pdf\->to_string()
.Ve
.Sp
.RS 4
Return the document as a string and remove the object structure from memory.
.Sp
\&\fBCaution:\fR Although the object \f(CW$pdf\fR will still exist, it is no longer
usable for any purpose after invoking this method! You will receive error
messages about \*(L"can't call method new_obj on an undefined value\*(R".
.Sp
\&\fBExample:\fR
.RE
.PP
.Vb 3
\&    $pdf = PDF::Builder\->new();
\&    ...
\&    print $pdf\->to_string();
.Ve
.Sp
.RS 4
\&\fBAlternate name:\fR \f(CW\*(C`stringify\*(C'\fR
.Sp
\&\f(CW\*(C`to_string\*(C'\fR was formerly known as \f(CW\*(C`stringify\*(C'\fR, and this older name is still
valid as an alternative to \f(CW\*(C`to_string\*(C'\fR. It is \fIpossible\fR that \f(CW\*(C`stringify\*(C'\fR
will be deprecated and then removed some time in the future, so it may be
advisable to use \f(CW\*(C`to_string\*(C'\fR in new work.
.RE
.SS "finishobjects"
.IX Subsection "finishobjects"
.Vb 1
\&    $pdf\->finishobjects(@objects)
.Ve
.Sp
.RS 4
Force objects to be written to file if possible.
.Sp
\&\fBExample:\fR
.RE
.PP
.Vb 5
\&    $pdf = PDF::Builder\->new(file => \*(Aqour/new.pdf\*(Aq);
\&    ...
\&    $pdf\->finishobjects($page, $gfx, $txt);
\&    ...
\&    $pdf\->save();
.Ve
.Sp
.RS 4
\&\fBNote:\fR 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
\&\f(CW\*(C`save()\*(C'\fR when all changes have been made.  There's no memory advantage since
\&\f(CW\*(C`ship_out\*(C'\fR doesn't remove objects from memory.
.RE
.SS "update"
.IX Subsection "update"
.Vb 1
\&    $pdf\->update()
.Ve
.Sp
.RS 4
Saves a previously opened document.
.Sp
\&\fBExample:\fR
.RE
.PP
.Vb 3
\&    $pdf = PDF::Builder\->open(\*(Aqour/to/be/updated.pdf\*(Aq);
\&    ...
\&    $pdf\->update();
.Ve
.Sp
.RS 4
\&\fBNote:\fR it is considered better to simply \f(CW\*(C`save()\*(C'\fR the file, rather than
calling \f(CW\*(C`update()\*(C'\fR. They end up doing the same thing, anyway. This method
may be deprecated in the future.
.RE
.SS "saveas"
.IX Subsection "saveas"
.Vb 1
\&    $pdf\->saveas($file)
.Ve
.Sp
.RS 4
Save the document to \f(CW$file\fR and remove the object structure from memory.
.Sp
\&\fBCaution:\fR Although the object \f(CW$pdf\fR will still exist, it is no longer
usable for any purpose after invoking this method! You will receive error
messages about \*(L"can't call method new_obj on an undefined value\*(R".
.Sp
\&\fBExample:\fR
.RE
.PP
.Vb 3
\&    $pdf = PDF::Builder\->new();
\&    ...
\&    $pdf\->saveas(\*(Aqour/new.pdf\*(Aq);
.Ve
.SS "save"
.IX Subsection "save"
.Vb 1
\&    $pdf\->save()
\&
\&    $pdf\->save(filename)
.Ve
.Sp
.RS 4
Save the document to an already-defined file (or filename) and 
remove the object structure from memory.
Optionally, a new filename may be given.
.Sp
\&\fBCaution:\fR Although the object \f(CW$pdf\fR will still exist, it is no longer
usable for any purpose after invoking this method! You will receive error
messages about \*(L"can't call method new_obj on an undefined value\*(R".
.Sp
\&\fBExample:\fR
.RE
.PP
.Vb 3
\&    $pdf = PDF::Builder\->new(file => \*(Aqfile_to_output\*(Aq);
\&    ...
\&    $pdf\->save();
.Ve
.Sp
.RS 4
\&\fBNote:\fR now that \f(CW\*(C`save()\*(C'\fR can take a filename as an argument, it effectively
is interchangeable with \f(CW\*(C`saveas()\*(C'\fR. This is strictly for compatibility with
recent changes to \s-1PDF::API2.\s0 Unlike \s-1PDF::API2,\s0 we are not deprecating
the \f(CW\*(C`saveas()\*(C'\fR method, because in user interfaces, \*(L"save\*(R" normally means that
the current filename is known and is to be used, while \*(L"saveas\*(R" normally means
that (whether or not there is a current filename) a new filename is to be used.
.RE
.SS "close, release, end"
.IX Subsection "close, release, end"
.Vb 1
\&    $pdf\->close();
.Ve
.Sp
.RS 4
Close an open file (if relevant) and remove the object structure from memory.
.Sp
\&\s-1PDF::API2\s0 contains circular references, so this call is necessary in
long-running processes to keep from running out of memory.
.Sp
This will be called automatically when you save or stringify a \s-1PDF.\s0
You should only need to call it explicitly if you are reading \s-1PDF\s0
files and not writing them.
.Sp
\&\fBAlternate names:\fR \f(CW\*(C`release\*(C'\fR and \f(CW\*(C`end\*(C'\fR
.RE
.SS "end"
.IX Subsection "end"
.Vb 1
\&    $pdf\->end()
.Ve
.Sp
.RS 4
Remove the object structure from memory. PDF::Builder contains circular
references, so this call is necessary in long-running processes to
keep from running out of memory.
.Sp
This will be called automatically when you save or to_string a \s-1PDF.\s0
You should only need to call it explicitly if you are reading \s-1PDF\s0
files and not writing them.
.Sp
This (and \fIrelease\fR) are older and now deprecated names formerly used in 
\&\s-1PDF::API2\s0 and PDF::Builder. You should try to avoid having to explicitly
call them.
.RE
.SS "\s-1METADATA METHODS\s0"
.IX Subsection "METADATA METHODS"
\fItitle\fR
.IX Subsection "title"
.PP
.Vb 1
\&    $title = $pdf\->title();
\&
\&    $pdf = $pdf\->title($title);
.Ve
.Sp
.RS 4
Get/set/clear the document's title.
.RE
.PP
\fIauthor\fR
.IX Subsection "author"
.PP
.Vb 1
\&    $author = $pdf\->author();
\&
\&    $pdf = $pdf\->author($author);
.Ve
.Sp
.RS 4
Get/set/clear the name of the person who created the document.
.RE
.PP
\fIsubject\fR
.IX Subsection "subject"
.PP
.Vb 1
\&    $subject = $pdf\->subject();
\&
\&    $pdf = $pdf\->subject($subject);
.Ve
.Sp
.RS 4
Get/set/clear the subject of the document.
.RE
.PP
\fIkeywords\fR
.IX Subsection "keywords"
.PP
.Vb 1
\&    $keywords = $pdf\->keywords();
\&
\&    $pdf = $pdf\->keywords($keywords);
.Ve
.Sp
.RS 4
Get/set/clear a space-separated string of keywords associated with the document.
.RE
.PP
\fIcreator\fR
.IX Subsection "creator"
.PP
.Vb 1
\&    $creator = $pdf\->creator();
\&
\&    $pdf = $pdf\->creator($creator);
.Ve
.Sp
.RS 4
Get/set/clear the name of the product that created the document prior to its
conversion to \s-1PDF.\s0
.RE
.PP
\fIproducer\fR
.IX Subsection "producer"
.PP
.Vb 1
\&    $producer = $pdf\->producer();
\&
\&    $pdf = $pdf\->producer($producer);
.Ve
.Sp
.RS 4
Get/set/clear the name of the product that converted the original document to
\&\s-1PDF.\s0
.Sp
PDF::Builder fills in this field when creating a \s-1PDF.\s0
.RE
.PP
\fIcreated\fR
.IX Subsection "created"
.PP
.Vb 1
\&    $date = $pdf\->created();
\&
\&    $pdf = $pdf\->created($date);
.Ve
.Sp
.RS 4
Get/set/clear the document's creation date.
.Sp
The date format is \f(CW\*(C`D:YYYYMMDDHHmmSSOHH\*(Aqmm\*(C'\fR, where \f(CW\*(C`D:\*(C'\fR is a static prefix
identifying the string as a \s-1PDF\s0 date.  The date may be truncated at any point
after the year.  \f(CW\*(C`O\*(C'\fR is one of \f(CW\*(C`+\*(C'\fR, \f(CW\*(C`\-\*(C'\fR, or \f(CW\*(C`Z\*(C'\fR, with the following \f(CW\*(C`HH\*(Aqmm\*(C'\fR
representing an offset from \s-1UTC.\s0
.Sp
See comments in the internal function \f(CW\*(C`_is_date()\*(C'\fR for more information on
the inconsistency of \s-1PDF\s0 standards on exactly what the date format should be!
.Sp
When setting the date, \f(CW\*(C`D:\*(C'\fR will be prepended automatically if omitted.
.RE
.PP
\fImodified\fR
.IX Subsection "modified"
.PP
.Vb 1
\&    $date = $pdf\->modified();
\&
\&    $pdf = $pdf\->modified($date);
.Ve
.Sp
.RS 4
Get/set/clear the document's modification date.  The date format is as described
in \f(CW\*(C`created\*(C'\fR above.
.Sp
See comments in the internal function \f(CW\*(C`_is_date()\*(C'\fR for more information on
the inconsistency of \s-1PDF\s0 standards on exactly what the date format should be!
.RE
.PP
\fIinfo_metadata\fR
.IX Subsection "info_metadata"
.PP
.Vb 1
\&    %info = $pdf\->info_metadata(); # Get all keys and values
\&
\&    $value = $pdf\->info_metadata($key); # Get the value of one key
\&
\&    $pdf = $pdf\->info_metadata($key, $value); # Set the value of one key
.Ve
.Sp
.RS 4
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
for interacting with custom metadata.
.Sp
Pass \f(CW\*(C`undef\*(C'\fR as the value in order to remove the key from the dictionary.
.Sp
See comments in the internal function \f(CW\*(C`_is_date()\*(C'\fR for more information on
the inconsistency of \s-1PDF\s0 standards on exactly what the date format should be!
This applies to CreationDate and ModDate keys.
.RE
.PP
\fIinfo\fR
.IX Subsection "info"
.PP
.Vb 1
\&    %infohash = $pdf\->info()
\&
\&    %infohash = $pdf\->info(%infohash)
.Ve
.Sp
.RS 4
Gets/sets the info structure of the document.
.Sp
See \*(L"info Example\*(R" in PDF::Builder::Docs section for an example of the use
of this method.
.Sp
\&\fBNote:\fR this method is still available, for compatibility purposes. It is
better to use individual accessors or \f(CW\*(C`info_metadata\*(C'\fR instead.
.RE
.PP
\fIinfoMetaAttributes\fR
.IX Subsection "infoMetaAttributes"
.PP
.Vb 1
\&    @metadata_attributes = $pdf\->infoMetaAttributes()
\&
\&    @metadata_attributes = $pdf\->infoMetaAttributes(@metadata_attributes)
.Ve
.Sp
.RS 4
Gets/sets the supported info-structure tags.
.Sp
\&\fBExample:\fR
.RE
.PP
.Vb 2
\&    @attributes = $pdf\->infoMetaAttributes;
\&    print "Supported Attributes: @attr\en";
\&
\&    @attributes = $pdf\->infoMetaAttributes(\*(AqCustomField1\*(Aq);
\&    print "Supported Attributes: @attributes\en";
.Ve
.Sp
.RS 4
\&\fBNote:\fR this method is still available for compatibility purposes, but the
use of \f(CW\*(C`info_metadata\*(C'\fR instead is encouraged.
.RE
.PP
\fIxml_metadata\fR
.IX Subsection "xml_metadata"
.PP
.Vb 1
\&    $xml = $pdf\->xml_metadata();
\&
\&    $pdf = $pdf\->xml_metadata($xml);
.Ve
.Sp
.RS 4
Gets/sets the document's \s-1XML\s0 metadata stream.
.RE
.PP
\fIxmpMetadata\fR
.IX Subsection "xmpMetadata"
.PP
.Vb 1
\&    $xml = $pdf\->xmpMetadata()  # Get
\&
\&    $xml = $pdf\->xmpMetadata($xml)  # Set (also returns $xml value)
.Ve
.Sp
.RS 4
Gets/sets the \s-1XMP XML\s0 data stream.
.Sp
See \*(L"\s-1XMP XML\s0 example\*(R" in PDF::Builder::Docs section for an example of the use
of this method.
.Sp
This method is considered \fBobsolete\fR. Use \f(CW\*(C`xml_metadata\*(C'\fR instead.
.RE
.PP
\fIdefault\fR
.IX Subsection "default"
.PP
.Vb 1
\&    $val = $pdf\->default($parameter)
\&
\&    $pdf\->default($parameter, $value)
.Ve
.Sp
.RS 4
Gets/sets the default value for a behavior of PDF::Builder.
.Sp
\&\fBSupported Parameters:\fR
.RE
.IP "nounrotate" 4
.IX Item "nounrotate"
prohibits Builder from rotating imported/opened page to re-create a
default pdf-context.
.IP "pageencaps" 4
.IX Item "pageencaps"
enables Builder's adding save/restore commands upon importing/opening
pages to preserve graphics-state for modification.
.IP "copyannots" 4
.IX Item "copyannots"
enables importing of annotations (\fB*EXPERIMENTAL*\fR).
.Sp
.RS 4
\&\fB\s-1CAUTION:\s0\fR Perl::Critic (tools/1_pc.pl) has started flagging the name 
\&\*(L"default\*(R" as a reserved keyword in higher Perl versions. Use with caution, and
be aware that this name \fImay\fR have to be changed in the future.
.RE
.PP
\fIversion\fR
.IX Subsection "version"
.PP
.Vb 1
\&    $version = $pdf\->version() # Get
\&
\&    $version = $pdf\->version($version) # Set (also returns newly set version)
.Ve
.Sp
.RS 4
Gets/sets the \s-1PDF\s0 version (e.g., 1.5). 
For compatibility with earlier releases, if no decimal point is given, assume
\&\*(L"1.\*(R" precedes the number given.
.Sp
A warning message is given if you attempt to \fIdecrease\fR the \s-1PDF\s0 version, as you
might have already read in a higher level file, or used a higher level feature.
.Sp
See PDF::Builder::Basic::PDF::File for additional information on the
\&\f(CW\*(C`version\*(C'\fR method.
.RE
.PP
\fIis_encrypted, isEncrypted\fR
.IX Subsection "is_encrypted, isEncrypted"
.PP
.Vb 1
\&    $bool = $pdf\->is_encrypted()
.Ve
.Sp
.RS 4
Checks if the previously opened \s-1PDF\s0 is encrypted.
.Sp
\&\fBAlternate name:\fR \f(CW\*(C`isEncrypted\*(C'\fR
.Sp
This is the older name; it is kept for compatibility with \s-1PDF::API2.\s0
.RE
.SH "INTERACTIVE FEATURE METHODS"
.IX Header "INTERACTIVE FEATURE METHODS"
.SS "outline, outlines"
.IX Subsection "outline, outlines"
.Vb 1
\&    $otls = $pdf\->outline()
.Ve
.Sp
.RS 4
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 
\&\s-1PDF\s0 reader being used.
.Sp
To examine or modify the outline tree, see PDF::Builder::Outlines.
.Sp
\&\fBAlternate name:\fR \f(CW\*(C`outlines\*(C'\fR
.Sp
This is the older name; it is kept for compatibility.
.RE
.SS "page_layout"
.IX Subsection "page_layout"
.Vb 1
\&    $layout = $pdf\->page_layout();
\&
\&    $pdf = $pdf\->page_layout($layout);
.Ve
.Sp
.RS 4
Gets/sets the page layout that should be used when the \s-1PDF\s0 is opened.
.Sp
\&\f(CW$layout\fR is one of the following:
.RE
.IP "single_page (or undef)" 4
.IX Item "single_page (or undef)"
Display one page at a time.
.IP "one_column" 4
.IX Item "one_column"
Display the pages in one column (a.k.a. continuous).
.IP "two_column_left" 4
.IX Item "two_column_left"
Display the pages in two columns, with odd-numbered pages on the left.
.IP "two_column_right" 4
.IX Item "two_column_right"
Display the pages in two columns, with odd-numbered pages on the right.
.IP "two_page_left" 4
.IX Item "two_page_left"
Display two pages at a time, with odd-numbered pages on the left.
.IP "two_page_right" 4
.IX Item "two_page_right"
Display two pages at a time, with odd-numbered pages on the right.
.Sp
.RS 4
This has been split out from \f(CW\*(C`preferences()\*(C'\fR for compatibility with \s-1PDF::API2.\s0
It also can both set (assign) and get (query) the settings used.
.RE
.SS "page_mode"
.IX Subsection "page_mode"
.Vb 1
\&    $mode = $pdf\->page_mode(); # Get
\&
\&    $pdf = $pdf\->page_mode($mode); # Set
.Ve
.Sp
.RS 4
Gets/sets the page mode, which describes how the \s-1PDF\s0 should be displayed when
opened.
.Sp
\&\f(CW$mode\fR is one of the following:
.RE
.IP "none (or undef)" 4
.IX Item "none (or undef)"
Neither outlines nor thumbnails should be displayed.
.IP "outlines" 4
.IX Item "outlines"
Show the document outline.
.IP "thumbnails" 4
.IX Item "thumbnails"
Show the page thumbnails.
.IP "full_screen" 4
.IX Item "full_screen"
Open in full-screen mode, with no menu bar, window controls, or any other window
visible.
.IP "optional_content" 4
.IX Item "optional_content"
Show the optional content group panel.
.IP "attachments" 4
.IX Item "attachments"
Show the attachments panel.
.Sp
.RS 4
This has been split out from \f(CW\*(C`preferences()\*(C'\fR for compatibility with \s-1PDF::API2.\s0
It also can both set (assign) and get (query) the settings used.
.RE
.SS "viewer_preferences"
.IX Subsection "viewer_preferences"
.Vb 1
\&    %preferences = $pdf\->viewer_preferences(); # Get
\&
\&    $pdf = $pdf\->viewer_preferences(%preferences); # Set
.Ve
.Sp
.RS 4
Gets/sets \s-1PDF\s0 viewer preferences, as described in
PDF::Builder::ViewerPreferences.
.Sp
This has been split out from \f(CW\*(C`preferences()\*(C'\fR for compatibility with \s-1PDF::API2.\s0
It also can both set (assign) and get (query) the settings used.
.RE
.SS "preferences"
.IX Subsection "preferences"
.Vb 1
\&    $pdf\->preferences(%opts)
.Ve
.Sp
.RS 4
Controls viewing preferences for the \s-1PDF,\s0 including the \fBPage Mode\fR, 
\&\fBPage Layout\fR, \fBViewer\fR, and \fBInitial Page\fR Options. See 
\&\*(L"Preferences \- set user display preferences\*(R" in PDF::Builder::Docs for details 
on all these 
option groups, and \*(L"Page Fit Options\*(R" in PDF::Builder::Docs for page positioning.
.Sp
\&\fBNote:\fR the various preferences have been split out into their own methods.
It is preferred that you use these specific methods.
.RE
.SH "PAGE METHODS"
.IX Header "PAGE METHODS"
.SS "page"
.IX Subsection "page"
.Vb 1
\&    $page = $pdf\->page()
\&
\&    $page = $pdf\->page($page_number)
.Ve
.Sp
.RS 4
Returns a \fInew\fR page object.  By default, the page is added to the end
of the document.  If you give an existing page number, the new page
will be inserted in that position, pushing existing pages back by 1 (e.g., 
\&\f(CWpage(5)\fR would insert an empty page 5, with the old page 5 now page 6,
etc.
.Sp
If \f(CW$page_number\fR is \-1, the new page is inserted as the second-to-last page;
if \f(CW$page_number\fR is 0, the new page is inserted as the last page.
.Sp
\&\fBExample:\fR
.Sp
.Vb 1
\&    $pdf = PDF::Builder\->new();
\&
\&    # Add a page.  This becomes page 1.
\&    $page = $pdf\->page();
\&
\&    # Add a new first page.  $page becomes page 2.
\&    $another_page = $pdf\->page(1);
.Ve
.RE
.SS "open_page, openpage"
.IX Subsection "open_page, openpage"
.Vb 1
\&    $page = $pdf\->open_page($page_number)
.Ve
.Sp
.RS 4
Returns the PDF::Builder::Page object of page \f(CW$page_number\fR.
This is similar to \f(CW\*(C`$page = $pdf\->page()\*(C'\fR, except that \f(CW$page\fR is 
\&\fInot\fR a new, empty page; but contains the contents of that existing page.
.Sp
If \f(CW$page_number\fR is 0, \-1, or unspecified, 
it will return the last page in the document.
If the requested page is out of range, the \f(CW$page\fR returned will be undefined.
.Sp
\&\fBExample:\fR
.RE
.PP
.Vb 7
\&    $pdf  = PDF::Builder\->open(\*(Aqour/99page.pdf\*(Aq);
\&    $page = $pdf\->open_page(1);   # returns the first page
\&    $page = $pdf\->open_page(99);  # returns the last page
\&    $page = $pdf\->open_page(\-1);  # returns the last page
\&    $page = $pdf\->open_page(999); # returns undef
\&    $page = $pdf\->open_page(0);   # returns the last page
\&    $page = $pdf\->open_page();    # returns the last page
.Ve
.Sp
.RS 4
\&\fBAlternate name:\fR \f(CW\*(C`openpage\*(C'\fR
.Sp
This is the older name; it is kept for compatibility until after June 2023
(deprecated, as previously announced).
.RE
.SS "import_page, importpage"
.IX Subsection "import_page, importpage"
.Vb 1
\&    $page = $pdf\->import_page($source_pdf)
\&
\&    $page = $pdf\->import_page($source_pdf, $source_page_number)
\&
\&    $page = $pdf\->import_page($source_pdf, $source_page_number, $target_page_number)
\&
\&    $page = $pdf\->import_page($source_pdf, $source_page_number, $target_page_object)
.Ve
.Sp
.RS 4
Imports a page from \f(CW$source_pdf\fR and adds it to the specified position
in \f(CW$pdf\fR.
.Sp
If the \f(CW$source_page_number\fR is omitted, 0, or \-1; the last page of the 
source is imported.
If the \f(CW$target_page_number\fR is omitted, 0, or \-1; the imported page will be
placed as the new last page of the target (\f(CW$pdf\fR).
Otherwise, as with the \f(CW\*(C`page()\*(C'\fR method, the page will be inserted before an 
existing page of that number.
.Sp
\&\fBNote:\fR If you pass a page \fIobject\fR instead of a page \fInumber\fR for
\&\f(CW$target_page_number\fR, the contents of the page will be \fBmerged\fR into the
existing page.
.Sp
\&\fBExample:\fR
.RE
.PP
.Vb 2
\&    my $pdf = PDF::Builder\->new();
\&    my $source = PDF::Builder\->open(\*(Aqsource.pdf\*(Aq);
\&
\&    # Add page 2 from the old PDF as page 1 of the new PDF
\&    my $page = $pdf\->import_page($source, 2);
\&
\&    $pdf\->saveas(\*(Aqsample.pdf\*(Aq);
.Ve
.Sp
.RS 4
\&\fBNote:\fR You can only import a page from an existing \s-1PDF\s0 file.
.Sp
\&\fBAlternate name:\fR importpage
.Sp
This name is still valid in \s-1PDF::API2,\s0 so it is included here for compatiblity.
.RE
.SS "embed_page, importPageIntoForm"
.IX Subsection "embed_page, importPageIntoForm"
.Vb 1
\&    $xoform = $pdf\->embed_page($source_pdf, $source_page_number)
.Ve
.Sp
.RS 4
Returns a Form XObject created by extracting the specified page from 
\&\f(CW$source_pdf\fR.
.Sp
This is useful if you want to transpose the imported page somewhat
differently onto a page (e.g. two-up, four-up, etc.).
.Sp
If \f(CW$source_page_number\fR is 0 or \-1, it will return the last page in the
document. The \fBdefault\fR value for the \f(CW$source_page_number\fR is 0 (return
last page).
.Sp
\&\fBExample:\fR
.RE
.PP
.Vb 6
\&    # 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(\*(Aqsource.pdf\*(Aq);        # content to copy over
\&    my $page = $pdf\->page();                      # place to be actually updated
\&
\&    # Import Page 2 from the source PDF
\&    my $xo = $pdf\->embed_page($source, 2);
\&
\&    # Add it to the new PDF\*(Aqs first page at 1/2 scale
\&    my ($x, $y) = (0, 0);
\&    $page\->object($xo, $x, $y, 0.5);
\&
\&    $pdf\->save(\*(Aqsample.pdf\*(Aq);
.Ve
.Sp
.RS 4
\&\fBNote:\fR You can only import a page from an existing \s-1PDF\s0 file.
.Sp
\&\fBAlternate name:\fR \f(CW\*(C`importPageIntoForm\*(C'\fR
.Sp
This is the older name; it is kept for compatibility.
.RE
.SS "page_count, pages"
.IX Subsection "page_count, pages"
.Vb 1
\&    $count = $pdf\->page_count()
.Ve
.Sp
.RS 4
Returns the number of pages in the document.
.Sp
\&\fBAlternate name:\fR \f(CW\*(C`pages\*(C'\fR
.Sp
This is the old name; it is kept for compatibility.
.RE
.SS "page_labels, pageLabel"
.IX Subsection "page_labels, pageLabel"
.Vb 1
\&    $pdf\->page_labels($page_number, %opts)
.Ve
.Sp
.RS 4
Sets page label numbering format, for the \s-1PDF\s0 Reader's page-selection slider 
thumb (\fInot\fR 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 \s-1PDF\s0 Reader you are using, this formatted page label \fImay\fR 
show up in the reader control area as the current page number.
.Sp
\&\fB\s-1CAUTIONS:\s0\fR
.RE
.IP "1." 4
The given page index started at 0 for the old method (\f(CW\*(C`pageLabel()\*(C'\fR),
which is the internal \s-1PDF\s0 array index, while for the new method 
(\f(CW\*(C`page_labels()\*(C'\fR) it starts with 1, the visible page number! Don't get
confused.
.IP "2." 4
Options for the old method (\f(CW\*(C`pageLabel\*(C'\fR) were a hashref, while for the
new method (\f(CW\*(C`page_labels\*(C'\fR) it is a hash. This permits \fBpageLabel()\fR to accept
\&\fImultiple\fR page number schemes in one call, rather than one per call as per
\&\fBpage_labels()\fR.
.IP "3." 4
Many \s-1PDF\s0 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 \fIm\fR of \fIn\fR"). You may be able to get around this
problem by using an explicit \fBstart\fR option value, e.g., \f(CW\*(C`\*(Aqstart\*(Aq => 1\*(C'\fR.
.PP
.Vb 3
\&    # Generate a 30\-page PDF
\&    my $pdf = PDF::Builder\->new();
\&    $pdf\->page() for 1..30;
\&
\&    # Number pages i to v, 1 to 20, and A\-1 to A\-5, respectively
\&    $pdf\->page_labels(1, \*(Aqstyle\*(Aq => \*(Aqroman\*(Aq);
\&    $pdf\->page_labels(6, \*(Aqstyle\*(Aq => \*(Aqdecimal\*(Aq);
\&    $pdf\->page_labels(26, \*(Aqstyle\*(Aq => \*(Aqdecimal\*(Aq, \*(Aqprefix\*(Aq => \*(AqA\-\*(Aq);
\&
\&    or...
\&
\&    $pdf\->pageLabel(0,  { style => \*(Aqroman\*(Aq },
\&                    5,  { style => \*(Aqdecimal\*(Aq },
\&                    25, { style => \*(Aqdecimal\*(Aq, prefix => \*(AqA\-\*(Aq });
\&
\&    $pdf\->save(\*(Aqsample.pdf\*(Aq);
.Ve
.PP
\&\fBSupported Options:\fR
.IP "style" 4
.IX Item "style"
\&\fBRoman\fR (I,II,III,...), \fBroman\fR (i,ii,iii,...), \fBdecimal\fR (1,2,3,...), 
\&\fBAlpha\fR (A,B,C,...), \fBalpha\fR (a,b,c,...), or \fBnocounter\fR. This is the 
styling of the counter part of the label (unless \f(CW\*(C`nocounter\*(C'\fR, in which case 
there is no counter output).
.IP "start" 4
.IX Item "start"
(Re)start numbering the \fIcounter\fR at given page number (this is a decimal 
integer, \fInot\fR the styled counter). By default it starts at 1, and \fBresets\fR
to 1 at each call to \f(CW\*(C`page_labels()\*(C'\fR! You need to explicitly give \f(CW\*(C`start\*(C'\fR if 
you want to \fIcontinue\fR counting at the current page number when you call
\&\f(CW\*(C`page_labels()\*(C'\fR, whether or not you are changing the format.
.Sp
Also note that the counter starts at physical page \fB1\fR, while the page 
\&\f(CW$index\fR number in the \f(CW\*(C`page_labels()\*(C'\fR call (as well as the \s-1PDF\s0 PageLabels 
dictionary) starts at logical page (index) \fB0\fR.
.IP "prefix" 4
.IX Item "prefix"
Text prefix for numbering, such as an Appendix letter \fBB\-\fR. If \f(CW\*(C`style\*(C'\fR is 
\&\fInocounter\fR, just this text is used, otherwise a styled counter will be 
appended. If \f(CW\*(C`style\*(C'\fR is omitted, remember that it will default to a decimal 
number, which will be appended to the prefix.
.Sp
According to the Adobe/ISO \s-1PDF\s0 specification, a prefix of 'Content' has a 
special meaning, in that any /S counter is ignored and only that text is used. 
However, this appears to be ignored (use a style of \fInocounter\fR to suppress
the counter).
.Sp
.RS 4
\&\fBDotted inserted page numbers\fR
.Sp
To easily insert a range of pages, e.g., 3 pages between existing pages 37 and 
38, use a \f(CW\*(C`prefix\*(C'\fR of '37.' and decimal numbering starting (\f(CW\*(C`start\*(C'\fR) 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 \f(CW\*(C`prefix\*(C'\fR of 
\&'37.0' and \f(CW\*(C`start\*(C'\fR at 5.
.Sp
Just remember that only the (rightmost) \fIcounter\fR, which begins at the 
\&\f(CW\*(C`start\*(C'\fR value, is incremented (and formatted) by the \s-1PDF\s0 Reader. Everything 
else (the \f(CW\*(C`prefix\*(C'\fR) is a constant string. At worst, you might have to define 
a page label for each individual page.
.Sp
\&\fBExample:\fR
.RE
.PP
.Vb 4
\&    # Start with lowercase Roman Numerals at the 1st page, starting with i (1)
\&    $pdf\->page_labels(1, 
\&        \*(Aqstyle\*(Aq => \*(Aqroman\*(Aq,
\&    );
\&
\&    or,
\&
\&    $pdf\->pageLabel(0, 
\&        { \*(Aqstyle\*(Aq => \*(Aqroman\*(Aq },
\&    );
\&
\&    # Switch to Arabic (decimal) at the 5th page, starting with 1
\&    $pdf\->page_labels(5, 
\&        \*(Aqstyle\*(Aq => \*(Aqdecimal\*(Aq,
\&    );
\&
\&    or, 
\&
\&    $pdf\->pageLabel(4, 
\&        { \*(Aqstyle\*(Aq => \*(Aqdecimal\*(Aq },
\&    );
\&
\&    # invalid style at the 25th page, should just continue 
\&    # with decimal at the current counter
\&    $pdf\->page_labels(25, 
\&        \*(Aqstyle\*(Aq => \*(Aqraman_noodles\*(Aq,  # fail over to decimal
\&           # note that older versions of PDF::API2 may see the \*(Aqr\*(Aq and 
\&           #   treat it as \*(Aqroman\*(Aq
\&        \*(Aqstart\*(Aq => 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(31, 
\&        \*(Aqstyle\*(Aq => \*(Aqnocounter\*(Aq,
\&    );
\&
\&    # Numbering for Appendix A at the 33rd page, A\-1, A\-2,...
\&    $pdf\->page_labels(33, 
\&        \*(Aqstart\*(Aq => 1,  # unnecessary
\&        \*(Aqprefix\*(Aq => \*(AqA\-\*(Aq
\&    );
\&
\&    # Numbering for Appendix B at the 37th page, B\-1, B\-2,...
\&    $pdf\->page_labels(37, 
\&        \*(Aqprefix\*(Aq => \*(AqB\-\*(Aq
\&    );
\&
\&    # Numbering for the Index at the 41st page, Index I, Index II,...
\&    $pdf\->page_labels(41, 
\&        \*(Aqstyle\*(Aq => \*(AqRoman\*(Aq,
\&        \*(Aqstart\*(Aq => 1,  # unnecessary
\&        \*(Aqprefix\*(Aq => \*(AqIndex \*(Aq  # note trailing space
\&    );
\&
\&    # Unnumbered \*(AqIndex\*(Aq at the 45th page, Index, Index,...
\&    $pdf\->page_labels(45, 
\&        \*(Aqstyle\*(Aq => \*(Aqnocounter\*(Aq,
\&        \*(Aqprefix\*(Aq => \*(AqIndex \*(Aq
\&    );
.Ve
.Sp
.RS 4
\&\fBAlternate name:\fR \f(CW\*(C`pageLabel\*(C'\fR
.Sp
This old method name is retained for compatibility with old user code.
Note that with \f(CW\*(C`pageLabel\*(C'\fR, you need to make the \*(L"options\*(R" list an anonymous
hash by placing \fB{ }\fR around the entire list, even if it has only one item
in it. Also remember that the page number (index) for \f(CW\*(C`pageLabel\*(C'\fR starts at 0
(same as the \s-1PDF\s0 page index), rather than 1 (as in \f(CW\*(C`page_labels\*(C'\fR).
Finally, \fBpageLabel()\fR still permits you to define multiple page numbering schemes
in one call.
.RE
.SS "userunit"
.IX Subsection "userunit"
.Vb 1
\&    $pdf\->userunit($value)
.Ve
.Sp
.RS 4
Sets the global UserUnit, defining the scale factor to multiply any size or
coordinate by. For example, \f(CW\*(C`userunit(72)\*(C'\fR results in a User Unit of 72 points,
or 1 inch.
.Sp
See \*(L"User Units\*(R" in PDF::Builder::Docs for more information.
.RE
.SS "mediabox"
.IX Subsection "mediabox"
.Vb 1
\&    $pdf\->mediabox($name)
\&
\&    $pdf\->mediabox($name, \*(Aqorient\*(Aq => \*(Aqorientation\*(Aq)
\&
\&    $pdf\->mediabox($w,$h)
\&
\&    $pdf\->mediabox($llx,$lly, $urx,$ury)
\&
\&    ($llx,$lly, $urx,$ury) = $pdf\->mediabox()
.Ve
.Sp
.RS 4
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 
the physical paper size.
.Sp
See \*(L"Media Box\*(R" in PDF::Builder::Docs for more information.
The method always returns the current bounds (after any set operation).
.RE
.SS "cropbox"
.IX Subsection "cropbox"
.Vb 1
\&    $pdf\->cropbox($name)
\&
\&    $pdf\->cropbox($name, \*(Aqorient\*(Aq => \*(Aqorientation\*(Aq)
\&
\&    $pdf\->cropbox($w,$h)
\&
\&    $pdf\->cropbox($llx,$lly, $urx,$ury)
\&
\&    ($llx,$lly, $urx,$ury) = $pdf\->cropbox()
.Ve
.Sp
.RS 4
Sets (or gets) the global CropBox. This will define the media size to which 
the output will later be clipped.
.Sp
See \*(L"Crop Box\*(R" in PDF::Builder::Docs for more information.
The method always returns the current bounds (after any set operation).
.RE
.SS "bleedbox"
.IX Subsection "bleedbox"
.Vb 1
\&    $pdf\->bleedbox($name)
\&
\&    $pdf\->bleedbox($name, \*(Aqorient\*(Aq => \*(Aqorientation\*(Aq)
\&
\&    $pdf\->bleedbox($w,$h)
\&
\&    $pdf\->bleedbox($llx,$lly, $urx,$ury)
\&
\&    ($llx,$lly, $urx,$ury) = $pdf\->bleedbox()
.Ve
.Sp
.RS 4
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.
.Sp
See \*(L"Bleed Box\*(R" in PDF::Builder::Docs for more information.
The method always returns the current bounds (after any set operation).
.RE
.SS "trimbox"
.IX Subsection "trimbox"
.Vb 1
\&    $pdf\->trimbox($name)
\&
\&    $pdf\->trimbox($name, \*(Aqorient\*(Aq => \*(Aqorientation\*(Aq)
\&
\&    $pdf\->trimbox($w,$h)
\&
\&    $pdf\->trimbox($llx,$lly, $urx,$ury)
\&
\&    ($llx,$lly, $urx,$ury) = $pdf\->trimbox()
.Ve
.Sp
.RS 4
Sets (or gets) the global TrimBox. This is supposed to be the actual 
dimensions of the finished page (after trimming of the paper).
.Sp
See \*(L"Trim Box\*(R" in PDF::Builder::Docs for more information.
The method always returns the current bounds (after any set operation).
.RE
.SS "artbox"
.IX Subsection "artbox"
.Vb 1
\&    $pdf\->artbox($name)
\&
\&    $pdf\->artbox($name, \*(Aqorient\*(Aq => \*(Aqorientation\*(Aq)
\&
\&    $pdf\->artbox($w,$h)
\&
\&    $pdf\->artbox($llx,$lly, $urx,$ury)
\&
\&    ($llx,$lly, $urx,$ury) = $pdf\->artbox()
.Ve
.Sp
.RS 4
Sets (or gets) the global ArtBox. This is supposed to define "the extent of 
the page's \fImeaningful\fR content\*(L". What is considered \*(R"meaningful\*(L" is up to 
the author of the page, but would usually exclude \*(R"decorative" graphics and
such; and possibly titles, headers, footers, and page numbers.
.Sp
See \*(L"Art Box\*(R" in PDF::Builder::Docs for more information.
The method always returns the current bounds (after any set operation).
.RE
.SH "FONT METHODS"
.IX Header "FONT METHODS"
.SS "Embedding of Fonts"
.IX Subsection "Embedding of Fonts"
\&\fB\s-1CAUTION:\s0\fR Some font routines (currently only \f(CW\*(C`ttfont()\*(C'\fR) automatically embed
font definitions for the purpose of improving portability of \s-1PDF\s0 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 \f(CW\*(C`noembed\*(C'\fR or \f(CW\*(C`nosubset\*(C'\fR 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!
.PP
\fIcorefont\fR
.IX Subsection "corefont"
.PP
.Vb 1
\&    $font = $pdf\->corefont($fontname, %opts)
.Ve
.Sp
.RS 4
Returns a new Adobe core font object. For details, 
see \*(L"Core Fonts\*(R" in PDF::Builder::Docs. Note that this is an Adobe-standard
corefont \fIname\fR, and not a file name.
.Sp
See also PDF::Builder::Resource::Font::CoreFont.
.RE
.PP
\fIpsfont\fR
.IX Subsection "psfont"
.PP
.Vb 1
\&    $font = $pdf\->psfont($ps_file, %opts)
.Ve
.Sp
.RS 4
Returns a new Adobe Type1 (\*(L"PostScript\*(R", \*(L"T1\*(R") font object.
For details, see \*(L"\s-1PS\s0 Fonts\*(R" in PDF::Builder::Docs.
.Sp
See also PDF::Builder::Resource::Font::Postscript.
.RE
.PP
\fIttfont\fR
.IX Subsection "ttfont"
.PP
.Vb 1
\&    $font = $pdf\->ttfont($ttf_file, %opts)
.Ve
.Sp
.RS 4
Returns a new TrueType (or OpenType) font object.
For details, see \*(L"TrueType Fonts\*(R" in PDF::Builder::Docs.
.RE
.PP
\fIbdfont\fR
.IX Subsection "bdfont"
.PP
.Vb 1
\&    $font = $pdf\->bdfont($bdf_file, @opts)
.Ve
.Sp
.RS 4
Returns a new \s-1BDF\s0 (bitmapped distribution format) font object, based on the 
specified Adobe \s-1BDF\s0 file. These are very low resolution fonts that appear to
have come off a dot-matrix printer.
.Sp
See also PDF::Builder::Resource::Font::BdFont
.RE
.PP
\fIcjkfont\fR
.IX Subsection "cjkfont"
.PP
.Vb 1
\&    $font = $pdf\->cjkfont($cjkname, %opts)
.Ve
.Sp
.RS 4
Returns a new \s-1CJK\s0 font object. These are TrueType-like fonts for East Asian
languages (Chinese, Japanese, Korean).
For details, see \*(L"\s-1CJK\s0 Fonts\*(R" in PDF::Builder::Docs.
.Sp
\&\fB\s-1NOTE:\s0\fR \f(CW\*(C`cjkfont\*(C'\fR is quite old and is not well supported. We recommend that
you try using \f(CW\*(C`ttfont\*(C'\fR (or another font routine, if not \s-1TTF/OTF\s0) with the
appropriate \s-1CJK\s0 font file. Most appear to be .ttf or .otf format. PDFs created
using \f(CW\*(C`cjkfont\*(C'\fR may not be fully portable, and support for
\&\f(CW\*(C`cjkfont\*(C'\fR \fImay\fR be dropped in a future release. We would appreciate hearing
from you if you are successfully using \f(CW\*(C`cjkfont\*(C'\fR, and are unable to use
\&\f(CW\*(C`ttfont\*(C'\fR instead.
.Sp
Among other things, \f(CW\*(C`cjkfont\*(C'\fR selections are limited, as they require \s-1CMAP\s0
files; they may or may not subset correctly; and they can not be used as the
base for synthetic fonts.
.Sp
See also PDF::Builder::Resource::CIDFont::CJKFont
.RE
.PP
\fIfont\fR
.IX Subsection "font"
.PP
.Vb 1
\&    $font = $pdf\->font($name, %opts)
.Ve
.Sp
.RS 4
A convenience function to add a font to the \s-1PDF\s0 without having to specify the
format. Returns the font object, to be used by PDF::Builder::Content.
.Sp
The font \f(CW$name\fR is either the name of one of the standard 14 fonts 
(\*(L"\s-1STANDARD FONTS\*(R"\s0 in PDF::Builder::Resource::Font::CoreFont), such as
Helvetica or the path to a font file.
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.
.RE
.PP
.Vb 5
\&    my $pdf = PDF::Builder\->new();
\&    my $font1 = $pdf\->font(\*(AqHelvetica\-Bold\*(Aq);
\&    my $font2 = $pdf\->font(\*(Aq/path/to/ComicSans.ttf\*(Aq);
\&    my $page = $pdf\->page();
\&    my $content = $page\->text();
\&
\&    $content\->position(1 * 72, 9 * 72);
\&    $content\->font($font1, 24);
\&    $content\->text(\*(AqHello, World!\*(Aq);
\&
\&    $content\->position(0, \-36);
\&    $content\->font($font2, 12);
\&    $content\->text(\*(AqThis is some sample text.\*(Aq);
\&
\&    $pdf\->saveas(\*(Aqsample.pdf\*(Aq);
.Ve
.Sp
.RS 4
The path can be omitted if the font file is in the current directory or one of
the directories returned by \f(CW\*(C`font_path\*(C'\fR.
.Sp
TrueType (ttf/otf), Adobe PostScript Type 1 (pfa/pfb), and Adobe Glyph Bitmap
Distribution Format (bdf) fonts are supported.
.Sp
The following options (\f(CW%opts\fR) are available:
.RE
.IP "format" 4
.IX Item "format"
The font format is normally detected automatically based on the file's
extension.  If you're using a font with an atypical extension, you can set
\&\f(CW\*(C`format\*(C'\fR to one of \f(CW\*(C`truetype\*(C'\fR (TrueType or OpenType), \f(CW\*(C`type1\*(C'\fR (PostScript
Type 1), or \f(CW\*(C`bitmap\*(C'\fR (Adobe Bitmap).
.IP "dokern" 4
.IX Item "dokern"
Kerning (automatic adjustment of space between pairs of characters) is enabled
by default if the font includes this information.  Set this option to false to
disable.
.IP "afm_file (PostScript Type 1 fonts only)" 4
.IX Item "afm_file (PostScript Type 1 fonts only)"
Specifies the location of the font metrics file.
.IP "pfm_file (PostScript Type 1 fonts only)" 4
.IX Item "pfm_file (PostScript Type 1 fonts only)"
Specifies the location of the printer font metrics file.  This option overrides
the encode option.
.IP "embed (TrueType fonts only)" 4
.IX Item "embed (TrueType fonts only)"
Fonts are embedded in the \s-1PDF\s0 by default, which is required to ensure that they
can be viewed properly on a device that doesn't have the font installed. Set
this option to false to prevent the font from being embedded.
.PP
\fIfont_path\fR
.IX Subsection "font_path"
.PP
.Vb 1
\&    @directories = PDF::Builder\->font_path()
.Ve
.Sp
.RS 4
Return the list of directories that will be searched (in order) in addition to
the current directory when you add a font to a \s-1PDF\s0 without including the full
path to the font file.
.RE
.PP
\fIadd_to_font_path, addFontDirs\fR
.IX Subsection "add_to_font_path, addFontDirs"
.PP
.Vb 1
\&    @directories = PDF::Builder::add_to_font_path(\*(Aq/my/fonts\*(Aq, \*(Aq/path/to/fonts\*(Aq, ...)
.Ve
.Sp
.RS 4
Adds one or more directories to the list of paths to be searched for font files.
.Sp
Returns the font search path.
.Sp
\&\fBAlternate name:\fR \f(CW\*(C`addFontDirs\*(C'\fR
.Sp
Prior to recent changes to \s-1PDF::API2,\s0 this method was \fBaddFontDirs()\fR. This 
method is still available, but may be deprecated some time in the future.
.RE
.PP
\fIset_font_path\fR
.IX Subsection "set_font_path"
.PP
.Vb 1
\&    @directories = PDF::Builder\->set_font_path(\*(Aq/my/fonts\*(Aq, \*(Aq/path/to/fonts\*(Aq);
.Ve
.Sp
.RS 4
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
reorder the list.
.Sp
Returns the font search path.
.RE
.PP
\fIsynfont, synthetic_font\fR
.IX Subsection "synfont, synthetic_font"
.PP
.Vb 1
\&    $font = $pdf\->synfont($basefont, %opts)
.Ve
.Sp
.RS 4
Returns a new synthetic font object. These are modifications to a core (or 
\&\s-1PS/T1\s0 or \s-1TTF/OTF\s0) font, where the font may be replaced by a Type1 or Type3 
PostScript font.
This does not appear to work with \s-1CJK\s0 fonts (created with \f(CW\*(C`cjkfont\*(C'\fR method).
For details, see \*(L"Synthetic Fonts\*(R" in PDF::Builder::Docs.
.Sp
See also PDF::Builder::Resource::Font::SynFont
.Sp
\&\fBAlternate name:\fR \f(CW\*(C`synthetic_font\*(C'\fR
.Sp
Prior to recent \s-1PDF::API2\s0 changes, the routine to create modified fonts was
\&\*(L"synfont\*(R". \s-1PDF::API2\s0 has renamed it to \*(L"synthetic_font\*(R", which I don't like,
but to maintain compatibility, \*(L"synthetic_font\*(R" is available as an alias.
.Sp
There are also some minor option differences (incompatibilities) 
discussed in \f(CW\*(C`SynFont\*(C'\fR, including the value of 'bold' between the two entry
points.
.RE
.PP
\fIunifont\fR
.IX Subsection "unifont"
.PP
.Vb 1
\&    $font = $pdf\->unifont(@fontspecs, %opts)
.Ve
.Sp
.RS 4
Returns a new uni-font object, based on the specified fonts and options.
.Sp
\&\fB\s-1BEWARE:\s0\fR This is not a true PDF-object, but a virtual/abstract font definition!
.Sp
See also PDF::Builder::Resource::UniFont.
.Sp
Valid options (\f(CW%opts\fR) are:
.RE
.IP "encode" 4
.IX Item "encode"
Changes the encoding of the font from its default.
.SS "Font Manager methods"
.IX Subsection "Font Manager methods"
The Font Manager is automatically initialized.
.PP
\fIfont_settings\fR
.IX Subsection "font_settings"
.PP
.Vb 1
\&    @list = $pdf\->font_settings()  # Get
\&
\&    $pdf\->font_settings(%info)  # Set
.Ve
.Sp
.RS 4
Change one or more default settings. 
See PDF::Builder::FontManager/font_settings for details.
.RE
.PP
\fIadd_font_path\fR
.IX Subsection "add_font_path"
.PP
.Vb 1
\&    $rc = $pdf\->add_font_path("a directory path", %opts)
.Ve
.Sp
.RS 4
Add a search path for Font Manager font entries.
See PDF::Builder::FontManager/add_font_path for details.
.RE
.PP
\fIadd_font\fR
.IX Subsection "add_font"
.PP
.Vb 1
\&    $rc = $pdf\->add_font(%info)
.Ve
.Sp
.RS 4
Add a font (face) definition to the Font Manager list.
See PDF::Builder::FontManager/add_font for details.
.RE
.PP
\fIget_font\fR
.IX Subsection "get_font"
.PP
.Vb 1
\&    @current = $pdf\->get_font()  # Get
\&
\&    $font = $pdf\->get_font(%info)  # Set
.Ve
.Sp
.RS 4
Retrieve a ready-to-use font, or find out what the current one is.
See PDF::Builder::FontManager/get_font for details.
.RE
.PP
\fIdump_font_tables\fR
.IX Subsection "dump_font_tables"
.PP
.Vb 1
\&    $pdf\->dump_font_tables()
.Ve
.Sp
.RS 4
Dump all known font information to \s-1STDOUT.\s0
See PDF::Builder::FontManager/dump_font_tables for details.
.RE
.SH "IMAGE METHODS"
.IX Header "IMAGE METHODS"
.SS "image"
.IX Subsection "image"
.Vb 1
\&    $object = $pdf\->image($file, %opts);
.Ve
.Sp
.RS 4
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:
.RE
.PP
.Vb 2
\&    my $pdf = PDF::Builder\->new();
\&    my $page = $pdf\->page();
\&
\&    my $image = $pdf\->image(\*(Aq/path/to/image.jpg\*(Aq);
\&    $page\->object($image, 100, 100);
\&
\&    $pdf\->save(\*(Aqsample.pdf\*(Aq);
.Ve
.Sp
.RS 4
\&\f(CW$file\fR may be either a file name, a filehandle, or a 
PDF::Builder::Resource::XObject::Image::GD object.
.Sp
\&\fBCaution:\fR Do not confuse this \f(CW\*(C`image\*(C'\fR ($pdf\->) with the image method 
found in the graphics (gfx) class ($gfx\->), used to actually \fIplace\fR a
read-in or decoded image on the page!
.Sp
See \*(L"image\*(R" in PDF::Builder::Content for details about placing images on a page
once they're imported.
.Sp
The image format is normally detected automatically based on the file's
extension (.gif, .png, .tif/.tiff, .jpg/.jpeg, .pnm/.pbm/.pgm/.ppm). If passed 
a filehandle, image formats \s-1GIF, JPEG, PNM,\s0 and \s-1PNG\s0 will be
detected based on the file's header. Unfortunately, at this time, other image
formats (\s-1TIFF\s0 and \s-1GD\s0) cannot be automatically detected. (\s-1TIFF\s0 \fIcould\fR be, 
except that \f(CW\*(C`image_tiff()\*(C'\fR cannot use a filehandle anyway as input when using 
the libtiff library, which is highly recommended.)
.Sp
If the file has an atypical extension or the filehandle is for a different kind
of image, you can set the \f(CW\*(C`format\*(C'\fR option to one of the supported types:
\&\f(CW\*(C`gif\*(C'\fR, \f(CW\*(C`jpeg\*(C'\fR, \f(CW\*(C`png\*(C'\fR, \f(CW\*(C`pnm\*(C'\fR, or \f(CW\*(C`tiff\*(C'\fR.
.Sp
\&\fBNote:\fR \s-1PNG\s0 images that include an alpha (transparency) channel go through a
relatively slow process of splitting the image into separate \s-1RGB\s0 and alpha
components as is required by images in PDFs. If you're having performance
issues, install Image::PNG::Libpng to speed this process up by
an order of magnitude; either module will be used automatically if available.
See the \f(CW\*(C`image_png\*(C'\fR method for details.
.Sp
\&\fBNote:\fR \s-1TIFF\s0 image processing is very slow if using the pure Perl decoder.
We highly recommend using the Graphics::TIFF library to improve performance.
See the \f(CW\*(C`image_tiff\*(C'\fR method for details.
.RE
.SS "image_jpeg"
.IX Subsection "image_jpeg"
.Vb 1
\&    $jpeg = $pdf\->image_jpeg($file, %opts)
.Ve
.Sp
.RS 4
Imports and returns a new \s-1JPEG\s0 image object. \f(CW$file\fR may be either a filename 
or a filehandle.
.Sp
See PDF::Builder::Resource::XObject::Image::JPEG for additional information
and \f(CW\*(C`examples/Content.pl\*(C'\fR for some examples of placing an image on a page.
.RE
.SS "image_tiff"
.IX Subsection "image_tiff"
.Vb 1
\&    $tiff = $pdf\->image_tiff($file, %opts)
.Ve
.Sp
.RS 4
Imports and returns a new \s-1TIFF\s0 image object. \f(CW$file\fR may be either a filename 
or a filehandle.
For details, see \*(L"\s-1TIFF\s0 Images\*(R" in PDF::Builder::Docs.
.Sp
See PDF::Builder::Resource::XObject::Image::TIFF and
PDF::Builder::Resource::XObject::Image::TIFF_GT for additional information
and \f(CW\*(C`examples/Content.pl\*(C'\fR
for some examples of placing an image on a page (\s-1JPEG,\s0 but the principle is
the same). 
There is an optional \s-1TIFF\s0 library (\s-1TIFF_GT\s0) described, that gives more
capability than the default one. However, note that \f(CW$file\fR can only be
a filename when using this library.
.RE
.PP
\fI\s-1LA_GT\s0\fR
.IX Subsection "LA_GT"
.PP
.Vb 1
\&    $rc = $pdf\->LA_GT()
.Ve
.Sp
.RS 4
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:
.RE
.PP
.Vb 5
\&    if ($pdf\->LA_GT() {
\&        # is installed and usable
\&    } else {
\&        # not available. you will be running the old, pure PERL code
\&    }
.Ve
.SS "image_pnm"
.IX Subsection "image_pnm"
.Vb 1
\&    $pnm = $pdf\->image_pnm($file, %opts)
.Ve
.Sp
.RS 4
Imports and returns a new \s-1PNM\s0 image object. \f(CW$file\fR may be either a filename 
or a filehandle.
.Sp
See PDF::Builder::Resource::XObject::Image::PNM for additional information
and \f(CW\*(C`examples/Content.pl\*(C'\fR for some examples of placing an image on a page
(\s-1JPEG,\s0 but the principle is the same).
.RE
.SS "image_png"
.IX Subsection "image_png"
.Vb 1
\&    $png = $pdf\->image_png($file, %opts)
.Ve
.Sp
.RS 4
Imports and returns a new \s-1PNG\s0 image object. \f(CW$file\fR may be either 
a filename or a filehandle.
For details, see \*(L"\s-1PNG\s0 Images\*(R" in PDF::Builder::Docs.
.Sp
See PDF::Builder::Resource::XObject::Image::PNG and
PDF::Builder::Resource::XObject::Image::PNG_IPL for additional information
and \f(CW\*(C`examples/Content.pl\*(C'\fR
for some examples of placing an image on a page (\s-1JPEG,\s0 but the principle is
the same).
.Sp
There is an optional \s-1PNG\s0 library (\s-1PNG_IPL\s0) described, that gives more
capability than the default one. However, note that \f(CW$file\fR can only be
a filename when using this library.
.RE
.PP
\fI\s-1LA_IPL\s0\fR
.IX Subsection "LA_IPL"
.PP
.Vb 1
\&    $rc = $pdf\->LA_IPL()
.Ve
.Sp
.RS 4
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:
.RE
.PP
.Vb 5
\&    if ($pdf\->LA_IPL() {
\&        # is installed and usable
\&    } else {
\&        # not available. don\*(Aqt use 16bps or interlaced PNG image files
\&    }
.Ve
.SS "image_gif"
.IX Subsection "image_gif"
.Vb 1
\&    $gif = $pdf\->image_gif($file, %opts)
.Ve
.Sp
.RS 4
Imports and returns a new \s-1GIF\s0 image object. \f(CW$file\fR may be either a filename 
or a filehandle.
.Sp
See PDF::Builder::Resource::XObject::Image::GIF for additional information
and \f(CW\*(C`examples/Content.pl\*(C'\fR for some examples of placing an image on a page 
(\s-1JPEG,\s0 but the principle is the same).
.RE
.SS "image_gd"
.IX Subsection "image_gd"
.Vb 1
\&    $gdf = $pdf\->image_gd($gd_object, %opts)
.Ve
.Sp
.RS 4
Imports and returns a new image object from Image::GD.
.Sp
See PDF::Builder::Resource::XObject::Image::GD for additional information
and \f(CW\*(C`examples/Content.pl\*(C'\fR for some examples of placing an image on a page 
(\s-1JPEG,\s0 but the principle is the same).
.RE
.SH "COLORSPACE METHODS"
.IX Header "COLORSPACE METHODS"
.SS "colorspace"
.IX Subsection "colorspace"
.Vb 1
\&    $colorspace = $pdf\->colorspace($type, @arguments)
.Ve
.Sp
.RS 4
Colorspaces can be added to a \s-1PDF\s0 to either specifically control the output
color on a particular device (spot colors, device colors) or to save space by
limiting the available colors to a defined color palette (web-safe palette, \s-1ACT\s0
file).
.Sp
Once added to the \s-1PDF,\s0 they can be used in place of regular hex codes or named
colors:
.RE
.PP
.Vb 3
\&    my $pdf = PDF::Builder\->new();
\&    my $page = $pdf\->page();
\&    my $content = $page\->graphics();
\&
\&    # Add colorspaces for a spot color and the web\-safe color palette
\&    my $spot = $pdf\->colorspace(\*(Aqspot\*(Aq, \*(AqPANTONE Red 032 C\*(Aq, \*(Aq#EF3340\*(Aq);
\&    my $web = $pdf\->colorspace(\*(Aqweb\*(Aq);
\&
\&    # Fill using the spot color with 100% coverage
\&    $content\->fill_color($spot, 1.0);
\&
\&    # Stroke using the first color of the web\-safe palette
\&    $content\->stroke_color($web, 0);
\&
\&    # Add a rectangle to the page
\&    $content\->rectangle(100, 100, 200, 200);
\&    $content\->paint();
\&
\&    $pdf\->save(\*(Aqsample.pdf\*(Aq);
.Ve
.Sp
.RS 4
The following types of colorspaces are supported
.RE
.IP "spot" 4
.IX Item "spot"
Spot colors are used to instruct a device (usually a printer) to use or emulate
a particular ink color (\f(CW$tint\fR) for parts of the document. An \f(CW$alt_color\fR
is provided for devices (e.g. \s-1PDF\s0 viewers) that don't know how to produce the
named color. It can either be an approximation of the color in \s-1RGB, CMYK,\s0 or
\&\s-1HSV\s0 formats, or a wildly different color (e.g. 100% magenta, \f(CW%0F00\fR) to make
it clear if the spot color isn't being used as expected.
.PP
.Vb 1
\&    my $spot = $pdf\->colorspace(\*(Aqspot\*(Aq, $tint, $alt_color);
.Ve
.IP "web" 4
.IX Item "web"
The web-safe color palette is a historical collection of colors that was used
when many display devices only supported 256 colors.
.PP
.Vb 1
\&    my $web = $pdf\->colorspace(\*(Aqweb\*(Aq);
.Ve
.IP "act" 4
.IX Item "act"
An Adobe Color Table (\s-1ACT\s0) file provides a custom palette of colors that can be
referenced by \s-1PDF\s0 graphics and text drawing commands.
.PP
.Vb 1
\&    my $act = $pdf\->colorspace(\*(Aqact\*(Aq, $filename);
.Ve
.IP "device" 4
.IX 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).
.PP
.Vb 1
\&    my $devicen = $pdf\->colorspace(\*(Aqdevice\*(Aq, @colorspaces);
.Ve
.Sp
.RS 4
Device colorspaces are also needed if you want to blend spot colors:
.RE
.PP
.Vb 3
\&    my $pdf = PDF::Builder\->new();
\&    my $page = $pdf\->page();
\&    my $content = $page\->graphics();
\&
\&    # Create a two\-color device colorspace
\&    my $yellow = $pdf\->colorspace(\*(Aqspot\*(Aq, \*(AqYellow\*(Aq, \*(Aq%00F0\*(Aq);
\&    my $spot = $pdf\->colorspace(\*(Aqspot\*(Aq, \*(AqPANTONE Red 032 C\*(Aq, \*(Aq#EF3340\*(Aq);
\&    my $device = $pdf\->colorspace(\*(Aqdevice\*(Aq, $yellow, $spot);
\&
\&    # Fill using a blend of 25% yellow and 75% spot color
\&    $content\->fill_color($device, 0.25, 0.75);
\&
\&    # Stroke using 100% spot color
\&    $content\->stroke_color($device, 0, 1);
\&
\&    # Add a rectangle to the page
\&    $content\->rectangle(100, 100, 200, 200);
\&    $content\->paint();
\&
\&    $pdf\->save(\*(Aqsample.pdf\*(Aq);
.Ve
.SS "colorspace_act"
.IX Subsection "colorspace_act"
.Vb 1
\&    $cs = $pdf\->colorspace_act($file)
.Ve
.Sp
.RS 4
Returns a new colorspace object based on an Adobe Color Table file.
.Sp
See PDF::Builder::Resource::ColorSpace::Indexed::ACTFile for a
reference to the file format's specification.
.RE
.SS "colorspace_web"
.IX Subsection "colorspace_web"
.Vb 1
\&    $cs = $pdf\->colorspace_web()
.Ve
.Sp
.RS 4
Returns a new colorspace-object based on the \*(L"web-safe\*(R" color palette.
.RE
.SS "colorspace_hue"
.IX Subsection "colorspace_hue"
.Vb 1
\&    $cs = $pdf\->colorspace_hue()
.Ve
.Sp
.RS 4
Returns a new colorspace-object based on the hue color palette.
.Sp
See PDF::Builder::Resource::ColorSpace::Indexed::Hue for an explanation.
.RE
.SS "colorspace_separation"
.IX Subsection "colorspace_separation"
.Vb 1
\&    $cs = $pdf\->colorspace_separation($tint, $color)
.Ve
.Sp
.RS 4
Returns a new separation colorspace object based on the parameters.
.Sp
\&\fI\f(CI$tint\fI\fR can be any valid ink identifier, including but not limited
to: 'Cyan', 'Magenta', 'Yellow', 'Black', 'Red', 'Green', 'Blue' or
\&'Orange'.
.Sp
\&\fI\f(CI$color\fI\fR must be a valid color specification limited to: '#rrggbb',
\&'!hhssvv', '%ccmmyykk' or a \*(L"named color\*(R" (rgb).
.Sp
The colorspace model will automatically be chosen based on the
specified color.
.RE
.SS "colorspace_devicen"
.IX Subsection "colorspace_devicen"
.Vb 1
\&    $cs = $pdf\->colorspace_devicen(\e@tintCSx, $samples)
\&
\&    $cs = $pdf\->colorspace_devicen(\e@tintCSx)
.Ve
.Sp
.RS 4
Returns a new DeviceN colorspace object based on the parameters.
.Sp
\&\fBExample:\fR
.RE
.PP
.Vb 4
\&    $cy = $pdf\->colorspace_separation(\*(AqCyan\*(Aq,    \*(Aq%f000\*(Aq);
\&    $ma = $pdf\->colorspace_separation(\*(AqMagenta\*(Aq, \*(Aq%0f00\*(Aq);
\&    $ye = $pdf\->colorspace_separation(\*(AqYellow\*(Aq,  \*(Aq%00f0\*(Aq);
\&    $bk = $pdf\->colorspace_separation(\*(AqBlack\*(Aq,   \*(Aq%000f\*(Aq);
\&
\&    $pms023 = $pdf\->colorspace_separation(\*(AqPANTONE 032CV\*(Aq, \*(Aq%0ff0\*(Aq);
\&
\&    $dncs = $pdf\->colorspace_devicen( [ $cy,$ma,$ye,$bk, $pms023 ] );
.Ve
.Sp
.RS 4
The colorspace model will automatically be chosen based on the first
colorspace specified.
.RE
.SH "BARCODE METHODS"
.IX Header "BARCODE METHODS"
These are glue routines to the actual barcode rendering routines found
elsewhere.
.SS "xo_* Bar Code routines"
.IX Subsection "xo_* Bar Code routines"
.Vb 1
\&    $bc = $pdf\->xo_codabar(%opts)
\&
\&    $bc = $pdf\->xo_code128(%opts)
\&
\&    $bc = $pdf\->xo_2of5int(%opts)
\&
\&    $bc = $pdf\->xo_3of9(%opts)
\&
\&    $bc = $pdf\->xo_ean13(%opts)
.Ve
.Sp
.RS 4
Creates the specified barcode object as a form XObject.
.RE
.SH "OTHER METHODS"
.IX Header "OTHER METHODS"
.SS "xo_form"
.IX Subsection "xo_form"
.Vb 1
\&    $xo = $pdf\->xo_form()
.Ve
.Sp
.RS 4
Returns a new form XObject.
.RE
.SS "egstate"
.IX Subsection "egstate"
.Vb 1
\&    $egs = $pdf\->egstate()
.Ve
.Sp
.RS 4
Returns a new extended graphics state object, as described
in PDF::Builder::Resource::ExtGState.
.RE
.SS "pattern"
.IX Subsection "pattern"
.Vb 1
\&    $obj = $pdf\->pattern(%opts)
.Ve
.Sp
.RS 4
Returns a new pattern object.
.RE
.SS "shading"
.IX Subsection "shading"
.Vb 1
\&    $obj = $pdf\->shading(%opts)
.Ve
.Sp
.RS 4
Returns a new shading object.
.RE
.SS "named_destination"
.IX Subsection "named_destination"
.Vb 1
\&    $ndest = $pdf\->named_destination()
.Ve
.Sp
.RS 4
Returns a new or existing named destination object.
.RE