.TH "yodlmanpage" "7" "1996\-2021" "yodl_4\&.03\&.03" "Your Own Document Language"

.PP 
.SH "NAME"
yodlmanpage \- Yodl\(cq\&s `manpage\(cq\& document type
.PP 
.SH "SYNOPSIS"

.PP 
The \fBmanpage\fP document type was specifically implemented to write
Unix\-style manual pages\&. Other Yodl document formats, such as \fBarticle\fP,
\fBreport\fP and \fBbook\fP are documented in the Yodl guide and in the
manpage for \fByodlmacros\fP\&.
.PP 
.SH "DESCRIPTION"

.PP 
This manual page briefly describes the \fBmanpage\fP document type of the
\fBYodl\fP document language\&. This document type is specific enough that it
warrants a separate manpage\&.
.PP 
\fBYodl\fP mapage documents can be converted to `groff\(cq\& documents (using
`yodl2man\(cq\&), to `html\(cq\& documents (using `yodl2html\(cq\&), or to plain
ascii text documents (using `yodl2txt\(cq\&)\&.
.PP 
\fBmanpage\fP documents do not use the `standard\(cq\& sectioning commands (e\&.g\&.,
\fBsect\fP() and \fBsubsect\fP()), but have specific \fBmanpage\&.\&.\&.\fP() macros\&.
You can however use (and are encouraged to\&.\&.) other `normal\(cq\& macros, such
as \fBdescription\fP(\&.\&.\&.) or \fBitemization\fP(\&.\&.\&.) for lists, or \fBbf\fP() for
boldface and \fBem\fP() for emphasis\&. As for fonts, the following is
suggested:
.IP o 
Use \fBem\fP(\fItext\fP) when \fItext\fP is a variable, or a
placeholder, etc\&.\&.
.IP o 
Use \fBbf\fP(\fItext\fP) when \fItext\fP is literal, such as a command,
a filename, a directory\&.
Each \fBmanpage\fP document in Yodl must be organized as follows:
.PP 
.IP o 
\fBmanpage\fP(\fIname\fP) (\fIsection\fP) (\fIdate\fP) (\fIpackage\fP)
(\fIsource\fP): 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 \fIsection\fP 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)\&.
.IP o 
\fBmanpagename\fP(\fIname\fP) (\fIshort description\fP):  The \fIname\fP
is again whatever is described, the \fIshort description\fP is what
e\&.g\&., the \fBwhatis\fP database uses for descriptions\&.
.IP o 
\fBmanpagesynopsis\fP(): a very short `usage\(cq\& information or
similar\&.  Keep this section short, e\&.g\&., a line with all program
options is acceptable but without descriptions (these come later)\&.
.IP o 
\fBmanpagedescription\fP(): the purpose of the program and such\&.
This is also the place to document the workings\&.
.IP o 
\fBmanpageoptions\fP(): This is the place to document e\&.g\&. the
flags that are stated in the \fBmanpagesynopsis\fP()\&. This section is 
optional, but when present, must appear at this place\&.
.IP o 
\fBmanpagefiles\fP(): relevant files are described in this section\&.
.IP o 
\fBmanpageseealso\fP(): this section lists related manual pages\&.
.IP o 
\fBmanpagediagnostics\fP(): Error conditions, error messages, etc\&.\&.
.IP o 
\fBmanpagebugs\fP(): This is where known bugs are described\&. This 
section is optional\&.
.IP o 
\fBmanpageauthor\fP(): stating the author and/or the maintainer\&.
.IP o 
\fBmanpagesection\fP(\fINAME\fP): This macro starts a generic, 
non\-required section\&. E\&.g\&., you might want a 
\fBmanpagesection\fP\fB(EXAMPLES)\fP in your document\&. As a typographic 
suggestion, use upper case for the \fBNAME\fP argument for consistency 
reasons\&. 

.PP 
.SH "SEE ALSO"

.PP 
\fByodl\fP(1), 
\fByodlbuiltins\fP(7), 
\fByodlconverters\fP(1), 
\fByodlletter\fP(7), 
\fByodlmacros\fP(7), 
\fByodlpost\fP(1), 
\fByodlstriproff\fP(1), 
\fByodltables\fP(7), 
\fByodlverbinsert\fP(1)\&.
.PP 
.SH "BUGS"

.PP 
\-
.PP 
.SH "AUTHOR"

.PP 
Frank B\&. Brokken (f\&.b\&.brokken@rug\&.nl),