add-pod-file - Utility to add new pod/*.pod file to core distribution
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.
NAMEsection of this file there is a single non-blank line which consists of a string in the format
STUB - ABSTRACT, where
STUBis the basename of the file without the
ABSTRACTis the short description of the file. For example, a new file whose path is pod/perlphonypod.pod must have a
NAMEsection 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
- 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.