mingw/html/lib/Pod/LaTeX.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>Pod::LaTeX - Convert Pod data to formatted Latex</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;Pod::LaTeX - Convert Pod data to formatted Latex</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <li><a href="#object_methods">OBJECT METHODS</a></li>
  26         <ul>
  27
  28                 <li><a href="#data_accessors">Data Accessors</a></li>
  29                 <li><a href="#subclassed_methods">Subclassed methods</a></li>
  30                 <li><a href="#list_methods">List Methods</a></li>
  31                 <li><a href="#methods_for_headings">Methods for headings</a></li>
  32                 <li><a href="#internal_methods">Internal methods</a></li>
  33         </ul>
  34
  35         <li><a href="#notes">NOTES</a></li>
  36         <li><a href="#see_also">SEE ALSO</a></li>
  37         <li><a href="#authors">AUTHORS</a></li>
  38         <li><a href="#copyright">COPYRIGHT</a></li>
  39         <li><a href="#revision">REVISION</a></li>
  40 </ul>
  41 <!-- INDEX END -->
  42
  43 <hr />
  44 <p>
  45 </p>
  46 <h1><a name="name">NAME</a></h1>
  47 <p>Pod::LaTeX - Convert Pod data to formatted Latex</p>
  48 <p>
  49 </p>
  50 <hr />
  51 <h1><a name="synopsis">SYNOPSIS</a></h1>
  52 <pre>
  53   use Pod::LaTeX;
  54   my $parser = Pod::LaTeX-&gt;new ( );</pre>
  55 <pre>
  56   $parser-&gt;parse_from_filehandle;</pre>
  57 <pre>
  58   $parser-&gt;parse_from_file ('file.pod', 'file.tex');</pre>
  59 <p>
  60 </p>
  61 <hr />
  62 <h1><a name="description">DESCRIPTION</a></h1>
  63 <p><code>Pod::LaTeX</code> is a module to convert documentation in the Pod format
  64 into Latex. The <a href="file://C|\msysgit\mingw\html/pod/pod2latex.html"><strong>pod2latex</strong></a>  command uses
  65 this module for translation.</p>
  66 <p><code>Pod::LaTeX</code> is a derived class from <a href="file://C|\msysgit\mingw\html/lib/Pod/Select.html">Pod::Select</a>.</p>
  67 <p>
  68 </p>
  69 <hr />
  70 <h1><a name="object_methods">OBJECT METHODS</a></h1>
  71 <p>The following methods are provided in this module. Methods inherited
  72 from <code>Pod::Select</code> are not described in the public interface.</p>
  73 <p>
  74 </p>
  75 <h2><a name="data_accessors">Data Accessors</a></h2>
  76 <p>The following methods are provided for accessing instance data. These
  77 methods should be used for accessing configuration parameters rather
  78 than assuming the object is a hash.</p>
  79 <p>Default values can be supplied by using these names as keys to a hash
  80 of arguments when using the <code>new()</code> constructor.</p>
  81 <dl>
  82 <dt><strong><a name="item_addpreamble"><strong>AddPreamble</strong></a></strong>
  83
  84 <dd>
  85 <p>Logical to control whether a <code>latex</code> preamble is to be written.
  86 If true, a valid <code>latex</code> preamble is written before the pod data is written.
  87 This is similar to:</p>
  88 </dd>
  89 <dd>
  90 <pre>
  91   \documentclass{article}
  92   \usepackage[T1]{fontenc}
  93   \usepackage{textcomp}
  94   \begin{document}</pre>
  95 </dd>
  96 <dd>
  97 <p>but will be more complicated if table of contents and indexing are required.
  98 Can be used to set or retrieve the current value.</p>
  99 </dd>
 100 <dd>
 101 <pre>
 102   $add = $parser-&gt;AddPreamble();
 103   $parser-&gt;AddPreamble(1);</pre>
 104 </dd>
 105 <dd>
 106 <p>If used in conjunction with <a href="#item_addpostamble"><code>AddPostamble</code></a> a full latex document will
 107 be written that could be immediately processed by <code>latex</code>.</p>
 108 </dd>
 109 <dd>
 110 <p>For some pod escapes it may be necessary to include the amsmath
 111 package. This is not yet added to the preamble automaatically.</p>
 112 </dd>
 113 </li>
 114 <dt><strong><a name="item_addpostamble"><strong>AddPostamble</strong></a></strong>
 115
 116 <dd>
 117 <p>Logical to control whether a standard <code>latex</code> ending is written to the output
 118 file after the document has been processed.
 119 In its simplest form this is simply:</p>
 120 </dd>
 121 <dd>
 122 <pre>
 123   \end{document}</pre>
 124 </dd>
 125 <dd>
 126 <p>but can be more complicated if a index is required.
 127 Can be used to set or retrieve the current value.</p>
 128 </dd>
 129 <dd>
 130 <pre>
 131   $add = $parser-&gt;AddPostamble();
 132   $parser-&gt;AddPostamble(1);</pre>
 133 </dd>
 134 <dd>
 135 <p>If used in conjunction with <code>AddPreaamble</code> a full latex document will
 136 be written that could be immediately processed by <code>latex</code>.</p>
 137 </dd>
 138 </li>
 139 <dt><strong><a name="item_head1level"><strong>Head1Level</strong></a></strong>
 140
 141 <dd>
 142 <p>The <code>latex</code> sectioning level that should be used to correspond to
 143 a pod <code>=head1</code> directive. This can be used, for example, to turn
 144 a <code>=head1</code> into a <code>latex</code> <code>subsection</code>. This should hold a number
 145 corresponding to the required position in an array containing the
 146 following elements:</p>
 147 </dd>
 148 <dd>
 149 <pre>
 150  [0] chapter
 151  [1] section
 152  [2] subsection
 153  [3] subsubsection
 154  [4] paragraph
 155  [5] subparagraph</pre>
 156 </dd>
 157 <dd>
 158 <p>Can be used to set or retrieve the current value:</p>
 159 </dd>
 160 <dd>
 161 <pre>
 162   $parser-&gt;Head1Level(2);
 163   $sect = $parser-&gt;Head1Level;</pre>
 164 </dd>
 165 <dd>
 166 <p>Setting this number too high can result in sections that may not be reproducible
 167 in the expected way. For example, setting this to 4 would imply that <code>=head3</code>
 168 do not have a corresponding <code>latex</code> section (<code>=head1</code> would correspond to
 169 a <code>paragraph</code>).</p>
 170 </dd>
 171 <dd>
 172 <p>A check is made to ensure that the supplied value is an integer in the
 173 range 0 to 5.</p>
 174 </dd>
 175 <dd>
 176 <p>Default is for a value of 1 (i.e. a <code>section</code>).</p>
 177 </dd>
 178 </li>
 179 <dt><strong><a name="item_label"><strong>Label</strong></a></strong>
 180
 181 <dd>
 182 <p>This is the label that is prefixed to all <code>latex</code> label and index
 183 entries to make them unique. In general, pods have similarly titled
 184 sections (NAME, DESCRIPTION etc) and a <code>latex</code> label will be multiply
 185 defined if more than one pod document is to be included in a single
 186 <code>latex</code> file. To overcome this, this label is prefixed to a label
 187 whenever a label is required (joined with an underscore) or to an
 188 index entry (joined by an exclamation mark which is the normal index
 189 separator). For example, <code>\label{text}</code> becomes <code>\label{Label_text}</code>.</p>
 190 </dd>
 191 <dd>
 192 <p>Can be used to set or retrieve the current value:</p>
 193 </dd>
 194 <dd>
 195 <pre>
 196   $label = $parser-&gt;Label;
 197   $parser-&gt;Label($label);</pre>
 198 </dd>
 199 <dd>
 200 <p>This label is only used if <a href="#item_uniquelabels"><code>UniqueLabels</code></a> is true.
 201 Its value is set automatically from the <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_name"><code>NAME</code></a> field
 202 if <a href="#item_replacenamewithsection"><code>ReplaceNAMEwithSection</code></a> is true. If this is not the case
 203 it must be set manually before starting the parse.</p>
 204 </dd>
 205 <dd>
 206 <p>Default value is <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a>.</p>
 207 </dd>
 208 </li>
 209 <dt><strong><a name="item_levelnonum"><strong>LevelNoNum</strong></a></strong>
 210
 211 <dd>
 212 <p>Control the point at which <code>latex</code> section numbering is turned off.
 213 For example, this can be used to make sure that <code>latex</code> sections
 214 are numbered but subsections are not.</p>
 215 </dd>
 216 <dd>
 217 <p>Can be used to set or retrieve the current value:</p>
 218 </dd>
 219 <dd>
 220 <pre>
 221   $lev = $parser-&gt;LevelNoNum;
 222   $parser-&gt;LevelNoNum(2);</pre>
 223 </dd>
 224 <dd>
 225 <p>The argument must be an integer between 0 and 5 and is the same as the
 226 number described in <a href="#item_head1level"><code>Head1Level</code></a> method description. The number has
 227 nothing to do with the pod heading number, only the <code>latex</code> sectioning.</p>
 228 </dd>
 229 <dd>
 230 <p>Default is 2. (i.e. <code>latex</code> subsections are written as <code>subsection*</code>
 231 but sections are numbered).</p>
 232 </dd>
 233 </li>
 234 <dt><strong><a name="item_makeindex"><strong>MakeIndex</strong></a></strong>
 235
 236 <dd>
 237 <p>Controls whether <code>latex</code> commands for creating an index are to be inserted
 238 into the preamble and postamble</p>
 239 </dd>
 240 <dd>
 241 <pre>
 242   $makeindex = $parser-&gt;MakeIndex;
 243   $parser-&gt;MakeIndex(0);</pre>
 244 </dd>
 245 <dd>
 246 <p>Irrelevant if both <a href="#item_addpreamble"><code>AddPreamble</code></a> and <a href="#item_addpostamble"><code>AddPostamble</code></a> are false (or equivalently,
 247 <a href="#item_userpreamble"><code>UserPreamble</code></a> and <a href="#item_userpostamble"><code>UserPostamble</code></a> are set).</p>
 248 </dd>
 249 <dd>
 250 <p>Default is for an index to be created.</p>
 251 </dd>
 252 </li>
 253 <dt><strong><a name="item_replacenamewithsection"><strong>ReplaceNAMEwithSection</strong></a></strong>
 254
 255 <dd>
 256 <p>This controls whether the <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_name"><code>NAME</code></a> section in the pod is to be translated
 257 literally or converted to a slightly modified output where the section
 258 name is the pod name rather than ``NAME''.</p>
 259 </dd>
 260 <dd>
 261 <p>If true, the pod segment</p>
 262 </dd>
 263 <dd>
 264 <pre>
 265   =head1 NAME</pre>
 266 </dd>
 267 <dd>
 268 <pre>
 269   pod::name - purpose</pre>
 270 </dd>
 271 <dd>
 272 <pre>
 273   =head1 SYNOPSIS</pre>
 274 </dd>
 275 <dd>
 276 <p>is converted to the <code>latex</code></p>
 277 </dd>
 278 <dd>
 279 <pre>
 280   \section{pod::name\label{pod_name}\index{pod::name}}</pre>
 281 </dd>
 282 <dd>
 283 <pre>
 284   Purpose</pre>
 285 </dd>
 286 <dd>
 287 <pre>
 288   \subsection*{SYNOPSIS\label{pod_name_SYNOPSIS}%
 289                \index{pod::name!SYNOPSIS}}</pre>
 290 </dd>
 291 <dd>
 292 <p>(dependent on the value of <a href="#item_head1level"><code>Head1Level</code></a> and <a href="#item_levelnonum"><code>LevelNoNum</code></a>). Note that
 293 subsequent <code>head1</code> directives translate to subsections rather than
 294 sections and that the labels and index now include the pod name (dependent
 295 on the value of <a href="#item_uniquelabels"><code>UniqueLabels</code></a>).</p>
 296 </dd>
 297 <dd>
 298 <p>The <a href="#item_label"><code>Label</code></a> is set from the pod name regardless of any current value
 299 of <a href="#item_label"><code>Label</code></a>.</p>
 300 </dd>
 301 <dd>
 302 <pre>
 303   $mod = $parser-&gt;ReplaceNAMEwithSection;
 304   $parser-&gt;ReplaceNAMEwithSection(0);</pre>
 305 </dd>
 306 <dd>
 307 <p>Default is to translate the pod literally.</p>
 308 </dd>
 309 </li>
 310 <dt><strong><a name="item_startwithnewpage"><strong>StartWithNewPage</strong></a></strong>
 311
 312 <dd>
 313 <p>If true, each pod translation will begin with a <code>latex</code>
 314 <code>\clearpage</code>.</p>
 315 </dd>
 316 <dd>
 317 <pre>
 318   $parser-&gt;StartWithNewPage(1);
 319   $newpage = $parser-&gt;StartWithNewPage;</pre>
 320 </dd>
 321 <dd>
 322 <p>Default is false.</p>
 323 </dd>
 324 </li>
 325 <dt><strong><a name="item_tableofcontents"><strong>TableOfContents</strong></a></strong>
 326
 327 <dd>
 328 <p>If true, a table of contents will be created.
 329 Irrelevant if <a href="#item_addpreamble"><code>AddPreamble</code></a> is false or <a href="#item_userpreamble"><code>UserPreamble</code></a>
 330 is set.</p>
 331 </dd>
 332 <dd>
 333 <pre>
 334   $toc = $parser-&gt;TableOfContents;
 335   $parser-&gt;TableOfContents(1);</pre>
 336 </dd>
 337 <dd>
 338 <p>Default is false.</p>
 339 </dd>
 340 </li>
 341 <dt><strong><a name="item_uniquelabels"><strong>UniqueLabels</strong></a></strong>
 342
 343 <dd>
 344 <p>If true, the translator will attempt to make sure that
 345 each <code>latex</code> label or index entry will be uniquely identified
 346 by prefixing the contents of <a href="#item_label"><code>Label</code></a>. This allows
 347 multiple documents to be combined without clashing
 348 common labels such as <code>DESCRIPTION</code> and <code>SYNOPSIS</code></p>
 349 </dd>
 350 <dd>
 351 <pre>
 352   $parser-&gt;UniqueLabels(1);
 353   $unq = $parser-&gt;UniqueLabels;</pre>
 354 </dd>
 355 <dd>
 356 <p>Default is true.</p>
 357 </dd>
 358 </li>
 359 <dt><strong><a name="item_userpreamble"><strong>UserPreamble</strong></a></strong>
 360
 361 <dd>
 362 <p>User supplied <code>latex</code> preamble. Added before the pod translation
 363 data.</p>
 364 </dd>
 365 <dd>
 366 <p>If set, the contents will be prepended to the output file before the translated
 367 data regardless of the value of <a href="#item_addpreamble"><code>AddPreamble</code></a>.
 368 <a href="#item_makeindex"><code>MakeIndex</code></a> and <a href="#item_tableofcontents"><code>TableOfContents</code></a> will also be ignored.</p>
 369 </dd>
 370 </li>
 371 <dt><strong><a name="item_userpostamble"><strong>UserPostamble</strong></a></strong>
 372
 373 <dd>
 374 <p>User supplied <code>latex</code> postamble. Added after the pod translation
 375 data.</p>
 376 </dd>
 377 <dd>
 378 <p>If set, the contents will be prepended to the output file after the translated
 379 data regardless of the value of <a href="#item_addpostamble"><code>AddPostamble</code></a>.
 380 <a href="#item_makeindex"><code>MakeIndex</code></a> will also be ignored.</p>
 381 </dd>
 382 </li>
 383 </dl>
 384 <p>
 385 </p>
 386 <hr />
 387 <h1><a name="notes">NOTES</a></h1>
 388 <p>Compatible with <code>latex2e</code> only. Can not be used with <code>latex</code> v2.09
 389 or earlier.</p>
 390 <p>A subclass of <code>Pod::Select</code> so that specific pod sections can be
 391 converted to <code>latex</code> by using the <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_select"><code>select</code></a> method.</p>
 392 <p>Some HTML escapes are missing and many have not been tested.</p>
 393 <p>
 394 </p>
 395 <hr />
 396 <h1><a name="see_also">SEE ALSO</a></h1>
 397 <p><a href="file://C|\msysgit\mingw\html/lib/Pod/Parser.html">the Pod::Parser manpage</a>, <a href="file://C|\msysgit\mingw\html/lib/Pod/Select.html">the Pod::Select manpage</a>, <a href="file://C|\msysgit\mingw\html/pod/pod2latex.html">the pod2latex manpage</a></p>
 398 <p>
 399 </p>
 400 <hr />
 401 <h1><a name="authors">AUTHORS</a></h1>
 402 <p>Tim Jenness &lt;<a href="mailto:tjenness@cpan.org">tjenness@cpan.org</a>&gt;</p>
 403 <p>Bug fixes and improvements have been received from: Simon Cozens
 404 &lt;<a href="mailto:simon@cozens.net">simon@cozens.net</a>&gt;, Mark A. Hershberger
 405 &lt;<a href="mailto:mah@everybody.org">mah@everybody.org</a>&gt;, Marcel Grunauer
 406 &lt;<a href="mailto:marcel@codewerk.com">marcel@codewerk.com</a>&gt;, Hugh S Myers
 407 &lt;<a href="mailto:hsmyers@sdragons.com">hsmyers@sdragons.com</a>&gt;, Peter J Acklam
 408 &lt;<a href="mailto:jacklam@math.uio.no">jacklam@math.uio.no</a>&gt;, Sudhi Herle &lt;<a href="mailto:sudhi@herle.net">sudhi@herle.net</a>&gt;,
 409 Ariel Scolnicov &lt;<a href="mailto:ariels@compugen.co.il">ariels@compugen.co.il</a>&gt;,
 410 Adriano Rodrigues Ferreira &lt;<a href="mailto:ferreira@triang.com.br">ferreira@triang.com.br</a>&gt; and
 411 R. de Vries &lt;<a href="mailto:r.de.vries@dutchspace.nl">r.de.vries@dutchspace.nl</a>&gt;.</p>
 412 <p>
 413 </p>
 414 <hr />
 415 <h1><a name="copyright">COPYRIGHT</a></h1>
 416 <p>Copyright (C) 2000-2004 Tim Jenness. All Rights Reserved.</p>
 417 <p>This program is free software; you can redistribute it and/or modify
 418 it under the same terms as Perl itself.</p>
 419 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 420 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 421 <big><strong><span class="block">&nbsp;Pod::LaTeX - Convert Pod data to formatted Latex</span></strong></big>
 422 </td></tr>
 423 </table>
 424
 425 </body>
 426
 427 </html>