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