txt: ## dist_zef-dwarring-Pod-To-PDF.md
  # TITLE
  
  Pod::To::PDF
  
  # SUBTITLE
  
  Render Pod to PDF via Cairo
  
  # Usage
  
  From command line:
  
  ```
  $ raku --doc=PDF lib/To/Class.rakumod --save-as=To-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();
  
  ```
  
  ### Command Line Options:
  
  **--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 --margin-left=n --margin-right=n --margin-top=n --margin-bottom=n**
  
  Page margin in points (default: 20)
  
  **--/toc**
  
  Disable table of contents
  
  **--/index**
  
  Disable index of terms
  
  **--page-numbers**
  
  Add page numbers (bottom right)
  
  **--compress**
  
  Compress the rendered PDF. The optional [Compress::PDF](https://raku.land/zef:tbrowder/Compress::PDF) module needs to be installed to use this option.
  
  **--page-style**
  
  ```
  -raku --doc=PDF lib/to/class.rakumod --page-style='margin:10px 20px; width:200pt; height:500pt" --save-as=class.pdf
  
  ```
  
  Perform CSS `@page` like styling of pages. At the moment, only margins (`margin`, `margin-left`, `margin-top`, `margin-bottom`, `margin-right`) and the page `width` and `height` can be set. The optional [CSS::Properties](https://css-raku.github.io/CSS-Properties-raku/) module needs to be installed to use this option.
  
  # Exports
  
  * `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.
  
  # Description
  
  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.
  
  # Subroutines
  
  ### sub pod2pdf()
  
  ```
  sub pod2pdf(
      Pod::Block $pod
  ) returns Cairo::Surface::PDF;
  
  ```
  
  #### pod2pdf() Options
  
  **`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<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.
  
  **`:%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
  
  ```
  
  # Installation
  
  This module's dependencies include [HarfBuzz](https://harfbuzz-raku.github.io/HarfBuzz-raku/), [Font::FreeType](https://pdf-raku.github.io/Font-FreeType-raku/), [FontConfig](https://raku.land/zef:dwarring/FontConfig) and [Cairo](https://raku.land/github:timo/Cairo), which further depend on native `harfbuzz`, `freetype6`, `fontconfig` and `cairo` libraries.
  
  Please check these module's installation instructions.
  
  # Testing
  
  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 .
  
  ```
  