Initial commit of OpenSPARC T2 architecture model.

[OpenSPARC-T2-SAM] / sam-t2 / devtools / v9 / man / man3 / Pod::LaTeX.3

.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Pod::LaTeX 3"
.TH Pod::LaTeX 3 "2001-09-21" "perl v5.8.8" "Perl Programmers Reference Guide"
.SH "NAME"
Pod::LaTeX \- Convert Pod data to formatted Latex
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use Pod::LaTeX;
\&  my $parser = Pod::LaTeX->new ( );
.Ve
.PP
.Vb 1
\&  $parser->parse_from_filehandle;
.Ve
.PP
.Vb 1
\&  $parser->parse_from_file ('file.pod', 'file.tex');
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Pod::LaTeX\*(C'\fR is a module to convert documentation in the Pod format
into Latex. The \fBpod2latex\fR  command uses
this module for translation.
.IX Xref "pod2latex"
.PP
\&\f(CW\*(C`Pod::LaTeX\*(C'\fR is a derived class from Pod::Select.
.SH "OBJECT METHODS"
.IX Header "OBJECT METHODS"
The following methods are provided in this module. Methods inherited
from \f(CW\*(C`Pod::Select\*(C'\fR are not described in the public interface.
.Sh "Data Accessors"
.IX Subsection "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.
.PP
Default values can be supplied by using these names as keys to a hash
of arguments when using the \f(CW\*(C`new()\*(C'\fR constructor.
.IP "\fBAddPreamble\fR" 4
.IX Item "AddPreamble"
Logical to control whether a \f(CW\*(C`latex\*(C'\fR preamble is to be written.
If true, a valid \f(CW\*(C`latex\*(C'\fR preamble is written before the pod data is written.
This is similar to:
.Sp
.Vb 4
\&  \edocumentclass{article}
\&  \eusepackage[T1]{fontenc}
\&  \eusepackage{textcomp}
\&  \ebegin{document}
.Ve
.Sp
but will be more complicated if table of contents and indexing are required.
Can be used to set or retrieve the current value.
.Sp
.Vb 2
\&  $add = $parser->AddPreamble();
\&  $parser->AddPreamble(1);
.Ve
.Sp
If used in conjunction with \f(CW\*(C`AddPostamble\*(C'\fR a full latex document will
be written that could be immediately processed by \f(CW\*(C`latex\*(C'\fR.
.Sp
For some pod escapes it may be necessary to include the amsmath
package. This is not yet added to the preamble automaatically.
.IP "\fBAddPostamble\fR" 4
.IX Item "AddPostamble"
Logical to control whether a standard \f(CW\*(C`latex\*(C'\fR ending is written to the output
file after the document has been processed.
In its simplest form this is simply:
.Sp
.Vb 1
\&  \eend{document}
.Ve
.Sp
but can be more complicated if a index is required.
Can be used to set or retrieve the current value.
.Sp
.Vb 2
\&  $add = $parser->AddPostamble();
\&  $parser->AddPostamble(1);
.Ve
.Sp
If used in conjunction with \f(CW\*(C`AddPreaamble\*(C'\fR a full latex document will
be written that could be immediately processed by \f(CW\*(C`latex\*(C'\fR.
.IP "\fBHead1Level\fR" 4
.IX Item "Head1Level"
The \f(CW\*(C`latex\*(C'\fR sectioning level that should be used to correspond to
a pod \f(CW\*(C`=head1\*(C'\fR directive. This can be used, for example, to turn
a \f(CW\*(C`=head1\*(C'\fR into a \f(CW\*(C`latex\*(C'\fR \f(CW\*(C`subsection\*(C'\fR. This should hold a number
corresponding to the required position in an array containing the
following elements:
.Sp
.Vb 6
\& [0] chapter
\& [1] section
\& [2] subsection
\& [3] subsubsection
\& [4] paragraph
\& [5] subparagraph
.Ve
.Sp
Can be used to set or retrieve the current value:
.Sp
.Vb 2
\&  $parser->Head1Level(2);
\&  $sect = $parser->Head1Level;
.Ve
.Sp
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 \f(CW\*(C`=head3\*(C'\fR
do not have a corresponding \f(CW\*(C`latex\*(C'\fR section (\f(CW\*(C`=head1\*(C'\fR would correspond to
a \f(CW\*(C`paragraph\*(C'\fR).
.Sp
A check is made to ensure that the supplied value is an integer in the
range 0 to 5.
.Sp
Default is for a value of 1 (i.e. a \f(CW\*(C`section\*(C'\fR).
.IP "\fBLabel\fR" 4
.IX Item "Label"
This is the label that is prefixed to all \f(CW\*(C`latex\*(C'\fR label and index
entries to make them unique. In general, pods have similarly titled
sections (\s-1NAME\s0, \s-1DESCRIPTION\s0 etc) and a \f(CW\*(C`latex\*(C'\fR label will be multiply
defined if more than one pod document is to be included in a single
\&\f(CW\*(C`latex\*(C'\fR 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, \f(CW\*(C`\elabel{text}\*(C'\fR becomes \f(CW\*(C`\elabel{Label_text}\*(C'\fR.
.Sp
Can be used to set or retrieve the current value:
.Sp
.Vb 2
\&  $label = $parser->Label;
\&  $parser->Label($label);
.Ve
.Sp
This label is only used if \f(CW\*(C`UniqueLabels\*(C'\fR is true.
Its value is set automatically from the \f(CW\*(C`NAME\*(C'\fR field
if \f(CW\*(C`ReplaceNAMEwithSection\*(C'\fR is true. If this is not the case
it must be set manually before starting the parse.
.Sp
Default value is \f(CW\*(C`undef\*(C'\fR.
.IP "\fBLevelNoNum\fR" 4
.IX Item "LevelNoNum"
Control the point at which \f(CW\*(C`latex\*(C'\fR section numbering is turned off.
For example, this can be used to make sure that \f(CW\*(C`latex\*(C'\fR sections
are numbered but subsections are not.
.Sp
Can be used to set or retrieve the current value:
.Sp
.Vb 2
\&  $lev = $parser->LevelNoNum;
\&  $parser->LevelNoNum(2);
.Ve
.Sp
The argument must be an integer between 0 and 5 and is the same as the
number described in \f(CW\*(C`Head1Level\*(C'\fR method description. The number has
nothing to do with the pod heading number, only the \f(CW\*(C`latex\*(C'\fR sectioning.
.Sp
Default is 2. (i.e. \f(CW\*(C`latex\*(C'\fR subsections are written as \f(CW\*(C`subsection*\*(C'\fR
but sections are numbered).
.IP "\fBMakeIndex\fR" 4
.IX Item "MakeIndex"
Controls whether \f(CW\*(C`latex\*(C'\fR commands for creating an index are to be inserted
into the preamble and postamble
.Sp
.Vb 2
\&  $makeindex = $parser->MakeIndex;
\&  $parser->MakeIndex(0);
.Ve
.Sp
Irrelevant if both \f(CW\*(C`AddPreamble\*(C'\fR and \f(CW\*(C`AddPostamble\*(C'\fR are false (or equivalently,
\&\f(CW\*(C`UserPreamble\*(C'\fR and \f(CW\*(C`UserPostamble\*(C'\fR are set).
.Sp
Default is for an index to be created.
.IP "\fBReplaceNAMEwithSection\fR" 4
.IX Item "ReplaceNAMEwithSection"
This controls whether the \f(CW\*(C`NAME\*(C'\fR 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 \*(L"\s-1NAME\s0\*(R".
.Sp
If true, the pod segment
.Sp
.Vb 1
\&  =head1 NAME
.Ve
.Sp
.Vb 1
\&  pod::name - purpose
.Ve
.Sp
.Vb 1
\&  =head1 SYNOPSIS
.Ve
.Sp
is converted to the \f(CW\*(C`latex\*(C'\fR
.Sp
.Vb 1
\&  \esection{pod::name\elabel{pod_name}\eindex{pod::name}}
.Ve
.Sp
.Vb 1
\&  Purpose
.Ve
.Sp
.Vb 2
\&  \esubsection*{SYNOPSIS\elabel{pod_name_SYNOPSIS}%
\&               \eindex{pod::name!SYNOPSIS}}
.Ve
.Sp
(dependent on the value of \f(CW\*(C`Head1Level\*(C'\fR and \f(CW\*(C`LevelNoNum\*(C'\fR). Note that
subsequent \f(CW\*(C`head1\*(C'\fR directives translate to subsections rather than
sections and that the labels and index now include the pod name (dependent
on the value of \f(CW\*(C`UniqueLabels\*(C'\fR).
.Sp
The \f(CW\*(C`Label\*(C'\fR is set from the pod name regardless of any current value
of \f(CW\*(C`Label\*(C'\fR.
.Sp
.Vb 2
\&  $mod = $parser->ReplaceNAMEwithSection;
\&  $parser->ReplaceNAMEwithSection(0);
.Ve
.Sp
Default is to translate the pod literally.
.IP "\fBStartWithNewPage\fR" 4
.IX Item "StartWithNewPage"
If true, each pod translation will begin with a \f(CW\*(C`latex\*(C'\fR
\&\f(CW\*(C`\eclearpage\*(C'\fR.
.Sp
.Vb 2
\&  $parser->StartWithNewPage(1);
\&  $newpage = $parser->StartWithNewPage;
.Ve
.Sp
Default is false.
.IP "\fBTableOfContents\fR" 4
.IX Item "TableOfContents"
If true, a table of contents will be created.
Irrelevant if \f(CW\*(C`AddPreamble\*(C'\fR is false or \f(CW\*(C`UserPreamble\*(C'\fR
is set.
.Sp
.Vb 2
\&  $toc = $parser->TableOfContents;
\&  $parser->TableOfContents(1);
.Ve
.Sp
Default is false.
.IP "\fBUniqueLabels\fR" 4
.IX Item "UniqueLabels"
If true, the translator will attempt to make sure that
each \f(CW\*(C`latex\*(C'\fR label or index entry will be uniquely identified
by prefixing the contents of \f(CW\*(C`Label\*(C'\fR. This allows
multiple documents to be combined without clashing 
common labels such as \f(CW\*(C`DESCRIPTION\*(C'\fR and \f(CW\*(C`SYNOPSIS\*(C'\fR
.Sp
.Vb 2
\&  $parser->UniqueLabels(1);
\&  $unq = $parser->UniqueLabels;
.Ve
.Sp
Default is true.
.IP "\fBUserPreamble\fR" 4
.IX Item "UserPreamble"
User supplied \f(CW\*(C`latex\*(C'\fR preamble. Added before the pod translation
data. 
.Sp
If set, the contents will be prepended to the output file before the translated 
data regardless of the value of \f(CW\*(C`AddPreamble\*(C'\fR.
\&\f(CW\*(C`MakeIndex\*(C'\fR and \f(CW\*(C`TableOfContents\*(C'\fR will also be ignored.
.IP "\fBUserPostamble\fR" 4
.IX Item "UserPostamble"
User supplied \f(CW\*(C`latex\*(C'\fR postamble. Added after the pod translation
data. 
.Sp
If set, the contents will be prepended to the output file after the translated 
data regardless of the value of \f(CW\*(C`AddPostamble\*(C'\fR.
\&\f(CW\*(C`MakeIndex\*(C'\fR will also be ignored.
.SH "NOTES"
.IX Header "NOTES"
Compatible with \f(CW\*(C`latex2e\*(C'\fR only. Can not be used with \f(CW\*(C`latex\*(C'\fR v2.09
or earlier.
.PP
A subclass of \f(CW\*(C`Pod::Select\*(C'\fR so that specific pod sections can be
converted to \f(CW\*(C`latex\*(C'\fR by using the \f(CW\*(C`select\*(C'\fR method.
.PP
Some \s-1HTML\s0 escapes are missing and many have not been tested.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Pod::Parser, Pod::Select, pod2latex
.SH "AUTHORS"
.IX Header "AUTHORS"
Tim Jenness <tjenness@cpan.org>
.PP
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>.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2000\-2004 Tim Jenness. All Rights Reserved.
.PP
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.