
    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 "<pre class=CCode></pre>" instead of
"<pre CCode></pre CCode>".  If there's no element in the diagram tag, for example "<CTitle></CTitle>", 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 <FramedMenuPage>,
    <FramedContentPage>, or <FramedIndexPage> depending on what it is.  Non-framed pages have a body style of
    <UnframedPage>.

    On unframed pages, the menu will be contained in a <MenuSection> td and the content or index in <ContentSection> or
    <IndexSection> 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:

    >   <body UnframedPage>
    >   [browser styles]
    >
    >       <table><tr>
    >
    >           <td MenuSection>
    >               Menu
    >           </td MenuSection>
    >
    >           <td ContentSection/IndexSection>
    >               Content or Index
    >           </td ContentSection/IndexSection>
    >
    >       </tr></table>
    >
    >       <Footer>
    >           Footer
    >       </Footer>
    >
    >   [/browser styles]
    >   </body UnframedPage>

    Framed Menu Page:

    >   <body FramedMenuPage>
    >   [browser styles]
    >
    >       Menu
    >
    >       <Footer>
    >           Footer
    >       </Footer>
    >
    >   [/browser styles]
    >   </body FramedMenuPage>

    Framed Content/Index Page:

    >   <body FramedContentPage/FramedIndexPage>
    >   [browser styles]
    >
    >       Content or Index
    >
    >   [/browser styles]
    >   </body FramedContentPage/FramedIndexPage>


List: 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.


