Manual

Reference

Modules

  • A • B • C • D • E
  • F • G • H • I • L
  • M • N • O • P • S
  • T • U • X

Tools

Pod::LaTeX

Perl 5 version 8.8 documentation
Go to top • Download PDF
Show page index • Show recent pages
Recently read

Pod::LaTeX

NAME

Pod::LaTeX - Convert Pod data to formatted Latex

SYNOPSIS

  1.   use Pod::LaTeX;
  2.   my $parser = Pod::LaTeX->new ( );
  4.   $parser->parse_from_filehandle;
  6.   $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.

  • initialize

    Initialise the object. This method is subclassed from C. The base class method is invoked. This method defines the default behaviour of the object unless overridden by supplying arguments to the constructor.

    Internal settings are defaulted as well as the public instance data. Internal hash values are accessed directly (rather than through a method) and start with an underscore.

    This method should not be invoked by the user directly.

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 C constructor.

  • AddPreamble

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

    1.   \documentclass{article}
    2.   \usepackage[T1]{fontenc}
    3.   \usepackage{textcomp}
    4.   \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.

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

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

    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 C ending is written to the output file after the document has been processed. In its simplest form this is simply:

    1.   \end{document}

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

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

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

  • Head1Level

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

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

    Can be used to set or retrieve the current value:

    1.   $parser->Head1Level(2);
    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 C<=head3> do not have a corresponding C section (C<=head1> would correspond to a C).

    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 C

    ).

  • Label

    This is the label that is prefixed to all C label and index entries to make them unique. In general, pods have similarly titled sections (NAME, DESCRIPTION etc) and a C label will be multiply defined if more than one pod document is to be included in a single C 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, C<\label{text}> becomes C<\label{Label_text}>.

    Can be used to set or retrieve the current value:

    1.   $label = $parser->Label;
    2.   $parser->Label($label);

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

    Default value is C.

  • LevelNoNum

    Control the point at which C section numbering is turned off. For example, this can be used to make sure that C sections are numbered but subsections are not.

    Can be used to set or retrieve the current value:

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

    The argument must be an integer between 0 and 5 and is the same as the number described in C method description. The number has nothing to do with the pod heading number, only the C sectioning.

    Default is 2. (i.e. C subsections are written as C but sections are numbered).

  • MakeIndex

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

    1.   $makeindex = $parser->MakeIndex;
    2.   $parser->MakeIndex(0);

    Irrelevant if both C and C are false (or equivalently, C and C are set).

    Default is for an index to be created.

  • ReplaceNAMEwithSection

    This controls whether the C 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

    1.   =head1 NAME
    3.   pod::name - purpose
    5.   =head1 SYNOPSIS

    is converted to the C

    1.   \section{pod::name\label{pod_name}\index{pod::name}}
    3.   Purpose
    5.   \subsection*{SYNOPSIS\label{pod_name_SYNOPSIS}%
    6.                \index{pod::name!SYNOPSIS}}

    (dependent on the value of C and C). Note that subsequent C directives translate to subsections rather than sections and that the labels and index now include the pod name (dependent on the value of C).

    The C

    1.   $mod = $parser->ReplaceNAMEwithSection;
    2.   $parser->ReplaceNAMEwithSection(0);

    Default is to translate the pod literally.

  • StartWithNewPage

    If true, each pod translation will begin with a C C<\clearpage>.

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

    Default is false.

  • TableOfContents

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

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

    Default is false.

  • UniqueLabels

    If true, the translator will attempt to make sure that each C label or index entry will be uniquely identified by prefixing the contents of C

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

    Default is true.

  • UserPreamble

    User supplied C 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 C. C and C will also be ignored.

  • UserPostamble

    User supplied C 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 C. C will also be ignored.

  • Lists

    Contains details of the currently active lists. The array contains C objects. A new C object is created each time a list is encountered and it is pushed onto this stack. When the list context ends, it is popped from the stack. The array will be empty if no lists are active.

    Returns array of list information in list context Returns array ref in scalar context

