NaturalDocs:: Builder:: HTMLBaseNaturalDocs::Builder::HTMLBase |
A base package for all the shared functionality in NaturalDocs::Builder::HTML and NaturalDocs::Builder::FramedHTML. Summary | | | These variables are shared by all instances of the package so don’t change them. | | 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. | | Whether the status message “Updating CSS file...” | | These variables are for the tooltip generation functions only. | | A number used as part of the ID for each link that has a tooltip. | | A number used as part of the ID for each tooltip. | | A hash that maps the tooltip symbols to their assigned numbers. | | The generated tooltip HTML. | | 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. | | Builds the HTML for a symbol’s tooltip and stores it in tooltipHTML. | | Builds and returns the tooltips for the page in HTML. | | Builds and returns a class hierarchy diagram for the passed class, if applicable. | | Builds and returns a single class hierarchy entry. | | Returns the JavaScript necessary to expand and collapse the menus. | | Returns the JavaScript necessary to detect the browser. | | Returns the JavaScript necessary to show, hide, and position tool tips. | | 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 the output file name of the index file. | | Returns the output file name of the index file, relative to other index files. | | 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. | | Returns the properties that should go in the link tag to add a tooltip to it. | | Adds second spaces after the appropriate punctuation with so they show up in HTML. | | Converts certain characters to their HTML amp char equivalents. | | Adds hidden breaks to symbols. | | A function that finds and returns the first file entry in the menu, or undef if none. | | Determines which groups should be expanded. | | |
Package VariablesThese variables are shared by all instances of the package so don’t change them. 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. saidUpdatingCSSFileWhether 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. ToolTip Package VariablesThese variables are for the tooltip generation functions only. Since they’re reset on every call to BuildContent() and BuildIndexContent(), and are only used by them and their support functions, they can be shared by all instances of the package. tooltipLinkNumberA number used as part of the ID for each link that has a tooltip. Should be incremented whenever one is made. tooltipNumberA number used as part of the ID for each tooltip. Should be incremented whenever one is made. tooltipSymbolsToNumbersmy %tooltipSymbolsToNumbers |
A hash that maps the tooltip symbols to their assigned numbers. tooltipHTMLThe generated tooltip HTML. Menu Package VariablesThese 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. 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. 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. |
EndBuildChecks that the project’s CSS file is the same as the master CSS file, unless -s Custom is specified. BuildTitleBuilds 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. BuildMenuBuilds and returns the side menu of a file. ParametersoutputFile | 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. BuildMenuSegmentA recursive function to build a segment of the menu. Remember to reset the Menu Package Variables before calling this for the first time. ParametersoutputFile | 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. |
BuildContentBuilds and returns the main page content. ParametersReturnsThe page content in HTML. BuildSummaryBuilds 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. BuildPrototypeBuilds and returns the prototype as HTML. Parameterstype | The type of prototype it is. | prototype | The prototype to format. | file | The file the prototype was defined in. |
ReturnsThe prototype in HTML. BuildFooterBuilds and returns the HTML footer for the page. BuildIndexContentBuilds and returns index’s content in HTML. Parametersindex | 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. | outputFile | The output file the index is going to be stored in. Since there may be multiple files, just send the first file. |
ReturnsAn 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. BuildIndexLinkReturns 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. | summary | The summary of the symbol, if any. | outputFile | The output file the link is appearing in. |
ReturnsThe link entry, including IEntry tags. BuildIndexFilesBuilds an index file or files. Parameterstype | 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. BuildIndexNavigationBarBuilds a navigation bar for a page of the index. Parameterstype | 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. |
BuildToolTipBuilds the HTML for a symbol’s tooltip and stores it in tooltipHTML. Parametersclass | The target’s class, or undef for global. | symbol | The target symbol. | file | The file the target’s defined in. | type | The symbol type. Should be one of the <Topic Types>. | prototype | The target prototype, or undef for none. | summary | The target summary, or undef for none. |
ReturnsIf a tooltip is necessary for the link, returns the tooltip ID. If not, returns undef. BuildToolTipsBuilds and returns the tooltips for the page in HTML. BuildClassHierarchyBuilds and returns a class hierarchy diagram for the passed class, if applicable. Parametersfile | The source file. | class | The class to build the hierarchy of. |
BuildClassHierarchyEntryBuilds and returns a single class hierarchy entry. Parametersfile | The source file. | class | The class whose hierarchy 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. |
MenuToggleJavaScriptReturns the JavaScript necessary to expand and collapse the menus. Creates the JavaScript function ToggleMenu(id). Pass the menu group ID and it will toggle its display style between “block” and “none”. BrowserStylesJavaScriptReturns the JavaScript necessary to detect the browser. The JavaScript creates two variables, browserType and browserVer. These contain the Browser Styles if the browser is detected, has JavaScript turned on, etc. One or both may be undefined. ToolTipsJavaScriptReturns the JavaScript necessary to show, hide, and position tool tips. Creates the functions ShowTip(tooltipID, linkID) and HideTip(tooltipID), which toggle the tooltips’ visibility style between “visible” and “hidden”. Tooltip elements should be hidden by default. Each link needs to have a unique ID. OpeningBrowserStylesReturns the JavaScript that will add opening browser styles if necessary. ClosingBrowserStylesReturns the JavaScript that will close browser styles if necessary. PurgeIndexFilesRemoves all or some of the output files for an index. Parameterstype | 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. |
OutputFileOfReturns the output file name of the source file. Will be undef if it is not a file from a valid input directory. IndexFileOfReturns the output file name of the index file. Parameterstype | The type of index, or undef if general. | page | The page number. Undef is the same as one. |
RelativeIndexFileOfReturns the output file name of the index file, relative to other index files. Parameterstype | The type of index, or undef if general. | page | The page number. Undef is the same as one. |
MakeRelativeURLReturns 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. StringToHTMLConverts a text string to HTML. Does not apply paragraph tags or accept formatting tags. Parametersstring | The string to convert. |
ReturnsThe string in HTML. SymbolToHTMLSymbolConverts 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. NDMarkupToHTMLConverts 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. BuildLinkCreates a HTML link to a symbol, if it exists. Parametersscope | 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. BuildEMailLinkCreates a HTML link to an e-mail address. The address will be transparently munged to protect it (hopefully) from spambots. Parametersaddress | The e-mail address. |
ReturnsThe HTML e-mail link, complete with tags. BuildToolTipLinkPropertiesReturns 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. ParameterstoolTipID | The ID of the tooltip. If undef, the function will return undef. |
ReturnsThe properties that should be put in the link tag, or undef if toolTipID wasn’t specified. AddDoubleSpacesAdds 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. ConvertAmpCharsConverts certain characters to their HTML amp char equivalents. ParametersReturnsThe converted text. AddHiddenBreaksAdds 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. FindFirstFileA function that finds and returns the first file entry in the menu, or undef if none. ExpandMenuDetermines which groups should be expanded. ParametersoutputFile | 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. ResetToolTipsResets the ToolTip Package Variables for a new page. ParameterssamePage | Set this flag if there’s the possibility that the next batch of tooltips may be on the same page as the last. |
|