NAME
SYNOPSIS
DESCRIPTION
CALLING FROM THE COMMAND LINE
FONTS USED
METHODS
METHODS TO OVERRIDE
SEE ALSO
COPYRIGHT AND DISCLAIMERS
AUTHOR
CAVEATS
TODO

NAME

Pod::Simple::PDF - convert Pod to PDF

SYNOPSIS

  perl -MPod::Simple::PDF -e Pod::Simple::PDF::go some.pod

DESCRIPTION

This class is for converting a Pod document into PDF.

This is a subclass of Pod::Simple::PullParser and inherits all its methods (and options).

CALLING FROM THE COMMAND LINE

 perl -MPod::Simple::PDF -e Pod::Simple::PDF::go some.pod some.pdf

FONTS USED

Some fonts are loaded by default. The default fonts used are Verdana (normal text) and Courier (for C and VerbatimFormatted). These can be changed with the font() method.

 # default font(s) used
 default   Verdana
 defaultB  Verdana-Bold
 defaultI  Verdana-Italic
 defaultBI Verdana-BoldItalic
 
 # for C<> and VerbatimFormatted
 fixed     Courier
 fixedB    Courier-Bold
 fixedI    Courier-Oblique
 fixedBI   Courier-BoldOblique

 # for the bullet character
 symbol    Symbol

METHODS

paper_size([NAME])

Set the paper size by name, like A4 (default), letter, ... Setting the paper dimensions in points is currently not supported.

default_font_size([POINTS])

Set the default font size, default: 10 pts.

margin_left([POINTS])

default: 50

margin_right([POINTS])

default: 50

margin_top([POINTS])

default: 50

margin_bottom([POINTS])

default: 50

Get/set the margins of the paper. Anything above the top margin and below the bottom margin can be safely set by overriding "page_footer()" / "page_header()".

indent_width([POINTS])

Pod::Simple::PDF currently ignores the depth set by an =over block, each nested block is indented by POINTS points, default is 20 points.

head_x_fontstep([POINTS])

The font size of the =headX is calculated by

  $tag =~ /^head(\d)$/;
  $size = $self->default_font_size + ((5 - $1) * $self->head_x_fontstep);

pdf

Returns the PDF::API3::Compat::API2 object. This can be used to set the fonts via $pdf->pdf->corefont(...)

page

Returns the PDF::API3::Compat::API2 page object, DO NOT call $pdf->pdf->page, as this will open a new page...

You may add graphics objects in page_footer(), page_header() with this.

txt

Returns the current text object of the "page". If you use this in page_header() / page_footer() you must set a font with something like

  $self->txt->font( $self->font("default"), 
                    $self->default_font_size - 3 );

font(KEY[, FONT])

Sets the font for KEY to FONT. FONT must be a valid font object, like returned from $pdf->pdf->corefont("Verdana") or $pdf->pdf->ttfont("fontname.ttf"). For others, see PDF::API3::Compat::API2.

KEY may be default or fixed to override the default fonts used in the PDF. You should set all four variants (e.g. default, defaultB (bold), defaultI (italics) and defaultBI (bold and italics)) of a KEY.

To set a specific font for a given tag, set KEYs to the tag name, e.g. head1, head1B, head1I and head1BI.

Example:

  use Pod::Simple::PDF;
  
  my $pdf = Pod::Simple::PDF->new();
  ## default font is "Verdana", set to "Helvetica":
  $pdf->font("default",   $pdf->pdf->corefont("Helvetica"));
  $pdf->font("defaultB",  $pdf->pdf->corefont("Helvetica-Bold"));
  $pdf->font("defaultI",  $pdf->pdf->corefont("Helvetica-Oblique"));
  $pdf->font("defaultBI", $pdf->pdf->corefont("Helvetica-BoldOblique"));
  
  # set font of "head1", "head2", ... to "Times":
  foreach ((1 .. 4)) {
      $pdf->font("head${_}",   $pdf->pdf->corefont("Times"));
      $pdf->font("head${_}B",  $pdf->pdf->corefont("Times-Bold"));
      $pdf->font("head${_}I",  $pdf->pdf->corefont("Times-Italic"));
      $pdf->font("head${_}BI", $pdf->pdf->corefont("Times-BoldItalic"));
  }
  
  $pdf->parse_from_file(@ARGV);

page_number

Returns the current page number.

page_width

Returns the width of the page in points

page_height

Returns the height of the page in points

METHODS TO OVERRIDE

See also the scripts in examples/ on how to use these.

title_page()

Called before the first page is opened, default is to do nothing.

page_footer()

page_header()

These are automatically called when a new page is opened. You can use these to give the pages another header / footer.

add_item_bullet()

Override add_item_bullet() with your changed version and call _add_item_bullet(NAME, CHAR), where NAME is the name of a font set with "font" (see above) and CHAR is the character(s) you want as bullet. Default is:

  sub add_item_bullet { 
      shift->_add_item_bullet("symbol", chr(183)); 
  }

COPYRIGHT AND DISCLAIMERS

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

AUTHOR

Hanno Hecker vetinari@ankh-morp.org

CAVEATS

This is module is in an early stage, the API may change without notice, see "TODO".

TODO

L<links> are currently unsupported, just text printed
X<indices> are currently unsupported
create PDF index, probably via $pdf->index(1), like Pod::Simple::HTML.
NBSP AKA S<some thing with spaces>: status unknown...
swap left / right margin on even / odd pages?
some values (like centering of page number) hard coded
pager numbering in corner, not center? see above. ... but: why not let them override $pdf->page_footer() and page_header() if someone needs something else.
unicode support?