NaturalDocs:: Builder:: HTML

A package that generates output in HTML. 

Usage and Dependencies

Summary
A package that generates output in HTML.
A hash of text equivalents of the Topic Types.
An existence hash of acceptable abbreviations.
These variables are for the menu generation functions only.
The current menu group number.
An array of the group numbers surrounding the selected menu item.
The length of the entire menu, fully expanded.
Constants used in conjunction with menuLength.
Registers the package with NaturalDocs::Builder.
Returns the option to follow -o to use this package.
Deletes the output files associated with the purged source files.
Deletes the output files associated with the purged source files.
Builds the output file from the parsed source file.
Builds an index for the passed type.
Updates the menu in all the output files that weren’t rebuilt.
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 HTML footer for the page.
Updates an output file.
Updates an index’s output file.
Builds and returns index’s content in HTML.
Returns a link in the index, complete with surrounding IEntry tags.
Returns the JavaScript necessary to expand and collapse the menus.
Returns the output file name of the source file.
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.
Adds second spaces after the appropriate punctuation with   so they show up in HTML.
Converts certain characters to their HTML amp char equivalents.
Returns a hidden word break in HTML.
Adds hidden breaks to symbols.
A recursive function that finds and returns the first file entry in the menu.

Variables

topicNames

my %topicNames

A hash of text equivalents of the Topic Types.  Makes output easier.  The keys are the tokens, and the values are their text equivalents. 

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. 

Menu Variables

These variables are for the menu generation functions only.  Since they’re needed in recursion, passing around references instead would just be a pain. 

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 group numbers surrounding the selected menu item.  Starts at the group immediately encompassing it, and works its way towards the outermost group. 

menuLength

my $menuLength

The length of the entire menu, fully expanded.  The value is computed from MENU_FILELENGTH and MENU_GROUPLENGTH

menuLength Constants

Constants used in conjunction with menuLength

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

INIT

sub INIT

Registers the package with NaturalDocs::Builder

CommandLineOption

sub CommandLineOption

Returns the option to follow -o to use this package.  In this case, “html”. 

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. 

BuildFile

sub BuildFile #(sourceFile, parsedFile)

Builds the output file from the parsed source file. 

Parameters

sourcefileThe name of the source file. 
parsedFileAn arrayref of the source file as NaturalDocs::Parser::ParsedTopic objects. 

BuildIndex

sub BuildIndex #(type)

Builds an index for the passed type. 

Parameters

typeThe type to limit the index to, or undef if none. 

UpdateMenu

sub UpdateMenu

Updates the menu in all the output files that weren’t rebuilt.  Also generates index.html. 

EndBuild

sub EndBuild #(hasChanged)

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

Section Functions

BuildTitle

sub BuildTitle #(sourceFile)

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

sub BuildMenu #(outputFile)

Builds and returns the side menu of a file. 

Parameters

outputFileThe output file to build the menu for. 

Returns

The side menu in HTML. 

BuildMenuSegment

sub BuildMenuSegment #(outputFile, menuSegment, hasSelectionRef)

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

Parameters

outputFileThe output file the menu is being built for. 
menuSegmentAn arrayref specifying the segment of the menu to build.  Either pass the menu itself or the content of a group. 
hasSelectionRefA reference to a boolean variable, which will be set to true if this function call had the selection in it.  Won’t be set if undef. 

Returns

The menu segment in HTML. 

BuildContent

sub BuildContent #(sourceFile, parsedFile)

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

sub BuildSummary #(sourceFile, parsedFile, index)

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. 

BuildFooter

sub BuildFooter

Builds and returns the HTML footer for the page. 

UpdateFile

sub UpdateFile #(sourceFile)

Updates an output file.  Replaces the menu, HTML title, and footer.  It opens the output file, makes the changes, and saves it back to disk, which is much quicker than rebuilding the file from scratch if these were the only things that changed. 

Parameters

sourceFileThe source file. 

UpdateIndex

sub UpdateIndex #(type)

Updates an index’s output file.  Replaces the menu and footer.  It opens the output file, makes the changes, and saves it back to disk, which is much quicker than rebuilding the file from scratch if these were the only things that changed. 

Parameters

typeThe index type, or undef if note. 

BuildIndexContent

sub BuildIndexContent #(index, outputFile)

Builds and returns index’s content in HTML. 

Parameters

indexAn arrayref of NaturalDocs::SymbolTable::IndexElement objects. 
outputFileThe output file the index is going to be stored in. 

BuildIndexLink

sub BuildIndexLink #(name, tag, class, showClass, symbol, file, type, prototype, outputFile)

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. 
outputFileThe output file the link is appearing in. 

Returns

The link entry, including IEntry tags. 

BuildMenuJavaScript

sub BuildMenuJavaScript

Returns the JavaScript necessary to expand and collapse the menus. 

Support Functions

OutputFileOf

sub OutputFileOf #(sourceFile)

Returns the output file name of the source file. 

MakeRelativeURL

sub MakeRelativeURL #(baseFile, targetFile)

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

sub StringToHTML #(string)

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

sub SymbolToHTMLSymbol #(class, symbol)

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

sub NDMarkupToHTML #(sourceFile, text, scope)

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. 

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

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. 

HiddenBreak

sub HiddenBreak

Returns a hidden word break in HTML.  Or more accurately, the best approximation of it I can make. 

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 #(arrayref)

A recursive function that finds and returns the first file entry in the menu. 

Parameters

arrayrefThe array to search.  Set to NaturalDocs::Menu::Content()