Pod::LaTeX - Convert Pod data to formatted Latex

  use Pod::LaTeX;
  my $parser = Pod::LaTeX->new ( );

  $parser->parse_from_filehandle;

  $parser->parse_from_file ('file.pod', 'file.tex');

CWPod::LaTeX is a module to convert documentation in the Pod format into Latex. The pod2latex command uses this module for translation.

CWPod::LaTeX is a derived class from Pod::Select.

The following methods are provided in this module. Methods inherited from CWPod::Select are not described in the public interface.

The following methods are provided for accessing instance data. These methods should be used for accessing configuration parameters rather than assuming the object is a hash.

Default values can be supplied by using these names as keys to a hash of arguments when using the CWnew() constructor.

AddPreamble

Logical to control whether a CWlatex preamble is to be written. If true, a valid CWlatex preamble is written before the pod data is written. This is similar to:

  \documentclass{article}
  \usepackage[T1]{fontenc}
  \usepackage{textcomp}
  \begin{document}

but will be more complicated if table of contents and indexing are required. Can be used to set or retrieve the current value.

  $add = $parser->AddPreamble();
  $parser->AddPreamble(1);

If used in conjunction with CWAddPostamble a full latex document will be written that could be immediately processed by CWlatex. For some pod escapes it may be necessary to include the amsmath package. This is not yet added to the preamble automaatically.

AddPostamble

Logical to control whether a standard CWlatex ending is written to the output file after the document has been processed. In its simplest form this is simply:

  \end{document}

but can be more complicated if a index is required. Can be used to set or retrieve the current value.

  $add = $parser->AddPostamble();
  $parser->AddPostamble(1);

If used in conjunction with CWAddPreaamble a full latex document will be written that could be immediately processed by CWlatex.

Head1Level

The CWlatex sectioning level that should be used to correspond to a pod CW=head1 directive. This can be used, for example, to turn a CW=head1 into a CWlatex CWsubsection. This should hold a number corresponding to the required position in an array containing the following elements:

 [0] chapter
 [1] section
 [2] subsection
 [3] subsubsection
 [4] paragraph
 [5] subparagraph

Can be used to set or retrieve the current value:

  $parser->Head1Level(2);
  $sect = $parser->Head1Level;

Setting this number too high can result in sections that may not be reproducible in the expected way. For example, setting this to 4 would imply that CW=head3 do not have a corresponding CWlatex section (CW=head1 would correspond to a CWparagraph). A check is made to ensure that the supplied value is an integer in the range 0 to 5. Default is for a value of 1 (i.e. a CWsection).

Label

This is the label that is prefixed to all CWlatex label and index entries to make them unique. In general, pods have similarly titled sections (NAME, DESCRIPTION etc) and a CWlatex label will be multiply defined if more than one pod document is to be included in a single CWlatex file. To overcome this, this label is prefixed to a label whenever a label is required (joined with an underscore) or to an index entry (joined by an exclamation mark which is the normal index separator). For example, CW\label{text} becomes CW\label{Label_text}. Can be used to set or retrieve the current value:

  $label = $parser->Label;
  $parser->Label($label);

This label is only used if CWUniqueLabels is true. Its value is set automatically from the CWNAME field if CWReplaceNAMEwithSection is true. If this is not the case it must be set manually before starting the parse. Default value is CWundef.

LevelNoNum

Control the point at which CWlatex section numbering is turned off. For example, this can be used to make sure that CWlatex sections are numbered but subsections are not. Can be used to set or retrieve the current value:

  $lev = $parser->LevelNoNum;
  $parser->LevelNoNum(2);

The argument must be an integer between 0 and 5 and is the same as the number described in CWHead1Level method description. The number has nothing to do with the pod heading number, only the CWlatex sectioning. Default is 2. (i.e. CWlatex subsections are written as CWsubsection* but sections are numbered).

MakeIndex

Controls whether CWlatex commands for creating an index are to be inserted into the preamble and postamble

  $makeindex = $parser->MakeIndex;
  $parser->MakeIndex(0);

Irrelevant if both CWAddPreamble and CWAddPostamble are false (or equivalently, CWUserPreamble and CWUserPostamble are set). Default is for an index to be created.

ReplaceNAMEwithSection

This controls whether the CWNAME section in the pod is to be translated literally or converted to a slightly modified output where the section name is the pod name rather than NAME. If true, the pod segment

  =head1 NAME

  pod::name - purpose

  =head1 SYNOPSIS

is converted to the CWlatex

  \section{pod::name\label{pod_name}\index{pod::name}}

  Purpose

  \subsection*{SYNOPSIS\label{pod_name_SYNOPSIS}%
               \index{pod::name!SYNOPSIS}}

(dependent on the value of CWHead1Level and CWLevelNoNum). Note that subsequent CWhead1 directives translate to subsections rather than sections and that the labels and index now include the pod name (dependent on the value of CWUniqueLabels). The CWLabel is set from the pod name regardless of any current value of CWLabel.

  $mod = $parser->ReplaceNAMEwithSection;
  $parser->ReplaceNAMEwithSection(0);

Default is to translate the pod literally.

StartWithNewPage

If true, each pod translation will begin with a CWlatex CW\clearpage.

  $parser->StartWithNewPage(1);
  $newpage = $parser->StartWithNewPage;

Default is false.

TableOfContents

If true, a table of contents will be created. Irrelevant if CWAddPreamble is false or CWUserPreamble is set.

  $toc = $parser->TableOfContents;
  $parser->TableOfContents(1);

Default is false.

UniqueLabels

If true, the translator will attempt to make sure that each CWlatex label or index entry will be uniquely identified by prefixing the contents of CWLabel. This allows multiple documents to be combined without clashing common labels such as CWDESCRIPTION and CWSYNOPSIS

  $parser->UniqueLabels(1);
  $unq = $parser->UniqueLabels;

Default is true.

UserPreamble

User supplied CWlatex preamble. Added before the pod translation data. If set, the contents will be prepended to the output file before the translated data regardless of the value of CWAddPreamble. CWMakeIndex and CWTableOfContents will also be ignored.

UserPostamble

User supplied CWlatex postamble. Added after the pod translation data. If set, the contents will be prepended to the output file after the translated data regardless of the value of CWAddPostamble. CWMakeIndex will also be ignored.

Compatible with CWlatex2e only. Can not be used with CWlatex v2.09 or earlier.

A subclass of CWPod::Select so that specific pod sections can be converted to CWlatex by using the CWselect method.

Some HTML escapes are missing and many have not been tested.

Pod::Parser, Pod::Select, pod2latex

Tim Jenness <tjenness@cpan.org>

Bug fixes and improvements have been received from: Simon Cozens <simon@cozens.net>, Mark A. Hershberger <mah@everybody.org>, Marcel Grunauer <marcel@codewerk.com>, Hugh S Myers <hsmyers@sdragons.com>, Peter J Acklam <jacklam@math.uio.no>, Sudhi Herle <sudhi@herle.net>, Ariel Scolnicov <ariels@compugen.co.il>, Adriano Rodrigues Ferreira <ferreira@triang.com.br> and R. de Vries <r.de.vries@dutchspace.nl>.

Copyright (C) 2000-2004 Tim Jenness. All Rights Reserved.

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