Pod::Thread version 1.01

(Format POD source into thread, an HTML macro language)

Maintained by Russ Allbery <rra@cpan.org>

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself. Please see the section LICENSE below for more information.

BLURB

Pod::Thread translates POD source into thread, a macro language processed by spin. It supports optionally adding a table of contents and a navigation bar to the genenerated file. This package also includes the pod2thread driver script, invoked automatically by spin for POD files and pointers to POD files.

DESCRIPTION

This package contains a module to translate POD into thread, an HTML macro language. As such, it's not very useful without spin, a separate program to convert thread into HTML. spin is available from:

    http://www.eyrie.org/~eagle/software/web/

and the most recent version of this module will be found on the same page. I wrote this module for my personal needs and it may not be (and in fact probably isn't) suitable for more general use as yet.

The eventual intention is to turn the core portions of spin into a second Perl module and add it to this package, which will make this a more generally useful package for HTML page generation. I have no estimate for when that work will be done.

The conversion done by this module is mostly straightforward. The only notable parts are a search through the full processed file for a CVS or Subversion Id string to pass on to the thread source and the optional generation of a table of contents or a navigation bar at the top of the generated file.

REQUIREMENTS

Pod::Thread requires Perl 5.8 or later, Pod::Parser 3.06 or later, and the Readonly module. As mentioned above, it's also not particularly useful without spin.

The test suite makes use of additional Perl modules for some tests. These tests will be skipped automatically if the modules aren't available. To run the full set of default tests, you will need the Perl modules:

    Perl::Critic
    Test::MinimumVersion
    Test::Pod
    Test::Pod::Coverage
    Test::Strict
    Test::Synopsis

and their dependencies. These modules are all available from CPAN.

Some parts of the test suite are suppressed by default because those tests are normally only useful for the maintainer. This includes tests of POD spelling and Perl coding style. To enable those tests, set the environment variable RRA_MAINTAINER_TESTS to a true value. For these tests, the additional Perl modules:

    Devel::Cover
    Test::Perl::Critic
    Test::Spelling

and their dependencies as well as a spell-checking program (several are supported by Test::Spelling) are required. These modules are all available from CPAN.

INSTALLATION

Follow the standard installation procedure for Perl modules, which is to type the following commands:

    perl Makefile.PL
    make
    make install

You'll probably need to do the "make install" as root. This will also install a driver scripts named pod2thread; see its man page for more information.

SUPPORT

My web tools web page at:

http://www.eyrie.org/~eagle/software/web/

will always have the current version of this package, the current documentation, and pointers to any additional resources.

Currently, there is no bug tracker for this package since I've not yet uploaded it to CPAN. I will do so once spin has been converted to a module and is included.

I welcome bug reports and patches for this package at rra@cpan.org. However, please be aware that I tend to be extremely busy and work projects often take priority. I'll save your mail and get to it as soon as I can, but it may take me a couple of months.

SOURCE REPOSITORY

Pod::Thread is maintained using Git. You can access the current source by cloning the repository at:

    git://git.eyrie.org/web/pod-thread.git

or view the repository on the web at:

http://git.eyrie.org/?p=web/pod-thread.git

Debian packaging is kept on the debian branch of the Git repository. When contributing modifications, patches (possibly generated by git-format-patch) are preferred to Git pull requests.

LICENSE

The Pod-Thread distribution as a whole is covered by the following copyright statement and license:

Copyright 2002, 2008, 2009, 2013 Russ Allbery <rra@cpan.org>

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself. This means that you may choose between the two licenses that Perl is released under: the GNU GPL and the Artistic License. Please see your Perl distribution for the details and copies of the licenses.

All individual files without an explicit exception below are released under this license. Some files may have additional copyright holders as noted in those files. There is detailed information about the licensing of each file in the LICENSE file in this distribution.

Some files in this distribution are individually released under different licenses, all of which are compatible with the above general package license but which may require preservation of additional notices. All required notices are preserved in the LICENSE file.

Converted to XHTML by faq2html version 1.32