< Previous PageNext Page >


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)




< Previous PageNext Page >


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