Tools: HeaderDoc User's Guide: Man Page Generation Language (MPGL) Dialect

## Man Page Generation Language (MPGL) Dialect

This section describes the basic syntax of the Man Page Generation Language (MPGL). Portions of the syntax are abridged due to complexity. For information on these details, see the examples later in this chapter.

Note: Many versions of `man` are exceptionally picky about blank lines. While the `xml2man` translator attempts to remove most of these, you should still avoid leaving blank lines in the input files.

The MPGL syntax includes a subset of mdoc. All text is unjustified, and some redundancy was reduced. In particular, the `usage` section in an MPGL file provides the source information for both the Synopsis and Description sections of a traditional man page. Beyond those changes, if you are familiar with the mdoc macro set, you should feel right at home.

At the top level (within the outer `<manpage>` tag), an MPGL page consists of some or all of the following large blocks:

Table 5-1 : MPGL block tags

Block tag | Description
--- | ---
`<docdate>` | the last modified date of the manual page
`<doctitle>` | the title of the manual page
`<os>` | the operating system for which the manual page was written
`<section>` | the man section in which the manual pages should appear
`<names>` | names and descriptions of functions or tools described in this manual page (see example for syntax)
`<usage>` | command-line usage or function parameters (see example for syntax)
`<returnvalues>` | function return value (text description)
`<environment>` | interaction with environment variables
`<files>` | files used by a command-line tool
`<examples>` | usage examples
`<diagnostics>` | troubleshooting information
`<errors>` | function error values (generally restricted to those returned via the `errno` global variable)
`<seealso>` | cross-references to other manual pages (see example)
`<conformingto>` | standards to which a tool or function conforms.
`<history>` | historical information
`<bugs>` | known bugs in a tool or function

Any field can contain either a block of raw text or the following subset of XHTML:

Table 5-2 : XHTML tags supported by MPGL

XHTML tag | Description
--- | ---
`<p>` | paragraph
`<blockquote>` | indented block
`<tt>` | indented literal text or code
`<ul>` | unordered (bullet) list
`<ol>` | ordered (numbered) list
`<li>` | list item (within a list)
`<code>` | literal text
`<dl>` | term and definition list
`<dt>` | term (within a term and definition list)
`<dd>` | definition (within a term and definition list)

Any field can also contain any of the following MPGL-specific inline tags:

Table 5-3 : Additional MPGL-specific inline tags

Tag | Description
--- | ---
`<path>` | path name
`<function>` | function name
`<command>` | command name
`<manpage>` | man page cross-reference (see example)

© 1999, 2004 Apple Computer, Inc. All Rights Reserved. (Last updated: 2004-10-27)