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.
hyperref
listings
fancyvrb
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.
Title
AddPreamble
Head1Level
LevelNoNum
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.
UserPreamble
frontmatter.tex
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.
DocStructure
Section
Input
SkipUntil
SkipFrom
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.
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.
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.
bug-pod-book@rt.cpan.org
Peter Paris <lutetius@cpan.org>
<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.
To install Pod::LaTeX::Book, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Pod::LaTeX::Book
CPAN shell
perl -MCPAN -e shell install Pod::LaTeX::Book
For more information on module installation, please visit the detailed CPAN module installation guide.