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 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 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.

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.