Pod::Thread

(Convert POD data to the HTML macro language thread)

Synopsis | Description | Diagnostics | See Also | Author
Copyright and License

SYNOPSIS

    use Pod::Thread;
    my $parser = Pod::Thread->new;

    # Read POD from STDIN and write to STDOUT.
    $parser->parse_from_filehandle;

    # Read POD from file.pod and write to file.th.
    $parser->parse_from_file ('file.pod', 'file.th');

DESCRIPTION

Pod::Thread is a module that can convert documentation in the POD format (the preferred language for documenting Perl) into thread, an HTML macro language. It lets the converter from thread to HTML handle some of the annoying parts of conversion to HTML.

As a derived class from Pod::Parser, Pod::Thread supports the same methods and interfaces. See Pod::Parser for all the details; briefly, one creates a new parser with Pod::Thread->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.

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.

The recognized options to new() are as follows. All options take a single argument.

contents

Asks for a table of contents section at the beginning of the document. Should be set to a hash table mapping section headers to section numbers prefixed by S (for internal links).

id

Sets the CVS Id string for the file. If this isn't set, Pod::Thread will try to find it in the file, but will only successfully find it if it occurs before the beginning of any POD in the input file.

navbar

Asks for a navigation bar at the beginning of the document. Should be set to a hash table mapping section headers to section numbers prefixed by S (for internal links).

style

Sets the name of the style sheet to use. If not given, no reference to a style sheet will be included in the generated page.

title

The title of the document. If this is set, it will be used rather than looking for and parsing a NAME section in the POD file, and NAME sections will no longer be required or special.

DIAGNOSTICS

Bizarre space in item

Item called without tag

(W) Something has gone wrong in internal =item processing. These messages indicate a bug in Pod::Thread; you should never see them.

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

%s:%d: Unknown formatting code: %s

(W) The POD source contained a non-standard formatting code (something of the form X<>) that Pod::Thread didn't know about.

%s:%d: Unmatched =back

(W) Pod::Thread encountered a =back command that didn't correspond to an =over command.

SEE ALSO

Pod::Parser, spin(1)

Current versions of this program are available from my web tools page at <http://www.eyrie.org/~eagle/software/web/>. spin is available from the same page.

AUTHOR

Russ Allbery <rra@stanford.edu>, based heavily on Pod::Text.

COPYRIGHT AND LICENSE

Copyright 2002 by Russ Allbery <rra@stanford.edu>.

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