gatherHeaderDoc.pl

Introduction

The gatherHeaderDoc.pl tool (gatherheaderdoc when installed) gathers up a folder full of HTML output from headerDoc2HTML.pl (headerdoc2html) and generates a master table of contents.

This document provides API-level documentation on the tool's internals. For user documentation, see HeaderDoc User Guide.

Functions

addTopLinkToFramesetTOCs: Adds a link to the main TOC index from each of the HTML frameset files.
chooseBest: Chooses the best object for a UID.
default_template: Returns a default (minimal) TOC template.
docListFromString: Takes a string containing link requests and assembles an array of just the link requests.
generateDocSetFile: Generates an Xcode-compatible pair of DocSet XML files for this documentation set.
genTable: Generates a multi-column table of links.
getFiles: Returns a list of the HTML files in the input directory.
gethierlinkstring: Returns a link string linking to a jump destination for a given letter group within an @indexgroup group within a data type family (e.g. headers, functions, etc.).
getLinkToFramesetFrom: Returns a relative link to a destination frameset (a header, class, etc.) from the main TOC.
getLinkToFunctionFrom: Returns a relative link to a function, data type, or other non-API-owning API element (i.e. not an entire header or class).
getNameStringForLink: Returns the jump destination part of an anchor.
groupList: Returns a list of links to @indexgroup groups within the TOC.
groupsort: Sorts the names of groups.
objName: Sort helper for sorting objects by name.
pathparts: Returns the number of parts in a path.
printll: Prints a list of the keys in the "letters linked" hash for debugging purposees.
printMasterTOC: Parses the template files and writes the output indices.
relatedDocs: Takes a string containing link requests and returns a single-column table containing only the link requests.
rightframework: Returns whether the framework discussion is at the same nesting level (pathwise) as the framework UID you just read from elsewhere in that folder.
textToXML: Converts a string of text to XML (minimally).
warnRetCause: Helper function to simplify warning code used for debugging chooseBest.
XMLTokenAbstract: Returns the abstract that goes into the Tokens.xml file.

addTopLinkToFramesetTOCs

Adds a link to the main TOC index from each of the HTML frameset files.

sub addTopLinkToFramesetTOCs

chooseBest

Chooses the best object for a UID.

sub chooseBest(
    $$$)

Parameters

firstObj: The first DocReference object to compare.
secondObj: The second DocReference object to compare.
uid: The uid in question.

Discussion

Used by the doc set generation code to choose which HTML file to associate with a given apple_ref in the event of a conflict.

This is primarily used when generating manual page content because multiple manual pages often describe the same functions. In general, apple_ref tags should always be unique. Do not rely on this logic remaining as it is today.

default_template

Returns a default (minimal) TOC template.

sub default_template

docListFromString

Takes a string containing link requests and assembles an array of just the link requests.

sub docListFromString

Parameters

string: The input string.

generateDocSetFile

Generates an Xcode-compatible pair of DocSet XML files for this documentation set.

sub generateDocSetFile

Parameters

outputDir: The input/output directory.

genTable

Generates a multi-column table of links.

sub genTable

Parameters

inputstring: A pile of links, one per line.
settings: The table parameters from the template file. (These are documented in the template section of the HeaderDoc User Guide).
groupname: The @indexgroup group that this will appear under.
typename: The name of the type of the destination (e.g. header, category, ...)
isman: Set to 1 for manual pages. This causes the code to generate multiple tables, one per manual section.

getFiles

Returns a list of the HTML files in the input directory.

sub getFiles

gethierlinkstring

Returns a link string linking to a jump destination for a given letter group within an @indexgroup group within a data type family (e.g. headers, functions, etc.).

sub gethierlinkstring

Parameters

group

The @indexgroup group that this will appear under.

linkletter

A name for the letter range suitable for inclusion in an anchor's "name" attribute.

letter

The first letter of the letter range.

typename

The name of the type of the destination (e.g. header, category, ...)

optional_last

The end of the letter range. (Optional.)

If omitted, for a single-character letter, the last part of the range is omitted. For example, instead of showing "A-B", it would just show "A". If the start of the range (letter) is two characters, in which case the range is automatically assumed to end with a Z (AM-AZ, for example).

getLinkToFramesetFrom

Returns a relative link to a destination frameset (a header, class, etc.) from the main TOC.

sub getLinkToFramesetFrom

Parameters

masterTOCFile: The path of the TOC file that this will go into.
dest: The filesystem path of the destination content.
name: The name of the destination as it should appear in the human-readable text for the link.
group: The name of the group (from @indexgroup) for the destination.
typename: The name of the type of the destination (e.g. header, category, ...)

Discussion

In addition to being a link, the anchors returned may also be jump link destinations for letter groups within long sets of links. Thus, this function needs to know the name of the group that the destination is in, as well as the type (e.g. header, category...).

getLinkToFunctionFrom

Returns a relative link to a function, data type, or other non-API-owning API element (i.e. not an entire header or class).

sub getLinkToFunctionFrom

Parameters

masterTOCFile: The path of the TOC file that this will go into.
dest: The filesystem path of the destination content.
name: The name of the destination as it should appear in the human-readable text for the link.
group: The name of the group (from @indexgroup) for the destination.
typename: The name of the type of the destination (e.g. header, category, ...)

Discussion

getNameStringForLink

Returns the jump destination part of an anchor.

