Ticket #108 (closed defect: fixed)

Opened 6 years ago

Last modified 2 years ago

Output semantically correct HTML

Reported by: tibbe Owned by: MtnViewMark
Priority: major Milestone:
Version: 2.4.2 Keywords:
Cc: leather@…

Description

Haddock's HTML output relies on tables for layout and formatting. This has two drawbacks:

1. The generated HTML is much larger than needed as more tags are needed.

2. It's hard to write alternative stylesheets.

I've been experimenting with a new stylesheet and I believe we can get away with using less markup than we currently do. The only place where I see a possible need to use tables in the markup is in the function parameter listings and even there a definition list would probably be more appropriate.

I've attached an example HTML file that demonstrates what the markup could look like. It comes with a stylesheet that mimics the style used at Google Code. This stylesheet is for demonstration purposes only.

The first two tasks would be to change the HTML backend to output semantically correct HTML and to create a stylesheet that replicates the current Haddock style using this HTML.

Attachments

test.html (6.1 kB) - added by tibbe 6 years ago.
test.css (1.6 kB) - added by tibbe 6 years ago.

Change History

Changed 6 years ago by tibbe

Changed 6 years ago by tibbe

  Changed 6 years ago by simonmar

tibbe - I've been waiting for someone to overhaul Haddock's layout for a long time, you have my full endorsement.

Some specific comments:

  • I like to see code in a monospaced font
  • I think the layout is a little less compact than the current layout. Can't we put argument types and descriptions on the same line, as in the current layout?
  • I'd like the synopsis to be hide-able with a +/- button. Sometimes it is huge and just gets in the way.
  • don't forget the header stuff (package name, link to contents and source code etc.)
  • it's probably a good idea to do an example with all the various kinds of Haskell declaration and markup, so we can see how they all look.

Tables aren't that bad, given that there isn't a good equivalent in CSS. However, the horrible fixed-size cell stuff in the current Haddock layout is very ugly, I grant you.

BTW, isn't there a copyright on that particular style? :)

  Changed 5 years ago by waern

  • milestone changed from _|_ to 2.9

  Changed 5 years ago by waern

Mark Lentczner has started working on this.

  Changed 5 years ago by waern

  • milestone 2.9 deleted

Milestone 2.9 deleted

  Changed 5 years ago by waern

  • milestone set to 2.9.0

  Changed 5 years ago by spl

  • cc leather@… added

The markup looks pretty nice. How would classes and instances looks?

The style is (of course) too Googly, but I gather from your statement about "demonstration purposes" that this is not permanent.

Here's one thing that's always bothered me and made it confusing for me to find what I was looking for. The Synopsis is simply a list of functions, classes, datatypes, etc. It is ordered by the export list, but it doesn't have the section headers. In many cases, it becomes a really long list with few breaks, and it's difficult to search by eye. I would like to see an improvement, though I don't yet know what the best one is. Perhaps adding section headers to the list would be enough. Perhaps alphabetizing it. Perhaps breaking it into sections for datatypes, classes, values. Thoughts on this?

  Changed 4 years ago by MtnViewMark

  • owner changed from tibbe to MtnViewMark

follow-up: ↓ 9   Changed 4 years ago by MtnViewMark

Take a gander at: Snap-Types.html on my server

Notice the style switcher menu on the top right... :-)

The interface pages have significant semantic markup, and all styling changes are done through pure CSS. I think, for the main interface pages, this is pretty much there. There are still tables, and I could replace them with dl lists, but then there is no way to get the kind of styling you see for constructors and arguments where the doc is all lined up nicely.

I have to next do index.html, index-frames.html, doc-index*.html, frames.html, and mini_*.html. Those should be quite a bit easier.

in reply to: ↑ 8 ; follow-up: ↓ 10   Changed 4 years ago by simonmar

Replying to MtnViewMark:

Take a gander at: Snap-Types.html on my server Notice the style switcher menu on the top right... :-)

Very cool! There are some things I would change about the new styles, but I presume you're mainly focussing on separating the style from the content for now, and improving the new styles is for later?

in reply to: ↑ 9   Changed 4 years ago by MtnViewMark

Replying to simonmar:

That is correct, the primary aim right now is to separate out the styling from the markup, and to make the markup "semantic". The first style is attempting to reproduce the current look for both continuity and so this change be released without blocking on the longer styling process.

The style "tibbe" is based on Johan Tibbe?'s mock-up attached to this ticket. The style "snappy" is based on the styling the Snap Framework team did for their documentation. I'm hoping they will refine my port of their styles. I'm going to do a style based on jQuery.

The other reason for doing these early alternative styles is to be sure that the choice of markup (especially placement of divs and classes) is right.

  Changed 4 years ago by MtnViewMark

  • status changed from new to closed
  • resolution set to fixed
  • milestone changed from 2.9.0 to 2.8.0

  Changed 2 years ago by anonymous

  • milestone 2.8.0 deleted

Milestone 2.8.0 deleted

Note: See TracTickets for help on using tickets.