Руководство по использованию PDF::API2 (Perl) для начинающих

1. Название и версия
   
2. Используемая терминология
   
3. Руководство
   
4. Преимущества формата PDF
   
5. Основные принципы работы с PDF-документами через PDF::API2
   
6. Создание PDF-документа
   
7. Открытие существующего документа PDF для редактирования, импортирование данных
   
8. Работа с текстовыми данными
   
   1. Управление шрифтами при создании PDF-документа
      
   2. Работа с цветом
      
   3. Добавление текста
9. Графические данные в PDF - документе
   
   1. Вставка графических изображений в PDF - документ
      
   2. Импортирование PDF - документов
      
   3. Создание графических изображений средствами PDF::API2
10. Вывод PDF-документа пользователю, сохранение документа
11. Приложение к руководству
    
12. Примеры кода
    
13. Полезные ссылки

Название и версия

Данное руководство создавалось для PDF::API2 версии 20020226.221611 . Соответственно, описываемые методы в других версиях модуля могут работать не корректно или не работать совсем. Данное руководство не претендует на полноту и точность изложения описания работы с модулем PDF::API2 для Perl. Скорее, оно является неким обзорным материалом, который предназначен помочь программистам Perl в практической работе, при создании PDF-документов.

Когда у меня возникла необходимость в предоставлении пользователю документов в формате PDF, и использовании модуля PDF::API2, обнаружилось, что русскоязычный интернет содержит крайне мало информации на данную тему. Возможно, составленное руководство сможет частично восполнить этот пробел. Кроме того, в тексте приводятся ссылки на полезную информацию, которой мне не хватало для решения поставленной задачи.

Используемая терминология

API (Application Programming Interface) - "Интерфейс прикладного программирования" - набор ("библиотека") стандартных процедур, программных прерываний, вызовов, форматов данных и других средств, которые должны использовать прикладные программы для реализации своих функций.

PDF (Portable Document Format) - метафайловый формат, предложенный фирмой Adobe для графических файлов (векторных и растровых), содержащих иллюстрации и текст с большим набором шрифтов и гипертекстовыми ссылками с целью передачи их по сети в сжатом виде. Версия PDF3 позволяет сохранять все установки для выводного устройства, записанные в файле формата PostScript. Восстановление формата PDF из формата PostScript производится с использованием опции Exchange. Этим обеспечивается оперативная возможность передачи графических файлов по электронной почте. PDF позволяет не заботиться о наличии необходимых шрифтов у адресата, поскольку они подгружаются непосредственно в файл. Особенностью формата является также возможность использования различных способов сжатия для разных типов объектов. Для работы с форматом PDF фирма Adobe выпустила пакет программ Acrobat. Входящий в этот пакет Acrobat Distiller переводит в PDF PostScript-файлы, Acrobat Exchange позволяет их редактировать (устанавливать внутренние ссылки, ссылки на внешние звуковые и видеофайлы, Web-ссылки и т.д.). Существует и ряд других графических редакторов, позволяющих создавать файлы в формате PDF.

Бесплатно распространяемую утилиту Adobe Acrobat Reader, которая позволяет читать документы и распечатывать их на принтере (однако не дает возможности создавать или изменять их) можно получить по адресу: www. adobe.com/acrobat. Файлы PDF используют расширение *.pdf. Версия формата PDF/A прошла сертификацию стандартом архивирования ISO [584-586, 959, 1640].

Источник: (словари Яндекса)

Руководство

1. Преимущества формата PDF

Основные преимущества:

• Кроссплатформенность. Просмотр PDF-файлов возможен практически на всех самых распространенных платформах, с помощью бесплатной программы Acrobat Reader.
  
• Независимость от наличия (отсутствия) шрифтов на компьютере пользователя. Шрифты, как и другие данные, при создании встраиваются в PDF-документ.
  
• Независимость от настроек принтера.
  
• Полное соответствие внешнего вида PDF-документа на экране компьютера и распечатанного на принтере. Данное преимущество имеет особенно большое значение при печати финансовых и юридических документов.
  
