The document type tt(manpage) is implemented for the creation of Unix-style 
manual pages. A tt(manpage) document bf(must) be organized as follows:

starteit()

    eit() The manual page itself is defined, using the macro
    
verb(manpage(short title)
            (section)
            (date)
            (source)
            (manual))
            
    where the arguments are:
    
    startdit()
    
        dit(Short title:) This should be the program name or something
        similar; i.e., whatever the manpage is describing.

        dit(Section:) A number, stating the manpage section. The Linux man (7)
        page states in respect to sections, that section 1 is for commands, 2
        for system calls, 3 for library calls, 4 for special files (e.g.,
        devices), 5 for file formats, 6 for games, 7 for macro packages and
        conventions, 8 for system management commands and 9 for other
        manpages, such as kernel commands.

        dit(Date:) The date of release.

        dit(Source:) The package where the manpage belongs to.

        dit(Manual:) The manual to which the package belongs.

    enddit()

    The arguments to the tt(manpage) macro define, e.g., the headers and
    footers of the manual page. The tt(date), tt(source) and tt(manual) 
    arguments can be empty.

    eit() The subject of the manpage is stated using

verb(manpagename(name)(short description))

    The tt(name) argument should be a short name (e.g., the program name), and
    the tt(short description) should state the function. The descriptive
    argument is used by, e.g., the tt(whatis) database.

    eit() The synopsis is started with

verb(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.

    eit() The description is presented using

verb(manpagedescription())

    followed by some descriptive text. The descriptive text can e.g. show what
    the program is supposed to do.

    eit() The options may be listed following

verb(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 tt(manpageoptions()) section is 
    optional. 

    eit() Necessary files are listed following

verb(manpagefiles())

    eit() The `see also' entry is started with

verb(manpageseealso())

    followed by a list of related manual pages.

    eit() The diagnostics are described following

verb(manpagediagnostics())

    Diagnostics can state, e.g., what error messages are produced by the
    program and what the cure is.

    eit() Next, known bugs can be described following

verb(manpagebugs())

    This section is optional.

    eit() Finally the author is stated after

verb(manpageauthor())

endeit()

The tt(manpage) document type bf(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 
(tt(sect), tt(subsect) etc.) are not allowed in a tt(manpage). You em(can)
however insert other sections in the manual page with the macro
tt(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 tt(yodl) program follows (the actual 
manual page may differ):

verb(\
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)
)

)