Subclassed methods

The following methods override methods provided in the C base class. See C and C for more information on what these methods require.

  • begin_pod

    Writes the C preamble if requested. Only writes something if AddPreamble is true. Writes a standard header unless a UserPreamble is defined.

  • end_pod

    Write the closing C code. Only writes something if AddPostamble is true. Writes a standard header unless a UserPostamble is defined.

  • command

    Process basic pod commands.

  • verbatim

    Verbatim text

  • textblock

    Plain text paragraph.

  • interior_sequence

    Interior sequence expansion

List Methods

Methods used to handle lists.

  • begin_list

    Called when a new list is found (via the C directive). Creates a new C object and stores it on the list stack.

    1.   $parser->begin_list($indent, $line_num);
  • end_list

    Called when the end of a list is found (the C directive). Pops the C object off the stack of lists and writes the C code required to close a list.

    1.   $parser->end_list($line_num);
  • add_item

    Add items to the list. The first time an item is encountered (determined from the state of the current C object) the type of list is determined (ordered, unnumbered or description) and the relevant latex code issued.

    1.   $parser->add_item($paragraph, $line_num);

Methods for headings

  • head

    Print a heading of the required level.

    1.   $parser->head($level, $paragraph, $parobj);

    The first argument is the pod heading level. The second argument is the contents of the heading. The 3rd argument is a Pod::Paragraph object so that the line number can be extracted.

Internal methods

Internal routines are described in this section. They do not form part of the public interface. All private methods start with an underscore.

  • _output

    Output text to the output filehandle. This method must be always be called to output parsed text.

    1.    $parser->_output($text);

    Does not write anything if a =begin is active that should be ignored.

  • _replace_special_chars

    Subroutine to replace characters that are special in C with the escaped forms

    1.   $escaped = $parser->_replace_special_chars($paragraph);

    Need to call this routine before interior_sequences are munged but not if verbatim. It must be called before interpolation of interior sequences so that curly brackets and special latex characters inserted during interpolation are not themselves escaped. This means that < and > can not be modified here since the text still contains interior sequences.

    Special characters and the C equivalents are:

    1.   }     \}
    2.   {     \{
    3.   _     \_
    4.   $     \$
    5.   %     \%
    6.   &     \&
    7.   \     $\backslash$
    8.   ^     \^{}
    9.   ~     \~{}
    10.   #     \#
  • _replace_special_chars_late

    Replace special characters that can not be replaced before interior sequence interpolation. See C<_replace_special_chars> for a routine to replace special characters prior to interpolation of interior sequences.

    Does the following transformation:

    1.   <   $<$
    2.   >   $>$
    3.   |   $|$
  • _create_label

    Return a string that can be used as an internal reference in a C document (i.e. accepted by the C<\label> command)

    1.  $label = $parser->_create_label($string)

    If UniqueLabels is true returns a label prefixed by Label() This can be suppressed with an optional second argument.

    1.  $label = $parser->_create_label($string, $suppress);

    If a second argument is supplied (of any value including undef) the Label() is never prefixed. This means that this routine can be called to create a Label() without prefixing a previous setting.

  • _create_index

    Similar to C<_create_label> except an index entry is created. If C is true, the index entry is prefixed by the current C

    1.   $ind = $parser->_create_index($paragraph);

    An exclamation mark is used by C to generate sub-entries in an index.

  • _clean_latex_commands

    Removes latex commands from text. The latex command is assumed to be of the form C<\command{ text }>. "C" is retained

    1.   $clean = $parser->_clean_latex_commands($text);
  • _split_delimited

    Split the supplied string into two parts at approximately the specified word boundary. Special care is made to make sure that it does not split in the middle of some curly brackets.

    e.g. "this text is \textbf{very bold}" would not be split into "this text is \textbf{very" and " bold".

    1.   ($hunk1, $hunk2) = $self->_split_delimited( $para, $length);

    The length indicates the maximum length of hunk1.

NOTES

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

A subclass of C so that specific pod sections can be converted to C by using the C