NaturalDocs::Builder::HTMLBase

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

Summary
NaturalDocs::Builder::HTMLBaseA base package for all the shared functionality in NaturalDocs::Builder::HTML and NaturalDocs::Builder::FramedHTML.
Object Variables
MembersThe object is implemented as a blessed arrayref, with the follow constants as indexes.
NDMarkupToHTML StylesThese are the styles used with NDMarkupToHTML().
Package VariablesThese variables are shared by all instances of the package so don’t change them.
FH_CSS_FILEThe file handle to use when updating CSS files.
abbreviationsAn existence hash of acceptable abbreviations.
indexHeadingsAn array of the headings of all the index sections.
indexAnchorsAn array of the HTML anchors of all the index sections.
searchExtensionsAn array of the search file name extensions for all the index sections.
saidUpdatingCSSFileWhether the status message “Updating CSS file...”
ADD_HIDDEN_BREAKSJust a synonym for “1” so that setting the flag on StringToHTML() is clearer in the calling code.
ToolTip Package VariablesThese variables are for the tooltip generation functions only.
tooltipLinkNumberA number used as part of the ID for each link that has a tooltip.
tooltipNumberA number used as part of the ID for each tooltip.
tooltipSymbolsToNumbersA hash that maps the tooltip symbols to their assigned numbers.
tooltipHTMLThe generated tooltip HTML.
Menu Package VariablesThese variables are for the menu generation functions only.
prebuiltMenusA hash that maps output directonies to menu HTML already built for it.
menuNumbersAndLengthsDoneSet when the variables that only need to be calculated for the menu once are done.
menuGroupNumberThe current menu group number.
menuLengthThe length of the entire menu, fully expanded.
menuGroupLengthsA hash of the length of each group, not including any subgroup contents.
menuGroupNumbersA hash of the number of each group, as managed by menuGroupNumber.
menuRootLengthThe length of the top-level menu entries without expansion.
Menu Length ConstantsConstants used to approximate the lengths of the menu or its groups.
Image Package VariablesThese variables are for the image generation functions only.
imageAnchorNumberIncremented for each image link in the file that requires an anchor.
imageContentThe actual embedded image HTML for all image links.
Search Package VariablesThese variables are for the search generation functions only.
searchResultIDsA hash mapping lowercase-only search result IDs to the number of times they’ve been used.
Object Functions
NewCreates and returns a new object.
MadeEmptySearchResultsPageReturns whether the empty search results page was created or not.
SetMadeEmptySearchResultsPageSets whether the empty search results page was created or not.
Implemented Interface FunctionsThe behavior of these functions is shared between HTML output formats.
UpdateImageDefine this function to add or update the passed image in the output.
PurgeFilesDeletes the output files associated with the purged source files.
PurgeIndexesDeletes the output files associated with the purged source files.
PurgeImagesDefine this function to make the package remove all output related to the passed image files.
BeginBuildCreates the necessary subdirectories in the output directory.
EndBuildSynchronizes the projects CSS and JavaScript files.
Section Functions
BuildTitleBuilds and returns the HTML page title of a file.
BuildMenuBuilds and returns the side menu of a file.
BuildMenuSegmentA recursive function to build a segment of the menu.
BuildContentBuilds and returns the main page content.
BuildSummaryBuilds a summary, either for the entire file or the current class/section.
BuildPrototypeBuilds and returns the prototype as HTML.
BuildFooterBuilds and returns the HTML footer for the page.
BuildToolTipBuilds the HTML for a symbol’s tooltip and stores it in tooltipHTML.
BuildToolTipsBuilds and returns the tooltips for the page in HTML.
BuildClassHierarchyBuilds and returns a class hierarchy diagram for the passed class, if applicable.
BuildClassHierarchyEntryBuilds and returns a single class hierarchy entry.
OpeningBrowserStylesReturns the JavaScript that will add opening browser styles if necessary.
ClosingBrowserStylesReturns the JavaScript that will close browser styles if necessary.
StandardCommentsReturns the standard HTML comments that should be included in every generated file.
IEWebMarkReturns the HTML comment necessary to get around the security warnings in IE starting with Windows XP Service Pack 2.
Index Functions
BuildIndexPagesBuilds an index file or files.
BuildIndexSectionsBuilds and returns the index and search results sections in HTML.
BuildIndexElementConverts a NaturalDocs::SymbolTable::IndexElement to HTML and returns it.
BuildIndexLinkBuilds and returns the HTML associated with an index link.
BuildIndexNavigationBarBuilds a navigation bar for a page of the index.
File Functions
PurgeIndexFilesRemoves all or some of the output files for an index.
OutputFileOfReturns the output file name of the source file.
OutputImageOfReturns the output image file name of the source image file.
IndexDirectoryReturns the directory of the index files.
IndexFileOfReturns the output file name of the index file.
RelativeIndexFileOfReturns the output file name of the index file, relative to other index files.
SearchResultsDirectoryReturns the directory of the search results files.
SearchResultsFileOfReturns the output file name of the search result file.
CSSDirectoryReturns the directory of the CSS files.
MainCSSFileReturns the location of the main CSS file.
JavaScriptDirectoryReturns the directory of the JavaScript files.
MainJavaScriptFileReturns the location of the main JavaScript file.
PrettifyJavaScriptFileReturns the location of the Google Prettify JavaScript file.
SearchDataJavaScriptFileReturns the location of the search data JavaScript file.
Support Functions
IndexTitleOfReturns the page title of the index file.
MakeRelativeURLReturns a relative path between two files in the output tree and returns it in URL format.
StringToHTMLConverts a text string to HTML.
SymbolToHTMLSymbolConverts a SymbolString to a HTML symbol, meaning one that is safe to include in anchor and link tags.
StringToSearchResultIDTakes a text string and translates it into something that can be used as a CSS ID.
NDMarkupToHTMLConverts a block of NDMarkup to HTML.
BuildTextLinkCreates a HTML link to a symbol, if it exists.
BuildURLLinkCreates a HTML link to an external URL.
BuildEMailLinkCreates a HTML link to an e-mail address.
BuildImageBuilds the HTML for an image.
BuildToolTipLinkPropertiesReturns the properties that should go in the link tag to add a tooltip to it.
AddDoubleSpacesAdds second spaces after the appropriate punctuation with   so they show up in HTML.
ConvertAmpCharsConverts certain characters to their HTML amp char equivalents.
RestoreAmpCharsRestores all amp characters to their original state.
AddHiddenBreaksAdds hidden breaks to symbols.
FindFirstFileA function that finds and returns the first file entry in the menu, or undef if none.
ExpandMenuDetermines which groups should be expanded.
GetMenuSelectionHierarchyFinds the sequence of menu groups that contain the current selection.
FindMenuSelectionA recursive function that deterimes if it or any of its sub-groups has the menu selection.
ResetToolTipsResets the ToolTip Package Variables for a new page.

