diff options
Diffstat (limited to 'docs/manpage.example')
| -rw-r--r-- | docs/manpage.example | 114 |
1 files changed, 114 insertions, 0 deletions
diff --git a/docs/manpage.example b/docs/manpage.example new file mode 100644 index 0000000..8a9d22e --- /dev/null +++ b/docs/manpage.example @@ -0,0 +1,114 @@ +.\" In .TH, FOO should be all caps, SECTION should be 1-8, maybe w/ subsection +.\" other parms are allowed: see man(7), man(1) +.\" +.\" This template provided by Tom Christiansen <tchrist@jhereg.perl.com>. +.\" +.TH FOO SECTION +.SH NAME +foo, bar \- programs to do something +.SH SYNOPSIS +A short usage summary. +.PP +.B foo +{ +.BR this | that +} +[ +.B -flags +] +[ +.B \-o +.I option +] +.I argument +[ +.I more... +] +.SH DESCRIPTION +.\" Putting a newline after each sentence can generate better output. +Long drawn-out discussion of the program. +It's a good idea to break this up into subsections using the .SS macro, +like these: +.SS "A Sample Subsection" +.SS "Yet Another Sample Subsection" +References to the +.BR foo (SECTION) +(or other) manual page should use the .BR macro as here. +.PP +Use the .PP macro to start a new paragraph within a section. +.SH OPTIONS +Some people make this separate from the description. +The following style is typically used to document options: +.TP +.BR this | that +The user MUST specify either +.B this +or +.B that +to run the program. +The { and } braces mean one of the enclosed is required. +The bar (|) separates exclusive options (i.e. you cannot have both at once). +.TP +.B \-o +Pass the user-supplied +.I option +to +.B foo +to change its behaviour. +The fact that +.I option +is underlined or in italics means that the user replaces it with a valid +value for this option. +The [ and ] brackets mean it isn't required. +.IP +Use \(oq\e-\(cq rather than \(oq-\(cq for dashes in command-line options. +\(oq-\(cq means hyphen, and formats differently when using certain output +devices. +.TP +.I argument +The last +.I argument +is required, because it is not in brackets. +.TP +.I more +means that the user can optionally specify additional arguments at the end. +The ellipses (...) indicate one or more of this parameter is allowed. +.SH "RETURN VALUE" +What the program or function returns if successful. +.SH ERRORS +Return codes, either exit status or errno settings. +.SH EXAMPLES +Give some example uses of the program. +.SH ENVIRONMENT +Environment variables this program might care about. +.SH FILES +All files used by the program. +Typical usage is like this: +.br +.nf +.\" set tabstop to longest possible filename, plus a wee bit +.ta \w'/usr/lib/perl/getopts.pl 'u +\fI/usr/man\fR default man tree +\fI/usr/man/man*/*.*\fR unformatted (nroff source) man pages +.SH NOTES +Miscellaneous commentary. +.SH CAVEATS +Things to take special care with, sometimes called WARNINGS. +.SH DIAGNOSTICS +All the possible error messages the program can print out, +what they mean, and how to correct them if applicable. +.SH BUGS +Things that are broken or just don't work quite right. +.SH RESTRICTIONS +Bugs you don't plan to fix. :-) +.SH AUTHOR +Who wrote it (or AUTHORS if multiple). +.SH HISTORY +Programs derived from other sources sometimes have this. +.SH "SEE ALSO" +.\" Always quote multiple words for .SH +Other man pages to check out, like +.BR man (1), +.BR man (7), +.BR mandb (8), +.BR catman (8). |