This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: PlotCalendar/Month, Next: PlusPlus, Prev: PlotCalendar/Day, Up: Module List Plot an ASCII or HTML calendar ****************************** NAME ==== PlotCalendar::Month - Plot an ASCII or HTML calendar SYNOPSIS ======== Creates a Month object for plotting as ASCII, HTML, or in a Perl/Tk Canvas. Calls Day.pm for the individual days within the calendar. DESCRIPTION =========== Measurements in pixels because - well, because. It seemed simpler when I made the decision. And it works for both Tk and HTML. The month is laid out like this : Month_name Year --------------------------------------------------------------- | Sun | Mon | Tue | Wed | Thu | Fri | Sat | --------------------------------------------------------------- | | | | | | | | | day | day | | | | | | | | | | | | | | |--------|--------|--------|-------|--------|--------|--------| | | | | | | | | | day | day | | | | | | | | | | | | | | |--------|--------|--------|-------|--------|--------|--------| | | | | | | | | | day | day | | | | | | | | | | | | | | |--------|--------|--------|-------|--------|--------|--------| | | | | | | | | | day | day | | | | | | | | | | | | | | |--------|--------|--------|-------|--------|--------|--------| | | | | | | | | | day | day | | | | | | | | | | | | | | |--------|--------|--------|-------|--------|--------|--------| | | | | | | | | | day | day | | | | | | optional | | | | | | | | row |--------|--------|--------|-------|--------|--------|--------| Globals : height, width, fgcol, bgcolmain, References expect to be given the entire thing, that is or The software will terminate it with a at the right spot. EXAMPLE ======= require PlotCalendar::Month; my $month = PlotCalendar::Month->new(01,1999); # Jan 1999 # global values, to be applied to all cells ------------------------- size of whole calendar $month -> size(700,700); # width, height in pixels ------------------------- font sizes for digit, name of day, and text $month -> font('14','10','8'); ------------------------- clip text if it wants to wrap? $month -> cliptext('yes'); ------------------------- This can be any day you want $month -> firstday('Sun'); # First column is Sunday ------------------------- If this is not set, regular text will be used. ------------------------- If it is set, then in that directory should be ------------------------- gif files named 0.gif, 1.gif ... January.gif, ... $month -> artwork('/home/ajackson/public_html/cgi-bin/Calendar/Calendar_art3/'); # arrays of values, if not an array, apply to all cells, if an array # apply to each cell, indexed by day-of-month The colors are the standard values used in html Textstyle encoding is b=bold, i=italic, u=underline, n=normal Fontsize = 6-14, roughly point sizes my @text; my @daynames; my @nameref; my @bgcolor; my @colors = ('WHITE','#33cc00','#FF99FF','#FF7070','#FFB0B0',); my (@textcol,@textsize,@textstyle,@textref); my @style = ('i','u','b',); my @url; ----------- build some random color and text fields as a demo for (my $i=1;$i<=31;$i++) { $daynames[$i] = "Day number $i"; $nameref[$i] = ""; $bgcolor[$i] = $colors[$i%5]; @{$text[$i]} = ("Text 1 for $i","Second $i text","$i bit of text",); @{$textref[$i]} = ("","Second $i text","",); @{$textcol[$i]} = ($colors[($i+1)%5],$colors[($i+2)%5],$colors[($i+3)%5]); @{$textsize[$i]} = ("8","10","8",); @{$textstyle[$i]} = @style; @style = reverse(@style); $url[$i] = ''; } ------------------------- Set global values $month -> fgcolor('BLACK',); # Global foreground color $month -> bgcolor(@bgcolor); # Background color per day $month -> styles('b','bi','ui',); # Global text styles # Comments my @prefs = ('before','after','after'); my @comments = (['Comment one'],["Comment two","and so on"],['Comment three']); my @comcol = qw(b g b); my @comstyle = qw(n b bi); my @comsize = qw(8 10 14); ------------------------- Comments get stuck into an otherwise empty cell $month->comments(\@prefs,\@comments,\@comcol,\@comstyle,\@comsize); ------------------------- Wrap a hotlink around the whole day, for each day $month -> htmlref(@url); ------------------------- set the names for every day $month -> dayname(@daynames); ------------------------- wrap the name in a hotlink $month -> nameref(@nameref); ------------------------- set the text and it's properties for each day $month -> text(@text); $month -> textcolor(@textcol); $month -> textsize(@textsize); $month -> textstyle(@textstyle); $month -> textref(@textref); # global HTML only options ----------------- allow days to expand vertically to accomodate text $month -> htmlexpand('yes'); # grab an ascii calendar and print it my $text = $month -> getascii; print $text; ------------------- get the html calendar my $html = $month -> gethtml; print "\n"; print $html; SEE ALSO ======== Also look at Day.pm DEPENDENCIES ============ PlotCalendar::DateTools This is a pure perl replacement for Date::Calc. I needed it because Date::Calc contains C code which my web hosting service did not have available for CGI-BIN stuff. AUTHOR ====== Alan Jackson March 1999 ajackson@icct.net  File: pm.info, Node: PlusPlus, Next: Pod/Checker, Prev: PlotCalendar/Month, Up: Module List [Delphi|VB|Java]-like Perl preprocessor *************************************** NAME ==== PlusPlus - [Delphi|VB|Java]-like Perl preprocessor SYNOPSIS ======== use PlusPlus; my $nested_hash = {outer => {inner => {a => 1, b => 2, c => 3}}} $nested_hash.outer.inner.a = 5; # dot syntax for variables $dbh.do ("DROP DATABASE TEST"); # dot syntax for methods with ($nested_hash.outer.inner) { # 'with' operator ($.a, $.c) = (10, 30); print " b = $.b\n"; }; DESCRIPTION =========== *PlusPlus* is a quick and (maybe) a little bit dirty way to have some additional comfort when working with nested Perl data structures. This module allows some extensions to the Perl syntax. *PlusPlus* is a source filter (preprocessor) based on the module Filter. DOT SYNTAX ---------- Using *PlusPlus*, you can dramatically clearify your code by typing $foo.bar.baz each time instead of $foo -> {bar} -> {baz} Yes, of course, the dot means the concatenation operator. So, you might suppose a collision in case like $foo.$bar What would it be: I<"$foo.$bar"> or I<$foo->{$bar}>? Please, remind: when using B, always type at least one space aside of your concatenation dot. So, $foo.$bar eq $foo->{$bar} $foo . $bar eq "$foo$bar" And what about the method calls? It's very similar (see SYNOPSYS). But, note: the method call must be followed by an open paranthesis, even if the argument list is void. $st.finish eq $st -> {finish} $st.finish () eq $st -> finish () WITH ---- The *PlusPlus* preprocessor introduces the with operator in the manner similar to Borland (C) Delphi (R) and MS ($) VB (...). Each fragment of code like with ($foo) { ... }; is mapped to do { my $__with__prefix__ = ($foo); ... }; All variables like $.bar are renamed to $__with__prefix__.bar. It is very unprobably that you use the variable named $__with__prefix__, but, in any case, you are warned. And, please, don't forget to put a semicolon after the closing brace: with is do, not while. AUTHOR ====== D. E. Ovyanko, do@mobile.ru SEE ALSO ======== Filter(3).  File: pm.info, Node: Pod/Checker, Next: Pod/Compiler, Prev: PlusPlus, Up: Module List check pod documents for syntax errors ************************************* NAME ==== Pod::Checker, podchecker() - check pod documents for syntax errors SYNOPSIS ======== use Pod::Checker; $syntax_okay = podchecker($filepath, $outputpath, %options); my $checker = new Pod::Checker %options; $checker->parse_from_file($filepath, \*STDERR); OPTIONS/ARGUMENTS ================= `$filepath' is the input POD to read and `$outputpath' is where to write POD syntax error messages. Either argument may be a scalar indicating a file-path, or else a reference to an open filehandle. If unspecified, the input-file it defaults to `\*STDIN', and the output-file defaults to `\*STDERR'. podchecker() ------------ This function can take a hash of options: *-warnings* => val Turn warnings on/off. See `"Warnings"' in this node. DESCRIPTION =========== *podchecker* will perform syntax checking of Perl5 POD format documentation. *NOTE THAT THIS MODULE IS CURRENTLY IN THE BETA STAGE!* It is hoped that curious/ambitious user will help flesh out and add the additional features they wish to see in Pod::Checker and *podchecker* and verify that the checks are consistent with *Note Perlpod: (perl.info)perlpod,. The following checks are currently preformed: * Unknown '=xxxx' commands, unknown 'X<...>' interior-sequences, and unterminated interior sequences. * Check for proper balancing of =begin and =end. The contents of such a block are generally ignored, i.e. no syntax checks are performed. * Check for proper nesting and balancing of =over, =item and =back. * Check for same nested interior-sequences (e.g. `L<...L<...>...>'). * Check for malformed or nonexisting entities `E<...>'. * Check for correct syntax of hyperlinks `L<...>'. See *Note Perlpod: (perl.info)perlpod, for details. * Check for unresolved document-internal links. This check may also reveal misspelled links that seem to be internal links but should be links to something else. DIAGNOSTICS =========== Errors ------ * empty =headn A heading (=head1 or =head2) without any text? That ain't no heading! * =over on line N without closing =back The =over command does not have a corresponding =back before the next heading (=head1 or =head2) or the end of the file. * =item without previous =over * =back without previous =over An =item or =back command has been found outside a =over/=back block. * No argument for =begin A =begin command was found that is not followed by the formatter specification. * =end without =begin A standalone =end command was found. * Nested =begin's There were at least two consecutive =begin commands without the corresponding =end. Only one =begin may be active at a time. * =for without formatter specification There is no specification of the formatter after the =for command. * unresolved internal link NAME The given link to NAME does not have a matching node in the current POD. This also happend when a single word node name is not enclosed in "". * Unknown command "*CMD*" An invalid POD command has been found. Valid are =head1, =head2, =over, =item, =back, =begin, =end, =for, =pod, =cut * Unknown interior-sequence "*SEQ*" An invalid markup command has been encountered. Valid are: `B<>', `C<>', `E<>', `F<>', `I<>', `L<>', `S<>', `X<>', `Z<>' * nested commands *CMD*<...*CMD*<...>...> Two nested identical markup commands have been found. Generally this does not make sense. * garbled entity STRING The STRING found cannot be interpreted as a character entity. * Entity number out of range An entity specified by number (dec, hex, oct) is out of range (1-255). * malformed link L<> The link found cannot be parsed because it does not conform to the syntax described in *Note Perlpod: (perl.info)perlpod,. * nonempty Z<> The `Z<>' sequence is supposed to be empty. * empty X<> The index entry specified contains nothing but whitespace. * Spurious text after =pod / =cut The commands =pod and =cut do not take any arguments. * Spurious character(s) after =back The =back command does not take any arguments. Warnings -------- These may not necessarily cause trouble, but indicate mediocre style. * multiple occurence of link target name The POD file has some =item and/or `=head' commands that have the same text. Potential hyperlinks to such a text cannot be unique then. * line containing nothing but whitespace in paragraph There is some whitespace on a seemingly empty line. POD is very sensitive to such things, so this is flagged. *vi* users switch on the list option to avoid this problem. * file does not start with =head The file starts with a different POD directive than head. This is most probably something you do not want. * No numeric argument for =over The =over command is supposed to have a numeric argument (the indentation). * previous =item has no contents There is a list =item right above the flagged line that has no text contents. You probably want to delete empty items. * preceding non-item paragraph(s) A list introduced by =over starts with a text or verbatim paragraph, but continues with =items. Move the non-item paragraph out of the =over/=back block. * =item type mismatch (one vs. *two*) A list started with e.g. a bulletted =item and continued with a numbered one. This is obviously inconsistent. For most translators the type of the first =item determines the type of the list. * N unescaped `<>' in paragraph Angle brackets not written as `' and `' can potentially cause errors as they could be misinterpreted as markup commands. * Unknown entity A character entity was found that does not belong to the standard ISO set or the POD specials `verbar' and `sol'. * No items in =over The list opened with =over does not contain any items. * No argument for =item * empty section in previous paragraph The previous section (introduced by a `=head' command) does not contain any text. This usually indicates that something is missing. Note: A =head1 followed immediately by =head2 does not trigger this warning. * Verbatim paragraph in NAME section The NAME section (`=head1 NAME') should consist of a single paragraph with the script/module name, followed by a dash `-' and a very short description of what the thing is good for. * Hyperlinks There are some warnings wrt. hyperlinks: Leading/trailing whitespace, newlines in hyperlinks, brackets `()'. RETURN VALUE ============ *podchecker* returns the number of POD syntax errors found or -1 if there were no POD commands at all found in the file. EXAMPLES ======== *[T.B.D.]* INTERFACE ========= While checking, this module collects document properties, e.g. the nodes for hyperlinks (`=headX', =item) and index entries (`X<>'). POD translators can use this feature to syntax-check and get the nodes in a first pass before actually starting to convert. This is expensive in terms of execution time, but allows for very robust conversions. `$checker->poderror( @args )' `$checker->poderror( {%opts}, @args )' Internal method for printing errors and warnings. If no options are given, simply prints "@_". The following options are recognized and used to form the output: -msg A message to print prior to `@args'. -line The line number the error occurred in. -file The file (name) the error occurred in. -severity The error level, should be 'WARNING' or 'ERROR'. `$checker->num_errors()' Set (if argument specified) and retrieve the number of errors found. `$checker->name()' Set (if argument specified) and retrieve the canonical name of POD as found in the `=head1 NAME' section. `$checker->node()' Add (if argument specified) and retrieve the nodes (as defined by `=headX' and =item) of the current POD. The nodes are returned in the order of their occurence. They consist of plain text, each piece of whitespace is collapsed to a single blank. `$checker->idx()' Add (if argument specified) and retrieve the index entries (as defined by `X<>') of the current POD. They consist of plain text, each piece of whitespace is collapsed to a single blank. `$checker->hyperlink()' Add (if argument specified) and retrieve the hyperlinks (as defined by `L<>') of the current POD. They consist of an 2-item array: line number and Pod::Hyperlink object. AUTHOR ====== Brad Appleton (initial version), Marek Rouchal Based on code for *Pod::Text::pod2text()* written by Tom Christiansen  File: pm.info, Node: Pod/Compiler, Next: Pod/DocBook, Prev: Pod/Checker, Up: Module List compile POD into an object tree ******************************* NAME ==== Pod::Compiler - compile POD into an object tree SYNOPSIS ======== use Pod::Compiler; DESCRIPTION =========== This package, based on `Pod::Parser|Pod::Parser' in this node, compiles a given POD document into an object tree (based on `Tree::DAG_Node|Tree::DAG_Node' in this node). It prints errors and warnings about the POD it reads. The result can be used to conveniently convert the POD into any other format. The resulting objects have a variety of methods to ease the subsequent conversion. There are two script based on this package, namely `podchecker2|podchecker2' in this node, an enhanced POD syntax checker and `podlint|podlint' in this node, which beautifies the POD of a given file. This package is object-oriented, which means that you can quite easily build a derived package and override some methods in case the given behaviour does not exactly suit your needs. Package Functions ----------------- The following functions can be imported and called from a script, e.g. like this: use Pod::Compiler qw(pod_compile); my $root = pod_compile('myfile.pod'); pod_compile( { %options } , $file ) pod_compile( $file ) Compile the given $file using some %options and return the root of the object tree representing the POD in $file. The return value is either undef if some fatal error occured or an object of type Pod::root. See below for methods applicable to this class and for the options. The special option `-compiler => 'class'' lets you specify an alternate (derived) compiler class rather than *Pod::Compiler*. Compiler Object Interface ------------------------- The following section describes the OO interface of *Pod::Compiler*. $c = Pod::Compiler->new( %options ) Set up a new compiler object. Options (see below) can be passed as a hash, e.g. $c = Pod::Compiler->new( -warnings => 0 ); # don't be silly *Pod::Compiler* inherits from Pod::Parser. See *Note Pod/Parser: Pod/Parser, for additional methods. $c->initialize() Initalize, set defaults. The following options are set to the given defaults unless they have been defined at object creation: -errors => 1 Print POD syntax errors (using *messagehandler*) if option value is true. -warnings => 1 Print POD syntax warnings (using *messagehandler*) if option value is true. -idlength => 20 Pod::Compiler creates a unique node id for each `=head', =item and `X<>', consisting only of `\w' characters. The option value specifies how many characters from the original node text are used for the node id by the built-in *make_unique_node_id* method. See below for more information. -ignore => 'BCFS' This option specifies which interior sequences (e.g. `B<...>') are ignored when nested in itself, e.g. `B<...B<...>...>'. The inner B is simply discarded if the corresponding letter appears in the option value string. -unwrap => 'I' This option specifies which interior sequences (e.g. `I<...>') are unwrapped when nested in itself, e.g. `I<...I<...>...>' is turned into `I<...>...I<...>'. While some destination formats may handle such nestings appropriately, other might have problems. This option solves it right away. By the way, from a typographical point of view, italics are often used for emphasis. In order to emphasize something within an emphasis, one reverts to the non-italic font. name => '' This is used to store the (logical) name of the POD, i.e. for example the module name as it appears in `use module;'. It is used internally only to detect internal links pointing to the explicit page name. Example: You compile the file `Compiler.pm' which contains the package `Pod::Compiler'. You set name to `Pod::Compiler' (there is no safe automatic way to do so). Thus if the file includes a link like `L' it is recognized as an internal link and it is checked whether it resolves. Of course you should have written the link as `L'... -perlcode => 0 If set to true, the compiler will also return the Perl code blocks as objects Pod::perlcode, rather than only the POD embedded in the file. This is used e.g. by `podlint|podlint' in this node. $c->option( $name , $value ) Get or set the compile option (see above) given by $name. If $value is defined, the option is set to this value. The resulting (or unchanged) value is returned. $c->messagehandler( $severity , $message ) This method is called every time a warning or error occurs. *$severity* is one of 'ERROR' or 'WARNING', *$message* is a one-line string. The built-in method simply does warn "$severity: $message\n"; $c->name( [ $name ] ) Set/retrieve the name property, i.e. the canonical Pod name (e.g. `Pod::HTML'). See above for more details. $c->root() Return the root element (instance of class Pod::root) representing the compiled POD document. See below for more info about its methods. $c->make_unique_node_id($string) Turn given text string into a document unique node id. Can be overridden to adapt this to specific formatter needs. Basically this method takes a string and must return something (more or less dependent on the string) that is unique for this POD document. The built-in method maps all consecutive non-word characters and underlines to a single underline and truncates the result to *-idlength* (see options above). If the result already exists, a suffix `_n' is appended, where n is a number starting with 1. A different method could e.g. just return ascending numbers, but if you think of HTML output, a node id that resembles the text and has a fair chance to remain constant over subsequent compiles of the same document gives the opportunity to link to such anchors from external documents. NOTES ===== Building POD converters ----------------------- The *Pod::Compiler* module is designed to serve as a basis for complex POD converters, e.g. to HTML, FrameMaker or LaTeX that can handle multiple POD documents with a table of contents, an index and most imporant hyperlinks/crossreferences. The following flow outlines how such a converter may work: * Getting the documents to be converted Interpreting command line arguments and options, the converter should gather all the POD files to be converted. Note that because of the structure of POD hyperlinks and restrictions in the anchor format of the individual destination formats you'll almost certainly will need a two-pass apporach where you process all documents at once. See *Note Pod/Find: Pod/Find, for some useful helpers in locating POD documents. The documents are stored as Pod::doc in a Pod::doc::collection. * Compiling all documents The next step would be a loop over all documents, calling *Pod::Compiler* on each document. This checks the syntax, prints errors and warnings and generates an object tree and information about the document's hyperlink anchors. The latter (a Pod::node::collection) is stored in the Pod::doc, the former is saved to a temporary file (see also *Note File/Temp: File/Temp,) with the help of Storable. * Converting the documents The second loop over all documents does the actual conversion. If you do not care very much about OO principles, you may extend the *Pod::** packages by e.g. a as_html method, so that you can say `(Pod::root)->as_html'. Or you use the `walk_down' method of *Tree::DAG_Node* to traverse the object tree and convert the individual objects in the callback. The existing Pod::doc::collection is used to resolve the hyperlinks. Each node already has a node id assigned. The result is saved to the destination files and the temporary files can be removed. * Table of contents and index During or after the final conversion one can build a TOC and an index, derived from the `=headX' and =item/`X<>' respectively. Strategies for the index could be: Only the `X<>' entries, single worded =head2/=item, all hyperlink anchors that were hit during conversion, all =items, ... SEE ALSO ======== *Note Pod/Checker: Pod/Checker,, *Note Pod/Parser: Pod/Parser,, *Note Pod/Find: Pod/Find,, `pod2man' in this node, `pod2text' in this node, *Note Pod/Man: Pod/Man, AUTHOR ====== Marek Rouchal HISTORY ======= A big deal of this code has been recycled from a variety of existing Pod converters, e.g. by Tom Christiansen and Russ Allbery. A lot of ideas came from Nick Ing-Simmons' *PodToHtml*.  File: pm.info, Node: Pod/DocBook, Next: Pod/Dsr, Prev: Pod/Compiler, Up: Module List module to convert pod files to DocBook SGML ******************************************* NAME ==== Pod::DocBook - module to convert pod files to DocBook SGML SYNOPSIS ======== use Pod::DocBook; pod2docbook( [options] ); DESCRIPTION =========== Converts files from pod format ( see *Note Perlpod: (perl.info)perlpod, ) to DocBook format. It can automatically generate indexes and cross-references, and it keeps a cache of things it knows how to cross-reference. ARGUMENTS ========= Pod::DocBook takes the following arguments: help --help Displays the usage message. 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. title --title=title Specify the title of the resulting HTML file. no-header --no-header Doesn't write a default header out for the DTD. no-footer --no-footer Doesn't write a default footer out for the DTD. root-id --root-id Specifies the root identifier for the base element used in chapter and section tags. The default is *pod2docbook-ch-1*. verbose --verbose Display progress messages. EXAMPLE ======= pod2docbook( "pod2docbook", "--infile=foo.pod", "--outfile=/perl/nmanual/foo.sgml" ); AUTHOR ====== Alligator Descartes from the original `pod2html' in this node source code by Tom Christiansen, , for it is he. Many thanks to Chris Maden of O'Reilly & Associations for doing serious road-testing on this module. BUGS ==== Has trouble with etc in = commands. LIMITATIONS =========== Nested =over/=back lists are not supported within DocBook. SEE ALSO ======== *Note Perlpod: (perl.info)perlpod, COPYRIGHT ========= This program is distributed under the Artistic License.  File: pm.info, Node: Pod/Dsr, Next: Pod/Find, Prev: Pod/DocBook, Up: Module List Convert POD data to formatted DSR input *************************************** NAME ==== Pod::Dsr - Convert POD data to formatted DSR input SYNOPSIS ======== use Pod::Dsr; my $parser = Pod::Dsr->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::Dsr is a module to convert documentation in the POD format (the preferred language for documenting Perl) into Digital Standard Runoff (DSR) input. The resulting DSR code is suitable for display on a terminal using RUNOFF(1) and TYPE(1), or printing using RUNOFF(1) and PRINT(1). It is conventionally invoked using the driver script *pod2rno*, but it can also be used directly. As a derived class from Pod::Parser, Pod::Dsr supports the same methods and interfaces. See *Note Pod/Parser: Pod/Parser, for all the details; briefly, one creates a new parser with `Pod::Dsr->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::Dsr 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). Besides the obvious pod conversions, Pod::Dsr 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, and escapes stuff that runoff 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 DD-MMM-YYYY. 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. release Set the centered footer. By default, this is the version of Perl you run Pod::Dsr under. section Set the section for the `.HEADER LEVEL' command. 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 =========== Invalid link %s (W) The POD source contained a `L<>' sequence that Pod::Dsr was unable to parse. You should never see this error message; it probably indicates a bug in Pod::Dsr. 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::Dsr didn't know about. It was ignored. Unknown escape E<%s> (W) The POD source contained an `E<>' escape that Pod::Dsr 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::Dsr didn't know about. It was ignored. %s: Unknown command paragraph "%s" on line %d. (W) The POD source contained a non-standard command paragraph (something of the form `=command args') that Pod::Dsr 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. The preamble added to each output file is a bit verbose, and should be made to be more flexible (e.g. support optional .LAYOUT commands). Some of the automagic applied to file names assumes Unix directory separators. Pod::Dsr is excessively slow. SEE ALSO ======== `Pod::Parser|Pod::Parser' in this node, perlpod(1), pod2rno(1), runoff(1), type(1), print(1), DSR(1) Please see the file `README.runoff' in the Pod2VMSHlp distribution for more information on RUNOFF and the DSR language. 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 ====== Peter Prymmer pvhp@best.com, based *very* heavily on Pod::Man by Russ Allbery which was in turn based upon the original pod2man by Tom Christiansen and Larry Wall.  File: pm.info, Node: Pod/Find, Next: Pod/GroveBuilder, Prev: Pod/Dsr, Up: Module List find POD documents in directory trees ************************************* NAME ==== Pod::Find - find POD documents in directory trees SYNOPSIS ======== use Pod::Find qw(pod_find simplify_name); my %pods = pod_find({ -verbose => 1, -inc => 1 }); foreach(keys %pods) { print "found library POD `$pods{$_}' in $_\n"; } print "podname=",simplify_name('a/b/c/mymodule.pod'),"\n"; DESCRIPTION =========== *Pod::Find* provides a function *pod_find* that searches for POD documents in a given set of files and directories. It returns a hash with the file names as keys and the POD name as value. The POD name is derived from the file name and its position in the directory tree. E.g. when searching in `$HOME/perl5lib', the file `$HOME/perl5lib/MyModule.pm' would get the POD name *MyModule*, whereas `$HOME/perl5lib/Myclass/Subclass.pm' would be *Myclass::Subclass*. The name information can be used for POD translators. Only text files containing at least one valid POD command are found. A warning is printed if more than one POD file with the same POD name is found, e.g. `CPAN.pm' in different directories. This usually indicates duplicate occurrences of modules in the *@INC* search path. The function *simplify_name* is equivalent to *basename*, but also strips Perl-like extensions (.pm, .pl, .pod) and extensions like `.bat', `.cmd' on Win32 and OS/2, respectively. Note that neither *pod_find* nor *simplify_name* are exported by default so be sure to specify them in the use statement if you need them: use Pod::Find qw(pod_find simplify_name); OPTIONS ======= The first argument for *pod_find* may be a hash reference with options. The rest are either directories that are searched recursively or files. The POD names of files are the plain basenames with any Perl-like extension (.pm, .pl, .pod) stripped. *-verbose* Print progress information while scanning. *-perl* Apply Perl-specific heuristics to find the correct PODs. This includes stripping Perl-like extensions, omitting subdirectories that are numeric but do not match the current Perl interpreter's version id, suppressing `site_perl' as a module hierarchy name etc. *-script* Search for PODs in the current Perl interpreter's installation *scriptdir*. This is taken from the local `Config|Config' in this node module. *-inc* Search for PODs in the current Perl interpreter's *@INC* paths. This automatically considers paths specified in the PERL5LIB environment. AUTHOR ====== Marek Rouchal , heavily borrowing code from Nick Ing-Simmons' PodToHtml. SEE ALSO ======== *Note Pod/Parser: Pod/Parser,, *Note Pod/Checker: Pod/Checker,  File: pm.info, Node: Pod/GroveBuilder, Next: Pod/HTML2Pod, Prev: Pod/Find, Up: Module List SYNOPSIS ======== use Pod::GroveBuilder; $grove = Pod::GroveBuilder->new ($sysid); DESCRIPTION =========== `Pod::GroveBuilder' uses Pod::Parser to create SGML::Grove objects. The resulting SGML::Grove objects can then be used by any module that supports them, including writing SGML/XML output (SGML::Writer), formatting the POD to Ascii or HTML (Quilt), or using SGML::Grove iterators to perform multiple passes over the POD or working with multiple PODs at the same time. `Pod::GroveBuilder->new ($sysid)' creates a grove from a `$sysid', a `$sysid' may be a file name or a FileHandle object. GroveBuilder will build a grove that is hierarchical, for example, `head2' sections will be contained inside of `head1' sections, and `item' paragraphs will be contained within lists, etc. HEAD1 "text" HEAD2 LIST ITEM "text" ITEM "text" HEAD2 "text" See `SGML::Grove' for details on using the grove returned by `Pod::GroveBuilder'. AUTHOR ====== Ken MacLeod, ken@bitsko.slc.ut.us SEE ALSO ======== perl(1), Pod::Parser(3), SGML::Grove(3), SGML::Writer(3), Quilt(3).  File: pm.info, Node: Pod/HTML2Pod, Next: Pod/HTML_Elements, Prev: Pod/GroveBuilder, Up: Module List translate HTML into POD *********************** NAME ==== Pod::HTML2Pod - translate HTML into POD SYNOPSIS ======== # Use the program 'html2pod' that comes in this dist, or: use Pod::HTML2Pod; print Pod::HTML2Pod::convert( 'file' => 'my_stuff.html', # input file 'a_href' => 1, # try converting links ); DESCRIPTION =========== Larry Wall once said (1999-08-27, on the `pod-people' list, I do believe): "The whole point of pod is to get people to document stuff they wouldn't document in any other form." To that end, I wrote this module so that people who are unpracticed with POD but in a hurry to simply document their programs or modules, could write their documentation in simple HTML, and convert that to POD. That's what this module does. Specifically, this module bends over backwards to try to turn even vaguely plausable HTML into POD - and when in doubt, it simply ignores things that it doesn't know about, or can't render. FUNCTIONS ========= This module provides one documented function, which it does not export: Pod::HTML2Pod::convert( ...options... ) This returns a single scalar value containing the converted POD text, with some comments after the end. This function takes options: 'file' => FILENAME, Specifies that the HTML code is to be read from the filename given. 'handle' => *HANDLE, Specifies that the HTML code is to be read from the open filehandle given (e.g., `$fh_obj', `*HANDLE', `*HANDLE{IO}', etc.) If you specify this, but fail to specify an actual handle object, inscrutible errors may result. 'content' => STRING, Specifies that the HTML code is in the string given. (Alternately, pass a reference to the scalar: `'content' => \$stuff'.) 'tree' => OBJ, Specifies that the HTML document is contained in the given HTML::TreeBuilder object (or HTML::Element object, at least). 'a_name' => BOOLEAN, Specifies whether you want to try converting `' elements. By default this is off - i.e., such elements are ignored. 'a_href' => BOOLEAN, Specifies whether you want to try converting `' elements. By default this is off - i.e., such elements are ignored. If on, bear in mind that relative URLs cannot be properly converted to POD - any relative URLs will be complained about in comments after the end of the document. Normal absolute URLs will be treated as best they can be. Note that URLs beginning "pod:..." will be turned into POD links to whatever follows; that is, "pod:Getopt::Std" is turned into `L' 'debug' => INTEGER, Puts Pod::HTML2Pod into verbose debug mode for the duration of processing this this HTML document. INTEGER can be 0 for no debug output, 1 for a moderate amount that will cause the HTML syntax tree to be be dumped at the start of the conversion, and 2 for that plus a dump of the intermediate POD doctree, plus a few more inscrutible diagnostic messages. Looking at the trees dumped might be helpful in making sense of error messages that refer to a particular node in the parse tree. GUIDELINES ========== Don't write crappy HTML and expect this module to understand it. Don't take the output of pod2html and feed it to this, just because you think it'd be neat to try it. You'll just learn really unpleasant things about Pod::Html - and that's fine if that means you'll use it to improve Pod::Html, but it's rather the long way around. However, do use this module to convert simple HTML into POD, bearing in mind these simple truths: POD can't do tables, images, forms, imagemaps, layers, CSS, embedded Java applets or any other kind of object, FONT, or BLINK. So don't try to do any of these things. Use `

