NaturalDocs::Builder::HTMLBase

NaturalDocs::Builder::Base

NaturalDocs::Builder::FramedHTML

NaturalDocs::Builder::HTML

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

Summary

NaturalDocs::Builder::HTMLBase	A base package for all the shared functionality in NaturalDocs::Builder::HTML and NaturalDocs::Builder::FramedHTML.
Object Variables
Members	The object is implemented as a blessed arrayref, with the follow constants as indexes.
NDMarkupToHTML Styles	These are the styles used with NDMarkupToHTML().
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	An existence hash of acceptable abbreviations.
indexHeadings	An array of the headings of all the index sections.
indexAnchors	An array of the HTML anchors of all the index sections.
searchExtensions	An array of the search file name extensions for all the index sections.
saidUpdatingCSSFile	Whether the status message “Updating CSS file...”
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.
tooltipLinkNumber	A number used as part of the ID for each link that has a tooltip.
tooltipNumber	A number used as part of the ID for each tooltip.
tooltipSymbolsToNumbers	A hash that maps the tooltip symbols to their assigned numbers.
tooltipHTML	The generated tooltip HTML.
Menu Package Variables	These variables are for the menu generation functions only.
prebuiltMenus	A hash that maps output directonies to menu HTML already built for it.
menuNumbersAndLengthsDone	Set when the variables that only need to be calculated for the menu once are done.
menuGroupNumber	The current menu group number.
menuLength	The length of the entire menu, fully expanded.
menuGroupLengths	A hash of the length of each group, not including any subgroup contents.
menuGroupNumbers	A hash of the number of each group, as managed by menuGroupNumber.
menuRootLength	The length of the top-level menu entries without expansion.
Menu Length Constants	Constants used to approximate the lengths of the menu or its groups.
Image Package Variables	These variables are for the image generation functions only.
imageAnchorNumber	Incremented for each image link in the file that requires an anchor.
imageContent	The actual embedded image HTML for all image links.
Search Package Variables	These variables are for the search generation functions only.
searchResultIDs	A hash mapping lowercase-only search result IDs to the number of times they’ve been used.
Object Functions
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	Define this function to add or update the passed image in the output.
PurgeFiles	Deletes the output files associated with the purged source files.
PurgeIndexes	Deletes the output files associated with the purged source files.
PurgeImages	Define this function to make the package remove all output related to the passed image files.
BeginBuild	Creates the necessary subdirectories in the output directory.
EndBuild	Synchronizes the projects CSS and JavaScript files.
Section Functions
BuildTitle	Builds and returns the HTML page title of a file.
BuildMenu	Builds and returns the side menu of a file.
BuildMenuSegment	A recursive function to build a segment of the menu.
BuildContent	Builds and returns the main page content.
BuildSummary	Builds a summary, either for the entire file or the current class/section.
BuildPrototype	Builds and returns the prototype as HTML.
BuildFooter	Builds and returns the HTML footer for the page.
BuildToolTip	Builds the HTML for a symbol’s tooltip and stores it in tooltipHTML.
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.
BuildClassHierarchyEntry	Builds and returns a single class hierarchy entry.
OpeningBrowserStyles	Returns the JavaScript that will add opening browser styles if necessary.
ClosingBrowserStyles	Returns the JavaScript that will close browser styles if necessary.
StandardComments	Returns the standard HTML comments that should be included in every generated file.
IEWebMark	Returns the HTML comment necessary to get around the security warnings in IE starting with Windows XP Service Pack 2.
Index Functions
BuildIndexPages	Builds an index file or files.
BuildIndexSections	Builds and returns the index and search results sections in HTML.
BuildIndexElement	Converts a NaturalDocs::SymbolTable::IndexElement to HTML and returns it.
BuildIndexLink	Builds and returns the HTML associated with an index link.
BuildIndexNavigationBar	Builds a navigation bar for a page of the index.
File Functions
PurgeIndexFiles	Removes all or some of the output files for an index.
OutputFileOf	Returns the output file name of the source file.
OutputImageOf	Returns the output image file name of the source image file.
IndexDirectory	Returns the directory of the index files.
IndexFileOf	Returns the output file name of the index file.
RelativeIndexFileOf	Returns the output file name of the index file, relative to other index files.
SearchResultsDirectory	Returns the directory of the search results files.
SearchResultsFileOf	Returns the output file name of the search result file.
CSSDirectory	Returns the directory of the CSS files.
MainCSSFile	Returns the location of the main CSS file.
JavaScriptDirectory	Returns the directory of the JavaScript files.
MainJavaScriptFile	Returns the location of the main JavaScript file.
SearchDataJavaScriptFile	Returns the location of the search data JavaScript file.
Support Functions
IndexTitleOf	Returns the page title of the index file.
MakeRelativeURL	Returns a relative path between two files in the output tree and returns it in URL format.
StringToHTML	Converts a text string to HTML.
SymbolToHTMLSymbol	Converts a SymbolString to a HTML symbol, meaning one that is safe to include in anchor and link tags.
StringToSearchResultID	Takes a text string and translates it into something that can be used as a CSS ID.
NDMarkupToHTML	Converts a block of NDMarkup to HTML.
BuildTextLink	Creates a HTML link to a symbol, if it exists.
BuildURLLink	Creates a HTML link to an external URL.
BuildEMailLink	Creates a HTML link to an e-mail address.
BuildImage	Builds the HTML for an image.
BuildToolTipLinkProperties	Returns the properties that should go in the link tag to add a tooltip to it.
AddDoubleSpaces	Adds second spaces after the appropriate punctuation with   so they show up in HTML.
ConvertAmpChars	Converts certain characters to their HTML amp char equivalents.
RestoreAmpChars	Restores all amp characters to their original state.
AddHiddenBreaks	Adds hidden breaks to symbols.
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.
GetMenuSelectionHierarchy	Finds the sequence of menu groups that contain the current selection.
FindMenuSelection	A recursive function that deterimes if it or any of its sub-groups has the menu selection.
ResetToolTips	Resets 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_PAGE

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

