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.