Object Variables

Members

The object is implemented as a blessed arrayref, with the follow constants as indexes.

MADE_EMPTY_SEARCH_RESULTS_PAGEWhether the search results page for searches with no results was generated.

NDMarkupToHTML Styles

These are the styles used with NDMarkupToHTML().

NDMARKUPTOHTML_GENERALGeneral style.
NDMARKUPTOHTML_SUMMARYFor summaries.
NDMARKUPTOHTML_TOOLTIPFor tooltips.

Package Variables

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

FH_CSS_FILE

The file handle to use when updating CSS files.

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.

searchExtensions

my @searchExtensions

An array of the search file name extensions for 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.

ADD_HIDDEN_BREAKS

Just a synonym for “1” so that setting the flag on StringToHTML() is clearer in the calling code.

ToolTip Package Variables

These variables are for the tooltip generation functions only.  Since they’re reset on every call to BuildContent() and BuildIndexSections(), 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.

prebuiltMenus

my %prebuiltMenus

A hash that maps output directonies to menu HTML already built for it.  There will be no selection or JavaScript in the menus.

menuNumbersAndLengthsDone

my $menuNumbersAndLengthsDone

Set when the variables that only need to be calculated for the menu once are done.  This includes menuGroupNumber, menuLength, menuGroupLengths, and menuGroupNumbers, and menuRootLength.

menuGroupNumber

