#=======================================================================
# ____ ____ _____ _ ____ ___ ____
# | _ \| _ \| ___| _ _ / \ | _ \_ _| |___ \
# | |_) | | | | |_ (_) (_) / _ \ | |_) | | __) |
# | __/| |_| | _| _ _ / ___ \| __/| | / __/
# |_| |____/|_| (_) (_) /_/ \_\_| |___| |_____|
#
# A Perl Module Chain to faciliate the Creation and Modification
# of High-Quality "Portable Document Format (PDF)" Files.
#
# Copyright 1999-2005 Alfred Reibenschuh <areibens@cpan.org>.
#
#=======================================================================
#
# PERMISSION TO USE, COPY, MODIFY, AND DISTRIBUTE THIS FILE FOR
# ANY PURPOSE WITHOUT FEE IS HEREBY GRANTED, PROVIDED THAT THE ABOVE
# COPYRIGHT NOTICE AND THIS PERMISSION NOTICE APPEAR IN ALL COPIES.
#
# THIS FILE IS PROVIDED ``AS IS´´ AND ANY EXPRESSED OR IMPLIED
# WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
# MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
# IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
# USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
# OF THE USE OF THIS FILE, EVEN IF ADVISED OF THE POSSIBILITY OF
# SUCH DAMAGE.
#
# $Id: HOWTO.pod,v 2.0 2005/11/16 02:16:00 areibens Exp $
#
#=======================================================================
=head1 NAME
PDF::API2::HOWTO - A basic set of guidelines to use PDF::API2.
=head1 THEORY
=head2 Coordinates and Units
=head3 Transformations
=head2 Colors
=head3 R-G-B
=head3 C-M-Y-K
=head3 H-S-V
=head1 THE BASIC DOCUMENT
=head2 A Hello World.
$pdf = PDF::API2->new;
#
$fnt = $pdf->corefont('Helvetica-Bold');
#
$page = $pdf->page;
$page->mediabox('A4');
#
$gfx = $page->gfx;
$gfx->textlabel(200,700,$fnt,20,'Hello World !');
#
$pdf->saveas('/this/new/document.pdf');
$pdf->end;
=head1 FONTS AND TYPESETTING
=head1 INTEROPERABLILITIES
=head2 Adobe Reader & Acrobat (Windows)
The Acrobat/Adobe Reader will open and print files created with PDF::API2,
but sometimes Acrobat (Full Product) will be unable to edit/update them.
=head3 Adobe Reader (Linux)
Since the MS Core Fonts may not be available via X11, those corefonts may
either look/print odd or may be entirely missing (dependent on installation).
=head2 Macromedia Freehand (Windows)
Any version of Freehand is unable to open files either created or updated by PDF::API2.
Redestilled files do work, but embedded fonts are missing, which is probably bug in
Freehand's pdf engine.
=head2 Ghostscript
Versions before 7.03 had problems reading PDF::API2 created pdfs.
PDF::API2 versions prior to 0.30_7x embedded Type1 Fonts not
digestible by gs.
=head3 Redmon / FreePDF (Windows)
Since these are based on ghostscript, they can be used to redistill
pdfs from and to PDF::API2.
=head2 Xpdf
Xpdf and tools need to be compiled with both freetype2 and libT1.
pdftops produces problematic ps-files if the pdf-file created via PDF::API2
contains embedded CFF (aka. Opentype) fonts.
=head2 pdftk
pdftk is a nice tool to pre/post-process pdf-files.
Version 0.91 does not support big-endian unicode metadata as
PDF::API2 does use as default.
=head2 Jaws PDF
Some versions of this software (5D PDF Creator) create pdfs not consumable
by PDF::API2 (if you just need a pdf-printer driver use FreePDF).
=head2 Omnipage
PDF::API2 versions prior to 0.40_17 had a bug that screws up omnipages
unfortunate image name-keys and lzw-encoded page descriptions.
=head2 Open Office
PDF::API2 versions prior to 0.40_xx had a bug that screws up colorspaces
of indexed images during import/save.
=cut
__END__
=head1 CHANGES
$Log: HOWTO.pod,v $
Revision 2.0 2005/11/16 02:16:00 areibens
revision workaround for SF cvs import not to screw up CPAN
Revision 1.2 2005/11/16 01:27:48 areibens
genesis2
Revision 1.1 2005/11/16 01:19:24 areibens
genesis
Revision 1.6 2005/03/14 22:01:05 fredo
upd 2005
Revision 1.5 2004/06/07 19:44:12 fredo
cleaned out cr+lf for lf
Revision 1.4 2004/02/22 23:45:25 fredo
added pdftk tool comment
Revision 1.3 2004/02/19 00:37:55 fredo
added interoperability section
Revision 1.2 2004/02/13 10:56:31 fredo
added hello world example
Revision 1.1 2003/12/08 22:42:19 Administrator
rudimentary skeleton
=cut