HeaderDoc Unfettered: Configuring HeaderDoc

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