Mark Lentczner <[email protected]> writes:
> Snap team -
>
> I'm working on converting the HTML backend for Haddock from a nested
> pile of tables to XHTML/semantic mark-up. I've been working with the
> Haddock maintainer, and slowing pushing small changes into the
> development branch. I'm at a point now where I think it is close to
> release.
>
> I'd love to get your input on particular mark-up I've chosen for
> various Haddock constructs. I've uploaded to my web site the
> documentation for Snap (core, server and Heist) generated with the new
> XHTML backend for Haddock:
>
> http://www.ozonehouse.com/mark/snap-xhtml/heist/
> http://www.ozonehouse.com/mark/snap-xhtml/snap-core/
> http://www.ozonehouse.com/mark/snap-xhtml/snap-server/
>
> The goal of the CSS file was to maintain the look as closely as
> possible(*), so no need to focus on that. What I'm after is, if you
> look at the page in some XHTML inspector, is the markup what you'd
> like to see. I basically made it up as I went along, though I tend to
> try to use as few classes as possible (put 'em on divs and let
> selectors work...). If there is anything you'd like to see different:
> class tag, different choice of tags, extra div wrappers, I'm very open
> to making changes before we go out with it.
>
> Also, focus on the main module pages - the index and associated pages
> haven't been fully XHTML'ized yet and we plan to leave those for round
> two...
>
> Looking forward to finding out what you think.
Hi Mark,
Finally took some time to look at this -- a couple of comments:
* looks like your markup still has <table>s in it -- at least on the
front page -- I would try to get rid of those if possible. Also I
would get rid of the javascript hide/collapse stuff for now (it's
clunky), and rebuild it later with something nice like jquery.
* decls are in <div>s with appropriate classes, +1 for this! A huge
improvement by itself. That said, you've got some "decldocs" which
only have headings in them -- ideally decldocs which only contain
headings should probably have their own class. One should be able to
do something like
$(".decldoc").(...)
and be able to process JUST the toplevel declarations.
* Synopsis and description should also have their own toplevel <div>s.
* Rather than <p class="decl">..</p> <p>...docs...</p> within the
decldoc blocks, why not replace the whole thing with a <dl>? It's
what it's for. I.e.:
<dl class="declarations">
<dt><span class="keyword">data</span>
<a name="t:Snap"></a><a name="t:Snap"></a><b>Snap</b> a </dt>
<dd><code><a href="Snap-Types.html#t%3ASnap">Snap</a></code> is
the...</dd>
...
</dl>
Other than this feedback, this is a HUUUGE improvement over what it was
generating before and I'm really looking forward to the final result.
G
--
Gregory Collins <[email protected]>
_______________________________________________
Snap mailing list
[email protected]
http://mailman-mail5.webfaction.com/listinfo/snap