my $menuGroupNumber

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

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.

menuRootLength

my $menuRootLength

The length of the top-level menu entries without expansion.  The value is computed from the Menu Length Constants.

Menu Length Constants

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

MENU_TITLE_LENGTHThe length of the title.
MENU_SUBTITLE_LENGTHThe length of the subtitle.
MENU_FILE_LENGTHThe length of one file entry.
MENU_GROUP_LENGTHThe length of one group entry.
MENU_TEXT_LENGTHThe length of one text entry.
MENU_LINK_LENGTHThe length of one link entry.
MENU_LENGTH_LIMITThe 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.

Image Package Variables

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

imageAnchorNumber

my $imageAnchorNumber

Incremented for each image link in the file that requires an anchor.

imageContent

my $imageContent

The actual embedded image HTML for all image links.  When generating an image link, the link HTML is returned and the HTML for the target image is added here.  Periodically, such as after the end of the paragraph, this content should be added to the page and the variable set to undef.

Search Package Variables

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

searchResultIDs

my %searchResultIDs

A hash mapping lowercase-only search result IDs to the number of times they’ve been used.  This is to work around an IE bug where it won’t correctly reference IDs if they differ only in case.

Object Functions

New

sub New

Creates and returns a new object.

MadeEmptySearchResultsPage

Returns whether the empty search results page was created or not.

SetMadeEmptySearchResultsPage

Sets whether the empty search results page was created or not.

Implemented Interface Functions

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

UpdateImage

sub UpdateImage #(file)

Define this function to add or update the passed image in the output.

Parameters

fileThe image FileName

PurgeFiles

sub PurgeFiles #(filesToPurge)

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 TopicTypes or * for the general index.

PurgeImages

sub PurgeImages #(files)

Define this function to make the package remove all output related to the passed image files.  These files are no longer used by the documentation.

Parameters

filesAn existence hashref of the image FileNames to purge.

BeginBuild

sub BeginBuild #(hasChanged)

Creates the necessary subdirectories in the output directory.

EndBuild

sub EndBuild #(hasChanged)

Synchronizes the projects CSS and JavaScript files.  Also generates the search data JavaScript file.

Section Functions

BuildTitle

sub BuildTitle #(sourceFile)

Builds and returns the HTML page title of a file.

Parameters

sourceFileThe source FileName to build the title of.

Returns

The source file’s title in HTML.

BuildMenu

sub BuildMenu #(FileName sourceFile,
TopicType indexType) -> string htmlMenu

Builds and returns the side menu of a file.

Parameters

sourceFileThe source FileName to use if you’re looking for a source file.
indexTypeThe index TopicType to use if you’re looking for an index.

Both sourceFile and indexType may be undef.

Returns

The side menu in HTML.

Dependencies

BuildMenuSegment

sub BuildMenuSegment #(outputDirectory,
menuSegment,
topLevel)

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

outputDirectoryThe output directory the menu is being built for.
menuSegmentAn arrayref specifying the segment of the menu to build.  Either pass the menu itself or the contents of a group.
topLevelWhether the passed segment is the top level segment or not.

Returns

The array ( menuHTML, length ).

menuHTMLThe menu segment in HTML.
groupLengthThe length of the group, not including the contents of any subgroups, as computed from the Menu Length Constants.

Dependencies

  • BuildMenu() depends on the way this function formats file and index entries.

BuildContent

sub BuildContent #(sourceFile,
parsedFile)

Builds and returns the main page content.

Parameters

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

Returns

The page content in HTML.

BuildSummary

sub BuildSummary #(sourceFile,
parsedFile,
index)

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

Parameters

sourceFileThe source FileName 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 TopicType that starts or ends a scope, it builds a summary for that scope

Returns

The summary in HTML.

BuildPrototype

sub BuildPrototype #(type,
prototype,
file)

Builds and returns the prototype as HTML.

Parameters

typeThe TopicType the prototype is from.
prototypeThe prototype to format.
fileThe FileName the prototype was defined in.

Returns

The prototype in HTML.

BuildFooter

sub BuildFooter #(bool multiline)

Builds and returns the HTML footer for the page.

Parameters

multilineWhether it should be formatted on multiple lines or not.

