Help language development. Donate to The Perl Foundation
Pod::To::PDF
Render Pod to PDF via Cairo
From command line:
$ raku --doc=PDF lib/to/class.rakumod --save-as=class.pdf
From Raku:
use Pod::To::PDF; use Cairo; =NAME foobar.pl =head2 SYNOPSIS =code foobar.pl <options> files ... my Cairo::Surface::PDF $pdf = pod2pdf($=pod, :save-as<foobar.pdf>); $pdf.finish();
--save-as=pdf-filename
File-name for the PDF output file. If not given, the output will be saved to a temporary file. The file-name is echoed to stdout
.
--width=n
Page width in points (default: 592)
--height=n
Page height in points (default: 792)
--margin=n
Page margin in points (default: 20)
--/toc
Disable table of contents
--/index
Disable index of terms
--page-numbers
Add page numbers (bottom right)
class Pod::To::PDF;
sub pod2pdf; # See below
From Raku code, the pod2pdf
function returns a Cairo::Surface::PDF object which can be further manipulated, or finished to complete rendering.
This module does simple rendering of 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( Pod::Block $pod ) returns Cairo::Surface::PDF;
Str() :$save-as
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.ttf>), %(: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, :save-as<out.pdf>); $pdf.finish();
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.
:!contents
Disables Table of Contents generation.
:!index
Disable writing of a Index
section to the table of contents.
:$linker
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
:%replace
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, :save-as<replace-example.pdf>); $renderer.finish(); =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 module enables structural testing.
For example, to test this module from source.
$ git clone https://github.com/pod-to-pdf/Pod-To-PDF-raku
$ cd Pod-To-PDF-raku
$ zef install PDF::Tags::Reader # enable structural tests
$ zef APP::Prove6
$ zef --deps-only install .
$ prove6 -I .