NDMarkupToHTML Styles

These are the styles used with NDMarkupToHTML().

NDMARKUPTOHTML_GENERAL	General style.
NDMARKUPTOHTML_SUMMARY	For summaries.
NDMARKUPTOHTML_TOOLTIP	For 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_LENGTH	The length of the title.
MENU_SUBTITLE_LENGTH	The length of the subtitle.
MENU_FILE_LENGTH	The length of one file entry.
MENU_GROUP_LENGTH	The length of one group entry.
MENU_TEXT_LENGTH	The length of one text entry.
MENU_LINK_LENGTH	The length of one link entry.
MENU_LENGTH_LIMIT	The 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

file	The 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

indexes

An 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

files

An 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

sourceFile

The 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

sourceFile	The source FileName to use if you’re looking for a source file.
indexType	The 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

Builder::HTML::UpdateFile() and Builder::HTML::UpdateIndex() require this section to be surrounded with the exact strings “<div id=Menu>” and “</div>”.
This function depends on the way BuildMenuSegment() formats file and index entries.

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

outputDirectory	The output directory the menu is being built for.
menuSegment	An arrayref specifying the segment of the menu to build. Either pass the menu itself or the contents of a group.
topLevel	Whether the passed segment is the top level segment or not.

Returns

The array ( menuHTML, length ).

menuHTML	The menu segment in HTML.
groupLength	The 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

sourceFile	The source FileName.
parsedFile	The 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

sourceFile	The source FileName the summary appears in.
parsedFile	A reference to the parsed source file.
index	The 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

type	The TopicType the prototype is from.
prototype	The prototype to format.
file	The 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

multiline

Whether 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>”.

BuildToolTip

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

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

Parameters

symbol	The target SymbolString.
file	The FileName the target’s defined in.
type	The symbol TopicType.
prototype	The target prototype, or undef for none.
summary	The 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

file	The source FileName.
class	The class SymbolString to build the hierarchy of.

BuildClassHierarchyEntry

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

Builds and returns a single class hierarchy entry.

Parameters

file	The source FileName.
symbol	The class SymbolString whose entry is getting built.
style	The style to apply to the entry, such as CHParent.
link	Whether 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

type	The TopicType the index is limited to, or undef for none.
indexSections	An 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.
beginIndexPage	All the content of the HTML page up to where the index content should appear.
endIndexPage	All the content of the HTML page past where the index should appear.
beginSearchResultsPage	All the content of the HTML page up to where the search results content should appear.
endSearchResultsPage	All 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

index

An 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

element	The NaturalDocs::SymbolTable::IndexElement to build.
cssID	The CSS ID to apply to the prefix.

Recursion-Only Parameters

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

symbol	If the element is below symbol level, the SymbolString to use.
package	If the element is below package level, the package SymbolString to use.
hasPackage	Whether 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

text	The text of the link in HTML. Use <IndexSymbolToHTML()> if necessary.
symbol	The partial SymbolString to link to.
package	The package SymbolString of the symbol.
file	The FileName the symbol is defined in.
type	The TopicType of the symbol.
prototype	The prototype of the symbol, or undef if none.
summary	The summary of the symbol, or undef if none.
style	The 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

type	The TopicType of the index, or undef for general.
page	The page of the index the navigation bar is for.
locations	An 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

type	The index TopicType.
indexSections	An 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.
startingPage	If 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

type	The TopicType of the index.
page	The 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

type	The TopicType of the index.
page	The 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

type	The TopicType of the index.
extra	The 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.

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

type	The 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

baseFile	The base FileName in local format, not in URL format.
targetFile	The target FileName of the link in local format, not in URL format.
baseHasFileName	Whether 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

string	The string to convert.
addHiddenBreaks	Whether 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

string	The string to convert
dontIncrement	If 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

sourceFile	The source FileName the NDMarkup appears in.
text	The NDMarkup text to convert.
symbol	The topic SymbolString the NDMarkup appears in.
package	The package SymbolString the NDMarkup appears in.
type	The TopicType the NDMarkup appears in.
using	An arrayref of scope SymbolStrings the NDMarkup also has access to, or undef if none.
style	Set 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

target	The link text.
name	The link name.
original	The original text as it appears in the source.
package	The package SymbolString the link appears in, or undef if none.
using	An arrayref of additional scope SymbolStrings the link has access to, or undef if none.
sourceFile	The 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

target	The URL to link to.
name	The 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

target	The e-mail address.
name	The 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

sourceFile	The source FileName this image appears in.
mode	Either “inline” or “link”.
target	The target.
original	The 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

toolTipID

The 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   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

text	The 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

text	The 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

text	The 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

string

The 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

sourceFile	The source FileName to use if you’re looking for a source file.
indexType	The index TopicType to use if you’re looking for an index.
selectionHierarchy	The FileName the menu is being built for. Does not have to be on the menu itself.
rootLength	The 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

sourceFile	The source FileName to use if you’re looking for a source file.
indexType	The 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

sourceFile	The source FileName to use if you’re looking for a source file.
indexType	The index TopicType to use if you’re looking for an index.
hierarchyRef	A reference to the menu selection hierarchy.
entries	An 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

samePage

Set this flag if there’s the possibility that the next batch of tooltips may be on the same page as the last.