chapter_5_section_2.html [plain text]
<html>
<head>
<META NAME="Generator" CONTENT="Gutenberg">
<META NAME="GeneratorVersion" CONTENT="v100.1">
<META http-equiv="content-type" CONTENT="text/html;charset=iso-8859-1">
<META NAME = "Copyright" CONTENT="Copyright 2004 Apple Computer, Inc. All Rights Reserved.">
<TITLE>Tools: HeaderDoc Unfettered: Man Page Generation Language (MPGL) Dialect</TITLE>
<base target="content">
<LINK REL="stylesheet" TYPE="text/css" HREF="../Resources/CSS/frameset_styles.css">
<style type="text/css"></style>
<script language="JavaScript" src="../Resources/JavaScript/page.js"></script>
</head>
<BODY bgcolor="#ffffff" onload="initialize_page();"><a name="//apple_ref/doc/uid/TP40001215-CH357-DontLinkElementID_1082" title="Man Page Generation Language (MPGL) Dialect" turn_anchor="no"></a>
<a name="top"></a>
<!-- start of header -->
<!--#include virtual="/includes/framesetheader" -->
<!-- end of header -->
<!-- start of path -->
<div class="breadcrumb"><a href="http://developer.apple.com/" target="_top">ADC Home</a> > <!--a logicalPath="//apple_ref/doc/uid/TP30000943" -->Reference Library<!--/a--> > <!--a logicalPath="//apple_ref/doc/uid/TP30000440" -->Documentation<!--/a--> > <!--a logicalPath="//apple_ref/doc/uid/TP30000436" -->Tools<!--/a--> > <a logicalPath="//apple_ref/doc/uid/TP40001215-CH345" href="../intro/chapter_1_section_1.html#//apple_ref/doc/uid/TP40001215-CH345">HeaderDoc Unfettered</a> > <a logicalPath="//apple_ref/doc/uid/TP40001215-CH357" href="chapter_5_section_1.html#//apple_ref/doc/uid/TP40001215-CH357">Using the MPGL Suite</a> > </div><br>
<!-- end of path -->
<table width="100%" cellpadding=0 cellspacing=0 border=0 class="mini_nav_text"><tr>
<td align=left scope="row">
<!-- insert Show/Hide frames -->
<script type="text/javascript" language="JavaScript"><!--
if (self != top) {
document.write('<a href="'+self.location+'" target="_top"><img src="../Resources/Images/show_toc_icon.gif" width="15" height="14" border="0" style="margin-bottom: -2px;" alt=""></a> <a href="'+self.location+'" target="_top">Hide TOC</a>');
}
else {
document.write('<a href="../index.html?'+self.location+'" target="_top"><img src="../Resources/Images/show_toc_icon.gif" width="15" height="14" border="0" style="margin-bottom: -2px;" alt=""></a> <a href="../index.html?'+self.location+'" target="_top">Show TOC</a>');
}
<!-- end Show/Hide frames -->
</td><td align=right>
<a href="chapter_5_section_1.html" target="_self">< Previous Page</a><span style="margin-left: 8px"><a href="chapter_5_section_3.html" target="_self">Next Page ></a></span>
</td>
</tr></table>
<hr>
<br><h2>Man Page Generation Language
(MPGL) Dialect</h2>
<p>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.</p><div class="notebox"><span class="content_text"><b>Note: </b>Many
versions of <tt>man</tt> are exceptionally
picky about blank lines. While the <tt>xml2man</tt> translator
attempts to remove most of these, you should still avoid leaving
blank lines in the input files.</span></div>
<p>The MPGL syntax includes a subset of mdoc. All text is unjustified,
and some redundancy was reduced. In particular, the <tt>usage</tt> 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.</p>
<p>At the top level (within the outer <tt><manpage></tt> tag),
an MPGL page consists of some or all of the following large blocks:</p>
<b><font face="lucida grande, geneva, helvetica, arial, sans-serif" size="2">Table 5-1 MPGL
block tags</font></b><br><br><table border = "1" cellpadding = "3">
<tr>
<th scope="col"><div align="left"><b><p>Block tag</p></b></div></th>
<th scope="col"><div align="left"><b><p>Description</p></b></div></th>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><docdate></tt></p></td>
<td class="content_text"><p>the last modified date of the manual page</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><doctitle></tt></p></td>
<td class="content_text"><p>the title of the manual page</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><os></tt></p></td>
<td class="content_text"><p>the operating system for which the manual page was written</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><section></tt></p></td>
<td class="content_text"><p>the man section in which the manual pages should appear</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><names></tt></p></td>
<td class="content_text"><p>names and descriptions of functions or tools described
in this manual page (see example for syntax) </p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><usage></tt></p></td>
<td class="content_text"><p>command-line usage or function parameters (see example
for syntax)</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><returnvalues></tt></p></td>
<td class="content_text"><p>function return value (text description)</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><environment></tt></p></td>
<td class="content_text"><p>interaction with environment variables</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><files></tt></p></td>
<td class="content_text"><p>files used by a command-line tool</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><examples></tt></p></td>
<td class="content_text"><p>usage examples</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><b><tt><diagnostics></tt></b></p></td>
<td class="content_text"><p>troubleshooting information</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><errors></tt></p></td>
<td class="content_text"><p>function error values (generally restricted to those
returned via the <tt>errno</tt> global
variable)</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><seealso></tt></p></td>
<td class="content_text"><p>cross-references to other manual pages (see example)</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><conformingto></tt></p></td>
<td class="content_text"><p>standards to which a tool or function conforms.</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><history></tt></p></td>
<td class="content_text"><p>historical information</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><bugs></tt></p></td>
<td class="content_text"><p>known bugs in a tool or function</p></td>
</tr>
</table><br>
<p>Any field can contain either a block of raw text or the following
subset of XHTML:</p><b><font face="lucida grande, geneva, helvetica, arial, sans-serif" size="2">Table 5-2 XHTML
tags supported by MPGL</font></b><br><br><table border = "1" cellpadding = "3">
<tr>
<th scope="col"><div align="left"><b><p>XHTML tag</p></b></div></th>
<th scope="col"><div align="left"><b><p>Description</p></b></div></th>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><p></tt></p></td>
<td class="content_text"><p>paragraph</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><blockquote></tt></p></td>
<td class="content_text"><p>indented block</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><tt></tt></p></td>
<td class="content_text"><p>indented literal text or code</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><ul></tt></p></td>
<td class="content_text"><p>unordered (bullet) list</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><ol></tt></p></td>
<td class="content_text"><p>ordered (numbered) list</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><li></tt></p></td>
<td class="content_text"><p>list item (within a list)</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><code></tt></p></td>
<td class="content_text"><p>literal text</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><dl></tt></p></td>
<td class="content_text"><p>term and definition list</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><dt></tt></p></td>
<td class="content_text"><p>term (within a term and definition list)</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><dd></tt></p></td>
<td class="content_text"><p>definition (within a term and definition list)</p></td>
</tr>
</table><br>
<p>Any field can also contain any of the following MPGL-specific
inline tags:</p><b><font face="lucida grande, geneva, helvetica, arial, sans-serif" size="2">Table 5-3 Additional
MPGL-specific inline tags</font></b><br><br><table border = "1" cellpadding = "3">
<tr>
<th scope="col"><div align="left"><b><p>Tag</p></b></div></th>
<th scope="col"><div align="left"><b><p>Description</p></b></div></th>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><path></tt></p></td>
<td class="content_text"><p>path name</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><function></tt></p></td>
<td class="content_text"><p>function name</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><command></tt></p></td>
<td class="content_text"><p>command name</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt><manpage></tt></p></td>
<td class="content_text"><p>man page cross-reference (see example)</p></td>
</tr>
</table><br>
<br><br>
<table width="100%" cellpadding=0 cellspacing=0 border=0 class="mini_nav_text"><tr>
<td align=left scope="row">
<!-- insert Show/Hide frames -->
<script type="text/javascript" language="JavaScript"><!--
if (self != top) {
document.write('<a href="'+self.location+'" target="_top"><img src="../Resources/Images/show_toc_icon.gif" width="15" height="14" border="0" style="margin-bottom: -2px;" alt=""></a> <a href="'+self.location+'" target="_top">Hide TOC</a>');
}
else {
document.write('<a href="../index.html?'+self.location+'" target="_top"><img src="../Resources/Images/show_toc_icon.gif" width="15" height="14" border="0" style="margin-bottom: -2px;" alt=""></a> <a href="../index.html?'+self.location+'" target="_top">Show TOC</a>');
}
<!-- end Show/Hide frames -->
</td><td align=right>
<a href="chapter_5_section_1.html" target="_self">< Previous Page</a><span style="margin-left: 8px"><a href="chapter_5_section_3.html" target="_self">Next Page ></a></span>
</td>
</tr></table>
<br><hr><p class="content_text"> <!--#if expr="0=1" -->© 1999, 2004 Apple Computer, Inc. All Rights Reserved. (<!--#endif -->Last updated: 2004-05-27<!--#if expr="0=1" -->)<!--#endif --></p>
<!-- start of footer -->
<!--#include virtual="/includes/framesetfooter" -->
<!-- end of footer -->
</BODY>
</html>