This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Pod/Pdf, Next: Pod/PlainText, Prev: Pod/Parser, Up: Module List A POD to PDF translator *********************** NAME ==== Pdf.pm - A POD to PDF translator SYNOPSIS ======== All systems: pod2pdf([options]) Also from the shell prompt in conjunction with the script "pod2pdf" (see "scripts/pod2pdf"): $ pod2pdf [options] E DESCRIPTION =========== `pod2pdf' translates single POD (Perl Plain Old Documentation) files and translates them to `PDF' (Adobe Portable Document Format) files. Future extensions to this program may permit translation of multiple POD files into a single book. At this stage the emphasis is on simplicity and ease of use. The output `PDF' file takes the name of the input file with the suffix `.pdf'. `PDF Outlines' are created at three levels corresponding to =head1, =head2 and =item. The `outline' headings are reproduced as a `Table of Contents' page. Long =item strings are curtailed to a length which will fit reasonably in the space available on the page. When the `PDF' document is viewed on screen, the `outlines' (sometimes known as Bookmarks) provide links to the appropriate page. When the document is printed the `ToC' provides the same facility. Links of the form `xyz.pm' in this node and links to named destinations are not implemented since it is rarely possible to resolve the link except in the limited instance of links to named destinations in the document itself. Links to URL addresses (including http, ftp and mailto) are active however and call the resident default browser. How that responds to the call will depend to some extent on the type of browser and the environment in which it finds itself. The POD specification `perlpod.pod' allows blocks of text to be enclosed by =begin and =end markers. The block-type my be indicated by a string after =begin (for example `=begin html' would indicate an HTML block) of which *roff, man, latex, tex and html* are recognised entities. Specification `perlpod.pod' goes on to say that *"A formatter that can utilize that format will use the section, otherwise it will be completely ignored."* This seems to defeat the object of the documentation since quite different output might be expected according to which translator was used. It is doubtful if that would necessarily be the author's intention. This translator, `Pdf.pm', in all cases reproduces the section enclosed by a `=begin/=end' pair (or any paragraph following =for which is similarly defined in `perlpod.pod') but in a special color so as to give a visual warning to the reader that special meaning might attach to the block of text. The primary objective is to produce a translation of a POD file of good typographical quality which can be printed on any printer (particularly low-cost non-PostScript ink-jet printers) in any environment. In this connection it must be recognised that some authors use POD mark-up more intelligently and to better effect than others. Not infrequently mistakes in formatting (frequently the absence of a blank line to end a block) result in files which do not translate properly on some or all translators. `PDF' files provide the very useful ability to quickly screen the translation for visual checking before the file is despatched to the printer. OPTIONS ======= In the interests of simplicity and ease of use the number of options has been kept to a minimum. However an option to set paper size remains an unavoidable necessity untill such time as the world can agree on one standard. Only *A4* and *USLetter* are preprogrammed, other custom sizes will require an edit to the `Pdf.pm' code. Options are implemented using Getopt::Long using the syntax `--[key]=' as indicated below. The order in which options are entered is immaterial. *Paper size* The default paper size is A4 (which may be re-editied to a custom size): my $x_size = 595; # default page width (pixels) my $y_size = 842; # default page height (pixels) The option: --paper=usletter sets the North American standard size: my $x_size = 612; # US letter page width (pixels) my $y_size = 792; # US letter page height (pixels) The program will accept any (reasonable) paper size. *Error reporting* Limited error reporting to STDERR may be turned on by setting `$verbose': --verbose=1 # progress reports --verbose=2 # more extensive progress reports about links =item B The input file name may be entered in various ways on most sytems. It may be included as an option, or as a string argument to `pod2pdf', or as an item in `@ARGV' or finally, as a command line entry on systems which support command lines. As an option the syntax is: --podname=filename =item B The output is always "duplex" in the sense that the pages are "handed" with the page number (for example) at the bottom right (on odd pages) and the bottom left (on even pages). However not everyone possesses a duplex printer capable of automatically printing on both sides of the paper, but fortunately most if not all printers are capable of printing all the odd sides in one pass and all the even pages (on the reverse side of the paper) in a second pass, which achieves the same result. Even if that is either not possible or not worth the effort, and the whole document is printed single sided, the handing of the pages is no great drawback. There is really no compelling need for the complication of a switch to select simplex or duplex mode. *Document name* Since the program is restricted to processing single POD files the input file name can be used as the output file name distinguished simply by adding the extension `.pdf' to that name. If a file of that name already exists it will be overwritten without warning. EXAMPLES ======== Example 1 (all platforms) use Pod::Pdf; push @ARGV, qw(--paper usletter --verbose 1); # alternatively "push @ARGV, qw(-paper usletter -verbose 1)" # but NB "push @ARGV, '--verbose 2'" will NOT work push @ARGV, 'podfilename'; pod2pdf(@ARGV); Example 2 (all platforms) use Pod::Pdf; pod2pdf( '--paper=usletter', 'podfilename' ); Example 3 (all platforms) use Pod::Pdf; pod2pdf( '--paper=usletter', '--verbose=2', '--podfile=podfilename' ); Example 4 (MacOS droplet) use Pod::Pdf; unshift @ARGV, '--paper=usletter'; pod2pdf(@ARGV); AUTHOR ====== Alan J. Fry e-mail `mailto:ajf@afco.demon.co.uk' in this node WWW `http:' in this node HISTORY ======= Version 1.0 released 04 April 2000 Version 1.1 released 18 April 2000 This version supports active URI links and features improved formatting. For many helpful suggestions sincere thanks (in alphabetical order) to: Stas Bekman Rob Carraretto M. Christian Hanson Marcus Harnisch Johannes la PoutrŽ Henrik Tougaard Version 1.2 released 26 May 2000 This version has essentially the same functionality as version 1.1 but is reshaped into modular format. In reshaping the module grateful thanks are due to Axel Rose `http:' in this node whose suggestion to place the opening statements of the program into the subroutine `pod2pdf' has been adopted together with his proposals for exporting the function name. This arrangement brings `Pdf.pm' more into line with the structure of other POD translators. His assistance in testing the module on a variety of platforms (MacOS, Linux and Windows) has been invaluable as has his advice on the structure of the interface and many fine details too numerous to mention individually. VERSION ======= v1.2 Friday, 26 May 2000 COPYRIGHT ========= © Alan J. Fry April 2000 This program is distributed under the terms of the Artistic Licence  File: pm.info, Node: Pod/PlainText, Next: Pod/Plainer, Prev: Pod/Pdf, Up: Module List Convert POD data to formatted ASCII text **************************************** NAME ==== Pod::PlainText - Convert POD data to formatted ASCII text SYNOPSIS ======== use Pod::PlainText; my $parser = Pod::PlainText->new (sentence => 0, width => 78); # Read POD from STDIN and write to STDOUT. $parser->parse_from_filehandle; # Read POD from file.pod and write to file.txt. $parser->parse_from_file ('file.pod', 'file.txt'); DESCRIPTION =========== Pod::PlainText is a module that can convert documentation in the POD format (the preferred language for documenting Perl) into formatted ASCII. It uses no special formatting controls or codes whatsoever, and its output is therefore suitable for nearly any device. As a derived class from Pod::Parser, Pod::PlainText supports the same methods and interfaces. See *Note Pod/Parser: Pod/Parser, for all the details; briefly, one creates a new parser with `Pod::PlainText->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. The currently recognized options are: alt If set to a true value, selects an alternate output format that, among other things, uses a different heading style and marks =item entries with a colon in the left margin. Defaults to false. indent The number of spaces to indent regular text, and the default indentation for =over blocks. Defaults to 4. loose If set to a true value, a blank line is printed after a =head1 heading. If set to false (the default), no blank line is printed after =head1, although one is still printed after =head2. This is the default because it's the expected formatting for manual pages; if you're formatting arbitrary text documents, setting this to true may result in more pleasing output. sentence If set to a true value, Pod::PlainText will assume that each sentence ends in two spaces, and will try to preserve that spacing. If set to false, all consecutive whitespace in non-verbatim paragraphs is compressed into a single space. Defaults to true. width The column at which to wrap text on the right-hand side. Defaults to 76. 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 =========== Bizarre space in item (W) Something has gone wrong in internal =item processing. This message indicates a bug in Pod::PlainText; you should never see it. Can't open %s for reading: %s (F) Pod::PlainText was invoked via the compatibility mode pod2text() interface and the input file it was given could not be opened. Unknown escape: %s (W) The POD source contained an `E<>' escape that Pod::PlainText didn't know about. Unknown sequence: %s (W) The POD source contained a non-standard internal sequence (something of the form `X<>') that Pod::PlainText didn't know about. Unmatched =back (W) Pod::PlainText encountered a =back command that didn't correspond to an =over command. RESTRICTIONS ============ Embedded Ctrl-As (octal 001) in the input will be mapped to spaces on output, due to an internal implementation detail. NOTES ===== This is a replacement for an earlier Pod::Text module written by Tom Christiansen. It has a revamped interface, since it now uses Pod::Parser, but an interface roughly compatible with the old Pod::Text::pod2text() function is still available. Please change to the new calling convention, though. The original Pod::Text contained code to do formatting via termcap sequences, although it wasn't turned on by default and it was problematic to get it to work at all. This rewrite doesn't even try to do that, but a subclass of it does. Look for `Pod::Text::Termcap|Pod::Text::Termcap' in this node. SEE ALSO ======== `Pod::Parser|Pod::Parser' in this node, `Pod::Text::Termcap|Pod::Text::Termcap' in this node, pod2text(1) AUTHOR ====== Russ Allbery , based *very* heavily on the original Pod::Text by Tom Christiansen and its conversion to Pod::Parser by Brad Appleton .  File: pm.info, Node: Pod/Plainer, Next: Pod/Rtf, Prev: Pod/PlainText, Up: Module List Perl extension for converting Pod to old style Pod. *************************************************** NAME ==== Pod::Plainer - Perl extension for converting Pod to old style Pod. SYNOPSIS ======== use Pod::Plainer; my $parser = Pod::Plainer -> new (); $parser -> parse_from_filehandle(\*STDIN); DESCRIPTION =========== Pod::Plainer uses Pod::Parser which takes Pod with the (new) 'C<< .. >>' constructs and returns the old(er) style with just 'C<>'; '<' and '>' are replaced by 'E' and 'E'. This can be used to pre-process Pod before using tools which do not recognise the new style Pods. EXPORT ------ None by default. AUTHOR ====== Robin Barker, rmb1@cise.npl.co.uk SEE ALSO ======== See *Note Pod/Parser: Pod/Parser,.  File: pm.info, Node: Pod/Rtf, Next: Pod/Select, Prev: Pod/Plainer, Up: Module List Pod::Rtf ******** NAME ==== Pod::Rtf SYNOPSIS ======== $parser = new Pod::Rtf(); $parser->parse_from_filehandle(\*STDIN) if (@ARGV == 0); for (@ARGV) { my $file = $_; $file =~ s/\..*$//; $Pod::Rtf::pound_note = $_; $Pod::Rtf::dollar_note = $file; $Pod::Rtf::K_note = $file; $parser->parse_from_file($_); } DESCRIPTION =========== Uses Pod::Parser to convert pod documentation to Rich Text Format (rtf) suitable for compilation by a Windows Help compiler. SEE ALSO ======== *Note Perl: (perl.info)perl,. *Note Pod/Rtf: Pod/Rtf,, *Note Pod/Parser: Pod/Parser,. AUTHOR ====== Peter Prymmer.  File: pm.info, Node: Pod/Select, Next: Pod/Tests, Prev: Pod/Rtf, Up: Module List extract selected sections of POD from input ******************************************* NAME ==== Pod::Select, podselect() - extract selected sections of POD from input SYNOPSIS ======== use Pod::Select; ## Select all the POD sections for each file in @filelist ## and print the result on standard output. podselect(@filelist); ## Same as above, but write to tmp.out podselect({-output => "tmp.out"}, @filelist): ## Select from the given filelist, only those POD sections that are ## within a 1st level section named any of: NAME, SYNOPSIS, OPTIONS. podselect({-sections => ["NAME|SYNOPSIS", "OPTIONS"]}, @filelist): ## Select the "DESCRIPTION" section of the PODs from STDIN and write ## the result to STDERR. podselect({-output => ">&STDERR", -sections => ["DESCRIPTION"]}, \*STDIN); or use Pod::Select; ## Create a parser object for selecting POD sections from the input $parser = new Pod::Select(); ## Select all the POD sections for each file in @filelist ## and print the result to tmp.out. $parser->parse_from_file("<&STDIN", "tmp.out"); ## Select from the given filelist, only those POD sections that are ## within a 1st level section named any of: NAME, SYNOPSIS, OPTIONS. $parser->select("NAME|SYNOPSIS", "OPTIONS"); for (@filelist) { $parser->parse_from_file($_); } ## Select the "DESCRIPTION" and "SEE ALSO" sections of the PODs from ## STDIN and write the result to STDERR. $parser->select("DESCRIPTION"); $parser->add_selection("SEE ALSO"); $parser->parse_from_filehandle(\*STDIN, \*STDERR); REQUIRES ======== perl5.005, Pod::Parser, Exporter, Carp EXPORTS ======= podselect() DESCRIPTION =========== podselect() is a function which will extract specified sections of pod documentation from an input stream. This ability is provided by the Pod::Select module which is a subclass of Pod::Parser. Pod::Select provides a method named select() to specify the set of POD sections to select for processing/printing. podselect() merely creates a Pod::Select object and then invokes the podselect() followed by parse_from_file(). SECTION SPECIFICATIONS ====================== podselect() and *Pod::Select::select()* may be given one or more "section specifications" to restrict the text processed to only the desired set of sections and their corresponding subsections. A section specification is a string containing one or more Perl-style regular expressions separated by forward slashes ("/"). If you need to use a forward slash literally within a section title you can escape it with a backslash ("\/"). The formal syntax of a section specification is: *head1-title-regex*/*head2-title-regex*/... Any omitted or empty regular expressions will default to ".*". Please note that each regular expression given is implicitly anchored by adding "^" and "$" to the beginning and end. Also, if a given regular expression starts with a "!" character, then the expression is *negated* (so `!foo' would match anything except foo). Some example section specifications follow. Match the NAME and SYNOPSIS sections and all of their subsections: `NAME|SYNOPSIS' Match only the `Question' and `Answer' subsections of the DESCRIPTION section: `DESCRIPTION/Question|Answer' Match the Comments subsection of all sections: `/Comments' Match all subsections of DESCRIPTION except for Comments: `DESCRIPTION/!Comments' Match the DESCRIPTION section but do not match any of its subsections: `DESCRIPTION/!.+' Match all top level sections but none of their subsections: `/!.+' RANGE SPECIFICATIONS ==================== podselect() and *Pod::Select::select()* may be given one or more "range specifications" to restrict the text processed to only the desired ranges of paragraphs in the desired set of sections. A range specification is a string containing a single Perl-style regular expression (a regex), or else two Perl-style regular expressions (regexs) separated by a ".." (Perl's "range" operator is ".."). The regexs in a range specification are delimited by forward slashes ("/"). If you need to use a forward slash literally within a regex you can escape it with a backslash ("\/"). The formal syntax of a range specification is: /*start-range-regex*/[../*end-range-regex*/] Where each the item inside square brackets (the ".." followed by the end-range-regex) is optional. Each "range-regex" is of the form: =cmd-expr text-expr Where *cmd-expr* is intended to match the name of one or more POD commands, and *text-expr* is intended to match the paragraph text for the command. If a range-regex is supposed to match a POD command, then the first character of the regex (the one after the initial '/') absolutely must be an single '=' character; it may not be anything else (not even a regex meta-character) if it is supposed to match against the name of a POD command. If no *=cmd-expr* is given then the text-expr will be matched against plain textblocks unless it is preceded by a space, in which case it is matched against verbatim text-blocks. If no *text-expr* is given then only the command-portion of the paragraph is matched against. Note that these two expressions are each implicitly anchored. This means that when matching against the command-name, there will be an implicit '^' and '$' around the given *=cmd-expr*; and when matching against the paragraph text there will be an implicit '\A' and '\Z' around the given *text-expr*. Unlike with section-specs, the '!' character does not have any special meaning (negation or otherwise) at the beginning of a range-spec! Some example range specifications follow. Match all `=for html' paragraphs: `/=for html/' Match all paragraphs between `=begin html' and `=end html' (note that this will not work correctly if such sections are nested): `/=begin html/../=end html/' Match all paragraphs between the given =item name until the end of the current section: `/=item mine/../=head\d/' Match all paragraphs between the given =item until the next item, or until the end of the itemized list (note that this will not work as desired if the item contains an itemized list nested within it): `/=item mine/../=(item|back)/' OBJECT METHODS ============== The following methods are provided in this module. Each one takes a reference to the object itself as an implicit first parameter. curr_headings() =============== ($head1, $head2, $head3, ...) = $parser->curr_headings(); $head1 = $parser->curr_headings(1); This method returns a list of the currently active section headings and subheadings in the document being parsed. The list of headings returned corresponds to the most recently parsed paragraph of the input. If an argument is given, it must correspond to the desired section heading number, in which case only the specified section heading is returned. If there is no current section heading at the specified level, then undef is returned. select() ======== $parser->select($section_spec1,$section_spec2,...); This method is used to select the particular sections and subsections of POD documentation that are to be printed and/or processed. The existing set of selected sections is *replaced* with the given set of sections. See add_selection() for adding to the current set of selected sections. Each of the `$section_spec' arguments should be a section specification as described in `"SECTION SPECIFICATIONS"' in this node. The section specifications are parsed by this method and the resulting regular expressions are stored in the invoking object. If no `$section_spec' arguments are given, then the existing set of selected sections is cleared out (which means all sections will be processed). This method should not normally be overridden by subclasses. add_selection() =============== $parser->add_selection($section_spec1,$section_spec2,...); This method is used to add to the currently selected sections and subsections of POD documentation that are to be printed and/or processed. See for replacing the currently selected sections. Each of the `$section_spec' arguments should be a section specification as described in `"SECTION SPECIFICATIONS"' in this node. The section specifications are parsed by this method and the resulting regular expressions are stored in the invoking object. This method should not normally be overridden by subclasses. clear_selections() ================== $parser->clear_selections(); This method takes no arguments, it has the exact same effect as invoking with no arguments. match_section() =============== $boolean = $parser->match_section($heading1,$heading2,...); Returns a value of true if the given section and subsection heading titles match any of the currently selected section specifications in effect from prior calls to select() and add_selection() (or if there are no explictly selected/deselected sections). The arguments `$heading1', `$heading2', etc. are the heading titles of the corresponding sections, subsections, etc. to try and match. If `$headingN' is omitted then it defaults to the current corresponding section heading title in the input. This method should not normally be overridden by subclasses. is_selected() ============= $boolean = $parser->is_selected($paragraph); This method is used to determine if the block of text given in `$paragraph' falls within the currently selected set of POD sections and subsections to be printed or processed. This method is also responsible for keeping track of the current input section and subsections. It is assumed that `$paragraph' is the most recently read (but not yet processed) input paragraph. The value returned will be true if the `$paragraph' and the rest of the text in the same section as `$paragraph' should be selected (included) for processing; otherwise a false value is returned. EXPORTED FUNCTIONS ================== The following functions are exported by this module. Please note that these are functions (not methods) and therefore `do not' take an implicit first argument. podselect() =========== podselect(\%options,@filelist); *podselect* will print the raw (untranslated) POD paragraphs of all POD sections in the given input files specified by `@filelist' according to the given options. If any argument to *podselect* is a reference to a hash (associative array) then the values with the following keys are processed as follows: *-output* A string corresponding to the desired output file (or ">&STDOUT" or ">&STDERR"). The default is to use standard output. *-sections* A reference to an array of sections specifications (as described in `"SECTION SPECIFICATIONS"' in this node) which indicate the desired set of POD sections and subsections to be selected from input. If no section specifications are given, then all sections of the PODs are used. *-ranges* A reference to an array of range specifications (as described in `"RANGE SPECIFICATIONS"' in this node) which indicate the desired range of POD paragraphs to be selected from the desired input sections. If no range specifications are given, then all paragraphs of the desired sections are used. All other arguments should correspond to the names of input files containing POD sections. A file name of "-" or "<&STDIN" will be interpeted to mean standard input (which is the default if no filenames are given). PRIVATE METHODS AND DATA ======================== Pod::Select makes uses a number of internal methods and data fields which clients should not need to see or use. For the sake of avoiding name collisions with client data and methods, these methods and fields are briefly discussed here. Determined hackers may obtain further information about them by reading the Pod::Select source code. Private data fields are stored in the hash-object whose reference is returned by the new() constructor for this class. The names of all private methods and data-fields used by Pod::Select begin with a prefix of "_" and match the regular expression `/^_\w+$/'. _compile_section_spec() ======================= $listref = $parser->_compile_section_spec($section_spec); This function (note it is a function and not a method) takes a section specification (as described in `"SECTION SPECIFICATIONS"' in this node) given in `$section_sepc', and compiles it into a list of regular expressions. If `$section_spec' has no syntax errors, then a reference to the list (array) of corresponding regular expressions is returned; otherwise undef is returned and an error message is printed (using carp) for each invalid regex. $self->{_SECTION_HEADINGS} -------------------------- A reference to an array of the current section heading titles for each heading level (note that the first heading level title is at index 0). $self->{_SELECTED_SECTIONS} --------------------------- A reference to an array of references to arrays. Each subarray is a list of anchored regular expressions (preceded by a "!" if the expression is to be negated). The index of the expression in the subarray should correspond to the index of the heading title in `$self->{_SECTION_HEADINGS}' that it is to be matched against. SEE ALSO ======== *Note Pod/Parser: Pod/Parser, AUTHOR ====== Brad Appleton Based on code for *pod2text* written by Tom Christiansen  File: pm.info, Node: Pod/Tests, Next: Pod/Text, Prev: Pod/Select, Up: Module List Extracts embedded tests and code examples from POD ************************************************** NAME ==== Pod::Tests - Extracts embedded tests and code examples from POD SYNOPSIS ======== *LOOK AT pod2test FIRST!* use Pod::Tests; $p = Pod::Tests->new; $p->parse_file($file); $p->parse_fh($fh); $p->parse(@code); my @examples = $p->examples; my @tests = $p->tests; foreach my $example (@examples) { print "The example: '$example->{code}' was on line ". "$example->{line}\n"; } my @test_code = $p->build_tests(@tests); my @example_test_code = $p->build_examples(@examples); DESCRIPTION =========== *LOOK AT pod2test FIRST! THIS IS ALPHA CODE!* This is a specialized POD viewer to extract embedded tests and code examples from POD. It doesn't do much more than that. pod2test does the useful work. Embedded Tests -------------- Embedding tests allows tests to be placed near the code its testing. This is a nice supplement to the traditional .t files. A test is denoted using either "=for testing" or a "=begin/end testing" block. =item B @pirates = is_pirate(@arrrgs); Go through @arrrgs and return a list of pirates. =begin testing my @p = is_pirate('Blargbeard', 'Alfonse', 'Capt. Hampton', 'Wesley'); ok(@p == 2); =end testing =cut sub is_pirate { .... } Code Examples *EXPERIMENTAL* ---------------------------- *BIG FAT WARNING* perldoc and the various pod2* reformatters are inconsistant in how they deal with =also. Some warn, some display it, some choke. So consider this to be a *Highly Experimental Feature*. Code examples in documentation are rarely tested. Pod::Tests provides a way to do some minimalist testing of your examples. A code example is denoted using either "=also for example" or an "=also begin/end example" block. The `=also' tag provides that examples will both be extracted and displayed as documentation. =also for example print "Here is a fine example of something or other."; =also begin example use LWP::Simple; getprint "http://www.goats.com"; =also end example Formatting ---------- The code examples and embedded tests are not translated from POD, thus all the C<> and B<> style escapes are not valid. Its literal Perl code. Parsing ------- After creating a Pod::Tests object, you parse the POD by calling one of the available parsing methods documented below. You can call parse as many times as you'd like, all examples and tests found will stack up inside the object. Testing ------- Once extracted, the tests can be built into stand-alone testing code using the build_tests() and build_examples() methods. However, it is recommended that you first look at the pod2test program before embarking on this. Methods ------- new $parser = Pod::Tests->new; Returns a new Pod::Tests object which lets you read tests and examples out of a POD document. parse $parser->parse(@code); Finds the examples and tests in a bunch of lines of Perl @code. Once run they're available via examples() and testing(). _init $parser->_init; Initializes the state of the parser, but not the rest of the object. Should be called before each parse of new POD. _beginfor $parser->_beginfor($format, $pod); Indicates that a =for tag has been seen. $format (what immediately follows '=for'), and $pod is the rest of the POD on that line. _endfor $parser->endfor; Indicates that the current =for block has ended. _beginblock $parser->_beginblock($format); Indicates that the parser saw a =begin tag. $format is the word immediately following =begin. _endblock $parser->_endblock Indicates that the parser saw an =end tag for the current block. parse_fh parse_file $parser->parse_file($filename); $parser->parse_fh($fh); Just like parse() except it works on a file or a filehandle, respectively. examples testing @examples = $parser->examples; @testing = $parser->tests; Returns the examples and tests found in the parsed POD documents. Each element of @examples and @testing is a hash representing an individual testing block and contains information about that block. $test->{code} actual testing code $test->{line} line from where the test was taken NOTE In the future, these will become full-blown objects. build_tests my @code = $p->build_tests(@tests); Returns a code fragment based on the given embedded @tests. This fragment is expected to print the usual "ok/not ok" (or something Test::Harness can read) or nothing at all. Typical usage might be: my @code = $p->build_tests($p->tests); This fragment is suitable for placing into a larger test script. NOTE Look at pod2test before embarking on your own test building. build_examples my @code = $p->build_examples(@examples); Similar to build_tests(), it creates a code fragment which tests the basic validity of your example code. Essentially, it just makes sure it compiles. This is currently very primitive. EXAMPLES ======== Here's the simplest example, just finding the tests and examples in a single module. my $p = Pod::Tests->new; $p->parse_file("path/to/Some.pm"); And one to find all the tests and examples in a directory of files. This illustrates building a set of examples and tests through multiple calls to parse_file(). my $p = Pod::Tests->new; opendir(PODS, "path/to/some/lib/") || die $!; while( my $file = readdir PODS ) { $p->parse_file($file); } printf "Found %d examples and %d tests in path/to/some/lib\n", scalar $p->examples, scalar $p->tests; Finally, an example of parsing your own POD using the DATA filehandle. use Fcntl qw(:seek); my $p = Pod::Tests->new; # Seek to the beginning of the current code. seek(DATA, 0, SEEK_SET) || die $!; $p->parse_fh(\*DATA); AUTHOR ====== Michael G Schwern NOTES and CAVEATS ================= This module is currently EXPERIMENTAL and only for use by pod2test. If you use it, the interface *will* change from out from under you. It currently does not use Pod::Parser. I couldn't figure out how to use it. Instead, I use a simple, home-rolled parser. This will eventually be split out as Pod::Parser::Simple. SEE ALSO ======== `pod2test' in this node, Perl 6 RFC 183 http://dev.perl.org/rfc183.pod Similar schemes can be found in `SelfTest' in this node and *Note Test/Unit: Test/Unit,.  File: pm.info, Node: Pod/Text, Next: Pod/Text/Color, Prev: Pod/Tests, Up: Module List Convert POD data to formatted ASCII text **************************************** NAME ==== Pod::Text - Convert POD data to formatted ASCII text SYNOPSIS ======== use Pod::Text; my $parser = Pod::Text->new (sentence => 0, width => 78); # Read POD from STDIN and write to STDOUT. $parser->parse_from_filehandle; # Read POD from file.pod and write to file.txt. $parser->parse_from_file ('file.pod', 'file.txt'); DESCRIPTION =========== Pod::Text is a module that can convert documentation in the POD format (the preferred language for documenting Perl) into formatted ASCII. It uses no special formatting controls or codes whatsoever, and its output is therefore suitable for nearly any device. As a derived class from Pod::Parser, Pod::Text supports the same methods and interfaces. See *Note Pod/Parser: Pod/Parser, for all the details; briefly, one creates a new parser with `Pod::Text->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. The currently recognized options are: alt If set to a true value, selects an alternate output format that, among other things, uses a different heading style and marks =item entries with a colon in the left margin. Defaults to false. indent The number of spaces to indent regular text, and the default indentation for =over blocks. Defaults to 4. loose If set to a true value, a blank line is printed after a =head1 heading. If set to false (the default), no blank line is printed after =head1, although one is still printed after =head2. This is the default because it's the expected formatting for manual pages; if you're formatting arbitrary text documents, setting this to true may result in more pleasing 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. sentence If set to a true value, Pod::Text will assume that each sentence ends in two spaces, and will try to preserve that spacing. If set to false, all consecutive whitespace in non-verbatim paragraphs is compressed into a single space. Defaults to true. width The column at which to wrap text on the right-hand side. Defaults to 76. 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 =========== Bizarre space in item (W) Something has gone wrong in internal =item processing. This message indicates a bug in Pod::Text; you should never see it. Can't open %s for reading: %s (F) Pod::Text was invoked via the compatibility mode pod2text() interface and the input file it was given could not be opened. 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: %s (W) The POD source contained an `E<>' escape that Pod::Text didn't know about. Unknown sequence: %s (W) The POD source contained a non-standard internal sequence (something of the form `X<>') that Pod::Text didn't know about. Unmatched =back (W) Pod::Text encountered a =back command that didn't correspond to an =over command. RESTRICTIONS ============ Embedded Ctrl-As (octal 001) in the input will be mapped to spaces on output, due to an internal implementation detail. NOTES ===== This is a replacement for an earlier Pod::Text module written by Tom Christiansen. It has a revamped interface, since it now uses Pod::Parser, but an interface roughly compatible with the old Pod::Text::pod2text() function is still available. Please change to the new calling convention, though. The original Pod::Text contained code to do formatting via termcap sequences, although it wasn't turned on by default and it was problematic to get it to work at all. This rewrite doesn't even try to do that, but a subclass of it does. Look for `Pod::Text::Termcap|Pod::Text::Termcap' in this node. SEE ALSO ======== `Pod::Parser|Pod::Parser' in this node, `Pod::Text::Termcap|Pod::Text::Termcap' in this node, pod2text(1) AUTHOR ====== Russ Allbery , based *very* heavily on the original Pod::Text by Tom Christiansen and its conversion to Pod::Parser by Brad Appleton .  File: pm.info, Node: Pod/Text/Color, Next: Pod/Text/Overstrike, Prev: Pod/Text, Up: Module List Convert POD data to formatted color ASCII text ********************************************** NAME ==== Pod::Text::Color - Convert POD data to formatted color ASCII text SYNOPSIS ======== use Pod::Text::Color; my $parser = Pod::Text::Color->new (sentence => 0, width => 78); # Read POD from STDIN and write to STDOUT. $parser->parse_from_filehandle; # Read POD from file.pod and write to file.txt. $parser->parse_from_file ('file.pod', 'file.txt'); DESCRIPTION =========== Pod::Text::Color is a simple subclass of Pod::Text that highlights output text using ANSI color escape sequences. Apart from the color, it in all ways functions like Pod::Text. See *Note Pod/Text: Pod/Text, for details and available options. Term::ANSIColor is used to get colors and therefore must be installed to use this module. BUGS ==== This is just a basic proof of concept. It should be seriously expanded to support configurable coloration via options passed to the constructor, and *pod2text* should be taught about those. SEE ALSO ======== `Pod::Text|Pod::Text' in this node, `Pod::Parser|Pod::Parser' in this node AUTHOR ====== Russ Allbery .  File: pm.info, Node: Pod/Text/Overstrike, Next: Pod/Text/Termcap, Prev: Pod/Text/Color, Up: Module List Convert POD data to formatted overstrike text ********************************************* NAME ==== Pod::Text::Overstrike - Convert POD data to formatted overstrike text SYNOPSIS ======== use Pod::Text::Overstrike; my $parser = Pod::Text::Overstrike->new (sentence => 0, width => 78); # Read POD from STDIN and write to STDOUT. $parser->parse_from_filehandle; # Read POD from file.pod and write to file.txt. $parser->parse_from_file ('file.pod', 'file.txt'); DESCRIPTION =========== Pod::Text::Overstrike is a simple subclass of Pod::Text that highlights output text using overstrike sequences, in a manner similar to nroff. Characters in bold text are overstruck (character, backspace, character) and characters in underlined text are converted to overstruck underscores (underscore, backspace, character). This format was originally designed for hardcopy terminals and/or lineprinters, yet is readable on softcopy (CRT) terminals. Overstruck text is best viewed by page-at-a-time programs that take advantage of the terminal's *stand-out* and underline capabilities, such as the less program on Unix. Apart from the overstrike, it in all ways functions like Pod::Text. See *Note Pod/Text: Pod/Text, for details and available options. BUGS ==== Currently, the outermost formatting instruction wins, so for example underlined text inside a region of bold text is displayed as simply bold. There may be some better approach possible. SEE ALSO ======== `Pod::Text|Pod::Text' in this node, `Pod::Parser|Pod::Parser' in this node AUTHOR ====== Joe Smith , using the framework created by Russ Allbery .  File: pm.info, Node: Pod/Text/Termcap, Next: Pod/Tree, Prev: Pod/Text/Overstrike, Up: Module List Convert POD data to ASCII text with format escapes ************************************************** NAME ==== Pod::Text::Color - Convert POD data to ASCII text with format escapes SYNOPSIS ======== use Pod::Text::Termcap; my $parser = Pod::Text::Termcap->new (sentence => 0, width => 78); # Read POD from STDIN and write to STDOUT. $parser->parse_from_filehandle; # Read POD from file.pod and write to file.txt. $parser->parse_from_file ('file.pod', 'file.txt'); DESCRIPTION =========== Pod::Text::Termcap is a simple subclass of Pod::Text that highlights output text using the correct termcap escape sequences for the current terminal. Apart from the format codes, it in all ways functions like Pod::Text. See *Note Pod/Text: Pod/Text, for details and available options. SEE ALSO ======== `Pod::Text|Pod::Text' in this node, `Pod::Parser|Pod::Parser' in this node AUTHOR ====== Russ Allbery .  File: pm.info, Node: Pod/Tree, Next: Pod/Tree/HTML, Prev: Pod/Text/Termcap, Up: Module List Create a static syntax tree for a POD ************************************* NAME ==== Pod::Tree - Create a static syntax tree for a POD SYNOPSIS ======== use Pod::Tree; $tree = new Pod::Tree; $tree->load_file ( $file, %options) $tree->load_fh ( $fh , %options); $tree->load_string ( $pod , %options); $tree->load_paragraphs(\@pod , %options); $loaded = $tree->loaded; $node = $tree->get_root; $tree->set_root ($node); $node = $tree->pop; $tree->push(@nodes); $tree->walk(\&sub); print $tree->dump; REQUIRES ======== Perl 5.004, Exporter, IO::File, Pod::Tree::Node EXPORTS ======= Nothing DESCRIPTION =========== `Pod::Tree' parses a POD into a static syntax tree. Applications walk the tree to recover the structure and content of the POD. See ``Pod::Tree::Node' in this node' for a description of the tree. METHODS ======= $tree = new `Pod::Tree' Creates a new `Pod::Tree' object. The syntax tree is initially empty. $ok = $tree->`load_file'($file, %options) Parses a POD and creates a syntax tree for it. $file is the name of a file containing the POD. Returns null iff it can't open $file. See `' in this node for a description of %options $tree->`load_fh'($fh, %options) Parses a POD and creates a syntax tree for it. $fh is an IO::File object that is open on a file containing the POD. See `' in this node for a description of %options $tree->`load_string'($pod, %options) Parses a POD and creates a syntax tree for it. $pod is a single string containing the POD. See `' in this node for a description of %options $tree->`load_paragraphs'(\*@pod*, %options) Parses a POD and creates a syntax tree for it. *\@pod* is a reference to an array of strings. Each string is one paragraph of the POD. See `' in this node for a description of %options $loaded = $tree->`loaded' Returns true iff one of the `load_'* methods has been called on $tree. $node = $tree->`get_root' Returns the root node of the syntax tree. See *Note Pod/Tree/Node: Pod/Tree/Node, for a description of the syntax tree. $tree->`set_root'($node) Sets to the root of the syntax tree to $node. $tree->push(*@nodes*) Pushes *@nodes* onto the end of the top-level list of nodes in $tree. $node = $tree->pop Pops $node off of the end of the top-level list of nodes in $tree. $tree->walk(*\&sub*) Walks the syntax tree, depth first. Calls sub once for each node in the tree. The current node is passed as the first argument to sub. walk descends to the children and siblings of $node iff *sub()* returns true. $tree->dump Pretty prints the syntax tree. This will show you how `Pod::Tree' interpreted your POD. OPTIONS ======= These options may be passed in the %options hash to the `load_'* methods. `in_pod => 0' `in_pod => 1' Sets the initial value of `in_pod'. When `in_pod' is false, the parser ignores all text until the next =command paragraph. The initial value of `in_pod' defaults to false for `load_file()' and `load_fh()' calls and true for `load_string()' and `load_paragraphs()' calls. This is usually what you want, unless you want consistency. If this isn't what you want, pass different initial values in the %options hash. limit => n Only parse the first n paragraphs in the POD. DIAGNOSTICS =========== `load_file'($file) Returns null iff it can't open $file. NOTES ===== Blank lines ----------- PODs are defined in terms of paragraphs, and paragraphs are defined as text delimited by two or more consecutive newlines. `load_file()' and `load_fh()' parse paragraphs by setting $/ to " and calling `getline()'. This reads paragraphs as desired; however, the strings returned by `getline()' always have two newlines at the end, no matter now many actually appear in the input. I reported this as a bug against Perl, but was told that it is a feature. To fix this, I would have to abandon $/ and count newlines in `Pod::Tree'. From a coding standpoint, this isn't difficult, but I hate to do it: $/ ought to be good for *something*. Instead, `load_file()' and `load_fh()' go ahead and chomp the line endings. `pod2'* translators can add back `"\n\n"' if they like, but there is no way to recover the actual number of newlines in the input. For consistency, `load_string()' splits on `m(\n{2,})' and discards the delimiters. In contrast, `load_paragraphs()' doesn't mung newlines. By definition, text passed to `load_paragraphs()' has already been divided into paragraphs, so any trailing newlines are taken to be part of the paragraph in which they appear. None of this should be an issue for ordinary POD paragraphs. However, it could be a problem for =begin/=end blocks, if they pass text to a formatter for which blank lines are significant. `' in this node markups ----------------------- In the documentation of the L<"sec"> section in this manual page markup, ``perlpod' in this node' has always claimed (the quotes are optional) However, there is no way to decide from the syntax alone whether L is a link to the foo man page or a link to the foo section of this man page. `Pod::Tree' parses `< LZ<' >> as a link to a section if foo looks like a section name (e.g. contains whitespace), and as a link to a man page otherswise. In practice, this tends to break links to sections. If you want your section links to work reliably, write them as `< LZ<'<"foo"> >> or `< LZ<' >>. SEE ALSO ======== perl(1), ``Pod::Tree::Node' in this node', ``Pod::Tree::HTML' 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.