Title: CSS Guide _______________________________________________________________________________ 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. The diagrams are designed for clarity. In the actual HTML, you'd obviously see "

" instead of "

". If there's no element in the diagram tag, for example "", that means you shouldn't rely on what HTML element it is. Just refer to them as .Style in your CSS file instead of Element.Style. Topic: Page Structure The body tag is used to distinguish between the types of pages. For framed pages, its style will be , , or depending on what it is. Non-framed pages have a body style of . On unframed pages, the menu will be contained in a td and the content or index in or tds. Tables are used instead of CSS positioning for better compatibility with older browsers and because they have the ability to stretch when its content is too wide and collapse when the browser window is too small. Unframed Page: > > [browser styles] > > > > > > > >

> Menu >

> Content or Index >

> > > > [/browser styles] > Framed Menu Page: > > [browser styles] > > Menu > > > > [/browser styles] > Framed Content/Index Page: > > [browser styles] > > Content or Index > > [/browser styles] > Styles: Page Styles UnframedPage - An unframed page. Will be applied to a body tag. FramedMenuPage - A framed menu page. Will be applied to a body tag. FramedContentPage - A framed content page. Will be applied to a body tag. FramedIndexPage - A framed index page. Will be applied to a body tag. MenuSection - The menu section in a non-framed page. Will be applied to a td tag. ContentSection - The content section in a non-framed page. Will be applied to a td tag. IndexSection - The index section in a non-framed page. Will be applied to a td tag. Footer - The page footer. Will be in a framed menu page or on its own in a non-framed page. 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. Immediately after the body tag, the browser type and version styles will be applied. 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 4, override it with .IE4 .CTopic. If a 's style gives you a problem in Opera 5 but only in frames, override it with .FramedMenuPage .Opera5 .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, Konquerer, and Safari, are taken care of. IE - Internet Explorer Gecko - The Gecko rendering engine, which includes Mozilla, Netscape 6+, etc. Opera - Opera KHTML - The KHTML rendering engine, which includes Konqueror and Safari. Netscape - The pre-Gecko Netscape rendering engine, which is 4.x and earlier. Browser Versions: If the browser is not one of the versions below, this style will not be present. The browser type still may be. Gecko and KHTML-based browsers are not broken out into sub-versions. IE4 - Internet Explorer 4.x. IE5 - Internet Explorer 5.x. IE6 - Internet Explorer 6.x. Opera5 - Opera 5.x. Opera6 - Opera 6.x. Opera7 - Opera 7.x. Netscape4 - Netscape 4.x. Topic: Content Structure All the content of a given file is either contained in a or a . All other content styles are prefixed with a C. Each piece of content is a surrounded by its type; for example, for a function. Inside that are the and if necessary, . Inside are analogues to all the top-level tags: , , etc. Styles like exist so that you only style explicit paragraphs, not any p that appears. In addition to the top-level tags, you also have , , and . are described in their own section. (start diagram) Topic title (See it's section) (See it's section)

Paragraph

Heading

                    Code

Bullet item

Entry

Description

(See it's section) (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 CTopic - An individual topic. CTitle - The title of a topic. CBody - The body of a topic. May not exist. CParagraph - A paragraph. Is implemented with a p. CHeading - A heading. CBulletList - A bullet list. Is implemented with a ul. CCode - A section of code. Is implemented with a pre. 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 topic type tag, such as and . 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 or a . 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. Every other entry in the menu is contained in a , inside of which there's the type, such as and . Inside of that is the content. With , there's also a section inside called which can contain more entries. Here's the diagram: > > > > Menu title > > > Menu sub title > > > > > > > File > > > > > > Text > > > > > > Link > > > > > > Group > > > (MEntries) > > > > > > The entry that's currently selected will have the <#MSelected> ID, so you can reference it in CSS via .Menu .MFile#MSelected. Styles: Menu Styles MTitle - The title of the menu. MSubTitle - The subtitle of the menu. Will appear within . MEntry - The parent container of and entries. MFile - A file entry. MGroup - A group entry. MGroupContent - A container for a content. MText - A plain text entry. MLink - An external link entry. #MSelected - The ID of the currently selected . 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. 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. Rows may have the style, which means they should be tinted for easier readablity. Since we many attributes left to apply, they're done with a kludgy mess of styles within each cell. It's hacky and verbose, but it works and is compatible everywhere. We apply the type, whether it's an entry or a description, and if it's in a group or class as shown below: > > > > > > ? > > 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. 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. 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. SEntrySize - A class applied to one entry cell to specify the column width. SDescriptionSize - A class applied to one description cell to specify the column width. 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 a or an . All other index styles are prefixed with an I. (start diagram) 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 - Surrounds 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: 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 HB - Hidden Break. Will surround a single space to try to break a word transparently. Should be set to as small as possible. 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.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>. 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 / and . 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.