NAME
yodlmanpage - Yodl’s ‘manpage’ document type
SYNOPSIS
The manpage document type was specifically implemented to write
Unix-style manual pages. Other Yodl document formats, such as article,
report and book are documented in the Yodl guide and in the manpage for
yodlmacros.
DESCRIPTION
This manual page briefly describes the manpage document type of the
YOLD document language. This document type is specific enough that it
warrants a separate manpage.
manpage documents do not use the ‘standard’ sectioning commands (e.g.,
sect() and subsect()), but have specific manpage...() macros. You can
however use (and are encouraged to..) other ‘normal’ macros, such as
description(...) or itemization(...) for lists, or bf() for boldface
and em() for emphasis. As for fonts, the following is suggested:
o Use em(text) when text is a variable, or a placeholder, etc..
o 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:
o 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).
o manpagename(name) (short description): The name is again
whatever is described, the short description is what e.g., the
whatis database uses for descriptions.
o 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 later).
o manpagedescription(): the purpose of the program and such. This
is also the place to document the workings.
o 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.
o manpagefiles(): relevant files are described in this section.
o manpageseealso(): this section lists related manual pages.
o manpagediagnostics(): Error conditions, error messages, etc..
o manpagebugs(): This is where known bugs are described. This
section is optional.
o manpageauthor(): stating the author and/or the maintainer.
o 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 reasons.
SEE ALSO
yodlstriproff(1), yodl(1), yodlbuiltins(7), yodlconverters(1),
yodlletter(7), yodlmacros(7), yodlpost(1), yodlverbinsert(1).
BUGS
-
AUTHOR
Frank B. Brokken (f.b.brokken@rug.nl),