HelpMessage - Format of the input to helpm2pod(1)
A HelpMessage text needs only be slightly modified to become a POD formatted text (see perlpod(1)). It is a bit less powerful than POD but it is more compact and more readable.
The structure is coded by the indentation. Section titles are line without any indentation. Text belonging to the section follows it and is indented by 1 tabulation character (at least). Subsections titles are indented by spaces.
In the sections USAGE/SYNOPSIS each line is considered a paragraph. In the other sections paragraphs are separated by a blank line as in POD.
List items are indented by a space followed by a tabulation. List item descriptions are indented by 2 tabulation characters.
Other structures or formatting is only supported in specific contexts.
In other cases leading white space is kept: such blocks are considered verbatim text by POD. They do not need to start by an empty line as in POD, which is convenient to give command line examples.
Inside normal text or list items, a specific style syntax is recognized where each occurrence of a word of the form "<..>" or "*..*" is changed to POD italic and POD bold respectively. SYNOPSIS lines and list items inside the section OPTIONS have "<..>" plus some smart auto styling.
Otherwise POD formatting constructs should be avoided or restricted to add styles to simple words, as (1) using them contradicts the aspiration to simply write text, (2) it is simple and more adjustale to write directly embedded POD and (3) they could interfere with the simplistic analyze made by helpm2pod.
A first line starting by a whitespace is considered a header and is ignored. Lines starting by a hash (#) or a double slash (//) is considered a comment and is ignored.
Embedding an HelpMessage text inside a program is suitable for small simple programs, as in this case elaborate formatting may be disposed of without loss of readability. The advantage is that by simply copying the script without its generated manual page nor pod2man a compact readable help message is still available to the user. The format is rather prone to be reformatted to the adequate terminal width by fmt(1).
Help output that is never converted to a standard manual page.
Documentation converted by pod2man or pod2text (that are runtime dependencies) or a help message that is less readable.
Programs very similar to helpm2pod that support only man(7) output.
A program that is a much more complex but with many more possibilities.
An example of a help message is given by:
$ helpm2pod -h |$PAGER
helpm2pod(1), perlpod(1), fmt(1), help2man(1), txt2man(1), asciidoc(1)