• Небольшой размер PDF-файлов.
  
• Криптозащита, шифрование файлов, управление доступом. PDF-формат позволяет устанавливать ограничения на просмотр, редактирование и печать документа. Возможна защита этих действий паролем.

Еще одно преимущество, актуальное при использовании PDF-документов в интернете:

• Простота генерации многостраничных документов (данная возможность с трудом реализуется для обычных html-документов, и поддерживается ограниченным числом браузеров)

2 Основные принципы работы с PDF-документами через PDF::API2

Модуль PDF::API2 не дает возможностей для редактирования существующих pdf-документов, с поиском в них текста, рисунков и их последующей заменой. В основном, он предназначен для создания новых документов.

Основные типы объектов, которые могут использоваться на странице PDF-документа: контуры (path object), текст (text object) и растр (image object). Для описания объектов используется язык, по функциям аналогичный PostScript.

Система координат является двумерной, и имеет начало в левом нижнем углу листа. Ось X направлена вправо, ось Y - вверх. Единицей измерения является 1/72 дюйма. Геометрическая плоскость, на которой расположена система координат - бесконечна. Ограничение документа происходит с помощью указания физических границ страницы (MediaBox). Также можно задать страницам документа границы видимой области (CropBox).

3 Создание документа PDF

Подключаем модуль PDF::API2

3: use PDF::API2;

Создаем новый объект PDF::API2 - документ в формате PDF. Каждый созданный объект позволяет работать только с одним документом

10: my $pdf = PDF::API2->new;

При вызове $pdf->page($page) происходит создание новой страницы PDF-документа. По умолчанию, новая страница добавляется в конец документа. Для добавления страницы в середину документа или в начало, нужно указать номер создаваемой страницы.
Если указать в качестве номера "-1" - страница будет вставлена перед последней страницей. Если $page = 1; вставка будет производиться в начало документа, перед первой страницей.

11: my $page = $pdf->page();

MediaBox определяет границы физической страницы. CropBox - границы видимой области. Если параметры CropBox не указаны, он принимается равным MediaBox. CropBox лучше задавать с помощью 4х параметров: $page->cropbox($llx, $lly, $urx, $ury);. С помощью CropBox удобно задавать поля страницы.

12: $page->mediabox($w,$h);
13: #$page->bleedbox($w,$h);
14: #$page->cropbox($w,$h);
15: #$page->artbox($w,$h);

4 Открытие существующего документа PDF для редактирования,
импортирование данных

Иногда возникает необходимость предоставить клиенту заполненную квитанцию, бланк и т.д. В подобных ситуациях будет проще не создавать квитанцию с нуля, а просто открыть готовый документ и добавить в него нужную информацию.

$pdf = PDF::API2->YzyX($FILE_NAME); - открывает существующий PDF-документ для редактирования. Стоит отметить, что PDF::API2 не предоставляет возможность отредактировать содержащиеся в документе данные. Можно только дополнить файл новой информацией.
$page = $pdf->openpage($page_number); - создает объект для редактирования страницы с номером $page_number открытого ранее документа.

8: my $pdf = PDF::API2->YzyX("helloworld.pdf");
9: my $page = $pdf->openpage(1);

Можно также создать новый документ и импортировать в него страницу(ы) из созданного ранее документа.

$pageobj = $pdf->importpage($sourcepdf, $sourceindex, $targetindex) - импортирует страницу с номером $sourceindex из документа $sourcepdf, на место страницы с номером $targetindex в текущий документ.

Если $sourceindex или $targetindex принимают значение "-1" или "0" - будут производиться операции
с последней страницей документа.

5: my $import_pdf = PDF::API2->YzyX("helloworld.pdf");
6: my $pdf = PDF::API2->new;
7:
8: my $page = $pdf->importpage($import_pdf, 1, 1);

Еще один вариант импортирования страниц из строннего PDF-документа описан в п.6.2. данного руководства.

5 Работа с текстовыми данными

