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

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

    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

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.

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

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.

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:
     Title:  Your Book
     Author: Your Name
     Date: August 2, 2007
     TexOut: mybook.tex
     UserPreamble: |
       \documentclass{book}
     UserPostamble: |
       \cleardoublepage
       \addcontentsline{toc}{chapter}{\numberline{}Index}
       \printindex
       \end{document}
     AddPreamble: 1
     Head1Level:  0
     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.

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.

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

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.

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.

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

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

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.

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.

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.

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.

Peter Paris <lutetius@cpan.org>

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

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.