Help language development. Donate to The Perl Foundation

PDF::Document cpan:TBROWDER last updated on 2021-02-12

docs/details.pod
=begin pod

=head1 Some details

=head2 Fonts

In this module we have three classes representing a font:

=head3 1. C<$rawfont>

An instance of a C<PDF::Lite> I<prototype> font. It is what the text
blocks require for rendering text.

=head3 2. C<BaseFont>

A class that holds the C<$rawfont> object as well as an instance of
its C<Font::AFM> object with the C<$rawfont>'s metrics.

=head3 3. C<DocFont>

A class representing the user-level font which marries the C<$rawfont>
and the desired size.  It also has methods from the C<Font::AFM>
object. Those methods that return metrics of the C<$rawfont> are
scaled to produce the exact values for the font at its size.

=head2 Document generation methods

There are three planned modes of document generation:

=head3 1. Text to PDF

This requires users to write a Raku program and use methods to write
their document. This method is being developed now and approximates
the original PostScript methods. The main purpose of this method being
first is to get the PDF methods understood, simplified, and integrated
into the main class for managing a document, the C<Doc> class.

=head3 2. Text to PDF (with text input)

This will be the first text-input method to be implemented, and it is
in very rudimentary form. It takes a plain text document and, line by
line, renders it into PDF. It is suitable for quickly putting text
files into printed form for such uses as code printouts.  It has
features such as:

=item1 line numbering
=item1 line wrapping
=item1 page numbering
=item1 bottom or top margin file naming

=head3 3. Pod to PDF (with Pod text file input)

Using Pod markup as input, the rendered PDF will look more like a
polished, typeset document with many ways to style and format the
finished product.

=head2 Font factory

As an aid to the user of this module, there is a C<FontFactory> class
that can be used to keep track of the fonts used and avoid duplicate
font generation instances.

The first requirement is to enforce strict naming rules. We recognize
two lists of names for the base fonts available.  The first list
contains the names as keys in the C<%CoreFonts> hash. The second is
the names of the aliases of those fonts which are at most three
characters long and are the keys of the C<%CoreFontAliases> hash.

Final C<DocFont> keys are formed from the alias of the desired font
followed by the integer of the font size. So a Times-Roman font face
set at 14 points would have a key of C<t14>. If the user needs a
fractional font size, the size would have the letter C<d> separating
the integral and fractional parts. For example, a Helvetica font face
set at 12.4 pts would have a key of C<h12d4>. The following code shows
initialization of a PDF document:

=begin code :lang<raku>
use PDF::Lite;
use Font::AFM;
use PDF::Document;

my $pdf = PDF::Lite.new;
my $pdf.media-box = "Letter";
my $ff = FontFactory.new: :$pdf;

# use a 12 point Times-Roman font
my $t12 = $ff.set-font<t12>;
# get another of the same
my $T12 = $ff.set-font<T12>;
# case is not significant, so the same font
# is requested, so the factory quietly
# returns a copy of the same instance.
=end code

=head1 PDF methods and their aliases ("codes")

Adobe has short names for many of their methods. The
following tables show many of those exposed by the C<Doc> class.

=begin table :caption<Color Operators>
Method | Alias | Description | Default | Example Setter
=====+======
Color operators
SetStrokeGray + G
SetFillGray + g
SetStrokeRGB + RG
SetFillRGB + rg
=end table

=begin table :caption<Graphics State>
Method | Alias | Description | Default | Example Setter
=====+======
TextLeading + Tl + text line height
SetLineWidth + w
SetLineCap + J
SetLineJoin + j
Save + q
Restore + Q
=end table

=begin table :caption<Text Operators>
Method | Alias | Description | Default | Example Setter
=====+======
BeginText + BT
EndText + ET
TextMove + Td
TextMoveSet + TD
TextNextLine + T*
ShowText + Tj
MoveShowText + '
MoveSetShowText + "
=end table

=begin table :caption<Path Construction>
Method | Alias | Description | Default | Example Setter
MoveTo + m
LineTo + l
CurveTo + c
ClosePath + h
Rectangle + re
Fill + f
Stroke + S
Clip + W
=end table

=end pod