5.1 Управление шрифтами при создании PDF-документа

Как уже было сказано, все объявленные (даже если шрифт не использовался) при создании PDF-документа шрифты, во время сохранения будут подгружены непосредственно в файл.

14: my $font_ps = $pdf->psfont("timesbd8.pfb","timesbd8.afm");
15: # my $font_tt = $pdf->ttfont(`verdana.ttf`);
16: # my $font_cf = $pdf->corefont(`Helvetica`);

PDF::API2 позволяет работать со шрифтами типа:

• corefont - набор основных шрифтов, которые Adobe позволяет разработчикам
  использовать бесплатно.
  В эту группу также входят некоторые шрифты от компании Microsoft. Шрифты предоставляются модулем
  PDF::API2, и не требуют дополнительной установки.
  
• psfont - шрифты Post Script.
  Дополнительная информация (Источник: http://www.paratype.ru):
  Язык программирования PostScript был разработан фирмой Adobe Systems для описания сложных графические объектов. За неимением реальных альтернатив в 80-90-х годах язык PostScript широко использовался при подготовке печатных изданий, и его интерпретаторы были встроены во многие принтеры и устройства отображения графической информации. Хотя этот формат и основывается на использовании языка PostScript для описания печатной страницы документа, он не требует для печати обязательного применения принтеров семейства PostScript. При использовании принтеров PostScript шрифт просто загружается в память принтера, а применение обычных принтеров требует выполнения операции растрирования шрифта (то есть преобразования в набор отдельных точек) и последующей посылки на принтер растрового образа страницы.
  
  Наиболее известная и распространенная сегодня реализация языка PostScript - формат документов PDF, поддерживаемый продуктами серии Acrobat. Почти что все, что может быть сделано в PostScript может быть реализовано в PDF.
  
  Когда мы говорим шрифты PostScript, мы обычно имеем ввиду шрифты PostScript Type 1. Это общепринятый стандарт для цифровых шрифтов (ISO 9541). Шрифт формата Type 1 - специальная форма программы PostScript и особый формат файла, который ориентирован на описание шрифта. В языке PostScript существуют и другие стандарты описания шрифтов - Type 0, Type 2, Type 3, ..., однако сейчас они почти не используются или используются для специальных целей. В последние годы язык PostScript был расширен, чтобы обеспечить поддержку шрифтовых возможностей стандартов TrueType и OpenType. Новые устройства с языком Adobe PostScript сейчас поддерживают все 3 шрифтовых стандарта.
  
  Шрифт PostScript состоит из нескольких файлов: Шрифт PostScript для Windows может состоять из 2-х, 3-х или 4-х файлов. Набор из 3 файлов состоит из файла с расширением PFB (Print Font Binary), который содержит информацию о контурах; файла с расширением AFM (Adobe Font Metrics), содержащего информацию о ширинах символов и кернинге; INF файла, содержащего дополнительную информацию, которая требуется для инсталляции. В процессе инсталляции Windows генерирует PFM файл (Print Font Metrics), в основе которого лежит информация из AFM и INF файлов. Далее используется только PFB и PFM файлы. Некоторые производители генерируют PFM файлы самостоятельно и поставляют своим клиентам только два этих файла. Этого достаточно для нормального использования. Некоторые так же добавляют AFM файлы, а некоторые поставляют все 4 файла.
  
  Шрифт PostScript для Macintosh состоит из файла-чемодана (suitcase) и принтерного файла. Если вы купили гарнитуру, а не одно начертание, то у вас может быть один чемодан на всю семью и несколько принтерных файлов, по одному для каждого начертания - Нормального (Regular), Курсивного (Italic), Жирного (Bold) и Жирного Курсивного (Bold Italic). Другой подход предполагает комплектацию каждого начертания отдельным файлом-чемоданом. В этом случае семья из 4 шрифтов будет состоять из 8 файлов. Гарнитуры могут поставляться с "совмещенными начертаниями" или с "разделенными начертаниями". Одна гарнитура может содержать до 4 начертаний, но иногда она содержит только Нормальное и Жирное, или Нормальное и Курсивное начертание.
  
• ttfont - шрифты TrueType.
  Дополнительная информация (Источник: http://www.paratype.ru):
  Шрифты TrueType были придуманы специалистами компании Apple Computer в ходе конкурентной борьбы с технологией PostScript. Позднее лицензия на шрифты TrueType была приобретена фирмой Microsoft с целью включения их в свои операционные системы. В отличие от шрифтов PostScript, шрифты TrueType не используют специального языка для описания формата печатной страницы. Шрифты TrueType могут содержать до 65000 символов, расположенных в порядке, определенном стандартом Unicode. В действительности, не все шрифты содержат расширенные наборы символов, большинство европейских изготовителей ограничиваются стандартной комплектацией западноевропейской кодировки (т.н. Latin 1).
  
  Шрифт в формате TrueType - это один файл. В системе Windows он имеет расширение TTF, а в Mac OS это файл-чемодан (suitcase) с ресурсом SFNT. В Mac OS X встроен шрифтовой процессор нового поколения, который кроме шрифтов с ресурсом SFNT, поддерживает и файлы TTF, созданные для Windows. Так что файл с расширением TTF можно использовать на обеих операционных платформах.

Особенности $pdf->ttfont
Не смотря на то, что шрифты по-умолчанию подгружаются в файл документа, это условие не является обязательным.

$font = $pdf->ttfont($ttfile, $lazy);

При стандартном использовании переменная $lazy, как правило, опускается. Однако, если установить ей значение, равное "1" - указанный в $pdf->ttfont($ttfile, $lazy) шрифт не будет встроен в pdf-документ.

Преимущества данного подхода:

• т.к. шрифт не встраивается, соответственно размер файла конечного PDF-документа уменьшается
  
• программисту нет необходимости беспокоиться о поиске (покупке) необходимых шрифтов, запоминании их месторасположения, названий и т.п. Достаточно использовать стандартные обозначения шрифтов:
  
  • arial arialbold arialitalic arialbolditalic arialblack
    
  • comicsansms comicsansmsbold
    
  • couriernew couriernewbold couriernewitalic couriernewbolditalic
    
  • tahoma tahomabold
    
  • timesnewroman timesnewromanbold timesnewromanitalic timesnewromanbolditalic
    
  • verdana verdanabold verdanaitalic verdanabolditalic
    
  • wingdings
  
  
• Дополнительное удобство для пользователей Acrobat Reader версии 5 и старше: возможен поиск и замена шрифтов.

Недостатки:

• Созданный подобным образом документ, смогут прочитать только пользователи Windows OC.
  
• Возможно, что ОС клиента не поддерживает русский (или любой другой, отличный от английского) язык и отображение русскоязычных документов будет происходит в искаженном виде.

5.2 Работа с цветом

(Вспомогательный источник: http://search.cpan.org/~areibens/PDF-API… PDF/API2/Lite.pm)

Задаем цвет текста. По умолчанию используется черный.

22: $txt->fillcolor(`blue`);

PDF::API2 позволяет использовать для определения цвета шрифта различные форматы. Самый простой вариант - указать наименование цвета.

Возможно использование следующих наименований:
aliceblue, antiquewhite, aqua, aquamarine, azure, beige, bisque, black, blanchedalmond,
blue, blueviolet, brown, burlywood, cadetblue, chartreuse, chocolate, coral, cornflowerblue,
cornsilk, crimson, cyan, darkblue, darkcyan, darkgoldenrod, darkgray, darkgreen, darkgrey,
darkkhaki, darkmagenta, darkolivegreen, darkorange, darkorchid, darkred, darksalmon,
darkseagreen, darkslateblue, darkslategray, darkslategrey, darkturquoise, darkviolet,
deeppink, deepskyblue, dimgray, dimgrey, dodgerblue, firebrick, floralwhite, forestgreen,
fuchsia, gainsboro, ghostwhite, gold, goldenrod, gray, grey, green, greenyellow, honeydew,
hotpink, indianred, indigo, ivory, khaki, lavender, lavenderblush, lawngreen, lemonchiffon,
lightblue, lightcoral, lightcyan, lightgoldenrodyellow, lightgray, lightgreen, lightgrey,
lightpink, lightsalmon, lightseagreen, lightskyblue, lightslategray, lightslategrey,
lightsteelblue, lightyellow, lime, limegreen, linen, magenta, maroon, mediumaquamarine,
mediumblue, mediumorchid, mediumpurple, mediumseagreen, mediumslateblue, mediumspringgreen,
mediumturquoise, mediumvioletred, midnightblue, mintcream, mistyrose, moccasin, navajowhite,
navy, oldlace, olive, olivedrab, orange, orangered, orchid, palegoldenrod, palegreen,
paleturquoise, palevioletred, papayawhip, peachpuff, peru, pink, plum, powderblue, purple,
red, rosybrown, royalblue, saddlebrown, salmon, sandybrown, seagreen, seashell, sienna,
silver, skyblue, slateblue, slategray, slategrey, snow, springgreen, steelblue, tan, teal,
thistle, tomato, turquoise, violet, wheat, white, whitesmoke, yellow, yellowgreen

Определение цвета в формате RGB:

22: $txt->fillcolor(`#FF0000`);

Определение цвета в формате CMYK (cyan, magenta, yellow, black):

22: $txt->fillcolor(`%50009900`);

Задание цвета для начертания линий или заливки цветом графического объекта происходит аналогичным образом.

26: $gfx->fillcolor(`blue`);
41: $line->strokecolor(`blue`);

5.3 Добавление текста

PDF-файлы выстраивают "снизу вверх". Элементы (текст, картинки, линии и т.д.), добавленные позднее, будут перекрывать собой элементы опубликованные ранее. Так, если мы сначала добавим в документ текстовую строку, а потом нарисуем в той же области большой прямоугольник - строка окажется под прямоугольником и не будет видна, либо видна только частично.

18: my $txt=$page->text;

Выбираем шрифт для вывода текста, и определяем его размер:

19: $txt->font($font_tnr,10);

Можно задать межсимвольный интервал и интервал между словами:

20: $txt->charspace(0.6);
21: $txt->wordspace(2);

Указываем координаты для размещения текста, отступ от левого и нижнего краев страницы.

23: $txt->translate($x,$y);

Выводим текст.

24: $txt->text("Hello world!");

Для вывода и одновременного выравнивания текста по правому краю страницы, можно использовать

$txt->text_right($row);

Выравнивание по центру: $txt->text_center($row);

Удобна для использования функция textln. Она позволяет выводить на печать массив строк. Отступы между строками реализуются использованием: $txt->lead(14); - каждая новая строка начинается на 14 px ниже предыдущей. Использование отрицательного значения для lead (например, $txt->lead(-14);) приводит к выводу строк таким образом, что каждая следующая строка располагается выше предыдущей на 14px.

26: $txt->lead(14);
27: $txt->textln(@row_txt);

Однако, несмотря на удобство, метод textln (как и text), имеет недостаток: отсутствие автоматического переноса строк, по достижении ими границ документа. Слишком длинная строка может выйти за границы документа. Чтобы этого избежать, рекомендуется использование функции paragraph. Рaragraph - выводит текст в виде абзаца, при необходимости выполняя автоматический перенос строк, и возвращает $t - отступ от левой границы обозначенного текстового блока в px, позиция вывода последнего символа абзаца; $y2 - позиция курсора относительно вертикальной оси координат на момент окончания вывода текста в px. Текстовые данные функции следует передавать в виде массива слов.

28: my @text = qw(This is functionally the same as the one above, but far less
29: resource-intensive, if you use many pages (possible the same) from one single pdf);

31: my ($t,$y2)=$txt->paragraph($x,$y,$paragraph_width,$paragraph_height,$string_height,@text);

25: $txt->compress();

6 Графические данные в PDF - документе

6.1 Вставка графических изображений в PDF - документ

20: my $gfx=$page->gfx;

Определяем изображение, указываем URL к нему и размеры. Метод image может работать с файлами формата: .jpeg, .png, .pnm.

21: my $img = $pdf->image("/htdocs/flower.jpg", 100, 60);

Выбираем изображение, подлежащее выводу, и указываем координаты размещения.

22: $gfx->image($img,$x,$y);

Следует отметить, что по умолчанию, для вывода изображений на странице используется разрешение 72 dpi. Чтобы вывести изображение с разрешением 150 или 300 dpi, можно указать масштаб 72/150 (или 72/300) или назначить требуемую высоту и ширину изображения:

22: $gfx->image($img,200,$y-30,100,60);

22: $gfx->image($img,0,0,72/300);

Примечание: DPI - (англ. dots per inch) - количество пикселей на дюйм. Указание DPI позволяет "привязать" изображение, размеры которого задаются в относительных единицах (пикселях) к физическим - дюймам. DPI используется при работе с разрешением принтера или сканера. Для указания разрешения монитора традиционно используют пиксели.

Источник: http://ru.wikipedia.org/wiki/DPI

23: $gfx->close;

Прорисовываем изображение в документе, с учетом всех выше указанных инструкции.

24: $gfx->stroke;

25: $gfx->compress();

6.2 Импортирование PDF - документов

Импортирует указанную страницу из стороннего pdf-документа, и позволяет ее использовать
аналогично импортируемым в создаваемый документ картинкам.

$img = $pdf->pdfimage($pdf_file_name,$page_number);
$gfx=$page->gfx;
$gfx->pdfimage($img,0,0,1); # ($img, x_coord, y_coord)

6.3 Создание графических изображений средствами PDF::API2

Рисуем прямоугольник
Создаем новый графический объект:

20: my $gfx=$page->gfx;

Определяем цвет заливки прямоугольника. Как и при использовании шрифтов, данные о цветовой
настройке встраиваются непосредственно в документ. Цвет будет встроен в документ, даже если
он определен, но не используется в дальнейшем.

26: $gfx->fillcolor(`blue`);

Строим прямоугольник. Для этого указываем координаты X (отсчет слева) и Y (отсчет снизу)
расположения прямоугольника, а также его ширину и высоту соответственно.

27: $gfx->rectxy($x1,$y1,$x2,$y2);

Разворачиваем прямоугольник на 45 градусов.

28: $gfx->rotate(45);

Ранее мы только "настраивали" параметры будущего прямоугольника. Теперь добавляем его в наш
PDF-документ. Метод stroke прорисовывает контуры геометрической фигуры. Метод fill
выполняет заливку объекта выбранным цветом.

29: $gfx->stroke;
29: $gfx->fill(1);
29: $gfx->fillstroke;

Рисование линии

Создаем новый графический объект:

40: my $line = $page->gfx;

Определяем цвет и толщину будущей линии соответственно.

41: $line->strokecolor(`blue`);
42: $line->linewidth(5);

Устанавливаем "курсор" в требуемое место страницы.

43: $line->move($x1, $y1);

Из определенной с помощью move позиции, проводим линию до точки, задаваемой командой line.

44: $line->line($x2, $y2);

Эту команду можно выполнять несколько раз подряд, тогда начало каждой новой линии будет исходить из точки, где заканчивается линия предыдущая. hline(X) - проводит горизонтальную линию из установленной командой move (или ранее выполненными командами hline, vline, line) точки. Х - координата точки на оси координат X. Аналогично функционирует команда vline(Y) - проводит вертикальную линию до точки Y на вертикальной оси системы координат.

45: $line->hline($x);
46: $line->vline($y);

Итак, линия определена, но еще не прорисована. Выводим линию, используя заданный цвет:

48: $line->stroke;

Другие геометрические объекты
По аналогии с прямоугольником можно нарисовать следующие геометрические фигуры:

$gfx->curve($x1, $y1, $x2, $y2, $x3, $y3);# рисует кривую линию.
$gfx->arc($center_x, $center_y, $radius_hor, $radius_vert, $from_ygol_naklona, $to_ygol_nakona, $move);#Рисует дугу
$gfx->ellipse($x, $y, $radius_hor, $radius_vert); # рисуем эллипс
$gfx->circle($x, $y, $radius); # рисует окружность
$gfx->rect($x,$y, $width,$height);# рисует прямоугольник

7 Вывод PDF-документа пользователю, сохранение документа

Сохранение документа под указанным именем.

50: $pdf->saveas(`helloworld.pdf`);

Возвращаем документ как строку символов. Stringify удобно использовать при динамической генерации pdf-документов по запросу пользователя и их незамедлительной передаче клиенту.

50: return $pdf->stringify();

Приложение к руководству

1. Примеры кода

Создание документа и вывод текста с помощью paragraph и text
use strict;
use PDF::API2;

my ($w,$h,$f,$str_h)=(596, 842, 39, 14);

my $pdf=PDF::API2->new;
my $page = $pdf->page();
$page->mediabox($w,$h);

my $font = $pdf->corefont(`Helvetica`);
my ($x, $y) = ($f, $h-$f);

my $txt=$page->text;

$txt->font($font,12);
$txt->fillcolor(`#221E1F`);
$txt->charspace(0.7);
$txt->wordspace(2);

my @text = qw(This is functionally the same as the one above, but far less resource);
my ($idt,$y2)=$txt->paragraph(100,700,400,400,14,@text);

$txt->translate(100,300);
$txt->text("idt - $idt, y2 - $y2");

$txt->compress();
$pdf->saveas(`helloworld.pdf`);
$pdf->end;


Открытие существующего документа PDF для редактирования
use strict;
use PDF::API2;

my ($w,$h,$f,$str_h)=(596, 842, 39, 14);
my $pdf = PDF::API2->YzyX("helloworld.pdf");
my $page = $pdf->openpage(1);
$page->cropbox($w,$h);

$pdf->saveas(`open.pdf`);
$pdf->end;



Импортирование страниц из ранее созданного PDF-документа
use strict;
use PDF::API2;

my ($w,$h,$f,$str_h)=(596, 842, 39, 14);
my $import_pdf = PDF::API2->YzyX("helloworld.pdf");
my $pdf = PDF::API2->new;

my $page = $pdf->importpage($import_pdf, 1, 1);

$page->cropbox($w,$h);

$pdf->saveas(`open.pdf`);
$pdf->end;
$import_pdf->end;


Публикация изображения
my $gfx=$page->gfx;

my $img = $pdf->image("flower.jpg", 2554, 3579);
$gfx->image($img,0,0,596,842);

$gfx->close;
$gfx->stroke;
$gfx->compress();


Использование textln для вывода текста
my $txt=$page->text;
$txt->lead($str_h);
$txt->font($font,12);
$txt->charspace(0.6);
$txt->wordspace(2);

my @txt_arr = (
qq{This chapter introduces JavaScript, discusses some of the fundamental concepts},
qq{of JavaScript in Navigator and provides basic examples.},
qq{It shows JavaScript code in action, so you can begin writing your own},
qq{scripts immediately, using the example code as a starting point.},
);

$txt->translate(100,500);
$txt->lead(14);
$txt->textln(@txt_arr);

Рисуем линию
my $line = $page->gfx;
$line->strokecolor(`blue`);
$line->move(100, 200);
$line->line(400, 500);
$line->close;
$line->stroke;
$line->compress();

2. Полезные ссылки

EN
Документация PDF::API2 на search.cpan.org
Официальные спецификации формата PDF
PDF::API2. Tutorial. Rick Measham
RU
Создание сайтов с возможностью печати PDF на примере PDF::API2 (http://www.opennet.ru)
Валентин Синицын. Статья. Работаем с PDF из Perl. Системный администратор, N3. Март, 2006.