' and `

' for headings. If you want to have a block of literal example code, put it in a `
'.

   Keep things simple.

   Remember: Just because it comes out of Pod::HTML2Pod doesn't mean it's
happy normal pod.  You can do lots of things in HTML that will produce POD
that is strange but technically legal (like having huge and complex
content in a `
'/=head1) but that will make perldoc scream bloody
murder about nroff macros stretched past their limit.

   Try to avoid using a WYSIWYG HTML editor, as they often produce scary
source.  Ditto for taking selecting "Save as... HTML" in your word
processor.  You can always try it, but look at the HTML to survey the
damage before you try converting it to POD.

   Always look at the POD that's been output by HTML2Pod - never just
blindly include it.

   Consider starting from this template:

     
     
      Things::Stuff
      
     
     
     
NAME

     
     Things::Stuff -- does some things with stuff
     
     
SYNOPSIS

     
     
       use HTML::Stuff;
       do some more stuff;
       la la la la la;
       oogah;
     

     
     
DESCRIPTION

     
     This module does things with stuff.  It exports these functions:
     
     

     
thingify( ... )
     
This function takes stuff, and returns their value as things.
     
     
destuffulate( ... )
     
This function returns the things, from stuff.
      
It will throw a fatal exception if applied to things.
      
So don't do that.
     
     
enthinction( ... )
     
This is where I run out of ways to make up silly sentences
      involving "thing" and "stuff".  Mostly.
     
     

     
     
Caveats and WYA's

     
     Things to be wary of:
     
     
    
     
  • The things.
     
  • And the stuff
      
    Don't forget about that stuff.  Gotta keep an eye on that.
     

     
     
BUGS

     
     Stuff is hard.
     
     
SEE ALSO

     
     Class::Classless,
     strict,
     Lingua::EN::Numbers::Ordinate,
     perlvar,
     
     
     
     
COPYRIGHT

     
     Copyright 2000, Joey Jo-Jo Jr. Shabadoo.
     
     
     
This library is free software; you can redistribute it and/or modify
     it under the same terms as Perl itself.
     
     
AUTHOR

     Joey Jo-Jo Jr. Shabadoo, jojojo@shabadoo.int
     
     

BUG REPORTS
===========

   If you do find a case where this converter misinterprets what you
consider straightforward HTML (which you should really really have run
thru an HTML syntax checker, by the way!), report it to me as a bug, at
`sburke@cpan.org'.

   Be sure to include the entire document that causes the error - then
specify exactly what you consider the error to be.

BUGS AND CAVEATS
================

   * Doesn't try to turn "smart quotes" characters into simple " and '.
Maybe should?

   * Fails to turn

     foo thing bar baz quux

   into

     foo S quux

   I.e., currently just turns ` ''s into normal spaces.

   * Numeric entities (`E') are used when necessary - but these are
not understood by some older POD converters.

   * No HTML that you provide will turn into `F<...>'

   * Currently maps

     bar

   to

     Xbar

   but is this correct?

SEE ALSO
========

   *Note Perlpod: (perl.info)perlpod,, *Note Pod/Html: Pod/Html,, *Note
HTML/TreeBuilder: HTML/TreeBuilder,

   And HTML Tidy, at `http://www.w3.org/People/Raggett/tidy/'

COPYRIGHT
=========

   Copyright (c) 2000 Sean M. Burke. All rights reserved.

   This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

AUTHOR
======

   Sean M. Burke `sburke@cpan.org'


File: pm.info,  Node: Pod/HTML_Elements,  Next: Pod/Hlp,  Prev: Pod/HTML2Pod,  Up: Module List

Convert POD to tree of LWP's HTML::Element and hence HTML or PostScript
***********************************************************************

NAME
====

   Pod::HTML_Elements - Convert POD to tree of LWP's HTML::Element and
hence HTML or PostScript

SYNOPSIS
========

     use Pod::HTML_Elements;

     my $parser = new Pod::HTML_Elements;
     $parser->parse_from_file($pod,'foo.html');

     my $parser = new Pod::HTML_Elements PostScript => 1;
     $parser->parse_from_file($pod,'foo.ps');

DESCRIPTION
===========

   *Pod::HTML_Elements* is subclass of `*Pod::Parser* in this node'. As
the pod is parsed a tree of **Note HTML/Element: HTML/Element,* objects is
built to represent HTML for the pod.

   At the end of each pod HTML or PostScript representation is written to
the output file.

BUGS
====

   Parameter pass-through to *Note HTML/FormatPS: HTML/FormatPS, needs to
be implemented.

SEE ALSO
========

   *Note Perlpod: (perl.info)perlpod,, *Note Pod/Parser: Pod/Parser,,
*Note HTML/Element: HTML/Element,, *Note HTML/FormatPS: HTML/FormatPS,

AUTHOR
======

   Nick Ing-Simmons