Dependencies

Builder::HTML::UpdateFile() and Builder::HTML::UpdateIndex() require this section to be surrounded with the exact strings “<div id=Footer>” and “</div><!--Footer-->”.

BuildToolTip

sub BuildToolTip #(symbol,
file,
type,
prototype,
summary)

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

Parameters

symbolThe target SymbolString.
fileThe FileName the target’s defined in.
typeThe symbol TopicType.
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

sub BuildToolTips

Builds and returns the tooltips for the page in HTML.

BuildClassHierarchy

sub BuildClassHierarchy #(file,
symbol)

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

Parameters

fileThe source FileName.
classThe class SymbolString to build the hierarchy of.

BuildClassHierarchyEntry

sub BuildClassHierarchyEntry #(file,
symbol,
style,
link)

Builds and returns a single class hierarchy entry.

Parameters

fileThe source FileName.
symbolThe class SymbolString whose entry 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.  It will automatically handle whether the symbol is defined or not.

OpeningBrowserStyles

sub OpeningBrowserStyles

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

ClosingBrowserStyles

sub ClosingBrowserStyles

Returns the JavaScript that will close browser styles if necessary.

StandardComments

sub StandardComments

Returns the standard HTML comments that should be included in every generated file.  This includes IEWebMark(), so this really is required for proper functionality.

IEWebMark

sub IEWebMark

Returns the HTML comment necessary to get around the security warnings in IE starting with Windows XP Service Pack 2.

With this mark, the HTML page is treated as if it were in the Internet security zone instead of the Local Machine zone.  This prevents the lockdown on scripting that causes an error message to appear with each page.

More Information

Index Functions

BuildIndexPages

sub BuildIndexPages #(
   TopicType type,
   NaturalDocs::SymbolTable::IndexElement[] indexSections,
   string beginIndexPage,
   string endIndexPage,
   string beginSearchResultsPage,
   string endSearchResultsPage
) => int

Builds an index file or files.

Parameters

typeThe TopicType the index is limited to, or undef for none.
indexSectionsAn 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.
beginIndexPageAll the content of the HTML page up to where the index content should appear.
endIndexPageAll the content of the HTML page past where the index should appear.
beginSearchResultsPageAll the content of the HTML page up to where the search results content should appear.
endSearchResultsPageAll the content of the HTML page past where the search results content should appear.

Returns

The number of pages in the index.

BuildIndexSections

sub BuildIndexSections #(
   NaturalDocs::SymbolTable::IndexElement[] index
) => ( string[], string[], string[] )

Builds and returns the index and search results sections 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.

Returns

The arrayref ( indexSections, tooltipSections, searchResultsSections ).

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.

BuildIndexElement

sub BuildIndexElement #(
   NaturalDocs::SymbolTable::IndexElement element,
   string cssID,
   SymbolString symbol,
   SymbolString package,
   bool hasPackage
) => ( string, string )

Converts a NaturalDocs::SymbolTable::IndexElement to HTML and returns it.  It will handle all sub-elements automatically.

Parameters

elementThe NaturalDocs::SymbolTable::IndexElement to build.
cssIDThe CSS ID to apply to the prefix.

Recursion-Only Parameters

These parameters are used internally for recursion, and should not be set.

symbolIf the element is below symbol level, the SymbolString to use.
packageIf the element is below package level, the package SymbolString to use.
hasPackageWhether the element is below package level.  Is necessary because package may need to be undef.

Returns

The array ( indexHTML, searchResultHTML ) which is the element in the respective HTML forms.

BuildIndexLink

sub BuildIndexLink #(string text,
SymbolString symbol,
SymbolString package,
FileName file,
TopicType type,
string prototype,
string summary,
string style) => ( string, string )

Builds and returns the HTML associated with an index link.  The HTML will be the a href tag, the text, and the closing tag.

Parameters

textThe text of the link in HTML.  Use <IndexSymbolToHTML()> if necessary.
symbolThe partial SymbolString to link to.
packageThe package SymbolString of the symbol.
fileThe FileName the symbol is defined in.
typeThe TopicType of the symbol.
prototypeThe prototype of the symbol, or undef if none.
summaryThe summary of the symbol, or undef if none.
styleThe CSS style to apply to the link.

