This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Pod/Hlp, Next: Pod/Html, Prev: Pod/HTML_Elements, Up: Module List convert POD data to formatted VMS HLP Help module text. ******************************************************* NAME ==== Pod::Hlp - convert POD data to formatted VMS HLP Help module text. SYNOPSIS ======== use Pod::Hlp; pod2hlp("perlfunc.pod",$top_help_level,*Filehandle); Also: pod2hlp < input.pod Also: perl pod2hlb DESCRIPTION =========== Pod::Hlp is a module that can convert documentation in the POD format (such as can be found throughout the Perl distribution) into formatted VMS `*.HLP' files. Such files can be inserted into an .HLB library through the `LIBRARY/HELP/REPLACE' system call, or via the use of the `pod2hlb' script supplied with the kit. A separate `pod2hlp' program is included that is primarily a wrapper for Pod::Hlp. The single function `pod2hlp()' can take one, two, or three arguments. The first should be the name of a file to read the pod from, or "<&STDIN" to read from STDIN. A second argument, if provided, should be an integer indicating the help header level of the file as a whole where `'1'' is the default. A third argument, if provided, should be a filehandle glob where output should be sent. AUTHOR ====== Peter Prymmer based heavily on Pod::Text by: Tom Christiansen TODO ==== Cleanup work. VT escapes should be substituted for the Term::Cap ones. The input and output locations need to be more flexible.  File: pm.info, Node: Pod/Html, Next: Pod/HtmlPsPdf, Prev: Pod/Hlp, Up: Module List module to convert pod files to HTML *********************************** NAME ==== Pod::Html - module to convert pod files to HTML SYNOPSIS ======== use Pod::Html; pod2html([options]); DESCRIPTION =========== Converts files from pod format (see *Note Perlpod: (perl.info)perlpod,) to HTML format. It can automatically generate indexes and cross-references, and it keeps a cache of things it knows how to cross-reference. ARGUMENTS ========= Pod::Html takes the following arguments: backlink --backlink="Back to Top" Adds "Back to Top" links in front of every HEAD1 heading (except for the first). By default, no backlink are being generated. css --css=stylesheet Specify the URL of a cascading style sheet. flush --flush Flushes the item and directory caches. header --header --noheader Creates header and footer blocks containing the text of the NAME section. By default, no headers are being generated. help --help Displays the usage message. htmldir --htmldir=name Sets the directory in which the resulting HTML file is placed. This is used to generate relative links to other files. Not passing this causes all links to be absolute, since this is the value that tells Pod::Html the root of the documentation tree. htmlroot --htmlroot=name Sets the base URL for the HTML files. When cross-references are made, the HTML root is prepended to the URL. index --index --noindex Generate an index at the top of the HTML file. This is the default behaviour. infile --infile=name Specify the pod file to convert. Input is taken from STDIN if no infile is specified. libpods --libpods=name:...:name List of page names (eg, "perlfunc") which contain linkable =items. netscape --netscape --nonetscape Use Netscape HTML directives when applicable. By default, they will not be used. outfile --outfile=name Specify the HTML file to create. Output goes to STDOUT if no outfile is specified. podpath --podpath=name:...:name Specify which subdirectories of the podroot contain pod files whose HTML converted forms can be linked-to in cross-references. podroot --podroot=name Specify the base directory for finding library pods. quiet --quiet --noquiet Don't display *mostly harmless* warning messages. These messages will be displayed by default. But this is not the same as verbose mode. recurse --recurse --norecurse Recurse into subdirectories specified in podpath (default behaviour). title --title=title Specify the title of the resulting HTML file. verbose --verbose --noverbose Display progress messages. By default, they won't be displayed. EXAMPLE ======= pod2html("pod2html", "--podpath=lib:ext:pod:vms", "--podroot=/usr/src/perl", "--htmlroot=/perl/nmanual", "--libpods=perlfunc:perlguts:perlvar:perlrun:perlop", "--recurse", "--infile=foo.pod", "--outfile=/perl/nmanual/foo.html"); ENVIRONMENT =========== Uses $Config{pod2html} to setup default options. AUTHOR ====== Tom Christiansen, . SEE ALSO ======== *Note Perlpod: (perl.info)perlpod, COPYRIGHT ========= This program is distributed under the Artistic License.  File: pm.info, Node: Pod/HtmlPsPdf, Next: Pod/HtmlPsPdf/Html, Prev: Pod/Html, Up: Module List documentation projects builder in HTML, PS and PDF formats ********************************************************** NAME ==== Pod::HtmlPsPdf - documentation projects builder in HTML, PS and PDF formats SYNOPSIS ======== pod2hpp [options] configuration_file_location Options: -h this help -v verbose -i podify pseudo-pod items (s/^* /=item */) -s create the splitted html version -t create tar.gz -p generate PS file -d generate PDF file -f force a complete rebuild -a print available hypertext anchors -l do hypertext links validation -e slides mode (for presentations) -m executed from Makefile (forces rebuild, no PS/PDF file, no tgz archive!) DESCRIPTION =========== This code knows to do following with a collection of your POD files. 1. Generate HTMLs 2. Generate a split version HTML, creating html file for each pod section, and having everything interlinked of course. This version is used best for the search. 3. Generate a single book-like version in PostScript format 4. Generate a single book-like version in PDF format 5. Complete the POD on the fly from the files in POD format. This is used to ease the generating of the presentations slides, so one can use * instead of a long =over/=item/.../=item/=back strings. The rest is done as before. Take a look at the special version of the html2ps format to generate nice slides in *conf/html2ps-slides.conf*. 6. If you turn the slides mode on, it automatically turns the -i (* preprocessing) mode and does a page break before each =head tag. You can customise the look and feel of the HTML files, PS and therefore the PDF by tweaking the template files in *./tmpl* directory. You can change look and feel of the PS (PDF) versions by modifying *./conf/html2ps.conf*. Be careful that if your documentation that you want to put in one PS or PDF file is very big and you tell html2ps to put the TOC at the beginning you will need lots of memory because it won't write a single byte to the disk before it gets all the HTML markup converted to PS. To generate HTML this code use a slightly modified version of the Pod::Html code and than does a lot of massage on the resulting HTML. I've tried to keep the pod2html code modified as little as possible, so when a new versions of the original Pod::Html module will be released I'll be able to merge the changes with my version. EXTENDED POD SYNTAX =================== I've extended the POD syntax to accomodate my own needs. Note that this can be always converted back to the standard POD. To see the extended syntax, refer to the *docs/extended_pod.pod* in the package distribution. CONFIGURATION ============= All you have to prepare is a single config file that you then pass as an argument to `pod2hpp': pod2hpp [options] /full/path/to/config/file Use the file *project.config* supplied in the directory sample. Modify it to be suit your documentation project layout. Note that *sample/bin/build* script automatically locates your project's directory, so you can move your project around filesystem without changing anything. *sample/README.sample* explains the layout of the directories. The easiest way to learn to use this package is to look at the `Apache::mod_perl_guide' package available at CPAN. I've developed the package `Pod::HtmlPsPdf' especially for `Apache::mod_perl_guide'. PREREQUISITES ============= All these are not required if all you want is to generate only the html version. * ps2pdf Needed to generate the PDF version * Storable Perl module available from CPAN (http://cpan.org/) Allows source modification control, so if you modify only one file you will not have to rebuild everything to get the updated HTML/PS/PDF files. SUPPORT ======= Notice that this tool relies on two tools (ps2pdf and html2ps) which I don't support. So if you have any problem first make sure that it's not a problem of these tools. Note that while `html2ps' is included in this distribution, it's written in the old style Perl, so if you have patches send them along, but I won't try to fix/modify this code otherwise. I didn't write this utility. This package works for me on Linux RedHat and Mandrake systems. I release it only to share. Unfortunately I don't have time to help with each available platform. If you have a problem, please don't contact me. I'm not going to solve it. If you solve the problem, I'll gladly accept the patch for others to benefit. Remember that this is a free software. BUGS ==== Huh? Probably many... AUTHOR ====== Stas Bekman SEE ALSO ======== perl(1), Pod::HTML(3), html2ps(1), ps2pod(1), Storable(3) COPYRIGHT ========= This program is distributed under the Artistic License, like the Perl itself.  File: pm.info, Node: Pod/HtmlPsPdf/Html, Next: Pod/InputObjects, Prev: Pod/HtmlPsPdf, Up: Module List module to convert pod files to HTML *********************************** NAME ==== Pod::Html - module to convert pod files to HTML SYNOPSIS ======== use Pod::Html; pod2html([options]); DESCRIPTION =========== Converts files from pod format (see *Note Perlpod: (perl.info)perlpod,) to HTML format. It can automatically generate indexes and cross-references, and it keeps a cache of things it knows how to cross-reference. ARGUMENTS ========= Pod::Html takes the following arguments: help --help Displays the usage message. htmlroot --htmlroot=name Sets the base URL for the HTML files. When cross-references are made, the HTML root is prepended to the URL. infile --infile=name Specify the pod file to convert. Input is taken from STDIN if no infile is specified. outfile --outfile=name Specify the HTML file to create. Output goes to STDOUT if no outfile is specified. podroot --podroot=name Specify the base directory for finding library pods. podpath --podpath=name:...:name Specify which subdirectories of the podroot contain pod files whose HTML converted forms can be linked-to in cross-references. libpods --libpods=name:...:name List of page names (eg, "perlfunc") which contain linkable =items. netscape --netscape Use Netscape HTML directives when applicable. nonetscape --nonetscape Do not use Netscape HTML directives (default). index --index Generate an index at the top of the HTML file (default behaviour). noindex --noindex Do not generate an index at the top of the HTML file. recurse --recurse Recurse into subdirectories specified in podpath (default behaviour). norecurse --norecurse Do not recurse into subdirectories specified in podpath. title --title=title Specify the title of the resulting HTML file. verbose --verbose Display progress messages. EXAMPLE ======= pod2html("pod2html", "--podpath=lib:ext:pod:vms", "--podroot=/usr/src/perl", "--htmlroot=/perl/nmanual", "--libpods=perlfunc:perlguts:perlvar:perlrun:perlop", "--recurse", "--infile=foo.pod", "--outfile=/perl/nmanual/foo.html"); AUTHOR ====== Originally written by Tom Christiansen, . Modified by Stas Bekman . BUGS ==== Has trouble with etc in = commands. SEE ALSO ======== *Note Perlpod: (perl.info)perlpod, COPYRIGHT ========= This program is distributed under the Artistic License.  File: pm.info, Node: Pod/InputObjects, Next: Pod/LaTeX, Prev: Pod/HtmlPsPdf/Html, Up: Module List objects representing POD input paragraphs, commands, etc. ********************************************************* NAME ==== Pod::InputObjects - objects representing POD input paragraphs, commands, etc. SYNOPSIS ======== use Pod::InputObjects; REQUIRES ======== perl5.004, Carp EXPORTS ======= Nothing. DESCRIPTION =========== This module defines some basic input objects used by Pod::Parser when reading and parsing POD text from an input source. The following objects are defined: Pod::InputSource An object corresponding to a source of POD input text. It is mostly a wrapper around a filehandle or IO::Handle-type object (or anything that implements the `getline()' method) which keeps track of some additional information relevant to the parsing of PODs. Pod::Paragraph An object corresponding to a paragraph of POD input text. It may be a plain paragraph, a verbatim paragraph, or a command paragraph (see *Note Perlpod: (perl.info)perlpod,). Pod::InteriorSequence An object corresponding to an interior sequence command from the POD input text (see *Note Perlpod: (perl.info)perlpod,). Pod::ParseTree An object corresponding to a tree of parsed POD text. Each "node" in a parse-tree (or *ptree*) is either a text-string or a reference to a Pod::InteriorSequence object. The nodes appear in the parse-tree in they order in which they were parsed from left-to-right. Each of these input objects are described in further detail in the sections which follow. Pod::InputSource ================ This object corresponds to an input source or stream of POD documentation. When parsing PODs, it is necessary to associate and store certain context information with each input source. All of this information is kept together with the stream itself in one of these Pod::InputSource objects. Each such object is merely a wrapper around an IO::Handle object of some kind (or at least something that implements the `getline()' method). They have the following methods/attributes: new() ----- my $pod_input1 = Pod::InputSource->new(-handle => $filehandle); my $pod_input2 = new Pod::InputSource(-handle => $filehandle, -name => $name); my $pod_input3 = new Pod::InputSource(-handle => \*STDIN); my $pod_input4 = Pod::InputSource->new(-handle => \*STDIN, -name => "(STDIN)"); This is a class method that constructs a Pod::InputSource object and returns a reference to the new input source object. It takes one or more keyword arguments in the form of a hash. The keyword `-handle' is required and designates the corresponding input handle. The keyword `-name' is optional and specifies the name associated with the input handle (typically a file name). name() ------ my $filename = $pod_input->name(); $pod_input->name($new_filename_to_use); This method gets/sets the name of the input source (usually a filename). If no argument is given, it returns a string containing the name of the input source; otherwise it sets the name of the input source to the contents of the given argument. handle() -------- my $handle = $pod_input->handle(); Returns a reference to the handle object from which input is read (the one used to contructed this input source object). was_cutting() ------------- print "Yes.\n" if ($pod_input->was_cutting()); The value of the `cutting' state (that the cutting() method would have returned) immediately before any input was read from this input stream. After all input from this stream has been read, the `cutting' state is restored to this value. Pod::Paragraph ============== An object representing a paragraph of POD input text. It has the following methods/attributes: new() ----- my $pod_para1 = Pod::Paragraph->new(-text => $text); my $pod_para2 = Pod::Paragraph->new(-name => $cmd, -text => $text); my $pod_para3 = new Pod::Paragraph(-text => $text); my $pod_para4 = new Pod::Paragraph(-name => $cmd, -text => $text); my $pod_para5 = Pod::Paragraph->new(-name => $cmd, -text => $text, -file => $filename, -line => $line_number); This is a class method that constructs a Pod::Paragraph object and returns a reference to the new paragraph object. It may be given one or two keyword arguments. The `-text' keyword indicates the corresponding text of the POD paragraph. The `-name' keyword indicates the name of the corresponding POD command, such as head1 or item (it should not contain the = prefix); this is needed only if the POD paragraph corresponds to a command paragraph. The `-file' and `-line' keywords indicate the filename and line number corresponding to the beginning of the paragraph cmd_name() ---------- my $para_cmd = $pod_para->cmd_name(); If this paragraph is a command paragraph, then this method will return the name of the command (*without* any leading = prefix). text() ------ my $para_text = $pod_para->text(); This method will return the corresponding text of the paragraph. raw_text() ---------- my $raw_pod_para = $pod_para->raw_text(); This method will return the raw text of the POD paragraph, exactly as it appeared in the input. cmd_prefix() ------------ my $prefix = $pod_para->cmd_prefix(); If this paragraph is a command paragraph, then this method will return the prefix used to denote the command (which should be the string "=" or "=="). cmd_separator() --------------- my $separator = $pod_para->cmd_separator(); If this paragraph is a command paragraph, then this method will return the text used to separate the command name from the rest of the paragraph (if any). parse_tree() ------------ my $ptree = $pod_parser->parse_text( $pod_para->text() ); $pod_para->parse_tree( $ptree ); $ptree = $pod_para->parse_tree(); This method will get/set the corresponding parse-tree of the paragraph's text. file_line() ----------- my ($filename, $line_number) = $pod_para->file_line(); my $position = $pod_para->file_line(); Returns the current filename and line number for the paragraph object. If called in an array context, it returns a list of two elements: first the filename, then the line number. If called in a scalar context, it returns a string containing the filename, followed by a colon (':'), followed by the line number. Pod::InteriorSequence ===================== An object representing a POD interior sequence command. It has the following methods/attributes: new() ----- my $pod_seq1 = Pod::InteriorSequence->new(-name => $cmd -ldelim => $delimiter); my $pod_seq2 = new Pod::InteriorSequence(-name => $cmd, -ldelim => $delimiter); my $pod_seq3 = new Pod::InteriorSequence(-name => $cmd, -ldelim => $delimiter, -file => $filename, -line => $line_number); my $pod_seq4 = new Pod::InteriorSequence(-name => $cmd, $ptree); my $pod_seq5 = new Pod::InteriorSequence($cmd, $ptree); This is a class method that constructs a Pod::InteriorSequence object and returns a reference to the new interior sequence object. It should be given two keyword arguments. The `-ldelim' keyword indicates the corresponding left-delimiter of the interior sequence (e.g. '<'). The `-name' keyword indicates the name of the corresponding interior sequence command, such as I or B or C. The `-file' and `-line' keywords indicate the filename and line number corresponding to the beginning of the interior sequence. If the `$ptree' argument is given, it must be the last argument, and it must be either string, or else an array-ref suitable for passing to *Pod::ParseTree::new* (or it may be a reference to an Pod::ParseTree object). cmd_name() ---------- my $seq_cmd = $pod_seq->cmd_name(); The name of the interior sequence command. prepend() --------- $pod_seq->prepend($text); $pod_seq1->prepend($pod_seq2); Prepends the given string or parse-tree or sequence object to the parse-tree of this interior sequence. append() -------- $pod_seq->append($text); $pod_seq1->append($pod_seq2); Appends the given string or parse-tree or sequence object to the parse-tree of this interior sequence. nested() -------- $outer_seq = $pod_seq->nested || print "not nested"; If this interior sequence is nested inside of another interior sequence, then the outer/parent sequence that contains it is returned. Otherwise undef is returned. raw_text() ---------- my $seq_raw_text = $pod_seq->raw_text(); This method will return the raw text of the POD interior sequence, exactly as it appeared in the input. left_delimiter() ---------------- my $ldelim = $pod_seq->left_delimiter(); The leftmost delimiter beginning the argument text to the interior sequence (should be "<"). right_delimiter() ----------------- The rightmost delimiter beginning the argument text to the interior sequence (should be ">"). parse_tree() ------------ my $ptree = $pod_parser->parse_text($paragraph_text); $pod_seq->parse_tree( $ptree ); $ptree = $pod_seq->parse_tree(); This method will get/set the corresponding parse-tree of the interior sequence's text. file_line() ----------- my ($filename, $line_number) = $pod_seq->file_line(); my $position = $pod_seq->file_line(); Returns the current filename and line number for the interior sequence object. If called in an array context, it returns a list of two elements: first the filename, then the line number. If called in a scalar context, it returns a string containing the filename, followed by a colon (':'), followed by the line number. DESTROY() --------- This method performs any necessary cleanup for the interior-sequence. If you override this method then it is *imperative* that you invoke the parent method from within your own method, otherwise *interior-sequence storage will not be reclaimed upon destruction!* Pod::ParseTree ============== This object corresponds to a tree of parsed POD text. As POD text is scanned from left to right, it is parsed into an ordered list of text-strings and Pod::InteriorSequence objects (in order of appearance). A Pod::ParseTree object corresponds to this list of strings and sequences. Each interior sequence in the parse-tree may itself contain a parse-tree (since interior sequences may be nested). new() ----- my $ptree1 = Pod::ParseTree->new; my $ptree2 = new Pod::ParseTree; my $ptree4 = Pod::ParseTree->new($array_ref); my $ptree3 = new Pod::ParseTree($array_ref); This is a class method that constructs a `Pod::Parse_tree' object and returns a reference to the new parse-tree. If a single-argument is given, it must be a reference to an array, and is used to initialize the root (top) of the parse tree. top() ----- my $top_node = $ptree->top(); $ptree->top( $top_node ); $ptree->top( @children ); This method gets/sets the top node of the parse-tree. If no arguments are given, it returns the topmost node in the tree (the root), which is also a Pod::ParseTree. If it is given a single argument that is a reference, then the reference is assumed to a parse-tree and becomes the new top node. Otherwise, if arguments are given, they are treated as the new list of children for the top node. children() ---------- This method gets/sets the children of the top node in the parse-tree. If no arguments are given, it returns the list (array) of children (each of which should be either a string or a Pod::InteriorSequence. Otherwise, if arguments are given, they are treated as the new list of children for the top node. prepend() --------- This method prepends the given text or parse-tree to the current parse-tree. If the first item on the parse-tree is text and the argument is also text, then the text is prepended to the first item (not added as a separate string). Otherwise the argument is added as a new string or parse-tree before the current one. append() -------- This method appends the given text or parse-tree to the current parse-tree. If the last item on the parse-tree is text and the argument is also text, then the text is appended to the last item (not added as a separate string). Otherwise the argument is added as a new string or parse-tree after the current one. raw_text() ---------- my $ptree_raw_text = $ptree->raw_text(); This method will return the raw text of the POD parse-tree exactly as it appeared in the input. DESTROY() --------- This method performs any necessary cleanup for the parse-tree. If you override this method then it is *imperative* that you invoke the parent method from within your own method, otherwise *parse-tree storage will not be reclaimed upon destruction!* SEE ALSO ======== See *Note Pod/Parser: Pod/Parser,, *Note Pod/Select: Pod/Select, AUTHOR ====== Brad Appleton  File: pm.info, Node: Pod/LaTeX, Next: Pod/Man, Prev: Pod/InputObjects, Up: Module List Convert Pod data to formatted Latex *********************************** 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* in this node|pod2latex' X command uses this module for translation. `Pod::LaTeX' is a derived class from `Pod::Select|Pod::Select' in this node. 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 Pod::Parser. 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 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} \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. 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. Lists Contains details of the currently active lists. The array contains Pod::List objects. A new Pod::List 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 Pod::Select base class. See Pod::Parser and Pod::Select for more information on what these methods require. begin_pod Writes the latex preamble if requested. end_pod Write the closing latex code. 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 over directive). Creates a new Pod::List object and stores it on the list stack. $parser->begin_list($indent, $line_num); end_list Called when the end of a list is found (the back directive). Pops the Pod::List object off the stack of lists and writes the latex code required to close a list. $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 Pod::List object) the type of list is determined (ordered, unnumbered or description) and the relevant latex code issued. $parser->add_item($paragraph, $line_num); Methods for headings -------------------- head Print a heading of the required level. $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. $parser->_output($text); Does not write anything if a =begin or =for is active that should be ignored. _replace_special_chars Subroutine to replace characters that are special in latex with the escaped forms $escaped = $parser->_replace_special_chars($paragraph); Need to call this routine before interior_sequences are munged but not if verbatim. Special characters and the latex equivalents are: } \} { \{ _ \_ $ \$ % \% & \& \ $\backslash$ ^ \^{} ~ \~{} | $|$ _create_label Return a string that can be used as an internal reference in a latex document (i.e. accepted by the `\label' command) $label = $parser->_create_label($string) If UniqueLabels is true returns a label prefixed by Label() This can be suppressed with an optional second argument. $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 _create_label except an index entry is created. If UniqueLabels is true, the index entry is prefixed by the current Label and an exclamation mark. $ind = $parser->_create_index($paragraph); An exclamation mark is used by `makeindex' 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 `\command{ text }'. "text" is retained $clean = $parser->_clean_latex_commands($text); 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 ======== *Note Pod/Parser: Pod/Parser,, *Note Pod/Select: Pod/Select,, `pod2latex' in this node AUTHORS ======= Tim Jenness COPYRIGHT ========= Copyright (C) 2000 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. REVISION ======== $Id: LaTeX.pm,v 1.6 2000/08/21 09:05:03 timj Exp $  File: pm.info, Node: Pod/Man, Next: Pod/POM, Prev: Pod/LaTeX, Up: Module List Convert POD data to formatted *roff input ***************************************** NAME ==== Pod::Man - Convert POD data to formatted *roff input SYNOPSIS ======== use Pod::Man; my $parser = Pod::Man->new (release => $VERSION, section => 8); # Read POD from STDIN and write to STDOUT. $parser->parse_from_filehandle; # Read POD from file.pod and write to file.1. $parser->parse_from_file ('file.pod', 'file.1'); DESCRIPTION =========== Pod::Man is a module to convert documentation in the POD format (the preferred language for documenting Perl) into *roff input using the man macro set. The resulting *roff code is suitable for display on a terminal using nroff(1), normally via man(1), or printing using troff(1). It is conventionally invoked using the driver script pod2man, but it can also be used directly. As a derived class from Pod::Parser, Pod::Man supports the same methods and interfaces. See *Note Pod/Parser: Pod/Parser, for all the details; briefly, one creates a new parser with `Pod::Man->new()' and then calls either parse_from_filehandle() or parse_from_file(). new() can take options, in the form of key/value pairs that control the behavior of the parser. See below for details. If no options are given, Pod::Man uses the name of the input file with any trailing `.pod', `.pm', or `.pl' stripped as the man page title, to section 1 unless the file ended in `.pm' in which case it defaults to section 3, to a centered title of "User Contributed Perl Documentation", to a centered footer of the Perl version it is run with, and to a left-hand footer of the modification date of its input (or the current date if given STDIN for input). Pod::Man assumes that your *roff formatters have a fixed-width font named CW. If yours is called something else (like CR), use the fixed option to specify it. This generally only matters for troff output for printing. Similarly, you can set the fonts used for bold, italic, and bold italic fixed-width output. Besides the obvious pod conversions, Pod::Man also takes care of formatting func(), func(n), and simple variable references like $foo or @bar so you don't have to use code escapes for them; complex expressions like `$fred{'stuff'}' will still need to be escaped, though. It also translates dashes that aren't used as hyphens into en dashes, makes long dashes-like this-into proper em dashes, fixes "paired quotes," makes C++ and PI look right, puts a little space between double underbars, makes ALLCAPS a teeny bit smaller in troff(1), and escapes stuff that *roff treats as special so that you don't have to. The recognized options to new() are as follows. All options take a single argument. center Sets the centered page header to use instead of "User Contributed Perl Documentation". date Sets the left-hand footer. By default, the modification date of the input file will be used, or the current date if stat() can't find that file (the case if the input is from STDIN), and the date will be formatted as YYYY-MM-DD. fixed The fixed-width font to use for vertabim text and code. Defaults to CW. Some systems may want CR instead. Only matters for troff(1) output. fixedbold Bold version of the fixed-width font. Defaults to CB. Only matters for troff(1) output. fixeditalic Italic version of the fixed-width font (actually, something of a misnomer, since most fixed-width fonts only have an oblique version, not an italic version). Defaults to CI. Only matters for troff(1) output. fixedbolditalic Bold italic (probably actually oblique) version of the fixed-width font. Pod::Man doesn't assume you have this, and defaults to CB. Some systems (such as Solaris) have this font available as CX. Only matters for troff(1) output. quotes Sets the quote marks used to surround C<> text. If the value is a single character, it is used as both the left and right quote; if it is two characters, the first character is used as the left quote and the second as the right quoted; and if it is four characters, the first two are used as the left quote and the second two as the right quote. This may also be set to the special value none, in which case no quote marks are added around C<> text (but the font is still changed for troff output). release Set the centered footer. By default, this is the version of Perl you run Pod::Man under. Note that some system an macro sets assume that the centered footer will be a modification date and will prepend something like "Last modified: "; if this is the case, you may want to set release to the last modified date and date to the version number. section Set the section for the `.TH' macro. The standard section numbering convention is to use 1 for user commands, 2 for system calls, 3 for functions, 4 for devices, 5 for file formats, 6 for games, 7 for miscellaneous information, and 8 for administrator commands. There is a lot of variation here, however; some systems (like Solaris) use 4 for file formats, 5 for miscellaneous information, and 7 for devices. Still others use 1m instead of 8, or some mix of both. About the only section numbers that are reliably consistent are 1, 2, and 3. By default, section 1 will be used unless the file ends in .pm in which case section 3 will be selected. The standard Pod::Parser method parse_from_filehandle() takes up to two arguments, the first being the file handle to read POD from and the second being the file handle to write the formatted output to. The first defaults to STDIN if not given, and the second defaults to STDOUT. The method parse_from_file() is almost identical, except that its two arguments are the input and output disk files instead. See *Note Pod/Parser: Pod/Parser, for the specific details. DIAGNOSTICS =========== roff font should be 1 or 2 chars, not "%s" (F) You specified a *roff font (using fixed, fixedbold, etc.) that wasn't either one or two characters. Pod::Man doesn't support *roff fonts longer than two characters, although some *roff extensions do (the canonical versions of nroff(1) and troff(1) don't either). Invalid link %s (W) The POD source contained a `L<>' sequence that Pod::Man was unable to parse. You should never see this error message; it probably indicates a bug in Pod::Man. Invalid quote specification "%s" (F) The quote specification given (the quotes option to the constructor) was invalid. A quote specification must be one, two, or four characters long. %s:%d: Unknown command paragraph "%s". (W) The POD source contained a non-standard command paragraph (something of the form `=command args') that Pod::Man didn't know about. It was ignored. Unknown escape E<%s> (W) The POD source contained an `E<>' escape that Pod::Man didn't know about. `E<%s>' was printed verbatim in the output. Unknown sequence %s (W) The POD source contained a non-standard interior sequence (something of the form `X<>') that Pod::Man didn't know about. It was ignored. Unmatched =back (W) Pod::Man encountered a =back command that didn't correspond to an =over command. BUGS ==== The lint-like features and strict POD format checking done by pod2man are not yet implemented and should be, along with the corresponding `lax' option. The NAME section should be recognized specially and index entries emitted for everything in that section. This would have to be deferred until the next section, since extraneous things in NAME tends to confuse various man page processors. The handling of hyphens, en dashes, and em dashes is somewhat fragile, and one may get the wrong one under some circumstances. This should only matter for troff(1) output. When and whether to use small caps is somewhat tricky, and Pod::Man doesn't necessarily get it right. Pod::Man doesn't handle font names longer than two characters. Neither do most troff(1) implementations, but GNU troff does as an extension. It would be nice to support as an option for those who want to use it. The preamble added to each output file is rather verbose, and most of it is only necessary in the presence of E<> escapes for non-ASCII characters. It would ideally be nice if all of those definitions were only output if needed, perhaps on the fly as the characters are used. Some of the automagic applied to file names assumes Unix directory separators. Pod::Man is excessively slow. SEE ALSO ======== `Pod::Parser|Pod::Parser' in this node, perlpod(1), pod2man(1), nroff(1), troff(1), man(1), man(7) Ossanna, Joseph F., and Brian W. Kernighan. "Troff User's Manual," Computing Science Technical Report No. 54, AT&T Bell Laboratories. This is the best documentation of standard nroff(1) and troff(1). At the time of this writing, it's available at http://www.cs.bell-labs.com/cm/cs/cstr.html. The man page documenting the man macro set may be man(5) instead of man(7) on your system. Also, please see pod2man(1) for extensive documentation on writing manual pages if you've not done it before and aren't familiar with the conventions. AUTHOR ====== Russ Allbery , based *very* heavily on the original pod2man by Tom Christiansen .  File: pm.info, Node: Pod/POM, Next: Pod/POM/Node, Prev: Pod/Man, Up: Module List POD Object Model **************** NAME ==== Pod::POM - POD Object Model SYNOPSIS ======== use Pod::POM; my $parser = Pod::POM->new(\%options); # parse from a text string my $pom = $parser->parse_text($text) || die $parser->error(); # parse from a file specified by name or filehandle my $pom = $parser->parse_text($file) || die $parser->error(); # parse from text or file my $pom = $parser->parse($text_or_file) || die $parser->error(); # examine any warnings raised foreach my $warning ($parser->warnings()) { warn $warning, "\n"; } # print table of contents using each =head1 title foreach my $head1 ($pom->head1()) { print $head1->title(), "\n"; } # print each section foreach my $head1 ($pom->head1()) { print $head1->title(), "\n"; print $head1->content(); } # print the entire document as HTML use Pod::POM::View::HTML; print Pod::POM::View::HTML->print($pom); # create custom view package My::View; use base qw( Pod::POM::View::HTML ); sub view_head1 { my ($self, $item) = @_; return "

