Natural Docs

Version 1.0

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.

Summary

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.
Page Structure	The body tag is used to distinguish between the types of pages.
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.
Content Structure	All the content of a given file is either contained in a ContentSection or a FramedContentPage.
Content Styles
Menu Structure	Everything is enclosed in a MenuSection or a FramedMenuPage.
Menu Styles
Summary Structure	Everything is enclosed in a single Summary.
Summary Styles
Link Structure	All links to symbols have a type style prefixed with L.
Link Styles
Index Structure	Everything is enclosed in a IndexSection or an FramedIndexPage.
Index Styles
Revisions	How the page structure has changed throughout the various releases.

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>

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.

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.

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.

<Content>

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

            <CTitle>
                Topic title
            </CTitle>

            <CBody>

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

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.

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.
CMain	The main topic.
CClass	A class topic.
CSection	A section topic.
CFile	A file topic.
CGroup	A group topic.
CFunction	A function topic.
CVariable	A variable 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.
CGenericList	A generic list 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.

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 MGroups content.
MText	A plain text entry.
MLink	An external link entry.
#MSelected	The ID of the currently selected MFile.

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. Cells may have the SMarked class, 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.

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.

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.

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.

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.

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.

Revisions

How the page structure has changed throughout the various releases.

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.