Take me over?
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>