NaturalDocs:: Builder:: HTMLBase

A base package for all the shared functionality in NaturalDocs::Builder::HTML and NaturalDocs::Builder::FramedHTML.

Summary
A base package for all the shared functionality in NaturalDocs::Builder::HTML and NaturalDocs::Builder::FramedHTML.
These variables are shared by all instances of the package so don’t change them.
An existence hash of acceptable abbreviations.
An array of the headings of all the index sections.
An array of the HTML anchors of all the index sections.
Whether the status message “Updating CSS file...”
These variables are for the tooltip generation functions only.
A number used as part of the ID for each link that has a tooltip.
A number used as part of the ID for each tooltip.
A hash that maps the tooltip symbols to their assigned numbers.
The generated tooltip HTML.
These variables are for the menu generation functions only.
The current menu group number.
An array of the NaturalDocs::Menu::Entry objects of each group surrounding the selected menu item.
The length of the entire menu, fully expanded.
A hash of the length of each group, not including any subgroup contents.
A hash of the number of each group, as managed by menuGroupNumber.
Constants used to approximate the lengths of the menu or its groups.
The behavior of these functions is shared between HTML output formats.
Deletes the output files associated with the purged source files.
Deletes the output files associated with the purged source files.
Checks that the project’s CSS file is the same as the master CSS file, unless -s Custom is specified.
Builds and returns the HTML page title of a file.
Builds and returns the side menu of a file.
A recursive function to build a segment of the menu.
Builds and returns the main page content.
Builds a summary, either for the entire file or the current class/section.
Builds and returns the prototype as HTML.
Builds and returns the HTML footer for the page.
Builds and returns index’s content in HTML.
Returns a link in the index, complete with surrounding IEntry tags.
Builds an index file or files.
Builds a navigation bar for a page of the index.
Builds the HTML for a symbol’s tooltip and stores it in tooltipHTML.
Builds and returns the tooltips for the page in HTML.
Builds and returns a class hierarchy diagram for the passed class, if applicable.
Builds and returns a single class hierarchy entry.
Returns the JavaScript necessary to expand and collapse the menus.
Returns the JavaScript necessary to detect the browser.
Returns the JavaScript necessary to show, hide, and position tool tips.
Returns the JavaScript that will add opening browser styles if necessary.
Returns the JavaScript that will close browser styles if necessary.
Removes all or some of the output files for an index.
Returns the output file name of the source file.
Returns the output file name of the index file.
Returns the output file name of the index file, relative to other index files.
Returns a relative path between two files in the output tree and returns it in URL format.
Converts a text string to HTML.
Converts a class and symbol to a HTML symbol, meaning one that is safe to include in anchor and link tags.
Converts a block of NDMarkup to HTML.
Creates a HTML link to a symbol, if it exists.
Creates a HTML link to an e-mail address.
Returns the properties that should go in the link tag to add a tooltip to it.
Adds second spaces after the appropriate punctuation with   so they show up in HTML.
Converts certain characters to their HTML amp char equivalents.
Adds hidden breaks to symbols.
A function that finds and returns the first file entry in the menu, or undef if none.
Determines which groups should be expanded.
Resets the ToolTip Package Variables for a new page.

Package Variables

These variables are shared by all instances of the package so don’t change them.

abbreviations

my %abbreviations

An existence hash of acceptable abbreviations.  These are words that AddDoubleSpaces() won’t put a second space after when followed by period-whitespace-capital letter.  Yes, this is seriously over-engineered.

indexHeadings

my @indexHeadings

An array of the headings of all the index sections.  First is for symbols, second for numbers, and the rest for each letter.

indexAnchors

my @indexAnchors

An array of the HTML anchors of all the index sections.  First is for symbols, second for numbers, and the rest for each letter.

saidUpdatingCSSFile

my $saidUpdatingCSSFile

Whether the status message “Updating CSS file...” has been displayed.  We only want to print it once, no matter how many HTML-based targets we are building.

ToolTip Package Variables

These variables are for the tooltip generation functions only.  Since they’re reset on every call to BuildContent() and BuildIndexContent(), and are only used by them and their support functions, they can be shared by all instances of the package.

tooltipLinkNumber

my $tooltipLinkNumber

A number used as part of the ID for each link that has a tooltip.  Should be incremented whenever one is made.

tooltipNumber

my $tooltipNumber

A number used as part of the ID for each tooltip.  Should be incremented whenever one is made.

tooltipSymbolsToNumbers

my %tooltipSymbolsToNumbers

A hash that maps the tooltip symbols to their assigned numbers.

tooltipHTML

my $tooltipHTML

The generated tooltip HTML.

Menu Package Variables

