= Interface Page Structure =

Structure of XHTML for main (interface) pages:

{{{
body
    div#package-header
    div#module-header
        p.caption
    div#table-of-contents
        p.caption
        ul(li(a(text))|ul(...))      
    div#description
        p.caption
        <doc>
    div#synopsis
        p.caption
        ul
            li.src.short
                text                -- currently still wrapped in a p
                ul.subs(li(..))     -- missing the .subs
                text (closing '}')
    div#interface
        h1(h2(...))
        div.top
            p.src
            div.arguments.subs
                p.caption
                <subs>
            <doc>
            div.constructors.subs,
            div.instances.subs,
            div.arguments.subs
            div.fields.subs
                p.caption
                <subs>
            div.associated-types.subs
            div.methods.subs,
                p.src
                <doc>
                div.subs...
    div#footer
        p
}}}

Expected general formatting:

 * constructors - shown side-by-side w/doc
   * fields   - shown side-by-side w/doc
   * GADT args- shown side-by-side w/doc (does this exist?)
 * methods      - shown stacked w/doc
   * args     - shown side-by-side w/doc (?)
 * associated types - shown stacked w/doc
   * args     - shown side-by-side w/doc (?)
 * args         - shown side-by-side w/doc
 * instances    - shown side-by-side w/doc (in classes)
 * instances    - just a list (no doc for types)
                
{{{        
<doc> ::= p | ul | ol | pre
<subs> ::=
    table
        tr
            td.src
            td(<doc>)
        tr
            td colspan=2
                div.subs... -- for documented arguments
}}}

= General Entity, Class and ID usage =

== basic structure ==

 * `div#xxx`     -- major page divs only
 * `p.caption`   -- fixed header for some page sections & the name of the module (in .module-header)
 * `h1`, `h2`...   -- interface's organization only

== formatting ==

 * `.src`        -- declaration source - for source code styling applied to `li`, `p`, and `dt`, such source is *not* part of documentation

== documentation ==

 * `p`
 * `ul`
 * `ol`
 * `pre`         -- for blocks of preformatted code
 * `code`        -- for inline source code
 * `a`           -- both in-line and external links

these are all "unadorned" by classes, or wrappers
the default styling of the page should be for these
blocks of documentation elements

== declaration structures ==

 * `.short`- an element containing a single, "short" declaration, used in `#synopsis` and in mini-pages
 * `.top` - an element containing a single, top level declaration & its doc, used in `#interface`
 * `.subs` - an element containing multiple, sub-declaration parts of a decl
 * `.arguments`, `.constructors`, `.methods`, `.instances`, `.associated-types`    -- various kinds of `.subs`


= Ancillary Page Structures =

== doc-index.html & doc-index-X.html ==

These are the alphabetic index pages

{{{
body
    div#package-header
    div#index
        p.caption
        ul
            li(a)
        table
            tr
                td.src, td.module
                td.alt, td.module
    div#footer
}}}

== index-frames.html ==

This is the flat list of modules shown in the upper left pane of the frames.html view

{{{
body#mini
    div#module-list
        p.caption
        ul
            li(span.module(a) <doc> span.package() ul(...))
}}}

== index.html ==

This is the "master" page for a package, or a whole set of packages. It includes a hierarchal list of modules, with optional short comments and package names.

{{{
body
    div#package-header
    div#description
        h1
        <doc>
    div#module-list
        p.caption
        ul
            li.module(a) -- never nested
    div#footer
}}}

== mini_Foo.html ==

This is the flat list of definitions in a module, shown in the lower right pane of the frames.html view. It differs from the synopsis in that the declarations have less information (no constructors or methods, for example), and the hierarchal headings from the contents are interspersed.

{{{
body#mini
    div#module-header
        p.caption
    div#interface
        h1, h2...
        div.top
            p.src
}}}

----

= Outstanding Questions =

We could show sub declarations as ad `dl` list, structured as so, but it is impossible to style this side by side with the right column being all the same sized AND allowed to size automatically to the (max-width) content:

{{{
    dl
        dt.src
        dd(<doc>, div.subs...)
}}}

Should we add the class `doc` to all constructs used for documentation? Or perhaps wrap documentation blocks in `div.doc`? Right now they are "unadorned" as they are the standard, "readable text" on the page.