chapter_6_section_1.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: Configuring HeaderDoc</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-CH348" title="Configuring HeaderDoc" turn_anchor="yes"></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> > </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="../mpgl/chapter_5_section_5.html" target="_self">< Previous Page</a><span style="margin-left: 8px"><a href="../anchors/chapter_7_section_1.html" target="_self">Next Page ></a></span>
</td>
</tr></table>
<hr>
<a name="//apple_ref/doc/uid/TP40001215-CH348-CEGJFJIB" turn_anchor="no"></a><a name="CEGJFJIB" turn_anchor="no"></a><h1 class="page_title">Configuring HeaderDoc</h1><p>You can set values for some commonly altered
variables. Currently, the configuration file lets you set these
things:</p>
<dl class="content_text"><br><dt class="content_text"><b>copyrightOwner</b></dt>
<dd class="content_text">The copyright notice that appears at the bottom of the
HTML pages. Unless you specify a value, no copyright will appear.</dd>
<br><dt class="content_text"><b>defaultFrameName</b></dt>
<dd class="content_text">The name of the file containing the frameset instructions
(by default, <tt>index.html</tt>).</dd>
<br><dt class="content_text"><b>compositePageName</b></dt>
<dd class="content_text">The name of the file containing the printable HTML page
(by default, <tt>CompositePage.html</tt>).</dd>
<br><dt class="content_text"><b>masterTOCName</b></dt>
<dd class="content_text">The name of the file containing the master table of
contents for a series of headers (by default, <tt>masterTOC.html</tt>).
(This variable is used by the gatherHeaderDoc script, and can be
overridden on the command line.)</dd>
<br><dt class="content_text"><b>apiUIDPrefix</b></dt>
<dd class="content_text">The prefix for named anchors (by default, <tt>apple_ref</tt>).
In the output, HeaderDoc adds a self-describing named anchor near
each API declaration—for example <tt><a name=”These can be useful for index generation and other purposes. See <span class="content_text"><a logicalPath="//apple_ref/doc/uid/TP40001215-CH347-BABJIFFD" href="../anchors/chapter_7_section_1.html#//apple_ref/doc/uid/TP40001215-CH347-BABJIFFD">“Symbol Markers for HTML-Based Documentation”</a></span> for more information.</dd>
<br><dt class="content_text"><b>ignorePrefixes</b></dt>
<dd class="content_text">A list of tokens to leave out of the final output if
they occur at the start of a line (before any other non-whitespace
characters).</dd>
<br><dt class="content_text"><b>htmlHeader</b></dt>
<dd class="content_text">A string (generally a server-side include directive)
that HeaderDoc will insert into the top of each right-side and composite
HTML page if you specify the <tt>-H</tt> flag
on the command line. For longer headers, use <tt>htmlHeaderFile</tt>.</dd>
<br><dt class="content_text"><b>htmlHeaderFile</b></dt>
<dd class="content_text">A file containing longer HTML headers. The contents
of this file will be added to each content page if you specify the <tt>-H</tt> flag
on the command line.</dd>
<br><dt class="content_text"><b>dateFormat</b></dt>
<dd class="content_text">A string specifying the date format to be used by HeaderDoc.
A few valid examples include <tt>Y/M/D</tt>, <tt>M-D-Y</tt>, <tt>M/Y</tt>, <tt>Y</tt>. </dd>
<br><dt class="content_text"><b>ignorePrefixes</b></dt>
<dd class="content_text">Specifies a list of tokens to remove from HeaderDoc
markup. Generally used to remove debug macros.</dd>
<br><dt class="content_text"><b>HeaderDoc Styles:</b></dt>
<dd class="content_text">These contain CSS formatting for various parts of declarations.
For example:<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>funcNameStyle => background:#ffffff; color:#000000;</code></pre></td><td><code><pre></pre></code></td></tr></table></td></tr></table></table><dl class="content_text">
<br><dt class="content_text"><b>commentStyle</b></dt>
<dd class="content_text">style for comments</dd>
<br><dt class="content_text"><b>preprocessorStyle</b></dt>
<dd class="content_text">style for preprocessor directives</dd>
<br><dt class="content_text"><b>funcNameStyle</b></dt>
<dd class="content_text">style for function names</dd>
<br><dt class="content_text"><b>stringStyle</b></dt>
<dd class="content_text">style for strings</dd>
<br><dt class="content_text"><b>charStyle</b></dt>
<dd class="content_text">style for characters ('a')</dd>
<br><dt class="content_text"><b>numberStyle</b></dt>
<dd class="content_text">style for numbers</dd>
<br><dt class="content_text"><b>keywordStyle</b></dt>
<dd class="content_text">style for keywords</dd>
<br><dt class="content_text"><b>typeStyle</b></dt>
<dd class="content_text">style for data types</dd>
<br><dt class="content_text"><b>paramStyle</b></dt>
<dd class="content_text">style for function parameters</dd>
<br><dt class="content_text"><b>varStyle</b></dt>
<dd class="content_text">style for variable names</dd></dl></dd>
<br><dt class="content_text"><b>useBreadCrumbs</b></dt>
<dd class="content_text">Controls whether HeaderDoc will insert breadcrumb links
into content pages instead of adding [Top] in the TOC. Valid Values
are 0 or 1.<p>The path leading up to the current framework must
be included manually in the <tt>htmlHeader</tt> or <tt>htmlHeaderFile</tt> directive.
The breadcrumb is inserted wherever</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><!-- begin breadcrumb --><!-- end breadcrumb --></code></pre></td><td><code><pre></pre></code></td></tr></table></td></tr></table></table><p>appears in
the <tt>htmlHeader</tt> or <tt>htmlHeaderFile</tt> content.</p></dd>
<br><dt class="content_text"><b>TOCTemplateFile</b></dt>
<dd class="content_text">Specifies a TOC template file to use instead of the
built-in TOC template. For more information, see <span class="content_text"><a logicalPath="//apple_ref/doc/uid/TP40001215-CH350-BABHAEAC" href="../gatherheaderdoc/chapter_4_section_3.html#//apple_ref/doc/uid/TP40001215-CH350-BABHAEAC">“Creating a TOC Template File”</a></span>.</dd></dl>
<p>HeaderDoc looks in three places for values for these variables,
in this order:</p>
<ol class="content_text"><li class="content_text">In the script
itself (see the declaration of the <tt>%config</tt> hash
near the top of <tt>headerDoc2HTML</tt>).</li><br>
<li class="content_text">In the home directory of the user, in <tt>Library/Preferences/com.apple.headerDoc2HTML.config</tt></li><br>
<li class="content_text">In a file named <tt>headerDoc2HTML.config</tt> in
the same folder as the script. </li><br></ol>
<p>A variable can be assigned a value in any of these places,
but only the last value read for a given variable will affect the
output of a run of the script. If you are happy with the default values
for these variables (as described above), you don't need to provide
a configuration file. If you want to change just one or more values,
provide a configuration file that declares just those values. </p>
<p>The format of the configuration file is 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> key1 => value1</code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code> key2 => value2</code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code></code></pre></td><td><code><pre></pre></code></td></tr></table></td></tr></table></table>
<br><h2>Configuration
File Example</h2>
<p><span class="content_text"><a logicalPath="//apple_ref/doc/uid/TP40001215-CH348-BABHFGII" href="chapter_6_section_1.html#//apple_ref/doc/uid/TP40001215-CH348-BABHFGII">Listing 1-1</a></span> is an example of a very basic HeaderDoc configuration
file. Several additional examples are included as part of the HeaderDoc
distribution.</p>
<table><a name="//apple_ref/doc/uid/TP40001215-CH348-BABHFGII" turn_anchor="no"></a><a name="BABHFGII" turn_anchor="no"></a><p><b><font face="lucida grande, geneva, helvetica, arial, sans-serif" size="2">Listing 6-1 Sample HeaderDoc configuration file</font></b></p>
<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>copyrightOwner => My Great Software Company</code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code>defaultFrameName => default.html</code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code>compositePageName => PrintablePage.html</code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code>masterTOCName => TOCCentral.html</code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code>apiUIDPrefix => greatSoftware</code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code>ignorePrefixes=> CF_EXTERN|CG_EXTERN</code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code>htmlHeader=> </code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code>dateFormat=> m/d/y</code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code></code></pre></td><td><code><pre></pre></code></td></tr></table></td></tr></table></table>
<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) {
// loaded in frames
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 {
// not loaded frames
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>');
}
//--></script>
<!-- end Show/Hide frames -->
</td><td align=right>
<a href="../mpgl/chapter_5_section_5.html" target="_self">< Previous Page</a><span style="margin-left: 8px"><a href="../anchors/chapter_7_section_1.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>