yodlmanpage - Yodl’s `manpage’ document type
document type was specifically implemented to write
Unix-style manual pages. Other Yodl document formats, such as article
are documented in the Yodl guide and in the
manpage for yodlmacros
This manual page briefly describes the manpage
document type of the
document language. This document type is specific enough that it
warrants a separate manpage.
mapage documents can be converted to groff documents (using
yodl2man), to html documents (using yodl2html), or to plain ascii text
documents (using yodl2txt).
documents do not use the `standard’ sectioning commands
() and subsect
()), but have specific
() macros. You can however use (and are encouraged to..)
other `normal’ macros, such as description
(...) for lists, or bf
() for boldface and em
for emphasis. As for fonts, the following is suggested:
- Use em(text) when text is a variable,
or a placeholder, etc..
- Use bf(text) when text is literal,
such as a command, a filename, a directory. Each manpage document
in Yodl must be organized as follows:
- manpage(name) (section) (date)
( package) ( source): This is the preamble of the document.
It states whatever the page describes, the section where it belongs, the
release date, the package that it belongs to, and the source of the
package. The section number should be (according to the Linux
manpage on man): 1 for commands, 2 for system calls, 3 for library calls,
4 for special files, 5 for file formats, 6 for games, 7 for macro packages
and conventions, 8 for system management commands, and 9 for other special
subjects (e.g., kernel commands).
- manpagename(name) (short description):
The name is again whatever is described, the short
description is what e.g., the whatis database uses for
- manpagesynopsis(): a very short `usage’
information or similar. Keep this section short, e.g., a line with all
program options is acceptable but without descriptions (these come
- manpagedescription(): the purpose of the program and
such. This is also the place to document the workings.
- manpageoptions(): This is the place to document e.g.
the flags that are stated in the manpagesynopsis(). This section is
optional, but when present, must appear at this place.
- manpagefiles(): relevant files are described in this
- manpageseealso(): this section lists related manual
- manpagediagnostics(): Error conditions, error
- manpagebugs(): This is where known bugs are
described. This section is optional.
- manpageauthor(): stating the author and/or the
- manpagesection(NAME): This macro starts a
generic, non-required section. E.g., you might want a
manpagesection (EXAMPLES) in your document. As a typographic
suggestion, use upper case for the NAME argument for consistency
Frank B. Brokken (firstname.lastname@example.org),