Help language development. Donate to The Perl Foundation

Pod::To::PDF zef:dwarring last updated on 2022-09-21



Render Pod to PDF via Cairo


From command line:

    $ raku --doc=PDF lib/to/class.rakumod | xargs evince

From Raku:

use Pod::To::PDF;
use Cairo;


=code <options> files ...

my Cairo::Surface::PDF $pdf = pod2pdf($=pod, :pdf-file<foobar.pdf>);


  * `class Pod::To::PDF;`

  * `sub pod2pdf; # See below`

From Raku code, the `pod2pdf` function returns a [Cairo::Surface::PDF](Cairo::Surface::PDF) object which can be further manipulated, or finished to complete rendering.


This module renders Pod to PDF documents via Cairo.

The generated PDF has a table of contents and is tagged for accessibility and testing purposes.

It uses HarfBuzz for font shaping and glyph selection and FontConfig for system font loading.


### sub pod2pdf()

sub pod2pdf(
    Pod::Block $pod
) returns Cairo::Surface::PDF;

#### pod2pdf() Options

**`Str() :$pdf-file`**

A filename for the output PDF file.

**`Cairo::Surface::PDF :$surface`**

A surface to render to

**`UInt:D :$width, UInt:D :$height`**

The page size in points (there are 72 points per inch).

**`UInt:D :$margin`**

The page margin in points (default 20).

**`Hash :@fonts`**

By default, Pod::To::PDF loads system fonts via FontConfig. This option can be used to preload selected fonts.

use Pod::To::PDF;
use Cairo;
my @fonts = (
    %(:file<fonts/Raku-Bold.ttf>, :bold),
    %(:file<fonts/Raku-Italic.ttf>, :italic),
    %(:file<fonts/Raku-BoldItalic.ttf>, :bold, :italic),
    %(:file<fonts/Raku-Mono.ttf>, :mono),

my Cairo::Surface::PDF $pdf = pod2pdf($=pod, :@fonts, :pdf-file<out.pdf>);

Each font entry should have a `file` entry and various combinations of `bold`, `italic` and `mono` flags. Note that `mono` is used to render code blocks and inline code.

**`Str :%metadata`**

This can be used to preset values for `title`, `subtitle`, `name`, `author` or `version`.

This is an alternative to, and will override `=TITLE`, `=SUBTITLE`, `=NAME`, `=AUTHOR` or `=VERSION` directives.

Note: All of these are options are provided for compatibility, however only `=TITLE` and `=AUTHOR` are directly supported in PDF metadata.


Disables Table of Contents generation.


Disable writing of a `Index` section to the table of contents.


Provides a class or object to intercept and sanitise or rebase links. The class/object should provide a method `resolve-link` that accepts the target component of C<L<>> formatting codes and returns the actual link to be embedded in the PDF. The link is omitted, if the method returns an undefined value.


Specify replacements for `R<>` placeholders in the POD. Replacement values should be simple strings (`Str`), Pod blocks (type `Pod::Block`), or a `List`. For example:

use Pod::To::PDF;
my $title = 'Sample Title';
my Str() $date = now.Date;
my $author = 'David Warring';
my $description = "sample Pod with replaced content";
my %replace = :$date, :$title, :$author, :$description;
my $renderer = pod2pdf($=pod, :%replace, :pdf-file<replace-example.pdf>);

=begin pod
=TITLE R<title>
=AUTHOR R<author>
=DATE R<date>
=head2 Description
=para R<description>;
=end pod


This module's dependencies include [HarfBuzz](, [Font::FreeType](, [FontConfig]( and [Cairo](, which further depend on native `harfbuzz`, `freetype6`, `fontconfig` and `cairo` libraries.

Please check these module's installation instructions.


Note that installation of the [PDF::Tags::Reader](PDF::Tags::Reader) module enables structural testing. 

For example, to test this module from source.

    $ git clone
    $ cd Pod-To-PDF-raku
    $ zef install PDF::Tags::Reader # enable structural tests
    $ zef APP::Prove6
    $ zef --deps-only install .
    $ prove6 -I .