List: 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.

    >   <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 4, override it with .IE4 .CTopic.  If a <MTitle>'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.  Yes, 5.0 and 5.5 are grouped together, as are Mac and Windows versions.
        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 <ContentSection> or a <FramedContentPage>.  All other content styles are
    prefixed with a C.

    Each piece of content is a <CTopic> surrounded by 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:
    <CHeading>, <CParagraph>, etc.  Styles like <CParagraph> exist so
    that you only style explicit <NDMarkup> paragraphs, not any p that appears.

    In addition to the top-level <NDMarkup> tags, you also have <CPrototype>, <CTitle>, and <Summaries>.  <Summaries> are
    described in their own section.

    (start diagram)

    <Content>

        <CType (CFunction, CItem, etc.)>
            <CTopic>

                <CTitle>
                    Topic title
                </CTitle>

                <CBody>

                    <ClassHierarchy> (See it's section)

                    <CPrototype>
                        Prototype
                    </CPrototype>

                    <p CParagraph>
                         Paragraph
                    </p CParagraph>

                    <CHeading>
                        Heading
                    </CHeading>

                    <pre CCode>
                    Code
                    </pre CCode>

                    <ul CBulletList>
                        <li>
                        Bullet item
                        </li>
                    </ul CBulletList>

                    <table CDescriptionList>
                        <tr>
                            <td CDLEntry>
                            Entry
                            </td CDLEntry>
                            <td CDLDescription>
                            Description
                            </td CDLDescription>
                        </tr>
                    </table CDescriptionList>

                    <Summary> (See it's section)

               </CBody>

           </CTopic>
        </CType (CFunction, CItem, 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.


List: Content Styles

    CTopic - An individual topic.

    CTitle - The title of a topic.
    CBody - The body of a topic.  May not exist.
    CPrototype - A prototype.
    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 <CClass>
                        and <CFunction>.

    CClass - A class topic.
    CSection - A section topic.
    CFile - A file topic.
    CGroup - A group topic.
    CFunction - A function topic.
    CVariable - A variable topic.
    CProperty - A property topic.
    CConstant - A constant topic.
    CType - A type topic.
    CGeneric - A generic topic.
    CClassList - A class list topic.
    CFileList - A file list topic.
    CFunctionList - A function list topic.
    CVariableList - A variable list topic.
    CPropertyList - A property list topic.
    CConstantList - A constant list topic.
    CTypeList - A type list topic.
    CGenericList - A generic list topic.


Topic: Menu Structure

    Everything is enclosed in a <MenuSection> or a <FramedMenuPage>.  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.  Every other entry in the menu is contained in a
     <MEntry>, inside of which there's the type, such as <MFile> and <MGroup>.  Inside of that is the content.  With <MGroups>,
    there's also a section inside called <MGroupContent> which can contain more entries.  Here's the diagram:

    >   <Menu>
    >
    >       <MTitle>
    >           Menu title
    >
    >           <MSubTitle>
    >               Menu sub title
    >           </MSubTitle>
    >
    >       </MTitle>
    >
    >       <MEntry>
    >           <MFile>
    >               <a href>File</a href>
    >           </MFile>
    >       </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>
    >
    >   </Menu>

    The <MFile> entry that's currently selected will have the <#MSelected> ID, so you can reference it in CSS via .Menu
    .MFile#MSelected.


List: Menu Styles

    MTitle - The title of the menu.
    MSubTitle - The subtitle of the menu.  Will appear within <MTitle>.

    MEntry - The parent container of <MFile> and <MGroup> entries.

    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.

    #MSelected - The ID of the currently selected <MFile>.


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>?

            <type (CHParent, CHCurrent, etc.)>
                <CHEntry>

                    Entry

                </CHEntry>
            </type (CHParent, CHCurrent, etc.)>

        </CHIndent>?

    </ClassHierarchy>

    (end diagram)


List: 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.

    CHIndent - A style used to indent a level.


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.  Rows may have the <SMarked> 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:

    >   <tr SMarked?>
    >       <td SEntrySize?>
    >
    >           <SType (SFunction, SClass, etc.)>
    >               <SEntry>
    >                   <SInClass/Section>? <SInGroup>?
    >
    >                       <a href>Entry</a href>
    >
    >                    </SInGroup>? </SInClass/Section>?
    >               </SEntry>
    >           </SType>
    >
    >       </td SEntrySize?>
    >       <td SDescriptionSize?>
    >
    >           <SType (SFunction, SClass, etc.)>
    >               <SDescription>
    >                   <SInClass/Section>? <SInGroup>?
    >
    >                       Description
    >
    >                   </SInGroup>? </SInClass/Section>?
    >               </SDescription>
    >           </SType>
    >
    >       </td SDescriptionSize?>
    >   </tr SMarked?>

    <SInGroup>, <SInClass>, and <SInSection> exist to allow indenting.  They're there in their current arrangement (all three
    "there"s in one sentence :) 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.


List: 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.
    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.

    SInGroup - Surrounding entries and descriptions that are part of a group.
    SInClass - Surrounding entries and descriptions that are part of a class.
    SInSection - Surrounds entries and descriptions that are part of a section.

    SMain - The main summary.
    SClass - For class summaries.
    SSection - For section summaries.
    SFile - For file summaries.
    SGroup - For group summaries.
    SFunction - For function summaries.
    SVariable - For item summaries.
    SGeneric - For generic summaries.
    SClassList - For class list summaries.
    SFileList - For file list summaries.
    SFunctionList - For function list summaries.
    SVariableList - For variable list summaries.
    SGenericList - For generic list summaries.



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 (LFunction, LClass, etc.)>
    >       Link
    >   </a LType (LFunction, LClass, etc.)>

    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.

List: Link Styles

    LClass - Link to a class.
    LSection - Link to a section.
    LFile - Link to a file.
    LGroup - Link to a group.
    LFunction - Link to a function.
    LVariable - Link to a item.
    LGeneric - Link to a generic.
    LClassList - Link to a class list.
    LFileList - Link to a file list.
    LFunctionList - Link to a function list.
    LVariableList - Link to a variable list.
    LGenericList - Link to a generic list.
    LURL - Link to an external URL.
    LEMail - Link to an e-mail address.



Topic: Index Structure

    Everything is enclosed in a <IndexSection> or an <FramedIndexPage>.  All other index styles are prefixed with an I.

    >   <Index>
    >
    >       <IPageTitle>
    >           Page Title
    >       </IPageTitle>
    >
    >       <INavigationBar>
    >           A - <a href>B</a href> - C ...
    >       </INavigationBar>
    >
    >       <ISection>
    >
    >           <IHeading>
    >               Heading (A, B, etc.)
    >           </IHeading>
    >
    >           <IEntry>
    >               <ISymbol>
    >                   <a href>Symbol</a href>
    >               </ISymbol>,
    >               <IParent>
    >                   Class
    >               </IParent>
    >           </IEntry>
    >
    >           <IEntry>
    >               <ISymbol>
    >                   Symbol
    >               </ISymbol>
    >               <ISubIndex>
    >                   <IEntry>
    >                       <IParent>
    >                           <a href>Class</a href>
    >                       </IParent>
    >                   </IEntry>
    >                   ...
    >               </ISubIndex>
    >           </IEntry>
    >
    >           <IEntry>
    >               <ISymbol>
    >                   Symbol
    >               </ISymbol>
    >               <ISubIndex>
    >                   <IEntry>
    >                       <IParent>
    >                           Class
    >                       </IParent>
    >                       <ISubIndex>
    >                           <IEntry>
    >                               <IFile>
    >                                   <a href>File</a href>
    >                               </IFile>
    >                           </IEntry>
    >                           ...
    >                       </ISubIndex>
    >                   </IEntry>
    >                   ...
    >               </ISubIndex>
    >           </IEntry>
    >
    >       </ISection>
    >
    >   </Index>

    Every index entry is an <IEntry> followed by a type.  If there's only one class and definition file for a symbol, it gets the link.
    However, if there's more of either, they get broken out into <ISubIndex> entries.  A <IParent> subindex can be broken out
    yet again into an <IFile> subindex.

    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.

List: Index Styles

    Index - Surrounds the entire index.

    IPageTitle - The page title.
    INavigationBar - The navigation bar.

    ISection - A section of entries.
    IHeading - A heading for a section of entries.

    IEntry - An entry in the index.
    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 - Surrounds all <IEntry>'s in a sub-index.


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>

List: 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>.


List: 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.


Topic: Revisions

    How the page structure has changed throughout the various releases.

    1.21:

        - Added <CProperty> and <CPropertyList> styles.

    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 types <CConstant>, <CConstantList>, <CType>, <CTypeList>.

    1.0:

        - The type 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.
