Pod::LaTeX - Convert Pod data to formatted Latex

- NAME
- SYNOPSIS
- DESCRIPTION
- OBJECT METHODS

- Data Accessors
- Subclassed methods
- List Methods
- Methods for headings
- Internal methods

- NOTES
- SEE ALSO
- AUTHORS
- COPYRIGHT
- REVISION

# NAME

Pod::LaTeX - Convert Pod data to formatted Latex

# SYNOPSIS

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

      $parser->parse_from_filehandle;

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

# DESCRIPTION

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

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

# OBJECT METHODS

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

## Data Accessors

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 `new()` constructor.

AddPreamble
  Logical to control whether a `latex` preamble is to be written. If true, a valid `latex` 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 `AddPostamble` a full latex document will be written that could be immediately processed by `latex`.

  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 `latex` 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 `AddPreaamble` a full latex document will be written that could be immediately processed by `latex`.

Head1Level
  The `latex` sectioning level that should be used to correspond to a pod `=head1` directive. This can be used, for example, to turn a `=head1` into a `latex` `subsection`. 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 `=head3` do not have a corresponding `latex` section (`=head1` would correspond to a `paragraph`).

  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 `section`).

Label
  This is the label that is prefixed to all `latex` label and index entries to make them unique. In general, pods have similarly titled sections (NAME, DESCRIPTION etc) and a `latex` label will be multiply defined if more than one pod document is to be included in a single `latex` 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, `\label{text}` becomes `\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 `UniqueLabels` is true. Its value is set automatically from the `NAME` field if `ReplaceNAMEwithSection` is true. If this is not the case it must be set manually before starting the parse.

  Default value is `undef`.

LevelNoNum
  Control the point at which `latex` section numbering is turned off. For example, this can be used to make sure that `latex` 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 `Head1Level` method description. The number has nothing to do with the pod heading number, only the `latex` sectioning.

  Default is 2. (i.e. `latex` subsections are written as `subsection*` but sections are numbered).

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

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

  Irrelevant if both `AddPreamble` and `AddPostamble` are false (or equivalently, `UserPreamble` and `UserPostamble` are set).

  Default is for an index to be created.

ReplaceNAMEwithSection
  This controls whether the `NAME` 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 `latex`

        \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 `Head1Level` and `LevelNoNum`). Note that subsequent `head1` directives translate to subsections rather than sections and that the labels and index now include the pod name (dependent on the value of `UniqueLabels`).

  The `Label` is set from the pod name regardless of any current value of `Label`.

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

  Default is to translate the pod literally.

StartWithNewPage
  If true, each pod translation will begin with a `latex` `\clearpage`.

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

  Default is false.

TableOfContents
  If true, a table of contents will be created. Irrelevant if `AddPreamble` is false or `UserPreamble` is set.

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

  Default is false.

UniqueLabels
  If true, the translator will attempt to make sure that each `latex` label or index entry will be uniquely identified by prefixing the contents of `Label`. This allows multiple documents to be combined without clashing common labels such as `DESCRIPTION` and `SYNOPSIS`

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

  Default is true.

UserPreamble
  User supplied `latex` 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 `AddPreamble`. `MakeIndex` and `TableOfContents` will also be ignored.

UserPostamble
  User supplied `latex` 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 `AddPostamble`. `MakeIndex` will also be ignored.

# NOTES

Compatible with `latex2e` only. Can not be used with `latex` v2.09 or earlier.

A subclass of `Pod::Select` so that specific pod sections can be converted to `latex` by using the `select` method.

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

# SEE ALSO

the Pod::Parser manpage, the Pod::Select manpage, pod2latex

# AUTHORS

Tim Jenness <t.jenness@jach.hawaii.edu>

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> and Ariel Scolnicov <ariels@compugen.co.il>.

# COPYRIGHT

Copyright (C) 2000-2003 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.

Pod::LaTeX - Convert Pod data to formatted Latex