These variables are for the menu generation functions only.  Since they’re reset on every call to BuildMenu() and are only used by it and its support functions, they can be shared by all instances of the package.

menuGroupNumber

my $menuGroupNumber

The current menu group number.  Each time a group is created, this is incremented so that each one will be unique.

menuSelectionHierarchy

my @menuSelectionHierarchy

An array of the NaturalDocs::Menu::Entry objects of each group surrounding the selected menu item.  First entry is the group immediately encompassing it, and each subsequent entries works its way towards the outermost group.

menuLength

my $menuLength

The length of the entire menu, fully expanded.  The value is computed from the Menu Length Constants.

menuGroupLengths

my %menuGroupLengths

A hash of the length of each group, not including any subgroup contents.  The keys are references to each groups’ NaturalDocs::Menu::Entry object, and the values are their lengths computed from the Menu Length Constants.

menuGroupNumbers

my %menuGroupNumbers

A hash of the number of each group, as managed by menuGroupNumber.  The keys are references to each groups’ NaturalDocs::Menu::Entry object, and the values are the number.

Menu Length Constants

Constants used to approximate the lengths of the menu or its groups.

MENU_TITLELENGTHThe length of the title.
MENU_SUBTITLELENGTHThe length of the subtitle.
MENU_FILELENGTHThe length of one file entry.
MENU_GROUPLENGTHThe length of one group entry.
MENU_TEXTLENGTHThe length of one text entry.
MENU_LINKLENGTHThe length of one link entry.
MENU_LENGTHLIMITThe limit of the menu’s length.  If the total length surpasses this limit, groups that aren’t required to be open to show the selection will default to closed on browsers that support it.

Implemented Interface Functions

The behavior of these functions is shared between HTML output formats.

PurgeFiles

sub PurgeFiles

Deletes the output files associated with the purged source files.

PurgeIndexes

sub PurgeIndexes #(indexes)

Deletes the output files associated with the purged source files.

Parameters

indexesAn existence hashref of the index types to purge.  The keys are the <Topic Types> or * for the general index.

EndBuild

Checks that the project’s CSS file is the same as the master CSS file, unless -s Custom is specified.

Section Functions

BuildTitle

Builds and returns the HTML page title of a file.

Parameters

sourceFileThe source file to build the title of.

Returns

The source file’s title in HTML.

BuildMenu

Builds and returns the side menu of a file.

Parameters

outputFileThe output file to build the menu for.  Does not have to be on the menu itself.
isFramedWhether the menu will appear in a frame.  If so, it assumes the <base> HTML tag is set to make links go to the appropriate frame.

Returns

The side menu in HTML.

BuildMenuSegment

A recursive function to build a segment of the menu.  Remember to reset the Menu Package Variables before calling this for the first time.

Parameters

outputFileThe output file the menu is being built for.  Does not have to be on the menu itself.
isFramedWhether the menu will be in a HTML frame or not.  Assumes that if it is, the <base> HTML tag will be set so that links are directed to the proper frame.
menuSegmentAn arrayref specifying the segment of the menu to build.  Either pass the menu itself or the contents of a group.

Returns

The array ( menuHTML, hasSelection, length ).

menuHTMLThe menu segment in HTML.
hasSelectionWhether the group or any of its subgroups contains the entry for the selected file.
groupLengthThe length of the group, not including the contents of any subgroups, as computed from the Menu Length Constants.

BuildContent

Builds and returns the main page content.

Parameters

sourceFileThe source file name.
parsedFileThe parsed source file as an arrayref of NaturalDocs::Parser::ParsedTopic objects.

Returns

The page content in HTML.

BuildSummary

Builds a summary, either for the entire file or the current class/section.

Parameters

sourceFileThe source file the summary appears in.
parsedFileA reference to the parsed source file.
indexThe index into the parsed file to start at.  If undef or zero, it builds a summary for the entire file.  If it’s the index of a class or section entry, it builds a summary for that class or section.

Returns

The summary in HTML.

BuildPrototype

Builds and returns the prototype as HTML.

Parameters

typeThe type of prototype it is.
prototypeThe prototype to format.
fileThe file the prototype was defined in.

Returns

The prototype in HTML.

BuildFooter

Builds and returns the HTML footer for the page.

BuildIndexContent

Builds and returns index’s content in HTML.

Parameters

indexAn arrayref of sections, each section being an arrayref NaturalDocs::SymbolTable::IndexElement objects.  The first section is for symbols, the second for numbers, and the rest for A through Z.
outputFileThe output file the index is going to be stored in.  Since there may be multiple files, just send the first file.

Returns

