Behavioral Settings Keys

This section describes configuration keys that control HeaderDoc’s general behavior, not including any output formatting or styling.

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.

compositePageName

The name of the file containing the printable HTML page (by default, CompositePage.html). Not used if classAsComposite is 1.

defaultFrameName

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

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.

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.

Note: Generally, if you are using external cross-reference files, you should be running resolveLinks manually rather than using this setting.

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

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

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

IDLLanguage

IDL files normally produce apple_ref markers with the language "idl". However, an IDL file is inherently language-neutral. This flag allows you to tell HeaderDoc to use a different language in apple_ref markers resulting from processing an IDL file.

Legal values are, in practice, any arbitrary URL-encoded string, but ideally should be valid programming languages as defined in the apple_ref specification. See Symbol Markers for HTML-Based Documentation for the specification.

General Output Style Settings

This section describes overall output style (not including CSS style sheets, which are described in General CSS Keys and Declaration CSS Keys).

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.

classAsComposite

By default, HeaderDoc splits the documentation on the right side into several files. This setting causes classes to be output in a single composite page instead.

copyrightOwner

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

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.

groupHierLimit

The maximum number of entries allowed in a list of headers, functions, and so on before gatherheaderdoc inserts jump links to particular letters within the list. If this key is absent, no letter links are inserted. If you set this key, you must also set the groupHierSubgroupLimit to a positive integer value.

groupHierSubgroupLimit

The maximum number of entries that should ideally appear in a single letter grouping. When this limit is exceeded, a new group begins as soon as an entry is reached whose first two letters differ from those of the current entry. This key is mandatory if groupHierLimit is set, and must be a positive integer.

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.

stripDotH

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

TOCFormat

Chooses the TOC format style for individual documents. Legal values are default (new style with disclosure triangles), frames (old style), or iframes (8.7 style).

This option replaces the -F flag, though that flag is still supported for now.

TOCTemplateFile

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

TOCTemplateEncoding

The encoding used by your TOC template file. The gatherHeaderDoc tool uses this to ensure that any date stamps inserted into master TOCs are in the correct encoding.

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.

General CSS Keys

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

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.

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.

Declaration CSS Keys

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

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

sets function names to be displayed in black text on a white background.

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