This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Pod/Tree/HTML, Next: Pod/Tree/Node, Prev: Pod/Tree, Up: Module List Generate HTML from a Pod::Tree ****************************** NAME ==== Pod::Tree::HTML - Generate HTML from a Pod::Tree SYNOPSIS ======== use Pod::Tree::HTML; $source = new Pod::Tree; $source = "file.pod"; $source = new IO::File; $source = \$pod; $source = \@pod; $dest = new HTML::Stream; $dest = new IO::File; $dest = "file.html"; $html = new Pod:::Tree::HTML $source, $dest, %options; $html->set_options(%options); @values = $html->get_options(@keys); $html->translate; DESCRIPTION =========== `Pod::Tree::HTML' reads a POD and translates it to HTML. The source and destination are fixed when the object is created. Options are provided for controlling details of the translation. The translate method does the actual translation. For convenience, `Pod::Tree::HTML' can read PODs from a variety of sources, and write HTML to a variety of destinations. The new method resolves the *$source* and $dest arguments. Source resolution ----------------- `Pod::Tree::HTML' can obtain a POD from any of 5 sources. new resolves *$source* by checking these things, in order: 1. If *$source* isa `POD::Tree', then the POD is taken from that tree. 2. If *$source* is not a reference, then it is taken to be the name of a file containing a POD. 3. If *$source* isa IO::File, then it is taken to be an IO::File object that is already open on a file containing a POD. 4. If *$source* is a SCALAR reference, then the text of the POD is taken from that scalar. 5. if *$source* is an ARRAY reference, then the paragraphs of the POD are taken from that array. If *$source* isn't any of these things, new dies. Destination resolution ---------------------- `Pod::Tree::HTML' can write HTML to any of 3 destinations. new resolves $dest by checking these things, in order: 1. If $dest isa `HTML::Stream', then it writes to that stream. 2. If $dest is a reference, then it is taken to be an IO::File object that is already open on the file where the HTML will be written. 3. If $dest is not a reference, then it is taken to be the name of the file where the HTML will be written. METHODS ======= $html = new `Pod::Tree::HTML' *$source*, $dest, %options Creates a new `Pod::Tree::HTML' object. $html reads a POD from *$source*, and writes HTML to $dest. See `' in this node and `' in this node for details. Options controlling the translation may be passed in the %options hash. See `' in this node for details. $html->`set_options'(%options) Sets options controlling the translation. See `' in this node for details. *@values* = $html->get_options(*@keys*) Returns the current values of the options specified in *@keys*. See `' in this node for details. $html->translate Translates the POD to HTML. This method should only be called once. OPTIONS ======= base => *$url* Translate `L<>' sequences into HTML links relative to *$url*. `link_map' => *$link_map* Sets the link mapping object. Before emitting an L<> markup in HTML, translate calls ($base, $page, $section) = *$link_map*->map($base, $page, $section); Where $base is the URL given in the base option. $page is the man page named in the L<> markup. $section is the man page section given in the L<> markup. The map method may perform arbitrary mappings on its arguments. The default link_map translates `::' sequences in $page to /. `toc' => [0|1] Includes or omits the table of contents. Default is to include the TOC. `hr' => *$level* Controls the profusion of horizontal lines in the output, as follows: $level horizontal lines 0 none 1 between TOC and body 2 after each =head1 3 after each =head1 and =head2 Default is level 1. bgcolor => *#rrggbb* Set the background color to *#rrggbb*. Default is `#fffff8', which is an off-white. text => *#rrggbb* Set the text color to *#rrggbb*. Default is `#fffff', which is black. title => title Set the page title to title. If no title option is given, `Pod::Tree::HTML' will attempt construct a title from the second paragrah of the POD. This supports the following style: =head1 NAME ls - list contents of directory LINKS and TARGETS ================= `Pod::Tree::HTML' automatically generates HTML name anchors for all =head1 and =head2 command paragraphs, and for text items in =over lists. The text of the paragraph becomes the name entity in the anchor. Markups are ignored and the text is escaped according to RFC 2396. For example, the paragraph =head1 C Bar is translated to

Foo Bar