An arrayref of the index sections.  Index 0 is the symbols, index 1 is the numbers, and each following index is A through Z.  The content of each section is its HTML, or undef if there is nothing for that section.

BuildIndexLink

Returns a link in the index, complete with surrounding IEntry tags.

Parameters

nameThe text to appear for the link.
tagThe tag to apply to name.  For example, ISymbol.
classThe class of the symbol, if any.
showClassWhether the class name should be shown in parenthesis.
symbolThe symbol to link to.
fileThe source file the symbol appears in.
typeThe type of the symbol.  One of the <Topic Types>.
prototypeThe prototype of the symbol, if any.
summaryThe summary of the symbol, if any.
outputFileThe output file the link is appearing in.

Returns

The link entry, including IEntry tags.

BuildIndexFiles

Builds an index file or files.

Parameters

typeThe type the index is limited to, or undef for none.  Should be one of the <Topic Types>.
indexContentAn arrayref containing the index content.  Each entry is a section; index 0 is symbols, index 1 is numbers, and following indexes represent A through Z.
beginPageAll the content of the HTML page up to where the index content should appear.
endPageAll the content of the HTML page past where the index should appear.

Returns

The number of pages in the index.

BuildIndexNavigationBar

Builds a navigation bar for a page of the index.

Parameters

typeThe type of the index, or undef for general.  Should be one of the <Topic Types>.
pageThe page of the index the navigation bar is for.
locationsAn arrayref of the locations of each section.  Index 0 is for the symbols, index 1 for the numbers, and the rest for each letter.  The values are the page numbers where the sections are located.

BuildToolTip

Builds the HTML for a symbol’s tooltip and stores it in tooltipHTML.

Parameters

classThe target’s class, or undef for global.
symbolThe target symbol.
fileThe file the target’s defined in.
typeThe symbol type.  Should be one of the <Topic Types>.
prototypeThe target prototype, or undef for none.
summaryThe target summary, or undef for none.

Returns

If a tooltip is necessary for the link, returns the tooltip ID.  If not, returns undef.

BuildToolTips

Builds and returns the tooltips for the page in HTML.

BuildClassHierarchy

Builds and returns a class hierarchy diagram for the passed class, if applicable.

Parameters

fileThe source file.
classThe class to build the hierarchy of.

BuildClassHierarchyEntry

Builds and returns a single class hierarchy entry.

Parameters

fileThe source file.
classThe class whose hierarchy is getting built.
styleThe style to apply to the entry, such as CHParent.
linkWhether to build a link for this class or not.  When building the selected class’ entry, this should be false.

MenuToggleJavaScript

Returns the JavaScript necessary to expand and collapse the menus.

Creates the JavaScript function ToggleMenu(id).  Pass the menu group ID and it will toggle its display style between “block” and “none”.

BrowserStylesJavaScript

Returns the JavaScript necessary to detect the browser.

The JavaScript creates two variables, browserType and browserVer.  These contain the Browser Styles if the browser is detected, has JavaScript turned on, etc.  One or both may be undefined.

ToolTipsJavaScript

Returns the JavaScript necessary to show, hide, and position tool tips.

Creates the functions ShowTip(tooltipID, linkID) and HideTip(tooltipID), which toggle the tooltips’ visibility style between “visible” and “hidden”.  Tooltip elements should be hidden by default.  Each link needs to have a unique ID.

OpeningBrowserStyles

Returns the JavaScript that will add opening browser styles if necessary.

ClosingBrowserStyles

Returns the JavaScript that will close browser styles if necessary.

Support Functions

PurgeIndexFiles

Removes all or some of the output files for an index.

Parameters

typeThe index type, or undef for general.  Should be one of the <Topic Types>.
startingPageIf defined, only pages starting with this number will be removed.  Otherwise all pages will be removed.

OutputFileOf

Returns the output file name of the source file.  Will be undef if it is not a file from a valid input directory.

IndexFileOf

Returns the output file name of the index file.

Parameters

typeThe type of index, or undef if general.
pageThe page number.  Undef is the same as one.

RelativeIndexFileOf

Returns the output file name of the index file, relative to other index files.

Parameters

typeThe type of index, or undef if general.
pageThe page number.  Undef is the same as one.

MakeRelativeURL

Returns a relative path between two files in the output tree and returns it in URL format.

Parameters

baseFileThe base file in local format, not in URL format.
targetFileThe target of the link in local format, not in URL format.

Returns

The relative URL to the target.

StringToHTML

Converts a text string to HTML.  Does not apply paragraph tags or accept formatting tags.

Parameters

stringThe string to convert.

Returns

The string in HTML.

SymbolToHTMLSymbol

Converts a class and symbol to a HTML symbol, meaning one that is safe to include in anchor and link tags.  You don’t need to pass the result to ConvertAmpChars().

