NaturalDocs:: Builder:: HTMLBaseA base package for all the shared functionality in NaturalDocs::Builder::HTML and NaturalDocs::Builder::FramedHTML. All functions are called with Package->Function() notation. Summary | | | | | | | An existence hash of acceptable abbreviations. | | An array of the headings of all the index sections. | | An array of the HTML anchors of all the index sections. | | These variables are for the menu generation functions only. | | The current menu group number. | | | | The length of the entire menu, fully expanded. | | A hash of the length of each group, not including any subgroup contents. | | | | Constants used to approximate the lengths of the menu or its groups. | | The behavior of these functions is shared between HTML output formats. | | Deletes the output files associated with the purged source files. | | Deletes the output files associated with the purged source files. | | Checks that the project’s CSS file is the same as the master CSS file, unless -s Custom is specified. | | | | Builds and returns the HTML page title of a file. | | Builds and returns the side menu of a file. | | A recursive function to build a segment of the menu. | | Builds and returns the main page content. | | Builds a summary, either for the entire file or the current class/section. | | Builds and returns the prototype as HTML. | | Builds and returns the HTML footer for the page. | | Builds and returns index’s content in HTML. | | Returns a link in the index, complete with surrounding IEntry tags. | | Builds an index file or files. | | Builds a navigation bar for a page of the index. | | Returns the JavaScript necessary to expand and collapse the menus. | | Returns the JavaScript necessary to detect the browser. | | Returns the JavaScript that will add opening browser styles if necessary. | | Returns the JavaScript that will close browser styles if necessary. | | | | Removes all or some of the output files for an index. | | Returns the output file name of the source file. | | Returns 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. | | | | Creates a HTML link to a symbol, if it exists. | | Creates a HTML link to an e-mail address. | | 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. | | Determines which groups should be expanded. |
topicNamesA hash of text equivalents of the Topic Types. Makes output easier. The keys are the tokens, and the values are their text equivalents. abbreviationsAn 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. indexHeadingsAn array of the headings of all the index sections. First is for symbols, second for numbers, and the rest for each letter. indexAnchorsAn array of the HTML anchors of all the index sections. First is for symbols, second for numbers, and the rest for each letter. Menu VariablesThese variables are for the menu generation functions only. Since they’re needed in recursion, passing around references instead would just be a pain. menuGroupNumberThe current menu group number. Each time a group is created, this is incremented so that each one will be unique. menuSelectionHierarchymy @menuSelectionHierarchy |
An array of the NaturalDocs::Menu::Entry objects of each group surrounding the selected menu item. First entry is the group immediately encompassing it, and each subsequent entries works its way towards the outermost group. menuLengthThe length of the entire menu, fully expanded. The value is computed from the Menu Length Constants. menuGroupLengthsA 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. Menu Length ConstantsConstants used to approximate the lengths of the menu or its groups. | 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 FunctionsThe behavior of these functions is shared between HTML output formats. PurgeFilesDeletes 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. |
EndBuild| sub EndBuild # | ( | hasChanged | ) | |
Checks that the project’s CSS file is the same as the master CSS file, unless -s Custom is specified. BuildTitle| sub BuildTitle # | ( | sourceFile | ) | |
Builds and returns the HTML page title of a file. Parameters| sourceFile | The source file to build the title of. |
ReturnsThe source file’s title in HTML. BuildMenu| sub BuildMenu # | ( | outputFile, | | | isFramed | ) | |
Builds and returns the side menu of a file. Parameters| outputFile | The output file to build the menu for. Does not have to be on the menu itself. | | isFramed | Whether the menu will appear in a frame. If so, it assumes the <base> HTML tag is set to make links go to the appropriate frame. |
ReturnsThe side menu in HTML. BuildMenuSegment| sub BuildMenuSegment # | ( | outputFile, | | | isFramed, | | | menuSegment | ) | |
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. Does not have to be on the menu itself. | | isFramed | Whether the menu will be in a HTML frame or not. Assumes that if it is, the <base> HTML tag will be set so that links are directed to the proper frame. | | menuSegment | An arrayref specifying the segment of the menu to build. Either pass the menu itself or the contents of a group. |
ReturnsThe array ( menuHTML, hasSelection, length ). | menuHTML | The menu segment in HTML. | | hasSelection | Whether the group or any of its subgroups contains the entry for the selected file. | | groupLength | The length of the group, not including the contents of any subgroups, as computed from the Menu Length Constants. |
BuildContent| sub BuildContent # | ( | sourceFile, | | | parsedFile | ) | |
Builds and returns the main page content. ParametersReturnsThe 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. |
ReturnsThe summary in HTML. BuildPrototype| sub BuildPrototype # | ( | prototype | ) | |
Builds and returns the prototype as HTML. BuildFooterBuilds and returns the HTML footer for the page. BuildIndexContent| sub BuildIndexContent # | ( | index, | | | outputFile | ) | |
Builds and returns index’s content in HTML. ParametersReturnsAn arrayref of the index sections. Index 0 is the symbols, index 1 is the numbers, and each following index is A through Z. The content of each section is its HTML, or undef if there is nothing for that section. BuildIndexLink| 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. |
ReturnsThe link entry, including IEntry tags. BuildIndexFiles| sub BuildIndexFiles # | ( | type, | | | indexContent,
beginPage, | | | endPage | ) | |
Builds an index file or files. Parameters| type | The type the index is limited to, or undef for none. Should be one of the Topic Types. | | indexContent | An arrayref containing the index content. Each entry is a section; index 0 is symbols, index 1 is numbers, and following indexes represent A through Z. | | beginPage | All the content of the HTML page up to where the index content should appear. | | endPage | All the content of the HTML page past where the index should appear. |
ReturnsThe number of pages in the index. BuildIndexNavigationBar| sub BuildIndexNavigationBar # | ( | type, | | | page, | | | locations | ) | |
Builds a navigation bar for a page of the index. Parameters| type | The type of the index, or undef for general. Should be one of the Topic Types. | | 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. |
MenuToggleJavaScriptReturns the JavaScript necessary to expand and collapse the menus. BrowserStylesJavaScriptsub BrowserStylesJavaScript |
Returns the JavaScript necessary to detect the browser. OpeningBrowserStylesReturns the JavaScript that will add opening browser styles if necessary. ClosingBrowserStylesReturns the JavaScript that will close browser styles if necessary. PurgeIndexFiles| sub PurgeIndexFiles # | ( | type, | | | startingPage | ) | |
Removes all or some of the output files for an index. Parameters| type | The index type, or undef for general. Should be one of the Topic Types. | | 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. 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. |
ReturnsThe 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. |
ReturnsThe 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. |
ReturnsThe 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. |
ReturnsThe text in HTML. MakeLink| sub MakeLink # | ( | scope, | | | text, | | | sourceFile | ) | |
Creates a HTML link to a symbol, if it exists. Parameters| scope | The scope the link appears in. | | text | The link text | | sourceFile | The file the link appears in. |
ReturnsThe link in HTML, including tags. If the link doesn’t resolve to anything, returns the HTML that should be substituted for it. MakeEMailLink| sub MakeEMailLink # | ( | address | ) | |
Creates a HTML link to an e-mail address. The address will be transparently munged to protect it (hopefully) from spambots. Parameters| address | The e-mail address. |
ReturnsThe HTML e-mail link, complete with tags. 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. ParametersReturnsThe text with double spaces as necessary. ConvertAmpChars| sub ConvertAmpChars # | ( | text | ) | |
Converts certain characters to their HTML amp char equivalents. ParametersReturnsThe converted text. HiddenBreakReturns 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. |
ReturnsThe string with hidden breaks. FindFirstFile| sub FindFirstFile # | ( | arrayref | ) | |
A recursive function that finds and returns the first file entry in the menu. ParametersExpandMenu| sub ExpandMenu # | ( | outputFile, | | | rootLength | ) | |
Determines which groups should be expanded. Parameters| outputFile | The file 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. |
ReturnsAn 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. |