Returns

The array ( indexHTML, searchResultHTML ) which is the link in the respective forms.

BuildIndexNavigationBar

sub BuildIndexNavigationBar #(type,
page,
locations)

Builds a navigation bar for a page of the index.

Parameters

typeThe TopicType of the index, or undef for general.
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.

File Functions

PurgeIndexFiles

sub PurgeIndexFiles #(
   TopicType type,
   optional NaturalDocs::SymbolTable::IndexElement[] indexSections,
   optional int startingPage
)

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

Parameters

typeThe index TopicType.
indexSectionsAn 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.  May be undef.
startingPageIf defined, only pages starting with this number will be removed.  Otherwise all pages will be removed.

OutputFileOf

sub OutputFileOf #(sourceFile)

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

OutputImageOf

sub OutputImageOf #(sourceImageFile)

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

IndexDirectory

sub IndexDirectory

Returns the directory of the index files.

IndexFileOf

sub IndexFileOf #(type,
page)

Returns the output file name of the index file.

Parameters

typeThe TopicType of the index.
pageThe page number.  Undef is the same as one.

RelativeIndexFileOf

sub RelativeIndexFileOf #(type,
page)

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

Parameters

typeThe TopicType of the index.
pageThe page number.  Undef is the same as one.

SearchResultsDirectory

sub SearchResultsDirectory

Returns the directory of the search results files.

SearchResultsFileOf

sub SearchResultsFileOf #(TopicType type,
string extra)

Returns the output file name of the search result file.

Parameters

typeThe TopicType of the index.
extraThe string to add to the end of the file name, such as “A” or “Symbols”.

CSSDirectory

sub CSSDirectory

Returns the directory of the CSS files.

MainCSSFile

sub MainCSSFile

Returns the location of the main CSS file.

JavaScriptDirectory

sub JavaScriptDirectory

Returns the directory of the JavaScript files.

MainJavaScriptFile

sub MainJavaScriptFile

Returns the location of the main JavaScript file.

PrettifyJavaScriptFile

sub PrettifyJavaScriptFile

Returns the location of the Google Prettify JavaScript file.

SearchDataJavaScriptFile

sub SearchDataJavaScriptFile

Returns the location of the search data JavaScript file.

Support Functions

IndexTitleOf

sub IndexTitleOf #(type)

Returns the page title of the index file.

Parameters

typeThe type of index.

MakeRelativeURL

sub MakeRelativeURL #(FileName baseFile,
FileName targetFile,
bool baseHasFileName) -> string relativeURL

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

Parameters

baseFileThe base FileName in local format, not in URL format.
targetFileThe target FileName of the link in local format, not in URL format.
baseHasFileNameWhether baseFile has a file name attached or is just a path.

Returns

The relative URL to the target.

StringToHTML

sub StringToHTML #(string,
addHiddenBreaks)

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

Parameters

stringThe string to convert.
addHiddenBreaksWhether to add hidden breaks to the string.  You can use ADD_HIDDEN_BREAKS for this parameter if you want to make the calling code clearer.

Returns

The string in HTML.

SymbolToHTMLSymbol

sub SymbolToHTMLSymbol #(symbol)

Converts a SymbolString 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().

StringToSearchResultID

sub StringToSearchResultID #(string string,  
bool dontIncrement =  0) => string

Takes a text string and translates it into something that can be used as a CSS ID.

Parameters

stringThe string to convert
dontIncrementIf set, it reuses the last generated ID.  Otherwise it generates a new one if it matches a previously generated one in a case-insensitive way.

NDMarkupToHTML

sub NDMarkupToHTML #(sourceFile,
text,
symbol,
package,
type,
using,
style)

Converts a block of NDMarkup to HTML.

Parameters

sourceFileThe source FileName the NDMarkup appears in.
textThe NDMarkup text to convert.
symbolThe topic SymbolString the NDMarkup appears in.
packageThe package SymbolString the NDMarkup appears in.
typeThe TopicType the NDMarkup appears in.
usingAn arrayref of scope SymbolStrings the NDMarkup also has access to, or undef if none.
styleSet to one of the NDMarkupToHTML Styles or leave undef for general.