Parameters

classThe symbol’s class.  Set to undef if global.
symbolThe symbol’s name.

Returns

The HTML symbol string.

NDMarkupToHTML

Converts a block of NDMarkup to HTML.

Parameters

sourceFileThe source file the NDMarkup appears in.
textThe NDMarkup text to convert.
scopeThe scope the NDMarkup appears in.

Returns

The text in HTML.

BuildLink

Creates a HTML link to a symbol, if it exists.

Parameters

scopeThe scope the link appears in.
textThe link text
sourceFileThe file the link appears in.

Returns

The link in HTML, including tags.  If the link doesn’t resolve to anything, returns the HTML that should be substituted for it.

BuildEMailLink

Creates a HTML link to an e-mail address.  The address will be transparently munged to protect it (hopefully) from spambots.

Parameters

addressThe e-mail address.

Returns

The HTML e-mail link, complete with tags.

BuildToolTipLinkProperties

Returns the properties that should go in the link tag to add a tooltip to it.  Because the function accepts undef, you can call it without checking if BuildToolTip() returned undef or not.

Parameters

toolTipIDThe ID of the tooltip.  If undef, the function will return undef.

Returns

The properties that should be put in the link tag, or undef if toolTipID wasn’t specified.

AddDoubleSpaces

Adds second spaces after the appropriate punctuation with &nbsp; so they show up in HTML.  They don’t occur if there isn’t at least one space after the punctuation, so things like class.member notation won’t be affected.

Parameters

textThe text to convert.

Returns

The text with double spaces as necessary.

ConvertAmpChars

Converts certain characters to their HTML amp char equivalents.

Parameters

textThe text to convert.

Returns

The converted text.

AddHiddenBreaks

Adds hidden breaks to symbols.  Puts them after symbol and directory separators so long names won’t screw up the layout.

Parameters

stringThe string to break.

Returns

The string with hidden breaks.

FindFirstFile

A function that finds and returns the first file entry in the menu, or undef if none.

ExpandMenu

Determines which groups should be expanded.

Parameters

outputFileThe file the menu is being built for.  Does not have to be on the menu itself.
rootLengthThe length of the menu’s root group, not including the contents of subgroups.

Returns

An arrayref of all the group numbers that should be expanded.  At minimum, it will contain the numbers of the groups present in menuSelectionHierarchy, though it may contain more.

ResetToolTips

Resets the ToolTip Package Variables for a new page.

Parameters

samePageSet this flag if there’s the possibility that the next batch of tooltips may be on the same page as the last.
A base class for all Builder output formats.
A package that generates output in HTML with frames.
A package that generates output in HTML.
my %abbreviations
An existence hash of acceptable abbreviations.
my @indexHeadings
An array of the headings of all the index sections.
my @indexAnchors
An array of the HTML anchors of all the index sections.
my $saidUpdatingCSSFile
Whether the status message “Updating CSS file...”
my $tooltipLinkNumber
A number used as part of the ID for each link that has a tooltip.
my $tooltipNumber
A number used as part of the ID for each tooltip.
my %tooltipSymbolsToNumbers
A hash that maps the tooltip symbols to their assigned numbers.
my $tooltipHTML
The generated tooltip HTML.
my $menuGroupNumber
The current menu group number.
my @menuSelectionHierarchy
An array of the NaturalDocs::Menu::Entry objects of each group surrounding the selected menu item.
A class representing an entry in the menu.
my $menuLength
The length of the entire menu, fully expanded.
my %menuGroupLengths
A hash of the length of each group, not including any subgroup contents.
my %menuGroupNumbers
A hash of the number of each group, as managed by menuGroupNumber.
sub PurgeFiles
Deletes the output files associated with the purged source files.
sub PurgeIndexes #(indexes)
Deletes the output files associated with the purged source files.
An entry in the index.
A markup format used by the parser, both internally and in NaturalDocs::Parser::ParsedTopic objects.
These variables are for the tooltip generation functions only.
Adds second spaces after the appropriate punctuation with &nbsp; so they show up in HTML.
Builds and returns the main page content.
Builds and returns index’s content in HTML.
Builds and returns the side menu of a file.
Constants used to approximate the lengths of the menu or its groups.
These variables are for the menu generation functions only.
A class for parsed topics of source files.
A class representing part of an indexed symbol.
The entry symbol.
The style for a parent class.
Natural Docs pages include JavaScript to detect which browser the user is running and apply styles so that you can work around browser quirks right in the CSS file.
Converts certain characters to their HTML amp char equivalents.
Builds the HTML for a symbol’s tooltip and stores it in tooltipHTML.