From 61bfe2d70cae6be8c4086a210a5451135ccca9ea Mon Sep 17 00:00:00 2001 From: Magnus Auvinen Date: Sat, 2 Aug 2008 08:21:29 +0000 Subject: added doc tool --- docs/tool/Info/CSSGuide.txt | 947 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 947 insertions(+) create mode 100644 docs/tool/Info/CSSGuide.txt (limited to 'docs/tool/Info/CSSGuide.txt') 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 "
" + instead of "
". + + - 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) + + + [browser styles] + + <#Content or #Index> + Content or Index + + + <#Menu> + Menu + + + <#Footer> + Footer + + + [/browser styles] + + + (end diagram) + + + Unframed Search Results Popup Page: + + (start diagram) + + + [browser styles] + + <#Index> + Index + + + [browser styles] + + + (end diagram) + + + Framed Menu Page: + + (start diagram) + + + [browser styles] + + <#Menu> + Menu + + + <#Footer> + Footer + + + [browser styles] + + + (end diagram) + + + Framed Content/Index/SearchResults Page: + + (start diagram) + + + [browser styles] + + <#Content or #Index> + Content or Index + + + [browser styles] + + + (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. + + > + > ? + > ? + > + > Page Content + > + > ? + > ? + > + + For example, if a 's style is giving you problems in Internet Explorer 6, override it with .IE6 .CTopic. If a '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 and its type; for example, CFunction for a function. Inside that are the + and if necessary, . Inside are analogues to all the top-level tags:

,

, etc. + + In addition to the top-level tags, you also have prototypes, class hierarchies, and summaries which are + described in their own sections. + + (start diagram) + + <#Content> + + + + + + Topic title + + + + + [Class Hierarchy] + + [Prototype] + + + Heading + + +

+ Paragraph +

+ + 
+                        Code or text diagram
+
+ +
    +
  • + Bullet item +
    • +
+ + ? + Caption + ? + + + + text + + + + + + + +
+ Entry + + Description +
+ + [Summary] + + + + + + + + + (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 . + + 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 and will always be at the beginning of the menu if it exists. If a subtitle exists as well, it will appear + as an inside . Subtitles aren't allowed without titles. Most other entries in the menu are contained in + . Here's the diagram: + + (start diagram) + + <#Menu> + + + Menu title + + + Menu sub title + + + + + + + File + + + + + + File + + + + + + Text + + + + + + Link + + + + + + Group + + + (MEntries) + + + + + + <#MSearchPanel and MSearchPanelActive/Inactive> + + + + + + + (if in unframed HTML) + <#MSearchResultsWindow> + + + + + + + + (end) + + The or 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 or + 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 . + + MFile - A file entry. + MGroup - A group entry. + MGroupContent - A container for a content. + MText - A plain text entry. + MLink - An external link entry. + MIndex - An index entry. + + #MSelected - The ID of the currently selected or . + + MType - , , , , or . + + #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 . Each entry is surrounded by its type, such as , and the + generic . Depending on the context, entries may be surrounded by one or more . + + (start diagram) + + + + ? + + + + + ? + Entry + + + + + + ? + + + + (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 - , , , or . + + + + +Topic: Summary Structure +_______________________________________________________________________________ + + + Everything is enclosed in a single . All the other summary styles are prefixed with an S. + + holds the actual word "Summary" and and hold the content. exists because different + browsers apply table padding attributes in different ways. exists as a class to separate the main table from any other + tables that may be necessary. Here's a diagram: + + > + > + > + > Title + > + > + > + > + > ... + >
+ > + > + > + + On to the table content. + + > + > + > + > Entry + > + > + > + > + > Description + > + > + > + + 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. 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 , 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 . 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) + + + + + + + + + + + + + + + + + + (repeated as necessary) + + + +
+ "void Function (" + + "unsigned" + + "int" + + "*" + + "a", "b" + + "=" + + "0" + + ")" +
+ + (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) + + + + + + + + + + + + + + (repeated as necessary) + + + +
+ "function Function (" + + "a,", "b:", "c:" + + "int" + + ":=" + + "0" + + ")" +
+ + (end diagram) + + + Note that any section may not exist. For example, there will be no 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. + + > + > Link + > + + 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 and to distinguish between output formats. All + other index styles are prefixed with an I. + + (start diagram) + + <#Index> + + + Page Title + + + + A - B - C ... + + + + + + Heading (A, B, etc.) + + + + + + + ... + +
+ Prefix, if any + + Entry +
+ + + + (end diagram) + + Every index entry, including headings, are rows in a table. The first column of a non-heading are so that + the non-prefix portions align correctly. The other column are , of which there are multiple formats, described below. + + (start diagram) + + + Symbol + , + + Class + + + + Symbol + + + + Class + + ... + + + + Symbol + + + + Class + + + + File + + ... + + ... + + + (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 . + + It's called instead of because class entries are . 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 to appear in the file. + + #IFirstSymbolPrefix - The ID for the first to appear under an . + #ILastSymbolPrefix - The ID for the last to appear under an . + #IOnlySymbolPrefix - The ID if there is only one for an . + + + +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 style, and there are a few additional 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. + + - sections are visible by default. + - sections are *not* visible by default. They must use display: none. + - 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 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 to be the outermost style so its visibility and + position can be manipulated in JavaScript. + + Inside there's a and/or the description text. The description text has no special surrounding tags. + + > + > + > + > Prototype + > + > + > Summary text + > + > + +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 . + + +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 and . + - 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 . Use CSS to position the elements instead. + - <#MainTopic> is applied to instead of . + - IE4, IE5, Opera5, Opera6, Netscape, and Netscape4 browser styles have been removed. , , + and have been added. Gecko has been replaced by , , , and . + KHTML has been replaced by , , , and . + - Removed redundant CParagraph, CCode, and CBulletList classes. Use with p, pre, and ul instead. + - Added and . + - Added <#MSearchPanel>, <#MSearchResultsWindow>, and all related styles. + - Added , , and . + - Removed SEntrySize. Apply the width to and instead. + - , , and were moved from the td and divs into the tr. + - Removed HB style. Now using wbr tag. + + 1.33: + + - Added . + + 1.32: + + - now surround elements that should scroll if they're too wide for the page. + + 1.3: + + - Removed CPrototype. See the replacement and . + - Removed SInGroup, SInClass, and SInSection in favor of more general . + - , , and are now completely determined by configuration files. + - , , and no longer have separate list types. A CFunctionList is now just a CFunction. + - Indexes are now done with tables. + - ISection was removed. + - are only used for the entry cell, not for each entry in an . + - Added , related IDs, and <#IFirstHeading>. + - Merged and 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 and TOPIC_PROPERTY_LIST styles, so they get corresponding , , and + . + + 1.2: + + - Added 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 . + - Renamed HiddenBreak to . + - Added , TOPIC_CONSTANT_LIST, , and TOPIC_TYPE_LIST types, so they get + corresponding , , and . + + 1.0: + + - The tags now appear arround the tags instead of vice versa. + - Added a tag to surround non- elements. + - now appears in tr's instead of td's, where it belonged in the first place. + + 0.95: + + - Added . + - Redid , replacing generic styles like Menu with page type styles like UnframedPage/MenuSection and + FramedMenuPage. + + 0.91: + + - Added and link styles, since 0.91 added URL and e-mail links. + - Added style, which is better than floating on its own. + + 0.9: + + - Added , since 0.9 added indexes. + -- cgit 1.4.1