< Previous PageNext Page >

Configuring HeaderDoc

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

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

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

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

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

The prefix for named anchors (by default, apple_ref). In the output, 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.

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

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.

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.

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.

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;

style for comments

style for preprocessor directives

style for function names

style for strings

style for characters ('a')

style for numbers

style for keywords

style for data types

style for function parameters

style for variable names

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.

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 1-1 is an example of a very basic HeaderDoc configuration file. Several additional examples are included as part of the HeaderDoc distribution.

Listing 6-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
dateFormat=> m/d/y

< Previous PageNext Page >

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