Xhtml / New Look to do list...

[Thomas Schilling]

On 24 July 2010 18:36, Mark Lentczner <markl at glyphic.com> wrote:
> Here's my to do list for finishing the Xhtml / New Look project:
> Graphic Issues to Design/Decide
> • Slide out Synopsis - refine or remove

It's currently very hard to discover.  One possibility would be to
have vertical text on it (that reads "synopsis", obviously).  For the
mini_* pages I deliberately left out type signatures and added
headings to make things more readable, maybe you could try the same
for the synopsis.

If we can't find something that works well, though, we should just
drop it.  I don't think it's that important.

> • Side margins on pre block - probably reduce to zero

Yes, the current 2em is too much.  I'd personally be happy with 1em
(both sides), but no margins would be fine, too.  The Python docs also
use no margins.

> • Amount of white space between sections - probably reduce to the
> neighborhood of 2~3em

Yes, see for example: http://imgur.com/kSstt

I'd personally prefer 2em over 3em.  We could add a light line above
top-level documentation headings, not sure.

> • Which sub-sections should be tables, which should  be def-lists, which
> block layout (like top-level decls):
>
> arguments - tables, seems right
> constructors - tables ? but unsure
> fields - def-lists, seems right
> instances - tables ? probably right
> methods - block layout, seems right
> associated types - block, seems right

Regarding def-lists, they currently don't work well when documentation
is missing, e.g.:
http://www.ozonehouse.com/mark/snap-xhtml/snap-server/Snap-Http-Server-Config.html#t:Config

>
> Layout Issues
> • When the window is narrow, the buttons and "info block" overlap into the
> package and module titles
> • Collapsable target (currently only for instances) should include the whole
> "Instances" caption, not just the little image
> • Collapsable images should come from .css, not hard coded in xhtml and
> javascript
> Code Issues
> • Test all the functionality of the --theme argument
> • Test that the new anchors work in Opera and IE (clicking on a reference to
> a symbol should scroll to the def)
> • The Doc constructors DocAName & DocModule don't seem to be generated
> anywhere in the code base (only save/restored from .haddock files). Are they
> deprecated? I ask because I had to clean up some markupAName & markupModule
> functions, which I think I did right, but without use, was unable to verify.
> Release Notes
> • Write some
> • Find a recipe for people to use to easily rebuild all their Haddock doc on
> their local installs.
>
> I've got plenty of things to clean up / fix / explore for some future
> version, but I think this is all that is outstanding before we can ship it.
> - Mark

On a different note, do you know how hard it would be to have a
link/button that toggles between a framed and unframed version?  The
main problem with frames is that they make it hard to bookmark.  The
python docs have this hovering paragraph symbol that one can click to
create a permalink.  It would be nice to have something like that.
They also highlight the currently linked element, e.g.:
http://docs.python.org/library/constants.html#quit

/ Thomas