chapter_3_section_2.html [plain text]
<html>
<head>
<META NAME="Generator" CONTENT="Gutenberg">
<META NAME="GeneratorVersion" CONTENT="v103.5
">
<META http-equiv="content-type" CONTENT="text/html;charset=iso-8859-1">
<META NAME = "Copyright" CONTENT="Copyright 2004 Apple Computer, Inc. All Rights Reserved.">
<META NAME="IndexTitle" CONTENT="Running headerDoc2HTML.pl">
<TITLE>Tools: HeaderDoc User's Guide: Running headerDoc2HTML.pl</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-CH337-DontLinkElementID_47" title="Running headerDoc2HTML.pl" 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/TP30000436-TP30000502" -->Darwin<!--/a--> > <a logicalPath="//apple_ref/doc/uid/TP40001215-CH345" href="../intro/chapter_1_section_1.html#//apple_ref/doc/uid/TP40001215-CH345">HeaderDoc User's Guide</a> > <a logicalPath="//apple_ref/doc/uid/TP40001215-CH337" href="chapter_3_section_1.html#//apple_ref/doc/uid/TP40001215-CH337">Using HeaderDoc</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_3_section_1.html" target="_self">< Previous Page</a><span style="margin-left: 8px"><a href="chapter_3_section_3.html" target="_self">Next Page ></a></span>
</td>
</tr></table>
<hr>
<a name="DontLinkElementID_47" title="Running headerDoc2HTML.pl" turn_anchor="no"></a><h2>Running headerDoc2HTML.pl</h2>
<p>Once you have a header containing HeaderDoc comments, you
can run the <code>headerDoc2HTML.pl</code> script to generate
HTML output like this:</p>
<table><table cellpadding="8" width="100%" bgcolor="#F1F5F9" style="border: 1px solid #C9D1D7;"><tr><td scope="row"><table bgcolor="#F1F5F9" width="100%" border="0" cellspacing="0" cellpadding="0"><tr><td><pre><code></code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code> > headerdoc2html MyHeader.h</code></pre></td><td><code><pre></pre></code></td></tr></table></td></tr></table><br></table>
<p>This will process <code>MyHeader.h</code> and create
an output directory called <code>MyHeader</code> in the
same directory as the input file. To view the results in your web
browser, open the file<code> index.html</code> that you
find inside the output directory.</p>
<p>Instead of specifying a single input file (as above), you
can specify an input directory if you wish. HeaderDoc will process
every <code>.h</code> file in the input directory (and all
of its subdirectories), generating an output directory of HTML files
for each header that contains HeaderDoc comments.</p>
<a name="//apple_ref/doc/uid/TP40001215-CH337-DontLinkElementID_48" title="HeaderDoc Command-line Switches" turn_anchor="no"></a><a name="DontLinkElementID_48" title="HeaderDoc Command-line Switches" turn_anchor="no"></a><h3>HeaderDoc Command-line Switches</h3>
<p>HeaderDoc has a number of useful command-line switches that
alter its behavior.</p>
<p>The <tt>-C</tt> switch causes
HeaderDoc to output class contents as a composite page instead of breaking
it up into separate pages for functions, data types, and so on.</p>
<p>The <tt>-H</tt> switch turns
on inclusion of the <tt>htmlHeader</tt> line,
as specified in the configuration file.</p>
<p>The <tt>-M</tt> switch allows
you to set the section number for man pages generated with <tt>-m</tt>.
For example,</p>
<table><table cellpadding="8" width="100%" bgcolor="#F1F5F9" style="border: 1px solid #C9D1D7;"><tr><td scope="row"><table bgcolor="#F1F5F9" width="100%" border="0" cellspacing="0" cellpadding="0"><tr><td><pre><code> > headerdoc2html -m -M 3 MyHeader.h</code></pre></td><td><code><pre></pre></code></td></tr></table></td></tr></table><br></table>
<p>would generate man pages designed for section 3 of the manual.
If the <tt>-m</tt> flag is not specified,
this flag has no effect.</p>
<p>The <tt>-O</tt> switch enables
“outer name only” type parsing, in which tag names for typedefs
are not documented (for example, <tt>foo</tt> in <tt>typedef
struct foo {...} tdname;</tt>).</p>
<p>The <tt>-S</tt> switch causes
HeaderDoc to include functions and data types from the superclass in
the documentation of child classes (if they are processed at once).</p>
<p>The <tt>-X</tt> switch causes
HeaderDoc to output XML content instead of HTML.</p>
<p>The <tt>-a</tt> switch enables
column alignment in declarations.</p>
<p>The <tt>-b</tt> switch puts
HeaderDoc into “basic” mode. In this mode, numbered lists are
not automatically recognized, and embedded headerdoc comments are
not removed from declarations.</p>
<p>The <tt>-c</tt> switch allows
you to add an alternate configuration file. For example:</p>
<table><table cellpadding="8" width="100%" bgcolor="#F1F5F9" style="border: 1px solid #C9D1D7;"><tr><td scope="row"><table bgcolor="#F1F5F9" width="100%" border="0" cellspacing="0" cellpadding="0"><tr><td><pre><code> > headerdoc2html -c myCustomHeaderDocConfigFile.config MyHeader.h</code></pre></td><td><code><pre></pre></code></td></tr></table></td></tr></table><br></table>
<p>The <tt>-d</tt> switch turns
on extra debugging output.</p>
<p>The <tt>-h</tt> switch causes
HeaderDoc to output an XML file containing metadata about the HeaderDoc
output.</p>
<p>The <tt>-i</tt> switch tells
HeaderDoc to output the body of macro declarations.</p>
<p>The <tt>-l</tt> switch tells
HeaderDoc not to generate link requests in declarations.</p>
<p>The <tt>-m</tt> switch tells
HeaderDoc to generate a man page for each function found in lieu
of generating XML or HTML output.</p>
<p>The <tt>-o</tt> switch allows
you to specify another directory for the output. For example:</p>
<table><table cellpadding="8" width="100%" bgcolor="#F1F5F9" style="border: 1px solid #C9D1D7;"><tr><td scope="row"><table bgcolor="#F1F5F9" width="100%" border="0" cellspacing="0" cellpadding="0"><tr><td><pre><code> > headerdoc2html -o /tmp MyHeader.h</code></pre></td><td><code><pre></pre></code></td></tr></table></td></tr></table><br></table>
<p>The <tt>-p</tt> switch enables
the C preprocessor. Any <tt>#define</tt> with
HeaderDoc markup will affect any content that appears after it within
the same header file, and will also affect any content after the <tt>#include</tt> in
any file that includes that header file.</p>
<p>The <tt>-q</tt> switch makes
HeaderDoc operate silently.</p>
<p>The <tt>-s</tt> switch causes
HeaderDoc to enter a comment stripping mode, in which it outputs a
copy of your header file in the output directory from which all
headerdoc comments have been removed.</p>
<p>The <tt>-t</tt> switch enables
strict tagging mode, in which any function parameters not described with
an <tt>@param</tt> tag result
in a warning.</p>
<p>The <tt>-u</tt> (unsorted)
switch disables sorting of functions, data types, and so on in the
table of contents, thus preserving the original file order. Note
that if you simply want to preserve groupings, you should use the <tt>@group</tt> or <tt>@functiongroup</tt> tags
instead.</p>
<p>The <tt>-v</tt> switch outputs
version information.</p>
<p>Most of these switches can be used in combination with each
other. The obvious exceptions are <tt>-X</tt> and <tt>-m</tt> (XML
vs. man page output). If you need both XML and man page output,
you should specify the <code>-X</code> flag (XML output),
then run the scripts <code>hdxml2manxml</code> and <code>xml2man</code> to convert
the XML output to a man page yourself.</p>
<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_3_section_1.html" target="_self">< Previous Page</a><span style="margin-left: 8px"><a href="chapter_3_section_3.html" target="_self">Next Page ></a></span>
</td>
</tr></table>
<br><hr><div align="center"><p class="content_text"> <!--#if expr="0=1" -->© 1999, 2004 Apple Computer, Inc. All Rights Reserved. (<!--#endif -->Last updated: 2004-10-27<!--#if expr="0=1" -->)<!--#endif --></p></div>
<!-- start of footer -->
<!--#include virtual="/includes/framesetfooter" -->
<!-- end of footer -->
</BODY>
</html>