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),