sub getNameStringForLink

Parameters

name: The name of the destination as it should appear in the human-readable text for the link.
group: The name of the group (from @indexgroup) for the destination.
typename: The name of the type of the destination (e.g. header, category, ...)

Discussion

Used by getLinkToFramesetFrom and getLinkToFunctionFrom.

groupList

Returns a list of links to @indexgroup groups within the TOC.

sub groupList

groupsort

Sorts the names of groups.

sub groupsort(
    @)

Parameters

@_: The names to sort.

Discussion

This forces the "Section legacy" to appear after all of the numeric man page sections when processing manual pages. For all other cases, it just does a simple sort.

objName

Sort helper for sorting objects by name.

sub objName

Parameters

obj1: Object 1.
obj2: Object 2.

pathparts

Returns the number of parts in a path.

sub pathparts

Parameters

string: The path to check.

printll

Prints a list of the keys in the "letters linked" hash for debugging purposees.

sub printll

Parameters

arrayref: A reference to the "letters linked" hash.
group: The name of the group (for printing only).

printMasterTOC

Parses the template files and writes the output indices.

sub printMasterTOC

relatedDocs

Takes a string containing link requests and returns a single-column table containing only the link requests.

sub relatedDocs

Parameters

inputstring: The input string.
field: Passed as the "settings" argument to genTable.

rightframework

Returns whether the framework discussion is at the same nesting level (pathwise) as the framework UID you just read from elsewhere in that folder.

sub rightframework

Discussion

Although not a complete guarantee, this prevents the most common cause of getting the wrong framework discussion, which is nesting multiple trees worth of HeaderDoc output inside one another and building an outer set of docs that incudes the inner set.

textToXML

Converts a string of text to XML (minimally).

sub textToXML

warnRetCause

Helper function to simplify warning code used for debugging chooseBest.

sub warnRetCause(
    $$$)

XMLTokenAbstract

Returns the abstract that goes into the Tokens.xml file.

sub XMLTokenAbstract

Discussion

This returns the abstract if there was one, stripping off any HTML tags in the process. If there is no abstract, it attempts to scrape the first paragraph from the discussion.

Globals

contentFiles: An array of all HTML files.
debugging: Always 1.
devtoolsModulesPath: Path to the Perl modules in the developer tools package.
externalXRefFiles: Storage for the externalXRefFiles config file field.
generateDocSet: Set if you pass the -d flag.
GHD::bgcolor: The background color for the built-in (default) template.
group_letters_linked: Per-group letter link status variable.
has_resolver: Indicates that an internal link resolution tool was found.
HeaderDoc::copyrightOwner: The copyright owner (from the config file).
HeaderDoc::groupHierLimit: Storage for the groupHierLimit config file field.
HeaderDoc::groupHierSubgroupLimit: Storage for the groupHierSubgroupLimit config file field.
HeaderDoc::useWhatIs: Set if you pass the -w flag.
inputDir: The diretory for input.
inputFiles: An array of HeaderDoc-generated files.
isMacOS: A 1 if MacPerl, else 0.
letters_linked: Per-output-file letter link status variable.
linktarget: Storage for the contents of the "target=..." attribute for generated links.
masterTOCFileName: The main TOC file (e.g. index.html).
noResolve: Set if -N flag is set (disable link resolution).
options: Storage for getopt().
pathSeparator: Usually a slash (/); in MacPerl, a colon(:).
skipTOC: Set if you pass the -n flag with the -d flag.
uninstalledModulesPath: Path to the Perl modules in the source directory.

contentFiles

An array of all HTML files.

my @contentFiles;

debugging

Always 1.

my $debugging = 1;

devtoolsModulesPath

Path to the Perl modules in the developer tools package.

my $devtoolsModulesPath;

externalXRefFiles

Storage for the externalXRefFiles config file field.

my $externalXRefFiles = "";

generateDocSet

Set if you pass the -d flag.

my $generateDocSet = 0;

GHD::bgcolor

The background color for the built-in (default) template.

$GHD::bgcolor = "#ffffff";

group_letters_linked

Per-group letter link status variable.

my %group_letters_linked = ();

Discussion

Used for determining whether to put in an anchor for jumping to the first two letters of a given symbol. (Only inserted the first time those two letters appear in a given .)

has_resolver

Indicates that an internal link resolution tool was found.

my $has_resolver;

HeaderDoc::copyrightOwner

The copyright owner (from the config file).

$HeaderDoc::copyrightOwner = $config{
    "copyrightOwner"
};

HeaderDoc::groupHierLimit

Storage for the groupHierLimit config file field.

$HeaderDoc::groupHierLimit = undef;

HeaderDoc::groupHierSubgroupLimit

Storage for the groupHierSubgroupLimit config file field.

$HeaderDoc::groupHierSubgroupLimit = undef;

HeaderDoc::useWhatIs

Set if you pass the -w flag.

$HeaderDoc::useWhatIs = 0;

inputDir

The diretory for input.

my $inputDir;

inputFiles

An array of HeaderDoc-generated files.

my @inputFiles;

isMacOS

A 1 if MacPerl, else 0.

my $isMacOS;

letters_linked

Per-output-file letter link status variable.

my %letters_linked = ();

Discussion

Used for determining whether to put in an anchor for jumping to the first two letters of a given symbol. (Only inserted the first time those two letters appear in a given .)