=head1 NAME

autopod - generating documentation from POD formatted input with the
MST autotool setup

=head1 DESCRIPTION

POD formatted text is used in a number of places.  There are a number
of common usage scenarios which have been codified into easy to use
snippets.  More complex usage requires a more in-depth understanding of
how the POD snippets tie together.

In order to ensure that the exported distribution does not depend upon
the tools required to generate the documentation, the formatted output
must be distributed along with any intermediate dependencies.  The
documentation may have values interpolated into during the
maintainer's build process, but those values will be frozen and
shipped.  To prevent confusion, make sure that those values are fairly
benign (like the package version), and try to avoid putting absolute
paths into the documentation.

Future updates to the snippets may check for the presence of the
documentation tools and allow generation of output upon their
presence.

The standard snippets install the documentation in the following
places:

  $(prefix)/share/<prog>/html/<prog>.html
  $(prefix)/share/<prog>/<prog>.ps
  $(prefix)/man/manl/<prog>.l


=head1 USAGE

=over

=item F<configure.ac>

Add

  m4_include(snippets/pod_docs.ac)

=item F<Makefile.am>

If the documentation is in the F<docs> subdirectory and is
interpolated (via F<configure.ac> or F<docs/Makefile.am>) ensure that
the F<docs> directory I<preceeds> the source code directory in the
C<SUBDIRS> list so that the interpolation is done before the source
build process requires it.

=back

=head2 Interpolating into POD source

If the POD source is interpolated into (either by F<configure> or by a
rule in the F<Makefile>) substitute

  include $(top_srcdir)/snippets/prog_pod_subst.mk

for

  include $(top_srcdir)/snippets/prog_pod.mk

and

  include $(top_srcdir)/snippets/lib_pod_subst.mk

for

  include $(top_srcdir)/snippets/lib_pod.mk

in the directions below.  The input POD files must have an additional
F<.in> suffix:

       foo.pod.in


=head2 Common Scenarios

=head3 Perl Executable Source With Embedded Documentation

If the POD is embedded into a single Perl source file (as is the case
with most Perl applications), say F<E<lt>progE<gt>.pl.in>, then the
following magic may be invoked in F<Makefile.am>

  include $(top_srcdir)/snippets/create_am_macros.mk
  include $(top_srcdir)/snippets/prog_perl.mk

  dist_manl_MANS = <prog>.l
  POD_SFX = .pl.in
  PODS = <prog>
  include $(top_srcdir)/snippets/prog_pod.mk

If multiple source files have documentation, simply append them to the
C<dist_manl_MANS> and C<PODS> variables.  Note that 

=over

=item *

The files must all have the same suffix (POD_SFX)

=item *

C<dist_manl_MANS> must be an explicit list; it cannot use any B<make>
variable substitutions.

=back

=head3 A Program with Standalone Documentation

Here the POD source is in a separate POD file.  Insert the following
in F<Makefile.am>

  include $(top_srcdir)/snippets/create_am_macros.mk

  dist_manl_MANS = <prog>.l
  POD_SFX = .pod
  PODS = <prog>

  include $(top_srcdir)/snippets/prog_pod.mk

If the suffix is other than C<.pod>, amend the above to reflect that.

=head3 A Library with Standalone Documentation

Here the POD source is in a separate POD file.  Insert the following
in F<Makefile.am>

  include $(top_srcdir)/snippets/create_am_macros.mk

  dist_man3_MANS = <lib>.3
  POD_SFX = .pod
  PODS = <lib>

  include $(top_srcdir)/snippets/lib_pod.mk

If the suffix is other than C<.pod>, amend the above to reflect that.

=head3 Multiple Manual Pages Intended For Different Sections

If there are multiple manual pages destined for different sections of
the UNIX manual (e.g, C<lib.3> and C<lib.5>), things are a little
different.  I<All> POD source files must have names which include the
section identifier:

	<prog>.l.pod
	<lib>.3.pod
	<file>.5.pod

Only sections C<l>, C<3>, and C<5> are supported.

Insert the following into F<Makefile.am>

  include include $(top_srcdir)/snippets/create_am_macros.mk

  dist_manl_MANS = <prog>.l
  dist_man3_MANS = <lib>.3
  dist_man5_MANS = <file>.5
  POD_SFX = .pod
  PODS = <prog>.l <lib>.3 <lib>.5

  include include $(top_srcdir)/snippets/pod_all.mk

Obviously, only include the C<dist_manX_MANS> variables which are required.


=head2 More Complex Scenarios

=head3 Generating only man pages

If only a man page is desired (for instance if the main documentation
is in texinfo, which does not produce a man page), it is necessary to
circumvent the construction of HTML and PostScript.  This requires
including only those parts of the F<pod_man> structure that are
required.  Here's the magic for F<Makefile.am> for a section C<l>
manual page derived from a file called F<E<lt>progE<gt>.pod>:

  include include $(top_srcdir)/snippets/create_am_macros.mk

  # this part is standard
  dist_manl_MANS = <prog>.l
  POD_SFX = .pod
  PODS    = <prog>

  # need these because we call pod_man directly
  POD_DIR = $(srcdir)/
  EXTRA_DIST += $(PACKAGE_NAME)$(POD_SFX)

  include include $(top_srcdir)/snippets/pod_man_init.mk
  include include $(top_srcdir)/snippets/pod_manl.mk




