NAME

add-pod-file - Utility to add new pod/*.pod file to core distribution

USAGE

After make test_prep has been run, call from top level of Perl 5 core distribution:

perl Porting/add-pod-file \
    --stub=<XXX> --section=<Z> --verbose

DESCRIPTION

This is a program which may be helpful when a committer has to add a new *.pod file in the pod/ directory.

Prerequisites

This program assumes that committer has taken the following steps (in the order listed):

1 You have run make test_prep.

This is to guarantee that all files are properly positioned.

2 You have placed a well-formatted .pod file into the pod/ directory.

In the NAME section of this file there is a single non-blank line which consists of a string in the format STUB - ABSTRACT, where STUB is the basename of the file without the .pod suffix and ABSTRACT is the short description of the file. For example, a new file whose path is pod/perlphonypod.pod must have a NAME section like this:

=head1 NAME

perlphonypod - This is phony POD

pod/*.pod files need entries in multiple locations to keep make test_porting happy. This program automates the formulation of most of those entries, but will need some assistance from the committer to work properly. The committer will have to make a reasonable choice as to which section of pod/perl.pod the new .pod file should be listed under. The eligible sections are shown in the following table:

Command-Line Value      Section in pod/perl.pod

     O               => 'Overview',
     T               => 'Tutorials',
     R               => 'Reference Manual',
     I               => 'Internals and C Language Interface',
     H               => 'History',
     M               => 'Miscellaneous',
     L               => 'Language-Specific',
     P               => 'Platform-Specific',

For a first pass, we'll put the new entry at the end of the ^=head2 section specified by the committer with the single-initial provided for command-line switch section.

Testing this program

1 Run configure and make in the source tree.

2 Create a well formatted .pod file somewhere on your system.

3 Copy it into the source tree under pod.

4 Call the program as in "USAGE" above.

5 Call git diff and examine results.

6 Run make test_porting.

BUGS

When the argument provided to the --section command-line switch is P (for platform-specific), win32/pod.mak is not getting updated -- but it's not clear whether it ought to be updated.