summaryrefslogtreecommitdiffstats
path: root/docs/manpage.example
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-06 01:16:24 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-06 01:16:24 +0000
commit9221dca64f0c8b5de72727491e41cf63e902eaab (patch)
treed8cbbf520eb4b5c656a54b2e36947008dcb751ad /docs/manpage.example
parentInitial commit. (diff)
downloadman-db-9221dca64f0c8b5de72727491e41cf63e902eaab.tar.xz
man-db-9221dca64f0c8b5de72727491e41cf63e902eaab.zip
Adding upstream version 2.8.5.upstream/2.8.5upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'docs/manpage.example')
-rw-r--r--docs/manpage.example114
1 files changed, 114 insertions, 0 deletions
diff --git a/docs/manpage.example b/docs/manpage.example
new file mode 100644
index 0000000..efd9276
--- /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).