headings and paragraphs

[Mark Lentczner]

> ... it's somewhat hard to style the function signatures as they are <p> tags. I typically want to format then differently from normal <p> tags. Perhaps changing all <p class="src"> to <div class="src">. I think a block element makes more sense here. What was the reason what's now called <div class="top"> couldn't be a definition list? Did it have something to do with the headlines that separate different sections? Since <dd> and <dt> are block elements they can have any content.
Defintion lists have three problems:
1) You can't have arbitrary block content in the <dl> element. Hence, because of section headings, each section would have to be it's own <dl> list. This isn't a serious problem, just lessens the joy in having a defintion list of me.
2) <dt> can only have inline content. Again, not a huge problem, but makes things like arguments with doc have to go in the <dd> section, which in turn means that we still need <div> around the actual documentation part within the <dd>. 
3) There is no way to group the <dt> and the <dd>. That is, you can't surround them with <div class="top"> or some such. This strikes me as the real deal breaker, as CSS would have no way to style the whole definition unit.

A late addition to the markup, at Thomas' request, is that all documentation sections are in some block element (usualy a <div>) with class doc. So now CSS can take two approaches: 1) style p as per documentation, and style p.src as per declarations. (This was my original intent), 2) style p as per declarations and .doc p as per documentation. I only feel a little queasy about being ambivalent this way!

> Could we have all these <p class="caption"> converted to real headings? They also make it somewhat tricky to style the <p> element.
My thought was that "captions" were bits of text naming structural sections, whereas the "table of contents", which would derive from the h1 through h6 elements, comes from the structure the module author wanted to use to represent their interface. Essentially we have two hierarchies here: The section tree from the module, and the "fixed" structure tree from Haddock's layout. Since the former is always embedded in the later, one could smoosh them all together: But then we end up with this (say)
	h1 - module name
		h2 -  contents
		h2 - description
		h2 - interface (though perhaps this h2 isn't shown?)
			h3 - module's first major heading
				h4 - module's first minor heading...
I didn't like relegating the module's sections to such smaller headings, since, after all, they are actually primary. And things like the "Description" text seems optional and only there as a signpost. Hence I'd like to stick with the current scheme.

> It would probably makes sense to only have one <h1> in the document (the module name) and the rest of the headings be h2-h6.
My reading of the spec implies that one uses multiple h1 elements for all the top level sections. Admittedly, the spec is loose on this point, and common usage varies all over the map! HTML 4.01 spec actually suggests placing a div around a heading and all it refers to (since the headings aren't themselves nested). Does anyone want me to add that? It doesn't seem, judging from the current layouts, all that useful.

I'm wondering why styling the p element is tricky: A bare p is only used for documentation, a p.src is for declaration source code, and a p.caption is only use for these ancillary headers. I'd like to understand more about where this makes the CSS tricky.

	- Mark


Mark Lentczner
http://www.ozonehouse.com/mark/
IRC: mtnviewmark