Returns

The text in HTML.

BuildTextLink

sub BuildTextLink #(target,
name,
original,
package,
using,
sourceFile)

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

Parameters

targetThe link text.
nameThe link name.
originalThe original text as it appears in the source.
packageThe package SymbolString the link appears in, or undef if none.
usingAn arrayref of additional scope SymbolStrings the link has access to, or undef if none.
sourceFileThe FileName the link appears in.

Target, name, and original are assumed to still have NDMarkup amp chars.

Returns

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

BuildURLLink

sub BuildURLLink #(target,
name)

Creates a HTML link to an external URL.  Long URLs will have hidden breaks to allow them to wrap.

Parameters

targetThe URL to link to.
nameThe label of the link.

Both are assumed to still have NDMarkup amp chars.

Returns

The HTML link, complete with tags.

BuildEMailLink

sub BuildEMailLink #(target,
name)

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

Parameters

targetThe e-mail address.
nameThe label of the link.

Both are assumed to still have NDMarkup amp chars.

Returns

The HTML e-mail link, complete with tags.

BuildImage

sub BuildImage #(sourceFile,
mode,
target,
original)

Builds the HTML for an image.

Parameters

sourceFileThe source FileName this image appears in.
modeEither “inline” or “link”.
targetThe target.
originalThe original text.

All are assumed to still have NDMarkup amp chars.

Returns

The result in HTML.  If the mode was “link”, the target image’s HTML is added to imageContent.

BuildToolTipLinkProperties

sub BuildToolTipLinkProperties #(toolTipID)

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

sub AddDoubleSpaces #(text)

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

sub ConvertAmpChars #(text)

Converts certain characters to their HTML amp char equivalents.

Parameters

textThe text to convert.

Returns

The converted text.

RestoreAmpChars

sub RestoreAmpChars #(text)

Restores all amp characters to their original state.  This works with both NDMarkup amp chars and fancy quotes.

Parameters

textThe text to convert.

Returns

The converted text.

AddHiddenBreaks

sub AddHiddenBreaks #(string)

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

sub FindFirstFile

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

ExpandMenu

sub ExpandMenu #(
   FileName sourceFile,
   TopicType indexType,
   NaturalDocs::Menu::Entry[] selectionHierarchy,
   int rootLength
) -> int[] groupsToExpand

Determines which groups should be expanded.

Parameters

sourceFileThe source FileName to use if you’re looking for a source file.
indexTypeThe index TopicType to use if you’re looking for an index.
selectionHierarchyThe FileName 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.

GetMenuSelectionHierarchy

sub GetMenuSelectionHierarchy #(
   FileName sourceFile,
   TopicType indexType
) -> NaturalDocs::Menu::Entry[] selectionHierarchy

Finds the sequence of menu groups that contain the current selection.

Parameters

sourceFileThe source FileName to use if you’re looking for a source file.
indexTypeThe index TopicType to use if you’re looking for an index.

Returns

An arrayref 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 entry works its way towards the outermost group.

FindMenuSelection

sub FindMenuSelection #(
   FileName sourceFile,
   TopicType indexType,
   NaturalDocs::Menu::Entry[] hierarchyRef,
   NaturalDocs::Menu::Entry[] entries
) -> bool hasSelection

A recursive function that deterimes if it or any of its sub-groups has the menu selection.

Parameters

sourceFileThe source FileName to use if you’re looking for a source file.
indexTypeThe index TopicType to use if you’re looking for an index.
hierarchyRefA reference to the menu selection hierarchy.
entriesAn arrayref of NaturalDocs::Menu::Entries to search.

Returns

Whether this group or any of its subgroups had the selection.  If true, it will add any subgroups to the menu selection hierarchy but not itself.  This prevents the topmost entry from being added.

ResetToolTips

