Configuring HeaderDoc

You can set values for some commonly altered variables. Currently, the configuration file lets you set these things:

copyrightOwner

The copyright notice that appears at the bottom of the HTML pages. Unless you specify a value, no copyright will appear.

defaultFrameName

The name of the file containing the frameset instructions (by default, index.html).

compositePageName

The name of the file containing the printable HTML page (by default, CompositePage.html).

masterTOCName

The name of the file containing the master table of contents for a series of headers (by default, masterTOC.html). (This variable is used by the gatherHeaderDoc script, and can be overridden on the command line.)

apiUIDPrefix

The prefix for named anchors in the HTML (by default, apple_ref). (In the HTML, HeaderDoc adds a self-describing named anchor near each API declaration -- for example <a name=”//apple_ref/c/func/CFArrayAppendValue”>. These can be useful for index generation and other purposes. See “Symbol Markers for HTML-based Documentation” for more information.)

ignorePrefixes

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).

htmlHeader

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 -H flag on the command line. For longer headers, use htmlHeaderFile.

htmlHeaderFile

A file containing longer HTML headers. The contents of this file will be added to each content page if you specify the -H flag on the command line.

dateFormat

A string specifying the date format to be used by HeaderDoc. A few valid examples include Y/M/D, M-D-Y, M/Y, Y.

ignorePrefixes

Specifies a list of tokens to remove from HeaderDoc markup. Generally used to remove debug macros.

HeaderDoc Styles:

These contain CSS formatting for various parts of declarations. For example:

funcNameStyle => background:#ffffff; color:#000000;

commentStyle

style for comments

preprocessorStyle

style for preprocessor directives

funcNameStyle

style for function names

stringStyle

style for strings

charStyle

style for characters ('a')

numberStyle

style for numbers

keywordStyle

style for keywords

typeStyle

style for data types

paramStyle

style for function parameters

varStyle

style for variable names

useBreadCrumbs

Controls whether HeaderDoc will insert breadcrumb links into content pages instead of adding [Top] in the TOC. Valid Values are 0 or 1.

The path leading up to the current framework must be included manually in the htmlHeader or htmlHeaderFile directive. The breadcrumb is inserted wherever

<!-- begin breadcrumb --><!-- end breadcrumb -->

appears in the htmlHeader or htmlHeaderFile content.

TOCTemplateFile

Specifies a TOC template file to use instead of the built-in TOC template. For more information, see “Creating a TOC Template File”.

HeaderDoc looks in three places for values for these variables, in this order:

1. In the script itself (see the declaration of the “%config” hash near the top of headerDoc2HTML).


2. In the home directory of the user, in Library/Preferences/com.apple.headerDoc2HTML.config


3. In a file named headerDoc2HTML.config in the same folder as the script.

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.

The format of the configuration file is this:

 key1 => value1

 key2 => value2

Configuration File Example

Listing 5-1 Sample HeaderDoc configuration file

copyrightOwner => My Great Software Company

defaultFrameName => default.html

compositePageName => PrintablePage.html

masterTOCName => TOCCentral.html

apiUIDPrefix => greatSoftware

ignorePrefixes=> CF_EXTERN|CG_EXTERN

htmlHeader=> 

dateFormat=> m/d/y

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