Basic HeaderDoc Configuration

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.

classAsComposite

By default, HeaderDoc generates class documentation in a way that matches

appleTOC

Specifies the Apple TOC format. This format requires extensive JavaScript and CSS support, and thus is not very useful outside of the developer.apple.com website. It is documented only for completeness.

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

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). While this feature still exists, it is usually better to use C preprocessor directives.

htmlFooter

A string (generally a server-side include directive) that HeaderDoc will insert into the bottom of each right-side and composite HTML page if you specify the -H flag on the command line. For longer headers, use htmlFooterFile.

htmlFooterFile

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

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 a longer HTML header. The contents of this file will be added at the top of each content page if you specify the -H flag on the command line.

useBreadcrumbs

Setting this option to 1 tells HeaderDoc that you intend to use an external tool to create breadcrumb links in your documents. When you specify this option, it disables the insertion of the “[Top]“ link in the table of contents, since it is not necessary if you have such a tool. Because such breadcrumbs are site-specific, no such tools are provided as part of HeaderDoc.

stripDotH

This option causes gatherHeaderDoc to strip the trailing .h from the names of header filenames in header lists.

dateFormat

A string specifying the date format to be used by HeaderDoc. This date format is specified using standard time formatting flags. For examples of valid date formats, see the man page for strftime.

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;

charStyle

style for characters ('a')

commentStyle

style for comments

funcNameStyle

style for function names

keywordStyle

style for keywords

numberStyle

style for numbers

paramStyle

style for function parameters

preprocessorStyle

style for preprocessor directives

stringStyle

style for strings

textStyle

style for normal text if declarations (mainly parentheses, punctuation, and spaces)

typeStyle

style for data types

varStyle

style for variable names

styleSheetExtrasFile

A file containing local headerdoc-specific CSS. The contents of the file specified will be inserted at the end of the built-in HeaderDoc styles (after any styles specified by the HeaderDoc declaration styles, such as varStyle).

Note: This option is the only style sheet option that does not disable the built-in HeaderDoc styles.

externalStyleSheets

A space-separated list of paths to external style sheet files on the server or destination volume. For example, if you set externalStyleSheets to /CSS/mysheet.css, HeaderDoc will insert the following:

<link rel="stylesheet" type="text/css" href="/CSS/mysheet.css">

These style sheets are inserted prior to any HeaderDoc-generated styles.

Note: Using this option disables the built-in HeaderDoc styles. For your convenience, these built-in styles are listed in “Built-in HeaderDoc Styles.”

externalTOCStyleSheets

Like externalStyleSheets, this is a space-separated list of paths to external style sheet files on the server or destination volume. If no TOC style sheets are specified, the style sheets specified in externalStyleSheets will be used.

Note: Using this option disables the built-in HeaderDoc styles. For your convenience, these built-in styles are listed in “Built-in HeaderDoc Styles.”

styleImports

A string of CSS to be inserted just prior to headerdoc-generated CSS, but after any external style sheets. This was originally intended to support the @import directive to import an external style sheet, but may be used for any CSS content.

Note: Using this option disables the built-in HeaderDoc styles. For your convenience, these built-in styles are listed in “Built-in HeaderDoc Styles.”

tocStyleImports

Similar to styleImports, this is a string of CSS to be inserted just prior to headerdoc-generated CSS, but after any external style sheets. This was originally intended to support the @import directive to import an external style sheet, but may be used for any CSS content.

If no TOC style imports are specified, the value of styleImports will be used for the TOC.

Note: Using this option disables the built-in HeaderDoc styles. For your convenience, these built-in styles are listed in “Built-in HeaderDoc Styles.”

TOCTemplateFile

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

externalXRefFiles

A space-separated list of paths to external files, each of which contains a list of cross references outside the current document. When gatherHeaderDoc runs resolveLinks to link together cross-referenced content, it passes these external cross-reference files to resolveLinks so that you can look up API references (apple_ref-style markup) in other documents.

For more information, see “Symbol Markers for HTML-Based Documentation.”

externalAPIUIDPrefixes

A space-separated list of prefixes for API references. When gatherHeaderDoc runs resolveLinks, it passes this list of prefixes to resolveLinks. This allows you to use (multiple) API reference prefixes other than apple_ref.

For more information, see “Symbol Markers for HTML-Based Documentation.”

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

Listing 3-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

Built-in HeaderDoc Styles

Many of the CSS options in HeaderDoc disable the built-in styles so that it is easier to override those styles in external style sheets. The built-in styles are listed below for your convenience.

Listing 3-2  Built-in HeaderDoc CSS Styles

a:link {text-decoration: none; font-family: lucida grande, geneva, helvetica, arial, sans-serif; font-size: small; color: #0000ff;}

a:visited {text-decoration: none; font-family: lucida grande, geneva, helvetica, arial, sans-serif; font-size: small; color: #0000ff;}

a:visited:hover {text-decoration: underline; font-family: lucida grande, geneva, helvetica, arial, sans-serif; font-size: small; color: #ff6600;}

a:active {text-decoration: none; font-family: lucida grande, geneva, helvetica, arial, sans-serif; font-size: small; color: #ff6600;}

a:hover {text-decoration: underline; font-family: lucida grande, geneva, helvetica, arial, sans-serif; font-size: small; color: #ff6600;}

h4 {text-decoration: none; font-family: lucida grande, geneva, helvetica, arial, sans-serif; font-size: tiny; font-weight: bold;}

body {text-decoration: none; font-family: lucida grande, geneva, helvetica, arial, sans-serif; font-size: 10pt;}