standards: Man Pages

1 
1 6.9 Man Pages
1 =============
1 
1 In the GNU project, man pages are secondary.  It is not necessary or
1 expected for every GNU program to have a man page, but some of them do.
1 It's your choice whether to include a man page in your program.
1 
1    When you make this decision, consider that supporting a man page
1 requires continual effort each time the program is changed.  The time
1 you spend on the man page is time taken away from more useful work.
1 
1    For a simple program which changes little, updating the man page may
1 be a small job.  Then there is little reason not to include a man page,
1 if you have one.
1 
1    For a large program that changes a great deal, updating a man page
1 may be a substantial burden.  If a user offers to donate a man page, you
1 may find this gift costly to accept.  It may be better to refuse the man
1 page unless the same person agrees to take full responsibility for
1 maintaining it--so that you can wash your hands of it entirely.  If this
1 volunteer later ceases to do the job, then don't feel obliged to pick it
1 up yourself; it may be better to withdraw the man page from the
1 distribution until someone else agrees to update it.
1 
1    When a program changes only a little, you may feel that the
1 discrepancies are small enough that the man page remains useful without
1 updating.  If so, put a prominent note near the beginning of the man
1 page explaining that you don't maintain it and that the Texinfo manual
1 is more authoritative.  The note should say how to access the Texinfo
1 documentation.
1 
1    Be sure that man pages include a copyright statement and free
1 license.  The simple all-permissive license is appropriate for simple
1 man pages (⇒(maintain)License Notices for Other Files).
1 
1    For long man pages, with enough explanation and documentation that
11 they can be considered true manuals, use the GFDL (⇒License for
 Manuals).
1 
1    Finally, the GNU help2man program
1 (<http://www.gnu.org/software/help2man/>) is one way to automate
1 generation of a man page, in this case from '--help' output.  This is
1 sufficient in many cases.
1