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 (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).
- 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:
- In the script
itself (see the declaration of the %config hash
near the top of headerDoc2HTML).
- In the home directory of the user, in Library/Preferences/com.apple.headerDoc2HTML.config
- 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
|
| htmlHeader=>
|
| dateFormat=> m/d/y
|
|
|
|
|
© 1999, 2004 Apple Computer, Inc. All Rights Reserved. (Last updated: 2004-05-27)