/ 
pod2book-0.0.1
River stage zero No dependents
/ Pod::LaTeX::Book

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:
  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.

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.

INCOMPATIBILITIES

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>

LICENCE AND COPYRIGHT

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

DISCLAIMER OF WARRANTY

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.