manpage
is implemented for the creation of Unix-style
manual pages. A manpage
document must be organized as follows:
manpage(short title) (section) (date) (source) (manual)
where the arguments are:
The arguments to the manpage
macro define, e.g., the headers and
footers of the manual page. The date
, source
and manual
arguments can be empty.
manpagename(name)(short description)
The name
argument should be a short name (e.g., the program name), and
the short description
should state the function. The descriptive
argument is used by, e.g., the whatis
database.
manpagesynopsis()
after which an abbreviated usage information is presented. This information should show, e.g., the possible program flags and required arguments; but no more.
manpagedescription()
followed by some descriptive text. The descriptive text can e.g. show what the program is supposed to do.
manpageoptions()
The options are typically a descriptive list of possible flags and their
meaning. This section lists the information of the synopsis, but also
gives an in-depth description. The manpageoptions()
section is
optional.
manpagefiles()
manpageseealso()
followed by a list of related manual pages.
manpagediagnostics()
Diagnostics can state, e.g., what error messages are produced by the program and what the cure is.
manpagebugs()
This section is optional.
manpageauthor()
The manpage
document type requires you to strictly follow the above
order of commands and to state all the necessary sections (and optionally, to
state the not required sections but in their right order).
Furthermore, sectioning commands that are available in other document types
(sect
, subsect
etc.) are not allowed in a manpage
. You can
however insert other sections in the manual page with the macro
manpagesection
. This macro takes one argument: the title of the extra
section. It is suggested that you type the section name in upper case, to
conform to the `standard'.
As an example, the manual page for the yodl
program follows (the actual
manual page may differ):
manpage(yodl) (1) (1996) (The Yodl Package) (Yet oneOther Document Language) manpagename(yodl)(main Yodl convertor) manpagesynopsis() bf(yodl) [-DNAME] [-IDIR] [-oFILE] [-PCMD] [-pPASS] [-t] [-v] [-w] [-h] [-?] inputfile [inputfile...] manpagedescription() This manual page describes the bf(yodl) program, the main converter of the Yodl package. This program is used by the bf(yodl2....) shell scripts, e.g., bf(yodl2tex) or bf(yodl2html). manpageoptions() startdit() dit(-DNAME) Defines symbol em(NAME). dit(-IDIR) Overrules the standard include directory (default em(/usr/local/lib/yodl)) with em(DIR). dit(-oFILE) Specifies em(FILE) as the output file (default is stdout). dit(-PCMD) `Preloads' command em(CMD), as if em(CMD) was the first line of the input. dit(-pPASS) Defines em(PASS) as the maximum number of `passes'; when this number is exceeded, bf(yodl) aborts. dit(-t) Enables tracing mode. Useful for debugging. dit(-v) Raises the verbosity mode. Useful for debugging. dit(-w) Enables warning. When enabled, bf(yodl) will warn when it sees inconsistencies. dit(-h, -?) Shows usage information. dit(inputfile) File to process, use em(-) to instruct bf(yodl) to read from stdin. enddit() manpagefiles() The bf(yodl) program requires no files, but `normal' usage of the Yodl package requires macro files installed in bf(/usr/local/lib/yodl). The files in this directory are included by the converters bf(yodl2txt) etc.. manpageseealso() bf(yodl2tex), bf(yodl2html), bf(yodl2man), etc.. manpagediagnostics() Warnings and errors of bf(yodl) are too many to enumerate, but all errors are printed to em(stderr) after which bf(yodl) exits with a non-zero status. manpagebugs() There may be bugs in the bf(yodl) program, but that's not very likely. More likely you'll encounter bugs or omissions in the macro package itself. manpageauthor() Karel Kubat (karel@icce.rug.nl)
)
Please send Yodl questions and comments to yodl@icce.rug.nl.
Please send comments on these web pages to
(address unknown),
send other FSF & GNU inquiries and questions to
Copyright (c) 1998 Karel Kubat and Jan Nieuwenhuizen
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.