Peter Paris > pod2book-0.0.1 > Pod::LaTeX::Book
Module Version: 0.0.1

# NAME

Pod::LaTeX::Book - Compile POD pages into a LaTeX book.

# VERSION

This document describes Pod::LaTeX::Book version 0.0.1

# SYNOPSIS

    use Pod::LaTeX::Book;

my $parser = Pod::LaTeX::Book->new ( ); # configure$parser->configure( $cfgRef ); # or$parser->configure_from_file( 'config' );

# output .tex file
\$parser->parse( 'out.tex' );

# script for producing a LaTeX book
pod2book --conf=conf_file --out=tex_file

# DESCRIPTION

This module aims to provide a mechanism to compile the POD documentation for a set of modules into a printable collection. LaTeX is used as an intermediate format from which both pdf and printed versions can be produced.

The modules builds on the functionality provided by Pod::LaTeX. For this purpose several methods from Pod::LaTeX are either overridden or extended. Perhaps most notably, this package uses the LaTeX packages hyperref, listings, and fancyvrb to produce more attractive, extensively hyper-linked PDF.

# INTERFACE

The following routines provide the public interface. Note, that the methods from Pod::LaTeX, from which this module inherits, are also available.

## configure

Provide information about the documents to be combined and options for the output to be produced. This function should not be invoked directly; use configure_from_file instead which calls this function.

Basic validation of the configuration parameters is performed.

## configure_from_file

Read configuration information from a file. The file may be in any format supported by Config::Any.

The format of the file is as follows (in YAML):

   ---
DocOptions:
Date: August 2, 2007
TexOut: mybook.tex
UserPreamble: |
\documentclass{book}
UserPostamble: |
\cleardoublepage
\printindex
\end{document}
LevelNoNum:  4
DocStructure:
- Input:
FileOrPod: frontmatter.tex
- Section:
Level: part
Title: First Part
- Input:
FileOrPod: Catalyst::Manual::Tutorial
SkipUntil: DESCRIPTION
- Input:
FileOrPod: Catalyst::Manual
SkipFrom: THANKS
- Section:
Level: part
Title: Appendix

Of the document options, only Title is required. All others have sensitive defaults. The parameters AddPreamble, Head1Level, and LevelNoNum are passed to Pod::LaTeX.

If the standard preamble is insufficient, it is recommended to set things up as above. Specify a minimal UserPreamble, set AddPreamble to a true value, and read the remainder of the preamble from the first input file (here, frontmatter.tex). Note, that the preamble must include at least the following LaTeX packages.

hyperref
listings
fancyvrb

The DocStructure specifies the sequence of documents to be included, it consists of a list of Section and Input directives. The Section directives can be used to provide additional section commands (e.g., parts). The Input directives specify the file name of a LaTeX document to be included or the name of a POD page. POD pages are parsed and translated to LaTeX. It is possible to skip leading sections in a POD via the SkipUntil directive or trailing sections via the SkipFrom directive.

## parse

Construct the latex document by converting each of the PODs from the configuration file. The bulk of the work is done by "parse_from_file" in Pod::LaTeX.

# Overriden Subroutines

The following routines from Pod::LaTeX are overridden to modify or extend functionality.

## verbatim

Overwrite the verbatim in Pod::LaTeX to use the listing environment rather than verbatim.

The original package breaks listings up into chunks separated by empty lines, here we combine those. output does not happen until we're done with the entire block. See "output_verbatim".

## interior_sequence

Partially overwrite the functionality in Pod::LaTeX. Specifically, we replace processing of C-tags to use the listings of fancyvrb package. Also, proper hyperlinking is provided via the hyperref package.

## textblock

Plain text paragraph. Modified to output any pending verbatim output.

## command

Process basic pod commands. Modified to output any pending verbatim output.

# DIAGNOSTICS

Invalid key: only Section and Input are allowed

A key, other than Section or Input was specified for the document structure. Occurs when the document structure in the configuration file is incorrect. In YAML, it must look something like:

   DocStructure:
- Section:
Level: part
Title: First Part
- Input:
FileOrPod: Catalyst::Manual::Tutorial
- Input:
FileOrPod: Catalyst::Manual
- Section:
Level: part
Title: Appendix
Mandatory parameter '...' missing in call to Pod::Book::configure

This and similar errors occur when the configuration does not meet specifications.

POD not found for ...

No POD documentation available on the system. Check for typos.

# CONFIGURATION AND ENVIRONMENT

Pod::Book is configured by means of a configuration file that provides details about the PODs to be combined. See "parse_from_file" for details.

# DEPENDENCIES

Module Pod::Book is sub-classed from PoD::LaTeX. It also needs Carp, Config::Any, Params::Validate, Perl6::Slurp, Pod::Find, and Pod::ParseUtils.

None reported.

# BUGS AND LIMITATIONS

The conversion process with pdflatex is rarely smooth. Beyond the usual complaints about overfull hboxes, frequent error messages surrounding the listings package are common. Try ignoring them.

Similarly, complaints about multiply defined labels and hypertargets are common.

Please report any bugs or feature requests to bug-pod-book@rt.cpan.org, or through the web interface at http://rt.cpan.org.

# AUTHOR

Peter Paris <lutetius@cpan.org>