diff options
| author | Magnus Auvinen <magnus.auvinen@gmail.com> | 2008-08-02 08:21:29 +0000 |
|---|---|---|
| committer | Magnus Auvinen <magnus.auvinen@gmail.com> | 2008-08-02 08:21:29 +0000 |
| commit | 61bfe2d70cae6be8c4086a210a5451135ccca9ea (patch) | |
| tree | 62bf7808b1b2bfe5f56fe1e329871fb0991d0687 /docs/tool/Info | |
| parent | a13b94f9e0bca8ea892311d9d9e0c0bc48616ea7 (diff) | |
| download | zcatch-61bfe2d70cae6be8c4086a210a5451135ccca9ea.tar.gz zcatch-61bfe2d70cae6be8c4086a210a5451135ccca9ea.zip | |
added doc tool
Diffstat (limited to 'docs/tool/Info')
| -rw-r--r-- | docs/tool/Info/CSSGuide.txt | 947 | ||||
| -rw-r--r-- | docs/tool/Info/File Parsing.txt | 83 | ||||
| -rw-r--r-- | docs/tool/Info/HTMLTestCases.pm | 269 | ||||
| -rw-r--r-- | docs/tool/Info/Languages.txt | 107 | ||||
| -rw-r--r-- | docs/tool/Info/NDMarkup.txt | 91 | ||||
| -rw-r--r-- | docs/tool/Info/Symbol Management.txt | 59 | ||||
| -rw-r--r-- | docs/tool/Info/images/Logo.png | bin | 0 -> 12405 bytes |
7 files changed, 1556 insertions, 0 deletions
diff --git a/docs/tool/Info/CSSGuide.txt b/docs/tool/Info/CSSGuide.txt new file mode 100644 index 00000000..2496b0bf --- /dev/null +++ b/docs/tool/Info/CSSGuide.txt @@ -0,0 +1,947 @@ + + Architecture: CSS Structure +_______________________________________________________________________________ + +It's important to understand the internal HTML file structure and styles in order to design your own CSS style for Natural Docs. If +you're content with the default styles, there's no need to read this document. + +Topic: Diagram Conventions + + The diagrams are designed for clarity. In the actual HTML, you'd obviously see "<table class=CDescriptionList></table>" + instead of "<table CDescriptionList></table CDescriptionList>". + + - A tag with just a style, for example "CTitle", means an unspecified element with that class. Style with .CTitle. + - A tag that includes a #, for example "#Menu", means an unspecified element with that ID. Style with #Menu. + - A tag that includes a HTML element as well, for example "table CDescriptionList", means it will always be that element. You + can style with either .CDescriptionList or table.CDescriptionList. + - A tag that has multiple classes or has an "and" in it, for example "CType and CTopic", means that both styles will apply to the + same element. You can style it with .CType.CTopic, noting that the space between them must be omitted. + - A tag that has an "or" in it, for example "#Content or #Index", is just shorthand for either of those elements. The diagram + applies to both of them but only one will actually appear at a time in the output. + - A tag or style with a question mark means that tag or style will only be there in certain situations. + + +Topic: Page Structure +_______________________________________________________________________________ + + The body tag is used to distinguish between the types of pages. + + Unframed Content/Index Page: + + (start diagram) + + <body ContentPage or IndexPage)> + [browser styles] + + <#Content or #Index> + Content or Index + </#Content or #Index> + + <#Menu> + Menu + </#Menu> + + <#Footer> + Footer + </#Footer> + + [/browser styles] + </body ContentPage or IndexPage)> + + (end diagram) + + + Unframed Search Results Popup Page: + + (start diagram) + + <body PopupSearchResultsPage> + [browser styles] + + <#Index> + Index + </#Index> + + [browser styles] + </body PopupSearchResultsPage> + + (end diagram) + + + Framed Menu Page: + + (start diagram) + + <body FramedMenuPage> + [browser styles] + + <#Menu> + Menu + </#Menu> + + <#Footer> + Footer + </#Footer> + + [browser styles] + </body FramedMenuPage> + + (end diagram) + + + Framed Content/Index/SearchResults Page: + + (start diagram) + + <body FramedContentPage or FramedIndexPage or FramedSearchResultsPage> + [browser styles] + + <#Content or #Index> + Content or Index + </#Content or #Index> + + [browser styles] + </body FramedContentPage or FramedIndexPage or FramedSearchResultsPage> + + (end diagram) + + +Styles: Page Styles + + ContentPage - An unframed content page. + IndexPage - An unframed index page. + PopupSearchResultsPage - A search results page for use in a popup iframe. + + FramedContentPage - A framed content page. + FramedIndexPage - A framed index page. + FramedSearchResultsPage - A framed search results page. + + #Footer - The page footer. Will be in a framed menu page or on its own in a non-framed page. + + See Also: + + - <#Content> + - <#Menu> + - <#Index> + - <#Footer> + + + + +Styles: Browser Styles +_______________________________________________________________________________ + + + Natural Docs pages include JavaScript to detect which browser the user is running and apply styles so that you can work + around browser quirks right in the CSS file. + + The browser type and version styles will be applied immediately after the body tag. However, neither are guaranteed to be + there; the user may have JavaScript turned off or be using a browser that isn't detected. These styles should only be used to + correct minor flaws and should not be heavily relied on. + + > <body> + > <browser type>? + > <browser version>? + > + > Page Content + > + > <browser version>? + > <browser type>? + > </body> + + For example, if a <CTopic>'s style is giving you problems in Internet Explorer 6, override it with .IE6 .CTopic. If a <MTitle>'s + style gives you a problem in Opera 7 but only in frames, override it with .Framed.Opera7 .MTitle. + + Browser Types: + + If the browser is not one of the types below, neither this nor the browser version will be present. There's the possibility that + some obscure browser will appear as one of the others by spoofing, but the most prominent of these, Opera, Konqueror, and + Safari, are taken care of. + + IE - Internet Explorer + Firefox - Firefox and anything else based on the Gecko rendering engine. + Opera - Opera + Safari - Safari + Konqueror - Konqueror and anything else based on the KHTML rendering engine except Safari. + + Browser Versions: + + If the browser is not one of the versions below, this style will not be present. The browser type still may be. + + IE6 - Internet Explorer 6.x. + IE7 - Internet Explorer 7.x. + + Firefox1 - Firefox 1.0.x and anything else based on Gecko 1.7.x. + Firefox15 - Firefox 1.5.x and anything else based on Gecko 1.8.0.x. + Firefox2 - Firefox 2.0.x and anything else based on Gecko 1.8.1.x. + + Opera7 - Opera 7.x. + Opera8 - Opera 8.x. + Opera9 - Opera 9.x. + + Safari2 - Safari 2.x. + Safari3 - Safari 3.x. + + Notes: + + Why not apply them to the body tag itself? The JavaScript is easy enough and everything supports multiple classes, right? + Because IE 6 doesn't support multiple selectors so I wouldn't be able to combine browser and page styles. + .Opera.ContentPage will apply to all ContentPages in IE because it treats it as if only the last class is there. + + + + +Topic: Content Structure +_______________________________________________________________________________ + + + All the topics of a given file is contained in a <#Content>. All other content styles are prefixed with a C. + + Surrounding each piece of content is a <CTopic> and its type; for example, CFunction for a function. Inside that are the + <CTitle> and if necessary, <CBody>. Inside <CBody> are analogues to all the top-level <NDMarkup> tags: <h1>, <p>, etc. + + In addition to the top-level <NDMarkup> tags, you also have prototypes, class hierarchies, and summaries which are + described in their own sections. + + (start diagram) + + <#Content> + + <CType (CFunction, CVariable, etc.)> + <CTopic and #MainTopic?> + + <CTitle> + Topic title + </CTitle> + + <CBody> + + [Class Hierarchy] + + [Prototype] + + <CHeading> + Heading + <CHeading> + + <p> + Paragraph + </p> + + <pre> + Code or text diagram + </pre> + + <ul> + <li> + Bullet item + </li> + </ul> + + <CImageCaption>? + Caption + </CImageCaption>? + <img> + + <a CImageLink> + text + </a CImageLink> + + <table CDescriptionList> + <tr> + <td CDLEntry> + Entry + </td CDLEntry> + <td CDLDescription> + Description + </td CDLDescription> + </tr> + </table CDescriptionList> + + [Summary] + + </CBody> + + </CTopic and #MainTopic?> + </CType (CFunction, CVariable, etc.)> + + </#Content> + + (end diagram) + + Take advantange of the CSS inheritance model. For example, you can style all titles via .CTitle, and you can style + specific titles with .CType .CTitle. + + +Styles: Content Styles + + #Content - Parent element containing all topics. + + CTopic - An individual topic. + + CTitle - The title of a topic. + CBody - The body of a topic. May not exist. + CHeading - Surrounds a heading. + CImageCaption - Surrounds an image caption. + CImageLink - Surrounds a link to an image. + + CDescriptionList - A description list, which is the type of list you're reading right now. Is implemented with a table. + CDLEntry - A description list entry, which is the left side. + CDLDescription - A description list description, which is the right side. + + #MainTopic - The ID given to the main topic, which is the first in the file. It is applied to the <CTopic>. + + CType - A placeholder for all type-specific styles. The actual styles will be C followed by the alphanumeric-only topic type name. + So the CType of a "PL/SQL Function" topic will actually be CPLSQLFunction. + + + + +Topic: Menu Structure +_______________________________________________________________________________ + + + Everything is enclosed in a <#Menu>. All other menu styles are prefixed with an M. + + The title is an <MTitle> and will always be at the beginning of the menu if it exists. If a subtitle exists as well, it will appear + as an <MSubTitle> inside <MTitle>. Subtitles aren't allowed without titles. Most other entries in the menu are contained in + <MEntries>. Here's the diagram: + + (start diagram) + + <#Menu> + + <MTitle> + Menu title + + <MSubTitle> + Menu sub title + </MSubTitle> + + </MTitle> + + <MEntry> + <MFile (and #MSelected?)> + <a href>File</a href> + </MFile> + </MEntry> + + <MEntry> + <MIndex (and #MSelected?)> + <a href>File</a href> + </MIndex> + </MEntry> + + <MEntry> + <MText> + Text + </MText> + </MEntry> + + <MEntry> + <MLink> + <a href>Link</a href> + </MLink> + </MEntry> + + <MEntry> + <MGroup> + <a href>Group</a href> + <MGroupContent> + + (MEntries) + + </MGroupContent> + </MGroup> + </MEntry> + + <#MSearchPanel and MSearchPanelActive/Inactive> + <input #MSeachField> + <select #MSearchType> + <option #MSearchEverything> + <option> + <option> + </select #MSearchType> + </#MSearchPanel and MSearchPanelActive/Inactive> + + </#Menu> + + (if in unframed HTML) + <#MSearchResultsWindow> + + <iframe #MSearchResults> + </iframe #MSearchResults> + + <a #MSearchResultsWindowClose> + + </#MSearchResultsWindow> + + (end) + + The <MFile> or <MIndex> entry that's currently selected will have the <#MSelected> ID, so you can reference it in CSS via + .MFile#MSelected. + + The search panel is has its own ID, <#MSearchPanel>, but also has one of the classes <MSearchPanelActive> or + <MSearchPanelInactive> depending on whether any of the controls are selected or the results window is open. + <#MSearchResultsWindow> is separate because it may be floating. + + +Styles: Menu Styles + + #Menu - Parent element containing the entire menu. + + MTitle - The title of the menu. + MSubTitle - The subtitle of the menu. Will appear within <MTitle>. + + MFile - A file entry. + MGroup - A group entry. + MGroupContent - A container for a <MGroup's> content. + MText - A plain text entry. + MLink - An external link entry. + MIndex - An index entry. + + #MSelected - The ID of the currently selected <MFile> or <MIndex>. + + MType - <MFile>, <MGroup>, <MText>, <MLink>, or <MIndex>. + + #MSearchPanel - Contains all the search controls. + MSearchPanelActive - Applied to <#MSearchPanel> when any of the controls are selected or the results window is open. + MSearchPanelInactive - Applied to <#MSearchPanel> when not in use. + + #MSearchField - The text input field of the search panel. + #MSearchType - The drop down type selector of the search panel. + #MSearchEverything - The <#MSearchType> option for the Everything index. + + #MSearchResultsWindow - Contains all the search results elements. + #MSearchResults - Contains the iframe that will hold the results. + #MSearchRseultsWindowClose - The link to manually close the search results window. + + + + +Topic: Class Hierarchy Structure +_______________________________________________________________________________ + + + Everything is contained in a single <ClassHierarchy>. Each entry is surrounded by its type, such as <CHParent>, and the + generic <CHEntry>. Depending on the context, entries may be surrounded by one or more <CHIndents>. + + (start diagram) + + <ClassHierarchy> + + <CHIndent>? + + <CHType> + <CHEntry> + + <a href>? + Entry + </a href> + + </CHEntry> + </CHType> + + </CHIndent>? + + </ClassHierarchy> + + (end diagram) + + +Styles: Class Hierarchy Styles + + ClassHierarchy - The topmost style containing everything. + + CHEntry - A generic class entry. + + CHParent - The style for a parent class. + CHCurrent - The style for the current class, which is the one the hierarchy is generated for. + CHChild - The style for a child class. + CHChildNote - The style for when a child is added that just shows how many other children were omitted. + + CHIndent - A style used to indent a level. + + CHType - <CHParent>, <CHCurrent>, <CHChild>, or <CHChildNote>. + + + + +Topic: Summary Structure +_______________________________________________________________________________ + + + Everything is enclosed in a single <Summary>. All the other summary styles are prefixed with an S. + + <STitle> holds the actual word "Summary" and <SBorder> and <STable> hold the content. <SBorder> exists because different + browsers apply table padding attributes in different ways. <STable> exists as a class to separate the main table from any other + tables that may be necessary. Here's a diagram: + + > <Summary> + > + > <STitle> + > Title + > </STitle> + > + > <SBorder> + > <table STable> + > ... + > </table STable> + > </SBorder> + > + > </Summary> + + On to the table content. + + > <tr SType and SEntry (and SIndent#?) (and SMarked?)> + > <td SEntry> + > + > <a href>Entry</a href> + > + > </td SEntry> + > <td SDescription> + > + > Description + > + > </td SDescription> + > </tr SType and SEntry (and SIndent#?) (and SMarked?)> + + <SIndent#> exist to allow indenting. They're necessary because implementing it as nested tables, while structurally cleaner, + won't allow the desciptions to line up on the right throughout the entire summary. <SMarked> will be applied on almost every + other row to allow for tinting to improve readability. + + Use the power of CSS's inheritance rules to specify styles. For example, to set the style of a group entry, apply it to + .SGroup .SEntry. However, you could also apply a style to both the group's entry and description by applying the + style to .SGroup td. Or, you could apply a style to all the entries by applying it to .SEntry. And so on. + + +Styles: Summary Styles + + Summary - The topmost style containing the entire summary. + + STitle - Contains the summary title, which is the part that actually says "Summary". + + SBorder - Surrounds <STable>, since some browsers can't do table padding right. A hack, I know. + STable - The actual summary table. This class separates it from other layout tables that may appear. + + SMarked - A class applied to rows that should have a slightly different color than the rest of the rows to make them easier to + read. + + SEntry - The entry (left) side of the table. + SDescription - The description (right) side of the table. + + SIndent# - Surrounding entries and descriptions that are part of a group and need to be indented. Actual styles will be + SIndent1, SIndent2, etc. + + SType - A placeholder for all topic-specific styles. The actual styles will be S followed by the alphanumeric-only topic type name. + So the SType of a "PL/SQL Function" topic will actually be SPLSQLFunction. + + + + +Topic: Prototype Structure +_______________________________________________________________________________ + + + Everything is enclosed in a <Prototype>. All other styles are prefixed with a P. + + Parameter Type First Style: + + For prototypes such as + > void Function (unsigned int* a, int b = 0) + where the types come first. + + (start diagram) + + <table Prototype> + + <td PBeforeParameters> + "void Function (" + </td PBeforeParameters> + + <td PTypePrefix> + "unsigned" + </td PTypePrefix> + + <td PType> + "int" + </td PType> + + <td PParameterPrefix> + "*" + </td PParameterPrefix> + + <td PParameter> + "a", "b" + </td PParameter> + + <td PDefaultValuePrefix> + "=" + </td PDefaultValuePrefix> + + <td PDefaultValue> + "0" + </td PDefaultValue> + + (repeated as necessary) + + <td PAfterParameters> + ")" + </td PAfterParameters> + + </table Prototype> + + (end diagram) + + + Parameter Name First Style: + + For prototypes such as + > function Function (a, b: int; c: int := 0) + where the parameters come first. + + (start diagram) + + <table Prototype> + + <td PBeforeParameters> + "function Function (" + </td PBeforeParameters> + + <td PParameter> + "a,", "b:", "c:" + </td PParameter> + + <td PType> + "int" + </td PType> + + <td PDefaultValuePrefix> + ":=" + </td PDefaultValuePrefix> + + <td PDefaultValue> + "0" + </td PDefaultValue> + + (repeated as necessary) + + <td PAfterParameters> + ")" + </td PAfterParameters> + + </table Prototype> + + (end diagram) + + + Note that any section may not exist. For example, there will be no <PTypePrefix> cells generated if none of the parameters + have it. + + +Styles: Prototype Styles + + Prototype - The style encompassing the entire prototype. + + PBeforeParameters - The part of the prototype that comes before the parameters. + PAfterParameters - The part of the prototype that comes after the parameters. + + PType - The parameter type. + PTypePrefix - The prefix of a parameter type. + PParameter - The parameter name. + PParameterPrefix - The prefix of a parameter name. + PDefaultValue - The default value expression for a parameter. + PDefaultValuePrefix - The prefix of the default value expression. + + + + +Topic: Link Structure +_______________________________________________________________________________ + + + All links to symbols have a type style prefixed with L. The only exceptions are summary entries; summary descriptions use + them as well. + + > <a LType> + > Link + > </a LType> + + You can use this to make links to different symbols appear in different styles. For example, making .LClass bold will make all + links to classes bold, except when appearing in summary entries. You can combine this with other styles to be even more + specific. For example, you can apply a style to function links appearing in summary descriptions with .SDescription .LFunction. + +Styles: Link Styles + + LType - A placeholder for all topic-specific styles. The actual styles will be L followed by the alphanumeric-only topic type name. + So the LType of a "PL/SQL Function" topic will actually be LPLSQLFunction. + + + +Topic: Index Structure +_______________________________________________________________________________ + + + Everything is enclosed in an <#Index>. Combine with <Framed> and <Unframed> to distinguish between output formats. All + other index styles are prefixed with an I. + + (start diagram) + + <#Index> + + <IPageTitle> + Page Title + </IPageTitle> + + <INavigationBar> + A - <a href>B</a href> - C ... + </INavigationBar> + + <table> + + <IHeading> + Heading (A, B, etc.) + </IHeading> + + <td ISymbolPrefix> + Prefix, if any + </td ISymbolPrefix> + + <td IEntry> + Entry + </td IEntry> + + ... + + </table> + + </#Index> + + (end diagram) + + Every index entry, including headings, are rows in a table. The first column of a non-heading are <ISymbolPrefixes> so that + the non-prefix portions align correctly. The other column are <IEntries>, of which there are multiple formats, described below. + + (start diagram) + + <a href ISymbol> + Symbol + </a href ISymbol>, + <IParent> + Class + </IParent> + + <ISymbol> + Symbol + </ISymbol> + <ISubIndex> + <a href IParent> + Class + </a href IParent> + ... + </ISubIndex> + + <ISymbol> + Symbol + </ISymbol> + <ISubIndex> + <IParent> + Class + </IParent> + <ISubIndex> + <a href IFile> + File + </a href IFile> + ... + </ISubIndex> + ... + </ISubIndex> + + (end diagram) + + Each part of the entry is surrounded by its type, which may or may not be a link. If an entry has more than one defining class + or file, they're broken out into <ISubIndexes>. + + It's called <IParent> instead of <IClass> because class entries are <ISymbols>. <IParents> are only used when the symbol + has a class. If the symbol _is_ a class, the symbol is global. + + +Styles: Index Styles + + #Index - Parent element for the entire index. + + IPageTitle - The page title. + INavigationBar - The navigation bar. + + IHeading - An index heading, such as the letter for the group. + + IEntry - An entry in the index. + ISymbolPrefix - The stripped prefix of the entry. + ISymbol - The entry symbol. + IParent - The entry parent class. If the entry _is_ a class, this isn't defined because classes are global and don't have parent + classes. This is why it's called IParent instead of IClass; hopefully it's less confusing. + IFile - The file the entry is defined in. + + ISubIndex - The surrounding block if an entry needs to be broken out into a sub-index. + + #IFirstHeading - The ID of the first <IHeading> to appear in the file. + + #IFirstSymbolPrefix - The ID for the first <ISymbolPrefix> to appear under an <IHeading>. + #ILastSymbolPrefix - The ID for the last <ISymbolPrefix> to appear under an <IHeading>. + #IOnlySymbolPrefix - The ID if there is only one <ISymbolPrefix> for an <IHeading>. + + + +Topic: Search Results Structure +_______________________________________________________________________________ + + + The search results use virtually the same structure and styles as the indexes, except that <#SearchResults> replaces + <#Index>, there's a new <SRResult> style, and there are a few additional <SRStatus> blocks. + + Visibility: + + Visibility is *very* important to making the search work correctly. JavaScript will handle most of it, but your CSS needs to + abide by these rules. + + - <SRStatus> sections are visible by default. + - <SRResult> sections are *not* visible by default. They must use display: none. + - <ISubIndex> should be display: none when under <#SearchResults>. + + +Styles: Search Results Styles + + #SearchResults - Parent element for the entire page. + SRStatus - Status message. Must be visible by default. + SRResult - A result. All you need to do for this class is set it to display: none. Nothing else should be set on it. + + + + +Topic: Tool Tip Structure +_______________________________________________________________________________ + + + Tool tips may appear anywhere in the page, mainly because it's assumed that they will use position: absolute and + visibility: hidden. + + The entire tool tip is found in a <CToolTip> style, with a CType style inside it. CTypes are normally outside their elements, but + that would cause it to be partially visible in this case. We need <CToolTip> to be the outermost style so its visibility and + position can be manipulated in JavaScript. + + Inside there's a <CPrototype> and/or the description text. The description text has no special surrounding tags. + + > <CToolTip> + > + > <CPrototype> + > Prototype + > </CPrototype> + > + > Summary text + > + > </CToolTip> + +Styles: Tool Tip Styles + + CToolTip - Surrounds the entire tool tip. This *must* have position: absolute and visibility: hidden for the tool tip mechanism + to work. + + See also <CPrototype>. + + +Styles: Miscellaneous Styles + + blockquote - This HTML element should surround anything that needs to be scrolled if it's too wide, like prototypes and text + diagrams. It's not a style because this makes it much easier to do the JavaScript necessary to get this working + in IE. + + +Group: History + +Topic: Revisions +_______________________________________________________________________________ + + + How the page structure has changed throughout the various releases. + + 1.4: + + - Replaced UnframedPage with <ContentPage> and <IndexPage>. + - Added <#Menu>, <#Content>, <#Footer>, and <#Index>. They were previously shown in the diagrams as classes but did + not actually appear in the generated output. + - Removed MenuSection, ContentSection, and IndexSection. Use things like ".ContentPage #Menu" instead. + - Removed tables from the unframed <Page Structure>. Use CSS to position the elements instead. + - <#MainTopic> is applied to <CTopic> instead of <CType>. + - IE4, IE5, Opera5, Opera6, Netscape, and Netscape4 browser styles have been removed. <IE7>, <Opera8>, + and <Opera9> have been added. Gecko has been replaced by <Firefox>, <Firefox1>, <Firefox15>, and <Firefox2>. + KHTML has been replaced by <Safari>, <Safari2>, <Safari3>, and <Konqueror>. + - Removed redundant CParagraph, CCode, and CBulletList classes. Use <CBody> with p, pre, and ul instead. + - Added <CImageCaption> and <CImageLink>. + - Added <#MSearchPanel>, <#MSearchResultsWindow>, and all related styles. + - Added <Search Results Structure>, <Search Results Styles>, and <FramedSearchResultsPage>. + - Removed SEntrySize. Apply the width to <SEntry> and <SDescription> instead. + - <SType>, <SEntry>, and <SIndent#> were moved from the td and divs into the tr. + - Removed HB style. Now using wbr tag. + + 1.33: + + - Added <PDefaultValuePrefix>. + + 1.32: + + - <blockquotes> now surround elements that should scroll if they're too wide for the page. + + 1.3: + + - Removed CPrototype. See the replacement <Prototype Structure> and <Prototype Styles>. + - Removed SInGroup, SInClass, and SInSection in favor of more general <SIndent#>. + - <CTypes>, <STypes>, and <LTypes> are now completely determined by <Topics.txt> configuration files. + - <CTypes>, <STypes>, and <LTypes> no longer have separate list types. A CFunctionList is now just a CFunction. + - Indexes are now done with tables. + - ISection was removed. + - <IEntries> are only used for the entry cell, not for each entry in an <ISubIndex>. + - Added <ISymbolPrefix>, related IDs, and <#IFirstHeading>. + - Merged <CType> and <CTopic> into the same element. Must now be styled with .CType.CTopic (no space) while all + sub-elements will still be .CType .CElement (with space.) + + 1.21: + + - Added <TOPIC_PROPERTY> and TOPIC_PROPERTY_LIST styles, so they get corresponding <CTypes>, <STypes>, and + <LTypes>. + + 1.2: + + - Added <Class Hierarchy Styles> since 1.2 added class hierarchies. + + 1.16: + + - Changed the first topic from having a CMain type to having a normal type with a <#MainTopic> ID. + + 1.1: + + - Added <Tool Tip Styles>. + - Renamed HiddenBreak to <HB>. + - Added <TOPIC_CONSTANT>, TOPIC_CONSTANT_LIST, <TOPIC_TYPE>, and TOPIC_TYPE_LIST types, so they get + corresponding <CTypes>, <STypes>, and <LTypes>. + + 1.0: + + - The <CType> tags now appear arround the <CTopic> tags instead of vice versa. + - Added a <CBody> tag to surround non-<CTitle> elements. + - <SMarked> now appears in tr's instead of td's, where it belonged in the first place. + + 0.95: + + - Added <Browser Styles>. + - Redid <Page Structure>, replacing generic styles like Menu with page type styles like UnframedPage/MenuSection and + FramedMenuPage. + + 0.91: + + - Added <LURL> and <LEMail> link styles, since 0.91 added URL and e-mail links. + - Added <ISection> style, which is better than <IHeading> floating on its own. + + 0.9: + + - Added <Index Styles>, since 0.9 added indexes. + diff --git a/docs/tool/Info/File Parsing.txt b/docs/tool/Info/File Parsing.txt new file mode 100644 index 00000000..10bd0e91 --- /dev/null +++ b/docs/tool/Info/File Parsing.txt @@ -0,0 +1,83 @@ + + Architecture: File Parsing + +#################################################################################### + + This is the architecture and code path for general file parsing. We pick it up at <NaturalDocs::Parser->Parse()> because we're not interested in how the files are gathered and their languages determined for the purposes of this document. We are just interested in the process each individual file goes through when it's decided that it should be parsed. + + + + Stage: Preparation and Differentiation + _______________________________________________________________________________________________________ + + <NaturalDocs::Parser->Parse()> can be called from one of two places, <NaturalDocs::Parser->ParseForInformation()> and <NaturalDocs::Parser->ParseForBuild()>, which correspond to the parsing and building phases of Natural Docs. There is no noteworthy work done in either of them before they call Parse(). + + + Stage: Basic File Processing + _______________________________________________________________________________________________________ + + The nitty-gritty file handling is no longer done in <NaturalDocs::Parser> itself due to the introduction of full language support in 1.3, as it required two completely different code paths for full and basic language support. Instead it's handled in NaturalDocs::Languages::Base->ParseFile(), which is really a virtual function that leads to <NaturalDocs::Languages::Simple->ParseFile()> for basic language support or a version appearing in a package derived from <NaturalDocs::Languages::Advanced> for full language support. + + The mechinations of how these functions work is for another document, but their responsibility is to feed all comments Natural Docs should be interested in back to the parser via <NaturalDocs::Parser->OnComment()>. + + + Stage: Comment Processing + _______________________________________________________________________________________________________ + + <NaturalDocs::Parser->OnComment()> receives the comment sans comment symbols, since that's language specific. All comment symbols are replaced by spaces in the text instead of removed so any indentation is properly preserved. Also passed is whether it's a JavaDoc styled comment, as that varies by language as well. + + OnComment() runs what it receives through <NaturalDocs::Parser->CleanComment()> which normalizes the text by removing comment boxes and horizontal lines, expanding tabs, etc. + + + Stage: Comment Type Determination + _______________________________________________________________________________________________________ + + OnComment() sends the comment to <NaturalDocs::Parser::Native->IsMine()> to test if it's definitely Natural Docs content, such as by starting with a recognized header line. If so, it sends it to <NaturalDocs::Parser::Native->ParseComment()>. + + If not, OnComment() sends the comment to <NaturalDocs::Parser::JavaDoc->IsMine()> to test if it's definitely JavaDoc content, such as by having JavaDoc tags. If so, it sends it to <NaturalDocs::Parser::JavaDoc->ParseComment()>. + + If not, the content is ambiguous. If it's a JavaDoc-styled comment it goes to <NaturalDocs::Parser::Native->ParseComment()> to be treated as a headerless Natural Docs comment. It is ignored otherwise, which lets normal comments slip through. Note that it's only ambiguous if neither parser claims it; there's no test to see if they both do. Instead Natural Docs always wins. + + We will not go into the JavaDoc code path for the purposes of this document. It simply converts the JavaDoc comment into <NDMarkup> as best it can, which will never be perfectly, and adds a <NaturalDocs::Parser::ParsedTopic> to the list for that file. Each of those ParsedTopics will be headerless as indicated by having an undefined <NaturalDocs::Parser::ParsedTopic->Title()>. + + + Stage: Native Comment Parsing + _______________________________________________________________________________________________________ + + At this point, parsing is handed off to <NaturalDocs::Parser::Native->ParseComment()>. It searches for header lines within the comment and divides the content into individual topics. It also detects (start code) and (end) sections so that anything that would normally be interpreted as a header line can appear there without breaking the topic. + + The content between the header lines is sent to <NaturalDocs::Parser::Native->FormatBody()> which handles all the block level formatting such as paragraphs, bullet lists, and code sections. That function in turn calls <NaturalDocs::Parser::Native->RichFormatTextBlock()> on certain snippets of the text to handle all inline formatting, such as bold, underline, and links, both explicit and automatic. + + <NaturalDocs::Parser::Native->ParseComment()> then has the body in <NDMarkup> so it makes a <NaturalDocs::Parser::ParsedTopic> to add to the list. It keeps track of the scoping via topic scoping, regardless of whether we're using full or basic language support. Headerless topics are given normal scope regardless of whether they might be classes or other scoped types. + + + Group: Post Processing + _______________________________________________________________________________________________________ + + After all the comments have been parsed into ParsedTopics and execution has been returned to <NaturalDocs::Parser->Parse()>, it's time for some after the fact cleanup. Some things are done like breaking topic lists, determining the menu title, and adding automatic group headings that we won't get into here. There are two processes that are very relevant though. + + + Stage: Repairing Packages + _______________________________________________________________________________________________________ + + If the file we parsed had full language support, the <NaturalDocs::Languages::Advanced> parser would have done more than just generate various OnComment() calls. It would also return a scope record, as represented by <NaturalDocs::Languages::Advanced::ScopeChange> objects, and a second set of ParsedTopics it extracted purely from the code, which we'll refer to as autotopics. The scope record shows, purely from the source, what scope each line of code appears in. This is then combined with the topic scoping to update ParsedTopics that come from the comments in the function <NaturalDocs::Parser->RepairPackages()>. + + If a comment topic changes the scope, that's honored until the next autotopic or scope change from the code. This allows someone to document a class that doesn't appear in the code purely with topic scoping without throwing off anything else. Any other comment topics have their scope changed to the current scope no matter how it's arrived at. This allows someone to manually document a function without manually documenting the class and still have it appear under that class. The scope record will change the scope to part of that class even if topic scoping did not. Essentially the previous topic scoping is thrown out, which I guess is something that can be improved. + + None of this affects the autotopics, as they are known to have the correct scoping since they are gleaned from the code with a dedicated parser. Wouldn't there be duplication of manually documented code elements, which would appear both in the autotopics and in the comment topics? Yes. That brings us to our next stage, which is... + + + Stage: Merging Auto Topics + _______________________________________________________________________________________________________ + + As mentioned above, ParseFile() also returns a set of ParsedTopics gleaned from the code called autotopics. The function <NaturalDocs::Parser->MergeAutoTopics()> merges this list with the comment topics. + + The list is basically merged by line number. Since named topics should appear directly above the thing that they're documenting, topics are tested that way and combined into one if they match. The description and title of the comment topic is merged with the prototype of the autotopic. JavaDoc styled comments are also merged in this function, as they should appear directly above the code element they're documenting. Any headerless topics that don't, either by appearing past the last autotopic or above another comment topic, are discarded. + + + Stage: Conclusion + _______________________________________________________________________________________________________ + + Thus ends all processing by <NaturalDocs::Parser->Parse()>. The file is now a single list of <NaturalDocs::Parser::ParsedTopics> with all the body content in <NDMarkup>. If we were using <NaturalDocs::Parser->ParseForBuild()>, that's pretty much it and it's ready to be converted into the output format. If we were using <NaturalDocs::Parser->ParseForInformation()> though, the resulting file is scanned for all relevant information to feed into other packages such as <NaturalDocs::SymbolTable>. + + Note that no prototype processing was done in this process, only the possible tranferring of prototypes from one ParsedTopic to another when merging autotopics with comment topics. Obtaining prototypes and formatting them is handled by <NaturalDocs::Languages::Simple> and <NaturalDocs::Languages::Advanced> derived packages. diff --git a/docs/tool/Info/HTMLTestCases.pm b/docs/tool/Info/HTMLTestCases.pm new file mode 100644 index 00000000..343b45a8 --- /dev/null +++ b/docs/tool/Info/HTMLTestCases.pm @@ -0,0 +1,269 @@ +############################################################################### +# +# File: Browser Testing +# +############################################################################### +# +# This file tests Natural Docs' generated output. Particularly useful when testing various browsers. +# +############################################################################### + +# This file is part of Natural Docs, which is Copyright (C) 2003-2008 Greg Valure +# Natural Docs is licensed under the GPL + +use strict; +use integer; + + +# +# About: Browsers +# +# The specific browser versions tested are below. Everything is tested on Windows Vista unless otherwise noted. +# +# Firefox 2.0.0.10 - 2.0 released October 2006. +# Firefox 1.5.0.8 - 1.5 released Novemer 2005. +# Firefox 1.0.8 - 1.0 released November 2004. Not critical to support. +# +# IE 7.0 - 7.0 released October 2006. +# IE 6.0 - 6.0 released August 2001. Tested on Windows XP SP2 via Virtual PC. +# +# Safari 3.0.4 - 3.0 released June 2007. Tested Windows version. +# Safari 2.0.4 - 2.0 released April 2005. Tested on Mac OS X 10.4 Tiger. +# +# Opera 9.02 - 9.0 released June 2006. +# Opera 8.54 - 8.5 released September 2005. +# Opera 8.02 - 8.0 released April 2005. +# Opera 7.51 - 7.5 released around August 2004 I think. Not critical to support. +# Opera 7.02 - 7.0 released January 2003. Not critical to support. +# +# Konqueror 3.5.5 - Tested on openSUSE 10.2 via VMware Player. +# + + +############################################################################### +# Group: Search + +# +# Topic: Unframed HTML Search +# +# Tests: +# +# - Make sure the search box appears and disappears correctly on hover. +# - Type to bring up results. Type further to narrow them. Narrow until there's no results. +# - Backspace to bring the results back. Backspacing to empty closes the results. +# - Type to bring up results with a different first letter. (Tests iframe content switch.) +# - Type *Z* to bring up empty page when there's nothing with that first letter. (Tests generic no results page.) +# - Type *Name* in Everything search to test expanding and collapsing, especially between two that differ only by case. +# - Change filter to *Functions* to test changing filter while results are open. Change to *Types* to switch to one with +# no results. +# - Test Close button on results. Should deactivate panel as well. +# - Clicking away should deactivate panel if the box is empty, not have an effect if there are results open. +# - Text should always change back to "Search" when deactivating. +# +# Results: +# +# Firefox 2.0 - OK +# Firefox 1.5 - OK +# Firefox 1.0 - OK +# +# IE 7.0 - OK +# IE 6.0 - Functionally OK. Search panel doesn't activate on hover. Works fine when clicked. +# +# Safari 3.0 - OK +# Safari 2.0 - *Broken.* Results panel doesn't show up. Border around deactivated search box. +# +# Opera 9.0 - OK +# Opera 8.5 - OK +# Opera 8.0 - OK +# Opera 7.5 - Functionally OK. Search panel has sunken border when deactivated, minor pixel shifting. +# Opera 7.0 - *Broken.* Completely. +# +# Konqueror 3.5 - *Broken.* Results panel doesn't show up. Seems to fail on "resultsFrame = window.frames.MSearchResults;" +# + +# +# Topic: Framed HTML Search +# +# Tests: +# +# - Make sure the search box appears and disappears correctly on hover. +# - Type to bring up results on right. Type further to narrow them. Narrow until there's no results. +# - Backspace to bring the results back. +# - Type to bring up results with a different first letter. (Tests frame content switch.) +# - Type *Z* to bring up empty page when there's nothing with that first letter. (Tests generic no results page.) +# - Type *Name* in Everything search to see that there's no collapsing in this mode. +# - Change filter to *Functions* to test changing filter while results are open. Change to *Types* to switch to one with +# no results. +# - Clicking away should deactivate panel. +# - Clicking a result should deactivate panel and show up in correct frame. +# - Text should always change back to "Search" when deactivating. +# +# Results: +# +# Firefox 2.0 - OK +# Firefox 1.5 - OK +# Firefox 1.0 - OK +# +# IE 7.0 - OK +# IE 6.0 - Functionally OK. Search panel doesn't activate on hover, is a little wide. Works fine when clicked. +# +# Safari 3.0 - OK +# Safari 2.0 - Functionally OK. Has a sunken border around the deactivated seach field. +# +# Opera 9.0 - OK +# Opera 8.5 - OK +# Opera 8.0 - OK +# Opera 7.5 - Functionally OK. Search panel has sunken border when deactivated, minor pixel shifting. +# Opera 7.0 - *Broken.* +# +# Konqueror 3.5 - Functionally OK. Panel doesn't reset and deactivate when clicking a result link. +# + + +############################################################################### +# Group: Other + +# +# Topic: Images +# +# Tests: +# +# - Here is an embedded image on its own line. +# +# (see images/logo.png) +# +# - Here is a reference in the middle of a sentence, in the middle of a bullet list: (see images/logo.png) It should have been +# converted to a link with the image appearing below the bullet list and the file name used as a caption. Make sure the +# caption positions correctly. +# - Here's a link to a non-existent image, which should appear literally: (see images/doesntexist.jpg) +# - Here is an embedded image that doesn't exist on it's own line. +# +# (see images/doesntexist.png) +# +# - Here is a link using the "(see)" syntax which shouldn't be interpreted as an image link because it doesn't end with an +# acceptable extension. Also, links should still resolve because of that. (see <Framed HTML Search>) +# +# Results: +# +# Firefox 2.0 - OK +# Firefox 1.5 - OK +# Firefox 1.0 - OK +# +# IE 7.0 - OK +# IE 6.0 - OK +# +# Safari 3.0 - OK +# Safari 2.0 - OK +# +# Opera 9.0 - OK +# Opera 8.5 - OK +# Opera 8.0 - OK +# Opera 7.5 - OK +# Opera 7.0 - OK +# +# Konqueror 3.5 - OK + + +# +# Topic: Prototypes and Tooltips +# +# Hover over <NaturalDocs::Parser::JavaDoc->ParseComment()> and <NaturalDocs::Parser::JavaDoc->IsMine()> +# +# Tests: +# +# - A tooltip should appear about a second after you hover over the link above. +# - It should go away when you move the cursor away. +# - It shoud be positioned directly underneath with a slight gap. +# - The prototype should be formatted cleanly with each parameter on its own line and aligned in columns. +# - The asterisk should be in a separate column. +# - Test it with the link too close to the edge of the window so the pop-up has to shift left to fit. +# +# Results: +# +# Firefox 2.0 - OK +# Firefox 1.5 - OK +# Firefox 1.0 - OK +# +# IE 7.0 - OK +# IE 6.0 - OK +# +# Safari 3.0 - OK +# Safari 2.0 - OK +# +# Opera 9.0 - OK. Has its own tooltips turned on by default which can cover it up though. +# Opera 8.5 - OK. Has its own tooltips turned on by default which can cover it up though. +# Opera 8.0 - OK. Has its own tooltips turned on by default which can cover it up though. +# Opera 7.5 - OK. Has its own tooltips turned on by default which can cover it up though. +# Opera 7.0 - *Broken.* Usually works, if the window is too narrow may collapse completely. +# +# Konqueror 3.5 - OK +# + + +# +# Topic: Long code block scrolling +# +# Go to <Prototype Parameter Styles>. +# +# Tests: +# +# - Shrink the browser window so that a line extends past the end of it. Only the line should have a scrollbar, not the +# entire page. +# - Expand the browser window. The scrollbar should disappear. +# +# Results: +# +# Firefox 2.0 - OK +# Firefox 1.5 - OK +# Firefox 1.0 - OK +# +# IE 7.0 - OK +# IE 6.0 - OK +# +# Safari 3.0 - OK +# Safari 2.0 - OK +# +# Opera 9.0 - OK +# Opera 8.5 - OK +# Opera 8.0 - OK +# Opera 7.5 - OK +# Opera 7.0 - OK +# +# Konqueror 3.5 - OK +# + + +# +# Topic: Menu and Class Hierarchies +# +# Go to <NaturalDocs::Languages::Simple>. +# +# Tests: +# +# - Class hierarchy should look okay. +# - Make sure the menu hierarchy opens up on its own when the page is loaded. +# - You should be able to click on groups to open and close them. +# +# Results: +# +# Firefox 2.0 - OK +# Firefox 1.5 - OK +# Firefox 1.0 - OK +# +# IE 7.0 - OK +# IE 6.0 - OK +# +# Safari 3.0 - OK +# Safari 2.0 - OK +# +# Opera 9.0 - OK +# Opera 8.5 - OK +# Opera 8.0 - OK +# Opera 7.5 - OK +# Opera 7.0 - OK +# +# Konqueror 3.5 - OK +# + + +1; diff --git a/docs/tool/Info/Languages.txt b/docs/tool/Info/Languages.txt new file mode 100644 index 00000000..c564eb58 --- /dev/null +++ b/docs/tool/Info/Languages.txt @@ -0,0 +1,107 @@ + + Title: Language Notes +_______________________________________________________________________________ + + This is more for my personal reference than anything else. + + + ___________________________________________________________________________ + + Topic: Prototype Parameter Styles + ___________________________________________________________________________ + + Parameters via Commas, Typed via Spaces: + + > FunctionName ( type indentifier, type identifier = value, modifier type identifier ) + > FunctionName ( indentifier, identifier = value ) + + The general idea is that parameters are separated by commas. Identifiers cannot contain spaces. Types and modifiers, + if available, are separated from the identifiers with spaces. There may be an equals sign to set the default value. + + So parsing means splitting by commas, stripping everything past an equals sign for the default value, stripping everything + after the last space for the identifier, and the rest is the type. If there are no internal spaces after the default value is + stripped, it's all identifier. + + Note that internal parenthesis, brackets, braces, and angle brackets should be parsed out. They may be present in default + values or types and any commas and equal signs in them should not be included. + + Applies to C++, Java, C#, JavaScript, Python, PHP, Ruby. + + Applies to Perl as well, even though it doesn't have any real parameter declaration structure. Just adding it with comments + is fine. + + Parameters via Semicolons and Commas, Typed via Colons: + + > FunctionName ( identifier: type; identifier, identifier: type; identifier: type := value ) + + Parameters via semicolons, types via colons. However, there can be more than one parameter per type via commas. + Default values via colon-equals. + + Applies to Pascal, Ada. + + + SQL: + + > FunctionName ( identifier type, identifier modifier type, identifier type := value ) + + Parameters separated by commas. Identifiers come before the types and are separated by a space. Default values are + specified with colon-equals. + + > FunctionName @identifier type, @dentifier modifier type, @identifier type = value + + Microsoft's SQL uses equals instead of colon-equals, doesn't need parenthesis, and starts its parameter names with an @ + symbol. + + + Visual Basic: + + > FunctionName ( modifiers identifier as type, identifier = value ) + + Parameters separated by commas. Default values via equals. However, any number of modifiers may appear before the + identifier. Those modifiers are ByVal, ByRef, Optional, and ParamArray. + + + Tcl: + + > FunctionName { identifier identifier { whatever } } { code } + + Identifiers are specified in the first set of braces and have no commas. However, they can be broken out into sub-braces. + + + ___________________________________________________________________________ + + Topic: Syntax References + ___________________________________________________________________________ + + C++ - http://www.csci.csusb.edu/dick/c++std/syntax.html + + C# - http://msdn.microsoft.com/library/default.asp?url=/library/en-us/csspec/html/CSharpSpecStart.asp. Open in IE. + + Java - http://cui.unige.ch/db-research/Enseignement/analyseinfo/ + Ada - http://cui.unige.ch/db-research/Enseignement/analyseinfo/ + + SQL - http://cui.unige.ch/db-research/Enseignement/analyseinfo/, + <http://www.cs.umb.edu/cs634/ora9idocs/appdev.920/a96624/13_elems.htm>, or + <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/tsqlref/ts_tsqlcon_6lyk.asp?frame=true> (open in IE). + + JavaScript - http://academ.hvcc.edu/~kantopet/javascript/index.php + + Python - http://www.python.org/doc/2.3.4/ref/ref.html + + PHP - http://www.php.net/manual/en/langref.php + + Visual Basic - http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vbls7/html/vbspecstart.asp. Open in IE. + + Pascal - <http://pages.cpsc.ucalgary.ca/~becker/231/SyntaxDiagrams/pascal-syntax_files/frame.htm>. Open in IE. + + Ruby - http://www.rubycentral.com/book/ + + ActionScript 2 - <http://download.macromedia.com/pub/documentation/en/flash/fl8/fl8_as2lr.pdf> + ActionScript 3 - <http://download.macromedia.com/pub/documentation/en/flex/2/prog_actionscript30.pdf> + E2X - http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-357.pdf + + R - Somewhere on http://www.r-project.org. + + ColdFusion - <http://livedocs.macromedia.com/coldfusion/6/Developing_ColdFusion_MX_Applications_with_CFML/contents.htm> + + Eiffel - http://www.gobosoft.com/eiffel/syntax/ diff --git a/docs/tool/Info/NDMarkup.txt b/docs/tool/Info/NDMarkup.txt new file mode 100644 index 00000000..db1817af --- /dev/null +++ b/docs/tool/Info/NDMarkup.txt @@ -0,0 +1,91 @@ + + Architecture: NDMarkup +_______________________________________________________________________________ + +A markup format used by the parser, both internally and in <NaturalDocs::Parser::ParsedTopic> objects. Text formatted in +NDMarkup will only have the tags documented below. + + +About: Top-Level Tags + + All content will be surrounded by one of the top-level tags. These tags will not appear within each other. + + <p></p> - Surrounds a paragraph. Paragraph breaks will replace double line breaks, and single line breaks will + be removed completely. + + <code></code> - Surrounds code or text diagrams that should appear literally in the output. + + <h></h> - Surrounds a heading. + + <ul></ul> - Surrounds a bulleted (unordered) list. + <dl></dl> - Surrounds a description list, which is what you are reading. + + <img mode="inline" target="" original=""> - An inline image. Target contains the image target, and original contains the + original text in case it doesn't resolve. + + +About: List Item Tags + + These tags will only appear within their respective lists. + + <li></li> - Surrounds a bulleted list item. + <de></de> - Surrounds a description list entry, which is the left side. It will always be followed by a description list + description. + <ds></ds> - Surrounds a description list symbol. This is the same as a description list entry, except that the content + is also a referenceable symbol. This occurs when inside a list topic. This tag will always + be followed by a description list description. + <dd></dd> - Surrounds a description list description, which is the right side. It will always be preceded by a description + list entry or symbol. + +About: Text Tags + + These tags will only appear in paragraphs, headings, or description list descriptions. + + <b></b> - Bold + <i></i> - Italics + <u></u> - Underline + + <link target="" name="" original=""> - Surrounds a potential link to a symbol; potential because the target is not guaranteed to + exist. This tag merely designates an attempted link. Target is what is attempting to be + linked to, name is the text that should appear for a successful link, and original is the + original text in case the link doesn't resolve. + + <url target="" name=""> - An external link. There's no need for an original attribute because it will always be + turned into an actual link. + <email target="" name=""> - A link to an e-mail address. + + <img mode="link" target="" original=""> - An image link. Target contains the image target, and original contains the original + text in case it doesn't resolve. + + +About: Amp Chars + + These are the only amp chars supported, and will appear everywhere. Every other character will appear as is. + + & - The ampersand &. + " - The double quote ". + < - The less than sign <. + > - The greater than sign >. + +About: Tabs + + NDMarkup will not contain tab characters, only spaces. Any tab characters appearing in the source files will be + expanded/replaced as necessary. + + +About: General Tag Properties + + Since the tags are generated, they will always have the following properties, which will make pattern matching much + easier. + + - Tags and amp chars will always be in all lowercase. + - Properties will appear exactly as documented here. They will be in all lowercase, in the documented order, and will have no + extraneous whitespace. Anything appearing in the properties will have amp chars. + - All code is valid, meaning tags will always be closed, <li>s will only appear within <ul>s, etc. + + So, for example, you can match description list entries with /<de>(.+?)<\/de>/ and $1 will be the text. No surprises or + gotchas. No need for sophisticated parsing routines. + + Remember that for symbol definitions, the text should appear as is, but internally (such as for the anchor) they need to + be passed through <NaturalDocs::SymbolTable->Defines()> so that the output file is just as tolerant as + <NaturalDocs::SymbolTable>. diff --git a/docs/tool/Info/Symbol Management.txt b/docs/tool/Info/Symbol Management.txt new file mode 100644 index 00000000..fb2bad23 --- /dev/null +++ b/docs/tool/Info/Symbol Management.txt @@ -0,0 +1,59 @@ + + Architecture: Symbol Management + +#################################################################################### + + This is the architecture and code path for symbol management. This is almost exclusively managed by <NaturalDocs::SymbolTable>, but it's complicated enough that I want a plain-English walk through of the code paths anyway. + + An important thing to remember is that each section below is simplified initially and then expanded upon in later sections as more facets of the code are introduced. You will not get the whole story of what a function does by reading just one section. + + + + Topic: Symbol Storage + _______________________________________________________________________________________________________ + + Symbols are indexed primarily by their <SymbolString>, which is the normalized, pre-parsed series of identifiers that make it up. A symbol can have any number of definitions, including none, but can only have one definition per file. If a symbol is defined more than once in a file, only the first definition is counted. Stored for each definition is the <TopicType>, summary, and prototype. + + Each symbol that has a definition has one designated as the global definition. This is the one linked to by other files, unless that file happens to have its own definition which then takes precedence. Which definition is chosen is rather arbitrary at this point; probably the first one that got defined. Similarly, if the global definition is deleted, which one is chosen to replace it is completely arbitrary. + + Each symbol also stores a list of references to it. Note that references can be interpreted as multiple symbols, and each of those symbols will store a link back to the reference. In other words, every reference a symbol stores is one that _can_ be interpreted as that symbol, but that is not necessarily the interpretation the reference actually uses. A reference could have a better interpretation it uses instead. + + For example, suppose there are two functions, MyFunction() and MyClass.MyFunction(). The reference text "MyFunction()" appearing in MyClass can be interpreted as either MyClass.MyFunction(), or if that doesn't exist, the global MyFunction(). Both the symbols for MyFunction() and MyClass.MyFunction() will store that it's referenced by the link, even though the class scoped one serves as the actual definition. + + This is also the reason a symbol can exist that has no definitions: it has references. We want symbols to be created in the table for each reference interpretation, even if it doesn't exist. These are called potential symbols. The reason is so we know whether a new symbol definition fulfills an existing reference, since it may be a better interpretation for the reference than what is currently used. + + + + Topic: Reference Storage + _______________________________________________________________________________________________________ + + References are indexed primarily by their <ReferenceString>, which is actually an elaborate data structure packed into a string. It includes a <SymbolString> of the text that appears in the link and a bunch of other data that determines the rules by which the link can be resolved. For example, it includes the scope it appears in and any "using" statements in effect, which are alternate possible scopes. It includes the type of link it is (text links, the ones you explicitly put in comments, aren't the only kind) and resolving flags which encode the language-specific rules of non-text links. But the bottom line is the <ReferenceString> encodes everything that influences how it may be resolved, so if two links come up with the same rules, they're considered two definitions of the same reference. This is the understanding of the word "reference" that will used in this document. + + Like symbols, each reference stores a list of definitions. However, it only stores the name as all the other relevant information is encoded in the <ReferenceString> itself. Unlike a symbol, which can be linked to the same no matter what kind of definitions it has, references that are in any way different might be interpreted differently and so need their own distinct entries in the symbol table. + + References also store a list of interpretations. Every possible interpretation of the reference is stored and given a numeric score. The higher the score, the better it suits the reference. In the MyFunction() example from before, MyClass.MyFunction() would have a higher score than just MyFunction() because the local scope should win. Each interpretation has a unique score, there are no duplicates. + + So the symbol and reference data structures are complimentary. Each symbol has a list of every reference that might be interpreted as it, and every reference has a list of each symbol that it could be interpreted as. Again, objects are created for potential symbols (those with references but no definitions) so that this structure always remains intact. + + The interpretation with the highest score which actually exists is deemed the current interpretation of the reference. Unlike symbols where the next global definition is arbitrary, the succession of reference interpretations is very controlled and predictable. + + + Topic: Change Detection + _______________________________________________________________________________________________________ + + Change management is handled a couple of ways. First, there is a secondary file index in <NaturalDocs::SymbolTable> that stores which symbols and references are stored in each file. It doesn't have any information other than a list of <SymbolStrings> and <ReferenceStrings> since they can be used in the main structures to look up the details. If a file is deleted, the symbol table can then prune any definitions that should no longer be in the table. + + Another way deals with how the information parsing stage works. Files parsed for information just have their symbols and references added to the table regardless of whether this was the first time it was ever parsed or if it had been parsed before. If it had been parsed before, all the information from the previous parse should be in the symbol table and file indexes already. If a new symbol or reference is defined, that's fine, it's added to the table normally. However, if a symbol is redefined it's ignored because only the first definition matters. Also, this won't detect things that disappear. + + Enter watched files. <NaturalDocs::Parser> tells <NaturalDocs::SymbolTable> to designate a file as watched before it starts parsing it, and then says to analyze the changes when it's done. The watched file is a second index of all the symbols and references that were defined since the watch started, including the specific details on the symbol definitions. When the analysis is done, it compares the list of symbols and references to the one in the main file index. Any that appear in the main file index but not the watched one are deleted because they didn't show up the second time around. Any symbol definitions that are different in the watched file than the main file are changed to the former, since the first definition that appeared the second time around was different than the original. + + + Topic: Change Management + _______________________________________________________________________________________________________ + + When a symbol's global definition changes, either because it switches to another file or because the details of the current file's definition changed (prototype, summary, etc.) it goes through all the references that can be interpreted as that symbol, finds the ones that use it as their current definition, and marks all the files that define them for rebuilding. The links in their output files have to be changed to the new definition or at least have their tooltips updated. + + When a symbol's last definition is deleted, it goes through all the references that can be interpreted as that symbol, finds the ones that use it as their current definition, and has them reinterpreted to the definition with the next highest score. The files that define them are also marked for rebuilding. + + When a potential symbol's first definition is found, it goes through all the references that can be interpreted as it and sees if it can serve as a higher scored interpretation than the current one. If so, the interpretations are changed and all the files that define them are marked for rebuilding. + diff --git a/docs/tool/Info/images/Logo.png b/docs/tool/Info/images/Logo.png new file mode 100644 index 00000000..87395ec5 --- /dev/null +++ b/docs/tool/Info/images/Logo.png Binary files differ |
