view release on metacpan or  search on metacpan

lib/App/Pods2Site.pod  view on Meta::CPAN

=head1 NAME

App::Pods2Site - converting pods to HTML site

Find all pods and convert them to linked HTML pages, and add some extra parts on top to bind them together
as a simple documentation site for your Perl installation.

=head1 VERSION

Version 1.003

=head1 SYNOPSIS

  # Normally run 'pods2site' from a shell prompt to create or update:
  # (place a site in the perl tree)
  #
  pods2site :std

  # or an explicit site root
  pods2site /path/to/site

=head1 OVERVIEW

This package is an application, generally intended to be run from a command line.

It was inspired by the HTML documentation present in an ActivePerl installation, and which was
updatable by using the 'ap-update-html' application after new modules had been installed.

As I also use other Perl distributions on both Windows and Linux, I felt the need to have a simple way
to generate something similar anywhere. Hence, this tool which generates a no-frills site similarly looking.

In short, this application will by default create a simple site based on all pods found in the distribution it's installed
in. As modules are updated/installed in the distribution, the application can be run again and efficiently update
the documentation site.

However, it also allows you to search arbitrary locations for pods, as well as cherrypick among the found pods and
skip ones of no interest to you.

=head1 FUNCTION

The overall function is simple:

Use the L<Config> module in the running Perl to find all pods, convert them using L<Pod::Html> and lastly, generate an index page
as well as a TOC and tie it all together. Point a browser at F<index.html> and you're good to go.

At any time, the command can be run again, and this time it will reuse the same options as before and update the site if any pods
are new or newer than the corresponding HTML file.

Taking a cue from the ActivePerl way of collecting the pods, pods are by default divided in 4 categories. The rules for doing this are fairly
simpleminded and heuristic though, so occasionally you may find a module that doesn't really conform to the categorization.
If you're unhappy: define your own groups from scratch.

Further, you may miss documentation for scripts or modules you know are there - this typically means that they don't contain any POD
text. Talk to the module author.

Lastly, due to how L<Pod::HTML> sometimes seem to reason on how links should be fulfilled, they may not necessarily go where you
expect.

=over

=item * Core

This group, as far as I can surmise, are found as pod files in the lib 'pods' directory and named 'perl...'. Technically, this means that they should
be named as 'pods::perlxxx', but as many modules and other pods use links with just 'perlxxx', behind the scenes they are set up to be found in the root also.

=item * Scripts

This group is found in the bin directories (e.g. the F<pods2site> command itself).

=item * Pragmas

Defined as modules with a (top-level) name starting with a lowercase a-z, such as 'attributes' but also 'autodie::Scope::Guard'.

=item * Modules

Everything else.

=back

=head1 AUTHOR

Kenneth Olwing, C<< <knth at cpan.org> >>

=head1 BUGS

Please report any bugs or feature requests to C<bug-app-pods2site at rt.cpan.org>,
or through the web interface at
L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-Pods2Site>. I will be
notified, and then you'll automatically be notified of progress on your bug as
I make changes.

=head1 SUPPORT