NAME
App::RakuDocToPDF - Provides routines to convert RakuDoc to PDF
See a simple README.rakudoc example for another module at click here
SYNOPSIS
From the command line:
rakudoc2pdf README.rakudoc
rakudoc2pdf README.rakudoc --output=README.pdf
rakudoc2pdf README.rakudoc --media=A4
rakudoc2pdf README.rakudoc --type=module-readme
From Raku:
use App::RakuDocToPDF;
my IO::Path $pdf = rakudoc-to-pdf(
'README.rakudoc',
:output<README.pdf>,
:media<Letter>,
:type<module-readme>,
);
DESCRIPTION
App::RakuDocToPDF converts simple RakuDoc files to paginated PDF documents.
Note documents are now parsed through RakuAST.
Its current primary purpose is to produce a printable draft of a module's RakuDoc README for proofreading and handwritten editing. The generated document uses normal Letter or A4 pages rather than one continuously growing PDF page.
The current version deliberately supports a useful subset of RakuDoc rather than attempting to be a complete RakuDoc publishing system.
PDF pages use the standard PDF core fonts:
Times-Roman for normal body text
Helvetica Bold for headings
Courier for code
Helvetica for page footers
Each page has a centered footer in the form:
Page M of N
where M is the current page number and N is the total number of pages.
COMMAND LINE
The distribution installs the rakudoc2pdf program.
Execute the program without an input file, or use --help or -h, to see its usage information:
Usage:
rakudoc2pdf INPUT.rakudoc [--output=FILE.pdf] [--media=Letter|A4] [--type=generic|module-readme]
Examples:
rakudoc2pdf README.rakudoc
rakudoc2pdf README.rakudoc --output=README.pdf
rakudoc2pdf README.rakudoc --media=A4
rakudoc2pdf README.rakudoc --type=module-readme
Only one input file may be specified.
OPTIONS
--output=FILE.pdf
Specifies the output PDF file.
For example:
rakudoc2pdf README.rakudoc --output=draft.pdf
If --output is omitted, the output file is created in the current working directory using the input file's basename, with the .rakudoc suffix replaced by .pdf.
Thus:
docs/README.rakudoc
with no options produces:
./README.pdf
Selects the PDF page media.
The supported values are:
The default is Letter.
For example:
rakudoc2pdf README.rakudoc --media=A4
rakudoc2pdf README.rakudoc --type=module-readme
--type=generic|module-readme
Selects the document type used for validation before the PDF is generated.
The supported values are:
Performs no document-type-specific validation. This is the default.
Validates conventions for a Raku module README. The current validation checks for duplicate =TITLE and =SUBTITLE directives, a =SUBTITLE that occurs before =TITLE, and a missing =head1 NAME section.
For example:
rakudoc2pdf README.rakudoc --type=module-readme
If document-type validation fails, the PDF is not generated and the reported issues are written as an error.
--help, -h
Displays command-line usage information and exits.
LIBRARY INTERFACE
The distribution exports the rakudoc-to-pdf routine:
use App::RakuDocToPDF;
my IO::Path $pdf = rakudoc-to-pdf(
'README.rakudoc',
:output<README.pdf>,
:media<Letter>,
:type<module-readme>,
);
The :output argument is optional. If it is omitted, the output filename is derived from the input file's basename and is written in the current working directory.
The :media argument is also optional and defaults to Letter.
The :type argument is optional and defaults to generic. The supported values are generic and module-readme. Document-type validation is performed before layout and PDF generation.
The routine returns the IO::Path of the generated PDF file.
SUPPORTED RAKUDOC
The current version is intended primarily for ordinary module README files. It will eventually handle other uses such as
It currently recognizes and renders:
headings written with =headN
ordinary paragraphs
=item entries
=code lines
=begin code and =end code blocks
the visible contents of common B<>, I<>, and C<> inline formatting codes
the visible label of a labeled L<> link
Text is wrapped to the available page width, and new PDF pages are created as needed.
REPRODUCIBLE OUTPUT
The renderer is designed so that identical RakuDoc input and identical rendering options produce identical PDF bytes. Volatile PDF metadata, such as the current creation time, is not written. The PDF file identifier is derived deterministically from the input text and media choice.
This makes generated README drafts suitable for checksum comparison and prevents a PDF from appearing to change when its rendered content has not.
LIMITATIONS
This is an intentionally lightweight renderer. It does not yet implement the complete RakuDoc specification.
In particular:
Inline B<>, I<>, and C<> markup is currently rendered as ordinary visible text rather than with bold, italic, or code styling.
Labeled links retain their visible label, but the generated PDF does not currently create active PDF hyperlinks.
Unsupported RakuDoc block directives are currently ignored.
Richer RakuDoc features such as tables and images are not currently rendered.
The current output is intended primarily as a clean printable draft for proofreading rather than as publication-quality typesetting.
These limitations may be reduced in later releases while retaining the simple draft-generation use case.
AUTHOR
Tom Browder tbrowder@acm.org
COPYRIGHT AND LICENSE
© 2026 Tom Browder
This library is free software; you may redistribute it or modify it under the Artistic License 2.0.