ch07.002_best_ex7.2

Perl Best Practices the source code

##############################################################################
##    Example 7.2 (Recommended) from Chapter 7 of "Perl Best Practices"     ##
##     Copyright (c) O'Reilly & Associates, 2005. All Rights Reserved.      ##
##  See: http://www.oreilly.com/pub/a/oreilly/ask_tim/2001/codepolicy.html  ##
##############################################################################


#  Example 7-2. User documentation template for applications

=head1 NAME
 
<application name> - <One line description of application's purpose>
 
 
=head1 VERSION
 
The initial template usually just has:
 
This documentation refers to <application name> version 0.0.1
 
 
=head1 USAGE
 
    # Brief working invocation example(s) here showing the most common usage(s)
 
    # This section will be as far as many users ever read
    # so make it as educational and exemplary as possible.
 
 
=head1 REQUIRED ARGUMENTS
 
A complete list of every argument that must appear on the command line. 
when the application  is invoked, explaining what each of them does, any
restrictions on where each one may appear (i.e. flags that must appear 
before or after filenames), and how the various arguments and options 
may interact (e.g. mutual exclusions, required combinations, etc.)
 
If all of the application's arguments are optional this section
may be omitted entirely.
 
 
=head1 OPTIONS
 
A complete list of every available option with which the application 
can be invoked, explaining what each does, and listing any restrictions,
or interactions.
 
If the application has no options this section may be omitted entirely.
 
 
=head1 DESCRIPTION
 
A full description of the application and its features.
May include numerous subsections (i.e. =head2, =head3, etc.) 
 
 
=head1 DIAGNOSTICS
 
A list of every error and warning message that the application can generate
(even the ones that will "never happen"), with a full explanation of each 
problem, one or more likely causes, and any suggested remedies. If the
application generates exit status codes (e.g. under Unix) then list the exit
status associated with each error.
 
 
=head1 CONFIGURATION AND ENVIRONMENT
 
A full explanation of any configuration system(s) used by the application,
including the names and locations of any configuration files, and the
meaning of any environment variables or properties that can be set. These
descriptions must also include details of any configuration language used
(also see  QUOTE \" " INCLUDETEXT "19_Miscellanea" "XREF40334_Configuration_Files_"\! Configuration Files QUOTE \" " QUOTE " in Chapter "  in Chapter  INCLUDETEXT "19_Miscellanea" "XREF55683__"\! 19).
  
 
=head1 DEPENDENCIES
=head1 INCOMPATIBILITIES
=head1 BUGS AND LIMITATIONS
=head1 AUTHOR
=head1 LICENCE AND COPYRIGHT
 
These sections are the same as in  REF XREF45430_Example_71_ \h Example 7-1  08D0C9EA79F9BACE118C8200AA004BA90B0200000008000000160000005800520045004600340035003400330030005F004500780061006D0070006C0065005F00370031005F000000 .