The document type manpage is implemented for the creation of Unix-style manual pages. A manpage document must be organized as follows:
  1. The manual page itself is defined, using the macro
    manpage(short title)
                (section)
                (date)
                (source)
                (manual)
    

    where the arguments are:

    Short title:
    This should be the program name or something similar; i.e., whatever the manpage is describing.

    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.

    Date:
    The date of release.

    Source:
    The package where the manpage belongs to.

    Manual:
    The manual to which the package belongs.

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

  2. The subject of the manpage is stated using

    manpagename(name)(short description)
    

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

  3. The synopsis is started with

    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.

  4. The description is presented using

    manpagedescription()
    

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

  5. The options may be listed following

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

  6. Necessary files are listed following

    manpagefiles()
    

  7. The `see also' entry is started with

    manpageseealso()
    

    followed by a list of related manual pages.

  8. The diagnostics are described following

    manpagediagnostics()
    

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

  9. Next, known bugs can be described following

    manpagebugs()
    

    This section is optional.

  10. Finally the author is stated after

    manpageauthor()
    

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

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)

)


Go back to index of Yodl.

Please send Yodl questions and comments to yodl@icce.rug.nl.

Please send comments on these web pages to (address unknown)

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

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


This page was built from Yodl-1.31.18 by

<(address unknown)>, Sat May 7 03:56:57 2011 UTC.