/ 
Pod-Compiler-0.20
River stage zero No dependents
/ podlint

NAME

podlint - beautify the POD within a file

SYNOPSIS

podlint -help | -man

or

podlint [ -warnings | -nowarnings ] [ -errors | -noerrors ] [ -perlcode | -noperlcode ] [ -linelength num ] [ -unwrap string ] [ -unnest string ] [ inputfile ] [ outputfile ]

or

podlint -i string [ -warnings | -nowarnings ] [ -errors | -noerrors ] [ -perlcode | -noperlcode ] [ -linelength num ] [ -unwrap string ] [ -unnest string ] inputfile1 [ inputfile2 ... ]

DESCRIPTION

podlint uses Pod::Compiler to compile the POD within a file. The output contains a "beautified" POD, i.e. podlint fixes all errors and warnings with respect to proper POD syntax.

Nothing changes if the input already was perfect. If there were errors, you should check the result whether it reflects what you intended.

This script works either in filter mode (if you omit the arguments), i.e. it reads from STDIN and writes to STDOUT, diagnostic messages always go to STDERR. If you specify the input file name and omit the output file name, the result is printed to STDOUT. See "-i string" for an alternative way of processing arguments.

OPTIONS

-help

Print the usage and options.

-man

Show the complete manual.

-warnings | -nowarnings

Enable or suppress the printing of warnings. Default is enabled.

-errors | -noerrors

Enable or suppress the printing of errors. Default is enabled.

-quiet

Same as -nowarnings -noerrors, and suppress any progress/status output.

-linelength num

Wrap all POD text to the given line length. Forced line breaks (i.e. a newline followed by whitespace) is not modified. Default is to leave paragraphs untouched.

-unwrap string

Unwrap all sequences indicated by the given string (e.g. I or BI), i.e. convert I<abcI<def>ghi> to I<abc>defI<ghi>. Default is no unwraps.

-unnest string

Unnest all sequences indicated by the given string (e.g. B or BCS), i.e. drop all occurrences of an interior sequence contained in one of the same type. Default is BCFS.

-perlcode | -noperlcode

Include or exclude non-POD (i.e. executable Perl code) in the output. Default is to include Perl code.

-i string

Similar to the Perl -i option, see perlrun: Create a backup file of the given input file. If string is empty, the input file will be overwritten without creating a backup. All command line arguments are treated as input files.

RETURN VALUE

0 in case of success, a non-zero value in case of fatal errors.

EXAMPLES

cat mail_containing_perl | podlint -noperlcode | less

Get all the POD out of the given file.

podlint abc.pod abc1.pod

Lint abc.pod and write the result to abc1.pod.

podlint -linelength  -i .bak abc.pod def.pod ghi.pod

Beautify the files abc.pod, def.pod, ghi.pod, keeping the original contents in abc.pod.bak, def.pod.bak, ghi.pod.bak, respectively.

CAVEATS

This tool depends on the capabilities of Pod::Parser. This means that if you have e.g. POD code in a here document, it is subject to processing by podlint as well.

ERRORS

Errors occur if the input file(s) cannot be read, the output file(s) cannot be written, backup file(s) cannot be created etc.

Errors in the POD syntax are printed, and podlint tries to resolve them as far as possible. The result may not be what you expected it to be, so please crosscheck the result.

If you run podlint on the result again, only those errors should re-occur that could not be fixed (e.g. internal hyperlinks without a destination).

WARNINGS

POD syntax warnings are printed and fixed as far as possible.

BUGS

Please report bugs to <marekr@cpan.org>.

AUTHOR

Marek Rouchal <marekr@cpan.org>

COPYRIGHT

Copyright (C) 2001 by Marek Rouchal. All rights reserved.

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

SEE ALSO

Pod::Compiler, podchecker, Pod::Parser