NAME

Pod::Wrap - Wrap pod paragraphs, leaving verbatim text and code alone.

SYNOPSIS

    #!/usr/bin/perl

    use strict;
    use warnings;

    use Pod::Wrap;

    my $w = new Pod::Wrap;

    unless (@ARGV) {
        $w->parse_from_filehandle() # STDIN
    } else {
        $w->parse_from_file($_) for @ARGV;
    }

DESCRIPTION

This is a Pod::Parser subclass, based on Pod::Stripper. It parses perl files, wrapping pod text, and leaving everything else intact. It prints it's output to wherever you point it to (like you do with Pod::Parser (and Pod::Stripper)).

METHODS

new

This is actually "new" in Pod::Parser.

All arguments to it are meaningless, as they are in Pod::Parser.

parse_from_filehandle
parse_from_file

These are actually "parse_from_filehandle" in Pod::Parser and "parse_from_file" in Pod::Parser.

They will receive input and output as described therein.

They will invoke this parser class, which will filter the pod text, wrapping the appropriate sections using Text::Wrap.

MOTIVATION

I prefer editing with tabs and soft wrapping.

Most people like getting documentation hard wrapped and with tabs expanded.

The tabs are easy (Text::Tabs), but wrapping only the correct parts of the pod is a little tricker. This module attempts to do this correctly, by wrapping only what isn't a command, a verbatim example (indented text), or actual Perl code.

PodMaster noted that I should see what perltidy has to offer. Turns out that

    What perltidy does not parse and format
    ...
    And, of course, it does not modify pod documents.

This drove me to release this tiny module.

BEHAVIOR MODIFICATION

The wrapping behavior is defined entirely by Text::Wrap.

No re-exporting is made, in order to minimize bugs. If you want to import the variables Text::Wrap uses, do something like this:

    use Pod::Wrap;
    use Text::Wrap qw/$columns $huge/;

BUGS

Welcome.

TODO

You can ask me.

CREDITS

Podmaster wrote Pod::Stripper. Even though the functionality of this module is very limited, and is not really derived from Pod::Stripper, I would have been too lazy to read Pod::Parser's docs without seeing Pod::Stripper's code as an example first.

Bottom line, most of the work (the research) that was actually done is not mine. Implementation wouldn't have happened if I hadn't known for sure it's possible to get perl code, verbatim, out of a pod parser. And I wouldn't have if I hadn't seen a working example.

COPYRIGHT & LICENSE

You may not wrap pod files in any way without my explicit permission, in writing.

Just kidding.

    Copyright 2004 Yuval Kogman. All rights reserved.
    This program is free software; you can redistribute it
    and/or modify it under the same terms as Perl itself.

AUTHOR

Yuval Kogman <nothingmuch@woobling.org>

SEE ALSO

Text::Wrap, Pod::Parser, Pod::Stripper, Perl::Tidy