<! banner_id >

The document type <code>manpage</code> is implemented for the creation of Unix-style 
manual pages. A <code>manpage</code> document <strong>must</strong> be organized as follows:

<ol>

<li> The manual page itself is defined, using the macro

<pre>
manpage(short title)
            (section)
            (date)
            (source)
            (manual)
</pre>

<p>where the arguments are:
<p><dl>
<p><p></p><dt><strong>Short title:</strong><dd> This should be the program name or something
        similar; i.e., whatever the manpage is describing.
<p><p></p><dt><strong>Section:</strong><dd> 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.
<p><p></p><dt><strong>Date:</strong><dd> The date of release.
<p><p></p><dt><strong>Source:</strong><dd> The package where the manpage belongs to.
<p><p></p><dt><strong>Manual:</strong><dd> The manual to which the package belongs.
<p></dl>
<p>The arguments to the <code>manpage</code> macro define, e.g., the headers and
    footers of the manual page. The <code>date</code>, <code>source</code> and <code>manual</code> 
    arguments can be empty.
<p><li> The subject of the manpage is stated using
<p><pre>
manpagename(name)(short description)
</pre>

<p>The <code>name</code> argument should be a short name (e.g., the program name), and
    the <code>short description</code> should state the function. The descriptive
    argument is used by, e.g., the <code>whatis</code> database.
<p><li> The synopsis is started with
<p><pre>
manpagesynopsis()
</pre>

<p>after which an abbreviated usage information is presented. This
    information should show, e.g., the possible program flags and required
    arguments; but no more.
<p><li> The description is presented using
<p><pre>
manpagedescription()
</pre>

<p>followed by some descriptive text. The descriptive text can e.g. show what
    the program is supposed to do.
<p><li> The options may be listed following
<p><pre>
manpageoptions()
</pre>

<p>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 <code>manpageoptions()</code> section is 
    optional. 
<p><li> Necessary files are listed following
<p><pre>
manpagefiles()
</pre>

<p><li> The `see also' entry is started with
<p><pre>
manpageseealso()
</pre>

<p>followed by a list of related manual pages.
<p><li> The diagnostics are described following
<p><pre>
manpagediagnostics()
</pre>

<p>Diagnostics can state, e.g., what error messages are produced by the
    program and what the cure is.
<p><li> Next, known bugs can be described following
<p><pre>
manpagebugs()
</pre>

<p>This section is optional.
<p><li> Finally the author is stated after
<p><pre>
manpageauthor()
</pre>

<p></ol>
<p>The <code>manpage</code> document type <strong>requires</strong> 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 
(<code>sect</code>, <code>subsect</code> etc.) are not allowed in a <code>manpage</code>. You <em>can</em>
however insert other sections in the manual page with the macro
<code>manpagesection</code>. 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'.
<p>As an example, the manual page for the <code>yodl</code> program follows (the actual 
manual page may differ):
<p><pre>
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)

</pre>

<p>)
<!--

if this file ./Documentation/footer.html.in is present, it is included

automatically by add-html-footer, and replaces the simple standard
footer substitutions:

 * index,
 * package name
 * package name
 * ENV:WEBMASTER,
 * ENV:WEBMASTER

-->

<hr>
Go <a href=>back</a> to index of Yodl.

<p>
Please send Yodl questions and comments to 

<a href="mailto:yodl@icce.rug.nl">
<em>yodl@icce.rug.nl</em></a>.
<p>

<!-- package Yodl Yodl -->

Please send comments on these web pages to 
<a href="mailto:(address unknown)"><em>(address unknown)</em></a>



<p>

Copyright (c) 1997, 1998, 1999 Karel Kubat and Jan Nieuwenhuizen.

<p>

Verbatim copying and distribution of this entire article is 
permitted in any medium, provided this notice is preserved.<p>

<hr><font size=-1>
This page was built from Yodl-1.31.18 by 
<address><br> &lt<a href=\"mailto:(address unknown)\">(address unknown)</a>&gt,  Wed Mar  5 04:36:20 2008 EST.</address><p></font></BODY>
</html>