From 9ba8e6cf38da5196ed7bc878fe452952f3e10638 Mon Sep 17 00:00:00 2001 From: Magnus Auvinen Date: Tue, 22 May 2007 15:06:55 +0000 Subject: moved docs --- docs/doctool/Info/CSSGuide.txt | 782 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 782 insertions(+) create mode 100644 docs/doctool/Info/CSSGuide.txt (limited to 'docs/doctool/Info/CSSGuide.txt') diff --git a/docs/doctool/Info/CSSGuide.txt b/docs/doctool/Info/CSSGuide.txt new file mode 100644 index 00000000..bf4e1377 --- /dev/null +++ b/docs/doctool/Info/CSSGuide.txt @@ -0,0 +1,782 @@ + + 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. + -- cgit 1.4.1