pod_alternate.md

Alternate Manual of Style for Plain Old Documentation

tl;dr This document describes an alternate, not replacement, manual of style (MoS) for Plain Old Documentation (POD) in Perl.

Introduction

I have been writing a lot of POD lately. I noticed my pinky finger on my right hand was getting tired and even a little painful. I looked at the POD and realized I had been using my pinky finger to hold down the shift key as I typed in the titles of the headings. If you are wondering why I did not use the Caps Lock key, it is because years ago, I repurposed it to be my compose key for my Linux system.

While massaging my pinky, I began wishing that the MoS would allow for sentence case for those headings. I then began wishing the POD was structured more like an article on the module, instead of just being a manual of use.

There are several headings that are generally acceptable currently. Not all of these headings will be used in every module, but these are the ones that seem to be expected.

• NAME
• VERSION
• SYNOPSIS
• DESCRIPTION
• USAGE
• REQUIRED ARGUMENTS
• OPTIONS
• SUBROUTINES
• METHODS
• CONFIGURATION
• ENVIRONMENT
• EXAMPLES
• COMMON USAGE MISTAKES
• FREQUENTLY ASKED QUESTIONS
• DEPENDENCIES
• DIAGNOSTICS
• INCOMPATIBILITIES
• BUGS AND LIMITATIONS
• SEE ALSO
• AUTHOR
• ACKNOWLEDGMENTS
• LICENSE AND COPYRIGHT
• WARRANTY
• DISCLAIMER OF WARRANTY

Whew! Typing those made my pinky tired, and I had to massage it a little.

Now, you may be thinking something along the lines of "Well, you are typing normally between those headings, giving your pinky a break."

You are correct. There is a lot that can go between those headings. However, when I get to those headings, my flow is also interrupted. Between headings I am typing sentences and code.

In almost every other MoS for how to write, the rule is to use sentence case for headings. In most cases, headings are made bold so they stand out from the text before and after them. Even meta::cpan makes headings bold. So why are we still using all capital letters in the headings for POD? Well, some are still writing for reading POD in a terminal with either perldoc or man. I find the only reason I read POD in a terminal is to check my own POD. I go to meta::cpan to read how to use all other modules. I have also noticed that perldoc does not make headings bold, that only happens in man.

Now, let us look at those headings again in sentence case and bold.

• Name
• Version
• Synopsis
• Description
• Usage
• Required arguments
• Options
• Subroutines
• Methods
• Configuration
• Environment
• Examples
• Common usage mistakes
• Frequently asked questions
• Dependencies
• Diagnostics
• Incompatibilities
• Bugs and limitations
• See also
• Author
• Acknowledgments
• License and copyright
• Warranty
• Disclaimer of warranty

(Note, I did not use the POD B<Heading> to make those bold in this post.)

Now is that not easier on the eyes? The headings are not yelling at us for attention. This is not the end of this recommendation.

The recommendation

In most MoS that I had read, the first heading of any document is the title of the document. None of the headings listed above are the title of the documentation of the module. They should be at head2. head1 should be reserved for the name of the module but not with the value of NAME.

=head1 B<Neat::Thing>

After the first heading is where the introduction of the module is written. Also, I made the heading bold because perlpod does not make anything bold unless told to do so.

=head1 B<Neat::Thing>

B<Neat::Thing>, version 1.0, does a thing that is neat and cool.
Its function C<neat_thing> needs to be imported into your script.
C<neat_thinng> will change your life forever.

It requires Perl version 5.10.0.

The introduction includes the name of the module in bold, the version, and a brief description of what it will do. This would eliminate three of the headings above. By putting the introduction of the module at the top of the module, users will be able to see what the module will do for them before getting to the synopsis.

All of the rest of the headings listed above would be head2. Also, all headings would be bold, Heading name.

Now, what I would really love, and have already asked for, is to have head5 and head6 added to the POD specification just as HTML has <h5> and <h6> and markdown has ##### and ######. That way we would not run out of heading levels so fast and have to be even more creative with how we write our POD.

Issues

1. An alternate MoS for POD would mean additional work for those who maintain all of the pod2 converters out there, especially pod2man. pod2man would need a way to convert this alternate MoS to the standard man style. I know I do not have the skill to help with that rewrite, so this would be more work for those who maintain pod2man.
2. An alternate MoS could cause havoc with meta::cpan.
3. An alternate MoS would not be adopted quickly or by many. When one has done something one way for a very long time, one could resist change. As this is an alternate, I do not think many would adopt it.
4. An alternate MoS could lead to more people coming up with their own way of writing POD causing even more confusion. I do not know if the Perl community would want new standards.