view release on metacpan or  search on metacpan

lib/Filter/Heredoc/Cookbook.pod  view on Meta::CPAN

=encoding utf8

=head1 NAME

Filter::Heredoc::Cookbook - The Filter::Heredoc Cookbook

=head1 VERSION

Version 0.05

=cut

=head1 DESCRIPTION

This is the L<Filter::Heredoc::Cookbook>.

This is intended to provide examples and food for thoughts
on the topic 'interesting here document concepts'.

=head1 POD AS HERE DOCUMENTS EMBEDDED IN SHELL SCRIPTS

Embedding documentation in source files as programmers reference
is an excellent strategy to keep them up to date. Embedding POD in
shell scripts as here documents achieves that goal.

Once documentation is in POD, tools like I<pod2pdf> and I<pod2html>
converts files with embedded documentation to pdf or html formats:

    pod2pdf diskusage > diskusage.pdf
    pod2html --infile=diskusage > diskusage.html

Converting documentation to man pages can be done with:

    su -c 'pod2man diskusage > /usr/local/share/man/man1/diskusage.1p'

A problem is to spell check both the verbatim output and the embedded
POD text but it has a solution.

=head2 Perls simple to use markup documentation language - i.e. POD

First, let's show how to embed POD in shell scripts.
We need a I<smart> here document delimiter and we need the POSIX
colon (:) command which does nothing else than expanding arguments
and performing redirections.

  : [arguments]

A very short example shows how to embed POD in shell scripts:

  #!/bin/bash
  # diskusage
  echo Demonstrate how to embed POD.
  echo This is a shell script line.
  
  : <<  =cut
  
  =head1 NAME

  diskusage - Send mail to top consumers of disk space

  =head1 SYNOPSIS

  diskusage 10000
  
  =cut

Note the use of '=cut' as the delimiter for the here document.
Running this prints only the first two I<echo> lines.
Converting this short script file to pdf produces the documentation:

    pod2pdf diskusage > diskusage.pdf
  
=head2 Long example: spell checking a script with multilingual text

The 'diskusage' script will mail all users who exceeded a specified
amount of disk space. However, and in this example only it does not
provide a useful user message when the required argument is missing.
The embedded POD text has included more information though.