NaturalDocs:: Builder:: HTMLA package that generates output in HTML. Usage and DependenciesSummary | A package that generates output in HTML. | | | | | | 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. | | | | | | | | 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 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. | | | | 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. |
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. 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 group numbers surrounding the selected menu item. Starts at the group immediately encompassing it, and works its way towards the outermost group. menuLength ConstantsConstants 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 FunctionsCommandLineOptionReturns the option to follow -o to use this package. In this case, “html”. PurgeFilesDeletes the output files associated with the purged source files. PurgeIndexessub PurgeIndexes #(indexes) |
Deletes the output files associated with the purged source files. Parametersindexes | An existence hashref of the index types to purge. The keys are the Topic Types or * for the general index. |
BuildFilesub BuildFile #(sourceFile, parsedFile) |
Builds the output file from the parsed source file. ParametersBuildIndexBuilds an index for the passed type. Parameterstype | The type to limit the index to, or undef if none. |
UpdateMenuUpdates the menu in all the output files that weren’t rebuilt. Also generates index.html. EndBuildsub EndBuild #(hasChanged) |
Checks that the project’s CSS file is the same as the master CSS file, unless -s Custom is specified. BuildTitlesub BuildTitle #(sourceFile) |
Builds and returns the HTML page title of a file. ParameterssourceFile | The source file to build the title of. |
ReturnsThe source file’s title in HTML. BuildMenusub BuildMenu #(outputFile) |
Builds and returns the side menu of a file. ParametersoutputFile | The output file to build the menu for. |
ReturnsThe side menu in HTML. BuildMenuSegmentsub 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. ParametersoutputFile | 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. |
ReturnsThe menu segment in HTML. BuildContentsub BuildContent #(sourceFile, parsedFile) |
Builds and returns the main page content. ParametersReturnsThe page content in HTML. BuildSummarysub BuildSummary #(sourceFile, parsedFile, index) |
Builds a summary, either for the entire file or the current class/section. ParameterssourceFile | 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. BuildFooterBuilds and returns the HTML footer for the page. UpdateFilesub 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. ParameterssourceFile | The source file. |
UpdateIndexUpdates 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. Parameterstype | The index type, or undef if note. |
BuildIndexContentsub BuildIndexContent #(index, outputFile) |
Builds and returns index’s content in HTML. ParametersBuildIndexLinksub BuildIndexLink #(name, tag, class, showClass, symbol, file, type, prototype, outputFile) |
Returns a link in the index, complete with surrounding IEntry tags. Parametersname | 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. BuildMenuJavaScriptReturns the JavaScript necessary to expand and collapse the menus. OutputFileOfsub OutputFileOf #(sourceFile) |
Returns the output file name of the source file. MakeRelativeURLsub MakeRelativeURL #(baseFile, targetFile) |
Returns a relative path between two files in the output tree and returns it in URL format. ParametersbaseFile | 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. StringToHTMLsub StringToHTML #(string) |
Converts a text string to HTML. Does not apply paragraph tags or accept formatting tags. Parametersstring | The string to convert. |
ReturnsThe string in HTML. SymbolToHTMLSymbolsub 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(). Parametersclass | The symbol’s class. Set to undef if global. | symbol | The symbol’s name. |
ReturnsThe HTML symbol string. NDMarkupToHTMLsub NDMarkupToHTML #(sourceFile, text, scope) |
Converts a block of NDMarkup to HTML. ParameterssourceFile | The source file the NDMarkup appears in. | text | The NDMarkup text to convert. | scope | The scope the NDMarkup appears in. |
ReturnsThe text in HTML. AddDoubleSpacessub 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. ConvertAmpCharssub 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. AddHiddenBreakssub AddHiddenBreaks #(string) |
Adds hidden breaks to symbols. Puts them after symbol and directory separators so long names won’t screw up the layout. Parametersstring | The string to break. |
ReturnsThe string with hidden breaks. FindFirstFilesub FindFirstFile #(arrayref) |
A recursive function that finds and returns the first file entry in the menu. Parameters |