", $item->title->present($self), "

\n\n"; $item->content->present($self); } package main; print My::View->print($pom); DESCRIPTION =========== This module implements a parser to convert Pod documents into a simple object model form known hereafter as the Pod Object Model. The object model is generated as a hierarchical tree of nodes, each of which represents a different element of the original document. The tree can be walked manually and the nodes examined, printed or otherwise manipulated. In addition, Pod::POM supports and provides view objects which can automatically traverse the tree, or section thereof, and generate an output representation in one form or another. Let's look at a typical Pod document by way of example. =head1 NAME My::Module - just another My::Module =head1 DESCRIPTION This is My::Module, a deeply funky piece of Perl code. =head2 METHODS My::Module implements the following methods =over 4 =item new(\%config) This is the constructor method. It accepts the following configuration options: =over 4 =item name The name of the thingy. =item colour The colour of the thingy. =back =item print() This prints the thingy. =back =head1 AUTHOR My::Module was written by me Less_Than_Special_Sequenceme@here.orgGreater_Than_Special_Sequence This document contains 3 main sections, NAME, DESCRIPTION and AUTHOR, each of which is delimited by an opening =head1 tag. NAME and AUTHOR each contain only a single line of text, but DESCRIPTION is more interesting. It contains a line of text followed by the =head2 subsection, METHODS. This contains a line of text and a list extending from the `=over 4' to the final =back just before the AUTHOR section starts. The list contains 2 items, new(\%config), which itself contains some text and a list of 2 items, and print(). Presented as plain text and using indentation to indicate the element nesting, the model then looks something like this : NAME My::Module - just another My::Module DESCRIPTION This is My::Module, a deeply funky piece of Perl code. METHODS My::Module implements the following methods * new(\%config) This is the constructor method. It accepts the following configuration options: * name The name of the thingy. * colour The colour of the thingy. * item print() This prints the thingy. AUTHOR My::Myodule was written by me Those of you familiar with XML may prefer to think of it in the following way:

My::Module - just another My::Module

This is My::Module, a deeply funky piece of Perl code.

My::Module implements the following methods

This is the constructor method. It accepts the following configuration options:

The name of the thingy.

The colour of the thingy.

This prints the thingy.

My::Myodule was written by me <me@here.org> Notice how we can make certain assumptions about various elements. For example, we can assume that any =head1 section we find begins a new section and implicitly ends any previous section. Similarly, we can assume an =item ends when the next one begins, and so on. In terms of the XML example shown above, we are saying that we're smart enough to add a `' element to terminate any previously opened `' when we find a new =head1 tag in the input document. However you like to visualise the content, it all comes down to the same underlying model. The job of the Pod::POM module is to read an input Pod document and build an object model to represent it in this structured form. Each node in the tree (i.e. element in the document) is represented by a Pod::POM::Node::* object. These encapsulate the attributes for an element (such as the title for a =head1 tag) and also act as containers for further Pod::POM::Node::* objects representing the content of the element. Right down at the leaf nodes, we have simple object types to represent formatted and verbatim text paragraphs and other basic elements like these. Parsing Pod ----------- The Pod::POM module implements the methods parse_file($file), parse_text($text) and parse($file_or_text) to parse Pod files and input text. They return a Pod::POM::Node::Pod object to represent the root of the Pod Object Model, effectively the `' element in the XML tree shown above. use Pod::POM; my $parser = Pod::POM->new(); my $pom = $parser->parse_file($filename) || die $parser->error(); The parse(), parse_text() and parse_file() methods return undef on error. The error() method can be called to retrieve the error message generated. Parsing a document may also generate non-fatal warnings. These can be retrieved via the warnings() method which returns a reference to a list when called in scalar context or a list of warnings when called in list context. foreach my $warn ($parser->warnings()) { warn $warn, "\n"; } Alternatively, the 'warn' configuration option can be set to have warnings automatically raised via `warn()' as they are encountered. my $parser = Pod::POM->new( warn => 1 ); Walking the Object Model ------------------------ Having parsed a document into an object model, we can then select various items from it. Each node implements methods (via AUTOLOAD) which correspond to the attributes and content elements permitted within in. So to fetch the list of '=head1' sections within our parsed document, we would do the following: my $sections = $pom->head1(); Methods like this will return a list of further Pod::POM::Node::* objects when called in list context or a reference to a list when called in scalar context. In the latter case, the list is blessed into the Pod::POM::Node::Content class which gives it certain magical properties (more on that later). Given the list of Pod::POM::Node::Head1 objects returned by the above, we can print the title attributes of each like this: foreach my $s (@$sections) { print $s->title(); } Let's look at the second section, DESCRIPTION. my $desc = $sections->[1]; We can print the title of each subsection within it: foreach my $ss ($desc->head2()) { print $ss->title(); } Hopefully you're getting the idea by now, so here's a more studly example to print the title for each item contained in the first list within the METHODS section: foreach my $item ($desc->head2->[0]->over->[0]->item) { print $item->title(), "\n"; } Element Content --------------- This is all well and good if you know the precise structure of a document in advance. For those more common cases when you don't, each node that can contain other nodes provides a 'content' method to return a complete list of all the other nodes that it contains. The 'type' method can be called on any node to return its element type (e.g. 'head1', 'head2', 'over', item', etc). foreach my $item ($pom->content()) { my $type = $item->type(); if ($type eq 'head1') { ... } elsif ($type eq 'head2') { ... } ... } The content for an element is represented by a reference to a list, blessed into the Pod::POM::Node::Content class. This provides some magic in the form of an overloaded stringification operator which will automatically print the contents of the list if you print the object itself. In plain English, or rather, in plain Perl, this means you can do things like the following: foreach my $head1 ($pom->head1()) { print '

', $head1->title(), "

\n\n"; print $head1->content(); } # print all the root content foreach my $item ($pom->content()) { print $item; } # same as above print $pom->content(); In fact, all Pod::POM::Node::* objects provide this same magic, and will attempt to Do The Right Thing to present themselves in the appropriate manner when printed. Thus, the following are all valid. print $pom; # entire document print $pom->content; # content of document print $pom->head1->[0]; # just first section print $pom->head1; # print all sections foreach my $h1 ($pom->head1()) { print $h1->head2(); # print all subsections } Output Views ------------ To understand how the different elements go about presenting themselves in "the appropriate manner", we must introduce the concept of a view. A view is quite simply a particular way of looking at the model. In real terms, we can think of a view as being some kind of output type generated by a pod2whatever converter. Notionally we can think in terms of reading in an input document, building a Pod Object Model, and then generating an HTML view of the document, and/or a LaTeX view, a plain text view, and so on. A view is represented in this case by an object class which contains methods for displaying each of the different element types that could be encountered in any Pod document. There's a method for displaying =head1 sections (view_head1()), another method for displaying =head2 sections (view_head2()), one for =over (view_over()), another for =item (view_item()) and so on. If we happen to have a reference to a $node and we know it's a 'head1' node, then we can directly call the right view method to have it displayed properly: $view = 'Pod::POM::View::HTML'; $view->view_head1($node); Thus our earlier example can be modified to be *slightly* less laborious and *marginally* more flexible. foreach my $node ($pom->content) { my $type = $node->type(); if ($type eq 'head1') { print $view->view_head1($node); } elsif ($type eq 'head2') { print $view->view_head2($node); } ... } However, this is still far from ideal. To make life easier, each Pod::POM::Node::* class inherits (or possibly redefines) a `present($view)' method from the Pod::POM::Node base class. This method expects a reference to a view object passed as an argument, and it simply calls the appropriate view_xxx() method on the view object, passing itself back as an argument. In object parlance, this is known as "double dispatch". The beauty of it is that you don't need to know what kind of node you have to be able to print it. You simply pass it a view object and leave it to work out the rest. foreach my $node ($pom->content) { print $node->present($view); } If $node is a Pod::POM::Node::Head1 object, then the view_head1($node) method gets called against the $view object. Otherwise, if it's a Pod::POM::Node::Head2 object, then the view_head2($node) method is dispatched. And so on, and so on, with each node knowing what it is and where it's going as if determined by some genetically pre-programmed instinct. Fullfilling their destinies, so to speak. Double dispatch allows us to do away with all the explicit type checking and other nonsense and have the node objects themselves worry about where they should be routed to. At the cost of an extra method call per node, we get programmer convenience, and that's usually a Good Thing. Let's have a look at how the view and node classes might be implemented. package Pod::POM::View::HTML; sub view_pod { my ($self, $node) = @_; return $node->content->present($self); } sub view_head1 { my ($self, $node) = @_; return "

", $node->title->present($self), "

\n\n" . $node->content->present($self); } sub view_head2 { my ($self, $node) = @_; return "

", $node->title->present($self), "

\n\n" . $node->content->present($self); } ... package Pod::POM::Node::Pod; sub present { my ($self, $view) = @_; $view->view_pod($self); } package Pod::POM::Node::Head1; sub present { my ($self, $view) = @_; $view->view_head1($self); } package Pod::POM::Node::Head2; sub present { my ($self, $view) = @_; $view->view_head2($self); } ... Some of the view_xxx methods make calls back against the node objects to display their attributes and/or content. This is shown in, for example, the view_head1() method above, where the method prints the section title in `

'...`

' tags, followed by the remaining section content. Note that the title() attribute is printed by calling its present() method, passing on the reference to the current view. Similarly, the content present() method is called giving it a chance to Do The Right Thing to present itself correctly via the view object. There's a good chance that the title attribute is going to be regular text, so we might be tempted to simply print the title rather than call its present method. sub view_head1 { my ($self, $node) = @_; # not recommended, prefer $node->title->present($self) return "

", $node->title(), "

\n\n", ... } However, it is entirely valid for titles and other element attributes, as well as regular, formatted text blocks to contain code sequences, such like `B' and `I'. These are used to indicate different markup styles, mark external references or index items, and so on. What's more, they can be `B>'. Pod::POM takes care of all this by parsing such text, along with any embedded sequences, into Yet Another Tree, the root node of which is a Pod::POM::Node::Text object, possibly containing other Pod::POM::Node::Sequence objects. When the text is presented, the tree is automatically walked and relevant callbacks made against the view for the different sequence types. The methods called against the view are all prefixed 'view_seq_', e.g. 'view_seq_bold', 'view_seq_italic'. Now the real magic comes into effect. You can define one view to render bold/italic text in one style: package My::View::Text; use base qw( Pod::POM::View::Text ); sub view_seq_bold { my ($self, $text) = @_; return "*$text*"; } sub view_seq_italic { my ($self, $text) = @_; return "_$text_"; } And another view to render it in a different style: package My::View::HTML; use base qw( Pod::POM::View::HTML ); sub view_seq_bold { my ($self, $text) = @_; return "$text"; } sub view_seq_italic { my ($self, $text) = @_; return "$text"; } Then, you can easily view a Pod Object Model in either style: my $text = 'My::View::Text'; my $html = 'My::View::HTML'; print $pom->present($text); print $pom->present($html); And you can apply this technique to any node within the object model. print $pom->head1->[0]->present($text); print $pom->head1->[0]->present($html); In these examples, the view passed to the present() method has been a class name. Thus, the view_xxx methods get called as class methods, as if written: My::View::Text->view_head1(...); If your view needs to maintain state then you can create a view object and pass that to the present() method. my $view = My::View->new(); $node->present($view); In this case the view_xxx methods get called as object methods. sub view_head1 { my ($self, $node) = @_; my $title = $node->title(); if ($title eq 'NAME' && ref $self) { $self->{ title } = $title(); } $self->SUPER::view_head1($node); } Whenever you print a Pod::POM::Node::* object, or do anything to cause Perl to stringify it (such as including it another quoted string "like $this"), then its present() method is automatically called. When called without a view argument, the present() method uses the default view specified in $Pod::POM::DEFAULT_VIEW, which is, by default, 'Pod::POM::View::Pod'. This view regenerates the original Pod document, although it should be noted that the output generated may not be exactly the same as the input. The parser is smart enough to detect some common errors (e.g. not terminating an =over with a =back) and correct them automatically. Thus you might find a =back correctly placed in the output, even if you forgot to add it to the input. Such corrections raise non-fatal warnings which can later be examined via the warnings() method. You can update the $Pod::POM::DEFAULT_VIEW package variable to set the default view, or call the default_view() method. The default_view() method will automatically load any package you specify. If setting the package variable directly, you should ensure that any packages required have been pre-loaded. use My::View::HTML; $Pod::POM::DEFAULT_VIEW = 'My::View::HTML'; or Pod::POM->default_view('My::View::HTML'); Template Toolkit Views ---------------------- One of the motivations for writing this module was to make it easier to customise Pod documentation to your own look and feel or local formatting conventions. By clearly separating the content (represented by the Pod Object Model) from the presentation style (represented by one or more views) it becomes much easier to achieve this. The latest version (2.01) of the Template Toolkit provides a Pod::POM plugin to interface to this module. In addition, it supports a new VIEW directive which allows you to define the presentation elements as template blocks. At the time of writing, version 2.01 hasn't been officially released to CPAN, but a preview is available from the Template Toolkit web site: http://www.template-toolkit.org/ The precise syntax and structure of the VIEW directive is subject to change, but at present it can be used to define a view something like this: [% VIEW myview %] [% BLOCK view_head1 %]

[% item.title.present(view) %]

[% item.content.present(view) %] [% END %] [% BLOCK view_head2 %]

[% item.title.present(view) %]

[% item.content.present(view) %] [% END %] ... [% END %] A plugin is provided to interface to the Pod::POM module: [% USE pom = Pod.POM(myfile) %] The returned Pod Object Model instance can then be navigated and presented via the view in almost any way imaginable:

Table of Contents

    [% FOREACH section = pom.head1 %]
  • [% section.title.present(view) %] [% END %]
[% FOREACH section = pom.head1 %] [% section.present(myview) %] [% END %] As noted above this is all still experimental but should stabilise with the release of the Template Toolkit 2.01, expected some time late in January 2001. This documentation will be updated at that time. METHODS ======= new(\%config) ------------- Constructor method which instantiates and returns a new Pod::POM parser object. use Pod::POM; my $parser = Pod::POM->new(); A reference to a hash array of configuration options may be passed as an argument. my $parser = Pod::POM->new( { warn => 1 } ); For convenience, configuration options can also be passed as a list of (key => value) pairs. my $parser = Pod::POM->new( warn => 1 ); The following configuration options are defined: code This option can be set to have all non-Pod parts of the input document stored within the object model as 'code' elements, represented by objects of the Pod::POM::Node::Code class. It is disabled by default and code sections are ignored. my $parser = Pod::POM->new( code => 1 ); my $podpom = $parser->parse(\*DATA); foreach my $code ($podpom->code()) { print "
$code
\n"; } __DATA__ This is some program code. =head1 NAME ... This will generate the output: 
This is some program code.
Note that code elements are stored within the POM element in which they are encountered. For example, the code element below embedded within between Pod sections is stored in the array which can be retrieved by calling `$podpom->head1->[0]->code()'. =head1 NAME My::Module::Name; =cut Some program code embedded in Pod. =head1 SYNOPSIS ... warn Non-fatal warnings encountered while parsing a Pod document are stored internally and subsequently available via the warnings() method. my $parser = Pod::POM->new(); my $podpom = $parser->parse_file($filename); foreach my $warning ($parser->warnings()) { warn $warning, "\n"; } The 'warn' option can be set to have warnings raised automatically via `warn()' as and when they are encountered. my $parser = Pod::POM->new( warn => 1 ); my $podpom = $parser->parse_file($filename); If the configuration value is specified as a subroutine reference then the code will be called each time a warning is raised, passing the warning message as an argument. sub my_warning { my $msg = shift; warn $msg, "\n"; }; my $parser = Pod::POM->new( warn => \&my_warning ); my $podpom = $parser->parse_file($filename); parse_file($file) ----------------- Parses the file specified by name or reference to a file handle. Returns a reference to a Pod::POM::Node::Pod object which represents the root node of the Pod Object Model on success. On error, undef is returned and the error message generated can be retrieved by calling error(). my $podpom = $parser->parse_file($filename) || die $parser->error(); my $podpom = $parser->parse_file(\*STDIN) || die $parser->error(); Any warnings encountered can be examined by calling the warnings() method. foreach my $warn ($parser->warnings()) { warn $warn, "\n"; } parse_text($text) ----------------- Parses the Pod text string passed as an argument into a Pod Object Model, as per parse_file(). parse($text_or_$file) --------------------- General purpose method which attempts to Do The Right Thing in calling parse_file() or parse_text() according to the argument passed. A hash reference can be passed as an argument that contains a 'text' or 'file' key and corresponding value. my $podpom = $parser->parse({ file => $filename }) || die $parser->error(); Otherwise, the argument can be a reference to an input handle which is passed off to parse_file(). my $podpom = $parser->parse(\*DATA) || die $parser->error(); If the argument is a text string that looks like Pod text (i.e. it contains '=' at the start of any line) then it is passed to parse_text(). my $podpom = $parser->parse($podtext) || die $parser->error(); Otherwise it is assumed to be a filename and is passed to parse_file(). my $podpom = $parser->parse($podfile) || die $parser->error(); NODE TYPES, ATTRIBUTES AND ELEMENTS =================================== This section lists the different nodes that may be present in a Pod Object Model. These are implemented as Pod::POM::Node::* object instances (e.g. head1 => Pod::POM::Node::Head1). To present a node, a view should implement a method which corresponds to the node name prefixed by 'view_' (e.g. head1 => view_head1()). pod The pod node is used to represent the root node of the Pod Object Model. Content elements: head1, head2, over, begin, for, verbatim, text, code. head1 A head1 node contains the Pod content from a =head1 tag up to the next =head1 tag or the end of the file. Attributes: title Content elements: head2, over, begin, for, verbatim, text, code. head2 A head2 node contains the Pod content from a =head2 tag up to the next =head1 or =head2 tag or the end of the file. Attributes: title Content elements: over, begin, for, verbatim, text, code. over The over node encloses the Pod content in a list starting at an =over tag and continuing up to the matching =back tag. Lists may be nested indefinately. Attributes: indent (default: 4) Content elements: over, item, begin, for, verbatim, text, code. item The item node encloses the Pod content in a list item starting at an =item tag and continuing up to the next =item tag or a =back tag which terminates the list. Attributes: title (default: *) Content elements: over, begin, for, verbatim, text, code. begin A begin node encloses the Pod content in a conditional block starting with a =begin tag and continuing up to the next =end tag. Attributes: format Content elements: verbatim, text, code. for A for node contains a single paragraph containing text relevant to a particular format. Attributes: format, text verbatim A verbatim node contains a verbatim text paragraph which is prefixed by whitespace in the source Pod document (i.e. indented). Attributes: text text A text node contains a regular text paragraph. This may include embedded inline sequences. Attributes: text code A code node contains Perl code which is by default, not considered to be part of a Pod document. The code configuration option must be set for Pod::POM to generate code blocks, otherwise they are ignored. Attributes: text INLINE SEQUENCES ================ Embedded sequences are permitted within regular text blocks (i.e. not verbatim) and title attributes. To present these sequences, a view should implement methods corresponding to the sequence name, prefixed by 'view_seq_' (e.g. bold => view_seq_bold()). code Code extract, e.g. C bold Bold text, e.g. B italic Italic text, e.g. I link A link (cross reference), e.g. L space Text contains non-breaking space, e.g.S file A filename, e.g. F index An index entry, e.g. X zero A zero-width character, e.g. Z<> entity An entity escape, e.g. E BUNDLED MODULES AND TOOLS ========================= The Pod::POM module distribution includes a number of sample view objects for rendering Pod Object Models into particular formats. These are incomplete and may require some further work, but serve at present to illustrate the principal and can be used as the basis for your own view objects. Pod::POM::View::Pod Regenerates the model as Pod. Pod::POM::View::Text Presents the model as plain text. Pod::POM::View::HTML Presents the model as HTML. A script is provided for converting Pod documents to other format by using the view objects provided. The `pom2' script should be called with two arguments, the first specifying the output format, the second the input filename. e.g. $ pom2 text My/Module.pm > README $ pom2 html My/Module.pm > ~/public_html/My/Module.html You can also create symbolic links to the script if you prefer and leave it to determine the output format from its own name. $ ln -s pom2 pom2text $ ln -s pom2 pom2html $ pom2text My/Module.pm > README $ pom2html My/Module.pm > ~/public_html/My/Module.html The distribution also contains a trivial script, `pomcheck', which checks a Pod document for well-formedness by simply parsing it into a Pod Object Model with warnings enabled. Warnings are printed to STDERR. $ pomcheck My/Module.pm The -f option can be set to have the script attempt to fix any problems it encounters. The regenerated Pod output is printed to STDOUT. $ pomcheck -f My/Module.pm > newfile AUTHOR ====== Andy Wardley VERSION ======= This is version 0.1 of the Pod::POM module. COPYRIGHT ========= Copyright (C) 2000, 2001 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== For the definitive reference on Pod, see *Note Perlpod: (perl.info)perlpod,. For an overview of Pod::POM internals and details relating to subclassing of POM nodes, see *Note Pod/POM/Node: Pod/POM/Node,. There are numerous other fine Pod modules available from CPAN which perform conversion from Pod to other formats. In many cases these are likely to be faster and quite possibly more reliable and/or complete than this module. But as far as I know, there aren't any that offer the same kind of flexibility in being able to customise the generated output. But don't take my word for it - see your local CPAN site for further details: http://www.cpan.org/modules/by-module/Pod/