sub ResetToolTips #(samePage)

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.
sub NDMarkupToHTML #(sourceFile,
text,
symbol,
package,
type,
using,
style)
Converts a block of NDMarkup to 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 @searchExtensions
An array of the search file name extensions for all the index sections.
my $saidUpdatingCSSFile
Whether the status message “Updating CSS file...”
sub StringToHTML #(string,
addHiddenBreaks)
Converts a text string to HTML.
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 %prebuiltMenus
A hash that maps output directonies to menu HTML already built for it.
my $menuNumbersAndLengthsDone
Set when the variables that only need to be calculated for the menu once are done.
my $menuGroupNumber
The current menu group number.
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.
my $menuRootLength
The length of the top-level menu entries without expansion.
my $imageAnchorNumber
Incremented for each image link in the file that requires an anchor.
my $imageContent
The actual embedded image HTML for all image links.
my %searchResultIDs
A hash mapping lowercase-only search result IDs to the number of times they’ve been used.
sub New
Creates and returns a new object.
sub UpdateImage #(file)
Define this function to add or update the passed image in the output.
sub PurgeFiles #(filesToPurge)
Deletes the output files associated with the purged source files.
sub PurgeIndexes #(indexes)
Deletes the output files associated with the purged source files.
sub PurgeImages #(files)
Define this function to make the package remove all output related to the passed image files.
sub BeginBuild #(hasChanged)
Creates the necessary subdirectories in the output directory.
sub EndBuild #(hasChanged)
Synchronizes the projects CSS and JavaScript files.
sub BuildTitle #(sourceFile)
Builds and returns the HTML page title of a file.
sub BuildMenu #(FileName sourceFile,
TopicType indexType) -> string htmlMenu
Builds and returns the side menu of a file.
sub BuildMenuSegment #(outputDirectory,
menuSegment,
topLevel)
A recursive function to build a segment of the menu.
sub BuildContent #(sourceFile,
parsedFile)
Builds and returns the main page content.
sub BuildSummary #(sourceFile,
parsedFile,
index)
Builds a summary, either for the entire file or the current class/section.
sub BuildPrototype #(type,
prototype,
file)
Builds and returns the prototype as HTML.
sub BuildFooter #(bool multiline)
Builds and returns the HTML footer for the page.
sub BuildToolTip #(symbol,
file,
type,
prototype,
summary)
Builds the HTML for a symbol’s tooltip and stores it in tooltipHTML.
sub BuildToolTips
Builds and returns the tooltips for the page in HTML.
sub BuildClassHierarchy #(file,
symbol)
Builds and returns a class hierarchy diagram for the passed class, if applicable.
sub BuildClassHierarchyEntry #(file,
symbol,
style,
link)
Builds and returns a single class hierarchy entry.
sub OpeningBrowserStyles
Returns the JavaScript that will add opening browser styles if necessary.
sub ClosingBrowserStyles
Returns the JavaScript that will close browser styles if necessary.
sub StandardComments
Returns the standard HTML comments that should be included in every generated file.
sub IEWebMark
Returns the HTML comment necessary to get around the security warnings in IE starting with Windows XP Service Pack 2.
sub BuildIndexPages #(
   TopicType type,
   NaturalDocs::SymbolTable::IndexElement[] indexSections,
   string beginIndexPage,
   string endIndexPage,
   string beginSearchResultsPage,
   string endSearchResultsPage
) => int
Builds an index file or files.
sub BuildIndexSections #(
   NaturalDocs::SymbolTable::IndexElement[] index
) => ( string[], string[], string[] )
Builds and returns the index and search results sections in HTML.
sub BuildIndexElement #(
   NaturalDocs::SymbolTable::IndexElement element,
   string cssID,
   SymbolString symbol,
   SymbolString package,
   bool hasPackage
) => ( string, string )
Converts a NaturalDocs::SymbolTable::IndexElement to HTML and returns it.
A class representing part of an indexed symbol.
sub BuildIndexLink #(string text,
SymbolString symbol,
SymbolString package,
FileName file,
TopicType type,
string prototype,
string summary,
string style) => ( string, string )
Builds and returns the HTML associated with an index link.
sub BuildIndexNavigationBar #(type,
page,
locations)
Builds a navigation bar for a page of the index.
sub PurgeIndexFiles #(
   TopicType type,
   optional NaturalDocs::SymbolTable::IndexElement[] indexSections,
   optional int startingPage
)
Removes all or some of the output files for an index.
sub OutputFileOf #(sourceFile)
Returns the output file name of the source file.
sub OutputImageOf #(sourceImageFile)
Returns the output image file name of the source image file.
sub IndexDirectory
Returns the directory of the index files.
sub IndexFileOf #(type,
page)
Returns the output file name of the index file.
sub RelativeIndexFileOf #(type,
page)
Returns the output file name of the index file, relative to other index files.
sub SearchResultsDirectory
Returns the directory of the search results files.
sub SearchResultsFileOf #(TopicType type,
string extra)
Returns the output file name of the search result file.
sub CSSDirectory
Returns the directory of the CSS files.
sub MainCSSFile
Returns the location of the main CSS file.
sub JavaScriptDirectory
Returns the directory of the JavaScript files.
sub MainJavaScriptFile
Returns the location of the main JavaScript file.
sub PrettifyJavaScriptFile
Returns the location of the Google Prettify JavaScript file.
sub SearchDataJavaScriptFile
Returns the location of the search data JavaScript file.
sub IndexTitleOf #(type)
Returns the page title of the index file.
sub MakeRelativeURL #(FileName baseFile,
FileName targetFile,
bool baseHasFileName) -> string relativeURL
Returns a relative path between two files in the output tree and returns it in URL format.
sub SymbolToHTMLSymbol #(symbol)
Converts a SymbolString to a HTML symbol, meaning one that is safe to include in anchor and link tags.
A scalar which encodes a normalized array of identifier strings representing a full or partially-resolved symbol.
sub StringToSearchResultID #(string string,  
bool dontIncrement =  0) => string
Takes a text string and translates it into something that can be used as a CSS ID.
A markup format used by the parser, both internally and in NaturalDocs::Parser::ParsedTopic objects.
sub BuildTextLink #(target,
name,
original,
package,
using,
sourceFile)
Creates a HTML link to a symbol, if it exists.
sub BuildURLLink #(target,
name)
Creates a HTML link to an external URL.
sub BuildEMailLink #(target,
name)
Creates a HTML link to an e-mail address.
sub BuildImage #(sourceFile,
mode,
target,
original)
Builds the HTML for an image.
sub BuildToolTipLinkProperties #(toolTipID)
Returns the properties that should go in the link tag to add a tooltip to it.
sub AddDoubleSpaces #(text)
Adds second spaces after the appropriate punctuation with &nbsp; so they show up in HTML.
sub ConvertAmpChars #(text)
Converts certain characters to their HTML amp char equivalents.
sub RestoreAmpChars #(text)
Restores all amp characters to their original state.
sub AddHiddenBreaks #(string)
Adds hidden breaks to symbols.
sub FindFirstFile
A function that finds and returns the first file entry in the menu, or undef if none.
sub ExpandMenu #(
   FileName sourceFile,
   TopicType indexType,
   NaturalDocs::Menu::Entry[] selectionHierarchy,
   int rootLength
) -> int[] groupsToExpand
Determines which groups should be expanded.
sub GetMenuSelectionHierarchy #(
   FileName sourceFile,
   TopicType indexType
) -> NaturalDocs::Menu::Entry[] selectionHierarchy
Finds the sequence of menu groups that contain the current selection.
sub FindMenuSelection #(
   FileName sourceFile,
   TopicType indexType,
   NaturalDocs::Menu::Entry[] hierarchyRef,
   NaturalDocs::Menu::Entry[] entries
) -> bool hasSelection
A recursive function that deterimes if it or any of its sub-groups has the menu selection.
sub ResetToolTips #(samePage)
Resets the ToolTip Package Variables for a new page.
These variables are for the tooltip generation functions only.
Constants used to approximate the lengths of the menu or its groups.
A class representing an entry in the menu.
A string representing the absolute, platform-dependent path to a file.
A string representing a topic type as defined in Topics.txt.
sub UpdateFile #(sourceFile)
Updates an output file.
sub UpdateIndex #(type)
Updates an index’s output file.
These variables are for the menu generation functions only.
A class for parsed topics of source files.
The style for a parent class.
Just a synonym for “1” so that setting the flag on StringToHTML() is clearer in the calling code.
These are the styles used with NDMarkupToHTML().
Close