NaturalDocs:: Builder:: HTML

A package that generates output in HTML.

Usage and Dependencies

Everything is handled by NaturalDocs::Builder.

Summary

NaturalDocs:: Builder:: HTML	A package that generates output in HTML.
Variables
topicNames	A hash of text equivalents of the Topic Types.
abbreviations	An existence hash of acceptable abbreviations.
Menu Variables	These variables are for the menu generation functions only.
menuGroupNumber	The current menu group number.
menuSelectionHierarchy	An array of the group numbers surrounding the selected menu item.
menuLength	The length of the entire menu, fully expanded.
menuLength Constants	Constants used in conjunction with menuLength.
Implemented Interface Functions
INIT	Registers the package with NaturalDocs::Builder.
CommandLineOption	Returns the option to follow -o to use this package.
PurgeFiles	Deletes the output files associated with the purged source files.
PurgeIndexes	Deletes the output files associated with the purged source files.
BuildFile	Builds the output file from the parsed source file.
BuildIndex	Builds an index for the passed type.
UpdateMenu	Updates the menu in all the output files that weren’t rebuilt.
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.
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.
BuildFooter	Builds and returns the HTML footer for the page.
UpdateFile	Updates an output file.
UpdateIndex	Updates an index’s output file.
BuildIndexContent	Builds and returns index’s content in HTML.
BuildIndexLink	Returns a link in the index, complete with surrounding IEntry tags.
BuildMenuJavaScript	Returns the JavaScript necessary to expand and collapse the menus.
Support Functions
OutputFileOf	Returns the output file name of the source 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 class and symbol to a HTML symbol, meaning one that is safe to include in anchor and link tags.
NDMarkupToHTML	Converts a block of NDMarkup to HTML.
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.
HiddenBreak	Returns a hidden word break in HTML.
AddHiddenBreaks	Adds hidden breaks to symbols.
FindFirstFile	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_TITLELENGTH	The length of the title.
MENU_SUBTITLELENGTH	The length of the subtitle.
MENU_FILELENGTH	The length of one file entry.
MENU_GROUPLENGTH	The length of one group entry.
MENU_TEXTLENGTH	The length of one text entry.
MENU_LINKLENGTH	The length of one link entry.
MENU_LENGTHLIMIT	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.

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

indexes

An 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

sourcefile	The name of the source file.
parsedFile	An arrayref of the source file as NaturalDocs::Parser::ParsedTopic objects.

BuildIndex

sub BuildIndex #(type)

Builds an index for the passed type.

Parameters

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

sourceFile

The 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

outputFile

The 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

outputFile	The output file the menu is being built for.
menuSegment	An arrayref specifying the segment of the menu to build. Either pass the menu itself or the content of a group.
hasSelectionRef	A 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

sourceFile	The source file name.
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 file 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 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

sourceFile

The 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

type	The index type, or undef if note.

BuildIndexContent

sub BuildIndexContent #(index, outputFile)

Builds and returns index’s content in HTML.

Parameters

index	An arrayref of NaturalDocs::SymbolTable::IndexElement objects.
outputFile	The 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

name	The text to appear for the link.
tag	The tag to apply to name. For example, ISymbol.
class	The class of the symbol, if any.
showClass	Whether the class name should be shown in parenthesis.
symbol	The symbol to link to.
file	The source file the symbol appears in.
type	The type of the symbol. One of the Topic Types.
prototype	The prototype of the symbol, if any.
outputFile	The 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

baseFile	The base file in local format, not in URL format.
targetFile	The 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

string

The 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

class	The symbol’s class. Set to undef if global.
symbol	The symbol’s name.

Returns

The HTML symbol string.

NDMarkupToHTML

sub NDMarkupToHTML #(sourceFile, text, scope)

Converts a block of NDMarkup to HTML.

Parameters

sourceFile	The source file the NDMarkup appears in.
text	The NDMarkup text to convert.
scope	The 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

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.

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

string

The 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

arrayref

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