To link to a heading, simply give the text of the heading in a `L<>' markup. The text must match exactly; markups may vary. Either of these would link to the heading shown above L Bar> L To generate HTML anchors in other places, use the index (`X<>') markup We can link to X. and link to it as usual L uses the index markup. DIAGNOSTICS =========== `Pod::Tree::HTML::new: not enough arguments' (F) new called with fewer than 2 arguments. `Pod::Tree::HTML::new: Can't load POD from $source' (F) new couldn't resolve the *$source* argument. See `' in this node for details. `Pod::Tree::HTML::new: Can't open $dest: $!' (F) The destination file couldn't be opened. SEE ALSO ======== perl(1), ``Pod::Tree' in this node', ``Pod::Tree::Node' in this node' AUTHOR ====== Steven McDougall, swmcd@world.std.com COPYRIGHT ========= Copyright 1999-2000 by Steven McDougall. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Pod/Tree/Node, Next: Pod/Tree/PerlBin, Prev: Pod/Tree/HTML, Up: Module List nodes in a Pod::Tree ******************** NAME ==== Pod::Tree::Node - nodes in a Pod::Tree SYNOPSIS ======== $node = root Pod::Tree::Node \@paragraphs; $node = verbatim Pod::Tree::Node $paragraph; $node = command Pod::Tree::Node $paragraph; $node = ordinary Pod::Tree::Node $paragraph; $node = letter Pod::Tree::Node $token; $node = sequence Pod::Tree::Node $letter, \@children; $node = text Pod::Tree::Node $text; $node = target Pod::Tree::Node $target; is_command $node and ... is_for $node and ... is_item $node and ... is_letter $node and ... is_list $node and ... is_ordinary $node and ... is_root $node and ... is_sequence $node and ... is_text $node and ... is_verbatim $node and ... is_link $node and ... is_c_head1 $node and ... is_c_head2 $node and ... is_c_over $node and ... is_c_back $node and ... is_c_item $node and ... is_c_for $node and ... is_c_begin $node and ... is_c_end $node and ... $arg = get_arg $node; $children = get_children $node; $command = get_command $node; $item_type = get_item_type $node; $letter = get_letter $node; $list_type = get_list_type $node; $page = get_page $node; $section = get_section $node; $siblings = get_siblings $node; $target = get_target $node; $text = get_text $node; $type = get_type $node; $deep_text = get_deep_text $node; $node->force_text($text); $node->force_for; $node->parse_begin (\@nodes); $node->set_children(\@children); $node->make_sequences; $node->parse_links; $node->unescape; $node->consolidate; $node->make_lists; $node->dump; DESCRIPTION =========== `Pod::Tree::Node' objects are nodes in a tree that represents a POD. Applications walk the tree to recover the structure and content of the POD. Methods are provided for * creating nodes in the tree * parsing the POD into nodes * returning information about nodes * walking the tree TREE STRUCTURE ============== Root node --------- The tree descends from a single root node; is_root returns true on this node and no other. $children = $root->get_children returns a reference to an array of nodes. These nodes represent the POD. Node types ---------- For each node, call `get_type' to discover the type of the node for $child (@$children) { $type = $child->get_type; } $type will be one of these strings: 'root' The node is the root of the tree. 'verbatim' The node represents a verbatim paragraph. 'ordinary' The node represents an ordinary paragraph. 'command' The node represents an =command paragraph (but not an =over paragraph). 'sequence' The node represents an interior sequence. 'target' The node represents the target of a link (An L<> markup). 'text' The node represents text that contains no interior sequences. 'list' The node represents an =over list. 'item' The node represents an item in an =over list. 'for' The node represents a =for paragraph, or it represents the paragraphs between =begin/=end commands. Here are instructions for walking these node types. root node --------- Call $children = $node->get_children to get a list of nodes representing the POD. verbatim nodes -------------- A verbatim node contains the text of a verbatim paragraph. Call $text = $node->get_text to recover the text of the paragraph. ordinary nodes -------------- An ordinary node represents the text of an ordinary paragraph. The text is parsed into a list of text and sequence nodes; these nodes are the children of the ordinary node. Call $children = $node->get_children to get a list of the children. Iterate over this list to recover the text of the paragraph. command nodes ------------- A command node represents an =command paragraph. Call $command = $node->get_command; to recover the name of the command. The name is returned *without* the equals sign. The text of a command paragraph is parsed into a list of text and sequence nodes; these nodes are the children of the command node. Call $children = $node->get_children; to get a list of the children. Iterate over this list to recover the text of the paragraph. sequence nodes -------------- A sequence node represents a single interior sequence (a <> markup). Call $node->get_letter to recover the original markup letter. The contents of the markup are parsed into a list of text and sequence nodes; these nodes are the children of the sequence node. Call $node->get_children to recover them. Z<> and E<> markups do not generate sequence nodes; these markups are expanded by `Pod::Tree' when the tree is built. target nodes ------------ If a sequence node represents a link (an `L<>' markup), then is_link $node returns true and $target = $node->get_target returns a node representing the target of the link. Call $page = $target->get_page; $section = $target->get_section; to recover the man page and section that the link refers to. $target is used only for constructing hyper-links; the text to be displayed for the link is recovered by walking the children of $node, as for any other interior sequence. text nodes ---------- A text node represents text that contains no interior sequences. Call $text = $node->get_text to recover the text. list nodes ---------- A list node represents an =over list. Call $list_type = $node->get_list_type; to discover the type of the list. This will be one of the strings 'bullet' 'number' 'text' The type of a list is the type of the first item in the list. The children of a list node are item nodes; each item node represents one item in the list. You can call $node->get_arg; to recover the indent value following the =over. item nodes ---------- An item node represents one item in an =over list. Call $item_type = $node->get_item_type; to discover the type of the item. This will be one of the strings shown above for `list nodes' in this node. Typically, all the items in a list have the same type, but `Pod::Tree::Node' doesn't assume this. The children of an item node represent the text of the =item paragraph; this is usually of interest only for 'text' items. Call $children = $node->get_children to get a list of the children; these will be sequence and text nodes, as for any other =command paragraph. Each item node also has a list of nodes representing all the paragraphs following it, up to the next =item command, or the end of the list. These nodes are called siblings of the item node. Call $siblings = $node->get_siblings to get a list of sibling nodes. for nodes --------- for nodes represent text that is to be passed to an external formatter. Call $formatter = $node->get_arg; to discover the name of the formatter. Call $text = $node->get_text; to obtain the text to be passed to the formatter. This will either be the text of an =for command, or all of the text between =begin and =end commands. Walking the tree ---------------- PODs have a recursive structure; therefore, any application that walks a Pod::Tree must also be recursive. See `skeleton' for an example of the necessary code. METHODS ======= Constructors ------------ These methods construct `Pod::Tree::Node' objects. They are used to build trees. They aren't necessary to walk trees. $node = root Pod::Tree::Node \@paragraphs; $node = verbatim Pod::Tree::Node $paragraph; $node = command Pod::Tree::Node $paragraph; $node = ordinary Pod::Tree::Node $paragraph; $node = letter Pod::Tree::Node $token; $node = sequence Pod::Tree::Node $letter, \@children; $node = text Pod::Tree::Node $text; $node = target Pod::Tree::Node $target; Tests ----- These methods return true iff $node has the type indicated by the method name. is_command $node and ... is_for $node and ... is_item $node and ... is_letter $node and ... is_link $node and ... is_list $node and ... is_ordinary $node and ... is_root $node and ... is_sequence $node and ... is_text $node and ... is_verbatim $node and ... These methods return true iff $node is a command node, and the command is the one indicated by the method name. is_c_head1 $node and ... is_c_head2 $node and ... is_c_over $node and ... is_c_back $node and ... is_c_item $node and ... is_c_for $node and ... is_c_begin $node and ... is_c_end $node and ... Accessors --------- These methods return information about nodes. Most accessors are only relevant for certain types of nodes. $arg = `get_arg' $node Returns the argument of $node. This is the number following an =over command, or the name of an external translator for =for, =begin, and =end commands. Only relevant for these four command nodes. $children = get_children $node Returns a reference to the list of nodes that are children of $node. May be called on any node. The list may be empty. $command = `get_command' $node Returns the name of a command, without the equals sign. Only relevant for command nodes. $item_type = `get_item_type' $node Returns the type of an item node. The type will be one of 'bullet' 'number' 'text' $letter = `get_letter' $node Returns the letter that introduces an interior sequence. Only relevant for sequence nodes. $list_type = `get_list_type' $node Returns the type of a list node. The type of a list node is the type of the first item node in the list. $page = `get_page' $node Returns the man page that is the target of a link. Only relevant for target nodes. $section = `get_section' $node Returns the section that is the target of a link. Only relevant for target nodes. $siblings = `get_siblings' $node Returns the siblings of a node. May be called on any node. Only item nodes have siblings. $target = `get_target' $node Returns the target of a node. Only relevant for sequence nodes that represent links (`L<>' markups). `is_link' returns true on these nodes. $text = get_text $node Returns the text of a node. $text will not contain any interior sequences. Only relevant for text nodes. $type = `get_type' $node Returns the type of $node. May be called on any node. See `' in this node for descriptions of the node types. $deep_text = `get_deep_text' $node Recursively walks the children of a node, catenates together the text from each node, and returns all that text as a single string. All interior sequence markups are discarded. `get_deep_text' is provided as a convenience for applications that want to ignore markups in a POD paragraph. Parsing ------- These methods manipulate the tree while it is being built. They aren't necessary to walk the tree. $node->force_text($text) $node->force_for; $node->parse_begin (\@nodes); $node->set_children(\@children); $node->make_sequences; $node->parse_links; $node->unescape; $node->consolidate; $node->make_lists; Utility ------- $node->dump Returns a string containing a pretty-printed representation of the node. Calling dump on the root node of a tree will show the entire POD. EXAMPLES ======== The `t/' directory in the `Pod::Tree' distribution contains examples of PODs, together with dumps of the trees that `Pod::Tree' constructs for them. The tree for `t/'file`.pod' is in `t/'file`.p_exp'. `Pod::Tree::Node::dump' is a simple example of code that walks a POD tree. `skeleton' is a skeleton application that walks a POD tree. SEE ALSO ======== perl(1), ``Pod::Tree' in this node' AUTHOR ====== Steven McDougall, swmcd@world.std.com COPYRIGHT ========= Copyright 1999-2000 by Steven McDougall. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Pod/Tree/PerlBin, Next: Pod/Tree/PerlDist, Prev: Pod/Tree/Node, Up: Module List translate program PODs to HTML ****************************** NAME ==== Pod::Tree::PerlBin - translate program PODs to HTML SYNOPSIS ======== $perl_map = new Pod::Tree::PerlMap; $perl_bin = new Pod::Tree::PerlBin $perl_dir, $HTML_dir, $perl_map, %opts; $perl_bin->scan(@path); $perl_bin->index; $perl_bin->translate; $top = $perl_bin->get_top_entry; DESCRIPTION =========== `Pod::Tree::PerlBin' translates program PODs to HTML. It searches for programs in a list of directories (typically a PATH), and searches for PODs withing the programs. Only text (-T) files are considered. `Pod::Tree::PerlBin' generates a top-level index of all the program PODs, and writes it to *HTML_dir*`/bin.html'. `Pod::Tree::PerlBin' generates and uses an index of the PODs that it finds to construct HTML links. Other modules can also use this index. METHODS ======= $perl_bin = new `Pod::Tree::PerlBin' *$perl_dir*, *$HTML_dir*, *$perl_map*, %options Creates and returns a new `Pod::Tree::PerlBin' object. *$HTML_dir* is the directory where HTML files will be written. *$perl_map* maps program names to URLs. %options are passed through to `Pod::Tree::HTML'. The *$perl_dir* argument is included for consistency with the other `Pod::Tree::Perl*' modules, but is currently unused. $perl_bin->scan(*@path*) Scans all the directories in *@path* for program PODs. Only text (-T) files are considered. The search does not recurse through subdirectories. Each POD that is located is entered into *$perl_map*. $perl_bin->index Generates a top-level index of all the program PODs, and writes it to *HTML_dir*`/bin.html'. $perl_bin->translate Translates each program POD found by scan to HTML. The HTML pages are written to *HTML_dir*. $perl_bin->`get_top_entry' Returns a hash reference of the form { URL => $URL, description => $description } `Pod::Tree::PerlTop' uses this to build a top-level index of all the Perl PODs. LINKING ======= `Pod::Tree::PerlBin' expects the second paragraph of the POD to have the form name - description and enters name into *$perl_map*. To link to a program POD from another POD, write L REQUIRES ======== 5.005 File::Find HTML::Stream Pod::Tree Pod::Tree::HTML Pod::Tree::PerlUtil EXPORTS ======= Nothing. SEE ALSO ======== ``Pod::Tree::HTML' in this node', ``Pod::Tree::PerlMap' in this node', AUTHOR ====== Steven McDougall, swmcd@world.std.com COPYRIGHT ========= Copyright 2000 by Steven McDougall. This program is free software; you can redistribute it and/or modify it under the same terms as Perl.  File: pm.info, Node: Pod/Tree/PerlDist, Next: Pod/Tree/PerlFunc, Prev: Pod/Tree/PerlBin, Up: Module List translate Perl distribution documentation to HTML ************************************************* NAME ==== Pod::Tree::PerlDist - translate Perl distribution documentation to HTML SYNOPSIS ======== $perl_map = new Pod::Tree::PerlMap; $perl_dist = new Pod::Tree::PerlDist $perl_dir, $HTML_dir, $perl_map, %opts; $perl_dist->scan; $perl_dist->index; $perl_dist->translate; $top = $perl_dist->get_top_entry; DESCRIPTION =========== `Pod::Tree::PerlDist' translates documents in the Perl distribution to HTML. These include Changes, README, and assored other files that appear in the top level of the Perl source tree. Files that contain PODs are parsed as PODs; files that do not contain PODs are converted to HTML as preformatted text. `Pod::Tree::PerlDist' generates and uses an index of the files that it finds to construct HTML links. Other modules can also use this index. METHODS ======= $perl_dist = new `Pod::Tree::PerlDist' *$perl_dir*, *$HTML_dir*, *$perl_map*, %options Creates and returns a new `Pod::Tree::PerlDist' object. *$perl_dir* is the root of the Perl source tree. *$HTML_dir* is the directory where HTML files will be written. *$perl_map* maps file names to URLs. %options are passed through to `Pod::Tree::HTML'. $perl_dist->scan Scans the top level of the Perl source tree for documentation files. Files that do not generally contain user-level documentation, such as source files, are ignored. The search does not recurse through subdirectories. Each file that is located is entered into *$perl_map*. $perl_dist->index Generates a top-level index of all the distribution documents, and writes it to *HTML_dir*`/dist.html'. $perl_dist->translate Translates each distribution document found by scan to HTML. The HTML pages are written to *HTML_dir*. $perl_dist->`get_top_entry' Returns a hash reference of the form { URL => $URL, description => $description } `Pod::Tree::PerlTop' uses this to build a top-level index of all the Perl PODs. LINKING ======= `Pod::Tree::PerlDist' indexes files by their name. To link to a file named `README.win32' write L REQUIRES ======== 5.005; HTML::Stream; Pod::Tree; Pod::Tree::HTML; Pod::Tree::PerlUtil; EXPORTS ======= Nothing. SEE ALSO ======== ``Pod::Tree::HTML' in this node', ``Pod::Tree::PerlMap' in this node', AUTHOR ====== Steven McDougall, swmcd@world.std.com COPYRIGHT ========= Copyright 2000 by Steven McDougall. This program is free software; you can redistribute it and/or modify it under the same terms as Perl.  File: pm.info, Node: Pod/Tree/PerlFunc, Next: Pod/Tree/PerlLib, Prev: Pod/Tree/PerlDist, Up: Module List translate `perlfunc.pod' to HTML ******************************** NAME ==== Pod::Tree::PerlFunc - translate `perlfunc.pod' to HTML SYNOPSIS ======== $perl_map = new Pod::Tree::PerlMap; $perl_func = new Pod::Tree::PerlFunc $perl_dir, $HTML_dir, $perl_map, %opts; $perl_func->scan; $perl_func->index; $perl_func->translate; DESCRIPTION =========== `Pod::Tree::PerlFunc' translates `perlfunc.pod' to HTML. It creates a separate HTML page for each function description in `perlfunc.pod'. The pages for the individual descriptions are named after the function and written to a `func/' subdirectory. `perlfunc.html' is generated as an index to all the pages in `func/'. `Pod::Tree::PerlFunc' generates and uses an index of the functions that it finds in `perlfunc.pod' to construct HTML links. Other modules can also use this index. METHODS ======= $perl_func = new `Pod::Tree::PerlFunc' *$perl_dir*, *$HTML_dir*, *$perl_map*, %options Creates and returns a new `Pod::Tree::PerlFunc' object. *$perl_dir* is the root of the Perl source tree. *$HTML_dir* is the directory where HTML files will be written. *$perl_map* maps function names to URLs. %options are passed through to `Pod::Tree::HTML'. $perl_func->scan Reads `perlfunc.pod' and identifies all the functions in it. Each function that is identified is entered into *$perl_map*. $perl_func->index Generates a top-level index of all the functions. The index is written to *HTML_dir*`/pod/perlfunc.html'. $perl_func->translate Translates each function found by scan to HTML. The HTML pages are written to *HTML_dir*`/pod/func/'. LINKING ======= `Pod::Tree::PerlFunc' indexes every =item paragraph in `perlfunc.html'. To link, for example, to the abs function, write L REQUIRES ======== 5.005; Pod::Tree; Pod::Tree::HTML; Pod::Tree::PerlUtil; EXPORTS ======= Nothing. SEE ALSO ======== ``Pod::Tree::HTML' in this node', ``Pod::Tree::PerlMap' in this node', AUTHOR ====== Steven McDougall, swmcd@world.std.com COPYRIGHT ========= Copyright 2000 by Steven McDougall. This program is free software; you can redistribute it and/or modify it under the same terms as Perl.  File: pm.info, Node: Pod/Tree/PerlLib, Next: Pod/Tree/PerlMap, Prev: Pod/Tree/PerlFunc, Up: Module List translate module PODs to HTML ***************************** NAME ==== Pod::Tree::PerlLib - translate module PODs to HTML SYNOPSIS ======== $perl_map = new Pod::Tree::PerlMap; $perl_lib = new Pod::Tree::PerlLib $perl_dir, $HTML_dir, $perl_map, %opts; $perl_lib->scan(@INC); $perl_lib->index; $perl_lib->translate; $top = $perl_lib->get_top_entry; DESCRIPTION =========== `Pod::Tree::PerlLib' translates module PODs to HTML. It does a recursive subdirectory search through a list of directories (typically `@INC') to find PODs. `Pod::Tree::PerlLib' generates a top-level index of all the PODs that it finds, and writes it to *HTML_dir*`/lib.html'. `Pod::Tree::PerlLib' generates and uses an index of the PODs that it finds to construct HTML links. Other modules can also use this index. METHODS ======= $perl_lib = new `Pod::Tree::PerlLib' *$perl_dir*, *$HTML_dir*, *$perl_map*, %options Creates and returns a new `Pod::Tree::PerlLib' object. *$HTML_dir* is the directory where HTML files will be written. *$perl_map* maps module names to URLs. %options are passed through to `Pod::Tree::HTML'. The *$perl_dir* argument is included for consistency with the other `Pod::Tree::Perl*' modules, but is currently unused. $perl_lib->scan(*@INC*) Does a recursive subdirectory search through *@INC* to locate module PODs. Each module that is identified is entered into *$perl_map*. $perl_lib->index Generates a top-level index of all the modules. The index is written to *HTML_dir*`/lib.html'. $perl_lib->translate Translates each module POD found by scan to HTML. The HTML pages are written to *HTML_dir*`/lib/', in a subdirectory hierarchy that maps the module names. $perl_lib->`get_top_entry' Returns a hash reference of the form { URL => $URL, description => $description } `Pod::Tree::PerlTop' uses this to build a top-level index of all the Perl PODs. LINKING ======= `Pod::Tree::PerlLib' expects the second paragraph of the POD to have the form Foo::Bar - description and enters *Foo::Bar* into *$perl_map*. To link to a module POD, write L REQUIRES ======== 5.005; HTML::Stream; Pod::Tree; Pod::Tree::HTML; Pod::Tree::PerlUtil; EXPORTS ======= Nothing. SEE ALSO ======== ``Pod::Tree::HTML' in this node', ``Pod::Tree::PerlMap' in this node', AUTHOR ====== Steven McDougall, swmcd@world.std.com COPYRIGHT ========= Copyright 2000 by Steven McDougall. This program is free software; you can redistribute it and/or modify it under the same terms as Perl.  File: pm.info, Node: Pod/Tree/PerlMap, Next: Pod/Tree/PerlPod, Prev: Pod/Tree/PerlLib, Up: Module List map names to URLs ***************** NAME ==== Pod::Tree::PerlMap - map names to URLs SYNOPSIS ======== $perl_map = new Pod::Tree::PerlMap; $perl_map->add_page ($name, $file); $perl_map->add_func ($func, $file); $perl_map->force_func(0); $perl_map->force_func(1); $perl_map->set_depth ($depth); ($base, $page, $section) = $perl_map->map($base, $page, $section); DESCRIPTION =========== `Pod::Tree::PerlMap' maps L<> markups to URLs. The `Pod::Tree::Perl*' translators make entries in the map. `Pod::Tree::HTML' uses the map to translate links before it emits them. METHODS ======= *$perl_map*->`add_page'($name, $file) Map $name to $file. $name is the name of a POD, as used in L<> markups. $file is the path to the HTML file that is the target of the link. *$perl_map*->`add_func'(*$func*, $file) Maps *$func* to $file. *$func* is the name of a function described in `perlfunc.pod'. $file is the name of the HTML file where it is described. *$perl_map*->`force_func'($state) Controls interpretation of links of the form L. If $state is true, calls to map will interpret L as L. If $state is false, calls to map will interpret L normally. *$perl_map*->`set_depth'(*$depth*) Informs *$perl_map* of the depth of the referring page in the HTML directory tree. *$perl_map* needs to know this so that it can construct relative links. ($base, $page, $section) = *$perl_map*->map($base, $page, $section) Remaps a link. $base is the base URL for the HTML page, if any. $page is the page given in an L<> markup. $section is the section given in the L<> markup, if any. map returns a new $base, $page, and $section that can be used to construct a link to the HTML page. REQUIRES ======== Nothing. EXPORTS ======= Nothing. AUTHOR ====== Steven McDougall, swmcd@world.std.com COPYRIGHT ========= Copyright 2000 by Steven McDougall. This program is free software; you can redistribute it and/or modify it under the same terms as Perl.  File: pm.info, Node: Pod/Tree/PerlPod, Next: Pod/Tree/PerlTop, Prev: Pod/Tree/PerlMap, Up: Module List translate Perl PODs to HTML *************************** NAME ==== Pod::Tree::PerlPod - translate Perl PODs to HTML SYNOPSIS ======== $perl_map = new Pod::Tree::PerlMap; $perl_pod = new Pod::Tree::PerlPod $perl_dir, $HTML_dir, $perl_map, %opts; $perl_pod->scan; $perl_pod->index; $perl_pod->translate; $top = $perl_pod->get_top_entry; DESCRIPTION =========== `Pod::Tree::PerlPod' translates Perl PODs to HTML. It does a recursive subdirectory search through *$perl_dir* to find PODs. `Pod::Tree::PerlPod' generates a top-level index of all the PODs that it finds, and writes it to *HTML_dir*`/pod.html'. `Pod::Tree::PerlPod' generates and uses an index of the PODs that it finds to construct HTML links. Other modules can also use this index. METHODS ======= $perl_pod = new `Pod::Tree::PerlPod' *$perl_dir*, *$HTML_dir*, *$perl_map*, %options Creates and returns a new `Pod::Tree::PerlPod' object. *$perl_dir* is the root of the Perl source tree. *$HTML_dir* is the directory where HTML files will be written. *$perl_map* maps POD names to URLs. %options are passed through to `Pod::Tree::HTML'. $perl_pod->scan; Does a recursive subdirectory search through *$perl_dir* to locate PODs. Each POD that is located is entered into *$perl_map*. $perl_pod->index Generates a top-level index of all the PODs. The index is written to *HTML_dir*`/pod.html'. $perl_pod->translate Translates each POD found by scan to HTML. The HTML pages are written to *HTML_dir*, in a subdirectory hierarchy that mirrors the the Perl source distribution. $perl_pod->`get_top_entry' Returns a hash reference of the form { URL => $URL, description => $description } `Pod::Tree::PerlTop' uses this to build a top-level index of all the Perl PODs. LINKING ======= `Pod::Tree::PerlPod' indexes PODs by the base name of the POD file. To link to `perlsub.pod', write L REQUIRES ======== 5.005; File::Find; HTML::Stream; IO::File; Pod::Tree::HTML; Pod::Tree::PerlUtil; EXPORTS ======= Nothing. SEE ALSO ======== ``Pod::Tree::HTML' in this node', ``Pod::Tree::PerlMap' in this node', AUTHOR ====== Steven McDougall, swmcd@world.std.com COPYRIGHT ========= Copyright 2000 by Steven McDougall. This program is free software; you can redistribute it and/or modify it under the same terms as Perl.  File: pm.info, Node: Pod/Tree/PerlTop, Next: Pod/Tree/Pod, Prev: Pod/Tree/PerlPod, Up: Module List generate a top-level index for Perl PODs **************************************** NAME ==== Pod::Tree::PerlTop - generate a top-level index for Perl PODs SYNOPSIS ======== $perl_map = new Pod::Tree::PerlMap; $perl_top = new Pod::Tree::PerlTop $perl_dir, $HTML_dir, $perl_map, %opts; $perl_top->index(@translators); $perl_top->translate; $top = $perl_top->get_top_entry; DESCRIPTION =========== `Pod::Tree::PerlTop' generates a top-level index for Perl PODs. It also translates `perl.pod' to `perl.html' The translator is specially hacked to insert links into the big verbatim paragraph that lists all the other Perl PODs. METHODS ======= $perl_top = new `Pod::Tree::PerlTop' *$perl_dir*, *$HTML_dir*, *$perl_map*, %options Creates and returns a new `Pod::Tree::PerlTop' object. *$perl_dir* is the root of the Perl source tree. *$HTML_dir* is the directory where HTML files will be written. *$perl_map* maps POD names to URLs. `Pod::Tree::PerlTop' uses it to resolve links in the `perl.pod' page. %options are passed through to `Pod::Tree::HTML'. $perl_top->index(*@translators*) Generates a top-level index of all the PODs. The index is written to *HTML_dir*`/index.html'. *@translators* is a list of other `Pod::Tree::Perl*' translator objects. index makes a `get_top_entry' call on each of them to obtain URLs and descriptions of the pages that it links to. $perl_top->translate Translates the `perl.pod' file to HTML. The HTML page is written to *HTML_dir*`/pod/perl.html' $perl_top->`get_top_entry' Returns a hash reference of the form { URL => $URL, description => $description } `Pod::Tree::PerlTop' uses this to build a top-level index of all the Perl PODs. REQUIRES ======== 5.005; Pod::Tree::HTML; Pod::Tree::PerlUtil; EXPORTS ======= Nothing. SEE ALSO ======== ``Pod::Tree::HTML' in this node', ``Pod::Tree::PerlMap' in this node', AUTHOR ====== Steven McDougall, swmcd@world.std.com COPYRIGHT ========= Copyright 2000 by Steven McDougall. This program is free software; you can redistribute it and/or modify it under the same terms as Perl.  File: pm.info, Node: Pod/Tree/Pod, Next: Pod/Usage, Prev: Pod/Tree/PerlTop, Up: Module List Convert a Pod::Tree back to a POD ********************************* NAME ==== Pod::Tree::Pod - Convert a Pod::Tree back to a POD SYNOPSIS ======== use Pod::Tree::Pod; $tree = new Pod::Tree; $dest = new IO::File; $dest = "file.pod"; $pod = new Pod:::Tree::HTML $tree, $dest; $pod->translate; DESCRIPTION =========== `Pod::Tree::Pod' converts a Pod::Tree back to a POD. The destination is fixed when the object is created. The translate method does the actual translation. For convenience, Pod::Tree::Pod can write the POD to a variety of destinations. The new method resolves the $dest argument. Destination resolution ---------------------- `Pod::Tree::Pod' can write HTML to either of 2 destinations. new resolves $dest by checking these things, in order: 1. If $dest is a reference, then it is taken to be an IO::File object that is already open on the file where the POD will be written. 2. If $dest is not a reference, then it is taken to be the name of the file where the POD will be written. METHODS ======= $pod = new `Pod::Tree::Pod' $tree, $dest Creates a new `Pod::Tree::Pod' object. $tree is a `Pod::Tree' object that represents a POD. $pod writes the POD to $dest. See `' in this node for details. $pod->translate Writes the text of the POD. This method should only be called once. DIAGNOSTICS =========== `Pod::Tree::Pod::new: not enough arguments' (F) new called with fewer than 2 arguments. `Pod::Tree::HTML::new: Can't open $dest: $!' (F) The destination file couldn't be opened. NOTES ===== * The destination doesn't actually have to be an IO::File object. It may be any object that has a print method. SEE ALSO ======== perl(1), ``Pod::Tree' in this node', ``Pod::Tree::Node' in this node' AUTHOR ====== Steven McDougall, swmcd@world.std.com COPYRIGHT ========= Copyright 2000 by Steven McDougall. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Pod/Usage, Next: Pod/XML, Prev: Pod/Tree/Pod, Up: Module List print a usage message from embedded pod documentation ***************************************************** NAME ==== Pod::Usage, pod2usage() - print a usage message from embedded pod documentation SYNOPSIS ======== use Pod::Usage my $message_text = "This text precedes the usage message."; my $exit_status = 2; ## The exit status to use my $verbose_level = 0; ## The verbose level to use my $filehandle = \*STDERR; ## The filehandle to write to pod2usage($message_text); pod2usage($exit_status); pod2usage( { -message => $message_text , -exitval => $exit_status , -verbose => $verbose_level, -output => $filehandle } ); pod2usage( -msg => $message_text , -exitval => $exit_status , -verbose => $verbose_level, -output => $filehandle ); ARGUMENTS ========= *pod2usage* should be given either a single argument, or a list of arguments corresponding to an associative array (a "hash"). When a single argument is given, it should correspond to exactly one of the following: * A string containing the text of a message to print before printing the usage message * A numeric value corresponding to the desired exit status * A reference to a hash If more than one argument is given then the entire argument list is assumed to be a hash. If a hash is supplied (either as a reference or as a list) it should contain one or more elements with the following keys: `-message' `-msg' The text of a message to print immediately prior to printing the program's usage message. `-exitval' The desired exit status to pass to the exit() function. `-verbose' The desired level of "verboseness" to use when printing the usage message. If the corresponding value is 0, then only the "SYNOPSIS" section of the pod documentation is printed. If the corresponding value is 1, then the "SYNOPSIS" section, along with any section entitled "OPTIONS", "ARGUMENTS", or "OPTIONS AND ARGUMENTS" is printed. If the corresponding value is 2 or more then the entire manpage is printed. `-output' A reference to a filehandle, or the pathname of a file to which the usage message should be written. The default is `\*STDERR' unless the exit value is less than 2 (in which case the default is `\*STDOUT'). `-input' A reference to a filehandle, or the pathname of a file from which the invoking script's pod documentation should be read. It defaults to the file indicated by $0 ($PROGRAM_NAME for users of `English.pm'). `-pathlist' A list of directory paths. If the input file does not exist, then it will be searched for in the given directory list (in the order the directories appear in the list). It defaults to the list of directories implied by `$ENV{PATH}'. The list may be specified either by a reference to an array, or by a string of directory paths which use the same path separator as `$ENV{PATH}' on your system (e.g., : for Unix, `;' for MSWin32 and DOS). DESCRIPTION =========== *pod2usage* will print a usage message for the invoking script (using its embedded pod documentation) and then exit the script with the desired exit status. The usage message printed may have any one of three levels of "verboseness": If the verbose level is 0, then only a synopsis is printed. If the verbose level is 1, then the synopsis is printed along with a description (if present) of the command line options and arguments. If the verbose level is 2, then the entire manual page is printed. Unless they are explicitly specified, the default values for the exit status, verbose level, and output stream to use are determined as follows: * If neither the exit status nor the verbose level is specified, then the default is to use an exit status of 2 with a verbose level of 0. * If an exit status *is* specified but the verbose level is not, then the verbose level will default to 1 if the exit status is less than 2 and will default to 0 otherwise. * If an exit status is not specified but verbose level *is* given, then the exit status will default to 2 if the verbose level is 0 and will default to 1 otherwise. * If the exit status used is less than 2, then output is printed on STDOUT. Otherwise output is printed on `STDERR'. Although the above may seem a bit confusing at first, it generally does "the right thing" in most situations. This determination of the default values to use is based upon the following typical Unix conventions: * An exit status of 0 implies "success". For example, *diff(1)* exits with a status of 0 if the two files have the same contents. * An exit status of 1 implies possibly abnormal, but non-defective, program termination. For example, *grep(1)* exits with a status of 1 if it did not find a matching line for the given regular expression. * An exit status of 2 or more implies a fatal error. For example, *ls(1)* exits with a status of 2 if you specify an illegal (unknown) option on the command line. * Usage messages issued as a result of bad command-line syntax should go to `STDERR'. However, usage messages issued due to an explicit request to print usage (like specifying *-help* on the command line) should go to STDOUT, just in case the user wants to pipe the output to a pager (such as *more(1)*). * If program usage has been explicitly requested by the user, it is often desireable to exit with a status of 1 (as opposed to 0) after issuing the user-requested usage message. It is also desireable to give a more verbose description of program usage in this case. *pod2usage* doesn't force the above conventions upon you, but it will use them by default if you don't expressly tell it to do otherwise. The ability of *pod2usage()* to accept a single number or a string makes it convenient to use as an innocent looking error message handling function: use Pod::Usage; use Getopt::Long; ## Parse options GetOptions("help", "man", "flag1") || pod2usage(2); pod2usage(1) if ($opt_help); pod2usage(-verbose => 2) if ($opt_man); ## Check for too many filenames pod2usage("$0: Too many files given.\n") if (@ARGV > 1); Some user's however may feel that the above "economy of expression" is not particularly readable nor consistent and may instead choose to do something more like the following: use Pod::Usage; use Getopt::Long; ## Parse options GetOptions("help", "man", "flag1") || pod2usage(-verbose => 0); pod2usage(-verbose => 1) if ($opt_help); pod2usage(-verbose => 2) if ($opt_man); ## Check for too many filenames pod2usage(-verbose => 2, -message => "$0: Too many files given.\n") if (@ARGV > 1); As with all things in Perl, *there's more than one way to do it*, and *pod2usage()* adheres to this philosophy. If you are interested in seeing a number of different ways to invoke *pod2usage* (although by no means exhaustive), please refer to `"EXAMPLES"' in this node. EXAMPLES ======== Each of the following invocations of `pod2usage()' will print just the "SYNOPSIS" section to `STDERR' and will exit with a status of 2: pod2usage(); pod2usage(2); pod2usage(-verbose => 0); pod2usage(-exitval => 2); pod2usage({-exitval => 2, -output => \*STDERR}); pod2usage({-verbose => 0, -output => \*STDERR}); pod2usage(-exitval => 2, -verbose => 0); pod2usage(-exitval => 2, -verbose => 0, -output => \*STDERR); Each of the following invocations of `pod2usage()' will print a message of "Syntax error." (followed by a newline) to `STDERR', immediately followed by just the "SYNOPSIS" section (also printed to `STDERR') and will exit with a status of 2: pod2usage("Syntax error."); pod2usage(-message => "Syntax error.", -verbose => 0); pod2usage(-msg => "Syntax error.", -exitval => 2); pod2usage({-msg => "Syntax error.", -exitval => 2, -output => \*STDERR}); pod2usage({-msg => "Syntax error.", -verbose => 0, -output => \*STDERR}); pod2usage(-msg => "Syntax error.", -exitval => 2, -verbose => 0); pod2usage(-message => "Syntax error.", -exitval => 2, -verbose => 0, -output => \*STDERR); Each of the following invocations of `pod2usage()' will print the "SYNOPSIS" section and any "OPTIONS" and/or "ARGUMENTS" sections to STDOUT and will exit with a status of 1: pod2usage(1); pod2usage(-verbose => 1); pod2usage(-exitval => 1); pod2usage({-exitval => 1, -output => \*STDOUT}); pod2usage({-verbose => 1, -output => \*STDOUT}); pod2usage(-exitval => 1, -verbose => 1); pod2usage(-exitval => 1, -verbose => 1, -output => \*STDOUT}); Each of the following invocations of `pod2usage()' will print the entire manual page to STDOUT and will exit with a status of 1: pod2usage(-verbose => 2); pod2usage({-verbose => 2, -output => \*STDOUT}); pod2usage(-exitval => 1, -verbose => 2); pod2usage({-exitval => 1, -verbose => 2, -output => \*STDOUT}); Recommended Use --------------- Most scripts should print some type of usage message to `STDERR' when a command line syntax error is detected. They should also provide an option (usually -H or `-help') to print a (possibly more verbose) usage message to STDOUT. Some scripts may even wish to go so far as to provide a means of printing their complete documentation to STDOUT (perhaps by allowing a `-man' option). The following complete example uses Pod::Usage in combination with Getopt::Long to do all of these things: use Getopt::Long; use Pod::Usage; my $man = 0; my $help = 0; ## Parse options and print usage if there is a syntax error, ## or if usage was explicitly requested. GetOptions('help|?' => \$help, man => \$man) or pod2usage(2); pod2usage(1) if $help; pod2usage(-verbose => 2) if $man; ## If no arguments were given, then allow STDIN to be used only ## if it's not connected to a terminal (otherwise print usage) pod2usage("$0: No files given.") if ((@ARGV == 0) && (-t STDIN)); __END__ =head1 NAME sample - Using GetOpt::Long and Pod::Usage =head1 SYNOPSIS sample [options] [file ...] Options: -help brief help message -man full documentation =head1 OPTIONS =over 8 =item B<-help> Print a brief help message and exits. =item B<-man> Prints the manual page and exits. =back =head1 DESCRIPTION B will read the given input file(s) and do something useful with the contents thereof. =cut CAVEATS ======= By default, *pod2usage()* will use $0 as the path to the pod input file. Unfortunately, not all systems on which Perl runs will set $0 properly (although if $0 isn't found, *pod2usage()* will search `$ENV{PATH}' or else the list specified by the `-pathlist' option). If this is the case for your system, you may need to explicitly specify the path to the pod docs for the invoking script using something similar to the following: pod2usage(-exitval => 2, -input => "/path/to/your/pod/docs"); AUTHOR ====== Brad Appleton Based on code for *Pod::Text::pod2text()* written by Tom Christiansen ACKNOWLEDGEMENTS ================ Steven McDougall for his help and patience with re-writing this manpage.