helpmessage.5.helpm

   1 // helpmessage.5.helpm - manual page in HelpMessage format
   2 NAME
   3         HelpMessage - Format of the input to helpm2pod(1)
   4
   5 DESCRIPTION
   6         A HelpMessage text needs only be slightly modified to become a POD
   7         formatted text (see perlpod(1)).  It is a bit less powerful than POD but
   8         it is more compact and more readable.
   9   Structure
  10         The structure is coded by the indentation.  Section titles are line without
  11         any indentation.  Text belonging to the section follows it and is indented
  12         by 1 tabulation character (at least).  Subsections titles are indented by
  13         spaces.
  14
  15         In the sections USAGE/SYNOPSIS each line is considered a paragraph.  In the
  16         other sections paragraphs are separated by a blank line as in POD.
  17
  18         List items are indented by a space followed by a tabulation.  List item
  19         descriptions are indented by 2 tabulation characters.
  20
  21         Other structures or formatting is only supported in specific contexts.
  22   Formatting
  23         In other cases leading white space is kept: such blocks are considered
  24         verbatim text by POD.  They do not need to start by an empty line as in
  25         POD, which is convenient to give command line examples.
  26   Styles
  27         Inside normal text or list items, a specific style syntax is recognized
  28         where each occurrence of a word of the form "<..>" or "*..*" is changed to
  29         POD <italic> and POD *bold* respectively.  SYNOPSIS lines and list items
  30         inside the section OPTIONS have "<..>" plus some smart auto styling.
  31
  32         Otherwise POD formatting constructs should be avoided or restricted to add
  33         styles to simple words, as (1) using them contradicts the aspiration to
  34         simply write text, (2) it is simple and more adjustale to write directly
  35         embedded POD and (3) they could interfere with the simplistic analyze made
  36         by helpm2pod.
  37   Comments
  38         A first line starting by a whitespace is considered a header and is
  39         ignored.  Lines starting by a hash (#) or a double slash (//) is considered
  40         a comment and is ignored.
  41
  42 RATIONALE
  43         Embedding an HelpMessage text inside a program is suitable for small
  44         simple programs, as in this case elaborate formatting may be disposed of
  45         without loss of readability.  The advantage is that by simply copying the
  46         script without its generated manual page nor installing pod2man a compact
  47         readable help message is still available to the user.  The format is rather
  48         prone to be reformatted to the adequate terminal width by fmt(1).
  49
  50         The script can generate the message dynamically, adding tty higlighting if
  51         outputting to a terminal or HelpM styles if outputing to generate a
  52         manpage.
  53
  54 ALTERNATIVES
  55         Free-form text
  56                 Help output that is never converted to a standard manual page.
  57         POD
  58                 Documentation converted by pod2man or pod2text (that are runtime
  59                 dependencies) or a help message that is less readable and less compact.
  60         txt2man(1) or help2man(1)
  61                 Programs very similar to helpm2pod that support only man(7) output.
  62         AsciiDoc or Halibut
  63                 Programs that are more complex but with many more possibilities.
  64
  65 EXAMPLES
  66         An example of a help message is given by:
  67           $ helpm2pod -h |$PAGER
  68
  69 SEE ALSO
  70         helpm2pod(1), perlpod(1), fmt(1), helpmselect(1), help2man(1), txt2man(1),
  71         asciidoc(1)