home *** CD-ROM | disk | FTP | other *** search
/ PC Welt 2006 November (DVD) / PCWELT_11_2006.ISO / casper / filesystem.squashfs / usr / share / doc / man-db / examples / manpage.example.pod < prev    next >
Encoding:
Text File  |  2001-09-18  |  2.7 KB  |  127 lines
  1. =head1 NAME
  2.  
  3. foo, bar - programs to do something
  4.  
  5. =head1 SYNOPSIS
  6.  
  7. A short usage summary.
  8.  
  9. B<foo> { B<this>|B<that> } [ B<-flags> ] [ B<-o> I<option> ] I<argument> [ I<more...> ]
  10.  
  11. =head1 DESCRIPTION
  12.  
  13. Long drawn-out discussion of the program. It's a good idea to break this
  14. up into subsections using "=head2" directives, like these:
  15.  
  16. =head2 A Sample Subsection
  17.  
  18. =head2 Yet Another Sample Subsection
  19.  
  20. References to the foo(1) (or other) manual page should be written normally
  21. as here; B<pod2man> will usually guess the correct formatting. Use S<L><>
  22. (e.g. L<foo(SECTION)>) if you need to force this.
  23.  
  24. Paragraphs are separated by blank lines.
  25.  
  26. =head1 OPTIONS
  27.  
  28. Some people make this separate from the description.
  29.  
  30. The following style is typically used to document options:
  31.  
  32. =over 8
  33.  
  34. =item B<this>|B<that>
  35.  
  36. The user MUST specify either B<this> or B<that> to run the program. The {
  37. and } braces mean one of the enclosed is required. The bar (|) separates
  38. exclusive options (i.e. you cannot have both at once).
  39.  
  40. =item B<-o>
  41.  
  42. Pass the user-supplied I<option> to B<foo> to change its behaviour. The
  43. fact that I<option> is underlined or in italics means that the user replaces
  44. it with a valid value for this option. The [ and ] brackets mean it isn't
  45. required.
  46.  
  47. =item I<argument>
  48.  
  49. The last I<argument> is required, because it is not in brackets.
  50.  
  51. =item I<more>
  52.  
  53. means that the user can optionally specify additional arguments at the end.
  54. The ellipses (...) indicate one or more of this parameter is allowed.
  55.  
  56. =back
  57.  
  58. =head1 RETURN VALUE
  59.  
  60. What the program or function returns if successful.
  61.  
  62. =head1 ERRORS
  63.  
  64. Return codes, either exit status or errno settings.
  65.  
  66. =head1 EXAMPLES
  67.  
  68. Give some example uses of the program.
  69.  
  70. =head1 ENVIRONMENT
  71.  
  72. Environment variables this program might care about.
  73.  
  74. =head1 FILES
  75.  
  76. All files used by the program. Typical usage is like this:
  77.  
  78. =over 8
  79.  
  80. =item F</usr/man>
  81.  
  82. default man tree
  83.  
  84. =item F</usr/man/man*/*.*>
  85.  
  86. unformatted (nroff source) man pages
  87.  
  88. =back
  89.  
  90. =head1 NOTES
  91.  
  92. Miscellaneous commentary.
  93.  
  94. =head1 CAVEATS
  95.  
  96. Things to take special care with, sometimes called WARNINGS.
  97.  
  98. =head1 DIAGNOSTICS
  99.  
  100. All the possible error messages the program can print out, what they
  101. mean, and how to correct them if applicable.
  102.  
  103. =head1 BUGS
  104.  
  105. Things that are broken or just don't work quite right.
  106.  
  107. =head1 RESTRICTIONS
  108.  
  109. Bugs you don't plan to fix. :-)
  110.  
  111. =head1 AUTHOR
  112.  
  113. Who wrote it (or AUTHORS if multiple).
  114.  
  115. This example was constructed by Colin Watson <S<cjwatson@debian.org>>
  116. from a template provided by Tom Christiansen <S<tchrist@jhereg.perl.com>>.
  117.  
  118. =head1 HISTORY
  119.  
  120. Programs derived from other sources sometimes have this.
  121.  
  122. =head1 SEE ALSO
  123.  
  124. Other man pages to check out, like man(1), man(7), mandb(8), catman(8).
  125.  
  126. For this example, see pod2man(1) for more details.
  127.