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


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


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


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.


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.